DEV Community: Hagicode

How We Use impeccable to Optimize Frontend Interface Design and Implementation Stability

Hagicode — Sat, 04 Jul 2026 13:29:21 +0000

How We Use impeccable to Optimize Frontend Interface Design and Implementation Stability

Introduction

Many teams face the same pain point when building UI: design language depends on experience, interaction details depend on memory, and the final result is often “usable but unstable.”

In the HagiCode monorepo, impeccable is not used as an “inspiration tool,” but embedded into an executable, verifiable, and regression-friendly engineering workflow:

Structured constraints at task entry (commands, scenarios, repository scope)
Automatic alignment between site content and upstream command definitions
Fixed local development ports, runtime parameters, and validation process

Based on the current implementation in the repository, this article breaks things into four parts: Background, Analysis, Solution, and Practice.

Background

In the current repository snapshot, the main lines directly related to impeccable are concentrated in three places:

Static site runtime orchestration: scripts/static-sites-dev.mjs
impeccable documentation site: repos/impeccable-site
UI task preset contract example: designs/task-preset-plugin-examples/ui-master

The third item is a design example, not the production backend runtime code itself. This distinction should be clarified first to avoid mistaking a “design contract” for “published behavior.”

Analysis

1) Structure design intent first to reduce “freestyle” variance

In the backend contract example of ui-master, dependencies and inputs are locked first before execution begins.

designs/task-preset-plugin-examples/ui-master/backend/task-preset.json:

{
  "taskKey": "uiMaster",
  "scriptKey": "autotask.ui-master",
  "requirements": [
    {
      "type": "skills",
      "name": "impeccable"
    },
    {
      "type": "cli",
      "name": "impeccable",
      "command": "npm",
      "args": ["exec", "--offline", "--", "impeccable", "--help"]
    }
  ],
  "inputBindings": [
    {
      "input": "uiMasterDescription",
      "promptParameter": "uiMasterDescription",
      "required": true
    },
    {
      "input": "uiMasterCommandIds",
      "promptParameter": "uiMasterCommandIds",
      "required": true
    },
    {
      "input": "sceneKey",
      "promptParameter": "sceneKey"
    }
  ]
}

Key points:

Validate skills:impeccable and cli:impeccable first to avoid discovering broken links during execution.
uiMasterCommandIds enforces command-based input, preventing “long descriptions but unclear direction.”
sceneKey standardizes scenario keys, avoiding each preset inventing its own input name.

The stability value of this structure is direct: failures happen earlier, are explainable, and inputs are replayable.

2) Unify command catalog and documentation routes to reduce semantic drift

designs/task-preset-plugin-examples/ui-master/frontend/commands.json defines command grouping, documentation route templates, and command prelude:

{
  "docs": {
    "baseUrl": "https://impeccable.hagicode.com",
    "routeTemplate": "/{lang}/docs/{commandId}",
    "languageResolver": "supported-language"
  },
  "commands": [
    {
      "id": "craft",
      "groupId": "build",
      "skill": "impeccable",
      "docsSlug": "craft",
      "preludeTemplate": "/impeccable {commandId} {uiMasterDescription}"
    }
  ]
}

This allows “execution commands, documentation descriptions, and language routing” to share the same set of IDs, reducing common mismatches:

Called A in docs, called B in the panel
Chinese page links to the wrong command in English
Prompt prelude and docs slug are inconsistent

3) Site implementation turns “content correctness” into a verifiable asset

In repos/impeccable-site/package.json, validate chains together the full quality gate:

{
  "scripts": {
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

And the script behind catalog:check (scripts/build-command-catalog.mjs) performs hard validation on frontmatter structure:

function parseFrontmatter(sourceText, sourcePath) {
  const match = sourceText.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/u);
  assert(match, `${sourcePath} must include YAML frontmatter`);
  const frontmatter = load(match[1]);
  assert(isPlainObject(frontmatter), `${sourcePath} frontmatter must be a mapping`);
  return {
    frontmatter,
    body: match[2].trim(),
  };
}

This kind of assert is simple, but crucial for stability: it is far better to fail locally and in CI than to discover missing document fields after deployment.

4) Fix development ports and env to avoid “works on my machine”

In the monorepo root script scripts/static-sites-dev.mjs, impeccable is explicitly orchestrated:

{
  id: 'impeccable',
  name: 'Impeccable',
  repoPath: 'repos/impeccable-site',
  productionUrl: 'https://impeccable.hagicode.com/',
  command: 'npm',
  args: ['run', 'dev'],
  env: {
    PORT_IMPECCABLE_SITE: '36296'
  },
  portHint: 36296,
  order: 56
}

The test scripts/static-sites-dev.test.mjs also asserts these values (port, args, env, productionUrl).

This “hardcoded + tested” approach is not flashy, but stable:

Unified local entry point
Fixed troubleshooting path
No drifting documentation site links

Solution

If you want to use impeccable to optimize both interface quality and implementation stability, the existing repository practices can be implemented as four layers.

Layer 1: Contractualize task entry

Approach: reuse preset structures like ui-master.

Goals:

Restrict allowed repository scope (targetRepositories)
Restrict command source (uiMasterCommandIds)
Restrict context entry (uiMasterDescription)

Benefit: every task assignment can be reviewed in terms of “what was the input, and why was it changed this way.”

Layer 2: Standardize command semantics

Approach: bind the three-piece set of command ID, docs slug, and prelude template.

Goals:

Commands selected in the panel can jump to docs with the same ID
/impeccable <command> in prompts matches documentation semantics

Benefit: reduces hidden risk where “terminology is consistent but behavior is not.”

Layer 3: Validate content assets

Approach: keep npm run validate as a pre-commit gate.

Goals:

No missing i18n keys
No drift between command catalog and upstream structure
Type checks, tests, and build pass in one go

Benefit: moves “occasional content issues” forward to local development.

Layer 4: Standardize development runtime environment

Approach: use static-sites-dev for unified startup and fix PORT_IMPECCABLE_SITE.

Goals:

Minimize port conflicts in team collaboration
Fix multi-site joint debugging paths

Benefit: less time spent on environment setup, faster issue localization to code itself.

Practice

Step 1: Initialize impeccable-site

cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --init --recursive
env -u NPM_CONFIG_PREFIX npm install

Step 2: Local development and full validation

env -u NPM_CONFIG_PREFIX npm run dev
env -u NPM_CONFIG_PREFIX npm run validate

validate covers i18n, catalog, typecheck, test, and build in one run.

Step 3: Run within unified monorepo orchestration

From the monorepo root, run via the scripts/static-sites-dev.mjs workflow and reuse the predefined PORT_IMPECCABLE_SITE=36296.

The key point here is not just “it runs,” but “everyone runs it the same way.”

Step 4: Convert UI requests into command-based input

In the task preset flow, prioritize landing requirements as:

uiMasterDescription: business objective
uiMasterCommandIds: commands for this run (e.g., craft, audit, polish)
sceneKey: scenario context

Then proceed to implementation changes to reduce direction drift caused by directly editing UI.

Step 5: Clarify current evidence gaps

Based on the current repository snapshot, what can be confirmed is:

The site and validation workflow of impeccable-site are implemented code.
The deep integration contract between ui-master and impeccable is mainly presented in designs/task-preset-plugin-examples and design documents.

If you plan to conclude that this is “fully enabled in production backend,” current evidence is insufficient, so that claim should not be made yet.

HagiCode Information Overview

HagiCode is a platform project that integrates multi-repository engineering, AI task execution, documentation sites, and toolchains. Its core capability is not a single-point “can generate code,” but chaining task input constraints, execution context, validation gates, and cross-repository collaboration into a stable delivery pipeline. Typical use cases include structured UI iteration, cross-repository feature integration testing, standards-driven technical content production, and automated delivery with quality gates.

Summary

The real value of impeccable is not “helping you think of a prettier button,” but “turning interface optimization into an engineering discipline.” In HagiCode’s current practice, this is achieved through four actions: task contractualization, unified command semantics, upfront content validation, and standardized runtime environment. Build these foundations first, then pursue more advanced design enhancements—the payoff is greater and more sustainable.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-07-04-goal-preset-agent-compatible-prompt-variants%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Teaching Every Agent to Speak `/goal`: A Compatible Extension Design for HagiCode's Continuous-Work Preset

Hagicode — Fri, 03 Jul 2026 15:12:26 +0000

Teaching Every Agent to Speak `/goal`: A Compatible Extension Design for HagiCode's Continuous-Work Preset

Introduction

When you hand an AI Agent a "continuous work" task, the ideal experience looks like this: you write down a goal, pick the repositories it's allowed to touch, click submit, and the Agent drives straight toward that goal—no mid-course questions, no going off-topic, no reaching outside the allowed repositories.

In HagiCode, this capability has a dedicated entry point—the goal preset task, whose command surface is /goal. The catch: not every Agent understands /goal. Claude and Codex have native continuous-work command semantics, so handing them /goal just works; but other CLIs (Gemini, Copilot, iFlow, OpenCode, etc.) have no such slash command at all. Stuffing /goal ... into them verbatim, at best, gets treated as an invalid command, and at worst gets executed literally and blows up.

The laziest option at first was: just let goal run on Claude / Codex only and reject every other Agent outright. But that shuts most of the Agent matrix out the door. This article is about how we made this actually work—using "Agent-aware" prompt variants, so natively supported Agents take the native command while unsupported Agents take a fallback prompt, keeping behavior aligned and the experience consistent.

The content is based on the goal preset package under repos/hagitask and the backend parsing implementation in repos/hagicode-core.

Background

What `goal` is

goal is a built-in task preset plugin package located at repos/hagitask/presets/goal/. Its manifest.json declares the plugin identity, icon, localization bundle, and frontend/backend assets:

{
  "taskPresetId": "goal",
  "version": "1.0.0",
  "icon": "flag",
  "kind": "custom-executor",
  "status": "experimental",
  "entrypoints": { "menuSurface": "session-create", "drawerId": "goal" },
  "ui": { "panel": "./frontend/panel.json", "commands": "./frontend/commands.json" },
  "backend": {
    "taskPreset": "./backend/task-preset.json",
    "prompts": "./backend/prompts.json"
  }
}

Its purpose is "continuous work mode": the user fills in a goal description (goalDescription), optionally scopes the writable / read-only repositories, and then the backend assembles it into a single non-interactive auto-task run. The key fields in the frontend panel panel.json are:

goalCommandIds: the command selector, which by default contains only a single /goal;
goalDescription: the required goal description;
targetRepositories: the repository access selector, distinguishing read / write.

Where `/goal` comes from

The command surface is defined in frontend/commands.json, and the core is a single line of preludeTemplate:

{
  "commands": [
    {
      "id": "goal",
      "label": "goal",
      "preludeTemplate": "/goal {goalDescription}"
    }
  ]
}

In other words, the final prompt sent to the Agent will have a /goal <goal description> line prepended before the body. For Claude / Codex, this line is a command they recognize; for other Agents, this line is something that needs to be "translated." The adaptation challenge of this entire article is exactly this: how the meaning of that single /goal ... line diverges across different Agents.

Analysis

A single-locale template no longer holds up

HagiTask's early prompt packages were split by language only: in prompts.json, each locale declares one set of systemTemplate + userTemplate, and the backend PresetTaskCatalogProvider reads them into PromptPackage.Locales, then picks and renders one set at runtime based on the request language.

This model is enough for presets whose "execution instructions are Agent-agnostic." But goal isn't like that:

Claude / Codex: can rely directly on the native /goal command surface;
Other Agents: need a more verbose prompt that explicitly teaches them "how to enter continuous work mode," and must also tell them not to execute /goal ... as a command.

When two starkly different sets of instructions have to appear under the same locale, splitting by language alone is no longer enough. We needed to introduce another dimension beyond language: the Agent family.

Refusing to run isn't a good option

Initially, goal's requirements locked Agents down to ["claude", "codex"], and any other Agent was immediately judged incompatible. This has two product downsides:

In the hero selection panel, the compatible heroes get filtered down to very few, easily leaving "no hero to pick";
Plenty of Agents are perfectly capable of doing continuous work—they just don't have a native /goal—and a blanket rejection wastes their capability.

So the real problem to solve isn't "who can run," but "for the same goal, how do we give different but equivalent execution instructions based on Agent capability." The answer: push the Agent-aware differences down into the prompt layer, solving it with variants + fallbacks, rather than blocking people at the admission layer.

Solution

The variant selector: agent × language

The new prompt package contract introduces variants in prompts.json, using selectors to declare the matching dimensions and entries to declare each variant's matching rules and template files:

{
  "version": "1.1.0",
  "templateEngine": "handlebars",
  "variants": {
    "selectors": ["agent", "language"],
    "entries": [
      {
        "id": "native-zh-cn",
        "match": { "agent": ["claude", "codex"], "language": ["zh-CN"] },
        "systemTemplate": "./templates/zh-CN/native.system.md",
        "userTemplate": "./templates/zh-CN/native.user.hbs"
      },
      {
        "id": "fallback-zh-cn",
        "match": { "language": ["zh-CN"] },
        "systemTemplate": "./templates/zh-CN/fallback.system.md",
        "userTemplate": "./templates/zh-CN/fallback.user.hbs"
      }
      // ... native-en-us / fallback-en-us follow the same pattern
    ],
    "fallback": {
      "id": "fallback-default",
      "systemTemplate": "./templates/en-US/fallback.system.md",
      "userTemplate": "./templates/en-US/fallback.user.hbs"
    }
  }
}

Three levels of fallback, loosening progressively:

native variant: match constrains both agent (claude/codex) and language at the same time, so only native Agents hit it;
fallback variant: match constrains only language, not agent, so any Agent can hit it—this is the fallback for Agents that "have no native /goal";
fallback-default: the final safety net for when even the language can't be matched.

Order matters: entries is traversed in declaration order, with native placed ahead of fallback. So claude/codex hit native first; other Agents fall through to the fallback language variant.

Two sets of templates: native vs. fallback

For the same goal, the difference between the two system prompts lies entirely in their attitude toward that /goal line.

The native template (templates/zh-CN/native.system.md):

You are the built-in execution prompt of the `goal` task preset plugin.

This run must use `/goal` as the command surface for continuous work mode. Treat the provided project paths and repository scope as authoritative work boundaries.

This run is in a non-interactive environment. Do not question the user; when reasonable assumptions allow you to keep making progress, proceed directly and state those assumptions explicitly in your response.

The fallback template (templates/zh-CN/fallback.system.md):

You are the fallback execution prompt of the `goal` task preset plugin.

The current agent may not support the native `/goal` command. If a `/goal ...` line appears at the front of the prompt, treat it as goal metadata attached by the preset—do not treat it as a slash command that must be executed verbatim.

Please complete the task in continuous work mode, and treat the provided project paths and repository scope as authoritative work boundaries.

This run is in a non-interactive environment. Do not question the user; when reasonable assumptions allow you to keep making progress, proceed directly and state those assumptions explicitly in your response.

That core sentence is the soul of the fallback strategy: "If a /goal ... line appears at the front of the prompt, treat it as goal metadata attached by the preset—do not treat it as a slash command that must be executed verbatim." The /goal <goal> line that preludeTemplate splices in is a command in the eyes of a native Agent, but for a fallback Agent it is explicitly downgraded to "metadata / a goal marker," so that ordinary prompt following reproduces the same continuous-work behavior.

The user templates (.hbs) also come in two sets, and the fallback set has an extra "routing note" section that explicitly tells the Agent it was routed to a branch that doesn't rely on native /goal, and requires it to "not rely on native /goal support; instead use ordinary prompt-following to accomplish the same continuous-work behavior."

Backend: one resolution decides it all

Variant matching happens in the backend at ResolvePromptSelection in PCode.Application/Services/PresetTaskCatalogProvider.cs. It first resolves the locale, then packs language and agent into a selector dictionary, and finds the first matching variant in order:

public PresetTaskResolvedPromptSelection ResolvePromptSelection(string? locale, string? agentFamily)
{
    var resolvedLocale = ResolvePromptLocale(locale);
    if (!PromptPackage.UsesVariants)
    {
        // Legacy presets split by locale only take the legacy path, preserving backward compatibility
        var legacyTemplate = PromptPackage.Locales[resolvedLocale];
        return new PresetTaskResolvedPromptSelection(
            resolvedLocale, NormalizeAgentFamily(agentFamily), null, false,
            "legacy-locales", legacyTemplate);
    }

    var normalizedAgentFamily = NormalizeAgentFamily(agentFamily);
    var selectorInputs = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
    {
        [PresetTaskPromptSelectorNames.Language] = resolvedLocale,
    };
    if (!string.IsNullOrWhiteSpace(normalizedAgentFamily))
    {
        selectorInputs[PresetTaskPromptSelectorNames.Agent] = normalizedAgentFamily!;
    }

    foreach (var variant in PromptPackage.Variants)
    {
        if (!VariantMatches(variant, selectorInputs)) continue;
        return new PresetTaskResolvedPromptSelection(
            resolvedLocale, normalizedAgentFamily, variant.Id, false, "variants", variant.Template);
    }

    // No variant hit: fall to the explicitly declared fallback variant
    return new PresetTaskResolvedPromptSelection(
        resolvedLocale, normalizedAgentFamily, PromptPackage.FallbackVariant?.Id, true,
        "variants", PromptPackage.FallbackVariant?.Template ?? PromptPackage.Locales[resolvedLocale]);
}

The matching rule VariantMatches is dead simple—whatever selectors a variant declares, they all have to match at runtime; undeclared dimensions impose no constraint:

private static bool VariantMatches(
    PresetTaskPromptVariantDefinition variant,
    IReadOnlyDictionary<string, string> selectorInputs)
{
    foreach (var selector in variant.Match)
    {
        if (!selectorInputs.TryGetValue(selector.Key, out var runtimeValue))
            return false;
        if (!selector.Value.Contains(runtimeValue, StringComparer.OrdinalIgnoreCase))
            return false;
    }
    return true;
}

This explains why a fallback variant that only writes language can cover all Agents: it doesn't constrain the agent dimension at all, so any Agent whose language matches will hit it. The native variant, by contrast, adds one more constraint on agent, so only claude/codex can satisfy it.

Where does the Agent family come from? At runtime it's mapped from the selected hero's executor type—see PresetTaskRequirementModels.cs:

public static string? Resolve(AIProviderType? executorType) => executorType switch
{
    AIProviderType.ClaudeCodeCli => Claude,
    AIProviderType.CodexCli      => Codex,
    AIProviderType.GitHubCopilot => Copilot,
    AIProviderType.IFlowCli      => Iflow,
    AIProviderType.OpenCodeCli   => Opencode,
    // ... gemini / kimi / qoder / kiro / hermes / codebuddy / pi ...
    _ => null,
};

When creating a session, SessionsController.PresetTasks.cs first gets the hero, then calls PresetTaskAgentFamilies.Resolve(hero.ExecutorType) to get the family name and feeds it to ResolvePromptSelection. After a variant is selected, RenderPrompt renders the template with Handlebars and splices the /goal <goal> generated by preludeTemplate right at the front:

var renderedPrompt = prompt.FillTemplate(normalizedContext);
var commandPrelude = BuildCommandPrelude(normalizedContext); // -> "/goal <goalDescription>"
return string.IsNullOrWhiteSpace(commandPrelude)
    ? renderedPrompt
    : $"{commandPrelude}\n\n{renderedPrompt}";

Loosening admission: from an allowlist to `any`

With a fallback prompt in place, goal no longer needs to shut non-native Agents out. The requirements in backend/task-preset.json loosens from ["claude","codex"] to any:

{
  "taskKey": "goal",
  "requirements": [ { "type": "agent", "name": "any" } ],
  "inputBindings": [
    { "input": "goalCommandIds",  "promptParameter": "goalCommandIds",  "required": true },
    { "input": "goalDescription", "promptParameter": "goalDescription", "required": true },
    { "input": "targetScopeMarkdown", "promptParameter": "targetScopeMarkdown", "producer": "frontend-computed" }
  ]
}

