specdacular 0.5.3 → 0.6.1

package/README.md

@@ -33,11 +33,9 @@ npx specdacular
 - [How It Works](#how-it-works)
   - [Parallel Agents](#parallel-agents)
   - [Feature Flow](#feature-flow)
+- [Multi-Project Support](#multi-project-support)
 - [Project Structure](#project-structure)
 - [Philosophy](#philosophy)
-- [Migration Guides](#migration-guides)
-  - [From v0.5](#migrating-from-v05)
-  - [From v0.4](#migrating-from-v04)
 - [Updating](#updating)
 - [Uninstalling](#uninstalling)
 - [Contributing](#contributing)
@@ -58,6 +56,8 @@ Spawns 4 parallel agents to analyze your codebase and generate AI-optimized docu
 | `STRUCTURE.md` | Where do I put new code? |
 | `CONCERNS.md` | What will bite me? Gotchas? Tech debt? |
 
+For monorepos and multi-repo setups, it maps each sub-project in parallel, then produces system-level docs (`PROJECTS.md`, `TOPOLOGY.md`, `CONTRACTS.md`, `CONCERNS.md`) at the orchestrator level.
+
 ### 2. Plan Features
 
 Two commands drive the entire feature lifecycle:
@@ -69,6 +69,8 @@ Two commands drive the entire feature lifecycle:
 
 `feature:next` reads your feature's current state and offers the natural next step. You never need to remember which command comes next.
 
+Works with single projects and multi-project setups (monorepos, multi-repo). In multi-project mode, features are discussed at the system level and routed to the relevant sub-projects, with cross-project dependency tracking and contract validation.
+
 ---
 
 ## Requirements
@@ -106,7 +108,7 @@ In Claude Code:
 /specd:map-codebase
 ```
 
-Creates `.specd/codebase/` with 4 AI-optimized documents. This gives Claude context about your codebase's architecture, patterns, structure, and gotchas.
+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.
 
 ### Plan a Feature
 
@@ -327,9 +329,49 @@ review      → review-phase workflow
 
 ---
 
+## Multi-Project Support
+
+Specdacular supports monorepos and multi-repo setups through an orchestrator layer. All existing commands gain multi-project awareness automatically — no new commands to learn.
+
+### Setup
+
+```
+/specd:map-codebase
+```
+
+When it detects multiple projects (via `package.json`, `go.mod`, `Cargo.toml`, etc.), it offers to enable multi-project mode. This:
+
+1. Registers sub-projects in an orchestrator `.specd/config.json`
+2. Spawns 4 mapper agents per sub-project in parallel
+3. Runs an orchestrator mapper that produces system-level docs:
+
+| Document | What It Answers |
+|----------|-----------------|
+| `PROJECTS.md` | What projects exist, their tech stacks and purposes? |
+| `TOPOLOGY.md` | How do projects communicate? What's the data flow? |
+| `CONTRACTS.md` | What are the cross-project relationships and shared domains? |
+| `CONCERNS.md` | What are the system-level gotchas? |
+
+### Feature Planning
+
+`feature:new` conducts a system-level discussion, identifies which projects are involved, and creates per-project features with self-contained requirements. Each sub-project's `.specd/` works identically whether standalone or part of a multi-project setup.
+
+`feature:plan` creates per-project roadmaps plus a cross-project dependency graph (`DEPENDENCIES.md`) with cycle validation.
+
+### Execution & Scheduling
+
+`feature:next` schedules across projects, respecting cross-project dependencies. After each phase, it performs contract review — comparing what was implemented against system-level expectations and flagging deviations before they cascade to downstream projects.
+
+```
+/specd:feature:next auth-system       # Auto-picks next unblocked phase across projects
+/specd:feature:next auth-system api   # Target a specific sub-project
+```
+
+---
+
 ## Project Structure
 
-After using Specdacular:
+### Single Project
 
 ```
 your-project/
@@ -361,6 +403,44 @@ your-project/
 └── ...
 ```
 
+### Multi-Project
+
+```
+monorepo/
+├── .specd/                         # Orchestrator level
+│   ├── config.json                 # type: "orchestrator", projects list
+│   ├── codebase/                   # System-level docs
+│   │   ├── PROJECTS.md
+│   │   ├── TOPOLOGY.md
+│   │   ├── CONTRACTS.md
+│   │   └── CONCERNS.md
+│   └── features/
+│       └── auth-system/
+│           ├── FEATURE.md          # System-level requirements
+│           ├── DEPENDENCIES.md     # Cross-project dependency graph
+│           └── STATE.md            # Cross-project progress
+│
+├── api/
+│   └── .specd/                     # Sub-project (works standalone too)
+│       ├── config.json             # type: "project"
+│       ├── codebase/
+│       │   ├── MAP.md
+│       │   ├── PATTERNS.md
+│       │   ├── STRUCTURE.md
+│       │   └── CONCERNS.md
+│       └── features/
+│           └── auth-system/
+│               ├── FEATURE.md      # Project-specific requirements
+│               ├── ROADMAP.md      # Per-project phases
+│               └── plans/...
+│
+└── web/
+    └── .specd/                     # Another sub-project
+        ├── config.json
+        ├── codebase/...
+        └── features/...
+```
+
 ---
 
 ## Philosophy
@@ -389,48 +469,6 @@ Once recorded in `DECISIONS.md`, decisions aren't re-litigated. Each has date, c
 
 ---
 
-## Migration Guides
-
-### Migrating from v0.5
-
-**New command: `/specd:feature:next`** — Drives the entire feature lifecycle from a single command. Reads current state and offers the next step automatically.
-
-| Before (v0.5) | After (v0.6) |
-|----------------|--------------|
-| Remember command sequence: `discuss` → `research` → `plan` → `phase:prepare` → `phase:plan` → `phase:execute` → `phase:review` | Just run `/specd:feature:next` — it figures out what's next |
-| `feature:new` ends with list of commands to try | `feature:new` offers to continue discussing or stop with `feature:next` |
-
-**Existing `.specd/` data is fully compatible.** `feature:next` reads the same `config.json`, `STATE.md`, and other files.
-
-### Migrating from v0.4
-
-Commands were renamed into `feature:` and `phase:` namespaces:
-
-| v0.4 | v0.5 |
-|------|------|
-| `/specd:new-feature` | `/specd:feature:new` |
-| `/specd:discuss-feature` | `/specd:feature:discuss` |
-| `/specd:research-feature` | `/specd:feature:research` |
-| `/specd:plan-feature` | `/specd:feature:plan` |
-| `/specd:discuss-phase` | `/specd:phase:prepare` |
-| `/specd:research-phase` | `/specd:phase:research` |
-| `/specd:execute-plan` | `/specd:phase:execute` |
-| `/specd:insert-phase` | `/specd:phase:insert` |
-| `/specd:renumber-phases` | `/specd:phase:renumber` |
-
-**New commands in v0.5:**
-- `/specd:phase:prepare` — Replaces `discuss-phase`, adds optional research at the end
-- `/specd:phase:plan` — Creates detailed plans for **one phase** (new command)
-
-**Behavior changes in v0.5:**
-- `feature:plan` now creates only `ROADMAP.md` + empty phase directories. It no longer creates `PLAN.md` files for all phases upfront.
-- Detailed `PLAN.md` files are created per-phase with `phase:plan`, right before execution.
-- `phase:prepare` combines the old discuss-phase + research-phase into a single command.
-
-**Existing `.specd/` data is fully compatible.** Your feature files, decisions, and roadmaps work with the new commands.
-
----
-
 ## Updating
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "Feature planning system for existing codebases. Map, understand, and plan features in large projects.",
   "bin": {
     "specdacular": "bin/install.js"
@@ -10,9 +10,11 @@
     "commands",
     "agents",
     "specdacular",
-    "hooks"
+    "hooks",
+    "README.md"
   ],
   "keywords": [
+    "specd",
     "claude",
     "claude-code",
     "ai",

package/specdacular/templates/features/DEPENDENCIES.md

@@ -0,0 +1,47 @@
+# Dependencies: {feature-name}
+
+**Last Updated:** {YYYY-MM-DD}
+
+## Overview
+
+{Brief description of how this feature spans multiple projects and what each project contributes.}
+
+---
+
+## Project Involvement
+
+| Project | Role | Path |
+|---------|------|------|
+| {project-name} | {What this project does for this feature} | {./relative/path} |
+
+---
+
+## Phase Dependencies
+
+| Phase | Depends On | Status |
+|-------|------------|--------|
+| {project}/phase-{N} | — | pending |
+| {project}/phase-{N} | {project}/phase-{N} | blocked |
+
+**Status values:** `pending` | `blocked` | `in-progress` | `complete`
+
+---
+
+## Dependency Graph
+
+```mermaid
+graph TD
+    A1[{project-a}/phase-1] --> A2[{project-a}/phase-2]
+    B1[{project-b}/phase-1] --> B2[{project-b}/phase-2]
+    A2 --> B2
+```
+
+---
+
+## Scheduling Notes
+
+{Notes about execution order, parallelism opportunities, and constraints.}
+
+- Phases with no dependencies can start immediately
+- Phases with all dependencies `complete` are unblocked
+- The `next` command reads this table to determine what work is available

package/specdacular/templates/orchestrator/CONCERNS.md

@@ -0,0 +1,27 @@
+# System Concerns
+
+**Last Updated:** {YYYY-MM-DD}
+
+## Overview
+
+{Brief description of cross-cutting system-level concerns that affect multiple projects. These are distinct from per-project concerns in each project's `.specd/codebase/CONCERNS.md`.}
+
+---
+
+## {Concern Title}
+
+**Scope:** {Which projects are affected}
+**Issue:** {What the concern is — the cross-cutting problem}
+**Impact:** {What goes wrong if this is ignored during planning/execution}
+**Mitigation:** {How to handle this during feature planning and phase execution}
+
+---
+
+{Repeat for each system-level concern}
+
+## Concern Categories
+
+| Category | Concerns | Projects Affected |
+|----------|----------|-------------------|
+| {e.g., Data Consistency} | {concern titles} | {project list} |
+| {e.g., Deployment Order} | {concern titles} | {project list} |

package/specdacular/templates/orchestrator/CONTRACTS.md

@@ -0,0 +1,31 @@
+# Contracts
+
+**Last Updated:** {YYYY-MM-DD}
+
+## Overview
+
+{Brief description of how contracts work in this system. These are stable relationship descriptions — specific contracts for individual features are defined in each feature's FEATURE.md.}
+
+---
+
+## {project-a} ↔ {project-b}
+
+**Communication:** {REST, gRPC, pub/sub, etc.}
+**Pattern:** {Consumer/provider relationship}
+**Shared Domains:** {What concepts/data they share}
+**Source of Truth:** {Which project defines the contract}
+
+### Contract Nature
+
+{Prose description of what flows between these projects and the general expectations. This is NOT a detailed API spec — it describes the relationship so that feature planning can identify which projects are affected.}
+
+---
+
+{Repeat for each project relationship with contracts}
+
+## Notes
+
+- These contracts describe relationship patterns, not specific endpoints
+- Feature-level contracts (specific endpoints, schemas) are defined in each feature's orchestrator FEATURE.md
+- Deviation detection runs against feature-level contracts, not this document
+- This document helps with feature routing: identifying which projects a feature involves

package/specdacular/templates/orchestrator/PROJECTS.md

@@ -0,0 +1,39 @@
+# Projects
+
+**Last Updated:** {YYYY-MM-DD}
+**Project Count:** {N}
+
+---
+
+## Project Registry
+
+| Project | Path | Tech Stack | Purpose |
+|---------|------|------------|---------|
+| {project-name} | {./relative/path} | {e.g., Node.js, TypeScript, Next.js} | {One-liner purpose} |
+
+---
+
+## {project-name}
+
+**Path:** `{./relative/path}`
+**Tech Stack:** {stack}
+**Purpose:** {What this project does in the system}
+
+### Responsibilities
+
+- {What this project owns and manages}
+
+### Key Entry Points
+
+- `{path/to/main/file}` — {What it does, why other projects care}
+
+### Codebase Docs
+
+- `{project-path}/.specd/codebase/MAP.md` — System overview
+- `{project-path}/.specd/codebase/PATTERNS.md` — Code patterns
+- `{project-path}/.specd/codebase/STRUCTURE.md` — File structure
+- `{project-path}/.specd/codebase/CONCERNS.md` — Project-level concerns
+
+---
+
+{Repeat for each project}

package/specdacular/templates/orchestrator/TOPOLOGY.md

@@ -0,0 +1,43 @@
+# Topology
+
+**Last Updated:** {YYYY-MM-DD}
+
+## Overview
+
+{Brief description of how projects in this system communicate. 2-3 sentences.}
+
+---
+
+## Project Relationships
+
+### {project-a} ↔ {project-b}
+
+**Communication:** {REST, gRPC, pub/sub, shared database, file system, etc.}
+**Pattern:** {Who initiates, who responds. e.g., "UI is the sole consumer of the API"}
+**Shared Domains:** {What data/concepts they share. e.g., "Authentication, Users, Projects"}
+**Source of Truth:** {Which project defines the contract. e.g., "API defines the contract, UI adapts"}
+
+**Data Flow:**
+- {project-a} → {project-b}: {What data/events flow in this direction}
+- {project-b} → {project-a}: {What data/events flow in this direction}
+
+---
+
+{Repeat for each project relationship}
+
+## Shared Resources
+
+{Resources shared across projects — databases, caches, queues, file storage.}
+
+| Resource | Type | Used By | Owner |
+|----------|------|---------|-------|
+| {resource-name} | {database, cache, queue, etc.} | {project-a, project-b} | {which project manages it} |
+
+---
+
+## Communication Diagram
+
+```mermaid
+graph LR
+    A[{project-a}] -->|{protocol}| B[{project-b}]
+```

package/specdacular/templates/orchestrator/config.json

@@ -0,0 +1,12 @@
+{
+  "type": "orchestrator",
+  "specd_version": 1,
+  "created": "{date}",
+  "projects": [
+    {
+      "name": "{project-name}",
+      "path": "{./relative/path}",
+      "description": "{One-liner purpose}"
+    }
+  ]
+}

package/specdacular/workflows/execute-plan.md

@@ -96,6 +96,40 @@ Load ALL context needed for execution.
 - `STRUCTURE.md` — Where files go
 - `MAP.md` — System overview
 
+**Check for orchestrator mode:**
+
+Read feature's `config.json`. If `"orchestrator": true`:
+
+Set mode = "orchestrator".
+
+**Load orchestrator context:**
+- Orchestrator FEATURE.md — System-level expectations (used for contract validation)
+- Orchestrator DEPENDENCIES.md — Cross-project dependency graph
+- Orchestrator STATE.md — Which project/phase to execute
+
+**Determine target project:**
+From orchestrator STATE.md or arguments, identify which project and phase to execute.
+Read the target project's feature context:
+- `{project-path}/.specd/features/{feature-name}/config.json`
+- `{project-path}/.specd/features/{feature-name}/STATE.md`
+- `{project-path}/.specd/features/{feature-name}/ROADMAP.md`
+- `{project-path}/.specd/features/{feature-name}/DECISIONS.md`
+
+Read the project's codebase context:
+- `{project-path}/.specd/codebase/PATTERNS.md`
+- `{project-path}/.specd/codebase/STRUCTURE.md`
+- `{project-path}/.specd/codebase/MAP.md`
+
+```
+Orchestrator mode: executing in {project-name} ({project-path}).
+Feature: {feature-name}, Phase {N}.
+```
+
+Continue to find_plan (with project-path-prefixed plan lookup).
+
+**If not orchestrator:**
+Set mode = "project".
+
 **Internalize:**
 - Which plans are complete (from STATE.md)
 - Which phase we're in
@@ -390,9 +424,126 @@ All plans complete! Feature '{feature}' is implemented.
 Review STATE.md and CHANGELOG.md for summary.
 ```
 
+**If orchestrator mode:**
+Continue to contract_review.
+
+**If single-project mode:**
 End workflow.
 </step>
 
+<step name="contract_review">
+Review completed phase against cross-project contract expectations (orchestrator mode only).
+
+**Only runs in orchestrator mode, after a plan completes in a sub-project.**
+
+**Gather what was implemented:**
+1. Read the sub-project's CHANGELOG.md for this plan — deviations and changes
+2. Review files created/modified during this plan
+3. Understand what the phase actually produced
+
+**Compare against expectations:**
+1. Read orchestrator FEATURE.md — system-level requirements and cross-project contracts
+2. Read DEPENDENCIES.md — which other project phases depend on this phase's output
+3. For each downstream dependency, check: does the actual output match what the dependent phase expects?
+
+**Assessment:**
+```
+### Contract Review: {project-name}/phase-{N}
+
+**Implemented:** {brief summary of what was built}
+
+**Cross-project impact:**
+{For each dependent phase:}
+- {other-project}/phase-{M}: {expects X} → {actual output matches / deviates}
+```
+
+**If no deviations:**
+```
+No contract deviations detected. Downstream phases can proceed as planned.
+```
+
+Update orchestrator STATE.md: mark this project phase as complete.
+Continue to orchestrator_phase_complete.
+
+**If deviations detected:**
+```
+Contract deviation detected:
+
+**What changed:** {description of deviation}
+**Expected by:** {list of dependent project phases}
+**Impact:** {what breaks or needs updating}
+
+For example:
+"API changed /auth/login response from {token: string} to {accessToken: string, refreshToken: string}.
+UI phase 2 expects {token: string}. Will need to update token handling."
+```
+
+Use AskUserQuestion:
+- header: "Deviation"
+- question: "How would you like to handle this contract deviation?"
+- options:
+  - "Accept and update" — Accept the deviation, update orchestrator notes, continue
+  - "Trigger replan" — Replan affected project phases to accommodate the change
+  - "Investigate" — Look deeper before deciding
+
+**If "Accept and update":**
+- Log deviation to orchestrator CHANGELOG.md
+- Note that downstream phases should account for the change
+- Continue to orchestrator_phase_complete
+
+**If "Trigger replan":**
+- Check cascade depth (DEC-010)
+- If depth < 2: trigger replan for affected project phases
+  - Update affected project's ROADMAP.md phase description
+  - Regenerate affected PLAN.md files
+  - Log to orchestrator CHANGELOG.md
+  - Increment cascade depth
+- If depth >= 2: force pause
+  ```
+  Multiple cascading replans detected (depth {N}).
+
+  This suggests a significant architectural mismatch.
+  Before continuing, review the overall approach:
+  - Are the project responsibilities correctly divided?
+  - Should the feature be restructured?
+
+  Recommend: /specd:feature:discuss {feature-name} to reassess.
+  ```
+  End workflow (user must explicitly resume).
+</step>
+
+<step name="orchestrator_phase_complete">
+Update orchestrator state and present summary after contract review.
+
+**Update orchestrator STATE.md:**
+- Mark this project's phase as complete in Sub-Project Features table
+- Update orchestrator progress
+
+**Update orchestrator config.json:**
+- Increment completed phase count if all plans for this project phase are done
+
+**Present summary:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE COMPLETE (ORCHESTRATOR)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+**Project:** {project-name}
+**Phase:** {N}
+**Contract review:** {passed / deviations accepted / replanned}
+
+**Next unblocked work:**
+{From DEPENDENCIES.md — which phases are now unblocked by this completion}
+
+───────────────────────────────────────────────────────
+
+Resume with /specd:feature:next {feature-name}
+```
+
+End workflow (returns to orchestrator scheduling via next).
+</step>
+
 </process>
 
 <changelog_format>
@@ -418,6 +569,8 @@ Types:
 </changelog_format>
 
 <success_criteria>
+
+## Single-Project Mode
 - Feature validated with plans
 - All context loaded and internalized
 - Tasks executed in plan order
@@ -426,4 +579,16 @@ Types:
 - Commits made with proper format
 - STATE.md updated with progress
 - Next plan identified or completion announced
+
+## Multi-Project Mode (Orchestrator)
+- Orchestrator mode detected from feature config.json
+- Sub-project context loaded with path-prefixed file access
+- Plans executed inline in sub-project context
+- Contract review performed after phase completion (DEC-004)
+- Deviations flagged with cross-project impact analysis
+- User can accept deviation or trigger replan
+- Replan cascade depth limited to 2 (DEC-010)
+- Orchestrator STATE.md updated after each phase
+- Summary shows next unblocked work
+
 </success_criteria>