# Specsafe Agentforge

> Repository-specific SpecSafe workflow for AgentForge. Use when creating, refining, testing, implementing, or reviewing AgentForge specs so work follows the documented SpecSafe stages, prompt files, and source-of-truth rules consistently.

- Skill: `majiayu000/specsafe-agentforge` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/specsafe-agentforge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/specsafe-agentforge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/specsafe-agentforge

---


# 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 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:

| 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`, 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.