Open up the admission layer, push the differences down to the prompt layer—this is the key trade-off of the whole design: compatibility is no longer a switch of "can it run," but a routing of "which prompt set does it run with."

Practice

What an end-to-end run looks like

In the goal drawer, the user fills in the goal description, selects the repository scope, picks a hero, and submits;
The backend resolves the agent family (e.g. claude / gemini) from the selected hero's executor type;
ResolvePromptSelection(locale, agentFamily) finds a variant by agent × language:
- claude/codex + zh-CN → native-zh-cn;
- gemini + zh-CN → native doesn't hit, falls to fallback-zh-cn;
RenderPrompt renders the selected template and splices /goal <goal description> at the front;
A native Agent executes the first line as a command; a fallback Agent, following the system prompt, treats the first line as metadata and reproduces continuous work via ordinary prompt following.

Adding Agent awareness to your own preset

If you want to do the same adaptation for a new preset, the routine is fixed:

In prompts.json, replace locales with variants, and add agent to selectors;
The native variant's match writes both agent and language; the fallback variant writes only language;
Then declare a top-level variants.fallback as the final safety net (the schema requires that the variants mode must have a fallback);
The backend needs no changes—ResolvePromptSelection / VariantMatches are generic;
If admission shouldn't be restricted, set the requirements agent to any.

A few easy pitfalls

Variant order is priority. native must come before fallback, otherwise the fallback that only constrains language would grab all Agents first, and claude/codex would never reach the native branch.
The fallback prompt must explicitly "downgrade" that /goal line. The /goal ... prefix is spliced on unconditionally (decided by preludeTemplate), so the sentence in the fallback system prompt—"treat it as metadata, don't execute it verbatim"—cannot be omitted, or a non-native Agent might treat it as an invalid command.
The non-interactive constraint must go into every template. goal is a queued auto-task, and the templates repeatedly emphasize "don't use AskUserQuestion, don't question, proceed with reasonable assumptions and state them," precisely to keep the Agent from getting stuck waiting for input while unattended.
Repository boundaries are enforced by the prompt, not by a sandbox. The templates explicitly require "only modify within repositories explicitly selected as writable, and treat read-only repositories as supplementary context." This is a soft constraint at the prompt layer, so fill in the repository scope carefully.
Backward compatibility is a free lunch. When an old preset writes no variants and only writes locales, UsesVariants is false, and it goes straight down the legacy-locales path—completely unaffected—so you don't have to touch existing presets just for the new model.

Conclusion

"If an Agent doesn't natively support goal, how do we extend it to make it work"—the answer isn't to hard-code a pile of branches for each Agent, but to model the difference as agent × language prompt variants:

Natively supported Agents (Claude / Codex) take the native variant and use the /goal command surface directly;
Unsupported Agents take the fallback variant, explicitly downgrade /goal ... to goal metadata, and reproduce the same continuous-work behavior via ordinary prompt following;
Matching relies on the generic rule that "whatever selectors a variant declares must all match" + progressive fallbacks, resolved once and for all on the backend;
Admission loosens from an allowlist to any, so compatibility shifts from "can it run" to "which prompt set does it run with."

The value of this design isn't limited to the single goal preset: the agent × language selector + fallback model is generic, reusable by any preset that needs to "give different instructions based on Agent capability," and with zero disruption to old presets.

References

Preset package: repos/hagitask/presets/goal/ (manifest.json, backend/task-preset.json, backend/prompts.json, backend/templates/{en-US,zh-CN}/{native,fallback}.*, frontend/commands.json, frontend/panel.json)
Prompt package schema: repos/hagitask/schemas/task-preset-plugin/prompt-package.schema.json
Backend variant resolution: repos/hagicode-core/src/PCode.Application/Services/PresetTaskCatalogProvider.cs (ResolvePromptSelection / VariantMatches / RenderPrompt / BuildCommandPrelude)
Agent family mapping: repos/hagicode-core/src/PCode.Application/Services/PresetTaskRequirementModels.cs (PresetTaskAgentFamilies.Resolve)
Session creation: repos/hagicode-core/src/PCode.HttpApi/Controllers/SessionsController.PresetTasks.cs
OpenSpec capability and proposals: openspec/specs/goal-preset-task/spec.md, openspec/changes/archive/2026-06-23-preset-task-agent-requirement-support/, openspec/changes/archive/2026-06-26-support-agent-language-prompt-selection-in-hagitask/

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-07-03-goal-preset-agent-compatible-prompt-variants%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

How to Use last30days for AI Research Based on Social Networks

Hagicode — Sat, 27 Jun 2026 10:33:43 +0000

How to Use last30days for AI Research Based on Social Networks

Every day on social networks, people express themselves: posting, voting, arguing, unsubscribing, migrating. These scattered voices on Reddit, X, YouTube comments, TikTok, Hacker News, and Polymarket are just noise when viewed individually, but together they form a fairly authentic slice of public opinion. The only problem is—no one wants to manually browse through thirty days of posts across eight platforms just to reach a research conclusion.

That's what the last30days skill was built for. It pulls together the last thirty days of content from these channels for you and synthesizes it by topic. The preset task layer then turns "calling last30days" from a command that requires memorizing parameters into a ready-to-run form.

This article isn't about how useful last30days itself is. Rather, it's about how HagiCode uses the preset task orchestration mechanism to solidly deliver "one skill, four research postures." After all, a skill is a capability, and a preset is the glue that turns capabilities into products.

Background: What Preset Really Saves Is That Sentence Said Over and Over

The preset task system originally bound a skill at the preset level. That is, one preset corresponded to one skill, with a relatively single way of calling it. But in reality, the same capability often needs to be used in different postures—with last30days, sometimes you want to do general research, sometimes you want competitive comparison, and sometimes you only want to analyze prompt style for a specific product.

Hard-coding these different usage patterns into one interaction flow makes the interface increasingly messy; splitting them into four independent skills duplicates work. So the design took a middle step: allow binding skills at the command level. One preset hangs multiple commands, each command self-describing which skill it calls and with what parameters; the preset-level requirements then serve as an authoritative list declaring which skills this preset depends on as a whole.

This way, interface stays interface, execution stays execution. Who wants to mix interface styles with execution logic anyway.

One Skill, Four Modes

The last30days preset is the exemplar of this paradigm: one skill, four commands. Four commands correspond to four research postures:

general (broad research): Give a query and let last30days pull relevant discussions from each platform over the last thirty days and synthesize a conclusion.
comparison: Explicitly specify the objects to compare, letting the skill organize material around "who's better/who's worse/their respective pain points."
competitors: Focus on a product's competitive ecosystem, calling last30days's built-in --competitors flag.
prompting (prompt style): Focus on how people actually use it and ask questions, oriented toward usage and mental models.

All four commands declare "skill": "last30days" in commands.json, but each has a different prelude (parameters and prompts). In the frontend drawer, users select a mode, write a query, and check target repositories; as for which command gets assembled behind the scenes, the preset decides that itself. Users don't need to memorize parameters or know about flags like --competitors.

Two Data Layers: commands.json and task-preset.json

Two files in the preset package share responsibilities quite cleanly:

commands.json: Describes "what commands exist and what each command looks like." Each command comes with a skill field explaining which skill it calls, plus its own prelude template explaining how to assemble this command into a single-line instruction. This is command-level self-description.
task-preset.json: Describes "what this preset needs overall." It holds requirements (the skill dependency list), inputs definitions, inputBindings, and metadata like selectionMode. This is the preset-level authoritative list.

The boundaries between the two layers are quite clear: commands are responsible for saying "I need this skill," and the preset is responsible for saying "which skills my preset allows." If a command declares a skill but it's not in the preset's requirements, validation fails with diagnostic command-skill-not-in-requirements. This explicit failure is much better than silent degradation.

Single-Line Injection: `/{skill} {prelude}`

What actually connects the skill into the execution flow is an unassuming little mechanism: single-line injection.

PresetTaskCatalogProvider has a method called CombineCommandSkillPrelude. The logic is simple: if a command declares a skill and its rendered prelude line doesn't start with /{skill}, prefix /{skill} onto it. What finally gets handed to the executor is a standalone instruction of the form:

/last30days {commandPrelude}

Then comes the body rendered by user.hbs: mode shaping, query, target repository boundaries, and the constraint of "non-interactive, record assumptions."

Why do this? Because skills like last30days themselves load and run upon "receiving a /{skill} instruction." The preset can't assume the skill will be automatically triggered; it must explicitly feed this instruction in. Just one line, but it's the key that makes the whole chain work.

Five-Stage Technical Chain

Putting all this together, from user clicking submit to conclusion linking back to the repository, there are five stages:

Frontend selection: Users select mode, write query, and check target repositories in CreatePresetTaskDrawer. resolveCommandPreview mirrors the backend assembly logic to show the preview instruction in real time; buildTargetScopeMarkdown groups by read/write and calculates repository boundaries as a markdown segment.
Backend validation: The request lands in SessionsController.PresetTasks.TryResolvePresetTaskRequestAsync. It first validates that inputs/targets/derived keys are on the whitelist, command id is in the catalog, selectionMode is single, then runs PresetTaskRequirementCheckService.CheckAsync: for each skill in requirements, it checks the local skill inventory via LocalSkillCommandAdapter and deduplicates by CacheKey.
Prompt rendering: Renders the corresponding user.hbs according to locale, injecting last30daysMode, last30daysQuery, targetScopeMarkdown, and targetRepositories. user.hbs explicitly forbids AskUserQuestion, requiring the executor to record assumptions rather than ask questions when encountering ambiguity—this is the hard boundary of non-interactive execution.
Skill loading and execution: The executor receives the assembled prompt. /last30days as a standalone instruction comes first, triggering skill loading. Inside the skill, it runs according to its own LAWs: Step 0.45 does keyword-trap pre-check (preventing query from being mistaken for handle/subreddit), Step 0.5/0.55 parses directed channels, Step 0.75 lets the reasoning model generate --plan itself, then runs the Python engine to pull data from Reddit/X/YouTube/TikTok/Instagram/HN/Polymarket/Web, Step 2 supplements with WebSearch, Step 2.5 appends to the raw file, and finally synthesizes a conclusion according to LAWs.
Conclusion linking back: The synthesized conclusion is brought back into the preset context. The read/write boundaries of target repositories rely on the soft constraint of targetScopeMarkdown in the prompt—the preset tells the skill "you can only read these and write those," and the skill follows this boundary during its own execution.

Several Practical Points

Non-interactive boundaries must be written into the template. Disabling AskUserQuestion in user.hbs isn't a suggestion, it's a hard constraint. When a preset runs, no one sits in front of the screen answering back-questions, so ambiguities must be digested by "recording assumptions."
Pre-set flags that can be preset. The competitors mode writes --competitors directly into the prelude; users don't need to know this flag exists. The meaning of a preset is to hide professional parameters in the right hands.
Skill deduplication relies on CacheKey. It doesn't matter if the same skill appears multiple times in requirements; PresetTaskRequirementCheckService deduplicates by CacheKey, so it won't repeatedly check or load.
Repository boundaries are soft constraints. Read/write boundaries rely on prompt injection, not sandboxing. This means whether the skill "obeys" depends partly on how well it follows the prompt. This is a realistic compromise.
Failures should be explicit, not silent. Missing skills should report requirement check failure, return 400, and provide a "one-click install" entry in the frontend (openSkillGalleryForSkill). Letting users know what's broken and how to fix it is far more responsible than quietly degrading into "can run without skill."
Migration should be non-destructive. The evolution from preset-level skill to per-command skill is backward compatible. Old preset-level declarations remain valid; new command-level declarations are additive capabilities, not replacements. Taking too big a step is easy to tear something, so why bother.

Preset task turns one skill into four product forms, not relying on any sophisticated algorithm, but on several contracts with cleanly drawn boundaries: command self-description, preset authoritative list, single-line injection, non-interactive hard constraints, explicit failure. Putting these together, "using last30days for social network research" moves from a command requiring memorized parameters to a feature that runs by filling out a form.

As for what these voices actually prove when gathered together—that's last30days's own job...

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-02-11-last30days-social-ai-research%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Precise Routing for Every Command: Practical Implementation of Multi-Skill Support in HagiCode Preset Task

Hagicode — Tue, 23 Jun 2026 11:52:41 +0000

Precise Routing for Every Command: Practical Implementation of Multi-Skill Support in HagiCode Preset Task

A preset packed with multiple commands, yet they all have to share the same skill requirements? This refactor lets each command independently declare its dependent skill, and visualizes this binding on the panel—badges, summaries, one-click installation, all in one smooth flow.

Background

Let me start with some context.

HagiCode's preset task is a plugin-based mini-tool system. Users don't need to manually type commands; just fill in a few fields on the visual panel and click to create an automated task session. Each preset is essentially a directory that typically looks like this:

manifest.json: preset identity information
panel.json: visual panel form definition
commands.json: list of commands to actually execute
task-preset.json or prompts.json: task parameters and skill requirements

This system is indeed convenient to use, but we quickly ran into an awkward limitation.

In the early versions, skills could only be declared in the requirements array at the preset level. What does this mean? It means all commands within the same preset share the same skill requirements. It might not sound like a big deal, but in practice, you encounter scenarios like this:

A preset has five commands, where the first one wants to use the last30days skill, the third one wants to use ui-master, and the remaining three don't need any skills. This was impossible in the old design. If you wanted different commands to route to different skills, you had to forcibly split these commands into multiple presets, and configuration would bloat immediately.

This is exactly the problem that proposal extend-preset-task-multiple-skills-support aims to solve: let each command independently declare the skill it depends on, and visualize this binding in the UI.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI code assistant project, and the preset task system is precisely its quick action entry point for users. Every change discussed below was refined through actual pitfalls and optimizations—after all, "reading books is no substitute for practicing." The project source code is at HagiCode-org/site, interested readers can go give it a Star first.

Clarifying the Problem First: Why Not a Mapping Table?

Before diving in, the most intuitive solution is: create another commandSkillMappings mapping table to store the "command ID → skill" relationship separately. This sounds clean, separation of concerns and all that.

But on closer reflection, it doesn't hold up.

Each command in commands.json already has an ID, and this ID would need to be copied into the mapping table. Two files, same ID—as soon as someone changes a command and forgets to sync the mapping table, the data drifts apart. This "separation for separation's sake" design has maintenance costs far outweighing the little cleanliness it brings. In the end, it just adds trouble.

So we ultimately chose a more direct path: put an optional skill field directly on the command definition. A command declares which skill it binds to itself, maintained locally, and nothing gets disconnected.

Behind this decision, there's a more important design principle worth pulling out separately.

Core One: Two-Layer Data Responsibility Separation

This is the most critical insight in the entire refactor.

Many people's first reaction is: since commands now have skill, shouldn't we scan each command's skill field when doing requirement check (skill gatekeeper inspection)?

No.

We deliberately split this into two layers:

skill field in commands.json: only responsible for declaring binding. It tells the system "this command binds to which skill," used for rendering prompt preambles and UI display.
requirements array in task-preset.json: this is the authoritative enumeration. It's the real gatekeeper, determining which skills a preset needs to satisfy to run.

In other words, skill answers "which to bind, what to render," while requirements answers "whether it's actually allowed to run." These are two separate things, don't mix them together.

The benefit of this split is that the check logic is naturally simple. Because the gatekeeper is always based on preset-level requirements, deduplicated by CacheKey, multiple commands binding the same skill only get probed once, without repeated hits. Command-level skills don't introduce any additional probing overhead.

This principle is also the fundamental reason we rejected the mapping table approach—a mapping table would mislead people into thinking "binding equals gatekeeping," stirring the two layers of responsibilities back together. Outsmarting yourself, plain and simple.

Core Two: What Does a Command Definition Look Like?

The refactored command definition simply adds an optional skill field to the original structure. Taking the last30days bundled preset as an example, its commands.json roughly looks like this:

{
  "$schema": "../../schemas/commands.schema.json",
  "version": "1.1",
  "commands": [
    {
      "id": "research",
      "skill": "last30days",
      "prompt": "调研一下最近30天大家对 {topic} 的真实讨论"
    },
    {
      "id": "summarize",
      "prompt": "把上面的调研结果整理成一份摘要"
    }
  ]
}

Several points to note:

version upgraded to 1.1, and the corresponding schema also added the optional skill field.
The first command research binds to the last30days skill, and execution will route to this skill.
The second command summarize doesn't bind to any skill, it's just a regular instruction taking the default path.
Note here that no requirement is written in the command. The real gatekeeper is in the requirements of task-preset.json:

{
  "requirements": [
    {
      "key": "last30days",
      "cacheKey": "skill:last30days"
    }
  ]
}

The last30days bound by the research command must appear in this requirements, otherwise there's a problem—which is exactly the hard constraint discussed in the next section. You can't force things.

Core Three: Cross-Validation During Loading

Declaring bindings in data alone isn't enough; someone needs to provide a safety net to prevent "orphan bindings" where a command binds to a skill but it's never declared in requirements from making it to production.

This safety net is ValidateCommandSkills. It runs once during preset package loading, checking each command's skill one by one to see if it can find a corresponding entry in the preset-level requirements. If not found, it judges the package as illegal, directly disables the entire preset, and throws diagnostic code command-skill-not-in-requirements.

