catalyst-os 3.0.2 → 3.1.0

package/.claude/agents/curator.md

@@ -12,7 +12,7 @@ description: >
 
   DO NOT audit database integrity yourself - delegate to Curator.
 model: sonnet
-color: cyan
+color: red
 skills: secret-scanning
 ---
 

package/.claude/commands/plan-project.md

@@ -0,0 +1,75 @@
+# /plan-project
+
+Plan the future of the project: maintain `roadmap.md` as a **queue of specs grouped by lifecycle state**, with a single clear next action.
+
+> **Companion to `/sync-project`.** `/plan-project` plans what's *not yet started* (Backlog, ordering, Next Up direction); `/sync-project` reconciles what's *already done* (archives finished specs). Plan the future, sync the past.
+
+## Usage
+
+```
+/plan-project              # Create new or update existing
+/plan-project "Q1 focus"   # Update with specific direction
+```
+
+## Core Principle
+
+**The roadmap is a queue of specs, not a checklist of tasks.**
+
+- One entry = one spec = one forge cycle (one PR-sized unit of work).
+- Tasks belong in each spec's `tasks.md` — never in the roadmap.
+- Sections are **lifecycle states**, not time horizons. A spec moves across the board as it progresses: `Backlog → Planned → In Progress → Audited → Done`.
+- There is always exactly **one `▶ Next Up`** so "what's the next spec?" is answerable at a glance.
+
+> The lifecycle, state detection, next-command resolution, and dashboard generation are defined once in the **`spec-lifecycle-board`** skill — load it and treat it as the source of truth. This command owns the *planning* judgment (backlog ideas, ordering, Next Up direction).
+
+## Workflow
+
+1. **Read** `.catalyst/main/mission.md` for context
+2. **Read existing** `.catalyst/main/roadmap.md` if present
+3. **Scan specs** in `.catalyst/specs/` and `.catalyst/specs/completed/` to determine the state of each
+4. **Analyze** codebase for current feature state
+5. **Ask** about priorities and ordering:
+   - What's the single most important thing next?
+   - What's blocking progress?
+   - In what order should the backlog be built?
+6. **Classify** each spec into a lifecycle bucket (see State Detection below)
+7. **Resolve** the next command for each entry
+8. **Order the Backlog** — it is a ranked queue; #1 is what becomes Next Up once the board clears
+9. **Set `▶ Next Up`** using the resolution rule below
+10. **Create/Update** the roadmap using the template at `.catalyst/main/temp/temp-roadmap.md`
+11. **Regenerate the dashboard** — write `.catalyst/main/dashboard.html` (see Dashboard below)
+
+## State Detection & Next Up
+
+Use the **State Detection** table and **`▶ Next Up` Resolution** rule from the `spec-lifecycle-board` skill (the single source). In short: five states — 🗂️ Backlog · 📋 Planned · 🔨 In Progress · 🔬 Audited · ✅ Done — detected from the spec folder's files, and Next Up = the spec closest to Done (Audited → In Progress → Planned → Backlog #1).
+
+## Granularity Guardrail
+
+Before writing any entry, check its size:
+
+- If it would need **more than ~5-8 tasks**, or spans **multiple subsystems** (e.g. backend + frontend + migrations as separable pieces), it is **too big for one spec** → split it into multiple ordered Backlog entries.
+- Replace task checklists with a one-line **Scope** + a **Done when** acceptance criterion. Detailed tasks are `tasks.md`'s job, produced later by `/forge-spec`.
+- Every Backlog entry gets a `Catalyze as: {slug}` hint so naming is decided up front, plus a seed prompt ready to hand to `/catalyze-spec`.
+
+## Backlog Ordering
+
+The Backlog is a **ranked queue** — the number is the priority. Order by:
+1. Dependencies (a spec can't precede what it depends on — note `Depends on:` per entry)
+2. Unblocking value (what makes the product usable / lets other work proceed)
+3. Priority label (🔴 → 🟢)
+
+## Output Format
+
+`.catalyst/main/roadmap.md` — uses the structure defined in `.catalyst/main/temp/temp-roadmap.md`:
+
+- `▶ Next Up` — the single next action
+- `🗂️ Backlog` — ordered queue of not-yet-catalyzed specs
+- `📋 Planned` — catalyzed, ready to forge
+- `🔨 In Progress` — being built (keep to 0-1, WIP limit)
+- `🔬 Audited` — validated, awaiting seal
+- `✅ Done` — sealed specs, for closure and history
+- `Vision / Someday` — strategic goals not yet ready to be specs
+
+## Dashboard
+
+Also (re)generate the visual, browser-openable panel at `.catalyst/main/dashboard.html` — a **whole-`.catalyst/main` control panel** tabbed across **Roadmap / Mission / Tech Stack / Architecture / Concerns**. Follow **Generating `dashboard.html`** in the `spec-lifecycle-board` skill for the full `DATA` schema and steps (set `generatedBy: "/plan-project"`). The board shows the 4 active states as collapsible columns; **Done** is the timeline below it.

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

@@ -226,3 +226,7 @@ This ensures `/primer-spec` always reflects actual progress, even if the orchest
 | Scope violation detected | STOP agent, revert, re-run with stricter prompt |
 | Parallel agents conflict | STOP build, revert, restructure DAG |
 | Dependency deadlock | STOP all, report to user, restructure DAG |
+
+## Board Sync (final step)
+
+Once the build reaches green and `tasks.md` reflects progress, the spec has moved **Planned → In Progress**. Load `spec-lifecycle-board` and run **Update the Board**: move the entry to In Progress in `roadmap.md`, re-resolve `▶ Next Up`, and regenerate `.catalyst/main/dashboard.html` (`generatedBy: "/forge-spec"`).

package/.claude/skills/project-initialization/SKILL.md

@@ -65,12 +65,21 @@ Create in `.catalyst/main/`:
 |------|--------|
 | `project-config.yaml` | User preferences |
 | `mission.md` | Questions or README |
-| `roadmap.md` | Questions or TODOs |
+| `roadmap.md` | Spec-queue |
 | `tech-stack.md` | Detected or recommended |
 | `architecture.md` | Analyzed or planned |
 | `conventions.md` | Learned or best-practice |
 | `concerns.md` | Found or empty |
 
+**Generating `roadmap.md`:** Use the template at `.catalyst/main/temp/temp-roadmap.md`. The roadmap is a **queue of specs, not a checklist of tasks** — one entry = one spec = one forge cycle. Do NOT emit "Goal + Key Tasks" lists; that granularity belongs in each spec's `tasks.md` later.
+
+- Seed the **🗂️ Backlog** with 3-6 ordered spec entries derived from the mission/TODOs. Each gets a `Catalyze as: {slug}` hint, a one-line **Scope**, a **Done when** acceptance line, `Depends on:`, and a ready-to-run `!/catalyze-spec "..."` seed prompt.
+- Order the Backlog as a ranked queue (dependencies first, then unblocking value, then priority).
+- Set **▶ Next Up** to Backlog #1 (a fresh project has nothing In Progress yet).
+- Leave 📋 Planned / 🔨 In Progress / 🔬 Audited / ✅ Done empty (a fresh project has no specs yet).
+- Granularity guardrail: if a backlog idea would need more than ~5-8 tasks or spans multiple subsystems, split it into multiple entries.
+- After writing `roadmap.md`, also generate the visual panel `.catalyst/main/dashboard.html` — follow **Generating `dashboard.html`** in the `spec-lifecycle-board` skill (set `generatedBy: "/catalyze-project"`). Point the user to it — double-click to open in a browser.
+
 ### Phase 5: Bootstrap CLAUDE.md
 
 The project's `CLAUDE.md` must contain the Catalyst OS bootstrap directive. This is what makes skills load automatically.

package/.claude/skills/project-sync/SKILL.md

@@ -88,9 +88,15 @@ For each spec the user confirms:
 
 ### Phase 5: Update Roadmap (Optional)
 
-If `.catalyst/main/roadmap.md` exists:
-1. Update status of archived specs to COMPLETE
-2. Update command sections for completed specs
+If `.catalyst/main/roadmap.md` exists, load the `spec-lifecycle-board` skill (single source of the lifecycle) and:
+1. Move archived/sealed specs into the **✅ Done** section
+2. Re-classify remaining on-disk specs into their current buckets (📋 Planned / 🔨 In Progress / 🔬 Audited) by re-running State Detection
+
+> **Boundary:** this is mechanical reconciliation of specs that exist on disk. Do NOT invent, reorder, or re-prioritize **🗂️ Backlog** entries or set strategic Next Up direction — that is planning, owned by `/plan-project`. If the board needs re-planning, tell the user to run `/plan-project`.
+
+### Phase 6: Regenerate Dashboard
+
+If `.catalyst/main/roadmap.md` exists, also regenerate `.catalyst/main/dashboard.html` so it reflects the archiving just done. Follow **Generating `dashboard.html`** in the `spec-lifecycle-board` skill (set `generatedBy: "/sync-project"`). The **Backlog stays as-is** — sync never re-plans it.
 
 ## Output
 
@@ -110,5 +116,8 @@ Flagged: 1 stale spec
 
 Library: Added authentication.md, payment-integration.md
 
-Roadmap: Updated .catalyst/main/roadmap.md
+Roadmap: Moved 2 specs to ✅ Shipped, re-classified active specs
+         (run /plan-project to re-plan the backlog and Next Up)
+
+Dashboard: Regenerated .catalyst/main/dashboard.html (open in browser)
 ```

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

@@ -118,3 +118,7 @@ Library: {status}
 
 PR: {pr-url}
 ```
+
+## Board Sync (final step)
+
+The spec just moved **Audited → Done (sealed)**. Load `spec-lifecycle-board` and run **Update the Board**: move the entry out of the board into the **Done** timeline in `roadmap.md`, re-resolve `▶ Next Up`, and regenerate `.catalyst/main/dashboard.html` (`generatedBy: "/seal-spec"`).

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

@@ -75,3 +75,7 @@ Library: {Added to .catalyst/library/X.md | Skipped}
 Note: This was a lightweight archive (no git ceremony).
 For full commit + branch management, use /seal-spec.
 ```
+
+## Board Sync (final step)
+
+The spec just moved to **Done (sealed)**. Load `spec-lifecycle-board` and run **Update the Board**: move the entry into the **Done** timeline in `roadmap.md`, re-resolve `▶ Next Up`, and regenerate `.catalyst/main/dashboard.html` (`generatedBy: "/archive-spec"`).

package/.claude/skills/spec-lifecycle-board/SKILL.md

@@ -0,0 +1,73 @@
+# Spec Lifecycle Board
+
+> **When to invoke:** After ANY spec lifecycle transition (catalyze / forge / audit / seal), and whenever the roadmap or dashboard must reflect reality.
+> **Invoked by:** `spec-shaping`, `build-orchestration`, `spec-validation`, `spec-archival`, `project-sync`, `project-initialization`, and the `/plan-project` command.
+
+This skill is the **single source of truth** for the spec lifecycle, its board buckets, next-command resolution, and how the visual `dashboard.html` is generated. Everything that touches the board reads from here so the model never drifts across commands.
+
+## The Lifecycle
+
+```
+Backlog → Planned → In Progress → Audited → Done (sealed)
+```
+
+| State | Meaning | How to detect | Next command |
+|-------|---------|---------------|--------------|
+| 🗂️ **Backlog** | Idea, not yet catalyzed | No spec folder; only a roadmap entry | `!/catalyze-spec "{seed prompt}"` |
+| 📋 **Planned** | Catalyzed, ready to build | `spec.md` exists, no `tasks.md` | `!/forge-spec @{slug}` |
+| 🔨 **In Progress** | Being built (TDD) | `tasks.md` exists, no `validation.md` | `!/audit-spec @{slug}` |
+| 🔬 **Audited** | Validated, awaiting seal | `validation.md` exists, not sealed | `!/seal-spec @{slug}` |
+| ✅ **Done** | Sealed / archived | In `.catalyst/specs/completed/` | (none) |
+
+**Board vs. Done:** the Kanban board shows the **4 active** states (Backlog · Planned · In Progress · Audited) as columns. **Done** is the sealed timeline **below** the board — it is not a column (4 columns is the max that fits comfortably).
+
+## Transition Trigger
+
+Each lifecycle command moves exactly one spec one step to the right:
+
+| Command | Transition | Board effect |
+|---------|-----------|--------------|
+| `/catalyze-spec` | Backlog → Planned | Remove backlog entry, add Planned entry |
+| `/forge-spec` | Planned → In Progress | Move entry to In Progress |
+| `/audit-spec` | In Progress → Audited | Move entry to Audited (only if audit PASSED) |
+| `/seal-spec` | Audited → Done | Move entry to the Done timeline |
+
+After the transition, the invoking skill calls **Update the Board** below. Do not re-plan or re-order the Backlog on a transition — that is `/plan-project`'s job.
+
+## `▶ Next Up` Resolution
+
+Pick exactly ONE spec for the top pointer, scanning right-to-left (closest to done first):
+
+```
+IF anything is Audited      → Next Up = that spec (seal it)
+ELSE IF anything In Progress → that spec (finish it)
+ELSE IF anything Planned      → highest-priority Planned spec (forge it)
+ELSE                          → Backlog #1 (catalyze it)
+```
+
+Render as: spec name + one-line why + resolved command.
+
+## Update the Board
+
+Two artifacts stay in sync — `roadmap.md` (source) and `dashboard.html` (view).
+
+1. **`roadmap.md`** — move the spec's entry to its new lifecycle section (see `/plan-project` for the section layout). On a single transition, touch only the moved entry and re-resolve `▶ Next Up`.
+2. **`dashboard.html`** — regenerate (see below).
+
+## Generating `dashboard.html`
+
+A self-contained, offline, browser-openable panel covering the **whole `.catalyst/main`**.
+
+1. Read the template `.catalyst/main/temp/temp-dashboard.html`.
+2. Copy it verbatim to `.catalyst/main/dashboard.html`, replacing **only** the block between `// === DATA:START` and `// === DATA:END` with a `const DATA = {…}` object. **Never edit the CSS/JS below the data block.**
+3. Build `DATA` from the `.catalyst/main` docs (skip any that don't exist — the tab/section auto-hides):
+   - Top: `project`, `tagline` (mission vision one-liner), `generated` (today), `generatedBy` (the command that ran)
+   - `roadmap` (from `roadmap.md`): `nextUp {name,why,command}`; and five arrays — `backlog` (ordered `[{rank,name,slug,scope,doneWhen,dependsOn,priority,command}]`), `planned`/`inProgress`/`audited` (`[{name,slug,scope,doneWhen,command}]`), `done` (`[{name,slug,date}]`); plus `vision [{goal,description,prereq}]`
+   - `mission` (from `mission.md`): `vision`, `pain[]`, `whoSuffers[]`, `coreValue[]`, `differentiators[]`, `targetUsers[{persona,description,need}]`, `metrics[{metric,target,timeline}]`, `qualitativeGoals[]`, `nonGoals[]`
+   - `techStack` (from `tech-stack.md`): `overview`, `groups[{category,items[{name,version,purpose,docs}]}]`, `decisions[{id,title,context,decision,consequences}]`
+   - `architecture` (from `architecture.md`): `overview`, `layers[{layer,location,responsibility}]`, `patterns[{name,purpose,location}]`, `entryPoints[{name,location,purpose}]`, `keyFiles[{purpose,file}]`
+   - `concerns` (from `concerns.md`): `summary{critical,high,medium,low}`, `issues[{id,title,severity,type,location,description,fix}]`, `techDebt[{id,location,description,effort}]`, `security[{area,status,notes}]`, `knownBugs[{id,description,location,priority}]`
+4. Set each item's `command` from the next-command column above (Audited → `!/seal-spec`, etc.).
+5. Keep `DATA` a **valid JS object literal** — quote strings, escape embedded quotes. Omit a field with `[]`/`null` rather than inventing content.
+
+On a single spec transition you may keep the other tabs' `DATA` as-is from the existing `dashboard.html` and only update the `roadmap` block + `generated`/`generatedBy` — but a full rebuild from the docs is always safe.

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

@@ -179,3 +179,7 @@ Next steps:
 ```
 
 **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`.
+
+## Board Sync (final step)
+
+The spec just moved **Backlog → Planned**. Load `spec-lifecycle-board` and run **Update the Board**: move the entry to Planned in `roadmap.md`, re-resolve `▶ Next Up`, and regenerate `.catalyst/main/dashboard.html` (`generatedBy: "/catalyze-spec"`).

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

@@ -184,3 +184,7 @@ Validation failed!
 Failed Checks: [details]
 Action: Fix issues and re-run /audit-spec
 ```
+
+## Board Sync (final step)
+
+**Only if the audit PASSED**, the spec has moved **In Progress → Audited**. Load `spec-lifecycle-board` and run **Update the Board**: move the entry to Audited in `roadmap.md`, re-resolve `▶ Next Up`, and regenerate `.catalyst/main/dashboard.html` (`generatedBy: "/audit-spec"`). If the audit failed, leave the board unchanged (the spec stays In Progress).

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

@@ -51,6 +51,7 @@ Skills tell you HOW. User instructions tell you WHAT.
 | **project-initialization** | `.claude/skills/project-initialization/SKILL.md` | `/catalyze-project` — setting up a new project |
 | **spec-update** | `.claude/skills/spec-update/SKILL.md` | `/update-spec` — modifying an existing spec |
 | **project-sync** | `.claude/skills/project-sync/SKILL.md` | `/sync-project` — batch sync and archive specs |
+| **spec-lifecycle-board** | `.claude/skills/spec-lifecycle-board/SKILL.md` | After any spec transition, or `/plan-project` — move the spec on the board and regenerate `dashboard.html` |
 
 ---
 

package/README.md

@@ -221,11 +221,36 @@ Guardians (Quality)
 | `/status-spec @slug` | Check progress | Current status |
 | `/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 |
+| `/plan-project` | Plan the backlog & next spec | roadmap.md |
 | `/tech-stack` | Create/update tech-stack.md | tech-stack.md |
 
 ---
 
+## Project Dashboard
+
+Alongside `roadmap.md`, Catalyst generates a self-contained visual panel at **`.catalyst/main/dashboard.html`** — double-click to open in any browser (no server, no network). It's a whole-`.catalyst/main` control panel tabbed across **Roadmap · Mission · Tech Stack · Architecture · Concerns**.
+
+The Roadmap tab is a Kanban board over the spec lifecycle:
+
+```
+Backlog → Planned → In Progress → Audited → Done (sealed)
+```
+
+The board shows the 4 active states as collapsible columns; **Done** is the sealed timeline below. A single **▶ Next Up** card always answers "what's the next spec?", with a copy-able command.
+
+**It stays in sync automatically.** Every lifecycle command moves the spec one column and regenerates the dashboard:
+
+| Command | Moves the spec |
+|---------|----------------|
+| `/catalyze-spec` | Backlog → Planned |
+| `/forge-spec` | Planned → In Progress |
+| `/audit-spec` (pass) | In Progress → Audited |
+| `/seal-spec` | Audited → Done |
+
+Run `/plan-project` to re-plan the backlog, or `/sync-project` to reconcile after the fact. The lifecycle, detection, and dashboard generation are defined once in the `spec-lifecycle-board` skill.
+
+---
+
 ## Voice Meetings (`/meet-spec`)
 
 Shape a spec by **talking it through**. `/meet-spec` opens a local browser meeting room,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catalyst-os",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "scripts": {
     "postinstall": "node .catalyst/bin/install.js",
     "validate": "node .catalyst/bin/validate-artifacts.js"

package/.claude/commands/roadmap.md

@@ -1,69 +0,0 @@
-# /roadmap
-
-Create or update the project roadmap with spec-grouped entries and actionable next commands.
-
-## Usage
-
-```
-/roadmap              # Create new or update existing
-/roadmap "Q1 focus"   # Update with specific direction
-```
-
-## Workflow
-
-1. **Read** `.catalyst/main/mission.md` for context
-2. **Read existing** `.catalyst/main/roadmap.md` if present
-3. **Scan specs** in `.catalyst/specs/` to determine current state of each spec
-4. **Analyze** codebase for current feature state
-5. **Ask** about priorities and timeline:
-   - What's most important right now?
-   - What's blocking progress?
-   - What's the target timeline?
-6. **Resolve commands** for each spec entry (see Command Resolution below)
-7. **Create/Update** the roadmap using the template at `.catalyst/main/temp/temp-roadmap.md`
-
-## Command Resolution
-
-The canonical spec workflow is: `/catalyze-spec` → `/forge-spec` → `/audit-spec` → `/seal-spec`
-
-For each spec entry in the roadmap, determine the next action based on its state:
-
-| Spec State | How to Detect | Next Command |
-|------------|---------------|--------------|
-| Not yet created | Only exists in roadmap, no spec folder | `!/catalyze-spec "{seed prompt}"` |
-| DRAFT | `spec.md` exists, no `tasks.md` | `!/forge-spec @{slug}` or `!/forge-spec-worktree @{slug}` |
-| IN_PROGRESS | `tasks.md` exists, build ongoing | `!/audit-spec @{slug}` |
-| VALIDATING | `validation.md` exists | `!/seal-spec @{slug}` |
-| COMPLETE | `handoff.md` exists with sealed status | No command (show checkmark) |
-
-> **Worktree tip:** Use `!/forge-spec-worktree` when another spec is already in progress on the current branch, or when file scopes might collide between concurrent specs.
-
-### Detection Logic
-
-For each spec entry, check `.catalyst/specs/{slug}/`:
-
-```
-IF no folder exists for this entry:
-  → Status: Planned | Command: !/catalyze-spec "{seed prompt}"
-
-ELSE IF spec.md exists BUT tasks.md does NOT:
-  → Status: DRAFT | Command: !/forge-spec @{slug} (or !/forge-spec-worktree @{slug})
-
-ELSE IF tasks.md exists BUT validation.md does NOT:
-  → Status: IN_PROGRESS | Command: !/audit-spec @{slug}
-
-ELSE IF validation.md exists BUT not sealed:
-  → Status: VALIDATING | Command: !/seal-spec @{slug}
-
-ELSE (sealed):
-  → Status: COMPLETE | Command: (none)
-```
-
-## Output Format
-
-`.catalyst/main/roadmap.md` — uses the structure defined in `.catalyst/main/temp/temp-roadmap.md`
-
-Specs are grouped within time-horizon sections:
-- **Short-Term (1-3 months)** — immediate priorities
-- **Medium-Term (3-6 months)** — next wave of work
-- **Long-Term Vision (6+ months)** — strategic goals, not yet ready for specs