catalyst-os 0.2.6 → 0.3.0

package/.claude/commands/iterate-spec.md

@@ -0,0 +1,492 @@
+# /iterate-spec
+
+Continue building a spec with new improvements, ideas, or enhancements discovered during development.
+
+---
+
+## FORGE-MASTER BEHAVIORAL RULES
+
+**You are an ORCHESTRATOR. You coordinate work, you do NOT do work.**
+
+```
+BEFORE writing ANY code or test:
+  → STOP
+  → Ask yourself: "Should a specialized agent do this?"
+  → If YES: Use Task tool with appropriate subagent_type
+  → If NO: You're probably wrong. Use the Task tool.
+
+You may ONLY:
+  ✓ Read files to understand context
+  ✓ Use Task tool to spawn agents (oracle, scribe, forger, enforcer, smith, shaper, alchemist)
+  ✓ Run test commands to verify gates
+  ✓ Report status to user
+
+You may NEVER:
+  ✗ Write code (use smith or shaper)
+  ✗ Write tests (use enforcer)
+  ✗ Create task breakdowns (use forger)
+  ✗ Write database schemas (use alchemist)
+  ✗ Update spec documentation (use scribe)
+
+IF YOU ARE ABOUT TO USE Edit/Write TOOL ON A .py/.ts/.js/.md FILE → STOP → SPAWN AN AGENT
+```
+
+---
+
+## Usage
+
+```
+/iterate-spec @2025-11-29-stripe-integration "add support for annual billing with 20% discount"
+/iterate-spec @2025-11-29-stripe-integration "handle the edge case where user cancels mid-checkout"
+/iterate-spec @2025-11-29-stripe-integration "improve error messages for failed payments"
+```
+
+## When to Use
+
+Use `/iterate-spec` when you're **in the middle of building** and:
+- You discovered a better approach during testing
+- You thought of an improvement or enhancement
+- You found an edge case that should be handled
+- You want to add something that makes the feature better
+
+**NOT for bugs** - bugs are implementation issues, not spec changes.
+**NOT for missing requirements** - if the spec was incomplete, use `/update-spec` first.
+
+---
+
+## Prerequisites
+
+- Spec must exist in `.catalyst/specs/`
+- Build has been started (tasks.md exists)
+- You're on the feature branch (from `/build-spec`)
+
+---
+
+## KEY DIFFERENCE FROM OTHER COMMANDS
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  /update-spec  →  Updates docs  →  STOPS  →  Manual /build-spec │
+│                                                                 │
+│  /iterate-spec →  Updates docs  →  CONTINUES BUILDING           │
+│                   (Single continuous flow, no context loss)     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## GIT WORKFLOW
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  GIT CHECKPOINTS                                                │
+│  ───────────────                                                │
+│                                                                 │
+│  PHASE 0: Verify Branch                                         │
+│  └── Confirm on feature branch: {branch_prefix}/{spec-slug}     │
+│                                                                 │
+│  GATE 1: RED FLAG (for new tests)                               │
+│  └── Commit: "test({scope}): add tests for {improvement}"       │
+│                                                                 │
+│  GATE 2: GREEN FLAG                                             │
+│  └── Commit: "feat({scope}): {improvement description}"         │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## TDD IS MANDATORY - NO EXCEPTIONS
+
+```
+  IMPLEMENTATION WITHOUT TESTS IS FORBIDDEN
+
+  The iteration MUST follow this exact sequence:
+
+  1. Task(subagent_type="scribe")    -> Update spec.md
+  2. Task(subagent_type="forger")    -> Add new tasks to tasks.md
+  3. Task(subagent_type="enforcer")  -> Write tests for NEW tasks (must FAIL)
+  4. Verify                          -> Run tests, confirm RED for new tests
+  5. Task(subagent_type="smith/shaper/alchemist") -> Implement until GREEN
+```
+
+---
+
+## ORCHESTRATION MODE
+
+Forge-Master spawns specialized agents using the **Task tool**. Each phase is a separate agent.
+
+### Output Location
+
+All outputs go to the existing spec folder. See AGENTS.md "Documentation Output Policy".
+
+```
+.catalyst/specs/YYYY-MM-DD-{slug}/
+├── spec.md           # Scribe updates with new requirement
+├── research.md       # Scribe appends if needed
+├── tasks.md          # Forger adds new tasks
+├── validation.md     # (unchanged until /validate-spec)
+└── handoff.md        # (regenerated on completion)
+```
+
+### Execution Order
+
+```
+Phase 1: Clarify (Oracle - if needed)
+              |
+Phase 2: Update Spec (Scribe)
+              |
+Phase 3: Update Tasks (Forger)
+              |
+Phase 4: Write Tests (Enforcer) - NEW tasks only
+              |
+         GATE 1: RED PHASE - New tests must FAIL
+              |
+Phase 5: Implement (Smith/Shaper/Alchemist)
+              |
+         GATE 2: GREEN PHASE - All tests must PASS
+```
+
+---
+
+## Workflow
+
+### Phase 0: Verify State
+
+**Before any work begins, verify we're in the right state.**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  📍 STATE VERIFICATION                                          │
+│  ────────────────────                                           │
+│                                                                 │
+│  1. Verify on feature branch:                                   │
+│     $ git branch --show-current                                 │
+│     Expected: {branch_prefix}/{spec-slug}                       │
+│                                                                 │
+│  2. Read existing spec files:                                   │
+│     - spec.md (current requirements)                            │
+│     - tasks.md (current tasks and progress)                     │
+│                                                                 │
+│  3. If NOT on feature branch:                                   │
+│     → Ask user if they want to checkout the branch              │
+│     → Or if they need to run /build-spec first                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Phase 1: Clarify Improvement (Oracle - Optional)
+
+**If the improvement description is vague, spawn Oracle to clarify.**
+
+**Spawn Oracle agent** using `Task` tool with `subagent_type="oracle"`:
+
+```
+"Clarify this improvement for spec {slug}:
+'{improvement description}'
+
+Current spec is in spec.md. Ask focused questions to understand:
+- What exactly should change?
+- What's the expected behavior?
+- Are there edge cases to consider?
+
+Keep it brief - this is an iteration, not a new spec."
+```
+
+**Skip this phase if the improvement is already clear and specific.**
+
+---
+
+### Phase 2: Update Specification (Scribe)
+
+**Spawn Scribe agent** using `Task` tool with `subagent_type="scribe"`:
+
+```
+"Update spec.md for spec {slug} with this improvement:
+'{improvement description}'
+
+Tasks:
+1. Add new requirement(s) to Requirements section
+2. Update Changelog with date and description
+3. If technical research needed, append to research.md
+4. Keep Status as IN_PROGRESS
+
+Do NOT change existing completed requirements.
+Mark this as an ITERATION, not a new feature."
+```
+
+**WAIT for Scribe to complete before proceeding to Phase 3.**
+
+---
+
+### Phase 3: Update Tasks (Forger)
+
+**Spawn Forger agent** using `Task` tool with `subagent_type="forger"`:
+
+```
+"Update tasks.md for spec {slug} with new tasks for:
+'{improvement description}'
+
+Tasks:
+1. Read current tasks.md and identify completed vs pending tasks
+2. Add NEW tasks for the improvement (prefix with ITERATION marker)
+3. Update Build DAG with new task dependencies
+4. Place new tasks in appropriate phase (foundation/contracts/parallel)
+5. Do NOT modify completed tasks
+
+New tasks should be marked with:
+| ID | Agent | Scope | Depends On | Status |
+| iter-001 | {agent} | {scope} | {deps} | pending |
+"
+```
+
+**WAIT for Forger to complete before proceeding to Phase 4.**
+
+---
+
+### Phase 4: Write Tests for New Tasks (Enforcer) - RED PHASE
+
+**CRITICAL: Only write tests for the NEW iteration tasks.**
+
+**Spawn Enforcer agent** using `Task` tool with `subagent_type="enforcer"`:
+
+```
+"Write failing tests for NEW iteration tasks in tasks.md.
+Look for tasks with 'iter-' prefix or marked as new.
+
+Tests go in project test folders (src/__tests__/, tests/, etc.).
+Update tasks.md Progress section with test file locations.
+
+Do NOT modify existing tests.
+New tests MUST fail (we haven't implemented yet)."
+```
+
+**WAIT for Enforcer to complete before proceeding to Gate 1.**
+
+---
+
+### GATE 1: Red Phase Verification (RED FLAG)
+
+**STOP! Before implementing:**
+
+```bash
+# Run tests for new iteration tasks
+npm test -- --grep "iter-"  # or appropriate filter
+
+# Expected: New tests FAIL, existing tests still PASS
+```
+
+**Gate Checklist:**
+- [ ] Every new task has at least one test
+- [ ] All NEW tests FAIL
+- [ ] All EXISTING tests still PASS (no regression)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🚩 RED FLAG COMMIT                                             │
+│  ─────────────────                                              │
+│                                                                 │
+│  After Gate 1 passes, commit the new tests:                     │
+│                                                                 │
+│  $ git add .                                                    │
+│  $ git commit -m "test({scope}): add tests for {improvement}"   │
+│                                                                 │
+│  Example:                                                       │
+│  git commit -m "test(billing): add tests for annual discount"   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Phase 5: Implement New Tasks (Smith/Shaper/Alchemist)
+
+**Only start this phase AFTER Gate 1 passes!**
+
+**Spawn appropriate agents based on task types in tasks.md.**
+
+For database tasks, **spawn Alchemist**:
+```
+"Implement iter-db-* tasks.
+SCOPE (write): {from tasks.md}
+Run tests after to verify progress."
+```
+
+For backend tasks, **spawn Smith**:
+```
+"Implement iter-api-* tasks.
+SCOPE (write): {from tasks.md}
+READS (no modify): src/types/**
+Run tests after each change."
+```
+
+For frontend tasks, **spawn Shaper**:
+```
+"Implement iter-ui-* tasks.
+SCOPE (write): {from tasks.md}
+READS (no modify): src/types/**, src/components/shared/**
+Run tests after each change."
+```
+
+**Parallel execution allowed if tasks have non-overlapping scopes.**
+
+---
+
+### GATE 2: Green Phase Verification (GREEN FLAG)
+
+**Before completing iteration:**
+
+```bash
+# Run ALL tests - they MUST pass
+npm test
+
+# Expected output:
+# Tests: XX passed, 0 failed
+# Status: GREEN
+```
+
+**Gate Checklist:**
+- [ ] All new iteration tests PASS
+- [ ] All existing tests still PASS
+- [ ] No regressions introduced
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🟢 GREEN FLAG COMMIT                                           │
+│  ───────────────────                                            │
+│                                                                 │
+│  After Gate 2 passes, commit the implementation:                │
+│                                                                 │
+│  $ git add .                                                    │
+│  $ git commit -m "feat({scope}): {improvement description}"     │
+│                                                                 │
+│  Example:                                                       │
+│  git commit -m "feat(billing): add annual billing with 20% discount"
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Output
+
+```
+Iteration complete!
+
+Spec: 2025-11-29-stripe-integration
+Branch: feat/2025-11-29-stripe-integration
+Improvement: "add annual billing with 20% discount"
+
+Git Commits:
+┌────────────────────────────────────────────────────────────────┐
+│ 🚩 abc1234 test(billing): add tests for annual discount        │
+│ 🟢 def5678 feat(billing): add annual billing with 20% discount │
+└────────────────────────────────────────────────────────────────┘
+
+Changes Made:
+- spec.md: Added REQ-011 (annual billing requirement)
+- tasks.md: Added 3 new tasks (iter-001, iter-002, iter-003)
+- New tests: 8 tests written, all passing
+- Implementation: 4 files modified
+
+TDD Compliance: VERIFIED
+- New tests written before implementation
+- All tests passing (existing + new)
+
+Updated: .catalyst/specs/2025-11-29-stripe-integration/
+├── spec.md (new requirement added)
+├── tasks.md (new tasks added)
+└── research.md (unchanged)
+
+Next: Continue testing, or run another /iterate-spec
+      When ready: /validate-spec @2025-11-29-stripe-integration
+```
+
+---
+
+## Failure Modes
+
+### If Not on Feature Branch
+
+```
+PROBLEM: Not on the spec's feature branch
+ACTION:  Either checkout the branch:
+         $ git checkout feat/{spec-slug}
+
+         Or if build hasn't started:
+         $ /build-spec @{spec-slug}
+```
+
+### If Spec Not Found
+
+```
+PROBLEM: Spec doesn't exist in .catalyst/specs/
+ACTION:  Create the spec first:
+         $ /catalyze-spec "your feature description"
+```
+
+### If Tasks.md Doesn't Exist
+
+```
+PROBLEM: No tasks.md found - build hasn't started
+ACTION:  Run /build-spec first to create initial tasks
+         $ /build-spec @{spec-slug}
+```
+
+### If Improvement Conflicts with Existing
+
+```
+PROBLEM: New requirement conflicts with completed work
+ACTION:  Spawn Oracle to discuss with user
+         Options:
+         1. Modify approach to avoid conflict
+         2. Accept rework of completed tasks
+         3. Create follow-up spec instead
+```
+
+### If New Tests Pass Immediately
+
+```
+PROBLEM: New tests pass before implementation
+ACTION:  Tests are wrong - they're testing existing behavior
+         Delete and rewrite tests for the NEW functionality
+```
+
+---
+
+## Tips
+
+Be specific about the improvement:
+- Bad: "make it better"
+- Good: "add 20% discount for annual billing plans"
+
+- Bad: "handle errors"
+- Good: "show user-friendly message when payment fails with insufficient funds"
+
+- Bad: "improve performance"
+- Good: "cache subscription status to reduce Stripe API calls"
+
+---
+
+## Multiple Iterations
+
+You can run `/iterate-spec` multiple times during a build:
+
+```
+/build-spec @my-feature
+   ↓
+/iterate-spec @my-feature "add X"
+   ↓
+/iterate-spec @my-feature "improve Y"
+   ↓
+/iterate-spec @my-feature "handle edge case Z"
+   ↓
+/validate-spec @my-feature
+```
+
+Each iteration adds to the same spec, maintaining full history in:
+- spec.md changelog
+- tasks.md with iter-* prefixed tasks
+- Git commits showing progression

