gspec 1.15.0 → 1.17.0

package/README.md

@@ -25,7 +25,7 @@ These documents become the shared context for all subsequent AI interactions. Wh
 
 The only commands you *need* are the four fundamentals and `/gspec-implement`. Everything else exists to help when your project calls for it.
 
-The fundamentals give your AI tool enough context to build well — it knows what the product is, how it should look, what technologies to use, and what engineering standards to follow. From there, `/gspec-implement` can take a plain-language description and start building. The remaining commands — `/gspec-research`, `/gspec-feature`, `/gspec-architect`, and `/gspec-analyze` — add structure and rigor when the scope or complexity warrants it.
+The fundamentals give your AI tool enough context to build well — it knows what the product is, how it should look, what technologies to use, and what engineering standards to follow. From there, `/gspec-implement` can take a plain-language description and start building. The remaining commands — `/gspec-research`, `/gspec-feature`, `/gspec-architect`, `/gspec-tasks`, `/gspec-analyze`, and `/gspec-audit` — add structure and rigor when the scope or complexity warrants it.
 
 ```mermaid
 flowchart LR
@@ -42,10 +42,14 @@ flowchart LR
     Architect["4. Architect
     technical blueprint"]
 
-    Analyze["5. Analyze
-    reconcile specs"]
+    Plan["5. Plan
+    ordered tasks"]
 
-    Build["6. Build
+    Analyze["6. Analyze & Audit
+    reconcile specs
+    check specs vs code"]
+
+    Build["7. Build
     implement"]
 
     Define --> Research
@@ -54,9 +58,12 @@ flowchart LR
     Research --> Specify
     Research --> Build
     Specify --> Architect
+    Specify --> Plan
     Specify --> Build
+    Architect --> Plan
     Architect --> Analyze
     Architect --> Build
+    Plan --> Build
     Analyze --> Build
     Build --> Define
 
@@ -64,6 +71,7 @@ flowchart LR
     style Research fill:#a855f7,color:#fff,stroke:none
     style Specify fill:#f59e0b,color:#fff,stroke:none
     style Architect fill:#f59e0b,color:#fff,stroke:none
+    style Plan fill:#f59e0b,color:#fff,stroke:none
     style Analyze fill:#f59e0b,color:#fff,stroke:none
     style Build fill:#22c55e,color:#fff,stroke:none
 ```
@@ -76,7 +84,7 @@ flowchart LR
 | Command | Role | What it produces |
 |---|---|---|
 | `/gspec-profile` | Business Strategist | Product identity, audience, value proposition, positioning |
-| `/gspec-style` | UI/UX Designer | Visual design language, design tokens, component patterns |
+| `/gspec-style` | UI/UX Designer | Visual design language, design tokens, component patterns. Produces either a renderable `style.html` design system or a `style.md` Markdown guide |
 | `/gspec-stack` | Software Architect | Technology stack, frameworks, infrastructure, architecture |
 | `/gspec-practices` | Engineering Lead | Development standards, code quality, testing, workflows |
 
@@ -104,22 +112,35 @@ Use `/gspec-feature` when you want detailed PRDs with prioritized capabilities a
 
 Use `/gspec-architect` when your feature involves significant technical complexity — new data models, service boundaries, auth flows, or integration points that benefit from upfront design. It also **identifies technical gaps and ambiguities** in your specs and proposes solutions, so that `/gspec-implement` can focus on building rather than making architectural decisions. For straightforward features, `/gspec-implement` can make sound architectural decisions on its own using your `stack` and `practices` specs.
 
-**5. Analyze** *(optional)* — Reconcile discrepancies across specs before building.
+**5. Plan** *(optional)* — Decompose a feature PRD into ordered work.
+
+| Command | Role | What it produces |
+|---|---|---|
+| `/gspec-tasks` | Engineering Lead | A sibling `gspec/features/<feature>.tasks.md` file with stable task IDs, explicit `deps:` lines, and `[P]` markers for parallel-safe work |
+
+Use `/gspec-tasks` after `/gspec-feature` (and after `/gspec-architect` when it exists) for any feature large enough that build order matters or that has work which could legitimately run in parallel. The output is what `/gspec-implement` consumes — when a tasks file exists for an in-scope feature, implement plans phases from it, respecting deps and surfacing `[P]`-marked tasks for parallel execution. Trivial features can skip this step and go straight to `/gspec-implement`, which falls back to PRD-checkbox-driven planning.
+
+**6. Analyze & Audit** *(optional)* — Reconcile discrepancies before building, and keep specs honest as the codebase evolves.
 
 | Command | Role | What it does |
 |---|---|---|
