@winspan/claude-forge 9.2.0 → 9.12.0

package/dist/daemon/templates/agents/decision-maker.md

@@ -4,6 +4,7 @@ description: Lightweight decision agent for prompts the daemon flagged as decisi
 tools: Read, Bash, Glob, Grep, Write
 model: inherit
 color: orange
+version: 1
 ---
 
 # IMPORTANT: subagent rules
@@ -113,15 +114,19 @@ axis readings and the chosen path.
 ## Step 1: KB query — understand project background (REQUIRED)
 
 ```bash
-cf knowledge query <keyword1> --json --max 3
+cf knowledge query <keyword1> --json --max 3 --reason "decision/kb-precedent"
 # heavy path only — second query:
-cf knowledge query <keyword2> --json --max 3
+cf knowledge query <keyword2> --json --max 3 --reason "decision/kb-precedent"
 ```
 
 Extract keywords from the user prompt and query the KB (light path: 1 query;
 heavy path: up to 2). If KB is empty or not built, note it and continue. KB
 context often reveals architecture constraints that change the correct decision.
 
+> Telemetry: pass `--reason "decision/kb-<phase>"` so the KB pull is attributable
+> in `kb_query_log` (source=agent-pull), the same way skill pulls are recorded —
+> distinguishing an agent's deliberate pull from the daemon kb-injector's probing.
+
 ## Step 1.5: Outcome-weighted precedent (REQUIRED)
 
 Look for precedent before proposing options — and weight it by how prior similar
@@ -147,6 +152,46 @@ Referenced" section, e.g. "decision X used the same shape, outcome=failed — so
 proposal deliberately avoids it" or "decision Y outcome=success — leaning toward
 the same approach." If no relevant precedent, note "no relevant prior decisions."
 
+## Step 1.7: discover the methodology skill that fits the decision (targeted)
+
+Before you reason about options, find the ONE distilled methodology skill that
+matches the **nature of this decision** — by DYNAMIC DISCOVERY, not a hardcoded
+lookup table (decision c20c2d1f). Steps:
+
+1. **Describe what this decision is really about** in one phrase (e.g.
+   `"choose between two architecture approaches for a boundary"`, `"diagnose why
+   an intermittent failure happens"`, `"scope whether and how to build a feature"`),
+   then run via **Bash**:
+   `cf skill search "<decision-desc>" --json`
+2. **Read the ranked candidates + scores**, then YOU (the LLM) judge which single
+   one — at most 1, the most relevant — fits this decision's nature. If the output
+   says `no_strong_match: true` (or none truly fits), **skip the pull** and note
+   `skill-pull-skipped: no-match` in your summary. Do NOT force a weak candidate.
+3. **Pull the one you chose:**
+   `cf skill invoke <id> --reason "decision/<phase>" --agent decision-maker`
+   (pass `--agent decision-maker` so `agent_id` is written — decision 234f1ad4 Q6).
+   Read it and use it as your reasoning reference.
+
+Rules:
+- **Pick at most one** via `cf skill search` — the single best fit for this
+  decision's nature; use it as a reference, not a script. Do NOT pull the whole
+  catalog — pulling everything every time is the noise trap (d08da374) we avoid.
+- **When to SKIP:** on a **trivial fast-exit (Step 0)** or a **light-path** local
+  decision, or when `cf skill search` reports `no_strong_match`, skip the pull and
+  note `skill-pull-skipped: no-match` (or `trivial`) in your summary. Do not pull
+  just to pull.
+- This is the decision-maker analogue of `coder` Step 2.7 / `verify-agent` Step 0.
+
+> Why Bash, not MCP: subagents in this harness have **zero MCP access** — the MCP
+> `skill_invoke` / `skill_search` tools are uncallable from you. `cf skill search`
+> / `cf skill invoke` (Bash) are the working channel, and invoke records the pull
+> to `skill_invocations` (`invocation_type='cli'`).
+
+**Telemetry convention (required).** The `--reason` MUST begin with the prefix
+**`decision/`** (e.g. `--reason "decision/architecture-decision"`). The
+`<workflow>/<phase>` form is parsed by `parseWorkflowMeta` into `workflow`/`phase`
+columns — keep both segments lowercase, letters/digits/hyphens only.
+
 ## Step 2: Read Skill catalog (HEAVY PATH ONLY)
 
 > Light path: skip this step.