Why disable the entire package instead of just skipping that command? Because a preset is a whole, and commands often have dependencies (one command's output feeds into the next). If you silently skip one, the following commands get empty input, and behavior becomes completely unpredictable. After all, you can't read people's minds, and you can't read code's either. Better to let users see explicit errors than to let tasks mysteriously go off the rails halfway. This point can't be sloppy.

This validation is completed during the loading phase, meaning the problem is discovered the moment the preset is registered, not dragged out until the user actually clicks "run" to explode. For user experience, early errors are always better than late errors.

Core Four: Idempotent Splicing of Prompt Preambles

Next is the most subtle link in the execution chain.

When a command binds to a skill, such as last30days, the system needs to "splice" this skill information in front of the command before actual execution, forming a complete single-line instruction to pass to the executor. This process is handled by CombineCommandSkillPrelude.

Let me give a concrete example. The research command's prompt is "调研一下最近30天大家对 {topic} 的真实讨论", and the bound skill is last30days, so the final instruction passed to the executor roughly becomes:

/last30days 调研一下最近30天大家对 {topic} 的真实讨论

That is, the /last30days preamble is added before the prompt. When the executor sees this preamble, it knows to first switch context to the last30days skill.

There's a pitfall here: idempotency.

Why emphasize idempotency? Because in some scenarios, the prompt itself might already carry this skill preamble (for example, the user manually wrote half, or copied it from somewhere else). If the system foolishly splices it again, it becomes /last30days /last30days 调研..., and the executor either errors or behaves abnormally.

So CombineCommandSkillPrelude detects before splicing; if the prefix already exists, it doesn't add it again. This step seems insignificant, but it can block a class of very subtle bugs.

It's worth mentioning that this entire preamble injection logic is completed at the preset definition layer ( BuildCommandPrelude in PresetTaskCatalogProvider ), and the session creation code on the SessionsController side doesn't need to change at all. This is also the benefit brought by separation of concerns—the execution entry remains stable, and the complexity of skill routing is contained within the definition layer.

Core Five: How the Frontend Displays Bindings

With the backend straightening out the data model and execution chain, the final step is to let users "see" this binding in the interface. After all, if users can't perceive a feature, it's essentially not done.

The frontend did three things.

First, add badges to the command selector. In the command-picker, a small badge appears next to each command bound to a skill, indicating which skill it depends on. Users can tell at a glance which command is "skill-enabled" and which is a regular command.

Second, requirement-check summary block. The panel has a dedicated summary area listing all skill requirements the current preset needs to satisfy, and which skill each command binds to. The data for this block comes from the commandSkillsByRequirementKey mapping—grouping and aggregating commands by their bound requirement key, so users can easily compare whether "requirements" match "actual bindings". Trying to draw a tiger and ending up with a dog—something like that—so the aggregation logic needs to be straightforward, not flashy.

Third, one-click installation deep link on failure. If requirement check finds a skill isn't installed, users don't need to go dig through documentation to find the installation entry. The interface directly gives a deep link button; click to jump to the corresponding installation process. This step compresses the distance between "discovering a problem" and "solving a problem" to the shortest possible.

The frontend types are also restrained, the command type just adds a skill?: string, and normalization is done (|| undefined), avoiding empty strings and other boundary values causing trouble in subsequent judgment logic.

Practice: Five Steps to Complete the Refactor

Stringing together the scattered points from before, the entire refactor is actually just five steps:

Extend schema: commands.schema.json adds optional skill field, version number upgraded to 1.1.
Parse + validate: NormalizeCommands is responsible for parsing command definitions, ValidateCommandSkills does cross-validation, command skills must be findable in preset-level requirements.
Inject preamble: BuildCommandPrelude idempotently splices the /skill preamble before commands before execution, no need to modify SessionsController.
Migrate bundled preset: last30days and ui-master built-in presets' commands.json get modified, adding the skill field to corresponding commands. Migration only touches commands.json, doesn't touch other files.
Frontend visualization: types add field, command-picker adds badges, requirement-check adds summary block, deep link for one-click installation on failure.

A few points to note in practice, listed separately:

One command can only bind to one skill. This is the current constraint. If a scenario really needs one command to trigger multiple skills, the escape hatch is to declare multiple skills in the preset-level requirements, letting them coexist at the preset level.
Diagnostic code for validation failure is command-skill-not-in-requirements, search this code directly when troubleshooting.
Frontend normalization remember || undefined, don't let empty strings sneak into judgment logic.
When migrating, only touch commands.json, keep requirements unchanged to avoid introducing unexpected changes.
Backend testing covers three scenarios: command skill in requirements (pass), not in requirements (disable package), multiple commands binding same skill (deduplication normal).

Summary

This multi-skill support refactor for preset task,表面上 just adds a skill field to commands, but it pulls out a design question worth pondering: should binding and gatekeeping be separated?

Our answer is separate. The skill field only manages "which to bind, what to render," while requirements manages "whether it's allowed to run." Once these two layers of responsibilities are mixed together, whether using a mapping table or some other form, subsequent validation, deduplication, and UI display become awkward. After separating, each layer becomes simple: the gatekeeper is always based on one authoritative enumeration, bindings are maintained locally and won't drift, preamble splicing is idempotent and controllable, and the UI just displays already clear data.

Looking back, the entire refactor didn't use any fancy technology, it just relied on cleanly cutting responsibilities and then having each layer provide the safety net it should. After this round of polishing, HagiCode's preset task system can finally route every command precisely to the skill it should go to. In the end, things should have been this simple all along...

References

HagiCode-org/site: project source code, complete implementation of preset task system is here.
HagiCode 官网: understand HagiCode's overall capabilities.
OpenSpec proposal extend-preset-task-multiple-skills-support: original design document for this refactor, containing proposal, design, and tasks.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-23-hagicode-preset-task-multiple-skills-support%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

How HagiCode Integrates 13 Agent CLI Tools into a Single System

Hagicode — Mon, 22 Jun 2026 12:15:25 +0000

How HagiCode Integrates 13 Agent CLI Tools into a Single System

Honestly, it's not that hard, yet not that simple either. Let's talk about how we use a layered architecture to uniformly manage diverse Agent CLIs like Claude Code, Codex, Copilot, and Gemini—and how we can plug in a new one at any time.

Background

The story started abruptly, born from a pretty headache-inducing problem.

Agent CLIs have sprung up like bamboo shoots in recent years—Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Kimi, Qoder, Kiro... a new one pops up every few months. As a project that wants users to "install one HagiCode and use the full suite of Agents," we couldn't bet on just one CLI. But we also couldn't write a complete set of logic for each CLI covering installation, health checks, and scheduling—the code would bloat until it was unmaintainable, like a tangled ball of yarn that no one dares touch.

More troublesome, these CLIs have wildly different temperaments: some use stdio, some gRPC, some only give you a shell entry point, and streaming output formats each speak their own language. If we wrote judgments like if (provider == ClaudeCode) directly in business code, within six months it would become a lump of "legacy code" no one dares touch. After all, who wants to touch a brick that looks ready to crumble?

To contain all these pain points, we made a decision: add a thin abstraction layer and shared runtime between the business layer and specific CLIs. This looks simple, yet it directly determines whether HagiCode can quickly integrate new CLIs. I'll explain the specifics shortly.

About HagiCode

The solution shared here comes from our hands-on practice in the HagiCode project. HagiCode is an AI code assistant integration platform with a very pure goal—use one installation, one configuration, to bring in all mainstream Agent CLIs for users.

How the Number "13" Came About

First, a number that gets asked repeatedly—why 13 Agent CLIs.

Actually, the answer is hidden right there in the AIProviderType enum, like bamboo shadows outside a window—as long as you're willing to look, you can see it. The original definition looks like this:

public enum AIProviderType
{
    ClaudeCodeCli = 0,
    CodexCli = 1,
    GitHubCopilot = 2,
    CodebuddyCli = 3,
    OpenCodeCli = 4,
    IFlowCli = 5,        // Deprecated
    HermesCli = 6,
    QoderCli = 7,
    KiroCli = 8,
    KimiCli = 9,
    GeminiCli = 10,
    DeepAgentsCli = 11,
    ReasonixCli = 12,
    PiCli = 13,
}

The enum has 14 values total, but the IFlowCli=5 path is now blocked. In AIProviderFactory, it's explicitly shut out:

if (providerType == AIProviderType.IFlowCli)
{
    throw new NotSupportedException("IFlowCli is no longer supported");
}

Combined with filtering through IsActivelySupportedProviderType(), the ones actually "alive" in the system are 13: Claude Code, Codex, GitHub Copilot, CodeBuddy, OpenCode, Hermes, Qoder, Kiro, Kimi, Gemini, DeepAgents, Reasonix, Pi.

That's where "13" comes from. Not a marketing number—counted straight from the code. After all, numbers don't lie. Only we do.

Layered Architecture: Locking Down Change

The core idea behind connecting 13 CLIs comes down to one sentence: let business code not care which specific CLI it's calling.

We broke it down into six layers, looking from top to bottom:

1. Identity Layer — `AIProviderType`

The enum is each CLI's "ID number." Anywhere a CLI is mentioned, this enum value identifies it. Strings and enums convert between each other via ToStringValue() / ToAIProviderType(). Simple, yet indispensable.

2. Business Contract Layer — `IAIProvider` / `IAIProviderFactory`

The business side only recognizes the IAIProvider interface, which defines universal actions like "send a prompt, get a streaming response." As for whether it's Claude or Codex underneath—business doesn't care. Like sending a letter: you hand it over, what the mailman's surname is, who cares?

3. Adapter Layer — `*CliProvider`

Each CLI corresponds to a thin adapter, like PiCliProvider, ReasonixCliProvider, ClaudeCodeCliProvider. These adapters have very little to do: translate universal business requests into parameters specific CLI can understand, then translate specific CLI output back. They're deliberately written thin—adding a new CLI basically means copying an existing one and tweaking.

4. Shared Runtime Layer — `ICliProvider<TOptions>`

This layer lives in HagiCode.Libs and does the real dirty work: launching processes cross-platform, handling stdio transport, parsing streaming output, handling timeouts and retries. All adapters reuse the same runtime, so when onboarding a new CLI, process management basically doesn't need rewriting.

To use an analogy: the adapter layer is the "interpreter," the shared runtime layer is the "delivery company." The interpreter just makes sure the message is clear; how the package gets delivered, whether there's traffic on the road—that's the delivery company's concern. Each does their job, and the world is peaceful.

5. Factory Routing Layer — `AIProviderFactory`

Inside CreateProvider, a switch instantiates the corresponding adapter based on AIProviderType, validating IsConfigured along the way. This is the only place that "knows concrete types," strictly isolated in the factory. Change is only allowed in one corner; everywhere else stays clean.

6. Directory / UI Projection Layer — `main-professions.yaml`

This layer is interesting—it's not code, it's data.

The primary profession list (role profiles like "I'm a frontend dev," "I'm a backend dev," "I'm a full-stack dev") is driven by the preset file main-professions.yaml, read through HeroPrimaryProfessionPresetProvider, then projected to the frontend UI. Adding a new primary profession requires no code changes—just edit YAML. Data instead of code, peace of mind.

By the way, this is the biggest refactor in HagiCode. Early versions had a code-embedded registry called AgentCliInstallRegistry. Later we found maintenance cost too high—more code, more tired people—so the whole thing got torn down and replaced with a data-driven + health monitoring approach. This is also why HagiCode can now rapidly expand profession types.

How Installation Gets Solved

13 CLIs all need installation, each with different official installation methods—that's another mountain.

Our approach is Docker Compose pre-installation + external management fallback. The Docker image pre-installs mainstream CLIs (Claude Code, Codex, Copilot, CodeBuddy, OpenCode, Qoder, Kiro, Kimi, Gemini, Pi), so users pull the image and use it—no typing commands one by one. Installed, naturally in a better mood.

For those needing separate installation in local environments, the installation command matrix looks roughly like this (verified against official docs):

CLI	Official Installation Method
Claude Code	`npm install -g @anthropic-ai/claude-code`
Codex	`npm install -g @openai/codex`
GitHub Copilot	`npm install -g @github/copilot`
CodeBuddy	`npm install -g @tencent-ai/codebuddy-code`
OpenCode	`npm i -g opencode-ai@latest`
Qoder	`npm install -g @qoder-ai/qodercli`
Kiro	`curl -fsSL https://cli.kiro.dev/install \
Kimi	{% raw %}`curl -LsSf https://code.kimi.com/install.sh \
Gemini	npm
Hermes	Official script, docs-only fallback preserved
DeepAgents / Reasonix	See respective official docs

The frontend {% raw %}PrimaryProfessionCard.tsx also changed accordingly—it now has no "Install CLI" button, but instead displays CLI availability, version detection results, and a fallback hint that "this CLI is externally managed." In other words, whether it installs successfully is the system layer's responsibility; UI only faithfully reports status. Writing state and logic separately, they'll eventually drift apart—so why bother?

What It Takes to Add a New CLI

In practice, adding a new CLI to HagiCode comes down to these steps:

Add an enum value to AIProviderType
Copy an existing *CliProvider, modify it for the new CLI's parameters and output parsing
Add a routing line in AIProviderFactory's switch
If entering the primary profession directory, configure it in main-professions.yaml
Add an installation command to the image (or fall back to external management)

Through this entire process, core changes don't exceed two hundred lines of code—that's the true value of this abstraction. Each additional CLI has very low marginal cost; business code doesn't need a single change. All roads lead to Rome, ours just happens to be a slightly easier walk.

Summary

Looking back, "integrating 13 CLIs" sounds daunting, but broken down, it's really two layers of work:

One layer is isolating change—through AIProviderType enum + IAIProvider contract + thin adapters + shared runtime, decoupling business code from specific CLIs. The other layer is data-ifying configuration—using YAML presets like main-professions.yaml to drive the directory and UI, avoiding touching code every time something is added.

This solution is what stabilized after we stumbled through pits and iterated a few rounds in actual HagiCode development. If you're working on a similar "multi-provider integration" system, I hope this layered approach gives you some reference. After all, Agent CLIs will keep popping up in the coming years—an architecture that can quickly integrate new CLIs matters far more than "how many are supported right now"...

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-22-hagicode-13-agent-cli-integration-architecture%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Solving Backend Distributed Challenges in AI Programming Workbenches with Orleans

Hagicode — Sun, 21 Jun 2026 07:30:48 +0000

Solving Backend Distributed Challenges in AI Programming Workbenches with Orleans

Managing dozens of AI CLI tools in a single process while pulling real-time streams across dozens of sessions—sounds like a pipe dream? Honestly, we thought it was pretty ridiculous too. But Orleans's Virtual Actor model actually tames this complexity quite beautifully. You know how some tools are born to solve specific problems? You just don't realize how perfect they are until you actually encounter that problem.

Background

Building an AI programming workbench product has a unique architectural quirk: each user session is essentially a living, stateful "lifeform" that can engage with you for an hour or two. When a user drops in a message, the system needs to pick an appropriate AI Provider—Claude Code, Codex, Gemini, Kimi, CodeBuddy, etc., just listing the names takes fingers and toes—then spin up subprocesses, push execution results back in real-time through streaming channels, and synchronize various state changes over SignalR.

If you tried to tackle this with a traditional stateless HTTP + Redis approach, you'd face some headaches:

Multi-provider management is fragmented everywhere. Each AI CLI tool has its own process model, streaming output format, and timeout temperament. Mixing a dozen different logics together, the code quickly becomes—you know—spaghetti. Not that it's inedible, it just gives you indigestion.
Timeouts are uncontrollable, it's pure luck. An AI operation might finish in three minutes, or drag on for two hours. Use a global unified timeout config? Then short operations get pointlessly cut off—think about it, that's unfair to users. Conversely, long operations chewing up the thread pool isn't a pretty picture either.
Concurrency needs careful budgeting, since GPUs don't fall from the sky. Run too many AI operations simultaneously and machine resources max out immediately; but being too conservative means wasting compute power you paid for—it's like cranking the AC to 16 degrees and then piling on quilts. You need precise control over active session counts based on global permissions.
State management is complex enough to make you question life choices. Each session has its own message queue, phase state, bound executor—this is stateful data. Forcing it into a stateless HTTP model means using Redis as universal glue. It sticks, sure, then you discover you've written a mountain of serialization/deserialization and distributed lock logic. After finishing, you stare at the screen: am I solving business problems, or fighting infrastructure?

These problems together aren't so much a technical challenge as a soul-searching interrogation of your architecture choices.

About HagiCode

These ideas didn't materialize out of thin air. The solution shared in this article comes from our real-world battle scars in the HagiCode project. HagiCode is a desktop workbench for AI-assisted collaborative programming. Its backend coordinates dozens of AI CLI tools in a single process while providing low-latency real-time responses to the frontend—basically, we want the horse to run, not eat grass, and sing while running.

The Orleans architecture discussed below is exactly what we honed and optimized during HagiCode's development. If you find this solution interesting, it shows our engineering foundation isn't bad—so HagiCode itself might be worth a closer look.

Selection: Why Orleans

Facing that soul-searching interrogation above, we seriously considered three paths:

Approach A: Stateless API + Redis state management. The logic is simple enough—pull session state from Redis per request, execute, write back. Horizontal scaling feels comfortable, but the Redis state structure grows alongside the business until you're not sure if you're maintaining a cache or an implicit database. State consistency relies on locks, streaming communication requires additional WebSocket/SSE routing layers. Essentially, Redis is just a shared dictionary here—it can't provide the stateful abstraction you really need.

Approach B: Actor model frameworks (Dapr / Akka.NET). Dapr's Actor capability is sufficient, but it requires deploying a Sidecar—for local desktop products, that's not just overkill, it's like driving a tank to buy groceries. Akka.NET's Actor model leans more toward low-latency short tasks. For long-lifecycle workflows lasting an hour or two, you have to handle persistence and recovery yourself—the framework doesn't provide a safety net.

Approach C: Microsoft Orleans. When we saw Orleans's Virtual Actor model—how to put it—it felt like searching everywhere for your keys, then realizing they're in your pocket. Several features seem literally tailor-stitched for our scenario:

Automatic Activation/Deactivation management: You don't worry about when grains are born or die—the runtime handles it all. One session corresponds to one grain, session alive means grain alive, session ends means grain auto-recycled. This "don't have to care" feeling—only people who've experienced manual lifecycle management understand.
Native streaming support with IAsyncEnumerable<T>: From CLI process output to frontend display, fully async streaming throughout, no intermediate buffer queues needed. Just this one feature saved us at least a thousand lines of hand-written glue code.
[AlwaysInterleave] and [ResponseTimeout]: Fine-grained concurrency and timeout control, configured per interface level, not a global一刀切. Finally no more painful choices between "all short" or "all long."
Built-in persistent state (IPersistentState<T>): State auto-persists, no need for extra distributed cache setup. Peace of mind, seriously.

In evaluation, Orleans almost perfectly checked all boxes for HagiCode backend's core needs:

Capability	Orleans Solution
Stateful sessions	`IPersistentState<T>` + SQLite Shard persistence
Streaming output	`IAsyncEnumerable<T>` native support, auto-penetrates to SignalR
Long timeout control	`[ResponseTimeout("02:00:00")]` configured per interface granularity
Provider polymorphic routing	`ExecutorGrainFactory` dispatches based on `AIProviderType`
Concurrency control	`SessionConcurrencyManager` with grain single-threaded scheduling

Five Core Design Decisions

Choosing the right tool is just step one. How to implement it is where the real skill shows. Below are five key designs we distilled after stepping into pits, climbing out, and brushing ourselves off. Some are experience, some are lessons, some... forget it, just read them yourself.

1. Facade Grain Pattern

The system's core scheduling grain is SessionGrain. But it doesn't directly handle all logic—if it did, it would become a god class with tens of thousands of lines. God classes—you feel omnipotent writing them, worthless modifying them.

We delegate domain-specific logic to two runtime components: ChatSessionGrain handles chat mode, ProposalSessionGrain handles proposal mode.

internal partial class SessionGrain(
    ILogger<SessionGrain> logger,
    IServiceProvider serviceProvider,
    IExecutorGrainFactory executorGrainFactory,
    IMessageService messageService,
    [PersistentState("session")] IPersistentState<SessionState> state)
    : Grain, ISessionGrain
{
    internal ChatSessionGrain ChatSessionComponent =>
        _chatSessionComponent ??= new ChatSessionGrain(RuntimeContext);

    internal ProposalSessionGrain ProposalSessionComponent =>
        _proposalSessionComponent ??= new ProposalSessionGrain(RuntimeContext);

    internal ISessionRuntimeComponent GetRuntimeComponent(SessionType sessionType) =>
        sessionType switch
        {
            SessionType.Chat => ChatSessionComponent,
            SessionType.Proposal => ProposalSessionComponent,
            _ => throw new ArgumentOutOfRangeException(nameof(sessionType))
        };
}

This pattern is clean: grain identity is stable, doesn't change with session type; external callers only deal with ISessionGrain, they don't care how work is split internally; components themselves are stateless, can be rebuilt on demand; both share the same SessionState persistence, data consistency naturally handled. Who says architectural design can't be elegant?

2. Polymorphic Executor Factory

HagiCode supports a dozen AI CLI tools, each requiring independent process management and streaming output. We implemented a dedicated grain for each tool—ClaudeCodeGrain, CodexGrain, GeminiGrain, etc., listing them like roll call. Then we rely on a factory for unified routing:

internal sealed class ExecutorGrainFactory : IExecutorGrainFactory
{
    public IExecutorStreamGrain GetExecutorGrain(
        AIProviderType executorType, CessionId cessionId)
    {
        return executorType switch
        {
            AIProviderType.ClaudeCodeCli => ExecutorStreamGrainAdapter.From(
                _grainFactory.GetGrain<IClaudeCodeGrain>(cessionId.Value)),
            AIProviderType.CodexCli => ExecutorStreamGrainAdapter.From(
                _grainFactory.GetGrain<ICodexGrain>(cessionId.Value)),
            AIProviderType.GeminiCli => ExecutorStreamGrainAdapter.From(
                _grainFactory.GetGrain<IGeminiGrain>(cessionId.Value)),
            // ... 10+ providers
            _ => throw new NotSupportedException(
                $"Unsupported executor type: {executorType}")
        };
    }
}

All executor grains implement the same IExecutorStreamGrain interface, with unified adaptation via ExecutorStreamGrainAdapter. Upper-layer code is completely unaware of which Provider is being used underneath—add a new tool? Add a new grain class, add one line to the factory switch, done. This extension point—how to put it—is like leaving a door for your future self, and behind the door is no complex maze, just walk straight in.

3. Streaming Communication Pipeline

Orleans's native support for IAsyncEnumerable<T> makes streaming output particularly natural. Taking ClaudeCodeGrain as an example:

public async IAsyncEnumerable<ClaudeCodeResponse> ExecuteCommandStreamAsync(
    string command,
    string? heroId,
    [EnumeratorCancellation] CancellationToken token = default)
{
    var (provider, configuration) = await CreateProviderAsync(heroId, token);

    await foreach (var response in SendAsync(command, provider, context, token))
    {
        yield return response;
    }
}

The entire pipeline looks like this: CLI process stdout → grain streaming yield → ExecutorGrainFactory wraps as SessionMessage → SessionGrain pushes to frontend via SignalR. Every step is async streaming, no intermediate buffering, no synchronous blocking. This is also one of the best parts about Orleans compared to traditional approaches—you don't need to maintain a ConcurrentQueue inside the grain and manually push, yield return four characters handle everything. This fluency—once you've experienced it, there's no going back.

4. Layered Timeout Strategy

AI operations have extreme time variance—a simple syntax correction might take 3 seconds, a complex refactoring could run for two hours. One-size-fits-all timeout strategy? What gets cut isn't the knife.

We configure in layers: Silo level defaults to 30 second timeout, individual interfaces override via [ResponseTimeout]:

public static class GrainTimeouts
{
    public const string LongRunningResponseTimeout = "02:00:00";
    public const string HealthCheckResponseTimeout = "00:01:00";
}

[Alias("HagiCode.Orleans.IAIGrain")]
public interface IAIGrain : IGrainWithStringKey
{
    [ResponseTimeout(GrainTimeouts.LongRunningResponseTimeout)]
    Task<ProposalOptimizationBundleResultDto> OptimizeProposalBundleAsync(...);

    [ResponseTimeout(GrainTimeouts.HealthCheckResponseTimeout)]
    Task<HealthCheckResult> PingAsync(HealthCheckRequest? request = null);
}

The principle is simple: conservative by default, relaxed as needed. This isn't some deep theory—it's just applying the principle of least privilege to timeout configuration. AI operations get two hours, health checks get one minute, each lives their own life, no one delays anyone.

5. Batch Grain Collection Configuration

By default, Orleans automatically recycles (deactivates) grains after they're idle for a while. This is good in itself, but frequent activation/recycling is like repeatedly opening and closing the fridge door—just adding overhead. We configured longer collection times uniformly for core grain types:

internal static void ConfigureGrainCollectionOptions(
    GrainCollectionOptions options,
    OrleansTimeoutPolicy? timeoutPolicy = null)
{
    var coreGrainTypes = new[]
    {
        typeof(SessionGrain).FullName,
        typeof(ClaudeCodeGrain).FullName,
        typeof(CodexGrain).FullName,
        typeof(GameDriverGrain).FullName,
        // ... 十余种核心 grain
    };

    var collectionAge = timeoutPolicy?.GrainCollectionAge
        ?? TimeSpan.FromHours(24);

    foreach (var name in coreGrainTypes)
    {
        options.ClassSpecificCollectionAge[name!] = collectionAge;
    }

    // MessageBucket exception: 10 minute fast recycling
    options.ClassSpecificCollectionAge[typeof(MessageBucketGrain).FullName!] =
        TimeSpan.FromMinutes(10);
}

The core idea is differentiation: high-frequency short-lived grains recycle quickly to release memory, core business grains keep hot caches with minimal churn. This optimization looks simple, but if you don't set it, default collection strategy has visible impact on throughput—anyone who's wrestled with this knows what I mean.

Implementation Practice

Local Development and Persistence

HagiCode local development uses Development Clustering, persistence via SQLite Shard, already validated across multiple contributor environments:

context.Services.AddOrleans(siloBuilder =>
{
    siloBuilder.UseDevelopmentClustering(options =>
    {
        options.PrimarySiloEndpoint = new IPEndPoint(
            IPAddress.Loopback, siloPort);
    });

    siloBuilder
        .Configure<ClusterOptions>(options =>
        {
            options.ClusterId = "hagicode-cluster";
            options.ServiceId = "hagicode-service";
        })
        .AddActivityPropagation();

    siloBuilder.ConfigureServices(services =>
    {
        services.AddSqliteGrainStorage(
            ProviderConstants.DEFAULT_STORAGE_PROVIDER_NAME,
            options =>
            {
                options.ShardRootPath = storageOptions.ShardRootPath;
                options.ShardCount = storageOptions.ShardCount;
                options.UseWalMode = storageOptions.UseWalMode;
            });
    });
});

Custom SqliteGrainStorage creates multiple database files by shard, paths like data/orleans/grains/shard_00.db. Production can switch to Azure Table Storage or SQL Server without changing a single line of code—this is the benefit of Orleans's storage provider abstraction. How to put it—good abstractions let you change backends like changing clothes; bad abstractions make it as painful as changing skin.

Concurrent Session Control

SessionConcurrencyManager uses in-process locks + global counters to manage active session count limits:

internal static class SessionConcurrencyManager
{
    private static readonly HashSet<SessionId> GlobalActiveSessions = [];
    private static readonly Lock Lock = new();

    internal static ConcurrencyCheckResult TryActivateSession(SessionId sessionId)
    {
        lock (Lock)
        {
            if (GlobalActiveSessions.Contains(sessionId))
                return new ConcurrencyCheckResult { Allowed = true };

            if (GlobalActiveSessions.Count >= _cachedMaxConcurrentSessions)
                return new ConcurrencyCheckResult { Allowed = false };

            GlobalActiveSessions.Add(sessionId);
            return new ConcurrencyCheckResult { Allowed = true };
        }
    }
}

This manager uses Stack Trace + Caller verification to restrict calls only from inside SessionGrain, preventing external code from bypassing concurrency checks. Though honestly, using internal static here actually breaks Actor isolation principles—but concurrency control is indeed a global need, so after weighing tradeoffs we accepted this design compromise. Perfect is the enemy of good—this saying holds true in architectural design too.

Health Check Integration

AIGrain.PingAsync() has two modes: lightweight connectivity probing and explicit Ping-Pong verification. The latter is used in the setup wizard to verify if a Provider is actually usable:

public async Task<HealthCheckResult> PingAsync(
    HealthCheckRequest? request = null)
{
    if (!isModelAware)
    {
        // Lightweight CLI readiness probe
        var provider = await aiProviderFactory.GetProviderAsync(
            AIProviderType.ClaudeCodeCli);
        var result = await provider.PingAsync(timeoutCts.Token);
        return new HealthCheckResult { IsHealthy = result.Success };
    }

    // Explicit Ping-Pong verification
    var response = await aiService.ExecuteAsync(new AIRequest
    {
        Prompt = HealthCheckPingPongProbe.Prompt,
        SystemMessage = HealthCheckPingPongProbe.SystemMessage,
        Temperature = 0,
        MaxTokens = 32
    }, timeoutCts.Token);

    var passed = HealthCheckPingPongProbe.IsExpectedResponse(
        normalizedResponse);
    return new HealthCheckResult { IsHealthy = passed };
}

Temperature set to 0, MaxTokens limited to 32—guarantees response determinism while controlling costs. After all, health checks aren't for running benchmarks, just needs to be good enough. Same with people—knowing when to stop is rarer than knowing when to act.

Conclusion

Looking back at HagiCode's journey building backend systems with Orleans, five core design decisions are worth remembering:

Configure timeouts at interface granularity, don't use global unified timeouts—AI operations 2h, health checks 1min, default 30s, each manages their own, no crossing paths.
Differentiate Grain Collection ages—high-frequency short-lived grains recycle quickly, core business grains keep hot caches, be fast where needed, be stable where needed.
Streaming pipeline should be async throughout—from CLI stdout to SignalR push, don't introduce any synchronous blocking middleware, let it flow naturally like water.
Facade Grain splits complexity—components are stateless but share persistent state, much more maintainable than god classes. Divide and conquer—ancestor wisdom applies equally well to code.
Mark stable names on Grain interfaces with [Alias]—the last line of defense for serialization compatibility. Guard this line, and the probability of being woken up by alerts in the middle of the night drops significantly.

Orleans's Virtual Actor model provides a complete-to-the-point-of-touching runtime abstraction for stateful, long-lifecycle session systems. If you're also building similar AI workbenches or real-time collaboration systems, this solution is worth trying—not because it's perfect, but because in the right scenarios, it's just right.

This memory can become something to cherish, though I was bewildered at the time... getting off track. Anyway, the code runs, the article is written. That's it.

Summary

Around "Solving Backend Distributed Challenges in AI Programming Workbenches with Orleans," a more prudent approach is to first get key configurations, dependency boundaries, and implementation paths working, then fill in optimization details.

When goals, steps, and acceptance criteria are clear, such solutions typically transition more smoothly into actual delivery.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-21-orleans-hagicode-backend-system%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

What is MonoSpecs: Why It's a Further Upgrade and Extension of OpenSpec

Hagicode — Sat, 20 Jun 2026 04:30:21 +0000

What is MonoSpecs: Why It's a Further Upgrade and Extension of OpenSpec

When a product system expands to 40+ independent Git repositories, where should "specifications" be placed? This article discusses the two steps HagiCode took in multi-repository governance: first lifting OpenSpec to the main repository, then developing MonoSpecs as a multi-repository management solution on top of it. Really nothing special, just stumbled through some pitfalls and wanted to document them.

Background

Anyone who's worked on a slightly larger product has probably had this experience—initially the code was in a single repository, well-organized and peaceful; later the frontend, backend, desktop app, documentation site, official website, and build tools each became independent repositories, and the number of repositories kept growing like wild grass, unstoppable. Then when you wanted to write a "specification document" for some cross-repository functionality, suddenly you didn't know where to write it—it's a bit like childhood pocket money, suddenly gone without a trace.

Our own HagiCode is such a product system composed of 40+ independent Git repositories. In the early days, we directly stuffed OpenSpec's openspec/ directory into the backend sub-repository hagicode-core, thinking that since the backend is the core, placing it there would be most stable. As the number of repositories grew, this approach exposed a series of headache-inducing problems. After all, the code world never actually becomes stable just because you "thought it would be stable."

The first pain point: specs are trapped in a single sub-repository. If a functionality affects both the frontend web and the backend hagicode-core, I have to write proposals in hagicode-core, then go to other sub-repositories to execute code changes. Which repository a proposal belongs to itself becomes a controversy.

The second pain point: sub-repositories are not pure. Each sub-repository carries its own openspec/, mixing specification documents with product code. Someone clones your frontend repository and ends up bringing back a bunch of backend proposal documents, completely bewildered.

The third pain point: AI Agents struggle to understand repository relationships. Each sub-repository is independent, with no machine-readable "manifest" telling the AI: what repositories this product consists of, what each is responsible for, which is editable, which is read-only reference.

The fourth pain point: high cost of cross-repository editing. To modify a spec, you must first cd into the corresponding sub-module, paths jump around, creating significant cognitive burden for collaboration.

Against this background, we first performed an "OpenSpec Monorepo Migration," lifting specs from sub-repositories to the monorepo root directory. Then on top of it, we developed MonoSpecs as a multi-repository management solution. Understanding the progressive relationship between these two steps is the key to understanding "why MonoSpecs is a further upgrade and extension of OpenSpec."

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI code assistant project with many repositories and frequent cross-language collaboration. This structural complexity forced us to make both "specifications" and "repository governance" solid. The MonoSpecs solution was gradually polished through multi-repository practice—no brilliant strokes, just a few more steps taken.

OpenSpec Solves "How Specifications Are Written and Evolved"

To clarify the relationship between the two, we need to first look at what each is responsible for.

OpenSpec is essentially a spec-driven change management workflow. Its core artifacts look like this:

openspec/
├── specs/          # Currently active capability specifications (one spec.md per capability)
├── changes/        # In-progress proposals
│   └── archive/    # Archived historical proposals
└── project.md

It answers the question: a change goes through a lifecycle of proposal, design, tasks, archive, and merges deltas into specs when archiving. This mechanism itself is unrelated to "how many repositories there are, where they are, who manages them"—it only cares about how spec files are organized.

Through a migration proposal, we lifted 82+ spec files originally scattered in hagicode-core/openspec/ to the monorepo root's openspec/, making all specs visible in one place with unified version control.

But this migration was essentially just "moving spec files," and didn't answer the more fundamental question: what sub-repositories does this monorepo actually consist of? What are the relationships between these sub-repositories? This is what MonoSpecs fills in.

MonoSpecs Solves "How Multi-Repositories Themselves Are Managed"

The core of MonoSpecs is a machine-readable manifest file: .hagicode/monospecs.yaml. It does four things that OpenSpec doesn't address at all.

The first: declare sub-repository manifest. Each repository's path, url, displayName, icon, tags, whether collapsed to "More", all written in a single YAML, clear at a glance.

The second: drive clone scripts. scripts/clone-repos.mjs reads this YAML directly, batch git clone, no longer hardcoding repository lists. Adding a new repository just requires one line in the YAML, the script needs zero changes.

The third: provide project structure context for AI/IDE. Paired with AGENTS.md, AI Agents can instantly see which repository is editable, which is reference-only, and what the tech stack is.

The fourth: anchor OpenSpec artifacts to the main repository. Specs are no longer scattered across sub-repositories, but unified in the main repository root's openspec/, keeping sub-repositories pure.

Two Layers of Meaning, Don't Get Confused

In MonoSpecs' official guide, a very confusing point is clearly pointed out: MonoSpecs actually has two layers of meaning.

One layer is the configuration system layer, referring to the .hagicode/monospecs.yaml configuration file itself, along with its accompanying loading, validation, and caching mechanisms.

The other layer is the repository type layer, referring to a "main repository + multiple sub-repositories + centralized specs" repository organization pattern. When we say a project "is a MonoSpecs project," it means it adopts this structure.

These two layers叠加 together form the complete MonoSpecs. Many people encountering it for the first time only see the YAML file layer, thinking MonoSpecs is just a configuration manifest, but its value is actually more in the second layer—a clear multi-repository collaboration paradigm. Beautiful things often aren't visible at first glance; you need to look a few more times.

Why "Upgrade and Extension"

Putting them side by side, the relationship becomes clear:

Dimension	OpenSpec	MonoSpecs
Focus	spec file content and lifecycle	repository organization structure and manifest
Core artifact	`openspec/specs/*/spec.md`	`.hagicode/monospecs.yaml`
Depends on the other	Doesn't depend on MonoSpecs	Depends on OpenSpec, reuses its `openspec/` for change management
Pain point solved	How specifications are written and evolved	How multi-repositories are declared, cloned, and understood by AI
Scope	Can be used in any repository	Designed specifically for "one main multiple sub" multi-repository structure

Fundamentally, MonoSpecs doesn't replace OpenSpec, but adds a layer of "repository governance" on top of it. Using monospecs.yaml to describe repository topology, using centralized openspec/ to decouple specs from sub-repositories, using commit_when_archive to automatically archive commits to the main repository.

If using an analogy: OpenSpec provides "change syntax," MonoSpecs provides "multi-repository semantics." The former is the premise of the latter, the latter is an extension of the former. All roads lead to Rome, just this time, the road is a bit longer than imagined.

How to Implement: Four Steps

Step 1: Establish Main Repository and Configuration File

Place the configuration file in the monorepo root directory, declaring all sub-repositories. Taking our own project as an example, the structure is roughly like this:

# .hagicode/monospecs.yaml
version: "1.0"
commit_when_archive: true

repositories:
- path: "repos/web"
  url: "https://github.com/HagiCode-org/web.git"
  displayName: "Frontend"
  tags: [frontend, react, pcode-client]

- path: "repos/hagicode-core"
  url: "https://github.com/newbe36524/pcode"
  displayName: "Backend"
  tags: [backend, dotnet, orleans]

- path: "repos/docs"
  url: "https://github.com/HagiCode-org/docs.git"
  displayName: "Docs"
  tags: [docs, astro, starlight]
  ui:
    collapseToMore: true   # Collapse to "More" in the UI

There are a few fields to pay special attention to:

path is the local path relative to the main repository root, and is also the unique key for each record.
url is the Git remote address, which the clone script relies on to pull code.
displayName / icon / tags only affect UI display and AI context, not clone behavior.
commit_when_archive: true automatically commits to the main repository when OpenSpec proposals are archived.

Step 2: Lift OpenSpec to Main Repository Root Directory

Before and after migration comparison:

Before migration (specs trapped in sub-repository)         After migration (specs centralized in main repository)
hagicode-core/                                            .  (main repository root)
└── openspec/                                             ├── .hagicode/monospecs.yaml
    └── specs/  (82+ specs)                               ├── openspec/
                                                          │   ├── specs/   (centralized management)
                                                          │   └── changes/
                                                          └── repos/
                                                              ├── hagicode-core/  (pure, no openspec)
                                                              ├── web/
                                                              └── docs/

From then on, sub-repositories no longer carry openspec/, and the main repository becomes the sole source of truth for specs. This step looks simple, but the benefits it brings are very practical—any engineer standing at the main repository root can see all specifications for the entire product system.

Step 3: Make Clone Scripts Read Configuration Instead of Hardcoding

The core logic of scripts/clone-repos.mjs is to read YAML and clone one by one:

const CONFIG_PATH = path.join(__dirname, '..', '.hagicode', 'monospecs.yaml');
// Parse repositories array
// Execute git clone <url> <path> for each entry
// Skip or git pull if target directory already exists

When adding a new repository, you only need to add one line in the YAML, without touching the script. This small change saves countless "forgot to sync repository list" disputes. After all, who wants to repeat labor?

Step 4: Backend Provides Unified MonoSpecs Service Layer

If you don't extract an abstraction layer, configuration parsing logic can easily scatter across GitAppService, ProjectAppService and other corners. HagiCode extracted IMonoSpecsService in the ClaudeHelper module, exposing a set of clear capabilities:

public interface IMonoSpecsService
{
    Task<MonoSpecsConfigDto> GetConfigAsync(string projectPath);
    Task<List<RepositoryInfoDto>> GetSubRepositoriesAsync(string projectPath);
    Task<MonoSpecsDataDto> GetMonoSpecsDataAsync(string projectPath);
    Task<MonoSpecsManagementDto> GetManagementDocumentAsync(string projectPath);
    Task<MonoSpecsManagementDto> InitializeManagementDocumentAsync(string projectPath);
    Task ValidateManagementDocumentAsync(string projectPath, UpdateMonoSpecsManagementRequestDto request);
    Task SaveManagementDocumentAsync(string projectPath, UpdateMonoSpecsManagementRequestDto request);
}

This service is responsible for loading, validating, caching configuration, and providing "initialize minimal template" capability—one-click generation of monospecs.yaml, repos/, openspec/changes/archive/, openspec/specs/ skeleton for an empty project, and automatically completing .gitignore. Caching, like memory, once remembered, next time you don't have to think hard.

Several Pitfalls in Practice

Initializing a Brand New MonoSpecs Project

After calling InitializeManagementDocumentAsync, this structure will appear on disk:

my-project/
├── .gitignore               # Added repos/ ignore rules (idempotent, won't duplicate append)
├── .hagicode/
│   └── monospecs.yaml       # Minimal template: version / commit_when_archive / repositories: []
├── openspec/
│   ├── changes/archive/
│   └── specs/
└── repos/                   # Empty directory, waiting for clone

There are a few boundaries to pay attention to here, all extracted from specs:

Idempotent: Existing repos/, openspec/ directories will be preserved and won't error.
No overwrite: If monospecs.yaml already exists and can be parsed normally, initialization won't touch it, only supplements missing .gitignore rules and openspec directories.
Reject dirty config: Existing but unparsable monospecs.yaml will be directly rejected, returning diagnosable error information, absolutely no overwrite.
No auto-scan: Initialization won't scan disk directories into repository entries on its own, repositories defaults to empty, requiring manual or UI filling.

Configuration File Location Migration Trap

Historically, monospecs.yaml was once placed in the project root, later forcibly migrated to .hagicode/monospecs.yaml. This is clearly stated in the spec:

Root directory's monospecs.yaml is no longer detected, nor as a compatibility fallback. Clone scripts only recognize .hagicode/monospecs.yaml.

So when upgrading old projects, you must manually execute mv monospecs.yaml .hagicode/monospecs.yaml, with no silent compatibility path. At first glance it seems unreasonable, but thinking carefully, this is to completely eliminate the ambiguity of "both locations might take effect"—once this ambiguity exists, troubleshooting can drive people crazy. After all, who wants to look for answers between two files?

Save Validation: Don't Write Invalid Configuration

Before writing back through SaveManagementDocumentAsync, the service performs field-level validation. Several typical rejection scenarios:

Two repository entries with duplicate path → reject, return conflicting fields.
Any entry missing path → reject, return required field error.
url is non-empty but not a valid absolute URL → reject.

Only after validation passes will it serialize to YAML and write to disk, while invalidating that project path's configuration cache, ensuring the next read gets the latest content. This step looks trivial, but can avoid countless "why didn't my configuration changes take effect" tickets. After all, when these tickets accumulate, who can bear it?

Workspace Mode vs Manual Repositories Mode

The configuration file supports two ways to derive repository lists.

One is manual repositories mode, directly listing each repository in the YAML, management document marked as editable.

The other is workspace mode, declaring a .code-workspace file, which derives the repository list. In this mode the management document is marked as read-only, prohibiting direct modification of the repository array, only modifying supported top-level fields.

Our own HagiCode Mono currently has workspace mode commented out, using manual mode. The reason is simple: manual mode allows fine-grained control of each repository's icon and tags, making UI display effects more controllable. As they say, things you can control always make you feel more at ease.

Practical Advice for AI Agents

Now with AI programming becoming increasingly popular, the MonoSpecs solution actually has an implicit value: it provides AI with a structured project map.

In multi-repository collaboration, AGENTS.md and monospecs.yaml are two key contexts for AI. The recommended workflow is:

First read monospecs.yaml to get repository topology, understanding who is editable, who is reference-only.
Then read root AGENTS.md's "Active Edit Scope" to confirm the currently allowed modification scope.
Cross-repository changes uniformly write proposals in the main repository root's openspec/changes/, don't start separate openspec in each sub-repository.

This convention lets AI stably understand the division of "main repository manages specs, sub-repositories manage code," and won't mistakenly write specs into sub-repositories—we've stumbled into this pit several times before. Actually can't blame AI, after all sub-repositories and main repositories look so similar, who can tell at a glance?

Summary

One sentence summary: OpenSpec defines "how changes are written," MonoSpecs defines "how repositories are placed."

The former is the grammatical foundation of the latter, the latter extends the former from single-repository context to multi-repository context, and converges repository topology, clone process, AI context, and specs ownership in one go with a YAML manifest. This is the true meaning of "MonoSpecs is a further upgrade and extension of OpenSpec"—not replacement, but adding a layer of multi-repository semantics on top of it.

If you're also working on a multi-repository product of similar scale, consider whether these two layers are both laid out properly. No matter how beautifully specifications are written, without clear repository governance supporting them, eventually it will all become a chaotic mess......

References

HagiCode Official Website
HagiCode-org/site GitHub Repository
OpenSpec Workflow Documentation
MonoSpecs related specs: monospecs-guide, monospecs-repository-config, monospec-config-management

Summary

Surrounding "What is MonoSpecs: Why It's a Further Upgrade and Extension of OpenSpec," a more prudent advancement approach is to first gradually run through key configurations, dependency boundaries, and implementation paths, then supplement optimization details.

Once goals, steps, and acceptance criteria are clear, such solutions can usually more smoothly enter actual delivery.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-20-monospecs-openspec-upgrade-and-extension%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Prompts for AI Commits in HagiCode: Design Rationale and Implementation Breakdown

Hagicode — Sat, 20 Jun 2026 04:29:48 +0000

Prompts for AI Commits in HagiCode: Design Rationale and Implementation Breakdown

When you dump a bunch of messy changes to AI and ask it to help you commit, what exactly is the prompt being sent to the model behind the scenes? Why is the prompt written that way? This article breaks down the actual prompt that drives "AI commits" in HagiCode for you to see.

Background

Using AI to assist with development—after a full day of coding, it can be quite exhausting. You've accumulated a pile of uncommitted changes: config files, documentation, business logic, test cases all mixed together—just looking at it gives you a headache. Manually grouping them, hand-writing commit messages that conform to standards, then switching branches and pushing—these "cleanup tasks" alone can eat up half an hour.

Naturally, this gives rise to a demand—can we just throw all uncommitted changes at AI at once, let it analyze, group, write messages, and even directly commit + push?

The idea is good, but there are plenty of pitfalls along the way. AI might only change --author without changing Committer, resulting in the correct author but wrong committer in commit history—a jarring inconsistency. It might write flashy messages that don't align with your repository's style at all. It might arbitrarily switch to the main branch and mess things up. It might miss Co-Authored-By or recklessly add Signed-off-by, triggering compliance issues.

These pitfalls are lessons learned the hard way. To address these pain points, we've made "AI commit" a parameterized Agent task contract. What this contract looks like and why it's designed this way is what this article aims to clarify.

About HagiCode

The solution shared in this article comes from our practice in the HagiCode project. HagiCode is an AI code assistant focused on developer workflows, turning daily tasks like Git commits, code reviews, and build deployments into AI-participated tasks. The prompt system broken down below is the one actually running in HagiCode's backend. Ultimately, it's just about handing off those tedious "cleanup tasks" to AI.

The True Form of Prompts: Templates Plus Metadata, Not a Hardcoded String

Many people think "prompts" are just a piece of hardcoded natural language to throw at a model. But HagiCode's approach is completely different.

The actual prompt driving "AI commits" is called auto-compose-commit, corresponding to PromptScenario.AutoComposeCommit in the code. It's located under repos/hagicode-core/src/PCode.Web/Resources/Prompts/ with this structure:

Resources/Prompts/
├── auto-compose-commit.en-US.hbs     # English Handlebars template
├── auto-compose-commit.en-US.json    # English metadata (parameter schema, version, tags)
├── auto-compose-commit.zh-CN.hbs     # Chinese template
└── auto-compose-commit.zh-CN.json    # Chinese metadata

In other words, a prompt is a combination of one Handlebars template + one JSON metadata, flattened into multiple sets by locale.

Why split it this way? There are several considerations behind it.

First, metadata decoupled from prompt body. JSON describes the parameter schema—parameter names, types, whether required, default values. .hbs only handles "how to say it." This way, the frontend can automatically render the correct input form based on JSON without knowing the template content: Git identity selector, Co-Authored-By mode, target branch strategy, whether to push... these controls are all driven by JSON.

Second, multi-language flattened, not using i18n keys for translation. Each locale has a complete set of .hbs + .json, avoiding "translation key drift." Different languages don't just substitute words—grouping examples and command examples can also be localized. Commit habits in Chinese and English repositories are inherently different; forcing them into one template then translating feels awkward.

Third, migrating from Scriban to Handlebars was for performance. HandlebarsTemplateRenderer chose Handlebars.Net because it can "compile templates directly to IL bytecode," which is much faster than interpretation. During migration, an interesting compatibility fix was made: replacing True/False with true/false in render results to match old Scriban boolean output habits—without paying attention to such details, old tests would all fail.

Five Key Decisions Behind This Prompt Structure

Looking at auto-compose-commit.zh-CN.hbs, the skeleton roughly is:

Non-interactive mode instructions
├── <task>            Task definition: analyze changes, intelligent grouping, multiple commits
├── <context>         Context: projectPath + push control + target branch control
├── <working_directory>
├── <git_profile>     Identity: Author plus Committer dual-write
├── <tools>           Tool whitelist
├── <requirements>    Hard requirements (branch, grouping, Co-Authored-By, Signed-off-by, Conventional Commits)
├── <historical_format_analysis>  Historical consistency
├── <constraints>     Constraints (prohibit reset, ignore .gitignore)
├── <workflow>        Step-by-step execution flow
├── <output_format>   Strict `---` separated output
└── <final_instruction>

Below, let's expand on five points that best reflect the design intent.

Decision One: Execute Directly, Don't Just Generate a Plan

The prompt repeatedly emphasizes one sentence: Use Git commands directly to execute each commit, don't return a plan, operate directly.

This is the fundamental difference between "Auto Compose Commit" and earlier solutions. The early ai-git-commit-message-generator (corresponding to the ai-commit-message-generation spec in OpenSpec) only did one thing: call a POST /api/git/generate-commit-message, return a commit message string, and let the user manually commit the rest.

But auto-compose-commit is different. It's an Agent automated task. The model must call Bash(git:*) tools itself and run the full chain of add → commit → push. This difference determines the tone of the entire prompt—it can't just describe "what kind of message to write," but also specify "what workflow to follow, what tools to use, and what to do when errors occur."

Decision Two: Why Git Identity is So Verbose

There's a large section in <git_profile> and <requirements> explaining Author versus Committer, which looks redundant at first glance:

- `--author="Name <email>"` only modifies Author
- `git -c user.name="Name" -c user.email="email" commit ...` only modifies Committer for this command
- For each generated commit, you must set both Author and Committer to the selected identity
- Preferred command form:
  git -c user.name="..." -c user.email="..." commit --author="... <...>" ...

This actually comes from real pitfalls learned. Git commits have two identity fields. Models easily only change --author, leaving Committer as the global config identity. In commit history, "author is correct but committer is wrong"—visually jarring. So the prompt directly provides the preferred command template and requires the model to self-check using git log --format=fuller -1.

By analogy, this is like shipping a package—"sender" and "actual handler" are two different forms. You only write your name on one form, the other still has the company name printed—the package ships, but records don't match, ultimately feeling awkward.

Decision Three: Grouping Decision Tree Plus Historical Consistency

Models excel at "free improvisation," but in commit grouping, this is often a disaster. So the prompt provides a clear decision tree: config files as one group, docs as another, same-module code changes merged, cross-module changes handled case-by-case. It also includes positive examples, like src/auth/login.ts plus auth.service.ts should go into the same commit.

More critical is the <historical_format_analysis> section. It requires the model to:

Use git log -n 15 --pretty=format:"%H|%s|%b%n---%n" to get recent commit history

Analyze structural patterns, language patterns, common types, special formats

Generate commit messages following detected patterns

In other words, the model can't write however it wants—it must align with the target repository's existing style first. HagiCode Mono main repo uses English + Conventional Commits, certain sub-repos use Chinese paragraph style—AI must follow local customs. This capability corresponds to archived proposal 2026-02-23-auto-commit-compose-history-consistency-optimization, an optimization added later. After all, nobody wants their commit history to look like a hodgepodge.

Decision Four: Conditional Rendering for Co-Authored-By and Signed-off-by

The prompt has many nested {{#if}} statements, deciding whether to add trailers based on runtime parameters:

When coAuthoredByIsNone, don't add Co-Authored-By at all
When coAuthoredByIsCustom, use the user-provided custom trailer
When signedOffByEnabled plus gitProfileName, add Signed-off-by; missing identity must error, not fabricate one

Trailers involve attribution and compliance (DCO sign-off), must be explicitly controlled by users, never left to model discretion. HagiCode has implemented proposals like git-commit-coauthor-standardization and ai-commit-consent-management to draw these boundaries clearly. Such things are better strict than vague.

Decision Five: `---` Separated Output Contract

<output_format> specifies that each return must use --- to separate multiple commit blocks, with hard-coded format:

---
Commit 1: {hash}
{message}
---
Commit 2: {hash}
{message}
---

This isn't for looks. A model might produce N commits in one task—the backend relies on this separator to parse each commit's hash and message, then pass them back to frontend for display. Once the output protocol loosens, backend parsing crashes. So the --- rule is emphasized twice in <output_format> and <final_instruction>—important things should indeed be said three times.

How Prompts Are Assembled and Delivered

Looking at templates isn't enough; we need to know how they run.

Loading and Rendering

The backend registers two singletons in PCodeClaudeHelperModule:

// Register prompt loader: find corresponding .json and .hbs by scenario + locale
context.Services.AddSingleton<IPromptLoader, FilePromptLoaderV2>();
// Register Handlebars renderer: compile templates to IL and cache
context.Services.AddSingleton<HandlebarsTemplateRenderer>(...);

FilePromptLoaderV2 gets the template body, then hands it to HandlebarsTemplateRenderer.Render(template, parameters) for rendering. The renderer's core logic roughly is:

public string Render(string template, IDictionary<string, object> parameters)
{
    // Cache by SHA256 of template content, avoid recompiling each commit
    var compiledTemplate = GetOrCompileTemplate(template);
    var rendered = compiledTemplate(parameters ?? new Dictionary<string, object>());
    // Compatible with old Scriban boolean output habit
    rendered = rendered.Replace("True", "true").Replace("False", "false");
    return rendered;
}

Compilation results cached by content hash is key for performance. Commit operations can trigger frequently—recompiling IL each time is unbearable.

Where Do Parameters Come From

JSON metadata declares a dozen parameters: projectPath, needPush, targetBranchMode, gitProfileName, gitProfileEmail, signedOffByEnabled, coAuthoredBy*, etc. These parameters are collected by the frontend "AI commit drawer," injected into backend via AutoTask channel, then routed by FilePromptProvider to this template set via PromptScenario.AutoComposeCommit.

Three-State Handling for Branch Strategy

targetBranchMode determines whether the model touches branches before commit, a three-state:

Mode	Behavior
`current`	Commit in place, don't touch branches
`new-custom`	Create new branch from current branch using user-provided `targetBranchName`
`ai-generated-new`	Model generates kebab-case branch name based on changes, add stable suffix if conflicts

The prompt explicitly says "don't switch to any other existing branch," preventing the model from arbitrarily switching to main branch to commit. This capability corresponds to the auto-branch-switch-on-commit proposal. After all, once main branch is messed up, rolling back is a messy affair.

A Complete Rendering Example

Suppose the user selects in frontend: stay on current branch, need push, enable Signed-off-by, disable Co-Authored-By, Git identity is newbe <newbe@newbe.pro>.

Then the <git_profile> section renders to:

<git_profile>
Use the following Git identity in all generated commits:
- Selected name: newbe
- Selected email: newbe@newbe.pro
...
- This run also requires Git standard sign-off trailer, so prefer using `git ... commit --author=... --signoff ...`
</git_profile>

<requirements> keeps only the "Co-Authored-By disabled for this run" branch, and <workflow> gives commands like:

# Note -c sets Committer, --author sets Author, --signoff adds DCO trailer
git -c user.name="newbe" -c user.email="newbe@newbe.pro" commit \
    --author="newbe <newbe@newbe.pro>" --signoff -m "type(scope): subject"

Engineering Practices for Template Maintenance

HagiCode provides a full set of engineering safeguards for these .hbs templates—not just writing them and calling it done.

First, snapshot tests. Test directory has BuildMessage_enUS.verified.txt, BuildMessage_zhCN.verified.txt and other verified snapshots—any rendering difference in templates is caught by tests. Change one character and you must update snapshots, preventing prompts from silently drifting.

Second, formatting scripts. cleanup-prompts.py --fix cleans trailing whitespace, collapses excess blank lines—CI check fails and blocks PR directly if not passing.

Third, parameter validation. Each scenario's required parameters, default values, types have dedicated test coverage—if template uses {{newParam}} but JSON doesn't declare it, tests fail.

Fourth, snapshot layering: Snapshots/Rendered/ stores render results, Snapshots/Scenarios/ stores scenario metadata, ensuring consistency between templates, metadata, and render products.

Here's a practical pitfall reminder. If you want to add new parameters or branches to this prompt system, four things must be done synchronously:

Use {{newParam}} in template (.hbs)
Declare schema in parameters array in metadata (.json)
Update corresponding .verified.txt in snapshot tests
Frontend form generates input controls based on new JSON parameters and passes through API

Missing any link either means empty parameters during rendering, red snapshot tests, or frontend unable to configure. This "four-way sync" constraint looks annoying, but for maintainability, it must be so.

Why Prompts Are So "Verbose"

Looking back at this prompt, you'll find it unusually verbose—identity, trailers, output format repeatedly emphasized. This is actually deliberate.

Models in Agent mode are particularly prone to "acting on their own," so hard constraints must be scattered and repeatedly declared across <requirements>, <workflow>, <final_instruction> to reduce probability of missed execution. This is like onboarding new people—say important things three times, not because they're slow, but because too many things compete for attention.

In non-interactive mode (CI/CD, automation), models can't ask users questions, so the prompt explicitly states at the start "prohibit using AskUserQuestion, use defaults for missing info and record assumptions," ensuring it runs unattended.

Once output contract loosens, backend parsing crashes—so --- separation rule is emphasized twice. Important things do indeed need to be said three times.

References

HagiCode official website
HagiCode GitHub repository
Conventional Commits specification: conventionalcommits.org
Handlebars.Net: github.com/Handlebars-Net/Handlebars.Net
Git DCO (Developer Certificate of Origin): developercertificate.org

Summary

Returning to the theme "Prompts for AI Commits in HagiCode: Design Rationale and Implementation Breakdown," what's worth repeatedly confirming isn't scattered techniques, but whether constraints, implementation boundaries, and engineering trade-offs are clearly seen.

Once you distill the judgment basis in this article into stable checklist items, you can make reliable decisions faster when facing similar problems.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-20-hagicode-ai-commit-prompt-design%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice

Hagicode — Fri, 19 Jun 2026 01:50:20 +0000

Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice

This article discusses how to switch Reasonix 1.x, a local ACP CLI provider, to DeepSeek V4 in HagiCode. The focus isn't really on "getting it in," but rather on the semantic changes from Reasonix 0.x to 1.x—startup parameters were cut down to just one -model, credentials and policies moved to reasonix.toml. Let's walk through the pitfalls encountered and the verification path, bit by bit.

Background

Recently someone asked a pretty specific question: how to integrate Reasonix 1.x version to use DeepSeek V4 in HagiCode.

At first glance it looked like a configuration question, but digging into the code revealed it's actually a CLI semantic migration problem. Reasonix is a local ACP (Agent Communication Protocol) CLI within HagiCode's multi-Agent Provider system. Its position in HagiCode's three-tier architecture is clear:

HagiCode.Libs — ReasonixProvider, ReasonixOptions, wrapping reasonix acp process startup, ACP handshake, streaming notification mapping.
hagicode-core — ReasonixCliProvider thin adapter, AIProviderType.ReasonixCli = 12, ReasonixGrain, Hero parameter mapping, health monitoring.
web — OpenAPI types, visual mapping, Hero configuration forms, multilingual copy.

The entire integration chain is already implemented in the archived proposal openspec/changes/archive/2026-06-06-integrate-reasonix-agent-provider. So the question isn't "how to get Reasonix into the system" anymore, but "once it's in, how to switch the model to DeepSeek V4".

The key turning point is: Reasonix 1.x and 0.x have fundamentally different ACP bootstrap semantics. This change directly determines how you configure DeepSeek V4. After all, once semantics change, even if the surface looks similar, it's a different beast entirely.

I'll leave that hanging: to untangle this complexity of multiple providers and multiple models, HagiCode adopted a "field preservation, semantic migration" design at the Reasonix adaptation layer. I'll explain exactly why this trade-off was chosen later.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project.

HagiCode is an AI coding assistant project supporting multiple local/remote Agent Providers. Code is open sourced at HagiCode-org/site.

Analysis

1.x Cut Startup Parameters to Just One

Look directly at ReasonixProvider.BuildCommandArguments:

internal virtual IReadOnlyList<string> BuildCommandArguments(ReasonixOptions options)
{
    var arguments = new List<string> { "acp" };
    // Reasonix 1.x reduced ACP bootstrap to a transport-scoped provider selector.
    AppendOption(arguments, "-model", options.Model);
    foreach (var argument in NormalizeExtraArguments(options.ExtraArguments))
        arguments.Add(argument);
    return arguments;
}

That comment is the key: 1.x condensed ACP bootstrap to a "transport-scoped provider selector." In plain English—the only flag still meaningful at startup is -model.

Those legacy flags from the 0.x era are explicitly filtered out:

private static readonly HashSet<string> FilteredBootstrapFlags = new(StringComparer.OrdinalIgnoreCase)
{
    "-model", "-m", "--model",
    "-dir", "--dir",
    "-effort", "--effort",
    "-budget", "--budget",
    "-transcript", "--transcript",
    "-mcp", "--mcp",
    "-mcp-prefix", "--mcp-prefix",
    "-yolo", "--yolo",
    "--dangerously-skip-permissions",
    "--no-proxy"
};

Unit tests directly prove this. Pass in a bunch of legacy flags, the command line comes out clean, no errors, just silently dropped:

arguments.ShouldBe(
[
    "acp",
    "-model", "deepseek-v4-flash"
]);

ReasonixOptions Fields Still There, But Semantics Changed

Here's an interesting design choice. Fields like Effort, BudgetUsd, TranscriptPath, EnableYolo, McpServerSpecs, McpPrefix in ReasonixOptions are all preserved, but each comment honestly states "Reasonix 1.x ACP no longer accepts ... so this value is currently ignored".

This is a classic field preservation, semantic migration pattern: caller contracts aren't broken (0.x code still compiles, still passes values), but at runtime these values are silently dropped. Policy-type things (permissions, MCP plugins, proxy) are required to move to reasonix.toml.

To put it another way, it's like your original light switch is still on the wall, but the renovation guy changed the wiring. Now the switch is just decoration, the real lighting control moved to the smart home panel. The switch looks unchanged, pressing it doesn't error out, but the light just doesn't turn on.

So the core action for integrating DeepSeek V4 is actually just one sentence: pass the model id through the -model selector, configure credentials/endpoint in reasonix.toml.

How DeepSeek V4 Gets In

In HagiCode's tests and README, the DeepSeek series uses the standard pattern through the Model field:

var reasonixOptions = new ReasonixOptions
{
    WorkingDirectory = "/path/to/repo",
    Model = "deepseek-flash",
    SessionId = "reasonix-session-123"
};

Tests repeatedly show Model = "deepseek-v4-flash", corresponding to the generated command line reasonix acp -model deepseek-v4-flash. The specific model id (deepseek-v4-flash, deepseek-flash, etc.) should follow the Reasonix 1.x version you installed and the provider aliases registered in reasonix.toml—after all, whether an alias is real or not, Reasonix knows best.

Working Directory and Session Recovery Go Through ACP, Not CLI Flags

This is the second semantic change in 1.x, easy to get confused about. In 0.x you used --dir to specify working directory, in 1.x it changed to using session/new / session/load within the ACP protocol:

var sessionHandle = await sessionClient.StartSessionAsync(
    workingDirectory,
    options.SessionId,
    model: null,   // Model selection completely determined by startup -model
    startupCts.Token);

Note that the model parameter in StartSessionAsync passes null—model selection is completely determined by -model at startup, session level no longer overrides the model. SessionId is still a provider-native continuity hint, used only to resume sessions.

Solution

Putting the above analysis together into an executable path, let's walk through four steps.

Step 1: Install Reasonix CLI

Reasonix is a locally installed, IsPubliclyInstallable: false provider, can't be installed via npm publicly. First put the reasonix executable in PATH. After installing, verify with HagiCode.Libs' built-in console:

# Run Ping scenario, execute reasonix acp handshake and report version
dotnet run --project src/HagiCode.Libs.Reasonix.Console -- --test-provider reasonix

If handshake fails, it's usually one of two cases: either PATH didn't find reasonix, or reasonix.toml isn't configured. There aren't really any other reasons.

Step 2: Configure DeepSeek V4 Credentials in reasonix.toml

1.x no longer accepts startup flags like --api-key, --base-url. Model provider endpoint, API key, proxy policies all need to be written to reasonix.toml. Configuration roughly includes:

DeepSeek V4 API endpoint
DeepSeek API key
Aliases you want to expose to the -model selector (like deepseek-v4-flash)

Specific field names should follow the documentation of your installed Reasonix version. HagiCode's side only cares about passing through -model deepseek-v4-flash, how this alias resolves to the actual model is Reasonix's business—responsibility boundaries are clearly drawn, don't cross lines.

Step 3: Configure HagiCode's ProviderConfiguration

The resolution priority in backend ReasonixCliProvider.ResolveModel is: request.Model takes priority, otherwise fall back to _config.Model:

private string? ResolveModel(AIRequest request)
{
    var model = string.IsNullOrWhiteSpace(request.Model)
        ? _config.Model
        : request.Model;
    return string.IsNullOrWhiteSpace(model) ? null : model.Trim();
}

So in appsettings or runtime config, set the provider's Model to DeepSeek V4's alias:

{
  "AIProvider": {
    "Providers": {
      "ReasonixCli": {
        "Type": "ReasonixCli",
        "Model": "deepseek-v4-flash",
        "Settings": {}
      }
    }
  }
}

Here's a trap that's easy to step in: Settings can only hold keys within the whitelist:

private static readonly IReadOnlyList<string> SupportedSettingKeys =
[
    "effort", "budgetUsd", "transcriptPath",
    "enableYolo", "arguments", "startupTimeoutMs", "reasoning"
];

ValidateConfigurationOverrides will directly reject keys outside the whitelist. And most of these keys are ignored in 1.x (corresponding to those ignored fields in ReasonixOptions), so never stuff DeepSeek credentials into Settings, that's not where they belong, credentials go to reasonix.toml.

Step 4: Use Console for End-to-End Verification

After configuration, run the full suite with Reasonix's dedicated console, explicitly specifying the model as DeepSeek V4:

# Default suite: four scenarios - Ping / Simple Prompt / Complex Prompt / Session Resume
dotnet run --project src/HagiCode.Libs.Reasonix.Console -- \
  --test-provider-full --model deepseek-v4-flash --repo .

If all four scenarios pass green, the model selector, ACP handshake, streaming notifications, session recovery—the entire chain is connected. Green means peace of mind.

Practice

How to Fill the Hero Configuration Form in Frontend

If you go through HagiCode's Hero career UI instead of directly modifying appsettings, after selecting Reasonix in HeroCliEquipmentForm, the form fields are:

binary: default reasonix
model: fill deepseek-v4-flash (key field for switching to DeepSeek V4)
effort: none / low / medium / high (ignored in 1.x, but UI still keeps it)
budgetUsd: number (ignored in 1.x)
transcriptPath: text (ignored in 1.x)
enableYolo: boolean (ignored in 1.x, permissions go to toml)
arguments: extra parameters passed through to ACP
startupTimeoutMs: default 15000

Actually, only the model field affects DeepSeek V4 behavior, the rest are just decoration under 1.x. This is also HagiCode's "field preservation, semantic migration" design reflected in the UI—the form doesn't break old user habits, but the fields that actually take effect are converged.

Session Binding and Recovery

ReasonixCliProvider uses ConcurrentDictionary<string, string> to maintain session bindings, binding key is calculated from sessionId, working directory, executable path, and model:

var bindingKey = NormalizedAcpCliAdapter.BuildBindingKey(
    effectiveRequest.CessionId,
    options.WorkingDirectory,
    options.ExecutablePath,
    options.Model);

This means if you switch models mid-session in the same session, the binding key changes and it's treated as a new session. So after integrating DeepSeek V4, keep the model alias stable throughout the session lifecycle, otherwise resume will break. I learned this the hard way through actual testing—blood and tears lesson, still remember the taste.

Monitoring and Degradation

Reasonix uses the Provider strategy (not Grain strategy) in AgentCliMonitoringRegistry, since it might not be installed:

new AgentCliMonitoringDescriptor
{
    CliId = "reasonix",
    DisplayName = "Reasonix",
    ProviderType = AIProviderType.ReasonixCli,
    Strategy = Provider, // ping-based, via PATH discovery
    ExecutableCandidates = ["reasonix"]
}

Frontend health checks show whether Reasonix is available. If reasonix isn't in PATH, the UI gracefully degrades to "unavailable"—this logic is built in, no need to worry about it yourself.

Several Practical Points to Note

Authenticity of Model Aliases: deepseek-v4-flash must be a real alias registered in reasonix.toml, otherwise ACP handshake passes but sending prompts still fails. Verify with console first before going to Hero, don't cut corners.
Don't Use arguments to Pass Legacy Flags: NormalizeExtraArguments filters out --effort, --budget, etc., passing them is futile, wasted effort.
Credentials Only in toml: API key, endpoint, proxy, MCP plugins all go in reasonix.toml, HagiCode's side Settings whitelist doesn't have these fields at all.
startupTimeoutMs is Adjustable: If DeepSeek V4 cold start is slow, raise startupTimeoutMs from default 15000, this field is recognized in 1.x.
Economic System Maps to Claude Bucket: Frontend resolveEconomicSystemByExecutorType maps Reasonix to the 'claude' bucket, purely for display, doesn't affect billing.

A Minimal Verification Path

If you just want to confirm DeepSeek V4 works quickly without touching Hero UI:

Install reasonix, configure reasonix.toml (DeepSeek endpoint + key + alias)
Set ReasonixCli.Model = "deepseek-v4-flash" in appsettings
Run dotnet run --project src/HagiCode.Libs.Reasonix.Console -- --test-provider-full --model deepseek-v4-flash
All four scenarios green, integration complete

Summary

Returning to the original question—"how to integrate Reasonix 1.x to use DeepSeek v4".

The answer is actually just one sentence: pass the model alias through the -model selector, configure credentials and policies in reasonix.toml, don't count on CLI flags.

Behind that one sentence is a pretty clean semantic convergence by Reasonix 1.x: startup parameters cut to just -model, working directory and session recovery moved into ACP protocol, policies all sunk into toml. HagiCode's adaptation layer didn't fight this change head-on, but chose the gentle "field preservation, semantic migration" route—old code still compiles, still passes values, silently ignored at runtime, converging effective switches to just -model.

The benefit of this trade-off is smooth migration, the cost is documentation needs to be clear—which is why this article exists. Just remember three things:

Models go through -model, DeepSeek V4 is -model deepseek-v4-flash
Credentials go to toml, don't stuff them into Settings
Don't switch models mid-session, binding key changes, resume breaks

HagiCode chose to design the Reasonix adaptation layer this way essentially because it needs to accommodate multiple providers, multiple model versions, multiple deployment forms. This complexity of multiple languages, multiple platforms is exactly why we repeatedly polish the provider adaptation strategy in HagiCode.

References

Reasonix Provider implementation: repos/Hagicode.Libs/src/HagiCode.Libs.Providers/Reasonix/ReasonixProvider.cs
Reasonix Options field semantics: repos/Hagicode.Libs/src/HagiCode.Libs.Providers/Reasonix/ReasonixOptions.cs
Backend thin adapter: repos/hagicode-core/src/PCode.ClaudeHelper/AI/Providers/ReasonixCliProvider.cs
Integration proposal archive: openspec/changes/archive/2026-06-06-integrate-reasonix-agent-provider
Backend spec: openspec/specs/reasonix-backend-integration/spec.md
Unit tests (including deepseek-v4-flash cases): repos/Hagicode.Libs/tests/HagiCode.Libs.Providers.Tests/ReasonixProviderTests.cs
HagiCode official site: hagicode.com

Summary

Around "Integrating Reasonix 1.x with DeepSeek V4: ACP Model Selector Integration in Practice," a more solid approach is to first gradually get key configurations, dependency boundaries, and implementation paths working, then fill in optimization details.

When goals, steps, and acceptance criteria are clear, this type of solution usually flows more smoothly into actual delivery.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-19-reasonix-1x-deepseek-v4-acp-integration%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

Pi Agent Integration: Message Parsing, Retry, and Cancellation

Hagicode — Fri, 19 Jun 2026 01:12:00 +0000

Pi Agent Integration: Message Parsing, Retry, and Cancellation

When integrating a CLI-based AI agent, you can't avoid three things: how to translate its private event stream into stable messages, who's responsible for retry after failures, and how to cleanly stop the process when users click cancel. These three things essentially boil down to "clarifying responsibilities"—it's simple in theory, but you only realize how deep the water is when you actually do it.

Background

Recently, I've been working on an AI coding assistant project, and one of the agents to integrate is pi. It's a TUI/CLI coding agent that outputs JSON events line by line to stdout when running. Sounds simple—spawn the process, read output, parse it—but when you actually start, you realize "integrating an agent CLI" is completely different from "integrating a regular CLI."

With a regular CLI, you read stdout, get an exit code, and that's it. But agent CLIs have three particularly headache-inducing characteristics:

First, its event stream is a private protocol. turn_start, session, message_update, message_end, turn_end, agent_end—these are defined by pi itself, not any industry standard. Every upper layer that wants to consume it has to handle it separately, effectively leaking pi's internal details everywhere. It's like looking at someone from a distance—you think you see them clearly, but you're only seeing the side they want to show you.

Second, its failure semantics are particularly ambiguous. The agent might encounter network jitter, model rate limiting, or process crashes while running. Should it retry? Where to retry? Will retry mess up the session state that's already half-output? This is an architectural decision, not something you can solve by casually writing a for loop.

Third, it's long-running and interruptible. A single turn might run for tens of seconds or even minutes, and users might want to cancel at any time. When canceled, the process can't become an orphan, tool calls can't be left half-finished, and already output content can't be lost. The water here is much deeper than imagined.

To solve these pain points, we spent some time straightening out the integration path. I'll get into specifics later, but here's a spoiler: the real difficulty isn't in "spawning the process," but in "clarifying responsibilities."

About HagiCode

The solution shared in this article comes from the HagiCode project—an AI coding assistant that supports multiple models and multiple agent CLI backends. GitHub repository: HagiCode-org/site, feel free to star it. All the code and all the pitfalls mentioned below are actually running in this project. Writing this out is just leaving myself a memory.

Overall Layering

HagiCode splits AI capability integration into two layers:

The bottom layer is Hagicode.Libs, providing reusable provider primitives ICliProvider<TOptions>, specifically responsible for "spawning a CLI agent and normalizing its output into a shared message stream."
The upper layer is hagicode-core, providing project-level thin adapters IAIProvider, responsible for "translating business requests into provider parameters, consuming shared message streams, and exposing unified streaming chunks externally."

Pi's integration follows this path. The bottom layer PiProvider spawns the pi process, reads the JSON event stream, and normalizes it into shared messages; the upper layer PiCliProvider translates AIRequest into PiOptions, consumes CliMessage, and outputs AIStreamingChunk.

These three things—message parsing, retry, cancellation—fall into three different places: PiJsonEventMapper, a seemingly strange archiving proposal, and CliProcessManager. Let's talk about each one.

Message Parsing: Converting Pi's Private Events to Shared Messages

pi outputs JSON events line by line under --mode json --print. This event set is private to pi and must not be leaked directly to upper layers, otherwise every consumer would couple to pi's internal details, and the entire project would follow pi's upgrades when its event structure changes. This kind of leakage is similar to writing your thoughts on your face—others find it tiring to look at, and you're not necessarily comfortable either.

We use PiJsonEventMapper as a translation layer to normalize pi's events into shared CliMessage. CliMessage is defined in HagiCode.Libs.Core/Transport/CliMessage.cs with a very simple structure—just a (Type, Content) record. The mapping relationship is roughly as follows:

pi event	shared message	purpose
`session`	`session.started` / `session.resumed`	session lifecycle
`message_update` (text type)	`assistant`	streaming body incremental
`message_update` (thinking type)	`assistant.thought`	thought chain
`message_update` (tool type)	`tool.call` / `tool.update`	tool call initiation
`message_end` / `turn_end` (toolResult)	`tool.completed` / `tool.failed`	tool result
`turn_end` / `agent_end`	`terminal.completed`	current turn end
non-zero exit / parse failure	`terminal.failed`	terminal state failure

This table is just a quick reference, but it contains two key techniques that were figured out after stumbling into pitfalls—worth expanding on.

Technique One: Converting Cumulative Snapshot to Delta

This is the easiest place to crash. pi's message_update event doesn't send increments, but cumulative full text—every time a token comes, it resends the "complete text so far."

If you forward received content directly to the frontend, users will see content repeated: the first is "you", the second is "hello", the third is "hello,", the fourth is "hello, wor"... The frontend will think these are four independent outputs. Repetition is fresh the first time you see it, but boring the tenth time.

The solution is prefix comparison to calculate the true delta:

// Key: pi sends cumulative snapshot, not increment
// Use prefix comparison to extract the delta, otherwise frontend sees repeated content
if (text.StartsWith(_lastAssistantTextSnapshot, StringComparison.Ordinal))
{
    var delta = text[_lastAssistantTextSnapshot.Length..];
    _lastAssistantTextSnapshot = text;
    return delta.Length == 0 ? null : delta;
}

There's another hidden pitfall here: cross-turn prefix replay. After tool calls end and the assistant continues speaking, pi will replay that previous text from the beginning again. If you only keep a global snapshot, you'll treat the replayed content as increments, causing repetition after tool calls. PiProviderTests has a dedicated test case ExecuteAsync_deduplicates_replayed_assistant_prefix_after_tool_turns covering this scenario. In other words, snapshots before and after tool calls need aligned processing, not independent handling.

Technique Two: Buffer Thinking Until Turn End

Thought chains (thinking) can't be output as soon as each token is received. pi stuffs a bunch of thinking fragments in the middle of tool calls. If forwarded in real time, the stream order becomes a mess—一会儿是 assistant 正文，一会儿是思考碎片，一会儿又是 tool.call。Does this make sense? It doesn't really, just adding confusion.

Our approach: when receiving thinking events, first put them in BufferThinkingSnapshot for temporary storage, and wait until message_end or turn_end with stopReason != "toolUse", then uniformly DrainBufferedThinkingMessages. This way, thinking fragments in the middle of tool calls won't pollute the main stream, and the complete thought process is given all at once when the turn ends.

Fault Tolerance: Bad Lines Can't Crash the Stream

Agent CLI isn't the ideal system from textbooks. It occasionally spits out a non-JSON line, or a JSON without a type field. If you throw an exception here, the entire stream dies and users see nothing. The real world isn't always perfect—who can guarantee every line is well-behaved?

Our strategy: any line that fails to parse doesn't interrupt the stream, but is collected into _invalidOutputLines. After the process ends, in Complete(), these "bad lines" are spliced into the diagnostic text of terminal.failed. This way, when users see errors, they can directly see what garbage pi actually output, not a dry "parse error."

Retry: If Provider Layer Doesn't Do It, Who Does?

This is the easiest pitfall in the entire integration. Intuitively "integrating a CLI should include retry," but HagiCode in an archiving proposal actively removed all automatic retry from the provider layer. The proposal is called remove-provider-auto-retry-support.

Why No Automatic Retry

The proposal background is written very bluntly. Retry logic was originally scattered in two places: one copy in Hagicode.Libs (OpenCode-style fresh-runtime replay), another in hagicode-core (ProviderErrorAutoRetryCoordinator). Both sides did their own thing, making "whether to retry" a hidden implicit behavior inside the provider, secretly changing failure timing, session continuation method, and chat state flow.

Think about it and your head hurts: user sends a message, provider internally retries three times itself, first two fail, third succeeds. Upper layer has no idea what happened in the middle, session state, token counting, UI progress all don't match. This kind of implicit behavior is chronic poison in architecture.

So the boundary was converged into one sentence:

provider converges to single-attempt semantics, caller needs to treat non-retry state as normal single-execution result.

What Does This Mean for PiProvider

In code, it's three things:

PiOptions has no retry-related fields—no maxAttempts, no retryDelay, no retryClassifier.
ExecuteAsync ends after one pi process run completes, failures directly give terminal.failed.
Classifiers previously serving automatic retry (ClaudeCodeRetryableTerminalFailureClassifier, CodexRetryableTerminalFailureClassifier, etc.)—if they purely served automatic retry—are all removed from the active path.

But please note, retry capability hasn't disappeared, just moved up. The proposal explicitly writes "leaving a stable boundary for higher layers to uniformly take over retry later." The DTO for providerErrorAutoRetry configuration item, normalization, serialization, frontend settings page round-trip are all preserved, it just no longer drives provider execution. Some things aren't really unwanted, just kept in a different way.

What If You Want to Retry

If you want to add retry on top of pi, the correct approach is to do it at the caller of PiCliProvider—for example, your session orchestration layer (in HagiCode it's Orleans's SessionGrain, frontend might be chat orchestration layer). After getting terminal.failed, judge yourself whether it's retryable, decide delay and count yourself, then send ExecuteAsync again.

A minimal viable pattern looks like this:

// Retry logic at caller, don't stuff back into PiProvider
// Otherwise breaks the "single-attempt" boundary just established by provider
async Task<AIResponse> ExecuteWithRetryAsync(AIRequest req, int maxAttempts, CancellationToken ct)
{
    for (var attempt = 1; ; attempt++)
    {
        var response = await provider.ExecuteAsync(req, ct);

        // Return on success or reaching limit
        if (response.FinishReason != FinishReason.Unknown || attempt >= maxAttempts)
            return response;

        // Only retry retryable terminal failures (network, 5xx, process crash)
        // model rejected, auth failure这类重试也无意义，别重试
        await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)), ct);
    }
}