package/.claude/commands/primer-spec.md

@@ -0,0 +1,158 @@
+# /primer-spec
+
+Quickly load spec context into a fresh conversation.
+
+---
+
+## Purpose
+
+When you start a new conversation (context was full), use this command to:
+- Restore awareness of the spec's current state
+- Understand what's done and what's pending
+- Know which branch you're on
+- Continue work without re-explaining everything
+
+**This is NOT an orchestration command.** Read files directly and output a summary.
+
+---
+
+## Usage
+
+```
+/primer-spec @2025-11-29-stripe-integration
+```
+
+---
+
+## What To Do
+
+### Step 1: Read Spec Files
+
+Read these files from `.catalyst/specs/{slug}/`:
+
+```
+1. spec.md      → What is this feature? Requirements?
+2. tasks.md     → What's done? What's pending? What's in progress?
+3. research.md  → (if exists) Any key technical decisions?
+```
+
+### Step 2: Check Git State
+
+```bash
+git branch --show-current    # What branch are we on?
+git status --short           # Any uncommitted changes?
+git log --oneline -3         # Recent commits?
+```
+
+### Step 3: Output Brief Summary
+
+Output a **concise** summary (aim for ~20-30 lines max):
+
+```
+## Spec Primer: {Feature Name}
+
+**Branch:** feat/{slug}
+**Status:** {phase - e.g., "Building", "Testing", "Validating"}
+
+### What It Does
+{1-2 sentences from spec.md overview}
+
+### Progress
+| Done | In Progress | Pending |
+|------|-------------|---------|
+| 3    | 1           | 2       |
+
+**Completed:**
+- ✓ {task-1}
+- ✓ {task-2}
+
+**In Progress:**
+- → {task-3}
+
+**Pending:**
+- ○ {task-4}
+- ○ {task-5}
+
+### Current Focus
+{What was being worked on based on tasks.md status}
+
+### Git State
+- Branch: feat/{slug}
+- Last commit: {commit message}
+- Uncommitted changes: {yes/no}
+
+---
+Ready to continue. What would you like to work on?
+```
+
+---
+
+## Rules
+
+1. **Be brief** - This is a primer, not a full report
+2. **Read directly** - Do NOT spawn agents, just read files
+3. **Focus on actionable state** - What's done, what's next
+4. **Preserve context** - Keep output short to leave room for actual work
+
+---
+
+## Example Output
+
+```
+## Spec Primer: Stripe Integration
+
+**Branch:** feat/2025-11-29-stripe-integration
+**Status:** Building (Phase 5 - Parallel Implementation)
+
+### What It Does
+Integrate Stripe for subscription billing with monthly/annual plans and usage-based pricing.
+
+### Progress
+| Done | In Progress | Pending |
+|------|-------------|---------|
+| 4    | 2           | 1       |
+
+**Completed:**
+- ✓ db-schema: Subscription tables
+- ✓ api-types: Shared TypeScript types
+- ✓ api-auth: Authentication endpoints
+- ✓ iter-001: Annual billing discount
+
+**In Progress:**
+- → api-billing: Billing service (tests passing)
+- → ui-pricing: Pricing page components
+
+**Pending:**
+- ○ integration: E2E tests
+
+### Current Focus
+Working on api-billing and ui-pricing in parallel.
+Annual billing iteration (iter-001) was added and completed.
+
+### Git State
+- Branch: feat/2025-11-29-stripe-integration
+- Last commit: feat(billing): add annual billing with 20% discount
+- Uncommitted changes: no
+
+---
+Ready to continue. What would you like to work on?
+```
+
+---
+
+## When to Use
+
+| Situation | Command |
+|-----------|---------|
+| Context full, need to continue building | `/primer-spec` |
+| Want to add improvement mid-build | `/iterate-spec` |
+| Need full validation | `/validate-spec` |
+| Check status without loading context | `/status-spec` |
+
+---
+
+## Tips
+
+- Run this FIRST in a new conversation before doing any work
+- After primer, you can run `/iterate-spec` or continue with `/build-spec`
+- If tasks.md doesn't exist, the spec hasn't been built yet - run `/build-spec`

