specdacular 0.7.0 → 0.7.1

package/specdacular/workflows/insert-phase.md

@@ -3,7 +3,7 @@ Insert a new phase after an existing one using decimal numbering (e.g., Phase 03
 
 **Key principles:**
 - Decimal numbering preserves existing phase sequence
-- Never renumber existing phases — that's what renumber-phases is for
+- Never renumber existing phases — decimal numbering eliminates renumbering
 - Create directory structure but don't create plans — user decides how to plan
 - Mark inserted phases with `(INSERTED)` in ROADMAP.md
 
@@ -12,29 +12,47 @@ Insert a new phase after an existing one using decimal numbering (e.g., Phase 03
 
 <process>
 
-<step name="parse_arguments">
-Parse the command arguments:
-- First argument: feature name
-- Second argument: integer phase number to insert after
-- Remaining arguments: phase description
+<step name="select_feature">
+@~/.claude/specdacular/references/select-feature.md
 
-Example: `/specd:phase:insert visual-blueprint-tool 3 Architecture Update`
-→ feature = "visual-blueprint-tool"
-→ after = 3
-→ description = "Architecture Update"
+Continue to select_target.
+</step>
 
-**Validation:**
-- All three parts are required (feature, phase number, description)
-- Phase number must be a positive integer
-- Cannot insert before Phase 1 (no Phase 0.x)
+<step name="select_target">
+Determine where to insert and what the phase is about.
+
+**If arguments include phase number and description (e.g., direct invocation):**
+Parse from arguments:
+- Second token: integer phase number to insert after
+- Remaining tokens: phase description
+
+Continue to validate.
 
-**If arguments missing:**
+**If arguments are just feature name (e.g., from toolbox dispatch):**
+
+Read ROADMAP.md and show current phases:
+```
+Current phases:
+{List each phase with number and name from ROADMAP.md}
 ```
-ERROR: Missing arguments.
 
-Usage: /specd:phase:insert [feature-name] [after-phase] [description...]
-Example: /specd:phase:insert visual-blueprint-tool 3 Architecture Update
+Use AskUserQuestion:
+- header: "Insert After"
+- question: "Insert new phase after which existing phase?"
+- options: List each phase as an option (e.g., "Phase 1: Rename + Toolbox", "Phase 2: Review + State Machine", etc.)
+
+After selection, ask:
+```
+What's this new phase about? Give a brief name and goal.
 ```
+
+Wait for response.
+
+**Validation:**
+- Phase number must be a positive integer (or existing decimal phase)
+- Cannot insert before Phase 1 (no Phase 0.x)
+
+Continue to validate.
 </step>
 
 <step name="validate">
@@ -161,7 +179,7 @@ Insert this line after `Phase {after_phase}` checkbox and before `Phase {after_p
 Update config.json to reflect the new phase count.
 
 1. Read config.json
-2. Increment `phases_count` by 1
+2. Increment `phases.total` by 1
 3. Write updated config.json
 </step>
 
@@ -181,18 +199,24 @@ Present completion summary:
 **Updated:**
 - ROADMAP.md — New phase section added
 - STATE.md — Evolution note + unchecked checkbox
-- config.json — phases_count incremented
+- config.json — phases.total incremented
 
 ───────────────────────────────────────────────────────
 
 ## Next Steps
 
-- `/specd:phase:prepare {feature} {new_phase}` — Discuss + optionally research the new phase
-- `/specd:phase:plan {feature} {new_phase}` — Create detailed plans for the phase
-- `/specd:phase:execute {feature}` — Execute when plans exist
-- `/specd:phase:renumber {feature}` — Clean up to integer sequence when ready
+`/specd:feature:continue {feature}` — Picks up the new phase automatically
+`/specd:feature:toolbox {feature}` — Prepare, plan, or discuss the new phase
 ```
 
+**Commit changes:**
+
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/features/{feature}/ROADMAP.md .specd/features/{feature}/STATE.md .specd/features/{feature}/config.json .specd/features/{feature}/plans/phase-{new_phase}/`
+- **$MESSAGE:** `docs({feature}): insert phase {new_phase} — {description}`
+- **$LABEL:** `phase insertion`
+
 End workflow.
 </step>
 
@@ -200,7 +224,7 @@ End workflow.
 
 <anti_patterns>
 - Don't insert before Phase 1 (Phase 0.x makes no sense)
-- Don't renumber existing phases (that's /specd:phase:renumber)
+- Don't renumber existing phases — decimal numbering eliminates renumbering
 - Don't modify the target phase content
 - Don't create plans yet — user decides how to plan (discuss, research, or manual)
 - Don't commit changes — user decides when to commit
@@ -217,6 +241,6 @@ Phase insertion is complete when:
 - [ ] ROADMAP.md updated with new phase entry (includes `(INSERTED)` marker)
 - [ ] Phase inserted in correct position (after target phase, before next integer phase)
 - [ ] STATE.md updated with roadmap evolution note and unchecked checkbox
-- [ ] config.json `phases_count` incremented
+- [ ] config.json `phases.total` incremented
 - [ ] User informed of next steps
 </success_criteria>

package/specdacular/workflows/map-codebase.md

@@ -358,37 +358,11 @@ Continue to commit_codebase_map.
 <step name="commit_codebase_map">
 Commit the codebase map.
 
-**First, check auto-commit setting. Run this command:**
+@~/.claude/specdacular/references/commit-docs.md
 
-```bash
-cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
-```
-
-Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
-
-```
-Auto-commit disabled for docs — changes not committed.
-Modified files: .specd/codebase/*.md
-```
-
-Then skip ahead to completion.
-
-**Only if `auto_commit_docs` is `true` or not set (default), run:**
-
-```bash
-git add .specd/codebase/*.md .specd/config.json
-git commit -m "$(cat <<'EOF'
-docs: map codebase for Claude
-
-- MAP.md - Navigation: modules, functions, integrations
-- PATTERNS.md - Code examples: services, errors, testing
-- STRUCTURE.md - Organization: where to put new code
-- CONCERNS.md - Warnings: gotchas, anti-patterns, debt
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-EOF
-)"
-```
+- **$FILES:** `.specd/codebase/*.md .specd/config.json`
+- **$MESSAGE:** `docs: map codebase for Claude` with list of documents created
+- **$LABEL:** `codebase map`
 
 Continue to completion.
 </step>

package/specdacular/workflows/new-feature.md

@@ -453,7 +453,7 @@ Use AskUserQuestion:
 - 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}
+  - "Stop for now" — Come back with /specd:feature:continue {feature-name}
 
 **If Keep discussing:**
 Execute the discuss-feature workflow logic:
@@ -468,11 +468,11 @@ Use AskUserQuestion:
 - 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}
+  - "Stop for now" — Come back with /specd:feature:continue {feature-name}
 
 **If Continue:**
-Hand off to next-feature workflow:
-@~/.claude/specdacular/workflows/next-feature.md
+Hand off to continue-feature workflow:
+@~/.claude/specdacular/workflows/continue-feature.md
 
 Start from the read_state step with the current feature.
 
@@ -482,7 +482,7 @@ Start from the read_state step with the current feature.
 
 Progress saved. Pick up where you left off anytime:
 
-/specd:feature:next {feature-name}
+/specd:feature:continue {feature-name}
 ```
 
 End workflow.
@@ -641,35 +641,11 @@ Continue to commit.
 <step name="commit">
 Commit the feature initialization.
 
-**First, check auto-commit setting. Run this command:**
+@~/.claude/specdacular/references/commit-docs.md
 
-```bash
-cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
-```
-
-Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
-
-```
-Auto-commit disabled for docs — changes not committed.
-Modified files: .specd/features/{feature-name}/
-```
-
-Then skip ahead to completion.
-
-**Only if `auto_commit_docs` is `true` or not set (default), run:**
-
-```bash
-git add .specd/features/{feature-name}/
-git commit -m "docs({feature-name}): initialize feature
-
-Creates feature structure with:
-- FEATURE.md: Technical requirements
-- CONTEXT.md: Discussion context
-- DECISIONS.md: Decision log ({N} decisions)
-- CHANGELOG.md: Implementation log (empty)
-- STATE.md: Progress tracking
-- config.json: Configuration"
-```
+- **$FILES:** `.specd/features/{feature-name}/`
+- **$MESSAGE:** `docs({feature-name}): initialize feature` with list of created files
+- **$LABEL:** `feature initialization`
 
 Continue to completion.
 </step>
@@ -717,7 +693,7 @@ Use AskUserQuestion:
 - 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}
+  - "Stop for now" — Come back with /specd:feature:continue {feature-name}
 
 **If Keep discussing:**
 Execute the discuss-feature workflow logic:
@@ -732,11 +708,11 @@ Use AskUserQuestion:
 - 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}
+  - "Stop for now" — Come back with /specd:feature:continue {feature-name}
 
 **If Continue:**
-Hand off to the next-feature workflow logic to determine next action:
-@~/.claude/specdacular/workflows/next-feature.md
+Hand off to the continue-feature workflow logic to determine next action:
+@~/.claude/specdacular/workflows/continue-feature.md
 
 Start from the read_state step with the current feature.
 
@@ -746,7 +722,7 @@ Start from the read_state step with the current feature.
 
 Progress saved. Pick up where you left off anytime:
 
-/specd:feature:next {feature-name}
+/specd:feature:continue {feature-name}
 ```
 
 End workflow.

package/specdacular/workflows/plan-feature.md

@@ -443,7 +443,7 @@ No cycles detected.
 
 The orchestrator will guide you through phases respecting cross-project dependencies.
 
-/specd:feature:next {feature-name} — Start executing phases
+/specd:feature:continue {feature-name} — Start executing phases
 ```
 
 End workflow.
@@ -609,34 +609,11 @@ Continue to commit.
 <step name="commit">
 Commit the roadmap.
 
-**First, check auto-commit setting. Run this command:**
+@~/.claude/specdacular/references/commit-docs.md
 
-```bash
-cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
-```
-
-Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
-
-```
-Auto-commit disabled for docs — changes not committed.
-Modified files: .specd/features/{feature-name}/ROADMAP.md, plans/, STATE.md, config.json
-```
-
-Then skip ahead to completion.
-
-**Only if `auto_commit_docs` is `true` or not set (default), run:**
-
-```bash
-git add .specd/features/{feature-name}/ROADMAP.md .specd/features/{feature-name}/plans/ .specd/features/{feature-name}/STATE.md .specd/features/{feature-name}/config.json
-git commit -m "docs({feature-name}): create roadmap
-
-Phases: {N}
-
-Phase structure:
-- Phase 1: {name}
-- Phase 2: {name}
-..."
-```
+- **$FILES:** `.specd/features/{feature-name}/ROADMAP.md .specd/features/{feature-name}/plans/ .specd/features/{feature-name}/STATE.md .specd/features/{feature-name}/config.json`
+- **$MESSAGE:** `docs({feature-name}): create roadmap` with phase count and structure
+- **$LABEL:** `roadmap creation`
 
 Continue to completion.
 </step>
@@ -709,6 +686,6 @@ End workflow.
 - Topological sort validates no cycles (DEC-009)
 - DEPENDENCIES.md written with table + Mermaid DAG
 - All roadmaps, state, and config committed
-- User knows to use /specd:feature:next for execution
+- User knows to use /specd:feature:continue for execution
 
 </success_criteria>

package/specdacular/workflows/plan-phase.md

@@ -301,36 +301,11 @@ Continue to commit.
 <step name="commit">
 Commit the plans.
 
-**First, check auto-commit setting. Run this command:**
+@~/.claude/specdacular/references/commit-docs.md
 
-```bash
-cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
-```
-
-Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
-
-```
-Auto-commit disabled for docs — changes not committed.
-Modified files: .specd/features/{feature-name}/plans/phase-{NN}/*-PLAN.md, ROADMAP.md, STATE.md
-```
-
-Then skip ahead to completion.
-
-**Only if `auto_commit_docs` is `true` or not set (default), run:**
-
-```bash
-git add .specd/features/{feature-name}/plans/phase-{NN}/*-PLAN.md
-git add .specd/features/{feature-name}/ROADMAP.md
-git add .specd/features/{feature-name}/STATE.md
-git commit -m "docs({feature-name}): plan phase {N} - {phase title}
-
-Plans: {count}
-Tasks: {total tasks across plans}
-
-Plan structure:
-- {01-PLAN.md}: {summary}
-- {02-PLAN.md}: {summary}"
-```
+- **$FILES:** `.specd/features/{feature-name}/plans/phase-{NN}/*-PLAN.md .specd/features/{feature-name}/ROADMAP.md .specd/features/{feature-name}/STATE.md`
+- **$MESSAGE:** `docs({feature-name}): plan phase {N} - {phase title}` with plan count, task count, and plan structure
+- **$LABEL:** `phase plans`
 
 Continue to completion.
 </step>

package/specdacular/workflows/prepare-phase.md

@@ -676,42 +676,11 @@ Continue to commit.
 <step name="commit">
 Commit the phase preparation.
 
-**First, check auto-commit setting. Run this command:**
+@~/.claude/specdacular/references/commit-docs.md
 
-```bash
-cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
-```
-
-Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
-
-```
-Auto-commit disabled for docs — changes not committed.
-Modified files: .specd/features/{feature}/plans/phase-{NN}/CONTEXT.md, RESEARCH.md (if created), DECISIONS.md
-```
-
-Then skip ahead to completion.
-
-**Only if `auto_commit_docs` is `true` or not set (default), run:**
-
-```bash
-# Add phase CONTEXT.md
-git add ".specd/features/{feature}/plans/phase-{NN}/CONTEXT.md"
-
-# Add phase RESEARCH.md if created
-git add ".specd/features/{feature}/plans/phase-{NN}/RESEARCH.md" 2>/dev/null
-
-# Add updated DECISIONS.md if modified
-git add ".specd/features/{feature}/DECISIONS.md"
-
-git commit -m "docs({feature}): prepare phase {N} - {phase title}
-
-Resolved:
-- {Area 1}
-- {Area 2}
-
-{If research:}Research: codebase, patterns, pitfalls
-New decisions: {count}"
-```
+- **$FILES:** `.specd/features/{feature}/plans/phase-{NN}/CONTEXT.md .specd/features/{feature}/plans/phase-{NN}/RESEARCH.md .specd/features/{feature}/DECISIONS.md` (skip RESEARCH.md if not created)
+- **$MESSAGE:** `docs({feature}): prepare phase {N} - {phase title}` with resolved areas and decision count
+- **$LABEL:** `phase preparation`
 
 Continue to completion.
 </step>

package/specdacular/workflows/research-phase.md

@@ -515,37 +515,11 @@ Continue to commit.
 <step name="commit">
 Commit the phase research.
 
-**First, check auto-commit setting. Run this command:**
+@~/.claude/specdacular/references/commit-docs.md
 
-```bash
-cat .specd/config.json 2>/dev/null || echo '{"auto_commit_docs": true}'
-```
-
-Read the output. If `auto_commit_docs` is `false`, do NOT run the git commands below. Instead print:
-
-```
-Auto-commit disabled for docs — changes not committed.
-Modified files: .specd/features/{feature}/plans/phase-{NN}/RESEARCH.md, DECISIONS.md
-```
-
-Then skip ahead to completion.
-
-**Only if `auto_commit_docs` is `true` or not set (default), run:**
-
-```bash
-git add ".specd/features/{feature}/plans/phase-{NN}/RESEARCH.md"
-git add ".specd/features/{feature}/DECISIONS.md"
-
-git commit -m "docs({feature}): research phase {N} - {phase title}
-
-Research dimensions:
-- Codebase integration
-- {Phase type} patterns
-- {Phase type} pitfalls
-
-Key findings:
-- {one-liner from summary}"
-```
+- **$FILES:** `.specd/features/{feature}/plans/phase-{NN}/RESEARCH.md .specd/features/{feature}/DECISIONS.md`
+- **$MESSAGE:** `docs({feature}): research phase {N} - {phase title}` with research dimensions and key findings
+- **$LABEL:** `phase research`
 
 Continue to completion.
 </step>