specdacular 0.5.3 → 0.6.1

package/specdacular/workflows/new-feature.md

@@ -76,13 +76,38 @@ Continue to codebase_context.
 </step>
 
 <step name="codebase_context">
-Look for codebase documentation.
+Look for codebase documentation and detect orchestrator mode.
 
 **Check for existing config:**
 ```bash
 cat .specd/config.json 2>/dev/null
 ```
 
+**Check for orchestrator mode (DEC-006):**
+
+If config exists, read `"type"` field.
+
+**If type = "orchestrator":**
+Set mode = "orchestrator".
+
+Read system-level codebase docs:
+- `.specd/codebase/PROJECTS.md` — Project registry
+- `.specd/codebase/TOPOLOGY.md` — Communication patterns
+- `.specd/codebase/CONTRACTS.md` — Shared interfaces
+- `.specd/codebase/CONCERNS.md` — System-level concerns
+
+Read project list from config.json `"projects"` array.
+
+```
+Orchestrator mode detected. {N} projects registered.
+I'll use system-level docs to understand cross-project architecture.
+```
+
+Continue to orchestrator_discussion.
+
+**If type = "project" or absent:**
+Set mode = "project".
+
 **If config exists with codebase_docs path:**
 Use that path for codebase docs.
 
@@ -118,6 +143,351 @@ Ask for path, then save to `.specd/config.json`.
 Continue to first_discussion.
 </step>
 
