catalyst-os 2.0.2 → 3.0.0

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

@@ -0,0 +1,112 @@
+# Meet Spec
+
+> **When to invoke:** When the user wants to shape a spec by holding a voice meeting.
+> **Invoked by:** `/meet-spec` command.
+> **Orchestrator:** Catalyst agent.
+
+## Purpose
+
+Run a local, browser-based voice meeting (ElevenLabs) where the user talks through a
+feature. The meeting agent can investigate the codebase live. When the meeting ends,
+write a structured, `/catalyze-spec`-ready notes artifact.
+
+**This skill does NOT produce a spec.** It produces a meeting artifact. The user runs
+`/catalyze-spec @<artifact>` afterwards, when they choose to.
+
+## Output Location
+
+```
+.catalyst/meetings/YYYY-MM-DD-{slug}/
+└── meeting.md        # Summary + Decisions + Action Items + Open Questions + Research Findings + Transcript
+```
+
+## Modes
+
+`voice.mode` in `project-config.yaml` picks how the meeting runs:
+
+- **diy** (default, free) — the browser does speech (Web Speech API) and the brain is a
+  local `claude -p`, which reads the codebase/docs and searches the web natively. No
+  ElevenLabs, no API key, no per-minute cost. Needs Chrome and the `claude` CLI on PATH.
+- **bundled** — ElevenLabs Conversational AI. Nicer voice, but billed per minute (BYOK).
+  Requires `elevenlabs_api_key` in `.catalyst/secrets.local.yaml`, `voice.agent_id` in
+  config, and an agent that has a `investigate_codebase` client tool. See the README.
+
+`language` sets the spoken meeting language (e.g. `"tr"`); written artifacts stay English.
+
+## Workflow
+
+### Phase 0: Preflight (stop early if not ready)
+
+1. Read `.catalyst/main/project-config.yaml`. If `voice.enabled` is not `true`, stop and
+   tell the user how to enable it. Do not proceed.
+2. Check `node --version` is >= 18 and `.catalyst/voice/meet-server.js` exists; otherwise
+   stop and explain (re-install catalyst-os if the runtime is missing).
+3. **Bundled mode only:** check `.catalyst/secrets.local.yaml` has a non-empty
+   `elevenlabs_api_key` and `voice.agent_id` is set. If missing, stop with setup
+   instructions — do NOT print or echo the key. In **diy** mode, skip this check entirely.
+
+**On any failure: stop gracefully. Voice is optional; never break the rest of Catalyst.**
+
+### Phase 1: Initialize meeting folder
+
+1. Determine the topic from `$ARGUMENTS`; if empty, ask the user one short question.
+2. Derive a kebab-case `{slug}` from the topic.
+3. Create `.catalyst/meetings/YYYY-MM-DD-{slug}/` (today's date).
+
+### Phase 2: Launch the meeting room
+
+Start the local daemon in the background and open the browser. The server reads config
+(and, in bundled mode, the key from `secrets.local.yaml`) itself — never pass the key on
+the command line or env.
+
+```bash
+PORT=4399 \
+MEETING_DIR=".catalyst/meetings/YYYY-MM-DD-{slug}" \
+MEETING_TOPIC="{topic}" \
+node .catalyst/voice/meet-server.js &
+```
+
+Run it from the project root (so `claude -p` investigations resolve against this repo).
+Then open `http://localhost:4399` (e.g. `open`, `xdg-open`, or `start`). Tell the user:
+"The meeting room is open. Click **Start meeting**, talk it through, then click **End
+meeting** when you're done."
+
+### Phase 3: Wait for the artifact
+
+Poll for `.catalyst/meetings/YYYY-MM-DD-{slug}/meeting.md`. It is written when the user
+clicks **End meeting** (the server folds the transcript + live findings into the artifact
+via a single `claude -p` summarization pass). When it appears, the meeting is over — the
+server shuts itself down.
+
+### Phase 4: Output
+
+```
+Meeting captured.
+
+Artifact: .catalyst/meetings/YYYY-MM-DD-{slug}/meeting.md
+  ├── Summary
+  ├── Decisions
+  ├── Action Items
+  ├── Open Questions
+  ├── Research Findings   (live codebase investigations from the meeting)
+  └── Transcript
+
+Next step — shape it into a spec when you're ready:
+  /catalyze-spec @.catalyst/meetings/YYYY-MM-DD-{slug}/meeting.md
+```
+
+**Do NOT auto-run `/catalyze-spec`.** The user references the artifact themselves.
+
+## Notes
+
+- **Live codebase access:** in **diy** mode every turn is a headless `claude -p` in this
+  repo, so the agent reads the codebase/docs and searches the web natively. In **bundled**
+  mode the ElevenLabs agent calls the `investigate_codebase` client tool, which the browser
+  relays to the daemon, which runs the same `claude -p`. Either way it loads Catalyst's
+  agents and can delegate to Seer/Scout.
+- **Typed messages:** the meeting room has a text box; typed messages are sent as user
+  turns (handy when speech is misheard) and appear in the transcript.
+- **Latency:** investigations take seconds; the meeting room shows a "thinking" indicator
+  while the agent says it is looking into it. This is expected meeting behavior.
+- **Cost:** billed to the user's ElevenLabs account (~$0.10/min bundled). A 30-min meeting
+  is ~$3.

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

@@ -73,13 +73,20 @@ Update spec.md status to COMPLETE.
 
 ### Phase 7: Push & Pull Request
 
+> **This phase is atomic — do NOT stop or ask for confirmation between push and PR creation.**
+> If validation passed in Phase 1 and the commit succeeded in Phase 5, proceed straight through push → PR without pausing.
+> Only halt if a git/gh command returns an error.
+
 1. Read `git.development_branch` from `.catalyst/main/project-config.yaml` (e.g., `development`, `staging`)
 2. Push the feature branch: `git push -u origin {branch-name}`
-3. Create a PR targeting the development branch:
+3. **Immediately** create a PR targeting the development branch — do not wait for user input:
    ```
    gh pr create --base {development_branch} --title "feat({scope}): {spec title}" --body "..."
    ```
 4. Include spec summary, TDD stats, and file change counts in the PR body
+5. Capture the returned PR URL for the final output
+
+**Do not ask** "should I create a PR?" or "ready to push?" — the user already invoked `/seal-spec`, which is the explicit authorization for the full push + PR flow. Only pause if a command fails or the working tree is in an unexpected state.
 
 ### Phase 8: Self-Documentation
 

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

@@ -0,0 +1,139 @@
+# Spec Challenge
+
+> **When to invoke:** When stress-testing a freshly shaped spec — interviewing the user across every branch of the design tree until shared understanding is reached.
+> **Invoked by:** `/challenge-spec` command.
+> **Position:** Optional intermediate step between `/catalyze-spec` and `/forge-spec`.
+
+## Purpose
+
+Shaping produces a spec. Challenge proves the spec is forge-ready. The orchestrator interviews the user one question at a time about every unresolved branch — assumptions, edge cases, integration points, scope ambiguity — patching `spec.md` and logging the trail to `handoff.md` as each answer lands.
+
+This is not a sign-off step. It is an interrogation step. The bar is "every branch of the design tree resolved", not "user said yes".
+
+## Skills Referenced
+
+- `brainstorming` — same form (one question at a time, recommend an answer, acknowledge before moving on). The 9-question cap **does not apply** here; challenge is exhaustive by design.
+- `agent-delegation` — if a question becomes a research task, spawn Seer/Scout rather than guessing.
+
+## When NOT to Use
+
+- Spec is trivial (rename, copy change, single-file fix) — go straight to `/forge-spec`.
+- Spec is still in DRAFT and missing whole sections — finish `/catalyze-spec` first.
+- Implementation has already started (`tasks.md` exists with completed tasks) — use `/update-spec` instead.
+- Spec is COMPLETE — challenge is meaningless after the fact.
+
+## Prerequisites
+
+- Target spec folder exists at `.catalyst/specs/{slug}/`.
+- `spec.md` exists with at minimum: Overview, Requirements, Acceptance Criteria, Technical Approach.
+- `handoff.md` exists (create if missing — Catalyst should have left one).
+
+If any prerequisite is missing, STOP and tell the user to run or finish `/catalyze-spec` first.
+
+## Workflow
+
+### Phase 1: Inventory the Decision Tree
+
+Read in order: `spec.md`, `research.md`, `handoff.md`, plus any assets.
+
+Build a working list (kept in your head or a scratch section in `handoff.md`) of every branch that needs resolution. Look for:
+
+| Source | What to extract |
+|--------|-----------------|
+| `spec.md` → Open Questions | Each one is an explicit branch. |
+| `spec.md` → Requirements | Vague verbs ("handle", "support", "manage") hide branches. |
+| `spec.md` → Acceptance Criteria | Missing thresholds, missing failure modes. |
+| `spec.md` → Out of Scope | Anything that *could* be in scope but isn't justified. |
+| `spec.md` → Technical Approach | Library/framework choices without a stated reason. |
+| `research.md` | Findings the spec didn't actually use. |
+| `handoff.md` | Prior decisions that may now be in tension. |
+
+Surface anything that, if guessed wrong, would cause `/forge-spec` to backtrack.
+
+### Phase 2: Codebase First, User Second
+
+> **Rule from grill-me:** "If a question can be answered by exploring the codebase, explore the codebase instead."
+
+Before asking the user anything, walk the list and ask: can I answer this myself? Use `Read`, `grep`, or spawn **Seer** for deeper analysis. Only the residue — genuine product/scope/intent decisions — goes to the user.
+
+### Phase 3: The Interview
+
+For each remaining branch, ask **one question at a time** following these rules:
+
+1. **Lead with your recommendation.** "I'd recommend X because Y. Agree, or push back?"
+2. **Multiple choice when options exist.** Numbered. Each option has a one-line tradeoff.
+3. **Acknowledge the answer.** One sentence. Connect it to the next question.
+4. **Walk depth-first.** If an answer opens a new branch, resolve that branch before returning to the trunk.
+5. **Resolve dependencies in order.** Don't ask about caching strategy before storage backend is chosen.
+6. **No artificial cap.** Keep going until every branch is resolved. Stop only when:
+   - The user says "good enough" / "ship it" / "stop".
+   - You can no longer surface a branch that would cause `/forge-spec` to backtrack.
+
+### Phase 4: Patch As You Go
+
+After **each** resolved question, update the spec immediately. Do not batch.
+
+**`spec.md` patches** — find the right home for the answer:
+
+| Answer type | Goes in |
+|-------------|---------|
+| Removes an unknown | Delete from Open Questions |
+| Adds a verifiable behavior | Append to Acceptance Criteria |
+| Tightens scope | Add to Requirements or Out of Scope |
+| Picks a library/pattern | Update Technical Approach |
+| Reframes the problem | Update Overview / User Stories |
+
+**`handoff.md` log** — append every Q&A under a `## Challenge Log` section:
+
+```markdown
+## Challenge Log
+
+### {YYYY-MM-DD HH:MM} — {short topic}
+**Q:** {the question, including the recommendation you led with}
+**A:** {user's answer, verbatim or close to it}
+**Spec impact:** {which section of spec.md was patched and how}
+```
+
+The log is the audit trail. Future-you (or anyone running `/primer-spec`) can read it and understand *why* the spec looks the way it does.
+
+### Phase 5: Close Out
+
+When the interview ends:
+
+1. Re-read `spec.md` end-to-end. Check that patches are coherent and don't contradict each other.
+2. Confirm Open Questions is empty (or every remaining item is explicitly deferred with a note).
+3. Append a closing entry to `handoff.md`:
+   ```markdown
+   ### Challenge complete — {YYYY-MM-DD HH:MM}
+   Branches resolved: {N}
+   Spec sections updated: {list}
+   Deferred (not blocking forge): {list or "none"}
+   ```
+4. Leave `spec.md` Status as `DRAFT` — challenge does not mark the spec ready for production. `/forge-spec` is still next.
+
+## Output
+
+```
+Spec challenged.
+
+Branches resolved: {N}
+spec.md sections updated: {list}
+handoff.md: +Challenge Log ({N} entries)
+Deferred: {list or "none"}
+
+Next steps:
+- /forge-spec @{slug} to start TDD build
+- /update-spec @{slug} "..." if you want further structural changes first
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Asking the user something `grep` would answer | Phase 2 first — codebase before user. |
+| Batching 4 questions because "they're related" | One at a time. Always. Related questions go in sequence, not in a list. |
+| Asking without a recommendation | Lead with your pick + why. The user's job is to push back, not to design from scratch. |
+| Logging answers in batch at the end | Patch `spec.md` and append to `handoff.md` after each answer — context is freshest then. |
+| Stopping at 9 questions because brainstorming says so | Brainstorming caps apply to scoping. Challenge is exhaustive — keep going until branches are resolved. |
+| Treating user's "looks fine" as resolution | If you have a branch in mind, ask it. "Looks fine" without a specific answer is not a resolution. |
+| Marking spec READY / APPROVED at the end | Status stays DRAFT. `/forge-spec` is next. Challenge is not approval. |

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

@@ -174,7 +174,8 @@ REMINDER: /forge-spec follows strict TDD
   4. Tests must PASS (green phase)
 
 Next steps:
+- /challenge-spec @YYYY-MM-DD-{slug} (optional) to interrogate every branch before tests are written
 - /forge-spec @YYYY-MM-DD-{slug} to start TDD build
 ```
 
-**IMPORTANT: Do NOT suggest `/seal-spec` after spec shaping.** `/seal-spec` is only for committing a fully built and validated implementation — it is the FINAL step, not a plan-approval step. The correct flow is: `/catalyze-spec` → `/forge-spec` → `/audit-spec` → `/seal-spec`.
+**IMPORTANT: Do NOT suggest `/seal-spec` after spec shaping.** `/seal-spec` is only for committing a fully built and validated implementation — it is the FINAL step, not a plan-approval step. The correct flow is: `/catalyze-spec` → *(optional)* `/challenge-spec` → `/forge-spec` → `/audit-spec` → `/seal-spec`.

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

@@ -56,7 +56,7 @@ If TDD was skipped → REJECT and return to /forge-spec
 TDD Check (sequential, must pass first)
         |
         v
-[Enforcer + Sentinel + Inquisitor + Watcher] (all parallel)
+[Enforcer + Sentinel + Inquisitor + Watcher + Curator] (all parallel)
         |
         v
 Arbiter compiles results → validation.md
@@ -98,7 +98,9 @@ Spawn all Guardians in parallel:
 - Secret scanning
 - Input validation checks
 
-**Alchemist** (Schema Integrity — only for specs touching database):
+**Curator** (Schema Integrity — only for specs touching database):
+- READ-ONLY Guardian — audits the schema, never creates or modifies it
+- (The Alchemist *builds* the schema during `/forge-spec`; Curator independently *verifies* it here)
 - Query actual database schema for all tables the spec touches
 - Verify column names in spec/code match real database columns
 - Verify all foreign keys and constraints exist in the actual DB
@@ -147,7 +149,7 @@ If all validation passes, create handoff.md with:
 - Secrets: status
 - Inputs: status
 
-### Schema Integrity (Alchemist) — if spec touches database
+### Schema Integrity (Curator) — if spec touches database
 - Column names match: status
 - Constraints verified: status
 - API end-to-end trace: status

package/.claude/skills/using-skills/SKILL.md

@@ -41,7 +41,9 @@ Skills tell you HOW. User instructions tell you WHAT.
 
 | Skill | Path | Load when... |
 |-------|------|-------------|
+| **meet-spec** | `.claude/skills/meet-spec/SKILL.md` | `/meet-spec` — shaping a spec via a voice meeting (optional) |
 | **spec-shaping** | `.claude/skills/spec-shaping/SKILL.md` | `/catalyze-spec` — shaping a new specification |
+| **spec-challenge** | `.claude/skills/spec-challenge/SKILL.md` | `/challenge-spec` — interrogating a shaped spec branch by branch (optional) |
 | **build-orchestration** | `.claude/skills/build-orchestration/SKILL.md` | `/forge-spec` — implementing a specification |
 | **spec-validation** | `.claude/skills/spec-validation/SKILL.md` | `/audit-spec` — quality checks on implementation |
 | **spec-approval** | `.claude/skills/spec-approval/SKILL.md` | `/seal-spec` — final commit and archival |

package/README.md

@@ -10,6 +10,7 @@
 npx catalyst-os                        # Install to your project
 /catalyze-project                      # Initialize project foundation
 /catalyze-spec "description"           # Shape a feature specification
+/challenge-spec @spec-name             # (optional) Interrogate the spec branch by branch
 /forge-spec @spec-name                 # Implement with TDD
 /audit-spec @spec-name                 # Run quality checks
 /seal-spec @spec-name                  # Accept and archive
@@ -44,6 +45,7 @@ Then run `/catalyze-project` to initialize — this detects your workspace type,
 │   ├── receiving-code-review/
 │   ├── workspace-detection/
 │   ├── spec-shaping/
+│   ├── spec-challenge/
 │   ├── build-orchestration/
 │   ├── spec-validation/
 │   ├── spec-approval/
@@ -102,6 +104,7 @@ Without this, skills are optional documentation. With it, they're mandatory proc
 | Skill | Command | Purpose |
 |-------|---------|---------|
 | `spec-shaping` | `/catalyze-spec` | Shape feature requests into specifications |
+| `spec-challenge` | `/challenge-spec` | Interrogate a shaped spec branch by branch (optional) |
 | `build-orchestration` | `/forge-spec` | DAG-based TDD implementation |
 | `spec-validation` | `/audit-spec` | Quality checks via Guardian agents |
 | `spec-approval` | `/seal-spec` | Final verification and archival |
@@ -185,6 +188,10 @@ Guardians (Quality)
   └──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
   Context full? New conversation?
   Run /primer-spec @slug to restore awareness before continuing.
+
+  Optional gate between CATALYZE and FORGE:
+  /challenge-spec @slug — interrogate every branch of the design tree
+  before tests are written. Patches spec.md, logs to handoff.md.
 ```
 
 ---
@@ -195,6 +202,7 @@ Guardians (Quality)
 |---------|-------------|--------|
 | `/catalyze-project` | Start new project | mission.md, roadmap.md, tech-stack.md |
 | `/catalyze-spec "feature"` | New feature request | spec.md, research.md |
+| `/challenge-spec @slug` | Stress-test the spec before forging (optional) | spec.md (patched), handoff.md (Challenge Log) |
 | `/forge-spec @slug` | Implement feature | tasks.md (updated) |
 | `/primer-spec @slug` | Restore context (new conversation) | Brief status summary |
 | `/audit-spec @slug` | Quality checks | validation.md, handoff.md |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catalyst-os",
-  "version": "2.0.2",
+  "version": "3.0.0",
   "scripts": {
     "postinstall": "node .catalyst/bin/install.js",
     "validate": "node .catalyst/bin/validate-artifacts.js"
@@ -13,6 +13,7 @@
     "AGENTS.md",
     ".claude",
     ".catalyst/bin",
+    ".catalyst/voice",
     ".catalyst/spec-structure.yaml",
     ".catalyst/main/project-config.yaml"
   ],