specdacular 0.7.1 → 0.8.0

package/specdacular/workflows/review.md

@@ -0,0 +1,289 @@
+<purpose>
+Review executed phase by comparing plan intent against actual code. Combines semantic inspection with git diff presentation. User approves or requests revisions.
+
+**Core principle:** Claude inspects first, then shows findings to user. User decides.
+
+**Output:** Phase approved (advance to next) or fix plans in decimal phases (e.g., phase-01.1/)
+</purpose>
+
+<philosophy>
+
+## Semantic Review, Not Literal Diff
+
+Plans describe intent. Code implements intent. Check whether intent was fulfilled, not whether every word matches.
+
+## Inspect, Then Show
+
+Claude reads the code and compares against the plan first. Then presents findings with the git diff. The user gets a curated view, not a raw dump.
+
+## Fix Plans, Not Inline Fixes
+
+When the user reports issues, create proper PLAN.md files in decimal phases. These get executed through the same execute workflow.
+
+## Deviations Are Neutral
+
+A deviation means code differs from plan. It might be an improvement. The review surfaces it; the user decides.
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+@~/.claude/specdacular/references/validate-task.md
+
+Use extended validation. Also check:
+- `config.json` → `phases.current_status` must be "executed"
+- `config.json` → `phases.phase_start_commit` must exist
+
+**If status is not "executed":**
+```
+Phase {N} is not ready for review (status: {status}).
+
+Run /specd:continue {task-name} to get to the right step.
+```
+End workflow.
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+@~/.claude/specdacular/references/load-context.md
+
+Load all context including the current phase's PLAN.md.
+
+**Read phase plan:**
+```bash
+PHASE_NUM=$(cat .specd/tasks/$TASK_NAME/config.json | grep -o '"current": [0-9]*' | grep -o '[0-9]*')
+PHASE_DIR=".specd/tasks/$TASK_NAME/phases/phase-$(printf '%02d' $PHASE_NUM)"
+cat "$PHASE_DIR/PLAN.md"
+```
+
+**Get phase start commit:**
+```bash
+cat .specd/tasks/$TASK_NAME/config.json | grep phase_start_commit
+```
+
+Continue to inspect_code.
+</step>
+
+<step name="inspect_code">
+Compare plan intent against actual implementation.
+
+**Get git diff:**
+```bash
+git diff {phase_start_commit}..HEAD --stat
+git diff {phase_start_commit}..HEAD --name-status
+```
+
+**For each task in the PLAN.md:**
+
+1. **File check:** Do the files listed in `creates` exist? Do the files in `modifies` still exist?
+
+2. **Intent check:** Read each created/modified file. Does the code achieve what the task described?
+
+3. **Classify:**
+   - ✅ **Match** — Files exist, intent fulfilled
+   - ⚠️ **Deviation** — Works but differs from plan
+   - ❌ **Incomplete** — Missing files or objectives not met
+
+4. **For deviations/incomplete, note:**
+   - What the plan specified
+   - What was actually implemented (or what's missing)
+   - Impact: Low (cosmetic), Medium (behavioral), High (missing functionality)
+
+**Check CHANGELOG.md** for already-logged deviations to avoid duplicates.
+
+Continue to present_findings.
+</step>
+
+<step name="present_findings">
+Show review results to user.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE REVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Task:** {task-name}
+**Phase:** {N} — {phase title}
+
+**Files changed:**
+{git diff --stat output}
+
+**Summary:** {N} ✅ | {N} ⚠️ | {N} ❌
+
+**What was built:**
+{For each task: one-line status with icon}
+```
+
+**If deviations or incomplete items exist:**
+For each:
+```
+───────────────────────────────────────────────────────
+Task {N}: {Title} — {⚠️ | ❌}
+───────────────────────────────────────────────────────
+**Planned:** {what the plan specified}
+**Actual:** {what was implemented or missing}
+**Impact:** {Low | Medium | High}
+```
+
+**If all clean:**
+```
+All tasks match their intended implementation. Phase {N} is clean.
+```
+
+Continue to gather_feedback.
+</step>
+
+<step name="gather_feedback">
+Ask user for their assessment.
+
+**If findings exist (⚠️ or ❌):**
+Use AskUserQuestion:
+- header: "Review"
+- question: "How would you like to handle these findings?"
+- options:
+  - "Looks good" — Accept all, approve phase
+  - "I want to revise" — Describe what needs fixing
+  - "Stop for now" — Come back later
+
+**If clean:**
+Use AskUserQuestion:
+- header: "Review"
+- question: "Phase {N} review is clean. Approve?"
+- options:
+  - "Looks good" — Approve phase
+  - "I have concerns" — Describe issues
+  - "Stop for now" — Come back later
+
+**If "Looks good":**
+Continue to approve_phase.
+
+**If "I want to revise" or "I have concerns":**
+Continue to collect_feedback.
+
+**If "Stop for now":**
+```
+Progress saved. Phase stays in "executed" state.
+Resume review with /specd:continue {task-name}
+```
+End workflow.
+</step>
+
+<step name="collect_feedback">
+Gather specific feedback from user.
+
+```
+Tell me what needs fixing. You can describe:
+- Bugs or incorrect behavior
+- Approach you'd prefer changed
+- Missing functionality
+- Code quality issues
+
+Describe as many issues as you want — I'll create a fix plan for all of them.
+```
+
+Wait for user response. Follow up to understand each issue clearly.
+
+Continue to create_fix_plan.
+</step>
+
+<step name="create_fix_plan">
+Create a fix plan in a decimal phase.
+
+**Determine fix phase number:**
+```bash
+ls -d .specd/tasks/$TASK_NAME/phases/phase-$CURRENT.* 2>/dev/null | sort -V | tail -1
+```
+- If no decimal phases → create `phase-{N}.1/`
+- If `phase-{N}.1/` exists → create `phase-{N}.2/`, etc.
+
+**Create fix phase directory and PLAN.md:**
+```bash
+mkdir -p .specd/tasks/$TASK_NAME/phases/phase-{N.M}/
+```
+
+Write `PLAN.md` using standard plan format:
+- Objective: Address review feedback for Phase {N}
+- Tasks: One per issue reported, with clear fix description and verification
+
+**Update ROADMAP.md:**
+Add fix phase entry after the parent phase.
+
+**Commit:**
+@~/.claude/specdacular/references/commit-docs.md
+- **$FILES:** fix plan directory + ROADMAP.md
+- **$MESSAGE:** `docs({task-name}): create fix plan phase-{N.M}`
+- **$LABEL:** `fix plan`
+
+**Offer execution:**
+Use AskUserQuestion:
+- header: "Fix Plan"
+- question: "Execute the fix plan now?"
+- options:
+  - "Execute" — Run the fix plan
+  - "Stop for now" — Come back later
+
+**If "Execute":**
+Execute fix plan via:
+@~/.claude/specdacular/workflows/execute.md
+
+After fix execution, loop back to the validate step of this review workflow (re-review with updated diff).
+
+**If "Stop for now":**
+```
+Fix plan saved. Resume with /specd:continue {task-name}
+```
+End workflow.
+</step>
+
+<step name="approve_phase">
+Mark phase as completed and advance.
+
+**Update config.json:**
+- Set `phases.current_status` to "completed"
+- Increment `phases.completed`
+- Advance `phases.current` to next phase
+- Reset `phases.phase_start_commit` to null
+- Set new phase status to "pending"
+
+**Update STATE.md:**
+- Mark phase as complete in execution progress
+
+**Add review cycle to STATE.md:**
+```markdown
+| {N} | 1 | {date} | {summary} | {fix plans or "—"} | clean |
+```
+
+**Commit:**
+@~/.claude/specdacular/references/commit-docs.md
+- **$FILES:** config.json + STATE.md
+- **$MESSAGE:** `docs({task-name}): phase {N} approved`
+- **$LABEL:** `phase approved`
+
+**Present:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE {N} COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase {N}: {phase-name} approved.
+{If more phases: "Next: Phase {N+1}: {next-phase-name}"}
+{If all phases done: "All phases complete! Task '{task-name}' is done."}
+```
+
+End workflow (caller handles continuation).
+</step>
+
+</process>
+
+<success_criteria>
+- Plan intent compared against actual code (semantic review)
+- Git diff presented to user
+- Per-task status with icons (✅ ⚠️ ❌)
+- User can approve, revise, or stop
+- Fix plans created in decimal phases when needed
+- Fix plans execute through same execute workflow
+- Review loops after fix execution
+- Phase advances only after explicit user approval
+</success_criteria>

package/specdacular/workflows/status.md

@@ -1,4 +1,4 @@
-# Workflow: Feature Status Dashboard
+# Workflow: Task Status Dashboard
 
 ## Input
 
@@ -8,7 +8,7 @@
 
 ### 1. Parse arguments
 
-Check if `$ARGUMENTS` contains `--all`. If so, completed features will be shown in a separate section.
+Check if `$ARGUMENTS` contains `--all`. If so, completed tasks will be shown in a separate section.
 
 ### 2. Detect orchestrator mode
 
@@ -29,24 +29,24 @@ cat .specd/config.json 2>/dev/null
 
 ### 3. Check for features directory
 
-Use Glob to check if `.specd/features/*/config.json` matches anything.
+Use Glob to check if `.specd/tasks/*/config.json` matches anything.
 
 **If mode = orchestrator and no root features:**
-Also check sub-project features — scan each project path for `{project-path}/.specd/features/*/config.json`. If features found in sub-projects, continue (there's something to show).
+Also check sub-project features — scan each project path for `{project-path}/.specd/tasks/*/config.json`. If features found in sub-projects, continue (there's something to show).
 
 **If no features found anywhere:** output the following and stop:
 
 ```
-No features found. Start one with `/specd:feature:new [name]`.
+No tasks found. Start one with `/specd:new [name]`.
 ```
 
 ### 4. Gather feature data
 
 #### If mode = project (single-project, unchanged):
 
-For each feature directory in `.specd/features/`:
+For each feature directory in `.specd/tasks/`:
 
-1. **Read `config.json`** — extract: `feature_name`, `created`, `stage`, `phases_count`, `plans_count`
+1. **Read `config.json`** — extract: `task_name`, `created`, `stage`, `phases_count`, `plans_count`
 2. **Read `STATE.md`** — extract:
    - **Authoritative stage**: Look for `**Stage:** <value>` in the Current Position section. This overrides `config.json` stage. A feature is complete when stage is `complete`.
    - **Plan completion**: From the `Plan Status` table, count rows with Status = `Complete` vs total rows. Format as `completed/total` (e.g. `5/8`). If no Plan Status table or no rows, use `—`.
@@ -56,15 +56,15 @@ For each feature directory in `.specd/features/`:
 
 **Step 4a: Gather root features (same as single-project).**
 
-For each feature directory in `.specd/features/`, extract feature_name, created, stage, plans, next_action using the same logic as single-project mode.
+For each feature directory in `.specd/tasks/`, extract task_name, created, stage, plans, next_action using the same logic as single-project mode.
 
 **Step 4b: For each root feature, check for sub-project features.**
 
 Read each root feature's `config.json`. If it has a `projects` array (orchestrator feature):
 
 For each project entry `{name, path}` in the feature's `projects` array:
-1. Check if `{path}/.specd/features/{feature_name}/` exists
-2. If yes, read `{path}/.specd/features/{feature_name}/config.json` and `{path}/.specd/features/{feature_name}/STATE.md`
+1. Check if `{path}/.specd/tasks/{task_name}/` exists
+2. If yes, read `{path}/.specd/tasks/{task_name}/config.json` and `{path}/.specd/tasks/{task_name}/STATE.md`
 3. Extract the same fields: stage (from STATE.md `**Stage:**`), plan completion, next action
 4. Store as a sub-feature of the parent orchestrator feature, tagged with the project name
 
@@ -73,7 +73,7 @@ Mark this root feature as an "orchestrator feature" (has sub-project children).
 **Step 4c: Scan for standalone sub-project features.**
 
 For each project in the repo-level `.specd/config.json` `projects` array:
-1. Use Glob to find `{project-path}/.specd/features/*/config.json`
+1. Use Glob to find `{project-path}/.specd/tasks/*/config.json`
 2. For each feature found, check if it was already captured as a sub-feature of an orchestrator feature in step 4b
 3. If NOT already captured, gather its data (same extraction logic) and store as a standalone feature, grouped by project name/path
 
@@ -100,7 +100,7 @@ Sort active features by stage priority (highest first), then by created date (ol
 **Output header:**
 
 ```
-# Feature Status
+# Task Status
 
 _{total} features, {in_progress} in progress_
 ```
@@ -116,13 +116,13 @@ _{total} features, {in_progress} in progress_
 - `Plans` shows the completed/total count from Plan Status table, or `—` if pre-planning
 - `Next Action` is the extracted recommendation from STATE.md Next Steps
 
-**If `--all` flag is NOT set and there are completed features:**
+**If `--all` flag is NOT set and there are completed tasks:**
 
 ```
-Run `/specd:status --all` to include completed features.
+Run `/specd:status --all` to include completed tasks.
 ```
 
-**If `--all` flag IS set and there are completed features, add:**
+**If `--all` flag IS set and there are completed tasks, add:**
 
 ```
 ### Completed
@@ -141,7 +141,7 @@ Where `Completed` date comes from the `**Last Updated:**` field in STATE.md.
 **Output header:**
 
 ```
-# Feature Status
+# Task Status
 
 _{total} features, {in_progress} in progress — orchestrator mode_
 ```
@@ -190,7 +190,7 @@ Only show active standalone features (not complete/abandoned, unless `--all`).
 **If `--all` flag is NOT set and there are completed/abandoned features (root or sub-project):**
 
 ```
-Run `/specd:status --all` to include completed features.
+Run `/specd:status --all` to include completed tasks.
 ```
 
 **If `--all` flag IS set and there are completed/abandoned features, add:**

package/commands/specd/blueprint.md

@@ -1,64 +0,0 @@
----
-name: specd:blueprint
-description: Generate visual blueprint for a feature
-argument-hint: "[feature-name] [wireframes|diagrams]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<objective>
-Generate a visual HTML blueprint for exploring feature artifacts.
-
-**Base command:** `/specd:blueprint {feature}`
-- Creates `.specd/features/{feature}/blueprint/index.html`
-- Shows Overview, Decisions, Context, Plans tabs
-- Opens in browser
-
-**Subcommands:**
-- `/specd:blueprint {feature} wireframes` — Add wireframes tab
-- `/specd:blueprint {feature} diagrams` — Add diagrams tab with Mermaid
-
-**Output:** Self-contained HTML file that opens in browser. Regenerate to update.
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/blueprint.md
-</execution_context>
-
-<context>
-Feature name: First argument ($ARGUMENTS before space)
-Subcommand: Second argument (wireframes, diagrams, or empty)
-
-**Load feature context:**
-@.specd/features/{name}/FEATURE.md
-@.specd/features/{name}/CONTEXT.md
-@.specd/features/{name}/DECISIONS.md
-@.specd/features/{name}/plans/ (if exists)
-
-**Load codebase context (if available):**
-@.specd/codebase/PATTERNS.md
-</context>
-
-<process>
-1. **Parse Arguments** — Extract feature name and optional subcommand
-2. **Validate** — Check feature exists with required files
-3. **Route Subcommand:**
-   - No subcommand → Generate base blueprint
-   - `wireframes` → Generate/update with wireframes tab
-   - `diagrams` → Generate/update with diagrams tab
-4. **Generate HTML** — Read files, parse content, embed in template
-5. **Open Browser** — Run `open` command to display
-</process>
-
-<success_criteria>
-- [ ] Feature validated (exists, has FEATURE.md, CONTEXT.md, DECISIONS.md)
-- [ ] HTML generated at `.specd/features/{name}/blueprint/index.html`
-- [ ] All content properly embedded (decisions, context, plans if exist)
-- [ ] Browser opens with the blueprint
-- [ ] Wireframes/Diagrams tabs enabled if generated
-</success_criteria>

package/commands/specd/feature/continue.md

@@ -1,84 +0,0 @@
----
-name: specd:feature:continue
-description: Continue feature lifecycle — picks up where you left off
-argument-hint: "[feature-name]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - AskUserQuestion
----
-
-<objective>
-Smart state machine that reads current feature state and drives the entire lifecycle. One command from discussion through phase execution.
-
-**How it works:**
-1. Select feature (from argument or picker)
-2. Read current state (STATE.md, config.json, CONTEXT.md, ROADMAP.md)
-3. Show status summary
-4. Offer the natural next step
-5. Execute it (delegating to existing workflows)
-6. Loop back — offer the next step or stop
-
-**Covers the full lifecycle:**
-- Discussion (gray areas, decisions)
-- Research (parallel agents for patterns/pitfalls)
-- Planning (roadmap with phases)
-- Phase preparation (phase-specific discussion + research)
-- Phase planning (detailed PLAN.md files)
-- Phase execution (with progress tracking)
-- Phase review (review executed work, user-guided)
-
-**No need to remember individual commands.** This one command figures out what to do.
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/continue-feature.md
-</execution_context>
-
-<context>
-Feature name: $ARGUMENTS
-
-**Scans for features:**
-@.specd/features/*/config.json
-
-**Loads feature context (once selected):**
-@.specd/features/{name}/config.json
-@.specd/features/{name}/STATE.md
-@.specd/features/{name}/CONTEXT.md
-@.specd/features/{name}/FEATURE.md
-@.specd/features/{name}/ROADMAP.md (if exists)
-@.specd/features/{name}/RESEARCH.md (if exists)
-
-**Delegates to existing workflows:**
-@~/.claude/specdacular/workflows/discuss-feature.md
-@~/.claude/specdacular/workflows/research-feature.md
-@~/.claude/specdacular/workflows/plan-feature.md
-@~/.claude/specdacular/workflows/prepare-phase.md
-@~/.claude/specdacular/workflows/plan-phase.md
-@~/.claude/specdacular/workflows/execute-plan.md
-@~/.claude/specdacular/workflows/review-feature.md
-</context>
-
-<process>
-1. **Select Feature** — From argument or scan .specd/features/*/config.json
-2. **Read State** — Load config.json, STATE.md, CONTEXT.md, ROADMAP.md
-3. **Show Status** — Concise summary of where things stand
-4. **Determine Next** — Based on stage + phase status
-5. **Offer Choice** — Next step + alternatives + "stop for now"
-6. **Execute** — Delegate to appropriate workflow
-7. **Loop** — Back to step 2 after each action
-</process>
-
-<success_criteria>
-- [ ] Feature selected (from argument or picker)
-- [ ] Current state accurately displayed
-- [ ] Correct next action offered
-- [ ] User can stop at any natural boundary
-- [ ] Delegated to correct workflow for execution
-- [ ] Looped back after completion
-</success_criteria>

package/commands/specd/feature/new.md

@@ -1,67 +0,0 @@
----
-name: specd:feature:new
-description: Initialize a new feature and start the first discussion
-argument-hint: "[feature-name]"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - AskUserQuestion
----
-
-<objective>
-Initialize a feature folder and start the first discussion. Creates structure, asks initial questions about what's being built, and writes technical requirements. After initialization, offers to continue discussing or stop.
-
-**Creates:**
-- `.specd/features/{name}/FEATURE.md` — Technical requirements from discussion
-- `.specd/features/{name}/CONTEXT.md` — Discussion context (accumulates over time)
-- `.specd/features/{name}/DECISIONS.md` — Memory file for decisions with rationale
-- `.specd/features/{name}/STATE.md` — Progress tracking
-- `.specd/features/{name}/config.json` — Feature configuration
-
-**This is the entry point.** After this, continue with `/specd:feature:continue` to drive the entire lifecycle.
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/new-feature.md
-</execution_context>
-
-<context>
-Feature 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:map-codebase`
-
-**Referenced docs (when available):**
-- `ARCHITECTURE.md` or `MAP.md` — System structure
-- `CONVENTIONS.md` or `PATTERNS.md` — Code patterns
-- `STRUCTURE.md` — Directory layout
-</context>
-
-<process>
-1. **Validate** — Check name, check if exists
-2. **Codebase Context** — Look for codebase docs (offer map-codebase if missing)
-3. **First Discussion** — "What are you building?"
-4. **Follow the Thread** — Collaborative, not interrogative
-5. **Probe Until Clear** — What creates, what integrates with, constraints
-6. **Write FEATURE.md** — Technical requirements
-7. **Write CONTEXT.md** — Initial discussion state
-8. **Initialize DECISIONS.md** — With any decisions made so far
-9. **Initialize STATE.md** — Feature created, ready for more discussion
-10. **Commit and Present Options**
-</process>
-
-<success_criteria>
-- [ ] Feature folder created at `.specd/features/{name}/`
-- [ ] FEATURE.md captures technical requirements
-- [ ] CONTEXT.md initialized with discussion context
-- [ ] DECISIONS.md initialized (possibly with initial decisions)
-- [ ] STATE.md tracks current position
-- [ ] config.json created
-- [ ] Committed to git
-- [ ] User offered to continue discussing or stop with `/specd:feature:continue`
-</success_criteria>

package/commands/specd/feature/toolbox.md

@@ -1,49 +0,0 @@
----
-name: specd:feature:toolbox
-description: Advanced feature operations — discuss, research, plan, review, insert
-argument-hint: "[feature-name]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - AskUserQuestion
----
-
-<objective>
-Menu of advanced feature operations. Presents options and dispatches to the appropriate workflow.
-
-**Operations:**
-- Discuss — Explore open questions (feature or phase level)
-- Research — Spawn parallel research agents (feature or phase level)
-- Plan — Create implementation plans (feature or phase level)
-- Review — Review executed work, report issues, generate fix plans
-- Insert phase — Add a new phase with decimal numbering
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/toolbox.md
-</execution_context>
-
-<context>
-Feature name: $ARGUMENTS
-
-**Delegates to workflows:**
-@~/.claude/specdacular/workflows/discuss-feature.md
-@~/.claude/specdacular/workflows/research-feature.md
-@~/.claude/specdacular/workflows/plan-feature.md
-@~/.claude/specdacular/workflows/review-feature.md
-@~/.claude/specdacular/workflows/insert-phase.md
-@~/.claude/specdacular/workflows/prepare-phase.md
-@~/.claude/specdacular/workflows/plan-phase.md
-</context>
-
-<success_criteria>
-- [ ] Feature selected (from argument or picker)
-- [ ] Menu presented with all 5 operations
-- [ ] Selected operation executed via correct workflow
-- [ ] Scope selection works for discuss/research/plan
-</success_criteria>