@specsafe/cli 2.1.0 → 2.2.1

package/README.md

@@ -1,13 +1,37 @@
 # SpecSafe
 
-SpecSafe is a skills-first TDD framework for AI-assisted development. It provides a structured 5-stage workflow that keeps AI agents aligned with human intent through specifications, test-driven implementation, and QA gates — regardless of which AI coding tool you use.
+SpecSafe is a two-phase software engineering framework for AI-assisted development. It provides structured planning workflows to reduce ambiguity, then enforces test-driven implementation through small spec slices — regardless of which AI coding tool you use.
 
-## The 5-Stage Workflow
+For the full canonical workflow, see [docs/SPECSAFE-CANONICAL-WORKFLOW.md](./docs/SPECSAFE-CANONICAL-WORKFLOW.md).
+
+## Two-Phase Workflow
 
 ```
-SPEC → TEST → CODE → VERIFY → QA → COMPLETE
+PHASE 1: PLANNING
+brainstorm → principles → brief → PRD → UX → architecture → readiness
+
+PHASE 2: DEVELOPMENT
+spec slice → tests → implementation → verify/QA → complete (or loop back)
 ```
 
+## Phase 1: Planning
+
+Planning removes ambiguity before implementation begins. Each planning skill produces an artifact that informs the next stage.
+
+| Step | Skill | Description |
+|------|-------|-------------|
+| 1 | `specsafe-brainstorm` | Divergent exploration of possibilities |
+| 2 | `specsafe-principles` | Product principles, non-goals, quality priorities |
+| 3 | `specsafe-brief` | Concise product/business framing document |
+| 4 | `specsafe-prd` | Testable requirements with user journeys and acceptance criteria |
+| 5 | `specsafe-ux` | UX design: tokens, components, flows, accessibility |
+| 6 | `specsafe-architecture` | System architecture with ADRs and technology decisions |
+| 7 | `specsafe-readiness` | Pre-development coherence check: GO / NEEDS REVISION / BLOCKED |
+
+## Phase 2: Development
+
+Development begins only after the change is understood well enough to be implemented as a small spec slice.
+
 | Stage | Skill | Persona | What happens |
 |-------|-------|---------|-------------|
 | **SPEC** | `specsafe-new`, `specsafe-spec` | Kai (Mason) | Create and refine a spec with requirements, acceptance criteria, scenarios |
@@ -16,16 +40,6 @@ SPEC → TEST → CODE → VERIFY → QA → COMPLETE
 | **VERIFY** | `specsafe-verify` | Lyra (Warden) | Run tests, validate against spec, loop back on failure |
 | **QA** | `specsafe-qa`, `specsafe-complete` | Lyra (Warden), Cass (Herald) | Full QA report with GO/NO-GO, then human approval gate |
 
