catalyst-os 2.0.3 → 3.0.1

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-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,6 +41,7 @@ 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 |

package/AGENTS.md

@@ -14,7 +14,7 @@ Quick reference for all agents and the skills they use.
 |----------|--------------|
 | Research phase | Oracle + Seer + Scout + Surveyor |
 | Build phase | Smith x N + Shaper x M (multiple instances) |
-| Validation phase | Inquisitor + Watcher + Sentinel |
+| Validation phase | Inquisitor + Watcher + Sentinel + Curator (DB specs) |
 
 ### Run Sequentially (Has Dependencies)
 
@@ -94,6 +94,7 @@ All builders follow `test-driven-development`, `systematic-debugging`, `verifica
 | [Sentinel](.claude/agents/sentinel.md) | E2E tests | — |
 | [Inquisitor](.claude/agents/inquisitor.md) | Code review | — |
 | [Watcher](.claude/agents/watcher.md) | Security audit | — |
+| [Curator](.claude/agents/curator.md) | Schema-integrity audit (read-only DB) | `secret-scanning` |
 
 ---
 

package/README.md

@@ -9,6 +9,7 @@
 ```bash
 npx catalyst-os                        # Install to your project
 /catalyze-project                      # Initialize project foundation
+/meet-spec "topic"                     # (optional) Talk it through -> meeting notes
 /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
@@ -44,6 +45,7 @@ Then run `/catalyze-project` to initialize — this detects your workspace type,
 │   ├── agent-delegation/
 │   ├── receiving-code-review/
 │   ├── workspace-detection/
+│   ├── meet-spec/
 │   ├── spec-shaping/
 │   ├── spec-challenge/
 │   ├── build-orchestration/
@@ -57,6 +59,8 @@ Then run `/catalyze-project` to initialize — this detects your workspace type,
 
 .catalyst/
 ├── main/                # Mission, roadmap, tech-stack, project-config
+├── voice/               # /meet-spec meeting runtime (zero-dependency)
+├── meetings/            # Meeting notes artifacts (generated, git-ignored)
 ├── specs/               # Active specifications
 ├── completed/           # Archived specs
 └── library/             # Reusable patterns
@@ -103,6 +107,7 @@ Without this, skills are optional documentation. With it, they're mandatory proc
 
 | Skill | Command | Purpose |
 |-------|---------|---------|
+| `meet-spec` | `/meet-spec` | Voice meeting → `/catalyze-spec`-ready notes (optional) |
 | `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 |
@@ -143,7 +148,8 @@ Guardians (Quality)
 ├── Enforcer   → Unit tests
 ├── Sentinel   → E2E tests
 ├── Inquisitor → Code review
-└── Watcher    → Security
+├── Watcher    → Security
+└── Curator    → Schema integrity (DB, read-only)
 ```
 
 ### Agent Capabilities
@@ -167,6 +173,7 @@ Guardians (Quality)
 | | Sentinel | Run E2E tests |
 | | Inquisitor | Code review, linting |
 | | Watcher | Security audit, dependency scan |
+| | Curator | Schema-integrity audit (read-only DB) |
 
 ---
 
@@ -201,6 +208,7 @@ Guardians (Quality)
 | Command | When to Use | Output |
 |---------|-------------|--------|
 | `/catalyze-project` | Start new project | mission.md, roadmap.md, tech-stack.md |
+| `/meet-spec "topic"` | Shape a spec by talking it through (optional) | meeting.html + meeting.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) |
@@ -218,6 +226,34 @@ Guardians (Quality)
 
 ---
 
+## Voice Meetings (`/meet-spec`)
+
+Shape a spec by **talking it through**. `/meet-spec` opens a local browser meeting room,
+holds a spoken conversation, and writes a `/catalyze-spec`-ready notes artifact. The
+agent can read the codebase, docs, and the web live during the meeting.
+
+```
+/meet-spec "realtime notifications"     # opens the room → talk → End meeting
+/catalyze-spec @.catalyst/meetings/YYYY-MM-DD-{slug}/meeting.md
+```
+
+Two modes (`voice.mode` in `project-config.yaml`):
+
+| | **diy** (default) | **bundled** |
+|---|---|---|
+| Speech | Browser Web Speech API | ElevenLabs Conversational AI |
+| Brain | Local `claude -p` | ElevenLabs agent (Claude LLM) |
+| Cost | **Free** (uses your Claude) | Per-minute, BYOK key |
+| Setup | None — just Chrome | API key + agent |
+
+The room shows **live meeting notes** (left) beside the **chat history** (right). On
+**End meeting** it saves both `meeting.html` (rendered, self-contained) and `meeting.md`
+(canonical input for `/catalyze-spec`). Notes are written in English regardless of the
+spoken language (`voice.language`, e.g. `"tr"`). Runtime lives in `.catalyst/voice/`
+(zero npm dependencies). See `.catalyst/voice/README.md` for setup.
+
+---
+
 ## Spec Folder Structure
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catalyst-os",
-  "version": "2.0.3",
+  "version": "3.0.1",
   "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"
   ],