catalyst-os 1.1.1 → 1.2.0

package/.catalyst/main/project-config.yaml

@@ -25,6 +25,9 @@ git:
     - "main"
     - "master"
 
+  # Path for git worktrees (relative to repo root, used by /build-spec-worktree)
+  worktree_path: ".catalyst/worktrees"
+
   # Commit message templates
   commit_templates:
     red_phase: "test({scope}): write failing tests for {spec}"

package/.claude/agents/alchemist.md

@@ -41,7 +41,8 @@ You handle all database concerns including schema design, migrations, and data t
 5. **Indexes**: Plan for query performance
 6. **Migration**: Write safe, reversible migrations
 7. **Self-Review**: Before reporting done (see below)
-8. **Report**: Actual test/migration output, files changed, any concerns
+8. **Update tasks.md**: Mark your task as done (see below) — MANDATORY
+9. **Report**: Actual test/migration output, files changed, any concerns
 
 ## Self-Review Before Reporting
 
@@ -72,6 +73,33 @@ Before reporting task completion to the orchestrator, review your own work:
 
 If you find issues during self-review, fix them before reporting.
 
+## MANDATORY: Update tasks.md on Completion
+
+**After your task passes self-review, you MUST update tasks.md BEFORE reporting back.**
+
+The orchestrator may lose context or the conversation may end before it updates. If you don't do this, your work looks like it never happened.
+
+### How to Update
+
+1. **Find tasks.md**: Read `.catalyst/specs/*/tasks.md` (the spec you're working on)
+2. **Update the Progress table**: Change your task's status from `⚡ Active` to `✓ Done`
+3. **Add commit hash** if you committed
+4. **Update Current Session**: Note what's next based on the DAG
+
+### Example
+
+Before:
+```
+| db-schema | ⚡ Active | alchemist | Pending | Working... |
+```
+
+After:
+```
+| db-schema | ✓ Done | alchemist | ✓ Pass | Schema migrated, types generated |
+```
+
+**If you skip this step, `/primer-spec` will show the spec as not started and all your progress is invisible.**
+
 ## When Receiving Review Feedback
 
 Follow `.claude/skills/receiving-code-review/SKILL.md`:

package/.claude/agents/enforcer.md

@@ -85,6 +85,32 @@ Write test → Run (PASS) → Revert the fix → Run (MUST FAIL) → Restore fix
 If it doesn't fail when reverted, the test is worthless.
 ```
 
+## MANDATORY: Update tasks.md on Completion
+
+**After completing your test-writing or integration task, you MUST update tasks.md BEFORE reporting back.**
+
+The orchestrator may lose context or the conversation may end before it updates. If you don't do this, your work looks like it never happened.
+
+### How to Update
+
+1. **Find tasks.md**: Read `.catalyst/specs/*/tasks.md` (the spec you're working on)
+2. **Update the Progress table**: Change your task's status from `⚡ Active` to `✓ Done`
+3. **Update Current Session**: Note what's next based on the DAG
+
+### Example
+
+Before:
+```
+| integration | ⚡ Active | enforcer | Pending | Running E2E tests |
+```
+
+After:
+```
+| integration | ✓ Done | enforcer | ✓ Pass | All integration tests passing |
+```
+
+**If you skip this step, `/primer-spec` will show the spec as not started and all your progress is invisible.**
+
 ## Principles
 
 - **Red First**: Tests must fail before implementation — and you must WATCH them fail

package/.claude/agents/forge-master.md

@@ -214,9 +214,18 @@ Agent reports "task complete, tests pass":
 1. Check: Did the agent include actual test output in its report?
 2. Check: Does VCS diff show the expected file changes?
 3. Run: Execute the test command for that scope yourself
-4. ONLY THEN: Mark the task as Done in tasks.md
+4. Verify: Did the agent update tasks.md Progress table? (agents are instructed to)
+5. If NOT updated: Update tasks.md yourself IMMEDIATELY
+6. ONLY THEN: Consider the task Done
 ```
 
+### CRITICAL: tasks.md Must Stay Current
+
+Agents are instructed to update tasks.md themselves. But if an agent fails to do so:
+- **You MUST update tasks.md immediately** after verifying completion
+- Do NOT defer this — if the conversation ends, stale tasks.md means `/primer-spec` shows no progress
+- Update BOTH the Progress table AND the Current Session section
+
 ## Escalation Protocol
 
 See: `.claude/skills/agent-delegation/SKILL.md`

package/.claude/agents/shaper.md

@@ -41,7 +41,8 @@ You implement frontend functionality including React components, pages, and UI f
 5. **Style**: Apply styling to match design
 6. **Polish**: Add interactions, transitions, states
 7. **Self-Review**: Before reporting done (see below)
-8. **Report**: Actual test output, files changed, any concerns
+8. **Update tasks.md**: Mark your task as done (see below) — MANDATORY
+9. **Report**: Actual test output, files changed, any concerns
 
 ## Self-Review Before Reporting
 
@@ -68,6 +69,33 @@ Before reporting task completion to the orchestrator, review your own work:
 
 If you find issues during self-review, fix them before reporting.
 
+## MANDATORY: Update tasks.md on Completion
+
+**After your task passes self-review, you MUST update tasks.md BEFORE reporting back.**
+
+The orchestrator may lose context or the conversation may end before it updates. If you don't do this, your work looks like it never happened.
+
+### How to Update
+
+1. **Find tasks.md**: Read `.catalyst/specs/*/tasks.md` (the spec you're working on)
+2. **Update the Progress table**: Change your task's status from `⚡ Active` to `✓ Done`
+3. **Add commit hash** if you committed
+4. **Update Current Session**: Note what's next based on the DAG
+
+### Example
+
+Before:
+```
+| ui-profile | ⚡ Active | shaper-1 | Pending | Working... |
+```
+
+After:
+```
+| ui-profile | ✓ Done | shaper-1 | ✓ Pass | Profile page complete |
+```
+
+**If you skip this step, `/primer-spec` will show the spec as not started and all your progress is invisible.**
+
 ## When Receiving Review Feedback
 
 Follow `.claude/skills/receiving-code-review/SKILL.md`:

package/.claude/agents/smith.md

@@ -40,7 +40,8 @@ You implement backend functionality including APIs, services, business logic, an
 4. **Implement**: Write code to pass tests (green phase)
 5. **Refactor**: Clean up while keeping tests green
 6. **Self-Review**: Before reporting done (see below)
-7. **Report**: Actual test output, files changed, any concerns
+7. **Update tasks.md**: Mark your task as done (see below) — MANDATORY
+8. **Report**: Actual test output, files changed, any concerns
 
 ## Self-Review Before Reporting
 
@@ -67,6 +68,33 @@ Before reporting task completion to the orchestrator, review your own work:
 
 If you find issues during self-review, fix them before reporting.
 
+## MANDATORY: Update tasks.md on Completion
+
+**After your task passes self-review, you MUST update tasks.md BEFORE reporting back.**
+
+The orchestrator may lose context or the conversation may end before it updates. If you don't do this, your work looks like it never happened.
+
+### How to Update
+
+1. **Find tasks.md**: Read `.catalyst/specs/*/tasks.md` (the spec you're working on)
+2. **Update the Progress table**: Change your task's status from `⚡ Active` to `✓ Done`
+3. **Add commit hash** if you committed
+4. **Update Current Session**: Note what's next based on the DAG
+
+### Example
+
+Before:
+```
+| api-auth | ⚡ Active | smith-1 | Pending | Working... |
+```
+
+After:
+```
+| api-auth | ✓ Done | smith-1 | ✓ Pass | Implemented auth endpoints |
+```
+
+**If you skip this step, `/primer-spec` will show the spec as not started and all your progress is invisible.**
+
 ## When Receiving Review Feedback
 
 Follow `.claude/skills/receiving-code-review/SKILL.md`:

package/.claude/commands/build-spec-worktree.md

@@ -0,0 +1,19 @@
+# /build-spec-worktree
+
+Implement a specification using **strict TDD** in an isolated git worktree.
+
+Use this instead of `/build-spec` when you need worktree isolation — e.g., working on a second spec while another is in progress, or wanting a clean working directory.
+
+## Usage
+
+```
+/build-spec-worktree @2025-11-29-stripe-integration
+```
+
+---
+
+**Invoke skill:** `build-orchestration` with `--worktree`
+
+**Orchestrator:** Forge-Master (delegates to Forger, Enforcer, Smith, Shaper, Alchemist)
+
+**Process skills used:** `test-driven-development`, `agent-delegation`, `verification-before-completion`, `systematic-debugging`

package/.claude/settings.local.json

@@ -6,8 +6,10 @@
     "deny": [],
     "ask": []
   },
+  "enableAllProjectMcpServers": true,
   "enabledMcpjsonServers": [
-    "shadcn"
-  ],
-  "enableAllProjectMcpServers": true
+    "shadcn",
+    "supabase-local",
+    "exa"
+  ]
 }

package/.claude/skills/build-orchestration/SKILL.md

@@ -1,7 +1,7 @@
 # Build Orchestration
 
 > **When to invoke:** When implementing a specification using strict TDD.
-> **Invoked by:** `/build-spec` command.
+> **Invoked by:** `/build-spec` or `/build-spec-worktree` command.
 > **Orchestrator:** Forge-Master agent.
 
 ## Purpose
@@ -38,8 +38,14 @@ Orchestrate the full build workflow: task breakdown, test writing, foundation, c
 ```
 PHASE 0: Setup
 ├── Read .catalyst/main/project-config.yaml
-├── Checkout to development_branch (default: main)
-└── Create branch: {branch_prefix}/{spec-slug}
+├── IF --worktree flag:
+│   ├── mkdir -p {worktree_path}
+│   ├── git worktree add {worktree_path}/{spec-slug} -b {branch_prefix}/{spec-slug} {development_branch}
+│   ├── cd {worktree_path}/{spec-slug}
+│   └── Record worktree path in spec's handoff.md
+├── ELSE (default):
+│   ├── Checkout to development_branch (default: main)
+│   └── Create branch: {branch_prefix}/{spec-slug}
 
 GATE 1: RED FLAG
 └── Commit: "test({scope}): write failing tests for {spec}"
@@ -105,9 +111,15 @@ Phase 6: Integration (Enforcer — cross-boundary tests)
 
 ### Phase 0: Git Setup
 
-1. Read `project-config.yaml` for `development_branch` and `branch_prefix`
-2. Checkout development branch and pull
-3. Create spec feature branch: `{branch_prefix}/{spec-slug}`
+1. Read `project-config.yaml` for `development_branch`, `branch_prefix`, and `worktree_path`
+2. IF `--worktree` flag (from `/build-spec-worktree`):
+   - `mkdir -p {worktree_path}` (default: `.catalyst/worktrees`)
+   - `git worktree add {worktree_path}/{spec-slug} -b {branch_prefix}/{spec-slug} {development_branch}`
+   - `cd {worktree_path}/{spec-slug}` — all subsequent work happens here
+   - Record `worktree: {worktree_path}/{spec-slug}` in the spec's `handoff.md`
+3. ELSE (default — branch checkout):
+   - Checkout development branch and pull
+   - Create spec feature branch: `{branch_prefix}/{spec-slug}`
 
 ### Phase 1: Task Breakdown (Forger)
 
@@ -179,13 +191,20 @@ FOR EACH TASK:
 3. Run test → must PASS
 4. Refactor if needed
 5. Run test → must still PASS
-6. Update tasks.md Progress
+6. Update tasks.md Progress — THE AGENT DOING THE WORK MUST DO THIS
 
 NEVER write code without a failing test first
 NEVER write more code than needed to pass the test
 NEVER modify files outside your SCOPE
+NEVER report done without updating tasks.md first
 ```
 
+### tasks.md Update Responsibility
+
+**Every agent (smith, shaper, alchemist, enforcer) MUST update tasks.md before reporting back.**
+The orchestrator (forge-master) verifies and fills gaps, but agents are the primary updaters.
+This ensures `/primer-spec` always reflects actual progress, even if the orchestrator loses context.
+
 ## Failure Modes
 
 | Failure | Action |

package/.claude/skills/spec-iteration/SKILL.md

@@ -68,9 +68,11 @@ Phase 5: Implement (Smith/Shaper/Alchemist)
 
 ### Phase 0: Verify State
 
-1. Verify on feature branch: `git branch --show-current`
-2. Read existing spec.md and tasks.md
-3. If NOT on feature branch: ask user to checkout or run `/build-spec`
+1. Check if `.catalyst/worktrees/{spec-slug}` exists
+   - IF exists: `cd` into it (worktree mode)
+2. ELSE: Verify on feature branch: `git branch --show-current`
+3. Read existing spec.md and tasks.md
+4. If neither worktree nor feature branch: ask user to run `/build-spec` or `/build-spec-worktree`
 
 ### Phase 1: Clarify (Oracle — Optional)
 
@@ -116,7 +118,7 @@ Spawn appropriate agents (Smith/Shaper/Alchemist) based on task types. Parallel
 
 | Failure | Action |
 |---------|--------|
-| Not on feature branch | Checkout or run `/build-spec` first |
+| Not on feature branch | Checkout, run `/build-spec`, or `/build-spec-worktree` first |
 | Spec not found | Run `/catalyze-spec` first |
 | tasks.md missing | Run `/build-spec` first |
 | Improvement conflicts with existing | Spawn Oracle to discuss options |

package/package.json

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