package/.claude/commands/validate-spec.md

@@ -245,11 +245,9 @@ TDD Compliance: FAILED
 Action: Run /build-spec @2025-11-29-stripe-integration
         Follow TDD process (tests BEFORE code)
         Then re-run /validate-spec
-```
-
-### Validation Failure
+```### Validation Failure
 ```
 Validation failed!Spec: 2025-11-29-stripe-integrationFailed Checks:
 - E2E Tests: 2 failures
 - Security: 1 vulnerability foundCreated: .catalyst/specs/{slug}/validation.md (with details)Action: Fix issues and re-run /validate-spec
-```
+```

package/README.md

@@ -10,6 +10,7 @@
 /catalyze-project              # Initialize project foundation
 /catalyze-spec "description"   # Shape a feature specification
 /build-spec @spec-name         # Implement with TDD
+/iterate-spec @spec-name "improvement"  # Add improvements mid-build
 /validate-spec @spec-name      # Run quality checks
 /approve-spec @spec-name       # Accept and archive
 ```
@@ -32,19 +33,14 @@ Your project keeps its own `CLAUDE.md` — Catalyst OS lives entirely within the
 
 ```
 .claude/
-├── commands/           # User-invoked slash commands
-└── skills/             # Model-invoked capabilities (HOW)
-    ├── catalysts/      # Orchestration skills
-    ├── seekers/        # Research skills
-    ├── technologists/  # Builder skills
-    └── guardians/      # Quality skills
-
-.catalyst/
 ├── agents/             # Agent definitions (WHO)
 │   ├── catalysts/      # Orchestrators
 │   ├── seekers/        # Research agents
 │   ├── technologists/  # Builder agents
 │   └── guardians/      # Quality agents
+└── commands/           # User-invoked slash commands
+
+.catalyst/
 ├── main/               # Mission, roadmap, tech-stack
 ├── specs/              # Active specifications
 ├── tasks/              # Independent task files
@@ -62,21 +58,36 @@ Your project keeps its own `CLAUDE.md` — Catalyst OS lives entirely within the
 
 | Component | Contains | Location |
 |-----------|----------|----------|
-| **Agent** | WHO - Persona, behavior | `.catalyst/agents/` |
-| **Skill** | HOW - Process, procedure | `.claude/skills/` |
-| **Command** | WHEN - User trigger | `.claude/commands/` |
+| **Agent** | WHO - Persona, behavior | `.claude/agents/` |
+| **Command** | WHEN - User trigger, orchestration | `.claude/commands/` |
 
-### 1 Agent → N Skills
+### Agent Specialization
 
 ```
