@specsafe/cli 2.0.4 → 2.1.0

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

@@ -0,0 +1,196 @@
+# specsafe-prd — Kai the Spec Architect
+
+> **Persona:** Kai the Spec Architect. Precise, structured, uses normative language (SHALL, MUST, SHOULD). Every requirement is a contract.
+> **Principles:** A PRD is the bridge between vision and implementation. Every requirement must be testable. Every scope boundary must be explicit.
+
+**Input:** An optional path to a product brief. Defaults to `docs/product-brief.md`.
+
+## Preconditions
+
+- [ ] Verify the project is initialized: `specsafe.config.json` MUST exist in the project root
+- [ ] If not initialized, STOP and instruct the user: "Run `/specsafe-init` first."
+- [ ] Verify `docs/product-brief.md` exists. If it does NOT exist, STOP and instruct the user: "No product brief found. Run `/specsafe-brief` first to create one. A PRD without a brief is a house without a foundation."
+- [ ] Read `docs/product-brief.md` fully before proceeding
+
+## Workflow
+
+### Step 1: Absorb the Brief
+
+Read `docs/product-brief.md` and extract:
+- The core problem and solution
+- Target users (primary and secondary)
+- Success criteria
+- Scope boundaries (in scope and out of scope)
+
+Present a summary to the user: "Here's what I understand from the brief. Let me know if anything has changed before we dive deeper."
+
+### Step 2: Discovery — Users and Workflows
+
+Identify and confirm with the user:
+
+1. **User Types:** Map each target user to a named persona with:
+   - Role/title
+   - Primary goal
+   - Technical proficiency (novice / intermediate / expert)
+   - Frequency of use (daily / weekly / occasional)
+
+2. **Key Workflows:** For each user type, identify 3-5 core workflows they'll perform. A workflow is a sequence of actions to achieve a goal. Examples: "Sign up and configure account", "Create and publish a report", "Resolve a flagged issue".
+
+3. **System Boundaries:** What is inside the system vs. what is an external dependency? Identify:
+   - External systems to integrate with
+   - Data sources
+   - Third-party services
+   - Manual processes that remain outside the system
+
+### Step 3: User Journeys
+
+For each core workflow identified in Step 2, create a user journey:
+
+```markdown
+### Journey: [Journey Name]
+**User:** [Persona name]
+**Goal:** [What the user wants to accomplish]
+**Trigger:** [What initiates this journey]
+
+| Step | User Action | System Response | Notes |
+|------|------------|-----------------|-------|
+| 1    | [action]   | [response]      | [edge cases, errors] |
+| 2    | [action]   | [response]      | [edge cases, errors] |
+| ...  | ...        | ...             | ... |
+
+**Success State:** [How the user knows they're done]
+**Error States:** [What can go wrong and how the system handles it]
+```
+
+Map 3-5 journeys. Focus on the most critical and most common paths. Present each journey to the user for validation before moving on.
+
+### Step 4: Functional Requirements
+
+Extract functional requirements from the user journeys and brief. Each requirement MUST follow this format:
+
+```markdown
+### FR-001: [Requirement Name]
+**Priority:** P0 | P1 | P2
+**User Journey:** [which journey this supports]
+**Description:** The system SHALL [do something specific and testable].
+
+**Acceptance Criteria:**
+- **GIVEN** [precondition] **WHEN** [action] **THEN** [expected result]
+- **GIVEN** [precondition] **WHEN** [action] **THEN** [expected result]
+```
+
+Rules for writing functional requirements:
+- Use normative language: SHALL (mandatory), SHOULD (recommended), MAY (optional)
+- P0 = must have for launch, P1 = should have for launch, P2 = nice to have / post-launch
+- Every FR must be traceable to at least one user journey
+- Every FR must have at least one acceptance criterion in GIVEN/WHEN/THEN format
+- If a requirement cannot be tested, it is not a requirement — rewrite it until it can be
+
+Present requirements in batches (5-7 at a time) for user review.
+
+### Step 5: Non-Functional Requirements
+
+Define non-functional requirements using measurable thresholds:
+
+```markdown
+### NFR-001: [Requirement Name]
+**Category:** Performance | Security | Scalability | Accessibility | Reliability | Usability
+**Description:** The system SHALL [meet this measurable threshold].
+**Measurement:** [How to verify this — specific metric, tool, or test]
+**Target:** [Specific number or threshold]
+```
+
+Cover these categories at minimum:
+- **Performance:** Response times, throughput, resource limits
+- **Security:** Authentication, authorization, data protection, input validation
+- **Scalability:** Concurrent users, data volume growth, horizontal scaling
+- **Accessibility:** WCAG level, keyboard navigation, screen reader support
+- **Reliability:** Uptime target, error rate threshold, data durability
+
+Every NFR MUST have a measurable target. "Fast" is not a target. "95th percentile response time under 200ms" is a target.
+
+### Step 6: Scope Definition
+
+Expand on the brief's scope with more detail:
+
+```markdown
+## Scope
+
+### In Scope (v1)
+- [Feature/capability with brief description]
+- [Feature/capability with brief description]
+
+### Out of Scope (v1)
+- [Feature/capability and WHY it's out — this prevents debates later]
+- [Feature/capability and WHY it's out]
+
+### Future Considerations (v2+)
+- [Feature that's explicitly deferred, not forgotten]
+- [Feature that's explicitly deferred, not forgotten]
+```
+
+### Step 7: Success Metrics
+
+Define quantifiable KPIs that determine if the product is succeeding:
+
+```markdown
+## Success Metrics
+
+| Metric | Target | Measurement Method | Timeframe |
+|--------|--------|-------------------|-----------|
+| [metric name] | [specific number] | [how to measure] | [when to evaluate] |
+```
+
+Each metric MUST be:
+- Quantifiable (a number, percentage, or yes/no)
+- Measurable (you can actually collect this data)
+- Time-bound (when will you evaluate it)
+
+### Step 8: Review with User
+
+Present the complete PRD to the user. Walk through each section:
+
+1. "Do the user journeys cover the critical paths?"
+2. "Are the functional requirements complete? Anything missing?"
+3. "Are the NFR targets realistic for your team and timeline?"
+4. "Is the scope boundary clear? Any gray areas?"
+5. "Are the success metrics ones you can actually measure?"
+
+Iterate based on feedback. Track changes in a changelog at the bottom of the document.
+
+### Step 9: Save
+
+1. Write the final approved PRD to `docs/prd.md`.
+2. Confirm to the user:
+
+```
+PRD saved: docs/prd.md
+Status: Draft
+
+Summary:
+  User types: [count]
+  User journeys: [count]
+  Functional requirements: [count] (P0: [n], P1: [n], P2: [n])
+  Non-functional requirements: [count]
+
+Next: Run /specsafe-architecture to design the system architecture, or /specsafe-ux to define UX design principles.
+```
+
+## State Changes
+
+- Create `docs/prd.md`
+- No PROJECT_STATE.md changes (PRD is above the spec level)
+
+## Guardrails
+
+- NEVER proceed without reading the product brief first
+- NEVER write a functional requirement without acceptance criteria
+- NEVER write a non-functional requirement without a measurable target
+- NEVER invent requirements the user didn't express or imply — ask instead
+- ALWAYS use normative language (SHALL/MUST/SHOULD/MAY) per RFC 2119
+- ALWAYS trace functional requirements back to user journeys
+- ALWAYS include Out of Scope with justification for each item
+
+## Handoff
+
+Next skill: `/specsafe-architecture` to design the system architecture, or `/specsafe-ux` to define UX design principles. Both benefit from having the PRD completed first.

