specdacular 0.7.2 → 0.8.0

package/specdacular/workflows/orchestrator/plan.md

@@ -0,0 +1,169 @@
+# Workflow: Plan Task (Orchestrator Mode)
+
+This workflow handles planning when the task's `config.json` has `"orchestrator": true`.
+Called from the main `plan.md` workflow after orchestrator mode detection.
+
+## Input
+
+- `$TASK_NAME` — Validated task name
+- Orchestrator config and context already loaded
+
+## Steps
+
+<step name="load_cross_project_context">
+Load system-level and sub-project context.
+
+**System-level codebase docs:**
+- `.specd/codebase/PROJECTS.md` — Project registry
+- `.specd/codebase/TOPOLOGY.md` — Communication patterns
+- `.specd/codebase/CONTRACTS.md` — Shared interfaces
+
+**Sub-project context:**
+From task config.json `"projects"` array, for each project:
+- Read `{project-path}/.specd/tasks/{task-name}/FEATURE.md` — Project-specific requirements
+- Read `{project-path}/.specd/codebase/MAP.md` — Project code overview (if exists)
+- Read `{project-path}/.specd/codebase/PATTERNS.md` — Project patterns (if exists)
+
+```
+Orchestrator mode: {N} projects involved in this task.
+Loading cross-project context for phase derivation.
+```
+
+Continue to derive_phases.
+</step>
+
+<step name="derive_phases">
+Derive phases for all involved projects in a single orchestrator pass.
+
+**For each project, analyze:**
+- Project's FEATURE.md requirements
+- Project's codebase patterns
+- Cross-project dependencies (from CONTRACTS.md, TOPOLOGY.md)
+
+**Derive per-project phases:**
+Apply dependency-driven phasing for each project:
+1. Types/interfaces needed
+2. Data layer changes
+3. Business logic
+4. UI components (if applicable)
+5. Integration/wiring
+
+Adjust per project — not all projects need all phases.
+
+**Present consolidated view:**
+```
+Here's the proposed phase structure across all projects:
+
+**{project-1}** ({N} phases):
+  Phase 1: {Name} — {Goal}
+  Phase 2: {Name} — {Goal}
+
+**{project-2}** ({N} phases):
+  Phase 1: {Name} — {Goal}
+
+**Cross-project dependencies (preliminary):**
+- {project-1}/phase-1 → no cross-project deps
+- {project-2}/phase-2 → after {project-1}/phase-2
+
+Does this phasing make sense? Any adjustments?
+```
+
+Use AskUserQuestion to confirm or adjust.
+
+Continue to write_project_roadmaps.
+</step>
+
+<step name="write_project_roadmaps">
+Write ROADMAP.md for each involved sub-project.
+
+For each project, use template at `~/.claude/specdacular/templates/tasks/ROADMAP.md`.
+
+**IMPORTANT:** Sub-project ROADMAP.md must be self-contained. Dependencies listed are intra-project only. No references to other projects.
+
+**Create phase directories:**
+```bash
+mkdir -p {project-path}/.specd/tasks/{task-name}/phases/phase-01
+# ... for each phase
+```
+
+**Update sub-project STATE.md and config.json** with planning status.
+
+Continue to build_dependency_graph.
+</step>
+
+<step name="build_dependency_graph">
+Build cross-project phase dependency graph.
+
+**Analyze:** For each phase across all projects, determine cross-project dependencies using:
+- CONTRACTS.md — Interface creation/consumption
+- TOPOLOGY.md — Communication patterns
+- Per-project FEATURE.md — Integration points
+- Per-project ROADMAP.md — Phase goals
+
+**Present dependency table and confirm with user.**
+
+Continue to validate_dependencies.
+</step>
+
+<step name="validate_dependencies">
+Validate the dependency graph has no cycles.
+
+**Perform topological sort.** If cycle detected, present options to user to resolve.
+
+Continue to write_dependencies.
+</step>
+
+<step name="write_dependencies">
+Write DEPENDENCIES.md in orchestrator's task folder.
+
+Contents:
+- Project Involvement table
+- Phase Dependencies table (all "pending" initially)
+- Mermaid DAG visualization
+- Scheduling Notes
+
+**Update orchestrator STATE.md and config.json** to stage: planned.
+
+Continue to commit.
+</step>
+
+<step name="commit">
+Commit all roadmaps and dependency graph.
+
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** Orchestrator DEPENDENCIES.md, STATE.md, config.json + per-project ROADMAP.md, phases/, STATE.md, config.json
+- **$MESSAGE:** `docs({task-name}): create multi-project roadmap`
+- **$LABEL:** `multi-project roadmap creation`
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present multi-project roadmap summary.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MULTI-PROJECT ROADMAP CREATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Task:** {task-name}
+
+## Per-Project Phases
+
+{For each project:}
+**{project-name}** ({N} phases):
+  Phase 1: {Name} — {Goal}
+  ...
+
+## Cross-Project Dependencies
+
+{dependency summary}
+
+## What's Next
+
+/specd:continue {task-name} — Start executing phases
+```
+
+End workflow.
+</step>

package/specdacular/workflows/plan.md

@@ -0,0 +1,201 @@
+<purpose>
+Create execution phases from task context. Derives phases based on dependencies, creates one PLAN.md per phase, and writes ROADMAP.md.
+
+**Output:** `phases/phase-NN/PLAN.md` files, ROADMAP.md, updated STATE.md
+</purpose>
+
+<philosophy>
+
+## Small Phases
+
+Each phase should be small and focused. One PLAN.md per phase. If a phase feels too big, split it into two phases.
+
+## Dependencies Drive Order
+
+Phase order follows code dependencies: types before implementations, APIs before consumers, foundations before features.
+
+## Plans Are Self-Contained
+
+Each PLAN.md should have enough context that the executing agent doesn't need to ask questions. Reference decisions, research, and codebase patterns.
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+@~/.claude/specdacular/references/validate-task.md
+
+Use basic validation with $TASK_NAME from $ARGUMENTS.
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+@~/.claude/specdacular/references/load-context.md
+
+Load all task context including RESEARCH.md if available.
+
+**Check for orchestrator mode:**
+Read config.json. If `"orchestrator": true`:
+Hand off to orchestrator workflow:
+@~/.claude/specdacular/workflows/orchestrator/plan.md
+End main workflow.
+
+Continue to assess_readiness.
+</step>
+
+<step name="assess_readiness">
+Check if there's enough context to plan.
+
+**Required:**
+- FEATURE.md has specific "Must Create" items
+- At least some gray areas resolved in CONTEXT.md
+
+**Recommended but not required:**
+- RESEARCH.md exists (warn if missing)
+- All gray areas resolved
+
+**If not ready:**
+```
+Not enough context to create a plan yet.
+
+Missing:
+- {what's missing}
+
+Recommended next:
+- /specd:discuss {task-name} — Resolve gray areas
+- /specd:research {task-name} — Research implementation patterns
+```
+End workflow.
+
+**If ready but RESEARCH.md missing:**
+```
+Note: No research findings available. Plans will be based on discussion context only.
+Consider running /specd:research {task-name} first for better plans.
+```
+
+Continue to derive_phases.
+</step>
+
+<step name="derive_phases">
+Break the task into ordered phases based on dependencies.
+
+**Dependency ordering principles:**
+1. Types/interfaces before implementations
+2. Data models before APIs
+3. APIs before consumers (UI, CLI)
+4. Core before extensions
+5. Setup before usage
+
+**For each phase, define:**
+- Name and one-liner goal
+- Files to create and modify
+- Dependencies on other phases
+- Success criteria
+
+**Keep phases small:**
+- 2-5 tasks per phase
+- Each task creates or modifies 1-3 files
+- If a phase has >5 tasks, split it
+
+```bash
+mkdir -p .specd/tasks/{task-name}/phases
+```
+
+Continue to write_plans.
+</step>
+
+<step name="write_plans">
+Write one PLAN.md for each phase.
+
+For each phase:
+
+```bash
+mkdir -p .specd/tasks/{task-name}/phases/phase-$(printf '%02d' $N)
+```
+
+Write `phases/phase-NN/PLAN.md` using template from:
+`~/.claude/specdacular/templates/tasks/PLAN.md`
+
+Fill in:
+- YAML frontmatter: task name, phase number, dependencies, creates, modifies
+- Objective: what the phase accomplishes
+- Context: reference codebase patterns, relevant decisions, research findings
+- Tasks: 2-5 tasks with clear actions, verification, and done-when criteria
+
+**Each task should include:**
+- Files affected
+- Clear action description
+- Verification command
+- Done-when checklist
+
+Continue to write_roadmap.
+</step>
+
+<step name="write_roadmap">
+Write ROADMAP.md with phase overview.
+
+Use template from: `~/.claude/specdacular/templates/tasks/ROADMAP.md`
+
+Fill in all phase details, success criteria, and execution order diagram.
+
+Continue to update_state.
+</step>
+
+<step name="update_state">
+Update STATE.md and config.json.
+
+**STATE.md:**
+- Stage: planning (or execution if ready)
+- Mark phases derived and plans created
+- Update documents status
+
+**config.json:**
+- Set `stage` to `"planning"`
+- Set `phases.total` to phase count
+- Set `phases.current` to 1
+
+Continue to commit.
+</step>
+
+<step name="commit">
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/tasks/{task-name}/ROADMAP.md .specd/tasks/{task-name}/phases/ .specd/tasks/{task-name}/STATE.md .specd/tasks/{task-name}/config.json`
+- **$MESSAGE:** `docs({task-name}): create roadmap and phase plans` with phase summary
+- **$LABEL:** `planning complete`
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present the plan.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLANNING COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Task:** {task-name}
+**Phases:** {N}
+
+{For each phase:}
+Phase {N}: {Name} — {one-liner}
+└── PLAN.md ({task count} tasks)
+
+**Execution order:**
+{dependency diagram}
+```
+
+End workflow (caller handles continuation).
+</step>
+
+</process>
+
+<success_criteria>
+- Phases derived from task requirements and dependencies
+- One PLAN.md per phase with clear tasks
+- ROADMAP.md created with phase overview
+- STATE.md updated to planning stage
+- Changes committed
+</success_criteria>

package/specdacular/workflows/research.md

@@ -0,0 +1,166 @@
+<purpose>
+Research implementation patterns for a task. Spawns three parallel agents to investigate codebase integration, external patterns, and pitfalls. Synthesizes findings into RESEARCH.md.
+
+**Output:** `.specd/tasks/{task-name}/RESEARCH.md`, updated DECISIONS.md
+</purpose>
+
+<philosophy>
+
+## Three Dimensions
+
+Research covers three complementary angles:
+1. **Codebase Integration** — How this fits with existing code
+2. **Implementation Patterns** — Standard approaches and libraries
+3. **Pitfalls** — What commonly goes wrong
+
+## Confidence Over Quantity
+
+Mark findings with confidence levels. A few HIGH-confidence findings are more valuable than many LOW-confidence ones.
+
+## Decisions From Research
+
+When research reveals clear choices (library X over Y, pattern A over B), record them as decisions immediately.
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+@~/.claude/specdacular/references/validate-task.md
+
+Use basic validation with $TASK_NAME from $ARGUMENTS.
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+@~/.claude/specdacular/references/load-context.md
+
+Load all task context. Extract:
+- Task description and requirements (from FEATURE.md)
+- Active decisions/constraints (from DECISIONS.md)
+- Technology stack (from codebase docs if available)
+- Files to create/modify (from FEATURE.md)
+
+**Check if RESEARCH.md already exists:**
+```bash
+[ -f ".specd/tasks/$TASK_NAME/RESEARCH.md" ] && echo "existing"
+```
+
+**If exists:**
+Use AskUserQuestion:
+- header: "Research Exists"
+- question: "Research already exists. What would you like to do?"
+- options:
+  - "Re-run research" — Generate fresh findings
+  - "View existing" — Show current RESEARCH.md
+  - "Skip" — Use existing research
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+@~/.claude/specdacular/references/spawn-research-agents.md
+
+Prepare variables:
+- `$TASK_NAME` — from arguments
+- `$TASK_CONTEXT` — summary from FEATURE.md
+- `$CONSTRAINTS` — active decisions from DECISIONS.md
+- `$TECH_STACK` — from codebase docs (or "unknown")
+- `$FILES_TO_CREATE` — from FEATURE.md "Must Create"
+- `$FILES_TO_MODIFY` — from FEATURE.md "Must Integrate With"
+
+Spawn all three agents with `run_in_background: true`.
+
+Continue to collect_results.
+</step>
+
+<step name="collect_results">
+Wait for all three agents to complete.
+
+Read each agent's output. If an agent failed, note it but continue with available results.
+
+```
+Research agents complete:
+- Codebase Integration: {✓ | ✗}
+- Implementation Patterns: {✓ | ✗}
+- Pitfalls: {✓ | ✗}
+```
+
+Continue to synthesize.
+</step>
+
+<step name="synthesize">
+@~/.claude/specdacular/references/synthesize-research.md
+
+Combine agent outputs into `.specd/tasks/$TASK_NAME/RESEARCH.md`.
+
+Continue to record_decisions.
+</step>
+
+<step name="record_decisions">
+@~/.claude/specdacular/references/record-decision.md
+
+If research revealed clear technology/library/pattern choices, record them as decisions.
+
+Continue to update_state.
+</step>
+
+<step name="update_state">
+Update STATE.md and config.json.
+
+**STATE.md:**
+- Mark research as conducted
+- Mark RESEARCH.md as created
+- Update decisions count
+
+**config.json:**
+- Update `decisions_count`
+
+Continue to commit.
+</step>
+
+<step name="commit">
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/tasks/{task-name}/RESEARCH.md .specd/tasks/{task-name}/DECISIONS.md .specd/tasks/{task-name}/STATE.md .specd/tasks/{task-name}/config.json`
+- **$MESSAGE:** `docs({task-name}): research complete` with key findings summary
+- **$LABEL:** `research findings`
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present research summary.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RESEARCH COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Task:** {task-name}
+
+**Key recommendation:** {one-liner from RESEARCH.md}
+
+**Findings:**
+- Codebase: {brief summary}
+- Patterns: {brief summary}
+- Pitfalls: {brief summary}
+
+**Confidence:** {overall level}
+**New decisions:** {count}
+```
+
+End workflow (caller handles continuation).
+</step>
+
+</process>
+
+<success_criteria>
+- Three research agents spawned and completed
+- RESEARCH.md synthesized from agent findings
+- Confidence levels assigned
+- Research-driven decisions recorded in DECISIONS.md
+- STATE.md updated
+- Changes committed
+</success_criteria>