-| `/gspec-analyze` | Specification Analyst | Cross-references all specs, identifies contradictions, and walks you through reconciling each one |
+| `/gspec-analyze` | Specification Analyst | Cross-references all specs against **each other**, identifies contradictions, and walks you through reconciling each one |
+| `/gspec-audit` | Specification Auditor | Cross-references specs against the **actual codebase**, finds drift (stack mismatches, stale data models, design tokens that don't match the stylesheet, capability checkboxes that lie), and walks you through updating specs to match reality |
+
+Use `/gspec-analyze` after `/gspec-architect` (or any time multiple specs exist) to catch spec-to-spec conflicts before `/gspec-implement` sees them. For example, if the stack says PostgreSQL but the architecture references MongoDB.
 
-Use `/gspec-analyze` after `/gspec-architect` (or any time multiple specs exist) to catch conflicts before `/gspec-implement` sees them. For example, if the stack says PostgreSQL but the architecture references MongoDB, or a feature PRD defines a data model that contradicts the architecture, `/gspec-analyze` will surface the discrepancy and let you choose the resolution. Each conflict is presented one at a time with options — no new files are created, only existing specs are updated.
+Use `/gspec-audit` periodically — before a major release, after a long sprint, or any time you suspect docs have drifted from code. Audit reads package manifests, configs, source files, and test output, then asks you per-finding whether to update the spec to match the code, keep the spec and fix the code separately, or defer. Each finding is presented one at a time with the spec quote and the code evidence side by side. Audit never modifies code.
 
-**6. Build** — Implement with full context.
+**7. Build** — Implement with full context.
 
 | Command | Role | What it does |
 |---|---|---|
-| `/gspec-implement` | Senior Engineer | Reads all specs, plans the build order, and implements |
+| `/gspec-implement` | Senior Engineer | Reads all specs (including any `*.tasks.md` files), plans the build order, and implements |
 
 **Spec Sync** — gspec includes always-on spec sync that automatically keeps your specification documents in sync as the code evolves. This is installed alongside the skills and requires no manual intervention — when code changes affect spec-documented behavior, the sync rules prompt your AI tool to update the relevant gspec files.
 
+**Design-tool integration** — The style guide supports both Markdown (`style.md`) and a renderable HTML design system (`style.html`) that design-aware AI tools can open, render, and reason about directly. Drop mockups from external design tools (Figma, v0, Framer AI, etc.) into `gspec/design/` and `/gspec-implement` will use them as authoritative visual guidance when building UI.
+
 **Maintenance** — Keep specs up to date with the latest gspec format.
 
 | Command | Role | What it does |
@@ -176,6 +197,18 @@ Saved specs are organized by type in `~/.gspec/` (profiles, stacks, styles, prac
 gspec restore playbook/my-starter
 ```
 
+## Extensions
+
+Author your own skills and have them auto-installed alongside the built-in `gspec-*` commands in every project. Extensions live in `~/.gspec/extensions/` as Markdown files with `name` and `description` frontmatter and the same shape as anything in `commands/`.
+
+```bash
+gspec extension save ./my-deploy.md   # Install a local skill file as a user extension
+gspec extension list                  # See what's installed
+gspec extension remove my-deploy      # Delete from ~/.gspec/extensions/
+```
+
+When you next run `npx gspec` in a project, the installer copies the built-in skills first, then emits each valid extension into the same per-platform install directory using the same formatting. Extension names that collide with built-in `gspec-*` skills are rejected with an error; malformed or duplicate extensions are skipped with a warning.
+
 ## Output Structure
 
 All specifications live in a `gspec/` directory at your project root:
@@ -184,18 +217,23 @@ All specifications live in a `gspec/` directory at your project root:
 project-root/
 └── gspec/
     ├── profile.md          # Product identity and positioning
-    ├── style.md            # Visual design language
+    ├── style.html          # Visual design language (HTML — renderable design system)
+    │                       # or style.md if you prefer a Markdown style guide
     ├── stack.md            # Technology stack and architecture
     ├── practices.md        # Development standards
     ├── architecture.md     # Technical architecture blueprint
     ├── research.md         # Competitive analysis and feature gaps
+    ├── design/             # Optional — external mockups read during implementation
+    │   ├── dashboard.html
+    │   ├── checkout-flow.png
+    │   └── ...
     └── features/
         ├── user-authentication.md
         ├── dashboard-analytics.md
         └── ...
 ```
 
-These are standard Markdown files. They live in your repo, are version-controlled with your code, and are readable by both humans and AI tools.
+Most specs are Markdown. The style guide can also be a self-contained HTML file (`style.html`) that renders the design system as live swatches, typography specimens, and styled component previews — ideal for design-aware AI tools. The optional `gspec/design/` folder holds mockups (HTML, SVG, PNG, JPG) exported from external design tools like Figma, v0, or Framer AI; `/gspec-implement` reads them to reason about layout and visual intent. All files live in your repo, are version-controlled with your code, and are readable by both humans and AI tools.
 
 ## Key Design Decisions