majiayu000 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:
| # | File | Why |
|---|---|---|
| 1 | AGENTS.md |
agent config, runtime constraints |
| 2 | PROJECT_STATE.md |
canonical active spec and stage |
| 3 | docs/SPECSAFE_WORKFLOW.md |
full stage definitions and stage commands |
| 4 | docs/PRE_SPEC_CHECKLIST.md |
required checks before opening a new spec |
| 5 | docs/SOURCE_OF_TRUTH.md |
authoritative external doc URLs (Mastra, Convex, LibSQL, Drizzle) |
| 6 | docs/SKILLS.md |
available skills and when to use them |
| 7 | docs/AI_OPERATIONS.md |
agent operating rules and tool restrictions |
| 8 | active spec in specs/active/ |
requirements, scope, and ## 6.5 Current Focus |
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 Focusin the active spec, if present - whether
PROJECT_STATE.mdand 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:
| Stage | When to Use | Prompt Files | Sub-Skill |
|---|---|---|---|
| session start | start of any session | — | agentforge-session-start |
| SPEC | creating or refining a spec | prompts/planner.md, prompts/spec-writer.md |
specsafe-spec-start |
| TEST | writing tests from the spec | prompts/test-designer.md |
specsafe-test-create |
| CODE | implementing the slice | prompts/implementer.md |
specsafe-implement |
| QA / REVIEW | reviewing and verifying | prompts/reviewer.md, prompts/security-reviewer.md |
specsafe-review |
| COMPLETE | completing and archiving | prompts/reviewer.md, prompts/docs-curator.md |
specsafe-complete |
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, orspecsafe doneas authoritative lifecycle operations in this repo. Usepnpm 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.