The classification logic for judging "retryable" is no longer in the provider, caller defines it themselves. providerErrorAutoRetry configuration (maxAttempts, retryDelay, enabled) can still be read from the frontend settings page, but what actually drives retry is your orchestration layer, not PiProvider. Repeat this three times.

Cancellation: Token Pass-through + Three-stage Shutdown

For cancellation, PiProvider almost doesn't implement anything itself, fully delegating to CliProcessManager. PiProvider only handles two things: passing CancellationToken down, and cleanup on exception.

Full-chain Pass-through

The chain looks like this, passing all the way down:

调用方 CancellationToken
  → PiCliProvider.StreamCoreAsync(cancellationToken)
  → PiProvider.ExecuteProcessAsync([EnumeratorCancellation] cancellationToken)
  → ReadLineAsync(cancellationToken) / WaitForExitAsync(cancellationToken)
  → 异常时 _processManager.StopAsync(handle, CancellationToken.None)

Note the last line: cleanup uses CancellationToken.None, not the token the user passed in. This is a detail, but extremely important.

The reason is: the user's token is already canceled. If you use this already-canceled token for cleanup, the cleanup task will be canceled immediately, and the process becomes an orphan—pi still running in the background, no one collecting it, CPU and memory occupied for nothing. So cleanup must use CancellationToken.None, ensuring cleanup actions definitely complete. It's like with people—some things need proper cleanup after they completely stop, otherwise it's just leaving a mess.

