SpecSafe for AgentForge

Use this skill for any meaningful feature work in AgentForge. It is the single entry point for the full SpecSafe lifecycle.

Step 1 — Retrieve Project Context

Read these files in order before taking any action:

Then run:

pnpm spec:status

From this, determine:

• the active spec ID
• the current stage (SPEC, TEST, CODE, QA, COMPLETE, ARCHIVED)
• the exact next step from ## 6.5 Current Focus in the active spec, if present
• whether PROJECT_STATE.md and the spec header agree — fix or flag any mismatch

Step 2 — Choose the Right Stage

Use this index to find the prompt file and sub-skill for the current work:

Load the prompt file for the active stage before doing work. The sub-skill provides detailed step-by-step instructions for that stage.

Step 3 — Move Through Stages in Order

SPEC → TEST → CODE → QA → COMPLETE → ARCHIVED

Stage advancement commands:

pnpm spec:stage <SPEC-ID> <STAGE>   # advance a spec to the next stage
pnpm spec:sync                      # sync PROJECT_STATE.md from spec files
pnpm spec:status                    # verify current state after any stage change

Do not skip stages. Update the spec file header and PROJECT_STATE.md before ending the session after any stage change.

Rules

• One active implementation spec at a time. Do not open overlapping implementation specs without explicit ownership.
• Do not write production code without a spec.
• Keep the current slice narrow. Be explicit about out-of-scope items.
• Verify Mastra and Convex behavior against official docs (see docs/SOURCE_OF_TRUTH.md) before implementation.
• Do not use upstream specsafe status, specsafe list, specsafe qa, or specsafe done as authoritative lifecycle operations in this repo. Use pnpm spec:* commands instead.
• If the active spec has no ## 6.5 Current Focus, call that out before starting implementation.
• If documentation or status files were not read, stop and read them before continuing.