specdacular 0.10.0 → 0.11.0

package/README.md

@@ -101,13 +101,13 @@ In Claude Code:
 
 ## Quick Start
 
-### Map a Codebase
+### Generate Codebase Docs
 
 ```
-/specd.codebase.map
+/specd.docs
 ```
 
-Creates `.specd/codebase/` with 4 AI-optimized documents. This gives Claude context about your codebase's architecture, patterns, structure, and gotchas. For multi-project setups, it detects sub-projects automatically and maps each one in parallel before producing system-level documentation.
+Spawns 4 parallel agents to analyze your codebase, then merges their outputs into topic-specific docs in `docs/` and writes a `CLAUDE.md` routing table. Topics are dynamically determined from what your codebase actually uses. Review docs with `/specd.docs.review`.
 
 ### Plan a Feature
 

package/bin/install.js

@@ -467,7 +467,9 @@ function install(isGlobal) {
   ${green}Done!${reset} Launch Claude Code and run ${cyan}/specd.help${reset}.
 
   ${yellow}Commands:${reset}
-    /specd.codebase.map  - Analyze and document your codebase
+    /specd.docs          - Generate topic docs and CLAUDE.md routing table
+    /specd.docs.review   - Review docs for accuracy and staleness
+    /specd.generate-skills.learn - Generate a /learn skill for your project
     /specd.update        - Update to latest version
     /specd.help          - Show all commands
 `);

package/bin/specd.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+// bin/specd.js — unified CLI entry point
+// Usage:
+//   specd llm-init [--local]     — install commands/agents/workflows
+//   specd runner                  — launch Electron app
+//   specd runner register <path>  — register a folder
+//   specd runner unregister <id>  — remove a project
+//   specd runner projects         — list projects
+//   specd runner status           — show task status
+
+import { resolve, join } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { homedir, platform } from 'os';
+import { execSync, spawn } from 'child_process';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function getAppDataDir() {
+  if (platform() === 'darwin') {
+    return join(homedir(), 'Library', 'Application Support', 'Specd');
+  }
+  return join(homedir(), '.config', 'specd');
+}
+
+function getDbPath() {
+  return join(getAppDataDir(), 'db.json');
+}
+
+function loadDb() {
+  const dbPath = getDbPath();
+  if (!existsSync(dbPath)) return { projects: [] };
+  return JSON.parse(readFileSync(dbPath, 'utf-8'));
+}
+
+function saveDb(data) {
+  const dbPath = getDbPath();
+  mkdirSync(join(dbPath, '..'), { recursive: true });
+  writeFileSync(dbPath, JSON.stringify(data, null, 2));
+}
+
+if (command === 'llm-init') {
+  // Delegate to existing install.js
+  const installScript = join(import.meta.dirname, 'install.js');
+  const isLocal = args.includes('--local');
+  process.argv = ['node', installScript, isLocal ? '--local' : '--global'];
+  await import(installScript);
+} else if (command === 'runner') {
+  const subcommand = args[1];
+
+  if (subcommand === 'register') {
+    const folderPath = resolve(args[2] || '.');
+    if (!existsSync(folderPath)) {
+      console.error(`Path does not exist: ${folderPath}`);
+      process.exit(1);
+    }
+    const name = args[3] || folderPath.split('/').pop();
+    const db = loadDb();
+    const existing = db.projects.find(p => p.path === folderPath);
+    if (existing) {
+      console.log(`Already registered: ${existing.name} (${existing.id})`);
+      process.exit(0);
+    }
+    const id = Math.random().toString(36).slice(2, 10);
+    db.projects.push({
+      id,
+      name,
+      path: folderPath,
+      active: true,
+      registeredAt: new Date().toISOString(),
+    });
+    saveDb(db);
+    console.log(`Registered: ${name} (${id}) → ${folderPath}`);
+  } else if (subcommand === 'unregister') {
+    const id = args[2];
+    if (!id) { console.error('Usage: specd runner unregister <id>'); process.exit(1); }
+    const db = loadDb();
+    db.projects = db.projects.filter(p => p.id !== id);
+    saveDb(db);
+    console.log(`Unregistered: ${id}`);
+  } else if (subcommand === 'projects') {
+    const db = loadDb();
+    if (db.projects.length === 0) {
+      console.log('No projects registered. Run: specd runner register <path>');
+    } else {
+      for (const p of db.projects) {
+        console.log(`  ${p.id}  ${p.name}  ${p.path}  ${p.active ? '●' : '○'}`);
+      }
+    }
+  } else if (subcommand === 'status') {
+    try {
+      const resp = await fetch('http://localhost:3700/api/status');
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+      const status = await resp.json();
+      for (const [projectId, state] of Object.entries(status)) {
+        console.log(`\n${projectId}:`);
+        for (const [taskId, task] of Object.entries(state.tasks || {})) {
+          const icon = { done: '✓', in_progress: '▸', failed: '✗', queued: '○' }[task.status] || '?';
+          console.log(`  ${icon} ${taskId}: ${task.name} [${task.status}]`);
+        }
+      }
+    } catch {
+      console.error('Runner not running. Start it with: specd runner');
+    }
+  } else {
+    // No subcommand — launch Electron app
+    const runnerDir = join(import.meta.dirname, '..', 'runner');
+    const electronPath = join(getAppDataDir(), 'electron', 'node_modules', '.bin', 'electron');
+
+    if (!existsSync(electronPath)) {
+      console.log('First run — installing Electron runtime...');
+      const electronDir = join(getAppDataDir(), 'electron');
+      mkdirSync(electronDir, { recursive: true });
+      writeFileSync(join(electronDir, 'package.json'), JSON.stringify({ name: 'specd-electron', private: true }));
+      execSync('npm install electron@latest', { cwd: electronDir, stdio: 'inherit' });
+      console.log('Electron installed.');
+    }
+
+    const child = spawn(electronPath, [runnerDir], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    console.log('Specd Runner launched.');
+  }
+} else {
+  console.log('Usage:');
+  console.log('  specd llm-init [--local]     Install Claude Code commands/agents');
+  console.log('  specd runner                  Launch the Specd Runner app');
+  console.log('  specd runner register <path>  Register a project folder');
+  console.log('  specd runner unregister <id>  Remove a project');
+  console.log('  specd runner projects         List registered projects');
+  console.log('  specd runner status           Show task status');
+}

package/commands/specd.best-practices.md

@@ -0,0 +1,75 @@
+---
+name: specd.best-practices
+description: Detect repo tech stack and generate a curated best-practices reference doc with project patterns, Claude Code tools, and tooling recommendations
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Agent
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+---
+
+<objective>
+Detect a repo's tech stack, spawn research agents to discover best practices, Claude Code ecosystem tools, and recommended tooling, then produce a curated `docs/best-practices.md` reference doc.
+
+Agents use web search to find current patterns, MCP servers, skills, hooks, and tooling for the detected stack. The output presents options with tradeoffs — not opinionated prescriptions.
+
+Output: `docs/best-practices.md` in the target repo.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/best-practices.md
+</execution_context>
+
+<context>
+**How it works:**
+1. Detects all tech stacks in the repo (marker files + dependency parsing)
+2. Asks user for focus areas before research
+3. Spawns 3 parallel research agents (stack patterns, Claude Code ecosystem, tooling/DX)
+4. Merges findings into a structured reference doc
+
+**Key principles:**
+- Auto-detects stack — user doesn't need to specify what tech they use
+- Presents options with context and tradeoffs, not single prescriptions
+- User steers research focus before agents run
+- Output is self-contained and readable without re-running the command
+- Does NOT modify CLAUDE.md — the doc is for the user, not necessarily for Claude
+</context>
+
+<when_to_use>
+**Use /specd.best-practices for:**
+- Starting a new project and want to know what tools/patterns exist for your stack
+- Joining an existing project and want to understand available Claude Code integrations
+- Exploring what MCP servers, skills, and hooks are available for your tech
+- Getting current tooling recommendations (linters, formatters, testing, CI)
+
+**Skip /specd.best-practices for:**
+- Projects where you already have a well-established toolchain
+- When you need docs about your existing codebase (use `/specd.docs` instead)
+</when_to_use>
+
+<process>
+1. Detect tech stacks from repo marker files and dependencies
+2. Present detected stacks to user (ask to select if 3+ found)
+3. Ask user for focus areas (everything, structure, Claude Code tools, or tooling/DX)
+4. Spawn 3 parallel research agents with stack and focus context
+5. Collect and merge agent outputs
+6. Write `docs/best-practices.md` with categorized findings
+7. Show summary to user
+</process>
+
+<success_criteria>
+- [ ] Tech stack auto-detected from repo files
+- [ ] User asked for focus areas before research
+- [ ] 3 research agents spawned with stack-aware prompts
+- [ ] Output organized by category: stack patterns, Claude Code ecosystem, tooling/DX
+- [ ] Each recommendation includes context, tradeoffs, and when to use it
+- [ ] Doc is self-contained and readable
+- [ ] CLAUDE.md is NOT modified
+</success_criteria>

package/commands/specd.docs.md

@@ -0,0 +1,81 @@
+---
+name: specd.docs
+description: Generate topic-based docs and CLAUDE.md routing table from codebase analysis
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Task
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Generate AI-optimized documentation using a context-engineering approach.
+
+Spawns 4 parallel mapper agents for raw codebase analysis, then merges their outputs into topic-specific docs in `docs/`. Writes CLAUDE.md as a pure routing table — no inline rules.
+
+Output: `docs/` folder with topic-specific docs + `CLAUDE.md` routing table.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/docs.md
+</execution_context>
+
+<context>
+**Context engineering approach:**
+
+CLAUDE.md is a thin routing table — "Working on X? Read docs/Y.md". All knowledge lives in `docs/`:
+
+| File | Purpose |
+|------|---------|
+| `docs/rules.md` | Always-true rules (imports, naming, conventions) |
+| `docs/{topic}.md` | Topic-specific patterns and guidance |
+| `CLAUDE.md` | Router only — points to the right doc for the context |
+
+**Key principles:**
+- Topics are dynamic — detected from what the codebase actually uses
+- Every doc has frontmatter (`last_reviewed`, `generated_by`) for staleness tracking
+- `rules.md` is always generated — contains project-wide rules
+- CLAUDE.md merge is non-destructive — preserves existing user content
+- No external research during generation — docs reflect actual code patterns
+</context>
+
+<when_to_use>
+**Use /specd.docs for:**
+- First time working with a codebase
+- Before planning a new feature
+- After significant refactoring
+- When existing docs are stale or missing
+
+**Skip /specd.docs for:**
+- Trivial codebases (<10 files)
+- When you have recently generated docs (use `/specd.docs.review` instead)
+</when_to_use>
+
+<process>
+1. Discover docs location (check CLAUDE.md for existing path, default to `docs/`)
+2. Check for existing specd-generated docs (offer refresh or skip)
+3. Scan for existing project documentation (README, ARCHITECTURE, etc.)
+4. Spawn 4 parallel mapper agents to temp directory
+5. Merge agent outputs into topic clusters (dynamic topic detection)
+6. Propose doc list to user for approval
+7. Generate topic docs + `rules.md` with YAML frontmatter
+8. Write/update CLAUDE.md routing table (non-destructive merge)
+9. Clean up temp files
+</process>
+
+<success_criteria>
+- [ ] Topic-specific docs generated in `docs/` (or user-configured location)
+- [ ] `docs/rules.md` always generated with project-wide rules
+- [ ] All docs have YAML frontmatter (`last_reviewed`, `generated_by`)
+- [ ] CLAUDE.md routing table written (new or merged into existing)
+- [ ] CLAUDE.md has zero inline rules — purely a router
+- [ ] Topics dynamically determined from codebase analysis
+- [ ] User approved doc list before generation
+- [ ] Existing CLAUDE.md content preserved during merge
+</success_criteria>

package/commands/specd.docs.review.md

@@ -0,0 +1,80 @@
+---
+name: specd.docs.review
+description: Review and audit codebase docs for accuracy, staleness, and coverage gaps
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Agent
+  - AskUserQuestion
+  - WebSearch
+  - WebFetch
+---
+
+<objective>
+Audit existing topic docs for accuracy, staleness, and coverage gaps. Optionally research best practices for the detected stack. Updates frontmatter review dates after approval.
+
+Output: Review findings with actionable suggestions, updated docs and review dates.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/docs-review.md
+</execution_context>
+
+<context>
+**Review approach:**
+
+Each doc has YAML frontmatter with `last_reviewed` and `generated_by` fields. The review workflow:
+
+1. Reads frontmatter dates to detect stale docs
+2. Spot-checks code references in docs against current codebase
+3. Detects coverage gaps (technologies in code not covered by docs)
+4. Optionally researches best practices for improvement suggestions
+5. Presents findings and lets user choose what to update
+
+**Staleness detection:**
+- Compare `last_reviewed` against today and recent git history
+- Flag docs where significant code changes happened since last review
+- Check if referenced file paths, function signatures, and patterns still exist
+
+**Research agents (optional):**
+- Only used during review, never during generation (DEC-008)
+- Investigate current best practices for detected technologies
+- Suggest improvements, not mandates
+</context>
+
+<when_to_use>
+**Use /specd.docs.review for:**
+- After significant code changes (refactoring, new features)
+- Periodically (monthly or quarterly)
+- When docs feel out of date
+- When wanting best-practice improvement suggestions
+
+**Skip /specd.docs.review for:**
+- Right after running /specd.docs (docs are fresh)
+- Trivial changes that don't affect patterns
+</when_to_use>
+
+<process>
+1. Find all specd-generated docs (scan for frontmatter)
+2. Assess freshness (compare review dates against git history)
+3. Check accuracy (spot-check code references)
+4. Detect gaps (technologies not covered by docs)
+5. Optionally research best practices
+6. Present findings with per-doc status
+7. Apply user-selected updates and update review dates
+</process>
+
+<success_criteria>
+- [ ] All specd-generated docs found and assessed
+- [ ] Stale docs flagged with days since review
+- [ ] Drifted docs identified with specific inaccuracies
+- [ ] Coverage gaps detected (new technologies, obsolete docs)
+- [ ] Research suggestions provided (if user opted in)
+- [ ] Review dates updated on approved docs
+- [ ] CLAUDE.md routing table updated if docs added/removed
+</success_criteria>

package/commands/specd.generate-skills.learn.md

@@ -0,0 +1,65 @@
+---
+name: specd.generate-skills.learn
+description: Generate a /learn skill that captures lessons into project docs
+argument-hint: "[namespace]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - AskUserQuestion
+---
+
+<objective>
+Generate a project-specific `/{namespace}:learn` skill that captures coding lessons, mistakes, and patterns from conversations into the project's `docs/` files.
+
+The skill is customized to the project's actual documentation structure — it knows which doc files exist, what sections they have, and what format they use.
+
+Output: `.claude/commands/{namespace}/learn.md`
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/generate-learn-skill.md
+</execution_context>
+
+<context>
+**What the learn skill does:**
+
+When a user runs `/{ns}:learn` during a conversation, it:
+1. Extracts lessons from the conversation (or from an explicit argument)
+2. Classifies each as a Rule (hard constraint) or Pattern (technique)
+3. Maps it to the right doc file and section
+4. Checks for duplicates
+5. Writes it in the existing format
+
+**Prerequisites:**
+- `docs/` folder with topic docs (run `/specd.docs` first if missing)
+- `CLAUDE.md` routing table
+
+**After generation**, users can refine the skill with the `/skill-creator` plugin (Anthropic-verified) which provides eval, improve, and benchmark modes.
+</context>
+
+<when_to_use>
+**Use after:**
+- Running `/specd.docs` to generate project documentation
+- When you want conversations to feed back into project docs
+
+**Prerequisites:**
+- `docs/` folder exists with topic docs
+</when_to_use>
+
+<process>
+1. Check docs/ exists, read all doc files
+2. Derive namespace from project name or user argument
+3. Build doc target table from actual doc files
+4. Generate the learn skill file
+5. Suggest /skill-creator for refinement
+</process>
+
+<success_criteria>
+- [ ] Namespace derived from project or user input
+- [ ] `.claude/commands/{namespace}/learn.md` generated
+- [ ] Skill references actual doc files that exist in the project
+- [ ] Doc target table matches real docs with accurate descriptions
+</success_criteria>

package/commands/specd.new-project.md

@@ -0,0 +1,58 @@
+---
+name: specd.new-project
+description: Bootstrap a new project from idea to structured plan
+argument-hint: "[project-name]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+Guide users from "I have an idea" to a structured project plan for greenfield projects. Unlike `/specd.new` which adds tasks to existing codebases, this bootstraps entire projects (or multi-service systems) through collaborative questioning, domain research, requirements scoping, and roadmap generation — producing an orchestrator setup with per-project task lifecycles.
+
+**Stages:**
+1. **Questioning** — Collaborative discussion to understand vision, goals, users, constraints
+2. **Research** — Parallel agents investigate stack, features, architecture, pitfalls
+3. **Requirements** — Multi-select scoping from research findings → REQUIREMENTS.md
+4. **Roadmap** — Phase planning mapped to requirements, identifies sub-projects
+5. **Scaffolding** — Create orchestrator config, sub-project directories, seed setup tasks
+
+**Creates:**
+- `.specd/tasks/project/PROJECT.md` — Project vision and goals
+- `.specd/tasks/project/research/` — Stack, features, architecture, pitfalls findings
+- `.specd/tasks/project/REQUIREMENTS.md` — Scoped v1 requirements with REQ-IDs
+- `.specd/tasks/project/ROADMAP.md` — Phased execution plan
+- `.specd/config.json` — Orchestrator config with projects array
+- Per sub-project: `.specd/config.json` + `.specd/tasks/setup/FEATURE.md`
+
+**This is a standalone command.** It runs its own sequential flow and exits. After scaffolding, use `/specd.new` and `/specd.continue` on individual sub-projects.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/new-project.md
+</execution_context>
+
+<context>
+Project name: $ARGUMENTS
+
+**No codebase context needed** — this is for greenfield projects with no existing code.
+
+**References:**
+- `~/.claude/specdacular/templates/tasks/PROJECT.md` — Project vision template
+- `~/.claude/specdacular/templates/tasks/REQUIREMENTS.md` — Requirements template (Phase 3)
+- `~/.claude/specdacular/agents/project-researcher.md` — Research agent (Phase 2)
+</context>
+
+<success_criteria>
+- [ ] Questioning produces PROJECT.md with clear vision, goals, users, constraints
+- [ ] Research spawns parallel agents for 4 domains (Phase 2)
+- [ ] Requirements scoped via multi-select from research (Phase 3)
+- [ ] Roadmap generated with phases mapped to requirements (Phase 3)
+- [ ] Sub-projects scaffolded with orchestrator config (Phase 4)
+- [ ] Each sub-project independently runnable via `/specd.new` and `/specd.continue`
+</success_criteria>

package/commands/specd.new-runner-task.md

@@ -0,0 +1,52 @@
+---
+name: specd.new-runner-task
+description: Create a new task in the Specd Runner app
+---
+
+<objective>
+Create a task in the Specd Runner by talking to its local API. Auto-detects the project from the current working directory.
+</objective>
+
+<instructions>
+
+## Step 1: Detect project
+
+Use Bash to find the matching project:
+
+```bash
+curl -s "http://localhost:3700/api/projects/by-path?path=$(pwd)" 2>/dev/null
+```
+
+If the runner is not running or no project matches, tell the user:
+- "The Specd Runner doesn't seem to be running. Start it with `specd runner`."
+- Or: "No project registered for this directory. Register with `specd runner register <path>`."
+
+## Step 2: Gather task details
+
+Ask the user for:
+1. **Task name** — short description (e.g., "Add dark mode support")
+2. **Description/spec** — what should be built (can be multi-line)
+3. **Working directory** — which subdirectory to work in (default: ".")
+4. **Pipeline** — which pipeline to use (default: "default")
+5. **Priority** — 1 (highest) to 99 (lowest), default 10
+
+## Step 3: Create the task
+
+```bash
+curl -s -X POST "http://localhost:3700/api/projects/{PROJECT_ID}/tasks" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "TASK_NAME",
+    "description": "DESCRIPTION",
+    "working_dir": "WORKING_DIR",
+    "pipeline": "PIPELINE",
+    "priority": PRIORITY,
+    "spec": "SPEC_CONTENT"
+  }'
+```
+
+## Step 4: Confirm
+
+Show the user the created task ID and confirm it's queued for execution.
+
+</instructions>

package/commands/specd.new.md

@@ -33,14 +33,14 @@ Initialize a task folder and start the first discussion. Creates structure, asks
 Task name: $ARGUMENTS
 
 **Codebase context discovery:**
-1. Check for `.specd/config.json` — if exists, read `codebase_docs` path
-2. If no config, check for `.specd/codebase/` (default location)
-3. If neither found, offer `/specd.codebase.map`
+1. Check for `CLAUDE.md` routing table — if exists, read referenced docs
+2. If no CLAUDE.md, check for `docs/` directory with specd-generated docs
+3. If neither found, offer `/specd.docs`
 
 **Referenced docs (when available):**
-- `MAP.md` — System structure
-- `PATTERNS.md` — Code patterns
-- `STRUCTURE.md` — Directory layout
+- `CLAUDE.md` — Routing table pointing to topic docs
+- `docs/rules.md` — Project-wide rules
+- `docs/*.md` — Topic-specific patterns and guidance
 </context>
 
 <process>

package/commands/specd.runner-status.md

@@ -0,0 +1,27 @@
+---
+name: specd.runner-status
+description: Show Specd Runner task status
+---
+
+<objective>
+Fetch and display the current status of all tasks across all projects from the Specd Runner.
+</objective>
+
+<instructions>
+
+## Step 1: Fetch status
+
+```bash
+curl -s "http://localhost:3700/api/status" 2>/dev/null
+```
+
+If the runner is not running, tell the user to start it with `specd runner`.
+
+## Step 2: Display
+
+Format the status as a readable table showing for each project:
+- Project name
+- Task list with status icons (done, running, failed, queued)
+- Current stage and progress for running tasks
+
+</instructions>

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "specdacular",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Feature planning system for existing codebases. Map, understand, and plan features in large projects.",
   "bin": {
-    "specdacular": "bin/install.js"
+    "specd": "bin/specd.js"
   },
   "files": [
     "bin",
@@ -11,6 +11,10 @@
     "agents",
     "specdacular",
     "hooks",
+    "runner/main",
+    "runner/renderer/dist",
+    "runner/preload.js",
+    "runner/package.json",
     "README.md"
   ],
   "keywords": [