Three-stage Progressive Shutdown

CliProcessManager.StopProcessAsync is a three-stage progressive shutdown process, with time constants defined at the top of the file:

// 优雅停止的耐心：先给进程自己收尾的时间
private static readonly TimeSpan GracefulStopTimeout = TimeSpan.FromSeconds(2);
// 强制 kill 后等待进程真正退出的耐心
private static readonly TimeSpan StopWaitTimeout = TimeSpan.FromSeconds(5);

The three stages progress like this:

Interrupt signal. TryInterruptAsync first writes a \u0003 (Ctrl+C character) to stdin, and on Unix additionally does kill -INT <pid>. This step is to let pi gracefully end itself—it can perceive the interrupt and wrap up what it's writing.
Graceful wait. Wait at most 2 seconds to see if the process exits on its own.
Force kill. If it hasn't exited, directly Process.Kill(entireProcessTree: true) to kill the entire process tree together, then wait at most 5 seconds to confirm it's really dead.

Why entireProcessTree: true? Because pi spawns child processes when running tools—for example, local model processes routed by provider, bash subprocesses running. Killing only the parent process leaves child processes as orphans continuing to run. Killing the whole tree together is clean.

Under Windows there's no SIGINT, can only rely on Ctrl+C character, so cross-platform behavior will differ, keep this in mind.

