npm - specdacular - Versions diffs - 0.7.1 → 0.8.0 - Mend

specdacular 0.7.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (63) hide show

package/README.md +72 -74
package/commands/specd/continue.md +59 -0
package/commands/specd/new.md +65 -0
package/commands/specd/status.md +1 -1
package/commands/specd/toolbox.md +59 -0
package/package.json +1 -1
package/specdacular/HELP.md +19 -16
package/specdacular/agents/feature-researcher.md +4 -4
package/specdacular/references/load-context.md +83 -0
package/specdacular/references/record-decision.md +61 -0
package/specdacular/references/select-feature.md +20 -20
package/specdacular/references/select-phase.md +3 -3
package/specdacular/references/spawn-research-agents.md +180 -0
package/specdacular/references/synthesize-research.md +127 -0
package/specdacular/references/validate-task.md +64 -0
package/specdacular/templates/{features → tasks}/CHANGELOG.md +2 -8
package/specdacular/templates/{features → tasks}/CONTEXT.md +6 -17
package/specdacular/templates/tasks/DECISIONS.md +46 -0
package/specdacular/templates/{features → tasks}/FEATURE.md +3 -3
package/specdacular/templates/tasks/PLAN.md +91 -0
package/specdacular/templates/tasks/RESEARCH.md +121 -0
package/specdacular/templates/{features → tasks}/ROADMAP.md +6 -43
package/specdacular/templates/tasks/STATE.md +93 -0
package/specdacular/templates/tasks/config.json +15 -0
package/specdacular/workflows/continue.md +275 -0
package/specdacular/workflows/discuss.md +184 -0
package/specdacular/workflows/execute.md +174 -0
package/specdacular/workflows/new.md +299 -0
package/specdacular/workflows/orchestrator/new.md +265 -0
package/specdacular/workflows/orchestrator/plan.md +169 -0
package/specdacular/workflows/plan.md +201 -0
package/specdacular/workflows/research.md +166 -0
package/specdacular/workflows/review.md +289 -0
package/specdacular/workflows/status.md +17 -17
package/commands/specd/blueprint.md +0 -64
package/commands/specd/feature/continue.md +0 -84
package/commands/specd/feature/new.md +0 -67
package/commands/specd/feature/toolbox.md +0 -49
package/specdacular/templates/blueprint/index.html +0 -110
package/specdacular/templates/blueprint/scripts.js +0 -71
package/specdacular/templates/blueprint/styles.css +0 -429
package/specdacular/templates/features/DECISIONS.md +0 -109
package/specdacular/templates/features/DEPENDENCIES.md +0 -47
package/specdacular/templates/features/PLAN.md +0 -180
package/specdacular/templates/features/RESEARCH.md +0 -183
package/specdacular/templates/features/STATE.md +0 -110
package/specdacular/templates/features/config.json +0 -20
package/specdacular/workflows/blueprint-diagrams.md +0 -273
package/specdacular/workflows/blueprint-wireframes.md +0 -312
package/specdacular/workflows/blueprint.md +0 -372
package/specdacular/workflows/continue-feature.md +0 -621
package/specdacular/workflows/discuss-feature.md +0 -382
package/specdacular/workflows/execute-plan.md +0 -636
package/specdacular/workflows/insert-phase.md +0 -246
package/specdacular/workflows/new-feature.md +0 -760
package/specdacular/workflows/plan-feature.md +0 -691
package/specdacular/workflows/plan-phase.md +0 -355
package/specdacular/workflows/prepare-phase.md +0 -745
package/specdacular/workflows/renumber-phases.md +0 -273
package/specdacular/workflows/research-feature.md +0 -252
package/specdacular/workflows/research-phase.md +0 -576
package/specdacular/workflows/review-feature.md +0 -316
package/specdacular/workflows/review-phase.md +0 -545

package/specdacular/workflows/blueprint-diagrams.md DELETED Viewed

