forge

Files (1)

• SKILL.md

SKILL.md (first lines)

# /forge runbook

Execute these phases in order. Stop on first ship-blocking failure. Every gate writes a `forge-meta` commit trailer.

## Phase 0 — Bootstrap (run before any phase)

```bash
# git ops below must work even when the workspace is owned by a different user.
git config --global --add safe.directory '*'
git config --global --add safe.directory "$(pwd)"
```

## Phase 1 — Plan (delegate to feature-dev:code-architect)

forge-lead does **not** decompose the brief itself. Mandatory dispatch — no inline planning, no exceptions.

```bash
mkdir -p .forge .forge/kind .forge/pbt .forge/mutation .forge/browser .forge/receipts .forge/council .forge/audit
```

Eligibility check (forge-lead does this inline BEFORE the dispatch): single repo, single package only. BAIL ONLY if the brief spans multiple repos or multiple packages — never bail on a single-target brief, even if its only changes are config or infra (those parcels classify as `kind=config|infra` in Phase 5 and skip gates; they do NOT skip Phase 1).

**Why this specific subagent (verified against the on-disk plugin):** the `feature-dev` plugin ships **three** Task subagents — `code-explorer`, `code-architect`, `code-reviewer` — plus an interactive `/feature-dev` slash-command. The slash-command stops to ask the user questions ("DO NOT START WITHOUT USER APPROVAL", "Ask user which approach"), so it cannot be invoked from headless forge-lead. `code-architect` is the correct primitive — its description: *"Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences."* That is parcel-DAG decomposition by another name.

REQUIRED dispatch:

```
Task(
  subagent_type="feature-dev:code-architect",
  model="opus",
  prompt="Decompose the following brief into independent parcels for the forge pipeline.
          Output strictly the JSON for .forge/dag.json with shape
            { parcels: [ { id, claim, paths, deps, research: [], must_fix: [] }, ... ] }.
          Independence: a parcel with empty `deps` must be implementable without any other
          parcel's output. Use `deps: [<id>, ...]` only when strictly necessary.
          Brief: <verbatim user brief>"
)
```

Optional follow-on (dispatch in parallel with the planner when the brief is large or unfamiliar): up to 2 `feature-dev:code-explorer` subagents for codebase analysis — the architect reads their outputs to ground its blueprint.

After the dispatch returns, forge-lead writes the JSON verbatim to `.forge/dag.json` and appends one line to `.forge/audit/tool-trace.jsonl`:

```json
{"kind":"task","subagent_type":"feature-dev:code-architect","model":"opus","phase":"plan"}
```

**Audit invariant (delegation):** after Phase 1 completes, `.forge/audit/tool-trace.jsonl` MUST contain at least one entry with `subagent_type: "feature-dev:code-architect"`. forge-lead authoring `dag.json` from its own context is a verify-gate failure regardless of the dag's correctness — the trace is the receipt.

## Phase 2 — Research (mandatory MCP calls, routed by claim type, FIRST-CHOICE order)

For every parcel, consult the **first-choice** MCP for each claim type. Web research is a FALLBACK, not a first stop — only escalate to web when the canonical tool misses or the claim is inherently web-shaped (recent news, philosophy, broad topic research).

| Claim type | First choice (try first) | Fallback (only if first misses) |
|---|---|---|
| Library / package API (npm, pip, cargo, go.mod imports) | `mcp__docfork__search_docs` + `mcp__docfork__fetch_doc` | `WebFetch` on docs site / `mcp__github__get_file_contents` on lib repo |
| Upstream repo semantics, behavior, recent change history | `mcp__deepwiki__ask_question` | `mcp__github__*` / `gh` CLI / `WebFetch` on repo |
| GitHub PR/issue/commit context across repos | `mcp__github__*` (`gh` CLI for single repo) | `WebFetch` on PR/issue URL |
| Our prior runs / lessons / cross-session memory | `mcp__plugin_claude-mem*` | (no fallback — always first, no substitute) |
| Recent / year-bounded web facts (CVEs published this month, new RFCs) | `WebSearch` (Exa if available) | `WebFetch` on cited URLs |
| Abstract / subjective topic research (best practices, design patterns, philosophy) | `WebSearch` | `WebFetch` |
| Database schema / SQL behavior | `psql` / `mongosh` / project ORM CLI | (no fallback — direct only) |
| Security / dep scan / CVE check | `mcp__snyk__*` (Snyk MCP — invoke even unauthenticated; the call attempt is the audit signal, partial results are fine) | `WebSearch` for advisories |
| SaaS integration semantics | `mcp__composio__*` | `WebFetch` on provider docs |