PiProvider's Exception Cleanup

PiProvider's ExecuteProcessAsync when ReadLineAsync throws an exception, uses ExceptionDispatchInfo.Capture to temporarily store the exception, jumps out of the loop to call StopAsync to clean up the process, then pendingException.Throw() rethrows the original exception to the upper layer.

Why store then throw? Because if you throw directly, the process hasn't been recycled yet and becomes an orphan; if you throw before StopAsync, cleanup logic doesn't run at all. Store it temporarily, first guarantee the process is definitely recycled, then preserve the original OperationCanceledException semantics completely for the caller—caller gets this exception and can judge "oh, user actively canceled" not "something went wrong."

Unified Contract for Startup Failures

There's another detail worth mentioning separately. Process startup failure—for example, pi executable doesn't exist, wrong permissions—PiProvider doesn't throw exceptions, but synthesizes a terminal.failed message, then yield break.

Why do this? Because if you throw exceptions, upper layer consumers have to handle two completely different semantics: one is "normal messages during streaming consumption," the other is "exceptions thrown before streaming starts." This makes the consumer's await foreach particularly hard to write.

After unifying to "always give you messages first, then end the stream," consumer logic is consistent: getting terminal.failed counts as failure, getting terminal.completed counts as success, no need for try/catch branching. This is a small but important design decision, stabilizing the contract.

