# Forge

> Forge tracked lifecycle for features, slices, evidence, review, and close. Use when the user says forge, plans features, runs slices, or closes delivery work.

- Skill: `fasalzein/forge` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fasalzein/forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fasalzein/forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: fasalzein (https://skillmd.com/u/fasalzein)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fasalzein/forge

---


<skill_context>
  <skill_dir>skills/forge</skill_dir>
  <workspace_dir>/Users/tothemoon/Dev/code-forge/knowledge-wiki-system</workspace_dir>

  <path_policy>
    Relative file references in this SKILL.md normally resolve from skill_dir when they exist there.
    Plain workspace commands like git status and bun test usually run in the workspace unless instructed otherwise.
    Use $PI_SKILL_DIR/path for explicit bundled skill files.
    Use $PI_WORKSPACE/path for explicit workspace/project files.
  </path_policy>
</skill_context>

## Wiki/Forge session context

Resolve vault via `KNOWLEDGE_VAULT_ROOT` or `wiki config --effective --repo <path>`. Do not create durable project memory markdown inside the code repo unless the repo itself is the configured vault.
Forge-tracked use: obey the active Forge phase packet, its required skills, artifact owner, and allowed writes.
Standalone use: route durable memory through Wiki under `${KNOWLEDGE_VAULT_ROOT}/projects/<project>/`.

# Forge

Forge is the SDLC lifecycle layer for tracked implementation work. It owns feature/PRD/slice state, active slice ownership, Git boundaries, TDD/verification/review evidence, handovers, amendments, and close readiness. The CLI and Forge kernel own phase ordering, invariants, and close gates.

Forge artifacts are vault-owned. Resolve the vault with `wiki init`, `wiki resume`, `wiki forge next/status`, or `wiki config --effective`. Do not create repo-local `forge/`, `wiki/`, or `projects/` folders.

Health is the cross-cutting inspector/reconciler. Do not move Health orchestration into shared or lib.

## Agent command surface

Only 7 commands exist for agents. Everything else is automated by phase packets.

```
wiki resume <project> --repo <path> --base <rev>    # start session
wiki forge next <project> --json                    # get next action
wiki forge plan <project> <feature> --scaffold --json  # scaffold artifacts
wiki forge plan <project> <feature> --plan-answer-file <path>  # submit plan answer when packet asks
wiki forge plan <project> <feature> --create-artifacts  # create artifacts when packet asks
wiki forge run <project> [slice-id] --repo <path>   # execute slice
wiki handover <project> --repo <path> --json        # end session
wiki ask <project> <question...>                    # retrieve knowledge
wiki search [--hybrid] <query...>                   # search vault
```

`forge next` returns a phase packet. The packet tells you:
- Which internal command to run next (tdd, evidence, review, close, etc.)
- Which skills to load
- What files you may write

Follow the packet. Do not pick internal commands manually.

## Phase packet contract

Treat `phasePacket` from `wiki forge plan`, `wiki forge next`, and `wiki forge status` as workflow truth. If prose conflicts with a packet, follow the packet.

The full lifecycle chain:

```
[research] → plan → implement (TDD loop) → verify → review → close
```

| Phase | Skills | Gate |
|-------|--------|------|
| research | /research + /wiki | research findings filed |
| plan | /grill-with-docs → /write-a-prd → /prd-to-slices → /forge | slices exist |
| implement | /tdd | red+green evidence recorded for all behaviors |
| verify | /forge | targeted verification passed |
| review | /forge | approved review verdict |
| close | /forge | forge check passes, slice closed |

TDD is mandatory. Targeted verification, review, and close are not skippable. Passing tests alone do not close work.

Use one `wiki forge plan` packet for planning context, PRD content, and slices. Then follow `wiki forge next/status`, the listed skill chain, evidence commands, review gate, and `wiki forge run`.

## Full workflow

The complete agent workflow including session management and interrupts:

### Session start
```
wiki resume <project> --repo <path> --base <rev>
```
Loads the latest handover, runs a checkpoint, and prints orientation.
The phase packet from the last active slice tells you where to pick up.

### Feature lifecycle
```
[research] → plan (grill → prd → slices) → implement → verify → review → close → [improve]
```

| Phase | Skill loaded | What happens | Agent action | Gate |
|-------|-------------|--------------|--------------|------|
| research | /research + /wiki | Web search, scrape, synthesize | File findings through Wiki when research is requested | Findings filed in vault |
| plan (1/3) | /grill-with-docs | Resolve domain language, challenge terms | Follow `wiki forge next` packet; write an agent-authored plan-answer input | Terms resolved |
| plan (2/3) | /write-a-prd | Synthesize PRD with acceptance criteria | Keep PRD content in the plan-answer input | PRD content exists |
| plan (3/3) | /prd-to-slices | Break into thin vertical slices | Run packet-provided `wiki forge plan ... --plan-answer-file` / `--create-artifacts` commands | Draft slice artifacts created |
| implement | /tdd | RED→GREEN per behavior | Follow packet commands or `wiki forge run`; do not choose internal TDD commands manually | TDD evidence |
| verify | /forge | Targeted verification against PRD criteria | Follow packet commands or `wiki forge run` | Verification passed |
| review | /forge (isolated subagent) | Review in SEPARATE context — never self-review | Spawn isolated review when packet requires it | Approved verdict |
| close | /forge | Check all gates, close the slice | Follow packet commands or `wiki forge run` | Slice done |
| improve | /improve-codebase-architecture + /desloppify | Post-close quality pass | Use only after Forge reports improvement work | Findings filed as follow-up work |

### Interrupts
- **/diagnose** — bug found mid-phase. Diagnose loop runs (feedback loop → reproduce → hypothesise → instrument → fix). Returns to interrupted phase.
- **/improve-codebase-architecture** — can also interrupt during review if architecture friction is found. Findings become new Forge-tracked slices.

### Session end
```
wiki handover <project> --repo <path> --json
```
Creates a structured handover with summary, next action, and the current phase packet for the next agent.

### Phase detection
`wiki forge status <project> <slice-id> --json` detects the current phase from evidence:
- No TDD evidence → implement
- TDD present, no verification → verify
- Verified, no review → review
- Reviewed → close

## Subagents and ownership

Use subagents only after the plan identifies non-overlapping work and a safe lifecycle ownership model. File non-overlap alone is not enough. There is one active mutating slice per vault. Never work around the active-slice invariant.

Internal lifecycle commands such as `wiki forge start`, `wiki forge tdd`, `wiki forge evidence`, `wiki forge review`, `wiki forge check`, `wiki forge close`, `wiki checkpoint`, and `wiki maintain` are not commands agents should independently choose. Run them only when they appear in a phase packet, CLI recovery prompt, or explicit human instruction.

## Failure handling

When verification, review, check, or close fails, do not blindly rerun. Use `wiki forge status <project> <slice> --json`, `wiki checkpoint`, and `wiki maintain` to repair truth.

## Handoffs

Create a handover when work stops unfinished or context risk is high. Use `wiki handover`/`wiki agent-handover` with summary, next action, slice/PRD IDs, and ordered commands. Return the CLI copy/paste prompt verbatim.

## Forge integration

Load this skill for tracked implementation work.
Before changing files, ensure /wiki and /forge skills are loaded.
After Forge work completes: run `wiki forge next` to discover the next lifecycle action.
Use `/wiki` only for memory, freshness, vault, or research context.

## Skill edits

After editing repo skill files, run `bun run sync:full`, then `bun run sync:local -- --audit`, then restart the agent session.