-Additional utility skills:
-
-| Skill | Persona | Purpose |
-|-------|---------|---------|
-| `specsafe-init` | Cass (Herald) | Initialize a new SpecSafe project |
-| `specsafe-explore` | Elena (Scout) | Pre-spec exploration and research |
-| `specsafe-status` | Cass (Herald) | Project dashboard with spec counts and metrics |
-| `specsafe-doctor` | Cass (Herald) | Validate project health |
-| `specsafe-archive` | Cass (Herald) | Archive obsolete specs |
-
 ## Quick Start
 
 ```bash
@@ -46,12 +60,24 @@ specsafe doctor
 
 ## Skills Reference
 
-All 12 canonical skills:
+21 canonical skills:
+
+### Planning Skills
 
 | Skill | Description |
-|-------|------------|
-| `specsafe-init` | Initialize project — creates dirs, config, PROJECT_STATE.md |
-| `specsafe-explore` | Pre-spec exploration and research mode |
+|-------|-------------|
+| `specsafe-brainstorm` | Divergent exploration before converging on a solution |
+| `specsafe-principles` | Product principles, non-goals, and quality priorities |
+| `specsafe-brief` | Create a concise product brief — problem, users, scope, success criteria |
+| `specsafe-prd` | Expand brief into full PRD with user journeys, FRs, NFRs |
+| `specsafe-ux` | UX design foundations — tokens, components, accessibility, flows |
+| `specsafe-architecture` | System architecture — components, data model, ADRs, technology stack |
+| `specsafe-readiness` | Pre-development coherence and readiness check |
+
+### Development Skills
+
+| Skill | Description |
+|-------|-------------|
 | `specsafe-new` | Create a new spec with unique ID and initial requirements |
 | `specsafe-spec` | Refine spec with detailed requirements, criteria, scenarios |
 | `specsafe-test` | Generate test files from spec scenarios (all tests start skipped) |
@@ -59,20 +85,31 @@ All 12 canonical skills:
 | `specsafe-verify` | Run tests, validate against spec, loop on failure |
 | `specsafe-qa` | Full QA validation with report and GO/NO-GO recommendation |
 | `specsafe-complete` | Human approval gate — moves spec to COMPLETE |
+
+### Utility Skills
+
+| Skill | Description |
+|-------|-------------|
+| `specsafe-init` | Initialize project — creates dirs, config, PROJECT_STATE.md |
+| `specsafe-explore` | Pre-spec exploration and research mode |
+| `specsafe-context` | Gather and present project context for AI agents |
 | `specsafe-status` | Project dashboard with spec counts by stage |
 | `specsafe-archive` | Archive obsolete or abandoned specs |
 | `specsafe-doctor` | Validate project health and configuration |
+| `specsafe-skill-creator` | Create new SpecSafe skills with proper structure and validation |
 
 ## Agent Personas
 
 | Persona | Role | Archetype | Stages |
 |---------|------|-----------|--------|
 | **Elena** | Exploration Lead | Scout | EXPLORE |
-| **Kai** | Spec Architect | Mason | SPEC |
+| **Kai** | Spec Architect | Mason | SPEC, BRIEF, PRD |
 | **Reva** | Test Engineer | Forge | TEST |
 | **Zane** | Implementation Engineer | Bolt | CODE |
 | **Lyra** | QA Inspector | Warden | QA, VERIFY |
 | **Cass** | Release Manager | Herald | COMPLETE, STATUS, ARCHIVE, INIT, DOCTOR |
+| **Aria** | UX Designer | Prism | UX |
+| **Nolan** | System Architect | Sage | ARCHITECTURE |
 
 ## Supported Tools
 
@@ -127,5 +164,6 @@ Tracks the current state of all specs in the project:
 
 ## Further Reading
 
+- [Canonical Workflow](./docs/SPECSAFE-CANONICAL-WORKFLOW.md) — source of truth for the two-phase model
 - [Tool Support Guide](./docs/tool-support.md) — per-tool setup details
 - [Persona Guide](./docs/personas.md) — how each persona works

package/canonical/rules/.cursorrules.mdc

@@ -1,16 +1,32 @@
 ---
-description: SpecSafe TDD workflow enforcement
+description: SpecSafe two-phase workflow enforcement
 alwaysApply: true
 ---
 
-# SpecSafe — TDD Workflow Rules
+# SpecSafe — Two-Phase Workflow Rules
 
-SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+SpecSafe is a two-phase software engineering framework. Phase 1 (Planning) reduces ambiguity before implementation. Phase 2 (Development) enforces strict test-driven execution through small spec slices. No stage may be skipped. Each stage has a dedicated skill and persona.
 
-## Workflow Stages
+## Phase 1: Planning
+
+Planning precedes development. Each step produces an artifact that informs the next.
+
+| Step | Skill | What Happens |
+|------|-------|--------------|
+| 1 | `specsafe-brainstorm` | Divergent exploration of possibilities |
+| 2 | `specsafe-principles` | Product principles, non-goals, quality priorities |
+| 3 | `specsafe-brief` | Concise product/business framing document |
+| 4 | `specsafe-prd` | Testable requirements with user journeys and acceptance criteria |
+| 5 | `specsafe-ux` | UX design: tokens, components, flows, accessibility |
+| 6 | `specsafe-architecture` | System architecture with ADRs and technology decisions |
+| 7 | `specsafe-readiness` | Pre-development coherence check |
+
+Canonical order: brainstorm → principles → brief → PRD → UX → architecture → readiness. UX always precedes architecture.
+
+## Phase 2: Development Stages
 
 | Stage | Skill | Persona | What Happens |
-|-------|-------|---------|--------------|
+|-------|-------|---------|--------------| 
 | SPEC | `specsafe-new`, `specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
 | TEST | `specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
 | CODE | `specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