Practice: Correct Way to Consume Streams

Referencing PiScenarioMessageReader (libs console test scenario) and PiCliProvider.StreamCoreAsync (core thin adapter) in HagiCode, consumers look roughly like this:

await foreach (var message in provider.ExecuteAsync(options, prompt, cancellationToken))
{
    // 1. 短路处理失败，别再处理后续消息
    if (NormalizedAcpCliAdapter.TryGetFailureMessage(message.Content, out var failure))
    {
        yield return new AIStreamingChunk { Type = StreamingChunkType.Error, ErrorMessage = failure };
        yield break;   // stream ends after terminal.failed
    }

    // 2. assistant 文本是 cumulative snapshot，自己再做一次增量计算
    if (message.Type == "assistant" && TryGetText(message.Content, out var text))
    {
        var delta = ReconcileSnapshot(text);  // 前缀比对
        if (!string.IsNullOrEmpty(delta)) yield return Chunk(delta);
    }

    // 3. terminal.completed 是唯一可靠的"结束"信号
    if (message.Type == "terminal.completed") break;
}

Common Pitfalls Quick Reference

Organizing all the pitfalls encountered along the way into a table, for future reference:

现象	原因	处理
前端看到 assistant 文本重复	没做 cumulative 转 delta	用 `ReconcileAssistantTextSnapshot` 做前缀比对
取消后进程还在跑	清理用了已经取消的 token	改用 `CancellationToken.None` 做清理
重试不生效	把重试写进了 PiProvider，但 provider 是单次尝试语义	上移到调用方编排层
pi 报错信息丢失	没读 `terminal.failed` 的诊断字段	完整透传 `text` / `invalid_output_lines` / `stderr`
工具调用中途收到思考碎片	直接转发了 thinking 事件	缓冲到 turn 结束再 `DrainBufferedThinkingMessages`

How to Verify

The libs layer uses StubCliProcessManager to mock processes, with unit tests covering pure logic like parameter construction, event normalization, incremental deduplication, failure pass-through. The real CLI path uses HAGICODE_REAL_CLI_TESTS environment variable to opt-in, running trip scenarios with real models. The core layer's PiCliProviderTests verifies the thin adapter's AIStreamingChunk projection and session binding.

# 在 Hagicode.Libs 仓库跑 Pi 相关单测
dotnet test --filter "FullyQualifiedName~PiProviderTests"

# 跑真实 CLI 集成测试（需要本地装好 pi）
HAGICODE_REAL_CLI_TESTS=1 dotnet test --filter "FullyQualifiedName~PiProviderTests.RealCli"

Summary

Putting these three things together, the mental model for integrating pi actually boils down to one sentence: let each layer do only its own thing.

Message parsing is handed to PiJsonEventMapper: private events are normalized into shared CliMessage, cumulative snapshots converted to deltas, thinking buffered until turn end.
Retry is handed to the caller: provider does single attempts, whoever wants retry does it at the upper layer themselves, configuration is preserved but no longer drives provider.
Cancellation is handed to CliProcessManager: CancellationToken is passed through the full chain, cleanup uses CancellationToken.None, three-stage progressive shutdown (interrupt signal → graceful wait → force kill entire process tree).

After these boundaries are clearly drawn, integrating a new agent CLI almost becomes pipeline work—you just need to write a new XxxProvider and XxxJsonEventMapper, and cross-cutting logic like retry, cancellation, message contracts, error handling are all reused. This is also the fundamental reason why HagiCode can simultaneously support multiple agent CLI backends (claude code, codex, pi, gemini cli, etc.) without getting messy.

Let me say that most important boundary one more time: don't add retry at the provider layer. Once you understand this, integrating agent CLI is more than halfway done...

Summary

Returning to the theme "Pi Agent Integration: Message Parsing, Retry, and Cancellation," what's really worth repeatedly confirming isn't scattered techniques, but whether constraints, implementation boundaries, and engineering trade-offs have been clearly seen.

As long as the judgment bases in this article are settled into stable checklist items, you can make reliable decisions faster when facing similar problems in the future.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-19-pi-agent-integration-message-parsing-retry-cancel%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

How to Use Upptime to Build Your Own Status Page for Free

Hagicode — Thu, 18 Jun 2026 05:30:22 +0000

How to Use Upptime to Build Your Own Status Page for Free

Move monitoring entirely into a GitHub repo—Actions as probes, the repo as a database, Pages as a CDN, and Issues as an event log. Zero servers, zero monthly fees, yet somehow you end up with a status page that you can view, query, and trace. Call it black magic or the wisdom of the frugal—either way, it runs.

Background

When operating a small product matrix consisting of over a dozen external services, "is it actually working" became a common refrain. Customers report they can't access it, you SSH in and curl once to find it's fine; a few minutes later it goes down, but this time you weren't watching. Commercial monitoring (Pingdom, UptimeRobot's premium tier, Datadog) can certainly solve this, but they charge either by site or by request count—for an indie developer, neither cost nor mental burden is quite worth it.

More importantly, users need to be able to check the status page themselves. Ideally, one domain (say status.hagicode.com) would display real-time availability for each service, response time curves, historical events, and automatically log incidents when failures occur with automatic notifications. The traditional approach requires four pieces—a server running cron, a database storing historical data, a frontend site, and a CDN. Once you lay out these four, operational costs immediately outweigh the services being monitored—using a sledgehammer to crack a nut, and even the nut feels crowded.

To address these pain points, we made a decision: move the entire monitoring solution directly to GitHub. This decision brought changes larger than you might imagine—I'll get to that gradually.

About HagiCode

The solution shared in this article comes from our experience building HagiCode. HagiCode is an AI code assistant project that exposes over a dozen public services including web pages, documentation sites, and download endpoints, driven by the main repository HagiCode-org/site. These sites must remain stable and available, so status monitoring is not optional for us—it's a necessity. The Upptime solution below is exactly what HagiCode's production environment uses—I didn't make this up.

Analysis: How Upptime Actually Works

Upptime is essentially a GitHub repository template plus six workflows generated by that template. The key to understanding it is seeing clearly "who calls whom, when, and produces what that lands where." Break it apart and it's not so mysterious.

Data Flow: One Configuration File Drives Everything

The entire system revolves around a single declarative configuration file .upptimerc.yml. HagiCode's actual configuration structure looks roughly like this:

owner: HagiCode-org
repo: upptime

sites:
  - name: HagiCode Website
    url: https://hagicode.com
  - name: HagiCode Docs
    url: https://docs.hagicode.com
  - name: Server Package Index
    url: https://index.hagicode.com/server/index.json
  # ... 14 sites total

status-website:
  cname: status.hagicode.com
  logoUrl: https://raw.githubusercontent.com/HagiCode-org/upptime/master/assets/upptime-icon.svg
  name: HagiCode Status
  introTitle: "**HagiCode Status**"
  introMessage: Real-time availability tracking for public HagiCode websites and download endpoints.
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

Two points here are worth calling out. First, sites can monitor both web pages (returning HTML) and pure JSON endpoints (like index.json)—Upptime only cares about HTTP status codes and response time, not content validation. Second, cname points to status.hagicode.com, which requires you to own that domain and configure DNS to point to GitHub Pages—after all, freebies aside, you still need to provide your own domain.

The Division of Six Workflows

All files under .github/workflows/ have a warning at the top Do not edit this file directly!—they're auto-updated weekly by the template; you only need to modify .upptimerc.yml. Each workflow is triggered by cron, calling different subcommands of the same action upptime/uptime-monitor@v1.42.6 with clear division of labor, which is actually quite reassuring:

Workflow	cron	command	purpose
`uptime.yml`	`/5 * * *`	`update`	probe every 5 minutes, write `history/*.yml`
`response-time.yml`	—	`response-time`	calculate response time statistics
`graphs.yml`	—	`graphs`	generate day/week/month/year PNG curves
`summary.yml`	—	`summary`	update status table in README
`site.yml`	`0 1 * * *`	`site`	build static site daily, deploy to Pages
`update-template.yml`	`0 0 * * *`	—	sync upstream template weekly

The core snippet of uptime.yml shows how the "probe" runs:

on:
  schedule:
    - cron: "*/5 * * * *"
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GH_PAT || github.token }}
      - name: Check endpoint status
        uses: upptime/uptime-monitor@v1.42.6
        with:
          command: "update"
        env:
          GH_PAT: ${{ secrets.GH_PAT || github.token }}
          SECRETS_CONTEXT: ${{ toJson(secrets) }}

site.yml adds one more step, using peaceiris/actions-gh-pages@v4 to push build artifacts to the gh-pages branch:

- uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GH_PAT || github.token }}
    publish_dir: "site/status-page/__sapper__/export/"
    user_name: "Upptime Bot"
    user_email: "73812536+upptime-bot@users.noreply.github.com"

Data Persistence: Files as Database

Monitoring results aren't stored in a database; instead they're committed back to the repository as files. This sounds a bit wild, but it's actually solid in practice. Each site produces three types of artifacts.

Status snapshot history/{slug}.yml, for example history/hagi-code-website.yml:

url: https://hagicode.com
status: up
code: 200
responseTime: 96
lastUpdated: 2026-06-17T00:22:34.485Z
startTime: 2026-03-24T10:07:32.531Z

shields.io endpoint badge data sources api/{slug}/response-time.json, uptime.json:

{"schemaVersion":1,"label":"response time","message":"739 ms","color":"yellow"}

And response time curve graphs graphs/{slug}/response-time-{day,week,month,year}.png.

The trade-off of this "files as database" approach is well-considered: write-heavy, read-light, controllable scale (about 288 samples per day per site, storing increments rather than full logs), naturally versioned, zero infrastructure. The cost, of course, is that the repository grows continuously and you occasionally need to look back and care about it.

Events and Notifications: Issues as Event Log

Incident logging relies on GitHub Issues, paired with two built-in repository templates: .github/ISSUE_TEMPLATE/bug_report.md (user-reported issues) and maintainance-event.md (scheduled maintenance). The maintenance template uses frontmatter to express the time window:

<!--
start: 2021-08-24T13:00:00.220Z
end: 2021-08-24T14:00:00.220Z
expectedDown: google, hacker-news
-->

Upptime parses these Issues and renders "maintenance in progress" and "past events" to the status page and README. Notifications rely on Issues' own watch mechanism, plus configurable webhooks, Slack, Telegram (declare notifications at the top of .upptimerc.yml; HagiCode's example repo currently doesn't have this enabled—after all, one less thing is one less thing).

Solution: Five Steps to Replicate a Status Page

Replicating a HagiCode-style status page, from zero to live, takes five steps total. Five steps sounds like a lot, but each one is short—take your time.

Step 1: Create Repository from Template

Don't git clone and modify—use GitHub's "Use this template" to create a repository directly (e.g., your-org/upptime). The template already includes all workflows, Issue templates, and the static site skeleton. After cloning locally, the only thing you need to manually modify is .upptimerc.yml—leave everything else alone.

Step 2: Edit `.upptimerc.yml`

Change owner/repo to yours, list the addresses you want to monitor in sites, configure status-website for the site. The minimum viable version looks roughly like this:

owner: your-org
repo: upptime

sites:
  - name: Main Site
    url: https://example.com
  - name: API Health
    url: https://api.example.com/health
    expectedStatusCodes:
      - 200

status-website:
  cname: status.example.com   # delete if no domain, use default your-org.github.io/upptime
  name: Example Status
  introTitle: "**Example Status**"
  introMessage: 服务可用性实时监控
  navbar:
    - title: Status
      href: /
    - title: GitHub
      href: https://github.com/$OWNER/$REPO

Advanced items: expectedStatusCodes limits acceptable status codes (default 200-399); headers customizes request headers (for endpoints requiring auth); maxResponseTime marks slow responses. Use these as needed—take what you need.

Step 3: Configure Secrets and Permissions

The workflow defaults to ${{ secrets.GH_PAT || github.token }}. github.token can run the basic flow, but two limitations will bite you:

Workflows triggered by the default token won't trigger downstream workflows (to prevent loops), breaking the "probe → create Issue → notify" chain in the middle.
Insufficient permissions for cross-repo operations (like multi-org).

Recommend creating a new PAT (requires repo + workflow permissions) and storing it as repository Secret GH_PAT. update-template.yml has a specific check: without GH_PAT, it skips template auto-update and prints a warning, so this secret isn't just optional—it's key to peace of mind.

Step 4: Enable GitHub Pages

Repository Settings → Pages → Source select Deploy from a branch, branch select gh-pages, directory /root. site.yml automatically pushes build artifacts to this branch every day at 1 AM. If you configured cname, add a CNAME record at your DNS provider pointing to your-org.github.io.

It's also good to manually trigger once the first time: Actions page find "Static Site CI" → Run workflow, no need to wait foolishly for scheduled tasks—seeing results one second earlier means peace of mind one second earlier.

Step 5: Verification and Maintenance

After pushing the config, go to Actions and check if "Uptime CI" runs every 5 minutes and if history/ starts showing *.yml files. The status page address is https://<your-org>.github.io/upptime/ or your custom domain. Later, adding sites or changing domains only requires touching .upptimerc.yml one file—workflows are fully automated. HagiCode has maintained availability for 14 endpoints using this mechanism for over a year now, basically worry-free.

Practice: I've Walked Through the Potholes for You

The following items are experience accumulated from HagiCode's actual operation—written down so you can take fewer detours.

Practice 1: Monitoring Granularity Selection

