Init

/specforge:init — bootstrap the lifecycle workspace

Create the committed specforge/ workspace that every other SpecForge command reads and writes. Run this once per project. It is safe to re-run: never overwrite an existing file — only create what is missing and report what already existed.

When to use

• The user wants to start spec-driven development / the SpecForge lifecycle in a repo.
• A session reports "a specforge/ workspace exists but state.md is missing" (repair).

Steps

1. Check whether specforge/ already exists. If it does, only fill in missing files and tell the user what was already present — do not clobber their work.

2. Create this structure at the project root (${CLAUDE_PROJECT_DIR}):

   specforge/
   ├── constitution.md          # project principles (soft gates)
   ├── state.md                 # gate source of truth (see format below)
   ├── audit.md                 # append-only log
   ├── inputs/
   │   ├── vision.md            # AI-DLC input #1 — WHAT/why, filled by a human
   │   └── tech-environment.md  # AI-DLC input #2 — language/framework/constraints
   └── specs/                   # per-feature artifacts land here (created by /specforge:specify)
   

3. Seed each file. If the full templates are available in the plugin at ${CLAUDE_SKILL_DIR}/../_shared/, copy them; otherwise write the seed content below.

4. state.md MUST start with these exact machine-readable markers (the gate parses them):

   <!-- SPECFORGE-STATE:v1 -->
   <!-- active: none -->
   <!-- fasttrack: off -->
   

   followed by a ## Stage approvals section containing a Markdown table with the header | Feature | Stage | Status | When |. The gate reads rows of the form | <feature> | <stage> | approved | <date> |.

5. Append an init row to specforge/audit.md: | <today ISO-8601> | — | init | SpecForge workspace created. |

6. Tell the user the workspace is ready and what to do next:

   • Fill in specforge/inputs/vision.md and specforge/inputs/tech-environment.md.
   • Optionally run /specforge:constitution to set project principles.
   • Then /specforge:specify to define the first feature.
   • Remind them: code edits are gate-blocked until a feature's spec + plan are approved.

Seed content (use if _shared/ templates are unavailable)

constitution.md — a short principles file (4–8 principles). Start minimal:

# Project Constitution

- **Version:** 1.0.0
- **Ratified:** <today>

## Principles

### P1 — Simplicity first
Prefer the simplest design that satisfies the spec. Justify added complexity.

### P2 — Test the behavior
Cover acceptance criteria with tests; avoid testing incidental implementation detail.

### P3 — Explicit contracts at boundaries
Define and document interfaces (APIs, events, schemas) before wiring internals.

## Enforcement
Advisory gates checked by /specforge:plan. The hard gate is spec+plan approval in state.md.

vision.md and tech-environment.md — use the templates in ${CLAUDE_SKILL_DIR}/../_shared/vision-template.md and tech-environment-template.md. If unavailable, create the headings from the AI-DLC inputs: Vision (what / who / why / in-scope / out-of-scope / success / uncertainties) and Technical Environment (language+version, package manager, framework, storage, deploy, test framework, prohibited libraries with reasons+alternatives, and example code).

Notes

• The specforge/ directory is meant to be committed and to travel with pull requests — the specs are the durable contract, not throwaway chat.
• Do not put specforge/ in .gitignore.