specdacular 0.2.5 → 0.5.1

package/specdacular/workflows/blueprint.md

@@ -0,0 +1,372 @@
+<purpose>
+Generate a visual HTML blueprint for exploring Specdacular feature artifacts.
+
+Reads FEATURE.md, CONTEXT.md, DECISIONS.md, and plans/ to create a browsable
+static HTML file with sidebar navigation and accordion decision viewer.
+
+**Output:** `.specd/features/{name}/blueprint/index.html`
+</purpose>
+
+<philosophy>
+
+## Self-Contained Output
+
+The generated HTML must work when opened directly in a browser (file:// protocol).
+All CSS and JS is inlined. Only external dependency is Mermaid.js CDN.
+
+## Parse Defensively
+
+Markdown files may have missing fields, multi-line values, or edge cases.
+Always provide defaults and handle gracefully.
+
+## HTML-Escape Everything
+
+All content from markdown files must be HTML-escaped before embedding
+to prevent XSS and layout breakage.
+
+</philosophy>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments.
+
+**Input:** `$ARGUMENTS` (e.g., "my-feature wireframes")
+
+**Extract:**
+- Feature name: First word
+- Subcommand: Second word (optional) — "wireframes", "diagrams", or empty
+
+```bash
+# Parse arguments
+FEATURE_NAME=$(echo "$ARGUMENTS" | awk '{print $1}')
+SUBCOMMAND=$(echo "$ARGUMENTS" | awk '{print $2}')
+
+echo "Feature: $FEATURE_NAME"
+echo "Subcommand: $SUBCOMMAND"
+```
+
+**If no feature name:**
+```
+Please provide a feature name: /specd:blueprint {feature-name}
+```
+
+Continue to validate.
+</step>
+
+<step name="validate">
+Check feature exists and has required files.
+
+```bash
+# Check feature directory exists
+[ -d ".specd/features/$FEATURE_NAME" ] || { echo "not found"; exit 1; }
+
+# Check required files
+[ -f ".specd/features/$FEATURE_NAME/FEATURE.md" ] || { echo "missing FEATURE.md"; exit 1; }
+[ -f ".specd/features/$FEATURE_NAME/CONTEXT.md" ] || { echo "missing CONTEXT.md"; exit 1; }
+[ -f ".specd/features/$FEATURE_NAME/DECISIONS.md" ] || { echo "missing DECISIONS.md"; exit 1; }
+
+# Check optional files
+[ -d ".specd/features/$FEATURE_NAME/plans" ] && echo "has_plans"
+[ -f ".specd/features/$FEATURE_NAME/blueprint/wireframes.html" ] && echo "has_wireframes"
+[ -f ".specd/features/$FEATURE_NAME/blueprint/diagrams.html" ] && echo "has_diagrams"
+```
+
+**If feature not found:**
+```
+Feature '{name}' not found.
+
+Run /specd:feature:new {name} to create it first.
+```
+
+Continue to load_context.
+</step>
+
+<step name="load_context">
+Read all feature files.
+
+**Read with Read tool:**
+- `.specd/features/{name}/FEATURE.md`
+- `.specd/features/{name}/CONTEXT.md`
+- `.specd/features/{name}/DECISIONS.md`
+- `.specd/features/{name}/STATE.md` (for stats)
+- `.specd/features/{name}/config.json` (for counts)
+
+**If plans/ exists:**
+- List all plan files: `.specd/features/{name}/plans/phase-*/`
+- Read ROADMAP.md if exists
+
+Continue to parse_decisions.
+</step>
+
+<step name="parse_decisions">
+Parse DECISIONS.md to extract decision data.
+
+**Parsing strategy:**
+1. Split content on `### DEC-` to find decision blocks
+2. For each block:
+   - Extract ID from heading: `### DEC-XXX: Title`
+   - Parse `**Date:**` line for date
+   - Parse `**Phase:**` line for phase number (default: 0 if missing)
+   - Parse `**Status:**` line for status
+   - Parse `**Context:**` for context (may be multi-line)
+   - Parse `**Decision:**` for decision text
+   - Parse `**Rationale:**` for bullet points
+   - Parse `**Implications:**` for bullet points
+
+**Output format (for each decision):**
+```
+{
+  id: "DEC-001",
+  title: "Decision title",
+  date: "2026-02-04",
+  phase: 0,
+  status: "Active",
+  context: "Context text...",
+  decision: "Decision text...",
+  rationale: ["Reason 1", "Reason 2"],
+  implications: ["Implication 1", "Implication 2"]
+}
+```
+
+**Edge cases:**
+- Missing Phase field → default to 0 (pre-planning)
+- Phase: 0 → label as "Pre-planning"
+- Missing fields → use empty string or "Unknown"
+- Multi-line values → collect until next `**Field:**`
+- Code blocks → skip parsing inside triple backticks
+
+**Collect unique phases** from all decisions (sorted numerically) for phase tab generation.
+
+Continue to parse_context.
+</step>
+
+<step name="parse_context">
+Parse CONTEXT.md to extract resolved questions.
+
+**Parsing strategy:**
+1. Find `## Resolved Questions` section
+2. Split on `### ` to find question blocks
+3. For each question:
+   - Extract title from heading
+   - Parse `**Question:**` for the question
+   - Parse `**Resolution:**` for the answer
+   - Parse `**Details:**` for bullet points
+   - Parse `**Related Decisions:**` for decision references (e.g., "DEC-001")
+
+**Associate with phase:**
+- Check `**Related Decisions:** DEC-XXX` field
+- Look up the phase of the referenced decision (from parsed decisions)
+- If no related decision, use phase 0
+
+**Output format:**
+```
+{
+  title: "Question title",
+  question: "What was unclear?",
+  resolution: "The answer",
+  details: ["Detail 1", "Detail 2"],
+  relatedDecisions: ["DEC-001"],
+  phase: 0
+}
+```
+
+Continue to parse_feature.
+</step>
+
+<step name="parse_feature">
+Parse FEATURE.md to extract overview and stats.
+
+**Extract:**
+- `## What This Is` section → feature description
+- Count items in `### Must Create` → files to create count
+- `## Success Criteria` items → for progress indicators
+
+**From config.json:**
+- `discussion_sessions` count
+- `decisions_count`
+
+**From plans/:**
+- Count phase directories
+- Count plan files
+
+Continue to generate_html.
+</step>
+
+<step name="generate_html">
+Generate the HTML by filling in the template.
+
+**Read templates:**
+- `~/.claude/specdacular/templates/blueprint/index.html`
+- `~/.claude/specdacular/templates/blueprint/styles.css`
+- `~/.claude/specdacular/templates/blueprint/scripts.js`
+
+**Replace placeholders:**
+- `{feature-name}` → Feature name
+- `{date}` → Current date (YYYY-MM-DD)
+- `{feature-description}` → From FEATURE.md "What This Is"
+- `{decisions-count}` → Number of decisions
+- `{sessions-count}` → Number of discussion sessions
+- `{plans-count}` → Number of plans
+- `{styles}` → Contents of styles.css
+- `{scripts}` → Contents of scripts.js
+
+**Generate phase tabs HTML:**
+Collect unique phases from decisions (sorted numerically).
+For each section (Decisions, Context), generate:
+
+```html
+<button class="phase-tab all-tab active" data-phase="all">All</button>
+<button class="phase-tab" data-phase="0">Pre-planning</button>
+<button class="phase-tab" data-phase="1">Phase 1</button>
+<button class="phase-tab" data-phase="2">Phase 2</button>
+<!-- ... for each phase found -->
+```
+
+**Replace placeholders:**
+- `{decisions-phase-tabs}` → Generated phase tabs for decisions
+- `{context-phase-tabs}` → Generated phase tabs for context
+- `{plans-phase-tabs}` → Generated phase tabs for plans (no "All" tab needed, use phase numbers only)
+
+**Generate decisions HTML:**
+Group decisions by phase, wrap each group in a phase-content div:
+```html
+<div class="phase-content active" data-phase="0">
+  <!-- Pre-planning decisions -->
+  <details class="decision-item">
+    <summary class="decision-header">
+      <span class="decision-id">{id}</span>
+      <span class="decision-title">{title}</span>
+      <span class="decision-status status-{status-lower}">{status}</span>
+      <span class="decision-date">{date}</span>
+    </summary>
+    <div class="decision-content">
+      <p><strong>Context:</strong> {context}</p>
+      <p><strong>Decision:</strong> {decision}</p>
+      <p><strong>Rationale:</strong></p>
+      <ul>{rationale-items}</ul>
+      <p><strong>Implications:</strong></p>
+      <ul>{implication-items}</ul>
+    </div>
+  </details>
+</div>
+<div class="phase-content active" data-phase="1">
+  <!-- Phase 1 decisions -->
+</div>
+```
+
+All phase-content divs start with `active` class so "All" tab shows everything by default.
+
+**Generate context HTML:**
+For each resolved question, associate with a phase via `**Related Decisions:** DEC-XXX` field:
+- Look up the phase of the referenced decision
+- If no related decision, use phase 0
+- Wrap context items in phase-content divs (same pattern as decisions)
+
+**Generate plans HTML:**
+Plans are already grouped by phase directory. Wrap each phase in a phase-content div:
+```html
+<div class="phase-content active" data-phase="1">
+  <div class="phase-group">
+    <div class="phase-header">Phase 1: {title}</div>
+    <div class="plan-item">...</div>
+  </div>
+</div>
+<div class="phase-content active" data-phase="2">
+  <div class="phase-group">
+    <div class="phase-header">Phase 2: {title}</div>
+    <div class="plan-item">...</div>
+  </div>
+</div>
+```
+
+**Generate timeline HTML:**
+Combine decision dates and discussion session dates into chronological timeline.
+
+**Tab states:**
+- `{wireframes-disabled}` → "disabled" if no wireframes, empty if exists
+- `{diagrams-disabled}` → "disabled" if no diagrams, empty if exists
+
+**HTML-escape all content:**
+```javascript
+text.replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+```
+
+Continue to write_output.
+</step>
+
+<step name="write_output">
+Write the generated HTML to the blueprint directory.
+
+```bash
+# Create blueprint directory
+mkdir -p ".specd/features/$FEATURE_NAME/blueprint"
+```
+
+**Write file:**
+Use Write tool to create `.specd/features/{name}/blueprint/index.html`
+with the generated HTML content.
+
+Continue to open_browser.
+</step>
+
+<step name="open_browser">
+Open the blueprint in the default browser.
+
+```bash
+open ".specd/features/$FEATURE_NAME/blueprint/index.html"
+```
+
+**Present completion:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT GENERATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Feature:** {feature-name}
+
+## Stats
+- {N} decisions
+- {N} discussion sessions
+- {N} plans
+
+## Tabs
+- Overview ✓
+- Decisions ✓
+- Context ✓
+- Plans {✓ or ✗}
+- Wireframes {✓ or "not generated"}
+- Diagrams {✓ or "not generated"}
+
+**File:** `.specd/features/{name}/blueprint/index.html`
+
+───────────────────────────────────────────────────────
+
+## To Update
+
+Run `/specd:blueprint {name}` again to regenerate.
+
+## To Add Wireframes
+
+Run `/specd:blueprint {name} wireframes`
+
+## To Add Diagrams
+
+Run `/specd:blueprint {name} diagrams`
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Feature validated
+- [ ] All files read and parsed
+- [ ] HTML generated with all content embedded
+- [ ] Output written to `.specd/features/{name}/blueprint/index.html`
+- [ ] Browser opens with the blueprint
+</success_criteria>

package/specdacular/workflows/discuss-feature.md

@@ -63,7 +63,7 @@ Validate feature exists and has required files.
 ```
 Feature '{name}' not found.
 
-Did you mean to run /specd:new-feature {name} first?
+Did you mean to run /specd:feature:new {name} first?
 ```
 
 Continue to load_context.
@@ -358,13 +358,13 @@ Present session summary and next options.
 
 ## What's Next
 
-**/specd:discuss-feature {feature-name}** — Continue discussing
+**/specd:feature:discuss {feature-name}** — Continue discussing
   {Recommended if gray areas remain}
 
-**/specd:research-feature {feature-name}** — Research implementation
+**/specd:feature:research {feature-name}** — Research implementation
   {Recommended if technical questions need investigation}
 
-**/specd:plan-feature {feature-name}** — Create executable plans
+**/specd:feature:plan {feature-name}** — Create roadmap with phase overview
   {Recommended when discussion is sufficient}
 
 Or just **keep talking** — this conversation continues naturally.

package/specdacular/workflows/execute-plan.md

@@ -64,14 +64,14 @@ Validate feature exists and has plans.
 ```
 Feature '{name}' not found.
 
-Run /specd:new-feature {name} to create it.
+Run /specd:feature:new {name} to create it.
 ```
 
 **If no plans:**
 ```
 Feature '{name}' has no plans yet.
 
-Run /specd:plan-feature {name} to create plans.
+Run /specd:feature:plan {name} to create a roadmap, then /specd:phase:plan {name} {N} to create plans.
 ```
 
 Continue to load_context.
@@ -101,7 +101,7 @@ Load ALL context needed for execution.
 - Which phase we're in
 - Key decisions affecting implementation
 - Patterns to follow
-- Phase-specific context and research (if discuss-phase/research-phase were run)
+- Phase-specific context and research (if phase:prepare/phase:research were run)
 
 Continue to find_plan.
 </step>
@@ -383,7 +383,7 @@ git commit -m "docs({feature}): complete plan {phase-XX/YY}"
 **Next plan:** {path or "None - all plans complete"}
 
 {If next plan exists:}
-Run `/specd:execute-plan {feature}` to continue.
+Run `/specd:phase:execute {feature}` to continue.
 
 {If all complete:}
 All plans complete! Feature '{feature}' is implemented.

package/specdacular/workflows/insert-phase.md

@@ -0,0 +1,222 @@
+<purpose>
+Insert a new phase after an existing one using decimal numbering (e.g., Phase 03.1).
+
+**Key principles:**
+- Decimal numbering preserves existing phase sequence
+- Never renumber existing phases — that's what renumber-phases is for
+- Create directory structure but don't create plans — user decides how to plan
+- Mark inserted phases with `(INSERTED)` in ROADMAP.md
+
+**Output:** New phase directory, updated ROADMAP.md, STATE.md, config.json
+</purpose>
+
+<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
+
+Example: `/specd:phase:insert visual-blueprint-tool 3 Architecture Update`
+→ feature = "visual-blueprint-tool"
+→ after = 3
+→ description = "Architecture Update"
+
+**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)
+
+**If arguments missing:**
+```
+ERROR: Missing arguments.
+
+Usage: /specd:phase:insert [feature-name] [after-phase] [description...]
+Example: /specd:phase:insert visual-blueprint-tool 3 Architecture Update
+```
+</step>
+
+<step name="validate">
+Validate the feature and target phase exist.
+
+1. Check feature directory exists:
+```bash
+[ -d ".specd/features/$feature" ] || { echo "Feature not found"; exit 1; }
+```
+
+2. Check ROADMAP.md exists:
+```bash
+[ -f ".specd/features/$feature/ROADMAP.md" ] || { echo "No ROADMAP.md"; exit 1; }
+```
+
+3. Check target phase exists in ROADMAP.md:
+   - Search for phase heading matching the target number (e.g., `## Phase 3:` or `### Phase 3:`)
+   - If not found, list available phases and exit
+
+4. Check config.json exists:
+```bash
+[ -f ".specd/features/$feature/config.json" ] || { echo "No config.json"; exit 1; }
+```
+
+**If feature not found:**
+```
+Feature '{name}' not found.
+
+Available features:
+{list .specd/features/*/}
+
+Run /specd:feature:new {name} to create it.
+```
+
+**If target phase not found:**
+```
+Phase {N} not found in ROADMAP.md.
+
+Available phases: {list phase numbers from ROADMAP.md}
+```
+</step>
+
+<step name="find_next_decimal">
+Scan for existing decimal phases after the target phase.
+
+1. List all `phase-*` directories under `plans/`:
+```bash
+ls -d .specd/features/$feature/plans/phase-* 2>/dev/null
+```
+
+2. Filter for directories matching `phase-{NN}.{M}` where NN matches the target phase (zero-padded to 2 digits):
+   - Format target phase as two digits: `printf "%02d" $after_phase`
+   - Look for `phase-{NN}.1/`, `phase-{NN}.2/`, etc.
+
+3. Find the highest existing decimal suffix M
+
+4. Calculate next decimal: M + 1 (or 1 if no decimals exist)
+
+Examples:
+- Phase 03 with no decimals → next is 03.1
+- Phase 03 with 03.1 → next is 03.2
+- Phase 03 with 03.1, 03.2 → next is 03.3
+
+Store the new phase number as: `new_phase = "{NN}.{next_decimal}"`
+(e.g., "03.1")
+</step>
+
+<step name="create_phase_directory">
+Create the phase directory under the feature's plans folder.
+
+```bash
+mkdir -p ".specd/features/$feature/plans/phase-${new_phase}"
+```
+
+Confirm: "Created directory: plans/phase-{new_phase}/"
+</step>
+
+<step name="update_roadmap">
+Insert the new phase into ROADMAP.md immediately after the target phase's section.
+
+1. Read ROADMAP.md
+2. Find the target phase section (heading and all content until the next phase heading)
+3. Insert new phase section after the target phase's content:
+
+```markdown
+## Phase {new_phase}: {Description} (INSERTED)
+
+**Goal:** {Description}
+**Plans:** TBD — discuss and plan this phase
+
+- [ ] Phase {new_phase} plans created
+```
+
+4. Write updated ROADMAP.md
+
+**Important:**
+- Preserve all existing content exactly (formatting, spacing, other phases)
+- The `(INSERTED)` marker identifies decimal phases as mid-flight insertions
+- Don't modify the target phase content
+- Insert before the next integer phase heading
+</step>
+
+<step name="update_state">
+Update STATE.md with the insertion.
+
+1. Read STATE.md
+
+2. Add roadmap evolution note. Find or create "### Roadmap Evolution" section under accumulated context:
+```markdown
+- Phase {new_phase} inserted after Phase {after_phase}: {description}
+```
+
+3. Add the new phase to the execution tracking section. Find the phase completion checkboxes and insert the new phase after the target phase:
+```markdown
+- [ ] Phase {new_phase} complete
+```
+
+Insert this line after `Phase {after_phase}` checkbox and before `Phase {after_phase + 1}` checkbox.
+
+4. Write updated STATE.md
+</step>
+
+<step name="update_config">
+Update config.json to reflect the new phase count.
+
+1. Read config.json
+2. Increment `phases_count` by 1
+3. Write updated config.json
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PHASE INSERTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {new_phase}: {description}**
+- Directory: plans/phase-{new_phase}/
+- Inserted after: Phase {after_phase}
+- Marker: (INSERTED)
+
+**Updated:**
+- ROADMAP.md — New phase section added
+- STATE.md — Evolution note + unchecked checkbox
+- config.json — phases_count 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
+```
+
+End workflow.
+</step>
+
+</process>
+
+<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 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
+</anti_patterns>
+
+<success_criteria>
+Phase insertion is complete when:
+
+- [ ] Arguments parsed: feature name, after-phase number, description
+- [ ] Feature validated: exists with ROADMAP.md
+- [ ] Target phase validated: exists in ROADMAP.md
+- [ ] Decimal number calculated correctly (based on existing decimals)
+- [ ] Phase directory created: `plans/phase-{NN.M}/`
+- [ ] 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
+- [ ] User informed of next steps
+</success_criteria>

package/specdacular/workflows/new-feature.md

@@ -67,7 +67,7 @@ Use AskUserQuestion:
 - header: "Feature Exists"
 - question: "Feature '{name}' already exists. What would you like to do?"
 - options:
-  - "Resume" — Continue with existing feature (suggest /specd:discuss-feature)
+  - "Resume" — Continue with existing feature (suggest /specd:feature:discuss)
   - "Reset" — Delete and start fresh
   - "Different name" — Use a different name
 
@@ -164,7 +164,7 @@ Does that capture it, or should we dig into anything more?
 **When to move on:**
 - User confirms understanding is correct
 - You have enough for initial FEATURE.md
-- Further details can be discussed later with /specd:discuss-feature
+- Further details can be discussed later with /specd:feature:discuss
 
 Continue to write_feature.
 </step>
@@ -322,13 +322,13 @@ Present what was created and next options.
 
 You control the rhythm. Options:
 
-**/specd:discuss-feature {feature-name}** — Dive deeper into specific areas
+**/specd:feature:discuss {feature-name}** — Dive deeper into specific areas
   {Suggested if gray areas remain}
 
-**/specd:research-feature {feature-name}** — Research implementation approach
+**/specd:feature:research {feature-name}** — Research implementation approach
   {Suggested if technology choices are unclear}
 
-**/specd:plan-feature {feature-name}** — Create executable task plans
+**/specd:feature:plan {feature-name}** — Create roadmap with phase overview
   {Only when discussion + research are sufficient}
 
 Or just **keep talking** — this conversation continues naturally.