HagiCode puts web pages (https://hagicode.com) and pure data endpoints (https://index.hagicode.com/server/index.json) in the same sites list. For JSON endpoints, Upptime makes requests and parses HTTP status codes but doesn't validate content structure. If you need deep checks like "returns 200 but content is wrong," you'll need to supplement with expectedStatusCodes plus external probes—Upptime itself only does black-box HTTP checks—it reads the face, not the mind.

Practice 2: Clever Use of Response Time Badges

api/{slug}/response-time.json is a shields.io endpoint badge data source. HagiCode's README heavily references these URLs:

https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FHagiCode-org%2Fupptime%2FHEAD%2Fapi%2Fhagi-code-website%2Fresponse-time.json

This way, you can embed real-time response time badges in any Markdown (project README, blog, third-party pages), with colors driven by the values in message and the color field. Note that using HEAD rather than master/main to reference raw files avoids widespread failures after branch renames—details hide stability.

Practice 3: Repository Size Control

Sampling every 5 minutes, history/ accumulates considerable volume over a year. Upptime uses incremental YAML rather than full logs, which is relatively restrained, but it's still recommended to occasionally check repository size. If a site's monitoring value declines, remove it from sites—corresponding historical files can also be manually cleaned up; after all, if you can't bear to delete, the repository will eventually show you what bloating means.

Practice 4: Real Usage of Maintenance Events

maintainance-event.md isn't decoration. Before a planned release, create an Issue using the template, fill in start/end/expectedDown, and Upptime will mark corresponding sites during that period as "scheduled maintenance," not counting them toward availability statistics, avoiding dragging down the full-year SLA with a normal release. HagiCode's expectedDown supports comma-separated site name lists, corresponding one-to-one with sites[].name.

Practice 5: Boundaries Between Template Updates and Customization

The Do not edit this file directly! at the top of all .github/workflows/*.yml isn't meant to scare you. update-template.yml overwrites these files with the upstream template weekly. When you need custom behavior, the correct approach is to use officially supported config items in .upptimerc.yml (like skipTopics, customStatusWebsite, runnerSettings), not to modify workflows. If you really must modify workflows, either turn off update-template.yml or fork and maintain the template yourself—the latter loses painless upgrades; weigh the trade-offs yourself.

Practice 6: Reality Constraints of Free Quotas

GitHub Actions is free and unlimited for public repositories, which Upptime's design exploits. Private repositories have 2000 free minutes per month, while uptime.yml runs every 5 minutes for about 1 minute each time—just this one item costs about 8640 minutes per month, exceeding the quota. So the Upptime repository must be public—this is the premise of "free"—don't go private for secrecy and then receive a bill, that's awkward.

Conclusion

Returning to the initial question: monitoring a pile of external services—is there really a cheap solution? HagiCode's answer is—yes, and so cheap you'll doubt it's real. Upptime breaks monitoring into four GitHub native components:

Probes = GitHub Actions cron
Database = YAML/JSON files in the repository
CDN = GitHub Pages
Event log = GitHub Issues

You get: real-time availability, response time curves, historical events, availability badges, custom domains, automatic notifications—all with zero servers and zero monthly fees. The cost is keeping the repository public and occasionally caring about repository size. Compared to hand-rolling a monitoring solution, this cost is actually far lighter.

The reason this solution works is behind GitHub's ecosystem's sincere subsidy for open-source projects. If you're also maintaining a small multi-site product matrix, I strongly recommend spending an afternoon setting this up—it's far less worry than hand-rolling monitoring.

References

Summary

Around "How to use Upptime to build your own status page for free," a more prudent approach is to gradually get key configurations, dependency boundaries, and landing paths working first, then fill in optimization details.

Once goals, steps, and acceptance criteria are clear, such solutions can typically enter actual delivery more smoothly.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-18-how-to-use-upptime-for-free-status-page%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

How to Publish an Electron App to Microsoft Store: From MSIX Packaging to Store Submission

Hagicode — Thu, 18 Jun 2026 02:58:33 +0000

How to Publish an Electron App to Microsoft Store: From MSIX Packaging to Store Submission

At its core, Electron is just an ordinary Win32 desktop application, but the Microsoft Store only recognizes MSIX. This article, drawing from the actual build configuration we used for HagiCode Desktop, breaks down the entire chain from "registering a developer account → creating MSIX packages → submitting to the store" from start to finish. We'll also discuss the pitfalls we encountered along the way—after all, once you've fallen into the traps, they become stories.

Background

You have an Electron application that needs to be distributed to end users on Windows. Beyond the NSIS installer packages and portable versions we've always used, we also wanted it available in the Microsoft Store. The reasons are actually quite practical:

Trusted Distribution Channel: Apps in the store are signed and reviewed, so users won't be blocked by SmartScreen during installation, and they won't have to face that cold "Unknown publisher" warning.
Automatic Updates and Commercialization: The store handles updates for you; subscriptions and permanent licenses can be directly integrated.
Coverage of Built-in Windows 10/11 Entry Points: winget, store search, Start menu recommendations—these entry points are genuinely useful for user acquisition.

However, Electron is ultimately not UWP. To publish to the Microsoft Store, the core task is essentially one thing—repackage Electron's output into an MSIX package that the Microsoft Store recognizes, and then complete the registration and submission process dutifully. It sounds simple, but once you actually get started, there are quite a few pitfalls. We spent significant effort mapping out the entire process to fill in these gaps. Below, we'll break down each step in detail.

About HagiCode

The solution described in this article comes from our practice in the HagiCode project. HagiCode Desktop is an Electron-based desktop application that needs to be distributed to users through three channels: the official website, GitHub Release, and the Microsoft Store. This article explains how we connected the store channel. There's more information about HagiCode at the end—if you're interested, feel free to scroll down.

Analysis: Four Critical Questions to Clarify Before Publishing

Publishing to the Microsoft Store involves four key technical judgments. Once you've thought these through clearly, you won't need to repeatedly backtrack later—after all, no one wants to redo their work.

1. Microsoft Store Only Accepts MSIX / AppX, Not Traditional NSIS/EXE

The Microsoft Store's support for desktop applications (Desktop Bridge) is built on the MSIX format. Traditional NSIS installer packages cannot be submitted directly; they must first be repackaged into MSIX using MakeAppx. Fortunately, Electron Forge provides a @electron-forge/maker-msix maker that can produce MSIX directly during the packaging phase, saving you the hassle of reverse-engineering packaging from an installed directory.

Our project includes this maker:

{
  name: '@electron-forge/maker-msix',
  platforms: ['win32'],
  config: {
    appManifest: msixManifestPath,
    packageAssets: msixAssetsPath,
    logLevel: 'warn',
    ...(windowsKitPath ? { windowsKitPath } : {}),
    ...(windowsKitVersion ? { windowsKitVersion } : {}),
    ...msixSigningConfig,
  },
},

The key inputs are essentially two: appManifest (AppxManifest.xml, which defines package identity and capabilities) and packageAssets (store icon assets). If either of these is wrong, everything else, no matter how well done, is wasted effort.

2. Package Identity Must Be Reserved in Partner Center in Advance

The Identity field (Name, Publisher) in the MSIX package cannot be filled in arbitrarily—it must match exactly the application identity reserved in Partner Center. Even one character off will result in rejection. Our reserved identity is stored in forge.store-config.json:

{
  "packageIdentity": {
    "displayName": "Hagicode",
    "publisherDisplayName": "newbe36524",
    "publisher": "CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F",
    "identityName": "newbe36524.Hagicode",
    "backgroundColor": "transparent",
    "languages": ["en-US", "zh-CN", "zh-TW", "ja-JP", "ko-KR", "de-DE", "fr-FR", "es-ES", "pt-BR", "ru-RU"]
  }
}

That publisher string comes from the certificate subject issued by Microsoft after developer account registration and must match character-for-character. The identityName is the package name prefix you reserved. This string must be copied exactly from Partner Center—never type it manually. We'll discuss this again in the "Common Pitfalls" section later.

3. Desktop Applications Must Declare `runFullTrust` Capability

Electron applications need full file system access, need to spawn child processes, and need to run the Node runtime—these can only be achieved in "full trust" mode. Therefore, the MSIX manifest must honestly declare the runFullTrust capability, otherwise the application will be blocked by the sandbox upon startup, manifesting as various baffling crashes. Our configuration looks like this:

{
  "msix": {
    "minVersion": "10.0.17763.0",
    "maxVersionTested": "10.0.19045.0",
    "capabilities": [
      "runFullTrust",
      "internetClient",
      "internetClientServer",
      "privateNetworkClientsServer"
    ]
  }
}

runFullTrust is the standard for desktop application publishing. Setting minVersion to 17763 (Windows 10 1809) is because from this version onwards, MSIX has stable support for desktop Win32 applications; set it lower and users can't install it; set it higher and you won't cover those older machines.

4. Store Submission Requires Windows Environment + Microsoft Store CLI

Packaging can be done on cross-platform CI, but store submission (msstore publish) cannot—it must run the Microsoft Store CLI in a Windows environment with Azure AD application credentials configured. This is why the publish_store job in the automation pipeline must run on a windows-latest runner. This is a hard constraint that can't be bypassed, unlike packaging which can be stuffed into a Linux container.

Solution: Eight-Step Process for Complete Store Publishing

Connecting the analysis above, the complete steps to publish an Electron app to the Microsoft Store are roughly as follows.

Step 1: Register a Developer Account

First, go to Partner Center to register a developer account (individual or company) and pay the one-time fee. After the account is activated, you'll receive a Publisher certificate subject string, which looks roughly like this: CN=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. This is the only source for the publisher field later.

Step 2: Reserve Application Identity in the Store

Create a new application in Partner Center and fill in the name you want to reserve. The system will assign you an identityName, which combined with your own Publisher forms the complete package identity. Copy this identity exactly into your local configuration:

// forge.store-config.json
{
  "packageIdentity": {
    "displayName": "Hagicode",
    "publisherDisplayName": "newbe36524",
    "publisher": "CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F",
    "identityName": "newbe36524.Hagicode"
  }
}

Step 3: Prepare Store Icon Assets

The Microsoft Store requires a set of PNGs in fixed dimensions: StoreLogo.png, Square44x44Logo.png, Square150x150Logo.png, Wide310x150Logo.png, etc. Our prepare-msix.js script validates whether all these assets are present before packaging:

// Validate required store icon assets, missing even one won't work
const requiredAssets = ['StoreLogo.png', 'Square44x44Logo.png', 'Square150x150Logo.png', 'Wide310x150Logo.png'];
for (const assetName of requiredAssets) {
  const assetPath = path.join(paths.generatedAssetsPath, assetName);
  if (!fs.existsSync(assetPath)) {
    throw new Error(`Missing required MSIX asset after preparation: ${assetPath}`);
  }
}

Why do this? Because if one size is missing, MakeAppx won't tell you exactly what's wrong during packaging, and you'll only get rejected during store review—by which time you've already waited several days. Validating in advance is an effective defense.

Step 4: Generate AppxManifest.xml

The manifest needs to include package identity, capabilities, visual assets, and the entry executable. We use an override configuration (forge.store-config.json) to drive prepare-msix.js to generate the manifest, ensuring the identity matches the store. The key sections of the manifest look roughly like this:

<!-- Package identity: must match Partner Center -->
<Identity Name="newbe36524.Hagicode"
          Publisher="CN=8B6C8A94-AAE5-4C8B-9202-A29EA42B042F"
          Version="1.2.3.0" />

<Applications>
  <Application Id="Hagicode" Executable="Hagicode.exe" EntryPoint="Windows.FullTrustApplication">
    <uap:VisualElements ... />
  </Application>
</Applications>

<!-- Capability declaration: runFullTrust is key for desktop apps -->
<Capabilities>
  <rescap:Capability Name="runFullTrust" />
  <Capability Name="internetClientServer" />
</Capabilities>

Note that line EntryPoint="Windows.FullTrustApplication"—this is a critical marker for desktop applications. Combined with the runFullTrust capability, it allows the app to run with full permissions. Without it, the app is confined to the sandbox, quite frustratingly.

Step 5: Package with maker-msix

The build command is in package.json:

{
  "scripts": {
    "build:win:store": "npm run generate:store-bindings && node scripts/build-store-package.js"
  }
}

It ultimately calls Electron Forge, passing forge.store-config.json as an override configuration. The maker-msix will call the Windows SDK's MakeAppx to output an .msix file. There's a hard constraint here: packaging must be done on Windows (or in a container with Windows SDK), since it depends on MakeAppx—this can't be bypassed.

Step 6: Sign (Can Skip for Store Submission)

This step is easily overlooked—packages submitted to the store are re-signed by Microsoft with their own certificates, so for development self-testing outside "formal submission," you don't need to sign. However, if you want to install and test locally, you need to sign with a trusted certificate, otherwise Windows will refuse installation. Our resolveMsixSigningConfig returns an empty object when no signing materials are configured, letting the process continue:

// Don't sign if no signing materials configured, let the store re-sign uniformly
function resolveMsixSigningConfig() {
  if (!process.env.MSIX_CERT_FILE) return {};
  return {
    signMethod: 'signtool',
    certFilePath: process.env.MSIX_CERT_FILE,
    certPassword: process.env.MSIX_CERT_PASSWORD,
  };
}

Separating the "self-testing signing" and "submitting unsigned" paths is a key practice.

Step 7: Configure Microsoft Store CLI Credentials

Create an Azure AD application in the Azure portal, grant it permissions to access Partner Center, and obtain the following set of credentials:

AZURE_AD_APPLICATION_CLIENT_ID
AZURE_AD_APPLICATION_SECRET
AZURE_AD_TENANT_ID
SELLER_ID (Seller ID from Partner Center)
MICROSOFT_STORE_PRODUCT_ID (Product ID of the reserved application)

This step is slightly convoluted, but the documentation for both Azure Portal and Partner Center is quite detailed—just follow it.

Step 8: Submit to Store

In a Windows environment, submit using the Microsoft Store CLI:

# Configure credentials
msstore reconfigure --tenantId $env:AZURE_AD_TENANT_ID `
  --clientId $env:AZURE_AD_APPLICATION_CLIENT_ID `
  --clientSecret $env:AZURE_AD_APPLICATION_SECRET `
  --sellerId $env:SELLER_ID

# Submit MSIX package to the reserved product
msstore publish "$packagePath" -id $env:MICROSOFT_STORE_PRODUCT_ID

After submission, you need to return to Partner Center to fill in the store listing details (description, screenshots, pricing, rating), then click submit for review. Review typically takes 1–3 business days; first submissions tend to take longer.

Practice: Consolidating Configuration and Pitfall Experience

After going through the process once, these practices can help you avoid some detours—after all, after you've taken enough detours, they don't feel like detours anymore, but some things can still be skipped.

Store Configuration Files Separately

Separating "general build configuration" from "store-specific configuration" is key. Our approach is: forge.config.js handles daily builds (NSIS, portable, macOS dmg), while forge.store-config.json only extends and overrides during store builds:

{
  "extends": "forge.config.js",
  "buildVersion": "0.1.0.0",
  "packageIdentity": { /* store reserved identity */ },
  "msix": {
    "minVersion": "10.0.17763.0",
    "maxVersionTested": "10.0.19045.0",
    "capabilities": ["runFullTrust", "internetClient", "internetClientServer", "privateNetworkClientsServer"]
  }
}

This way, store builds and release builds don't pollute each other. HagiCode Desktop maintains three distribution channels simultaneously; configuration separation is the prerequisite for our stable iteration.

Version Numbers Must Be Four Segments

MSIX version numbers must be four segments (Major.Minor.Build.Revision, e.g., 1.2.3.0), but Electron's package.json typically only has three segments. That buildVersion field is used to fill in the last segment—when submitting to the store, version numbers must increment, and the fourth segment is very convenient for distinguishing multiple submissions under the same semantic version. Those who've encountered this will understand; those who haven't will eventually.

Multi-Language Declaration

The store supports multi-language listings, which in the manifest corresponds to each <Resource Language="..." /> tag. We declared ten languages, and the store requires filling in a description for each (you can use machine translation to pass review first, then localize gradually). The corresponding rendering logic in prepare-msix.js is:

// Render language list as Resource tags in MSIX manifest
function renderResourceTags(languages) {
  return languages
    .map((language) => `    <Resource Language="${escapeXml(language)}" />`)
    .join('\n');
}

Common Pitfalls (Focus Here)

HagiCode Desktop has encountered almost every one of these pitfalls:

Publisher Mismatch: When copying the publisher string from Partner Center, it's easy to accidentally lose a space or mess up the case, leading to immediate rejection.建议直接写成配置文件，别手敲。
Missing runFullTrust: After the app starts, it can't access the file system or spawn child processes, manifesting as various bizarre crashes that are frustrating to debug.
Incomplete Icon Sizes: MakeAppx doesn't validate, but store review will reject it. prepare-msix.js validating in advance is an effective defense.
Non-Incrementing Version Numbers: The store refuses to accept the same or lower version numbers; CI pipelines must ensure bumping on each build.
Running maker-msix in Non-Windows Environments: It won't find MakeAppx; you must use a windows-latest runner.
Signing Confusion: Use self-signed certificates for self-testing, submit unsigned for store submission and let Microsoft re-sign—separate these two paths, don't stuff self-signed certificates into submission packages.

Automation Recommendations

After manually going through the entire process once and understanding each step, it's strongly recommended to connect GitHub Actions for automation. We eventually chained version parsing, MSIX building, GitHub Release publishing, and store publishing into a pipeline, checking for new versions every 4 hours. These details are fully broken down in our other article "Automating Windows App Publication to Microsoft Store."

If you just want to get your app on the store first and integrate commercialization (subscriptions / permanent licenses) later, you can also check out our "How to Integrate Microsoft Store Subscriptions and Permanent Licenses in Electron Desktop Apps"—that article covers connecting commercialization capabilities after store publication.

References

Summary

Regarding "How to Publish an Electron App to Microsoft Store: From MSIX Packaging to Store Submission," a more prudent approach is to first run through key configurations, dependency boundaries, and implementation paths step by step, then fill in optimization details.

Once objectives, steps, and acceptance criteria are clear, such solutions can typically enter actual delivery more smoothly.

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Author: newbe36524
Original URL: https://docs.hagicode.com/go?platform=devto&target=%2Fblog%2F2026-06-18-electron-app-publish-to-microsoft-store%2F
License: Unless otherwise stated, this article is licensed under CC BY-NC-SA. Please retain attribution when sharing.

DEV Community: Hagicode

How We Use impeccable to Optimize Frontend Interface Design and Implementation Stability

How We Use impeccable to Optimize Frontend Interface Design and Implementation Stability

Introduction

Background

Analysis

1) Structure design intent first to reduce “freestyle” variance

2) Unify command catalog and documentation routes to reduce semantic drift

3) Site implementation turns “content correctness” into a verifiable asset

4) Fix development ports and env to avoid “works on my machine”

Solution

Layer 1: Contractualize task entry

Layer 2: Standardize command semantics

Layer 3: Validate content assets

Layer 4: Standardize development runtime environment

Practice

Step 1: Initialize impeccable-site

Step 2: Local development and full validation

Step 3: Run within unified monorepo orchestration

Step 4: Convert UI requests into command-based input

Step 5: Clarify current evidence gaps

HagiCode Information Overview

Summary

Original Article & License

Teaching Every Agent to Speak `/goal`: A Compatible Extension Design for HagiCode's Continuous-Work Preset

Teaching Every Agent to Speak /goal: A Compatible Extension Design for HagiCode's Continuous-Work Preset

Introduction

Background

What goal is

Where /goal comes from

Analysis

A single-locale template no longer holds up

Refusing to run isn't a good option

Solution

The variant selector: agent × language

Two sets of templates: native vs. fallback

Backend: one resolution decides it all

Loosening admission: from an allowlist to any

Practice

What an end-to-end run looks like

Adding Agent awareness to your own preset

A few easy pitfalls

Conclusion

References

Original Article & License

How to Use last30days for AI Research Based on Social Networks

How to Use last30days for AI Research Based on Social Networks

Background: What Preset Really Saves Is That Sentence Said Over and Over

One Skill, Four Modes

Two Data Layers: commands.json and task-preset.json

Single-Line Injection: /{skill} {prelude}

Five-Stage Technical Chain

Several Practical Points

Original Article & License

Precise Routing for Every Command: Practical Implementation of Multi-Skill Support in HagiCode Preset Task

Precise Routing for Every Command: Practical Implementation of Multi-Skill Support in HagiCode Preset Task

Background

About HagiCode

Clarifying the Problem First: Why Not a Mapping Table?

Core One: Two-Layer Data Responsibility Separation

Core Two: What Does a Command Definition Look Like?

Core Three: Cross-Validation During Loading

Core Four: Idempotent Splicing of Prompt Preambles

Core Five: How the Frontend Displays Bindings

Practice: Five Steps to Complete the Refactor

Summary

References

Original Article & License

How HagiCode Integrates 13 Agent CLI Tools into a Single System

How HagiCode Integrates 13 Agent CLI Tools into a Single System

Background

About HagiCode

How the Number "13" Came About

Layered Architecture: Locking Down Change

1. Identity Layer — AIProviderType

2. Business Contract Layer — IAIProvider / IAIProviderFactory

3. Adapter Layer — *CliProvider

4. Shared Runtime Layer — ICliProvider<TOptions>

5. Factory Routing Layer — AIProviderFactory

6. Directory / UI Projection Layer — main-professions.yaml

Teaching Every Agent to Speak `/goal`: A Compatible Extension Design for HagiCode's Continuous-Work Preset

What `goal` is

Where `/goal` comes from

Loosening admission: from an allowlist to `any`

Single-Line Injection: `/{skill} {prelude}`

1. Identity Layer — `AIProviderType`

2. Business Contract Layer — `IAIProvider` / `IAIProviderFactory`

3. Adapter Layer — `*CliProvider`

4. Shared Runtime Layer — `ICliProvider<TOptions>`

5. Factory Routing Layer — `AIProviderFactory`

6. Directory / UI Projection Layer — `main-professions.yaml`

Decision Five: `---` Separated Output Contract