<skillcontext> <skilldir>skills/forge</skilldir> <workspacedir>/Users/tothemoon/Dev/code-forge/knowledge-wiki-system</workspace_dir>

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

Wiki/Forge session context

Resolve vault via KNOWLEDGEVAULTROOT 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 ${KNOWLEDGEVAULTROOT}/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

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]

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.