@@ -31,6 +47,10 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 |-------|-------------|
 | `specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
 | `specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `specsafe-brief` | Create a concise product brief |
+| `specsafe-prd` | Expand brief into full PRD with user journeys and requirements |
+| `specsafe-ux` | UX design foundations — tokens, components, accessibility, flows |
+| `specsafe-architecture` | System architecture — components, data model, ADRs |
 | `specsafe-new <name>` | Create a new spec from template with unique ID |
 | `specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
 | `specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
@@ -41,6 +61,8 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 | `specsafe-status` | Show project dashboard with all specs and metrics |
 | `specsafe-archive <id>` | Archive an obsolete spec with reason |
 | `specsafe-doctor` | Validate project health and diagnose issues |
+| `specsafe-context` | Gather and present project context for AI agents |
+| `specsafe-skill-creator` | Create new SpecSafe skills with proper structure |
 
 ## Project Constraints
 
@@ -48,6 +70,7 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
 3. **Tests define implementation** — code exists only to make tests pass
 4. **One spec at a time** — complete or park a spec before starting another
-5. **No stage skipping** — every spec must progress through all 5 stages in order
+5. **No stage skipping** — every spec must progress through all 5 development stages in order
 6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
 7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119
+8. **Planning precedes development** — reduce ambiguity before writing code

package/canonical/rules/.rules

@@ -1,11 +1,27 @@
-# SpecSafe — TDD Workflow Rules
+# SpecSafe — Two-Phase Workflow Rules
 
-SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+SpecSafe is a two-phase software engineering framework. Phase 1 (Planning) reduces ambiguity before implementation. Phase 2 (Development) enforces strict test-driven execution through small spec slices. No stage may be skipped. Each stage has a dedicated skill and persona.
 
-## Workflow Stages
+## Phase 1: Planning
+
+Planning precedes development. Each step produces an artifact that informs the next.
+
+| Step | Skill | What Happens |
+|------|-------|--------------|
+| 1 | `specsafe-brainstorm` | Divergent exploration of possibilities |
+| 2 | `specsafe-principles` | Product principles, non-goals, quality priorities |
+| 3 | `specsafe-brief` | Concise product/business framing document |
+| 4 | `specsafe-prd` | Testable requirements with user journeys and acceptance criteria |
+| 5 | `specsafe-ux` | UX design: tokens, components, flows, accessibility |
+| 6 | `specsafe-architecture` | System architecture with ADRs and technology decisions |
+| 7 | `specsafe-readiness` | Pre-development coherence check |
+
+Canonical order: brainstorm → principles → brief → PRD → UX → architecture → readiness. UX always precedes architecture.
+
+## Phase 2: Development Stages
 
 | Stage | Skill | Persona | What Happens |