-Seer agent
-├── codebase-analysis skill
-└── context7-lookup skill
-
-Scout agent
-├── web-research skill
-├── github-research skill
-└── reddit-research skill
+Catalysts (Orchestrators)
+├── Catalyst      → Spec orchestration
+├── Forge-Master  → Build orchestration
+└── Arbiter       → Validation orchestration
+
+Seekers (Research)
+├── Oracle   → Requirements gathering
+├── Seer     → Codebase analysis
+├── Scout    → Web research
+├── Surveyor → UI/UX research
+└── Scribe   → Documentation
+
+Technologists (Builders)
+├── Forger     → Task breakdown
+├── Alchemist  → Database
+├── Smith      → Backend
+├── Shaper     → Frontend
+└── Necromancer → ML/AI
+
+Guardians (Quality)
+├── Enforcer   → Unit tests
+├── Sentinel   → E2E tests
+├── Inquisitor → Code review
+└── Watcher    → Security
 ```
 
 ---
@@ -101,6 +112,21 @@ Scout agent
   │  spec.md     │     │  tasks.md    │     │ validation.md│     │   Commit +   │
   │  research.md │     │  (updated)   │     │  handoff.md  │     │   Archive    │
   └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
+                              │
+                              ▼
+                       ┌──────────────┐
+                       │  🔄 ITERATE  │ ◀─── New idea during build?
+                       │              │
+                       │ /iterate-    │      Updates spec + tasks
+                       │    spec      │      Continues building
+                       └──────────────┘
+
+  ┌─────────────────────────────────────────────────────────────────────────────┐
+  │  💡 CONTEXT RECOVERY                                                        │
+  │                                                                             │
+  │  Context full? New conversation?                                            │
+  │  Run /primer-spec @slug to restore awareness before continuing.             │
+  └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -171,27 +197,27 @@ Scout agent
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-### Agent Skills
-
-| Order | Agent | Skills |
-|-------|-------|--------|
-| **CATALYSTS** | Catalyst | `spec-orchestration` |
-| | Forge-Master | `build-orchestration` |
-| | Arbiter | `validation-orchestration` |
-| **SEEKERS** | Oracle | `requirement-elicitation` |
-| | Scribe | `documentation-management` |
-| | Seer | `codebase-analysis`, `context7-lookup` |
-| | Scout | `web-research`, `github-research`, `reddit-research` |
-| | Surveyor | `figma-analysis`, `ui-pattern-hunting` |
-| **TECHNOLOGISTS** | Forger | `task-breakdown` |
-| | Smith | `api-development`, `service-implementation` |
-| | Shaper | `react-development`, `ui-component-building` |
-| | Alchemist | `schema-design`, `migration-creation` |
-| | Necromancer | `ml-pipeline`, `ai-integration` |
-| **GUARDIANS** | Enforcer | `unit-test-writing`, `test-fixture-creation` |
-| | Sentinel | `e2e-test-execution`, `browser-automation` |
-| | Inquisitor | `lint-checking`, `code-review` |
-| | Watcher | `dependency-audit`, `secret-scanning` |
+### Agent Capabilities
+
+| Order | Agent | Responsibility |
+|-------|-------|----------------|
+| **CATALYSTS** | Catalyst | Spec orchestration, spawns Seekers |
+| | Forge-Master | Build orchestration, spawns Technologists |
+| | Arbiter | Validation orchestration, spawns Guardians |
+| **SEEKERS** | Oracle | Gather requirements from user |
+| | Scribe | Write and manage documentation |
+| | Seer | Analyze codebase patterns |
+| | Scout | Research web, GitHub, Reddit |
+| | Surveyor | Research UI/UX patterns |
+| **TECHNOLOGISTS** | Forger | Break down specs into tasks |
+| | Smith | Implement backend/API code |
+| | Shaper | Implement frontend/UI code |
+| | Alchemist | Design schemas, create migrations |
+| | Necromancer | Implement ML/AI features |
+| **GUARDIANS** | Enforcer | Write and run unit tests |
+| | Sentinel | Run E2E tests |
+| | Inquisitor | Code review, linting |
+| | Watcher | Security audit, dependency scan |
 
 ---
 
@@ -202,12 +228,14 @@ Scout agent
 | `/catalyze-project` | Start new project | mission.md, roadmap.md, tech-stack.md |
 | `/catalyze-spec "feature"` | New feature request | spec.md, research.md |
 | `/build-spec @slug` | Implement feature | tasks.md (updated) |
+| `/iterate-spec @slug "idea"` | Add improvements mid-build | Updated spec + tasks, continues building |
+| `/primer-spec @slug` | Restore context (new conversation) | Brief status summary |
 | `/build-task "description"` | Modify existing code | task.md in .catalyst/tasks/ |
 | `/validate-spec @slug` | Quality checks | validation.md, handoff.md |
 | `/approve-spec @slug` | Finalize | Commit + Archive |
 | `/reject-spec @slug "reason"` | Reject implementation | Status: REJECTED |
 | `/status-spec @slug` | Check progress | Current status |
-| `/update-spec @slug` | Modify spec | Updated spec.md |
+| `/update-spec @slug "change"` | Modify spec (planning phase) | Updated spec.md |
 | `/mission` | Create/update mission.md | mission.md |
 | `/roadmap` | Create/update roadmap.md | roadmap.md |
 | `/tech-stack` | Create/update tech-stack.md | tech-stack.md |
@@ -390,24 +418,21 @@ What this agent does.
 - Guidelines
 - Constraints
 
-## Skills
-| Skill | Purpose |
-|-------|---------|
-| `skill-name` | Description |
+## Capabilities
+What this agent can do.
 ```
 
-### Skill File
+### Command File
 
-```yaml
----
-name: skill-name
-description: When to use this skill...
-agent: agent-name
----
+```markdown
+# /command-name
+
+Description of what this command does.
 
-# Skill Name
+## Usage
+/command-name @spec-slug "optional args"
 
-## Process
+## Workflow
 1. Step one
 2. Step two
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catalyst-os",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "scripts": {
     "postinstall": "node .catalyst/bin/install.js"
   },