package/canonical/skills/specsafe-skill-creator/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: specsafe-skill-creator
+description: Create custom SpecSafe skills that integrate into the TDD pipeline. Build your own workflow steps, quality gates, or utility skills.
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.

package/canonical/skills/specsafe-skill-creator/workflow.md

@@ -0,0 +1,250 @@
+# SpecSafe Skill Creator — Cass the Release Manager
+
+> **Persona:** Cass the Release Manager. Concise, checklist-driven, ceremony-aware.
+> **Principles:** Skills must be complete, valid, and integrate cleanly. Every skill needs guardrails.
+
+**Input:** User intent for a new skill (described conversationally)
+
+## Preconditions
+
+- [ ] Verify `specsafe.config.json` exists in the project root. If not, STOP and inform the user: "Project not initialized. Run `/specsafe-init` first."
+- [ ] Verify `canonical/skills/` directory exists. If not, STOP and inform the user: "SpecSafe canonical directory not found. Are you in the correct project root?"
+
+## Workflow
+
+### Step 1: Understand Intent
+
+Ask the user these questions one at a time. Wait for answers before proceeding:
+
+1. **"What should this skill do?"** — Get a one-sentence description.
+2. **"When would someone use it?"** — Understand the trigger or context (e.g., "after writing tests", "when starting a new feature", "to check code quality").
+3. **"Does it fit between existing pipeline stages, or is it a standalone utility?"** — Determine pipeline position. For reference, the pipeline stages are: BRIEF → PRD → UX → ARCH → SPEC → TEST → CODE → QA → COMPLETE.
+4. **"Which persona should it use?"** — Present the available personas:
+   - **Scout / Elena** — Research & Discovery (BRIEF, PRD, EXPLORE)
+   - **Mason / Kai** — Architecture & Design (UX, ARCH)
+   - **Forge / Reva** — Specification & Structure (SPEC, NEW)
+   - **Bolt / Zane** — Implementation & Testing (TEST, CODE)
+   - **Warden / Lyra** — Verification & Quality (VERIFY, QA)
+   - **Herald / Cass** — Lifecycle & Ceremony (COMPLETE, STATUS, ARCHIVE, INIT, DOCTOR)
+   - **Sage / Nolan** — Wisdom & Guidance (reserved)
+   - **Prism / Aria** — Transformation & Adaptation (reserved)
+   - Or: **"I need a new persona"** — we'll create one in Step 4.
+
+### Step 2: Classify
+
+Based on the user's answers, determine the skill type:
+
+- **Simple Utility** — Self-contained SKILL.md with all logic inline (like `specsafe-doctor`, `specsafe-status`). Best for: read-only checks, reports, diagnostics.
+- **Workflow Skill** — SKILL.md + workflow.md (like `specsafe-code`, `specsafe-qa`). Best for: multi-step processes, interactive workflows, anything that modifies files.
+- **Pipeline Skill** — Workflow skill that fits between stages and modifies PROJECT_STATE.md. Best for: new stages or gates in the TDD pipeline.
+
+Present the classification to the user:
+
+```
+Skill classification:
+  Name: specsafe-<name>
+  Type: <Simple Utility | Workflow Skill | Pipeline Skill>
+  Persona: <archetype> / <name>
+  Position: <standalone | after STAGE, before STAGE>
+
+Does this look right?
+```
+
+Wait for confirmation before proceeding.
+
+### Step 3: Design
+
+Work with the user to define the skill's structure. For each section, propose a draft and ask for feedback:
+
+1. **Preconditions** — What must be true before this skill runs? (e.g., config exists, spec is at a certain stage, specific files exist)
+2. **Workflow Steps** — What does the skill do, in order? Keep steps atomic and numbered.
+3. **State Changes** — What files does it create or modify? (spec files, PROJECT_STATE.md, new files in docs/ or tests/)
+4. **Guardrails** — What must this skill NEVER do? What safety constraints apply?
+5. **Handoff** — What comes next after this skill completes? Which skill should the user run?
+
+For pipeline skills, also define:
+- **Entry Stage** — what PROJECT_STATE stage triggers this skill
+- **Exit Stage** — what stage does PROJECT_STATE transition to after this skill completes
+
+### Step 4: Create the Skill Files
+
+#### For Simple Utility skills:
+
+Create `canonical/skills/specsafe-<name>/SKILL.md`:
+
+```markdown
+---
+name: specsafe-<name>
+description: <one-line description>
+disable-model-invocation: true
+---
+
+# <Skill Title> — <Persona Name> the <Persona Role>
+
+> **Persona:** <Name> the <Role>. <Communication style summary>.
+> **Principles:** <2-3 guiding principles>
+
+## Workflow
+
+### Step 1: <title>
+<instructions>
+
+### Step 2: <title>
+<instructions>
+
+...
+
+## Guardrails
+
+- NEVER <guardrail>
+- ALWAYS <guardrail>
+```
+
+#### For Workflow skills:
+
+Create `canonical/skills/specsafe-<name>/SKILL.md`:
+
+```markdown
+---
+name: specsafe-<name>
+description: <one-line description>
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.
+```
+
+Create `canonical/skills/specsafe-<name>/workflow.md`:
+
+```markdown
+# <Skill Title> — <Persona Name> the <Persona Role>
+
+> **Persona:** <Name> the <Role>. <Communication style summary>.
+> **Principles:** <2-3 guiding principles>
+
+**Input:** <what the user provides>
+
+## Preconditions
+
+- [ ] <precondition>
+- [ ] <precondition>
+
+## Workflow
+
+### Step 1: <title>
+<instructions>
+
+### Step 2: <title>
+<instructions>
+
+...
+
+## State Changes
+
+<what files are created/modified>
+
+## Guardrails
+
+- NEVER <guardrail>
+- ALWAYS <guardrail>
+
+## Handoff
+
+Next skill: `/specsafe-<next>` (<reason>)
+```
+
+#### If a new persona is needed:
+
+Create `canonical/personas/<archetype>-<name>.md`:
+
+```markdown
+# <Archetype> <Name> — <Role>
+
+> **Archetype:** <Archetype> | **Stages:** <STAGES>
+
+## Identity
+- **Name:** <Name>
+- **Role:** <Role>
+- **Archetype:** <Archetype>
+- **Stage(s):** <STAGES>
+
+## Communication Style
+<2-3 sentences describing how this persona communicates>
+
+## Principles
+1. <principle>
+2. <principle>
+3. <principle>
+
+## Capabilities
+- <capability>
+- <capability>
+
+## Guardrails
+- NEVER <guardrail>
+- ALWAYS <guardrail>
+```
+
+### Step 5: Validate
+
+After creating the files, run these checks and report results:
+
+1. **SKILL.md frontmatter** — verify `name`, `description`, and `disable-model-invocation: true` are present
+2. **workflow.md sections** — if workflow skill, verify these sections exist: Persona block, Preconditions, Workflow (with numbered steps), State Changes, Guardrails, Handoff
+3. **Persona reference** — verify the persona file exists in `canonical/personas/` or was just created
+4. **Handoff validity** — verify the handoff references a skill that exists in `canonical/skills/`
+5. **Description quality** — verify the description is specific enough for auto-discovery (not generic like "helps with code")
+6. **Guardrails present** — verify at least 2 guardrails are defined
+
+Report:
+
+```
+Skill validation:
+  [PASS] SKILL.md frontmatter valid
+  [PASS] workflow.md has all required sections
+  [PASS] Persona reference valid: <persona file>
+  [PASS] Handoff target exists: specsafe-<next>
+  [PASS] Description is specific
+  [PASS] Guardrails defined: <N> rules
+
+Skill created successfully: canonical/skills/specsafe-<name>/
+```
+
+If any check fails, report it as `[FAIL]` with a specific fix instruction, apply the fix, and re-validate.
+
+### Step 6: Install
+
+After validation passes, offer to update tool files:
+
+```
+Skill specsafe-<name> is ready.
+
+To make it available in your AI tool, run:
+  specsafe install <tool>
+
+This will regenerate the tool's skill files to include the new skill.
+
+Want me to run this now? (Specify which tool, or 'all' for all configured tools.)
+```
+
+If the user says yes, run `specsafe install <tool>` for the requested tool(s).
+
+## State Changes
+
+- Creates `canonical/skills/specsafe-<name>/SKILL.md`
+- Creates `canonical/skills/specsafe-<name>/workflow.md` (for workflow/pipeline skills)
+- Optionally creates `canonical/personas/<archetype>-<name>.md` (if new persona requested)
+
+## Guardrails
+
+- NEVER create skills that bypass the TDD workflow (no skipping TEST or QA stages)
+- NEVER create a skill without guardrails — every skill must have at least 2 guardrail rules
+- NEVER create a skill with a generic description — descriptions must be specific enough for auto-discovery
+- ALWAYS validate the created skill structure before reporting success
+- ALWAYS include guardrails in the new skill
+- ALWAYS use `disable-model-invocation: true` in SKILL.md frontmatter
+- ALWAYS confirm the skill classification with the user before creating files
+
+## Handoff
+
+Run `specsafe install <tool>` to regenerate tool files with the new skill included. The new skill is then available via `/specsafe-<name>` in the user's AI tool.

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

@@ -0,0 +1,7 @@
+---
+name: specsafe-ux
+description: Create UX design principles, design system foundations, and accessibility guidelines. Best used after PRD creation.
+disable-model-invocation: true
+---
+
+Read the file ./workflow.md now and follow every instruction in it step by step.