-|-------|-------|---------|--------------|
+|-------|-------|---------|--------------| 
 | SPEC | `specsafe-new`, `specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
 | TEST | `specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
 | CODE | `specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
@@ -26,6 +42,10 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 |-------|-------------|
 | `specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
 | `specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `specsafe-brief` | Create a concise product brief |
+| `specsafe-prd` | Expand brief into full PRD with user journeys and requirements |
+| `specsafe-ux` | UX design foundations — tokens, components, accessibility, flows |
+| `specsafe-architecture` | System architecture — components, data model, ADRs |
 | `specsafe-new <name>` | Create a new spec from template with unique ID |
 | `specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
 | `specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
@@ -36,6 +56,8 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 | `specsafe-status` | Show project dashboard with all specs and metrics |
 | `specsafe-archive <id>` | Archive an obsolete spec with reason |
 | `specsafe-doctor` | Validate project health and diagnose issues |
+| `specsafe-context` | Gather and present project context for AI agents |
+| `specsafe-skill-creator` | Create new SpecSafe skills with proper structure |
 
 ## Project Constraints
 
@@ -43,6 +65,7 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
 3. **Tests define implementation** — code exists only to make tests pass
 4. **One spec at a time** — complete or park a spec before starting another
-5. **No stage skipping** — every spec must progress through all 5 stages in order
+5. **No stage skipping** — every spec must progress through all 5 development stages in order
 6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
 7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119
+8. **Planning precedes development** — reduce ambiguity before writing code

package/canonical/rules/AGENTS.md

@@ -1,11 +1,27 @@
-# SpecSafe — TDD Workflow Rules
+# SpecSafe — Two-Phase Workflow Rules
 
-SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+SpecSafe is a two-phase software engineering framework. Phase 1 (Planning) reduces ambiguity before implementation. Phase 2 (Development) enforces strict test-driven execution through small spec slices. No stage may be skipped. Each stage has a dedicated skill and persona.
 
-## Workflow Stages
+## Phase 1: Planning
+
+Planning precedes development. Each step produces an artifact that informs the next.
+
+| Step | Skill | What Happens |
+|------|-------|--------------|
+| 1 | `specsafe-brainstorm` | Divergent exploration of possibilities |
+| 2 | `specsafe-principles` | Product principles, non-goals, quality priorities |
+| 3 | `specsafe-brief` | Concise product/business framing document |
+| 4 | `specsafe-prd` | Testable requirements with user journeys and acceptance criteria |
+| 5 | `specsafe-ux` | UX design: tokens, components, flows, accessibility |
+| 6 | `specsafe-architecture` | System architecture with ADRs and technology decisions |
+| 7 | `specsafe-readiness` | Pre-development coherence check |
+
+Canonical order: brainstorm → principles → brief → PRD → UX → architecture → readiness. UX always precedes architecture.
+
+## Phase 2: Development Stages
 
 | Stage | Skill | Persona | What Happens |
-|-------|-------|---------|--------------|
+|-------|-------|---------|--------------| 
 | SPEC | `specsafe-new`, `specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
 | TEST | `specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
 | CODE | `specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
@@ -26,6 +42,10 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 |-------|-------------|
 | `specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
 | `specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `specsafe-brief` | Create a concise product brief |
+| `specsafe-prd` | Expand brief into full PRD with user journeys and requirements |
+| `specsafe-ux` | UX design foundations — tokens, components, accessibility, flows |
+| `specsafe-architecture` | System architecture — components, data model, ADRs |
 | `specsafe-new <name>` | Create a new spec from template with unique ID |
 | `specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
 | `specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
@@ -36,6 +56,8 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 | `specsafe-status` | Show project dashboard with all specs and metrics |
 | `specsafe-archive <id>` | Archive an obsolete spec with reason |
 | `specsafe-doctor` | Validate project health and diagnose issues |
+| `specsafe-context` | Gather and present project context for AI agents |
+| `specsafe-skill-creator` | Create new SpecSafe skills with proper structure |
 
 ## Project Constraints
 
@@ -43,6 +65,7 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
 3. **Tests define implementation** — code exists only to make tests pass
 4. **One spec at a time** — complete or park a spec before starting another
-5. **No stage skipping** — every spec must progress through all 5 stages in order
+5. **No stage skipping** — every spec must progress through all 5 development stages in order
 6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
 7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119
+8. **Planning precedes development** — reduce ambiguity before writing code

package/canonical/rules/CLAUDE.md

@@ -1,16 +1,32 @@
-# SpecSafe — TDD Workflow Rules
+# SpecSafe — Two-Phase Workflow Rules
 
-SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+SpecSafe is a two-phase software engineering framework. Phase 1 (Planning) reduces ambiguity before implementation. Phase 2 (Development) enforces strict test-driven execution through small spec slices. No stage may be skipped. Each stage has a dedicated skill and persona.
 
-## Workflow Stages
+## Phase 1: Planning
+
+Planning precedes development. Each step produces an artifact that informs the next.
+
+| Step | Skill | What Happens |
+|------|-------|--------------|
+| 1 | `specsafe-brainstorm` | Divergent exploration of possibilities |
+| 2 | `specsafe-principles` | Product principles, non-goals, quality priorities |
+| 3 | `specsafe-brief` | Concise product/business framing document |
+| 4 | `specsafe-prd` | Testable requirements with user journeys and acceptance criteria |
+| 5 | `specsafe-ux` | UX design: tokens, components, flows, accessibility |
+| 6 | `specsafe-architecture` | System architecture with ADRs and technology decisions |
+| 7 | `specsafe-readiness` | Pre-development coherence check |
+
+Canonical order: brainstorm → principles → brief → PRD → UX → architecture → readiness. UX always precedes architecture.
+
+## Phase 2: Development Stages
 
 | Stage | Skill | Persona | What Happens |