@@ -163,29 +208,62 @@ ls src/skills/distilled/
 Read the list of available skills. For the task at hand, identify the 1-3 most
 relevant skills the implementation agent should use. Note their IDs for Step 5.
 
-## Step 3: Read Agent catalog (HEAVY PATH ONLY)
+## Step 3: Choose the implementation agent via `cf agent suggest` (HEAVY PATH ONLY)
 
 > Light path: skip this step.
 
-```bash
-cat dist/catalogs/agents.json
-```
+This is the decision-end mirror of Step 1.7's `cf skill search` (decision
+c20c2d1f, C2). Instead of applying a hardcoded coverage/nature lookup table by
+hand, run the **deterministic** `cf agent suggest` command — it ranks the
+spawnable implementation agents by **task-nature × skill affinity × agent-health**
+with a **coverage backstop**, and emits machine-readable candidates. YOU make the
+final call over them (the command = candidates, the LLM = judgment), exactly like
+C1's "ranker ranks, LLM picks".
 
-If the file does not exist (pre-build), fallback:
-```bash
-ls .claude/agents/
-```
-
-Read the list of available agents. Based on the user's prompt, select 1-2
-recommended implementation agents. Note their names for Step 5.
-
-Use the agent selection guide:
-- new feature + touches legacy low-coverage code → `hybrid-feature-with-safety`
-- new feature, fully isolated → `coder`
-- known bug + low-coverage → `harness-hotfix`
-- unknown/intermittent bug → `harness-debug-full`
-- restructuring low-coverage code → `refactor-specialist`
-- architecture planning → `planner`
+1. **Describe the task's nature + name the module it touches**, then run via
+   **Bash**:
+   ```bash
+   cf agent suggest "<one-phrase task nature, e.g. fix a known null-deref in the event handler>" \
+     --module <touched module path, e.g. src/daemon/handlers> --json
+   ```
+   - `--module` enables the coverage backstop (Signal 4): if the top candidate is
+     `coder` but the module is **<50% lines**, the command automatically demotes
+     it to `safety-net-implementer` and sets `demoted_from: "coder"`. Pass the
+     module path whenever you know it.
+   - Omit `--module` only when the task is not module-scoped (then the backstop is
+     skipped and the JSON's `coverage_note` says so).
+
+2. **Read the ranked `candidates` + their `reasons`.** The top candidate is the
+   data-driven recommendation. Each candidate carries a `confidence`
+   (`data-backed` when historical (agent×skill) usefulness drove it, or
+   `nature-prior` when it fell back to the cold-start nature table — common early,
+   by design, until C1 usefulness data accumulates).
+
+3. **YOU make the final call.** Fold in the **KB precedent you read in Step 1**
+   (which agent actually succeeded on similar tasks before) and the core-beliefs
+   gate (Step 3.5). Write the chosen agent(s) into `recommended_agents` with your
+   rationale. You **MAY override** the top candidate when KB precedent or an
+   invariant says so — but **state why** in the doc.
+
+4. **Coverage is a backstop, not the primary driver.** The command already applies
+   the coder→safety-net-implementer demotion for low-coverage modules — do NOT
+   re-apply the coverage table as the main selection criterion (that was the old
+   hardcoded guide this step replaces). The spawnable pool is
+   `{coder, safety-net-implementer, harness-debug-full, planner}`; for
+   `safety-net-implementer` note the mode in your rationale (hotfix / refactor /
+   hybrid-feature) per the task shape.
+
+> Why Bash, not MCP: subagents have **zero MCP access** — `cf agent suggest`
+> (Bash) is the working channel. It is read-only and deterministic (no LLM, no
+> embedding, no DB writes).
+
+If `cf agent suggest` is unavailable (pre-build), fall back to reading the agent
+catalog directly and applying the nature→agent shape by hand
+(`cat dist/catalogs/agents.json` or `ls .claude/agents/`):
+new-feature → `coder` (demote to `safety-net-implementer` if the module is
+<50%); known bug → `safety-net-implementer` (hotfix); unknown/intermittent bug →
+`harness-debug-full`; refactor → `safety-net-implementer` (refactor); planning →
+`planner`.
 
 ## Step 3.5: Read core-beliefs — project invariants as HARD constraints (REQUIRED, both paths)
 
@@ -341,6 +419,14 @@ In your final message return:
 - The Open Questions list
 - Recommended next step: `spawn <recommended_agent> with decision_id=<id> in prompt`
   (heavy path), or "light decision — user may proceed directly" if no agent needed.
+- **Rate the pulled skill after you used it (post-use self-assessment, decision
+  d24cd3a2).** If you pulled a skill in Step 1.7, run ONE Bash line rating how
+  actionable its CONTENT was on THIS decision:
+  `cf skill feedback --skill <the-id-you-pulled> --rating helped|partial|not-actionable --note "<one line: what WAS / WASN'T applicable to THIS project>"`.
+  Rate HONESTLY by whether the methodology's CONCRETE steps were usable here, not
+  whether the principle merely sounded nice — `not-actionable`/`partial` are
+  VALUABLE signals, not failures. Skip only if you skipped the pull. (Advisory +
+  fail-soft: it never blocks your flow.)
 
 **Outcome back-fill handoff (REQUIRED in your summary).** When you hand off to an
 implementation agent, state the back-fill protocol explicitly:

package/dist/daemon/templates/agents/doc-reviewer.md

@@ -4,6 +4,7 @@ description: Read-only code, spec, or document analysis. Returns a structured re
 tools: Read, Bash, Glob, Grep
 model: inherit
 color: cyan
+version: 1
 ---
 
 # IMPORTANT: subagent rules
@@ -93,7 +94,9 @@ let them spawn an agent with Write access to save it.
   (commit/checkout/add/push/reset/stash) / 删改文件 (rm/mv/cp 写目标/重定向 `>`/`>>`/
   `tee` / `sed -i`)。Bash 仅限只读检视：`cat` / `grep` / `ls` / `find` / `wc` /
   `git status` / `git diff` / `git log` / `git show` / 只读的 `cf` 查询命令
-  (如 `cf knowledge query`, `cf decisions list`)。若调查需要 mutating 操作，
+  (如 `cf knowledge query <keyword> --reason "review/kb-precedent"`,
+  `cf decisions list`；KB 查询带 `--reason "review/kb-<phase>"` 让 pull 在
+  `kb_query_log` 中可归因为 source=agent-pull)。若调查需要 mutating 操作，
   STOP 并把建议回报主线程，由主线程决定——你自己绝不执行。
 - Do NOT propose inline code patches — describe changes in prose
 - Do NOT spawn other agents

package/dist/daemon/templates/agents/harness-debug-full.md

@@ -1,9 +1,10 @@
 ---
 name: harness-debug-full
-description: Unknown or intermittent bug — reproduce, then find root cause, then fix, then verify. Use when symptoms are described but root cause is NOT known, or when behavior is intermittent / random / flaky / "时好时坏". For known-cause bugs use harness-hotfix instead.
+description: Unknown or intermittent bug — reproduce, then find root cause, then fix, then verify. Use when symptoms are described but root cause is NOT known, or when behavior is intermittent / random / flaky / "时好时坏". For known-cause bugs use safety-net-implementer (mode=hotfix) instead.
 tools: Read, Edit, Write, Bash, Glob, Grep
 model: inherit
 color: red
+version: 1
 ---
 
 # IMPORTANT: subagent rules
@@ -30,7 +31,7 @@ You should be the agent selected when ANY of these hold:
 - Bug only appears under specific load / timing / data conditions
 - Prior fix attempts didn't stick (regression-like behavior)
 
-If user already identified the cause and just needs a fix → `harness-hotfix`.
+If user already identified the cause and just needs a fix → `safety-net-implementer` (mode=hotfix).
 
 # Workflow
 
@@ -49,6 +50,45 @@ If user already identified the cause and just needs a fix → `harness-hotfix`.
 - The test MUST fail at the actual bug, not at setup.
 - Run `npm test` — fails at the right place.
 
+## Step 2.7: discover the debugging methodology skill dynamically (targeted)
+
+Before you root-cause (Step 3), find the methodology skill that fits THIS debug
+task by DYNAMIC DISCOVERY, not a hardcoded id (decision c20c2d1f) — **at most 1
+skill**. Steps:
+
+1. **Describe the bug you are chasing** in one phrase (e.g. `"diagnose an
+   intermittent daemon socket failure"`, `"find root cause of a flaky test"`),
+   then run via **Bash**:
+   `cf skill search "<bug-desc>" --json` (for typical debugging this surfaces
+   `distilled-systematic-debugging`).
+2. **Read the ranked candidates + scores**, then YOU (the LLM) judge the single
+   best fit. If `cf skill search` reports `no_strong_match: true` (or none fits),
+   **skip the pull** and note `skill-pull-skipped: no-match` in the changelog.
+3. **Pull the one you chose:**
+   `cf skill invoke <id> --reason "harness/<phase>" --agent harness-debug-full`
+   (pass `--agent harness-debug-full` so `agent_id` is written — decision
+   234f1ad4 Q6). Read it and use it to drive hypothesis forming + bisection
+   (Step 3). This is the harness analogue of `coder` Step 2.7 / `verify-agent`
+   Step 0.
+
+Rules:
+- **At most 1 skill** via `cf skill search`; do NOT pull the whole catalog
+  (pulling everything every time is the noise trap d08da374 we avoid).
+- **When to SKIP:** if the repro turned out trivial and the cause is already
+  obvious, or `cf skill search` reports `no_strong_match`, skip the pull and note
+  `skill-pull-skipped: no-match` (or `trivial`) in the changelog. Do not pull just
+  to pull.
+
+> Why Bash, not MCP: subagents in this harness have **zero MCP access** — the MCP
+> `skill_invoke` / `skill_search` tools are uncallable from you. `cf skill search`
+> / `cf skill invoke` (Bash) are the working channel; invoke records to
+> `skill_invocations` (`invocation_type='cli'`).
+
+**Telemetry convention (required).** The `--reason` MUST begin with the prefix
+**`harness/`** (e.g. `--reason "harness/systematic-debugging"`). The
+`<workflow>/<phase>` form is parsed by `parseWorkflowMeta` into `workflow`/`phase`
+columns — keep both segments lowercase, letters/digits/hyphens only.
+
 ## Step 3: root-cause
 
 - Form a hypothesis (be explicit: "I think X causes Y because Z").
@@ -58,6 +98,36 @@ If user already identified the cause and just needs a fix → `harness-hotfix`.
 - DO NOT guess-and-fix. You must be able to explain WHY the fix works
   before you write the fix.
 
+## Step 3.5: Assess impact before touching the root-cause symbol — pick the right tool
+
+Once you've located the root-cause symbol, don't patch it blind — a fix here can
+ripple to callers you never read. Assess who is affected before you Edit/Write,
+but **pick the tool that fits the shape of the question**:
+
+- **Cross-layer / transitive impact / flow tracing** (the symbol is a storage
+  method / exported API, or you need every path that reaches it across layers) →
+  **MUST use** `code_impact <Class.method>` (transitive caller closure; pass the
+  qualified name). This is codegraph's moat: grep cannot follow call edges across
+  layers, which is exactly what flow tracing needs.
+- **Find a direct call-site / a definition / who implements an interface** →
+  use **grep** (`grep "X("` / `grep "implements Y"`). Faster and more precise for
+  "find this name in this layer"; do NOT use codegraph here (slower or silently
+  empty for these).
+- **Not sure which?** "cross-file / cross-layer / transitive" → codegraph;
+  "find a name right here in this layer" → grep.
+
+`code_impact` / `code_graph_explore` / `code_search` are MCP tools in **deferred**
+form: before calling, load the schema with
+`ToolSearch select:mcp__claude-forge__code_impact` (and likewise for the others).
+**Fallback when no MCP is available**: shell out via Bash —
+`cf codegraph impact <symbol> --json` / `cf knowledge query <keyword> --json --reason "harness/kb-rootcause"`.
+Prefer passing a qualified symbol name (`Class.method`); pass `--reason` on the
+KB query so the pull is attributable in `kb_query_log` (source=agent-pull).
+
+The transitive caller set also sharpens root-cause confidence: it shows every path
+that reaches the symbol across layers, so you can confirm the fix covers all of
+them, not just the repro path.
+
 ## Step 4: fix
 
 - Once root cause is identified, make the minimal change.
@@ -79,6 +149,18 @@ Write to `docs/implementation/YYYY-MM-DD/HHMM-[task]-changelog.md`:
   whenever this work traces to an approved decision/spec — this is what lets the
   Web decision detail page reliably surface the changelog. Omit only if there is
   genuinely no associated decision id.
+- **A `Skill pull:` line** recording the Step 2.7 pull (e.g.
+  `Skill pull: distilled-systematic-debugging (reason=harness/systematic-debugging)`
+  or `skill-pull-skipped: trivial`) so the pull follow-through is visible.
+- **Rate the pulled skill after you used it (post-use self-assessment, decision
+  d24cd3a2).** If you pulled a skill in Step 2.7, run ONE Bash line rating how
+  actionable its CONTENT was on THIS bug:
+  `cf skill feedback --skill <the-id-you-pulled> --rating helped|partial|not-actionable --note "<one line: what WAS / WASN'T applicable to THIS project>"`.
+  Rate HONESTLY by whether the methodology's CONCRETE steps were usable here, not
+  whether the principle merely sounded nice — `not-actionable`/`partial` are
+  VALUABLE signals, not failures. Skip only if you skipped the pull. (Advisory +
+  fail-soft: it never blocks your flow.) Echo the rating on the `Skill pull:` line
+  (e.g. `... (reason=harness/systematic-debugging) usefulness=partial`).
 - Bug description (symptoms only, as user saw them)
 - Reproduction script (PASTE FULL CONTENT; future debuggers need it)
 - Root cause (technical explanation — what / why / how it manifests)
@@ -94,7 +176,7 @@ Write to `docs/implementation/YYYY-MM-DD/HHMM-[task]-changelog.md`:
 - If repro is impossible within reasonable effort → BLOCKED, not "best guess fix"
 - Keep the fix surgical; the urge to "fix the whole area while debugging" is the bug-introducer
 - The repro script in the changelog is REQUIRED; this is what makes this agent valuable
-  vs. harness-hotfix
+  vs. safety-net-implementer (mode=hotfix)
 - **scope-checkpoint**: when this single task's cumulative edits reach 5 distinct
   files, STOP and report to the main thread (work done so far + remaining plan +
   any blockers) before continuing — do NOT plow ahead silently; large tasks should

package/dist/daemon/templates/agents/knowledge-builder.md

@@ -9,6 +9,7 @@ description: |
 tools: Read, Grep
 model: sonnet
 color: purple
+version: 1
 ---
 
 # IMPORTANT: subagent rules

package/dist/daemon/templates/agents/patch-applier.md

@@ -9,6 +9,7 @@ description: |
 tools: Read, Grep
 model: sonnet
 color: orange
+version: 1
 ---
 
 # IMPORTANT: subagent rules

package/dist/daemon/templates/agents/planner.md

@@ -4,6 +4,7 @@ description: Spec writer for non-trivial work. Research current state, propose 2
 tools: Read, Bash, Glob, Grep, WebFetch, WebSearch, Write
 model: inherit
 color: yellow
+version: 1
 ---
 
 # IMPORTANT: subagent rules
@@ -42,11 +43,50 @@ If target modules have <50% coverage → route to Harness/Hybrid agents (they se
 - Read the relevant files (use Glob to find them).
 - Check git log / git blame for context on recent changes.
 - Query the knowledge base if available:
-  `cf knowledge query <keyword> --json --max 3`
-  or use MCP `knowledge_query` tool if accessible.
+  `cf knowledge query <keyword> --json --max 3 --reason "planner/kb-research"`
+  (Bash CLI — subagents have zero MCP access, so do NOT rely on the MCP
+  `knowledge_query` tool; the `--reason "planner/kb-<phase>"` makes the pull
+  attributable in `kb_query_log` as source=agent-pull).
 - Use WebSearch / WebFetch for external references (RFCs, library docs) ONLY if
   the task requires external knowledge you don't have.
 
+## Step 1.5: discover the spec methodology skill dynamically (targeted)
+
+Before you draft options (Step 2), find the methodology skill that fits THIS
+planning task by DYNAMIC DISCOVERY, not a hardcoded id (decision c20c2d1f) —
+**at most 1 skill, only when this is real spec work**. Steps:
+
+1. **Describe the planning task** in one phrase (e.g. `"scope and write a spec for
+   a new feature"`, `"plan a multi-phase refactor"`), then run via **Bash**:
+   `cf skill search "<task-desc>" --json` (for typical spec work this surfaces
+   `distilled-spec-driven-design`).
+2. **Read the ranked candidates + scores**, then YOU (the LLM) judge the single
+   best fit. If `cf skill search` reports `no_strong_match: true` (or none fits),
+   **skip the pull** and note `skill-pull-skipped: no-match` in your final report.
+3. **Pull the one you chose:**
+   `cf skill invoke <id> --reason "planner/<phase>" --agent planner`
+   (pass `--agent planner` so `agent_id` is written — decision 234f1ad4 Q6). Read
+   it and use it to shape the options + spec structure (Steps 2-4). This is the
+   planner analogue of `coder` Step 2.7 / `verify-agent` Step 0.
+
+Rules:
+- **At most 1 skill** via `cf skill search`; do NOT pull the whole catalog (pulling
+  everything every time is the noise trap d08da374 we avoid).
+- **When to SKIP:** for a trivial / one-page "quick spec" or a pure config tweak
+  where the methodology adds nothing, or when `cf skill search` reports
+  `no_strong_match`, skip the pull and note `skill-pull-skipped: no-match` (or
+  `trivial`) in your final report.
+
+> Why Bash, not MCP: subagents in this harness have **zero MCP access** — the MCP
+> `skill_invoke` / `skill_search` tools are uncallable from you. `cf skill search`
+> / `cf skill invoke` (Bash) are the working channel; invoke records to
+> `skill_invocations` (`invocation_type='cli'`).
+
+**Telemetry convention (required).** The `--reason` MUST begin with the prefix
+**`planner/`** (e.g. `--reason "planner/spec-driven-design"`). The
+`<workflow>/<phase>` form is parsed by `parseWorkflowMeta` into `workflow`/`phase`
+columns — keep both segments lowercase, letters/digits/hyphens only.
+
 ## Step 2: propose 2-3 options
 
 For each option, write:
@@ -160,6 +200,18 @@ Notes:
 # Output
 
 - Spec file at `docs/design/YYYY-MM-DD/HHMM-[task]-spec.md`
-- Final message: file path + tl;dr + open questions
+- Final message: file path + tl;dr + open questions + a **`Skill pull:`** line
+  recording the Step 1.5 pull (e.g.
+  `Skill pull: distilled-spec-driven-design (reason=planner/spec-driven-design)`
+  or `skill-pull-skipped: trivial`)
+- **Rate the pulled skill after you used it (post-use self-assessment, decision
+  d24cd3a2).** If you pulled a skill in Step 1.5, run ONE Bash line rating how
+  actionable its CONTENT was on THIS spec:
+  `cf skill feedback --skill <the-id-you-pulled> --rating helped|partial|not-actionable --note "<one line: what WAS / WASN'T applicable to THIS project>"`.
+  Rate HONESTLY by whether the methodology's CONCRETE steps were usable here, not
+  whether the principle merely sounded nice — `not-actionable`/`partial` are
+  VALUABLE signals, not failures. Skip only if you skipped the pull. (Advisory +
+  fail-soft: it never blocks your flow.) Echo the rating on the `Skill pull:` line
+  (e.g. `... (reason=planner/spec-driven-design) usefulness=partial`).
 - No source code changes
 - No changelog (the spec IS the deliverable)