+<step name="orchestrator_discussion">
+System-level feature discussion for orchestrator mode.
+
+**Opening:**
+```
+Let's talk about what you're building across the system.
+
+What's the {feature-name} feature? What system-level behavior does it add?
+```
+
+Wait for response.
+
+**Follow the thread:**
+Based on their response, ask follow-up questions that:
+- Identify which projects are affected ("Which parts of the system does this touch?")
+- Explore cross-project behavior ("How would data flow between projects for this?")
+- Identify contract implications ("Does this change how projects communicate?")
+- Understand project responsibilities ("What does each project need to do?")
+
+**System-level probes (follow the conversation, don't march through):**
+- "Which projects does this involve?"
+- "What crosses project boundaries here?"
+- "Does this change any existing communication patterns?"
+- "What's each project's responsibility for this feature?"
+- "Are there shared data structures or APIs that need to align?"
+- "What's the simplest cross-project version that would work?"
+
+**Use system-level context from codebase docs:**
+- Reference PROJECTS.md for project responsibilities
+- Reference TOPOLOGY.md for existing communication patterns
+- Reference CONTRACTS.md for existing shared interfaces
+- Reference CONCERNS.md for system-level gotchas that might apply
+
+**Check understanding:**
+After 4-6 exchanges, summarize with project involvement:
+```
+So if I understand correctly:
+- This feature [system-level behavior]
+- It involves these projects:
+  - {project-1}: [responsibility]
+  - {project-2}: [responsibility]
+- Cross-project interaction: [how projects coordinate]
+- Key constraint: [constraint]
+
+Does that capture it, or should we dig into anything more?
+```
+
+**When to move on:**
+- User confirms understanding is correct
+- You have a clear project list with per-project responsibilities
+- Cross-project behavior is understood
+
+Continue to route_projects.
+</step>
+
+<step name="route_projects">
+Confirm which projects are involved in this feature.
+
+**Build project suggestion:**
+From the discussion, identify involved projects. Cross-reference with:
+- CONTRACTS.md — which projects have existing relationships relevant to this feature
+- PROJECTS.md — project responsibilities that align with feature needs
+
+**Present suggestion:**
+```
+Based on our discussion, these projects are involved:
+
+{For each project:}
+- **{project-name}** ({project-path}) — {responsibility for this feature}
+
+{If any projects from config NOT included:}
+Not involved: {project-name} — {brief reason}
+```
+
+Use AskUserQuestion:
+- header: "Projects"
+- question: "Are these the right projects for this feature?"
+- options:
+  - "Yes, looks right" — Continue with these projects
+  - "I need to adjust" — Add or remove projects
+
+**If "I need to adjust":**
+Ask user which projects to add or remove. Update the list accordingly.
+
+**Store project routing:**
+Build routing data:
+```json
+{
+  "projects": [
+    {"name": "{project-name}", "path": "{project-path}", "responsibility": "{what this project does for the feature}"}
+  ]
+}
+```
+
+Continue to create_orchestrator_feature.
+</step>
+
+<step name="create_orchestrator_feature">
+Create orchestrator-level feature folder with system-view documents.
+
+**Create feature directory:**
+```bash
+mkdir -p .specd/features/{feature-name}
+```
+
+**Write FEATURE.md (system view):**
+Use template at `~/.claude/specdacular/templates/features/FEATURE.md` but adapt for system level:
+
+- **What This Is:** System-level description from orchestrator discussion
+- **Must Create:** List the involved projects and what each creates (high-level)
+- **Must Integrate With:** Cross-project interactions, existing contracts affected
+- **Constraints:** System-level constraints (cross-project coordination, contract alignment)
+- **Success Criteria:** System-level observable behaviors (not project-level details)
+- **Out of Scope:** Explicit exclusions from the discussion
+- **Initial Context:**
+  - User Need: from discussion
+  - Projects Involved: list with responsibilities
+  - Cross-Project Contracts: what needs to align between projects
+
+**Write CONTEXT.md:**
+Use template at `~/.claude/specdacular/templates/features/CONTEXT.md`
+
+Fill in:
+- **Discussion Summary:** System-level discussion summary
+- **Resolved Questions:** Questions answered during orchestrator discussion
+- **Deferred Questions:** Things to resolve during planning
+- **Gray Areas Remaining:** Open areas
+
+**Write DECISIONS.md:**
+Use template at `~/.claude/specdacular/templates/features/DECISIONS.md`
+Record any decisions made during the system-level discussion.
+
+**Write CHANGELOG.md:**
+Use template at `~/.claude/specdacular/templates/features/CHANGELOG.md`
+Initialize empty.
+
+**Write STATE.md:**
+Use template at `~/.claude/specdacular/templates/features/STATE.md`
+
+Initialize with:
+- Stage: discussion
+- Initial discussion complete: yes
+- Add "Sub-Project Features" section:
+
+```markdown
+## Sub-Project Features
+
+| Project | Path | Feature Path | Status |
+|---------|------|--------------|--------|
+| {project-name} | {project-path} | {project-path}/.specd/features/{feature-name}/ | initialized |
+```
+
+**Write config.json:**
+```json
+{
+  "feature_name": "{name}",
+  "created": "{date}",
+  "stage": "discussion",
+  "discussion_sessions": 1,
+  "decisions_count": {N},
+  "orchestrator": true,
+  "projects": [
+    {"name": "{project-name}", "path": "{project-path}", "responsibility": "{responsibility}"}
+  ]
+}
+```
+
+Continue to delegate_to_projects.
+</step>
+
+<step name="delegate_to_projects">
+Create feature folders in each involved sub-project with translated requirements.
+
+For each project in the routing data:
+
+**Create feature directory:**
+```bash
+mkdir -p {project-path}/.specd/features/{feature-name}
+```
+
+**Write FEATURE.md (project-specific):**
+Use template at `~/.claude/specdacular/templates/features/FEATURE.md`
+
+Translate the system-level requirements into project-specific requirements:
+- **What This Is:** What this project specifically does for the feature (not the system-level description)
+- **Must Create:** Specific files/components this project needs to create
+- **Must Integrate With:** Existing code in THIS project + cross-project interfaces it must implement
+- **Constraints:** Project-specific constraints + any contract requirements from the orchestrator
+- **Success Criteria:** Project-specific observable behaviors
+- **Out of Scope:** What this project does NOT handle (other projects' responsibilities)
+- **Initial Context:**
+  - User Need: project-specific slice of the system need
+  - Integration Points: what this project exposes or consumes from other projects
+
+**IMPORTANT (DEC-001):** The sub-project FEATURE.md must read like a normal, self-contained feature requirement. No references to "orchestrator," "multi-project," or other projects by name. Cross-project requirements should be phrased as external interface requirements:
+- BAD: "API project must expose /auth/login for the UI project"
+- GOOD: "Must expose /auth/login endpoint that returns JWT tokens"
+
+**Write CONTEXT.md:**
+Use template at `~/.claude/specdacular/templates/features/CONTEXT.md`
+- Discussion Summary: "Requirements defined as part of system-level {feature-name} feature planning."
+- Resolved Questions: Any project-specific questions resolved during orchestrator discussion
+
+**Write DECISIONS.md:**
+Use template at `~/.claude/specdacular/templates/features/DECISIONS.md`
+Include any project-specific decisions from orchestrator discussion.
+
+**Write CHANGELOG.md:**
+Use template at `~/.claude/specdacular/templates/features/CHANGELOG.md`
+Initialize empty.
+
+**Write STATE.md:**
+Use template at `~/.claude/specdacular/templates/features/STATE.md`
+Initialize with stage: discussion, initial discussion complete: yes.
+
+**Write config.json:**
+```json
+{
+  "feature_name": "{name}",
+  "created": "{date}",
+  "stage": "discussion",
+  "discussion_sessions": 0,
+  "decisions_count": {N}
+}
+```
+
+Note: `discussion_sessions: 0` because no per-project discussion happened — requirements came from orchestrator delegation.
+
+After all projects processed, verify:
+```bash
+for project in {project-paths}; do
+  echo "Checking $project..."
+  ls "$project/.specd/features/{feature-name}/"
+done
+```
+
+Continue to orchestrator_feature_commit.
+</step>
+
+<step name="orchestrator_feature_commit">
+Commit orchestrator and all sub-project feature files.
+
+```bash
+# Add orchestrator feature files
+git add .specd/features/{feature-name}/
+
+# Add per-project feature files
+{For each project:}
+git add {project-path}/.specd/features/{feature-name}/
+
+git commit -m "docs({feature-name}): initialize multi-project feature
+
+Orchestrator:
+- FEATURE.md: System-level requirements
+- CONTEXT.md: Cross-project discussion
+- DECISIONS.md: {N} decisions
+- STATE.md: Sub-project tracking
+
+Projects:
+{For each project:}
+- {project-name}: Project-specific requirements
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+Continue to orchestrator_feature_completion.
+</step>
+
+<step name="orchestrator_feature_completion">
+Present multi-project feature creation summary.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MULTI-PROJECT FEATURE INITIALIZED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+
+## Orchestrator (.specd/features/{feature-name}/)
+
+- FEATURE.md — System-level requirements
+- CONTEXT.md — Cross-project discussion
+- DECISIONS.md — {N} decisions recorded
+- STATE.md — Sub-project tracking
+
+## Projects
+
+{For each project:}
+**{project-name}** ({project-path}/.specd/features/{feature-name}/)
+- FEATURE.md — {brief responsibility summary}
+- Responsibility: {one-liner}
+
+## Summary
+
+{2-3 sentence system-level summary}
+```
+
+Continue to orchestrator_continuation_offer.
+</step>
+
+<step name="orchestrator_continuation_offer">
+Offer to continue or stop (same pattern as existing continuation_offer).
+
+**If gray areas remain in orchestrator CONTEXT.md:**
+
+Use AskUserQuestion:
+- header: "Continue?"
+- question: "Want to keep discussing the open areas, or come back later?"
+- options:
+  - "Keep discussing" — Dive into the gray areas now
+  - "Stop for now" — Come back with /specd:feature:next {feature-name}
+
+**If Keep discussing:**
+Execute the discuss-feature workflow logic:
+@~/.claude/specdacular/workflows/discuss-feature.md
+
+After discussion completes, return to this step.
+
+**If no gray areas remain:**
+
+Use AskUserQuestion:
+- header: "Continue?"
+- question: "Discussion looks solid. Want to keep going or come back later?"
+- options:
+  - "Continue" — Move to the next step (research or planning)
+  - "Stop for now" — Come back with /specd:feature:next {feature-name}
+
+**If Continue:**
+Hand off to next-feature workflow:
+@~/.claude/specdacular/workflows/next-feature.md
+
+Start from the read_state step with the current feature.
+
+**If Stop for now:**
+```
+───────────────────────────────────────────────────────
+
+Progress saved. Pick up where you left off anytime:
+
+/specd:feature:next {feature-name}
+```
+
+End workflow.
+</step>
+
 <step name="first_discussion">
 Start the conversation.
 
@@ -368,6 +738,8 @@ End workflow.
 </process>
 
 <success_criteria>
+
+## Single-Project Mode
 - Feature folder created at `.specd/features/{name}/`
 - FEATURE.md has specific technical requirements (files to create, integrations)
 - CONTEXT.md captures the discussion state
@@ -377,4 +749,19 @@ End workflow.
 - config.json created
 - Committed to git
 - User presented with clear next options
+
+## Multi-Project Mode (Orchestrator)
+- Orchestrator mode detected from `.specd/config.json` type field
+- System-level discussion focuses on cross-project behavior
+- Project routing suggests involved projects from discussion + CONTRACTS.md
+- User confirms or adjusts project selection
+- Orchestrator feature folder created with system-level FEATURE.md, CONTEXT.md, DECISIONS.md, STATE.md
+- Orchestrator STATE.md includes Sub-Project Features table
+- Orchestrator config.json includes `orchestrator: true` and `projects` array
+- Each sub-project gets feature folder with project-specific requirements
+- Sub-project FEATURE.md reads as normal self-contained feature (DEC-001)
+- All files committed (orchestrator + all sub-projects)
+- Multi-project summary presented
+- User presented with clear next options
+
 </success_criteria>

package/specdacular/workflows/next-feature.md

@@ -3,6 +3,8 @@ Smart state machine that reads current feature state and drives the entire lifec
 
 **One command for the entire lifecycle:** discussion, research, planning, phase preparation, phase planning, phase execution, phase review.
 
+**Multi-project:** In orchestrator mode, aggregates state across all sub-projects and uses the dependency graph to schedule work. Users can also work directly in sub-projects for single-project changes (DEC-001).
+
 **Core loop:**
 ```
 read state → show status → determine next action → execute → loop
@@ -112,6 +114,40 @@ ls .specd/features/{name}/plans/phase-{NN}/*-PLAN.md 2>/dev/null | head -1
 # Check STATE.md for completed plans in this phase
 ```
 
+**Check for orchestrator mode:**
+
+Read feature's `config.json`. If `"orchestrator": true`:
+
+Set mode = "orchestrator".
+
+**Aggregate cross-project state:**
+1. Read orchestrator DEPENDENCIES.md — cross-project phase dependency graph
+2. For each project in feature config.json `"projects"` array:
+   - Read `{project-path}/.specd/features/{feature-name}/config.json` — stage, phases
+   - Read `{project-path}/.specd/features/{feature-name}/STATE.md` — detailed progress
+
+**Build combined state:**
+For each project phase, determine status:
+- **complete** — All plans executed for this phase
+- **in_progress** — Some plans executed
+- **ready** — All cross-project dependencies satisfied, phase can start
+- **blocked** — Waiting on another project's phase to complete
+- **not_started** — Phase exists but not yet prepared/planned
+
+**Check for optional project argument:**
+If arguments contain a second token after feature name (e.g., `/specd:feature:next feature-name project-name`):
+- Set target_project = project name
+- Validate project exists in feature config.json
+
+```
+Orchestrator mode: aggregating state across {N} projects.
+```
+
+Continue to show_status (orchestrator variant).
+
+**If not orchestrator:**
+Set mode = "project".
+
 Continue to show_status.
 </step>
 
@@ -154,7 +190,103 @@ Present a concise status summary.
 **Phase status:** {prepared | planned | executing | executed}
 ```
 
+**If mode = "project":**
 Continue to determine_action.
+
+**If mode = "orchestrator":**
+
+```
+## {feature-name} (Multi-Project)
+
+**Stage:** {stage}
+**Overall progress:** {total completed phases}/{total phases} across {N} projects
+
+### Per-Project Status
+
+{For each project:}
+**{project-name}** — {completed}/{total} phases
+  {For each phase: status indicator + name}
+  ✓ Phase 1: {name} — complete
+  ▶ Phase 2: {name} — ready
+  ○ Phase 3: {name} — blocked by {dep}
+
+### Cross-Project Dependencies
+
+{Summary of key dependencies and their status}
+
+**Note:** One orchestrator session at a time (DEC-011). State re-read fresh each time.
+```
+
+Continue to orchestrator_schedule.
+</step>
+
+<step name="orchestrator_schedule">
+Determine next work based on cross-project dependencies.
+
+**Compute unblocked work:**
+From the combined state and dependency graph:
+1. Find all phases with status "ready" (dependencies satisfied, not started/in-progress)
+2. Among "ready" phases, prioritize by:
+   - Phases that unblock the most downstream work
+   - Earlier phases within a project
+   - Projects with less progress (balance workload)
+
+**If target_project specified (from argument):**
+Filter to only that project's unblocked work.
+
+**If no unblocked work:**
+```
+All available phases are blocked or complete.
+
+{If all complete:}
+All phases across all projects are complete! Feature is implemented.
+
+{If blocked:}
+Waiting on:
+{List blocked phases and what they're waiting on}
+```
+
+→ Go to action_complete (if all done) or action_stop (if blocked).
+
+**If one phase unblocked:**
+Auto-suggest:
+```
+Next: {project-name}/Phase {N} — {phase-name}
+{Brief description of what this phase does}
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Execute {project-name} Phase {N}?"
+- options:
+  - "Execute (Recommended)" — Run this phase
+  - "Stop for now" — Come back later
+
+**If multiple phases unblocked:**
+```
+Multiple phases are ready:
+
+{For each ready phase:}
+- **{project-name}/Phase {N}** — {phase-name} ({brief description})
+```
+
+Use AskUserQuestion:
+- header: "Next Step"
+- question: "Which phase should we work on next?"
+- options: List each ready phase as an option + "Stop for now"
+
+**After selection:**
+Set the target project and phase.
+
+**Determine phase readiness:**
+Check if the target phase is prepared and planned:
+- If not prepared: → delegate to prepare-phase workflow
+- If prepared but not planned: → delegate to plan-phase workflow
+- If planned: → delegate to execute-plan workflow
+
+Pass feature name and project context to the delegated workflow.
+
+After delegated workflow completes, loop back to read_state.
 </step>
 
 <step name="determine_action">
@@ -487,6 +619,8 @@ End workflow.
 </process>
 
 <success_criteria>
+
+## Single-Project Mode
 - Feature selected (from argument or picker)
 - Current state accurately read and displayed
 - Correct next action determined from state
@@ -494,4 +628,17 @@ End workflow.
 - Looped back after action completion
 - User could stop at any natural boundary
 - Clean exit with resume instructions
+
+## Multi-Project Mode (Orchestrator)
+- Orchestrator mode detected from feature config.json
+- Cross-project state aggregated from all sub-projects
+- Dependency graph read from DEPENDENCIES.md
+- Per-project progress dashboard displayed
+- Unblocked work computed from dependency graph
+- Auto-suggests when one phase ready, asks when multiple
+- Optional project argument: /specd:feature:next feature project
+- Delegates to prepare/plan/execute based on phase readiness
+- One-session-at-a-time constraint documented (DEC-011)
+- Direct sub-project access always works (DEC-001)
+
 </success_criteria>