-|-------|-------|---------|--------------|
-| SPEC | `/specsafe-new`, `/specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
-| TEST | `/specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
-| CODE | `/specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
-| QA | `/specsafe-verify`, `/specsafe-qa` | Warden (Lyra) | Validate tests pass, check coverage, generate QA report |
-| COMPLETE | `/specsafe-complete` | Herald (Cass) | Human approval gate, move to completed |
+|-------|-------|---------|--------------| 
+| SPEC | `specsafe-new`, `specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
+| TEST | `specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
+| CODE | `specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
+| QA | `specsafe-verify`, `specsafe-qa` | Warden (Lyra) | Validate tests pass, check coverage, generate QA report |
+| COMPLETE | `specsafe-complete` | Herald (Cass) | Human approval gate, move to completed |
 
 ## Key Files
 
@@ -24,18 +40,24 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 
 | Skill | Description |
 |-------|-------------|
-| `/specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
-| `/specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
-| `/specsafe-new <name>` | Create a new spec from template with unique ID |
-| `/specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
-| `/specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
-| `/specsafe-code <id>` | Implement code via TDD to pass tests (TEST → CODE) |
-| `/specsafe-verify <id>` | Run tests and validate against spec (CODE → QA) |
-| `/specsafe-qa <id>` | Generate full QA report with GO/NO-GO recommendation |
-| `/specsafe-complete <id>` | Complete spec with human approval (QA → COMPLETE) |
-| `/specsafe-status` | Show project dashboard with all specs and metrics |
-| `/specsafe-archive <id>` | Archive an obsolete spec with reason |
-| `/specsafe-doctor` | Validate project health and diagnose issues |
+| `specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
+| `specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `specsafe-brief` | Create a concise product brief |
+| `specsafe-prd` | Expand brief into full PRD with user journeys and requirements |
+| `specsafe-ux` | UX design foundations — tokens, components, accessibility, flows |
+| `specsafe-architecture` | System architecture — components, data model, ADRs |
+| `specsafe-new <name>` | Create a new spec from template with unique ID |
+| `specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
+| `specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
+| `specsafe-code <id>` | Implement code via TDD to pass tests (TEST → CODE) |
+| `specsafe-verify <id>` | Run tests and validate against spec (CODE → QA) |
+| `specsafe-qa <id>` | Generate full QA report with GO/NO-GO recommendation |
+| `specsafe-complete <id>` | Complete spec with human approval (QA → COMPLETE) |
+| `specsafe-status` | Show project dashboard with all specs and metrics |
+| `specsafe-archive <id>` | Archive an obsolete spec with reason |
+| `specsafe-doctor` | Validate project health and diagnose issues |
+| `specsafe-context` | Gather and present project context for AI agents |
+| `specsafe-skill-creator` | Create new SpecSafe skills with proper structure |
 
 ## Project Constraints
 
@@ -43,6 +65,7 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
 3. **Tests define implementation** — code exists only to make tests pass
 4. **One spec at a time** — complete or park a spec before starting another
-5. **No stage skipping** — every spec must progress through all 5 stages in order
+5. **No stage skipping** — every spec must progress through all 5 development stages in order
 6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
 7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119
+8. **Planning precedes development** — reduce ambiguity before writing code

package/canonical/rules/CONVENTIONS.md

@@ -1,6 +1,21 @@
 # SpecSafe Conventions
 
-## TDD Workflow (5 Stages)
+## Two-Phase Workflow
+
+SpecSafe uses a two-phase model: Planning reduces ambiguity, then Development enforces test-driven execution.
+
+### Phase 1: Planning
+
+Canonical order: brainstorm → principles → brief → PRD → UX → architecture → readiness.
+
+- **Brainstorm**: Divergent exploration- **Principles**: Product principles and non-goals- **Brief**: Concise product/business framing (`specsafe-brief`)
+- **PRD**: Testable requirements with user journeys (`specsafe-prd`)
+- **UX**: Design foundations, tokens, accessibility (`specsafe-ux`)
+- **Architecture**: System design with ADRs (`specsafe-architecture`)
+- **Readiness**: Pre-development coherence check
+UX always precedes architecture. Planning precedes development.
+
+### Phase 2: Development (5 Stages)
 
 Every feature follows: **SPEC → TEST → CODE → QA → COMPLETE**. No skipping.
 