@@ -1,273 +0,0 @@
-<purpose>
-Generate Mermaid diagrams for a Specdacular feature blueprint.
-Reads FEATURE.md, DECISIONS.md, and plans to understand the feature flow
-and data relationships, then generates visual diagrams.
-**Output:** `.specd/features/{name}/blueprint/diagrams.html`
-**Invoked by:** `/specd:blueprint {feature} diagrams`
-</purpose>
-<philosophy>
-## High-Level Understanding
-Diagrams should help users understand the feature at a conceptual level.
-Focus on the happy path and main flow, not every edge case.
-## Two Diagram Types
-1. **Flow Diagram** — Shows the process/workflow from start to end
-2. **ER Diagram** — Shows data entities and relationships (if applicable)
-## Keep It Simple
-- Maximum 10-15 nodes per diagram
-- Clear labels, no jargon
-- Logical grouping with subgraphs if needed
-</philosophy>
-<process>
-<step name="validate">
-Check feature exists and main blueprint was generated.
-```bash
-# Check feature directory exists
-[ -d ".specd/features/$FEATURE_NAME" ] || { echo "Feature not found"; exit 1; }
-# Check blueprint exists (diagrams extend the blueprint)
-[ -f ".specd/features/$FEATURE_NAME/blueprint/index.html" ] || { echo "Run /specd:blueprint $FEATURE_NAME first"; exit 1; }
-```
-**If blueprint not found:**
-```
-Blueprint not generated yet.
-Run `/specd:blueprint {name}` first, then add diagrams.
-```
-Continue to load_context.
-</step>
-<step name="load_context">
-Read feature files to understand flow and data relationships.
-**Read with Read tool:**
-- `.specd/features/{name}/FEATURE.md` — Feature purpose, components
-- `.specd/features/{name}/DECISIONS.md` — Architectural decisions
-- `.specd/features/{name}/CONTEXT.md` — Clarified requirements
-- `.specd/features/{name}/plans/` — Execution plans (if exist)
-**Extract:**
-- Main user journey (from FEATURE.md)
-- Key decision points (from DECISIONS.md)
-- Data entities and relationships (from artifacts)
-- Process steps (from plans)
-Continue to generate_flow_diagram.
-</step>
-<step name="generate_flow_diagram">
-Generate a Mermaid flowchart showing the feature's process flow.
-**Analyze feature to identify:**
-- Start point (user action or trigger)
-- Main process steps
-- Decision points (if/else branches)
-- End point (success state)
-**Mermaid flowchart syntax:**
-```mermaid
-graph TD
-    A[Start: User Action] --> B[Step 1]
-    B --> C{Decision Point}
-    C -->|Yes| D[Happy Path]
-    C -->|No| E[Alternative]
-    D --> F[End: Success]
-    E --> F
-```
-**Guidelines:**
-- Use `graph TD` (top-down) for process flows
-- Use `graph LR` (left-right) for pipelines
-- Keep to 10-15 nodes maximum
-- Use clear, short labels
-- Group related steps in subgraphs if needed
-**Store flow diagram Mermaid code for later embedding.**
-Continue to generate_er_diagram.
-</step>
-<step name="generate_er_diagram">
-Generate a Mermaid ER diagram showing data relationships.
-**Analyze feature to identify:**
-- Main data entities (files, objects, records)
-- Relationships between entities
-- Key attributes of each entity
-**Mermaid ER syntax:**
-```mermaid
-erDiagram
-    FEATURE ||--o{ DECISION : contains
-    FEATURE ||--o{ PLAN : has
-    DECISION {
-        string id
-        string title
-        string status
-    }
-    PLAN {
-        int phase
-        int number
-        string title
-    }
-```
-**Guidelines:**
-- Only include entities relevant to understanding the feature
-- Show cardinality: `||` (one), `o{` (many), `|o` (zero or one)
-- Include 2-4 key attributes per entity
-- Skip ER diagram if feature doesn't have meaningful data relationships
-**Store ER diagram Mermaid code for later embedding.**
-Continue to generate_html.
-</step>
-<step name="generate_html">
-Generate the diagrams HTML page with embedded Mermaid.
-**HTML template:**
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Diagrams: {feature-name}</title>
-  <script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
-  <style>
-    body { font-family: system-ui, sans-serif; background: #f5f5f5; margin: 0; padding: 20px; }
-    .diagram-container { max-width: 1000px; margin: 0 auto; }
-    .diagram-section { background: white; border: 1px solid #ddd; padding: 20px; margin-bottom: 20px; border-radius: 4px; }
-    .diagram-section h2 { margin-top: 0; color: #333; border-bottom: 1px solid #eee; padding-bottom: 10px; }
-    .mermaid { text-align: center; }
-    .diagram-description { color: #666; font-size: 14px; margin-bottom: 15px; }
-  </style>
-</head>
-<body>
-  <div class="diagram-container">
-    <h1>{feature-name} - Diagrams</h1>
-    <p style="color: #666;">Generated {date}</p>
-    <div class="diagram-section">
-      <h2>Process Flow</h2>
-      <p class="diagram-description">{flow-description}</p>
-      <pre class="mermaid">
-{flow-diagram-mermaid}
-      </pre>
-    </div>
-    <div class="diagram-section">
-      <h2>Data Relationships</h2>
-      <p class="diagram-description">{er-description}</p>
-      <pre class="mermaid">
-{er-diagram-mermaid}
-      </pre>
-    </div>
-  </div>
-  <script>
-    mermaid.initialize({
-      startOnLoad: true,
-      theme: 'default',
-      securityLevel: 'loose'
-    });
-  </script>
-</body>
-</html>
-```
-**Replace placeholders:**
-- `{feature-name}` — Feature name
-- `{date}` — Current date (YYYY-MM-DD)
-- `{flow-description}` — Brief description of what the flow shows
-- `{flow-diagram-mermaid}` — Generated flow diagram code
-- `{er-description}` — Brief description of data model
-- `{er-diagram-mermaid}` — Generated ER diagram code
-Continue to write_diagrams.
-</step>
-<step name="write_diagrams">
-Write the diagrams HTML file.
-**Write file:**
-Use Write tool to create `.specd/features/{name}/blueprint/diagrams.html`
-with the generated HTML content.
-Continue to update_blueprint.
-</step>
-<step name="update_blueprint">
-Update the main blueprint to enable the diagrams tab.
-**Read:** `.specd/features/{name}/blueprint/index.html`
-**Find and update:**
-- Change `class="tab-link disabled"` to `class="tab-link"` for diagrams tab
-- Find `<section id="diagrams"` and update content:
-```html
-<section id="diagrams" class="tab-content">
-  <h2>Diagrams</h2>
-  <p>Visual diagrams showing feature flow and data relationships.</p>
-  <iframe src="diagrams.html" style="width: 100%; height: 700px; border: 1px solid #ddd;"></iframe>
-  <p><a href="diagrams.html" target="_blank">Open in new tab</a></p>
-</section>
-```
-**Write updated blueprint.**
-Continue to present_completion.
-</step>
-<step name="present_completion">
-Present diagrams completion.
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DIAGRAMS GENERATED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-**Feature:** {feature-name}
-## Diagrams Created
-- Flow Diagram: {brief description}
-- ER Diagram: {brief description}
-## Files
-- Diagrams: `.specd/features/{name}/blueprint/diagrams.html`
-- Blueprint updated: Diagrams tab now enabled
-───────────────────────────────────────────────────────
-**View:** Open blueprint in browser to see diagrams tab.
-**Regenerate:** Run `/specd:blueprint {name} diagrams` again to update.
-```
-End workflow.
-</step>
-</process>
-<success_criteria>
-- [ ] Feature validated
-- [ ] Flow diagram generated from feature artifacts
-- [ ] ER diagram generated (if applicable)
-- [ ] Diagrams HTML written with Mermaid.js
-- [ ] Main blueprint updated with diagrams tab enabled
-</success_criteria>

package/specdacular/workflows/blueprint-wireframes.md DELETED Viewed

@@ -1,312 +0,0 @@
-<purpose>
-Generate HTML/CSS wireframes for a Specdacular feature blueprint.
-Reads FEATURE.md to understand UI requirements, generates visual mockups
-showing layout, component placement, and interaction points.
-**Output:** `.specd/features/{name}/blueprint/wireframes.html`
-**Invoked by:** `/specd:blueprint {feature} wireframes`
-</purpose>
-<philosophy>
-## PM-Friendly Output
-Wireframes should be understandable by non-technical stakeholders.
-Focus on layout, navigation flow, and button placement rather than
-implementation details.
-## Visual Over Text
-Generate actual HTML/CSS mockups, not ASCII diagrams. Use boxes,
-buttons, and placeholder text that resembles the final UI.
-## Consistent Style
-Use a consistent wireframe aesthetic:
-- Gray backgrounds for containers
-- Blue buttons for primary actions
-- Dashed borders for optional/future elements
-- Clear labels for all interactive elements
-</philosophy>
-<process>
-<step name="validate">
-Check feature exists and main blueprint was generated.
-```bash
-# Check feature directory exists
-[ -d ".specd/features/$FEATURE_NAME" ] || { echo "Feature not found"; exit 1; }
-# Check blueprint exists (wireframes extend the blueprint)
-[ -f ".specd/features/$FEATURE_NAME/blueprint/index.html" ] || { echo "Run /specd:blueprint $FEATURE_NAME first"; exit 1; }
-```
-**If blueprint not found:**
-```
-Blueprint not generated yet.
-Run `/specd:blueprint {name}` first, then add wireframes.
-```
-Continue to prompt_scope.
-</step>
-<step name="prompt_scope">
-Prompt user for wireframe scope.
-**Present choice using AskUserQuestion:**
-```
-question: "What scope for wireframes?"
-header: "Scope"
-options:
-  - label: "Per feature (recommended)"
-    description: "Single wireframe showing the complete feature UI"
-  - label: "Per phase"
-    description: "Separate wireframe for each phase (useful for complex multi-phase features)"
-```
-**Store response:**
-- "Per feature" → scope = "feature"
-- "Per phase" → scope = "phase"
-Continue to load_context.
-</step>
-<step name="load_context">
-Read feature files to understand UI requirements.
-**Read with Read tool:**
-- `.specd/features/{name}/FEATURE.md` — UI requirements, components
-- `.specd/features/{name}/DECISIONS.md` — UI-related decisions
-- `.specd/features/{name}/CONTEXT.md` — Clarified requirements
-**Extract from FEATURE.md:**
-- `## What This Is` — Overall feature purpose
-- `### Must Create` — Components and files (look for UI elements)
-- `## Success Criteria` — User-facing requirements
-**If scope is "phase":**
-- List phase directories in `.specd/features/{name}/plans/`
-- For each phase, note if it has UI-related content
-- Phases are numbered: phase-01, phase-02, etc.
-Continue to analyze_ui.
-</step>
-<step name="analyze_ui">
-Identify UI components from feature artifacts.
-**Look for:**
-- Commands/inputs the user will interact with
-- Output displays (HTML pages, reports, visualizations)
-- Navigation elements (tabs, menus, links)
-- Action buttons (submit, generate, refresh)
-- Data displays (lists, tables, cards)
-**For each component, note:**
-- Name and purpose
-- Position in layout (header, sidebar, main, footer)
-- Interaction type (click, input, select)
-- Relationship to other components
-Continue to generate_wireframe.
-</step>
-<step name="generate_wireframe">
-Generate HTML/CSS wireframe mockup.
-**If scope is "feature":**
-Generate single combined wireframe as below.
-**If scope is "phase":**
-For each phase:
-1. Analyze phase plans for UI components
-2. If phase has UI elements:
-   - Generate wireframe for that phase
-   - Add phase number to header: "Phase N: {feature-name}"
-3. If phase has NO UI elements:
-   - Skip wireframe generation for this phase
-   - Note: "Phase N has no UI — consider generating diagrams"
-**Wireframe template structure:**
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Wireframe: {feature-name}</title>
-  <style>
-    /* Wireframe styles */
-    body { font-family: system-ui, sans-serif; background: #f0f0f0; margin: 0; padding: 20px; }
-    .wireframe-container { max-width: 1200px; margin: 0 auto; }
-    .wireframe-header { background: #e0e0e0; padding: 20px; border: 2px solid #999; margin-bottom: 20px; }
-    .wireframe-section { background: white; border: 2px solid #ccc; padding: 20px; margin-bottom: 20px; }
-    .wireframe-button { background: #4a90d9; color: white; padding: 10px 20px; border: none; cursor: pointer; }
-    .wireframe-button.secondary { background: #888; }
-    .wireframe-input { border: 2px solid #ccc; padding: 10px; width: 200px; }
-    .wireframe-placeholder { background: #f5f5f5; border: 2px dashed #ccc; padding: 40px; text-align: center; color: #888; }
-    .wireframe-label { font-size: 12px; color: #666; margin-bottom: 5px; }
-    .wireframe-nav { display: flex; gap: 10px; margin-bottom: 20px; }
-    .wireframe-nav-item { padding: 10px 15px; background: #ddd; border: 1px solid #999; }
-    .wireframe-nav-item.active { background: #4a90d9; color: white; }
-  </style>
-</head>
-<body>
-  <div class="wireframe-container">
-    <div class="wireframe-header">
-      <h1>{feature-name}</h1>
-      <p class="wireframe-label">Feature Wireframe - Generated {date}</p>
-    </div>
-    <!-- Generated wireframe content -->
-    {wireframe-content}
-  </div>
-</body>
-</html>
-```
-**Generate content based on feature type:**
-For command-based features:
-```html
-<div class="wireframe-section">
-  <p class="wireframe-label">Command Input</p>
-  <code>/{command-name} {arguments}</code>
-</div>
-<div class="wireframe-section">
-  <p class="wireframe-label">Output Display</p>
-  <div class="wireframe-placeholder">
-    {output-description}
-  </div>
-</div>
-```
-For UI-based features:
-```html
-<div class="wireframe-nav">
-  <div class="wireframe-nav-item active">Tab 1</div>
-  <div class="wireframe-nav-item">Tab 2</div>
-</div>
-<div class="wireframe-section">
-  <p class="wireframe-label">Main Content Area</p>
-  <!-- Component mockups -->
-</div>
-```
-Continue to write_wireframe.
-</step>
-<step name="write_wireframe">
-Write the wireframe HTML file(s).
-**If scope is "feature":**
-Use Write tool to create `.specd/features/{name}/blueprint/wireframes.html`
-with the generated wireframe content.
-**If scope is "phase":**
-For each phase with UI elements:
-- Write to `.specd/features/{name}/blueprint/wireframes-phase-{NN}.html`
-- Example: `wireframes-phase-01.html`, `wireframes-phase-02.html`
-Continue to update_blueprint.
-</step>
-<step name="update_blueprint">
-Update the main blueprint to enable the wireframes tab.
-**Read:** `.specd/features/{name}/blueprint/index.html`
-**Find and update:**
-- Change `class="tab-link disabled"` to `class="tab-link"` for wireframes tab
-- Find `<section id="wireframes"` and update content:
-**If scope is "feature":**
-```html
-<section id="wireframes" class="tab-content">
-  <h2>Wireframes</h2>
-  <p>Visual mockup of the feature interface.</p>
-  <iframe src="wireframes.html" style="width: 100%; height: 600px; border: 1px solid #ddd;"></iframe>
-  <p><a href="wireframes.html" target="_blank">Open in new tab</a></p>
-</section>
-```
-**If scope is "phase":**
-```html
-<section id="wireframes" class="tab-content">
-  <h2>Wireframes</h2>
-  <p>Visual mockups of the feature interface.</p>
-  <div class="phase-tabs">
-    <button class="phase-tab active" data-wireframe="phase-01">Phase 1</button>
-    <button class="phase-tab" data-wireframe="phase-02">Phase 2</button>
-    <!-- ... for each phase with wireframes -->
-  </div>
-  <iframe id="wireframe-viewer" src="wireframes-phase-01.html" style="width: 100%; height: 600px; border: 1px solid #ddd;"></iframe>
-  <script>
-    document.querySelectorAll('[data-wireframe]').forEach(btn => {
-      btn.addEventListener('click', function() {
-        document.querySelectorAll('[data-wireframe]').forEach(b => b.classList.remove('active'));
-        this.classList.add('active');
-        document.getElementById('wireframe-viewer').src = 'wireframes-' + this.dataset.wireframe + '.html';
-      });
-    });
-  </script>
-</section>
-```
-**Write updated blueprint.**
-Continue to present_completion.
-</step>
-<step name="present_completion">
-Present wireframes completion.
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- WIREFRAMES GENERATED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-**Feature:** {feature-name}
-## Components Visualized
-- {list of UI components}
-## Files
-**If scope is "feature":**
-- Wireframe: `.specd/features/{name}/blueprint/wireframes.html`
-**If scope is "phase":**
-- Phase 1: `.specd/features/{name}/blueprint/wireframes-phase-01.html`
-- Phase 2: `.specd/features/{name}/blueprint/wireframes-phase-02.html`
-<!-- ... for each generated phase -->
-**Phases without UI:**
-- Phase N: No UI elements (consider `/specd:blueprint {name} diagrams`)
-- Blueprint updated: Wireframes tab now enabled
-───────────────────────────────────────────────────────
-**View:** Open blueprint in browser to see wireframes tab.
-**Regenerate:** Run `/specd:blueprint {name} wireframes` again to update.
-```
-End workflow.
-</step>
-</process>
-<success_criteria>
-- [ ] Feature validated
-- [ ] UI components identified from artifacts
-- [ ] Wireframe HTML generated
-- [ ] Main blueprint updated with wireframes tab enabled
-</success_criteria>