**Rule of thumb:** docs first via canonical MCP, web second when canonical misses. Going straight to web for a library that's covered by docfork is a violation of the contract.

### Pre-research routing classifier (mandatory before research begins)

Before invoking any research MCP, scan each parcel claim for these keywords and write the routing decision to `.forge/routing-plan.md`:

| If brief mentions… | Route to (BEFORE other MCPs) |
|---|---|
| `CVE`, `vulnerability`, `audit dependencies`, `security scan`, `dep scan`, `package security`, `npm audit`, `dependency vulnerabilities` | `mcp__snyk__*` |
| `recent`, `2025`, `2026`, `latest`, `news`, `current state of`, `philosophy of`, `best practices` | `WebSearch` (Exa if available) |
| Specific GitHub repo by owner/name (`django/django`, `astropy/astropy`) | `mcp__deepwiki__*` |
| npm/pip/cargo package name (`ts-pattern`, `lodash`, `requests`) | `mcp__docfork__*` |
| GitHub PR number, issue number, commit sha | `mcp__github__*` |

If a brief touches multiple categories, route to ALL applicable MCPs — not just one. Snyk MUST fire when the brief mentions security/CVE/vulnerability/audit terms regardless of what other claims also need research.

`.forge/routing-plan.md` format:
```
- claim: "audit npm deps for CVEs"
  route: mcp__snyk__*  (matched: 'CVE', 'audit', 'deps')
- claim: "uses ts-pattern library"
  route: mcp__docfork__*  (matched: npm package 'ts-pattern')
```

**Training-data-only research is forbidden.** Even if you "know" how `django.db.models.Aggregate` works, call docfork or deepwiki BEFORE writing the patch. The audit trace is the receipt.

Forbidden shortcut: replying "I already know X, no MCP needed". That's a verify-gate failure regardless of patch correctness.

Append findings to each parcel's `research:` field. Reject the plan if any external claim is unsourced.

**Audit invariant:** `audit/tool-trace.jsonl` MUST contain:
- ≥1 `mcp__plugin_claude-mem*` entry per run (always check prior context first)
- For each distinct **library** named in any parcel: ≥1 `mcp__docfork__*` entry
- For each distinct **upstream repo** named in any parcel: ≥1 `mcp__deepwiki__*` entry
- For each **recent/year-bounded** claim: ≥1 `WebSearch` / `WebFetch` / Exa entry
- For each **CVE / security** claim: ≥1 `mcp__snyk__*` entry

If any required tool for a claim is missing, the verify phase REJECTS the run — re-enter Phase 2 and call it. Do not proceed with stale or training-data-only research.

## Phase 3 — Council (≥ 80 confidence filter)

Single Task batch dispatching all 6 in parallel:
- pr-review-toolkit:silent-failure-hunter
- pr-review-toolkit:type-design-analyzer
- pr-review-toolkit:code-reviewer
- pr-review-toolkit:code-simplifier
- pr-review-toolkit:comment-analyzer
- pr-review-toolkit:pr-test-analyzer

Each persona's findings go to `.forge/council/<persona>.json` with `confidence` 0-100.

Meta-judge (fresh context): drop confidence < 80, group remaining by parcel, write `.forge/council/meta-judge.json` with `must_fix`.

**Council is unconditional.** Even for one-line bug fixes. Even when "obviously correct". Even when the brief is a typo correction. Skipping council = verify-gate failure regardless of patch correctness. Do not let perceived simplicity override the contract.

From youssefKadaouiAbbassi/yka-code, MIT.

More from youssefKadaouiAbbassi/yka-code