@@ -16,21 +31,36 @@ Every feature follows: **SPEC → TEST → CODE → QA → COMPLETE**. No skippi
 - `specs/active/` — Active specs. `specs/completed/` — Done. `specs/archive/` — Obsolete.
 - `specsafe.config.json` — Project config (test framework, language, tools).
 
-## 12 Skills
-
-1. `specsafe-init` — Initialize project
-2. `specsafe-explore` — Pre-spec research
-3. `specsafe-new <name>` — Create new spec
-4. `specsafe-spec <id>` — Refine spec
-5. `specsafe-test <id>` — Generate tests (SPEC → TEST)
-6. `specsafe-code <id>` — Implement via TDD (TEST → CODE)
-7. `specsafe-verify <id>` — Validate implementation (CODE → QA)
-8. `specsafe-qa <id>` — Full QA report
-9. `specsafe-complete <id>` — Complete spec (QA → COMPLETE)
-10. `specsafe-status` — Project dashboard
-11. `specsafe-archive <id>` — Archive obsolete spec
-12. `specsafe-doctor` — Validate project health
+## 18 Skills
+
+### Planning
+1. `specsafe-brief` — Create product brief
+2. `specsafe-prd` — Expand brief into PRD
+3. `specsafe-ux` — UX design foundations
+4. `specsafe-architecture` — System architecture
+
+### Development
+5. `specsafe-new <name>` — Create new spec
+6. `specsafe-spec <id>` — Refine spec
+7. `specsafe-test <id>` — Generate tests (SPEC → TEST)
+8. `specsafe-code <id>` — Implement via TDD (TEST → CODE)
+9. `specsafe-verify <id>` — Validate implementation (CODE → QA)
+10. `specsafe-qa <id>` — Full QA report
+11. `specsafe-complete <id>` — Complete spec (QA → COMPLETE)
+
+### Utility
+12. `specsafe-init` — Initialize project
+13. `specsafe-explore` — Pre-spec research
+14. `specsafe-context` — Gather project context
+15. `specsafe-status` — Project dashboard
+16. `specsafe-archive <id>` — Archive obsolete spec
+17. `specsafe-doctor` — Validate project health
+18. `specsafe-skill-creator` — Create new skills
 
+### Planning (continued)
+19. `specsafe-brainstorm` — Divergent exploration
+20. `specsafe-principles` — Product principles
+21. `specsafe-readiness` — Pre-development coherence check
 ## Rules
 
 - Always read `PROJECT_STATE.md` before any operation
@@ -39,3 +69,4 @@ Every feature follows: **SPEC → TEST → CODE → QA → COMPLETE**. No skippi
 - One spec at a time
 - Evidence required for all QA verdicts
 - Requirements use SHALL/MUST/SHOULD (RFC 2119)
+- Planning precedes development — reduce ambiguity before writing code

package/canonical/rules/GEMINI.md

@@ -1,11 +1,27 @@
-# SpecSafe — TDD Workflow Rules
+# SpecSafe — Two-Phase Workflow Rules
 
-SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TEST → CODE → QA → COMPLETE**. No stage may be skipped. Each stage has a dedicated skill and persona.
+SpecSafe is a two-phase software engineering framework. Phase 1 (Planning) reduces ambiguity before implementation. Phase 2 (Development) enforces strict test-driven execution through small spec slices. No stage may be skipped. Each stage has a dedicated skill and persona.
 
-## Workflow Stages
+## Phase 1: Planning
+
+Planning precedes development. Each step produces an artifact that informs the next.
+
+| Step | Skill | What Happens |
+|------|-------|--------------|
+| 1 | `specsafe-brainstorm` | Divergent exploration of possibilities |
+| 2 | `specsafe-principles` | Product principles, non-goals, quality priorities |
+| 3 | `specsafe-brief` | Concise product/business framing document |
+| 4 | `specsafe-prd` | Testable requirements with user journeys and acceptance criteria |
+| 5 | `specsafe-ux` | UX design: tokens, components, flows, accessibility |
+| 6 | `specsafe-architecture` | System architecture with ADRs and technology decisions |
+| 7 | `specsafe-readiness` | Pre-development coherence check |
+
+Canonical order: brainstorm → principles → brief → PRD → UX → architecture → readiness. UX always precedes architecture.
+
+## Phase 2: Development Stages
 
 | Stage | Skill | Persona | What Happens |
-|-------|-------|---------|--------------|
+|-------|-------|---------|--------------| 
 | SPEC | `specsafe-new`, `specsafe-spec` | Mason (Kai) | Create and refine specification with requirements and scenarios |
 | TEST | `specsafe-test` | Forge (Reva) | Generate test files from spec scenarios (all tests fail) |
 | CODE | `specsafe-code` | Bolt (Zane) | Implement code using TDD red-green-refactor |
@@ -26,6 +42,10 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 |-------|-------------|
 | `specsafe-init` | Initialize a new SpecSafe project with directory structure and config |
 | `specsafe-explore` | Pre-spec research, spikes, and feasibility assessment |
+| `specsafe-brief` | Create a concise product brief |
+| `specsafe-prd` | Expand brief into full PRD with user journeys and requirements |
+| `specsafe-ux` | UX design foundations — tokens, components, accessibility, flows |
+| `specsafe-architecture` | System architecture — components, data model, ADRs |
 | `specsafe-new <name>` | Create a new spec from template with unique ID |
 | `specsafe-spec <id>` | Refine an existing spec with requirements and scenarios |
 | `specsafe-test <id>` | Generate test files from spec scenarios (SPEC → TEST) |
@@ -36,6 +56,8 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 | `specsafe-status` | Show project dashboard with all specs and metrics |
 | `specsafe-archive <id>` | Archive an obsolete spec with reason |
 | `specsafe-doctor` | Validate project health and diagnose issues |
+| `specsafe-context` | Gather and present project context for AI agents |
+| `specsafe-skill-creator` | Create new SpecSafe skills with proper structure |
 
 ## Project Constraints
 
@@ -43,8 +65,9 @@ SpecSafe enforces a strict 5-stage TDD workflow for every feature: **SPEC → TE
 2. **Never modify `PROJECT_STATE.md` directly** — only update it through skill workflows
 3. **Tests define implementation** — code exists only to make tests pass
 4. **One spec at a time** — complete or park a spec before starting another
-5. **No stage skipping** — every spec must progress through all 5 stages in order
+5. **No stage skipping** — every spec must progress through all 5 development stages in order
 6. **Evidence required** — QA verdicts require concrete test evidence, not assertions
 7. **Normative language** — specs use SHALL/MUST/SHOULD per RFC 2119
+8. **Planning precedes development** — reduce ambiguity before writing code
 
 @import AGENTS.md

package/canonical/rules/continue-config.yaml

@@ -1,4 +1,4 @@
-name: SpecSafe TDD
+name: SpecSafe Two-Phase Workflow
 version: 1.0.0
 schema: v1
 rules:

package/canonical/skills/specsafe-architecture/workflow.md

@@ -225,7 +225,7 @@ Summary:
   Architecture decisions: [count] ADRs
   Technology stack: [brief summary, e.g., "TypeScript + Next.js + PostgreSQL + Vercel"]
 
-Next: Run /specsafe-ux to define UX design principles, or /specsafe-new to start creating feature specs.
+Next: Run /specsafe-readiness to validate planning coherence before development begins (or /specsafe-new if readiness is not yet available).
 ```
 
 ## State Changes
@@ -245,4 +245,4 @@ Next: Run /specsafe-ux to define UX design principles, or /specsafe-new to start
 
 ## Handoff
 
-Next skill: `/specsafe-ux` to define UX design principles, or `/specsafe-new` to start creating feature specs informed by the architecture.
+Next skill: `/specsafe-readiness` to validate planning coherence before development begins (or `/specsafe-new` if readiness is not yet available). UX is upstream of architecture — it should already be complete before this skill runs.

package/canonical/skills/specsafe-brainstorm/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: specsafe-brainstorm
+description: Facilitate structured brainstorming sessions for product, feature, workflow, or system ideas. The entry point for ambiguous ideas before they become principles or briefs.
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.