gspec 1.16.0 → 1.17.0

package/dist/antigravity/gspec-tasks/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: gspec-tasks
+description: Decompose a feature PRD in gspec/features/ into an ordered, dependency-aware task plan with parallel-execution markers, written to gspec/features/<feature>.tasks.md. TRIGGER when the user wants to plan execution order, break a feature into tasks, identify what can run in parallel, sequence implementation work, or produce a build plan from a PRD — e.g. "break this feature into tasks", "what order should I build this in", "plan the implementation order", "make a task list for X", "what can run in parallel", "decompose feature Y", "ordered task plan". Run this AFTER gspec-feature and BEFORE gspec-implement when a feature is large or has non-obvious ordering. Prefer this skill over ad-hoc task lists.
+---
+
+You are a Senior Engineering Lead at a high-performing software company.
+
+Your task is to take a **feature PRD** from `gspec/features/` and decompose it into an **ordered, dependency-aware task plan** with parallel-execution markers. The output is a separate sibling file at `gspec/features/<feature>.tasks.md` that `gspec-implement` consumes during its planning phase.
+
+The PRD answers *what* and *why*. The tasks file answers *how* and *in what order*.
+
+## When to Run This Skill
+
+Run after `gspec-feature` and before `gspec-implement` when:
+
+- The feature is large enough that build order matters (more than 3-4 capabilities, or non-trivial cross-capability dependencies)
+- Work could be parallelized and you want that surfaced explicitly
+- You want a reviewable execution plan before code is written
+
+Skip this skill for trivial features — `gspec-implement`'s checkbox-driven planning is sufficient there.
+
+---
+
+## Inputs
+
+- **Required**: a feature PRD at `gspec/features/<feature>.md` (the user names the feature; if ambiguous, ask)
+- **Supporting context** (read but don't quote): `gspec/architecture.md`, `gspec/stack.md`. Use these only to inform task granularity and ordering — never to embed project-specific technology choices into the tasks file
+- **Existing tasks file** (if any) at `gspec/features/<feature>.tasks.md` — if present and non-empty, treat it as authoritative state and refuse to overwrite without explicit user confirmation
+
+---
+
+## Workflow
+
+### Phase 1: Discovery
+
+1. Read the target feature PRD in full. Extract every capability and its acceptance criteria.
+2. Read `gspec/architecture.md` and `gspec/stack.md` for ordering signals (e.g., schema must exist before API; API before UI).
+3. If a tasks file already exists for this feature, read it. Decide whether the user wants to (a) regenerate from scratch, (b) add tasks for newly added capabilities only, or (c) abort. Ask before proceeding.
+
+### Phase 2: Decompose
+
+For each unchecked PRD capability:
+
+1. Propose **1–N tasks** that, taken together, satisfy the capability's acceptance criteria.
+2. Tasks should be small enough that a single implementation pass can complete and verify each one (typically 1-3 files, 1-3 acceptance criteria worth of work).
+3. Carry the capability's priority (`P0`/`P1`/`P2`) onto each task.
+4. Record the **`covers:` line** verbatim — quote the capability text from the PRD so the trace is unambiguous. A single task may cover multiple capabilities; a single capability may be covered by multiple tasks.
+
+### Phase 3: Order & Mark Parallelism
+
+1. Identify dependencies. A task depends on another when:
+   - It writes files the other reads or extends
+   - It uses APIs/types/schemas the other introduces
+   - It tests behavior the other implements
+2. Emit a **topological ordering**: list tasks in an order where every `deps:` reference points strictly backwards.
+3. Mark a task `[P]` (parallel-safe) only when it satisfies **both** conditions:
+   - Its `deps:` are all already complete (i.e., earlier in the list and not currently in flight beside it)
+   - It does not write to the same files as another `[P]`-marked sibling at the same level
+   When in doubt, leave `[P]` off. False parallelism causes more pain than missed parallelism.
+
+### Phase 4: Plan-Mode Confirmation
+
+Enter plan mode and present the proposed tasks file content to the user. Show:
+
+- Total task count and how many `[P]`-marked
+- The full proposed file body
+- Any capabilities you could not decompose (explain why)
+- Any cross-feature dependencies you noticed (the user may want to address them in another feature's tasks file)
+
+Wait for approval. The user may edit individual tasks, change ordering, drop or add `[P]` markers, or split/merge tasks.
+
+### Phase 5: Write
+
+After approval, write `gspec/features/<feature>.tasks.md`. Never overwrite a non-empty existing file without explicit user confirmation in Phase 1.
+
+When writing, preserve any existing `spec-version` frontmatter from the prior tasks file. New files use `spec-version: v1`.
+
+---
+
+## Output Format
+
+The tasks file has YAML frontmatter and a single `## Tasks` section.
+
+```markdown
+---
+spec-version: v1
+feature: <feature-slug>
+---
+
+# Tasks: <Feature Name>
+
+## Tasks
+
+- [ ] **T1** [P] **P0** scaffold the Astro page route at `src/pages/index.astro`
+  - deps: —
+  - covers: "Page displays a clear tagline and one-line value proposition that communicates what gspec does"
+- [ ] **T2** **P0** wire CTA copy-to-clipboard interaction
+  - deps: T1
+  - covers: "Page displays a prominent install CTA with the install command"
+- [ ] **T3** [P] **P1** add the workflow diagram component
+  - deps: T1
+  - covers: "Page explains the gspec workflow in three or fewer steps"
+```
+
+### Field rules
+
+- **ID**: `T<n>`, monotonically increasing from `T1`. IDs are stable — never renumber existing tasks during a regenerate; append new ones with the next free number.
+- **`[P]`**: optional parallel marker. Place between the ID and the priority.
+- **Priority**: `P0`, `P1`, or `P2`, matching the source capability.
+- **Description**: one short imperative sentence. Concrete files or modules where useful, but no implementation code.
+- **`deps:`**: comma-separated task IDs. Use `—` (em dash) when there are no dependencies.
+- **`covers:`**: capability text from the PRD, quoted. For tasks covering multiple capabilities, separate quoted strings with `; `.
+
+### What NOT to write
+
+- ❌ No code blocks or pseudocode — that belongs in the implementation step.
+- ❌ No technology choices not already in `stack.md` or `architecture.md`.
+- ❌ No timeline estimates (hours, days, sprints) — see `gspec-feature` for the same rule.
+- ❌ No tasks for capabilities that are already `- [x]` in the PRD, unless the user explicitly requests re-implementation.
+- ❌ No "review" or "documentation" tasks unless the PRD's acceptance criteria explicitly require them.
+
+---
+
+## Relationship to PRD Checkboxes
+
+The tasks file and the PRD use **separate checkboxes**:
+
+- **Task checkboxes** (`- [ ]` / `- [x]` in the tasks file) track *execution state* — flip when the task is done.
+- **Capability checkboxes** (`- [ ]` / `- [x]` in the PRD) track *delivery state* — only flip when **every** task whose `covers:` references that capability is complete.
+
+`gspec-implement` is responsible for keeping both in sync. This skill only writes the initial unchecked tasks file.
+
+---
+
+## Output Rules
+
+- **Use plan mode** in Phase 4. Never write the tasks file before the user approves.
+- One tasks file per feature. Co-located with the PRD as `gspec/features/<feature>.tasks.md`.
+- Begin each file with the YAML frontmatter shown above.
+- Preserve existing frontmatter and existing task IDs when regenerating — append new tasks rather than renumbering.
+- If you discover the PRD itself is ambiguous (a capability has no clear acceptance criteria), pause and recommend the user run `gspec-feature` to refine the PRD before continuing. Do not invent acceptance criteria.
+
+---
+
+## Tone & Style
+
+- Decisive — pick an ordering and defend it; don't list options.
+- Tight — every task line earns its place.
+- Honest about dependencies — it's better to be slightly conservative on `[P]` than to claim parallelism that doesn't hold.
+
+---
+
+## Input Feature
+

package/dist/claude/gspec-analyze/SKILL.md

@@ -36,6 +36,7 @@ Read **every** available gspec document in this order:
 6. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
 7. `gspec/research.md` — Competitive analysis and feature proposals
 8. `gspec/features/*.md` — Individual feature requirements and dependencies
+9. `gspec/features/*.tasks.md` — For any feature that has a tasks file, read it alongside the PRD. Tasks files declare a build order and parallelism strategy that must stay consistent with the PRD's capabilities
 
 If fewer than two spec files exist, inform the user that there is nothing to cross-reference and stop.
 
@@ -80,6 +81,14 @@ Systematically compare specs against each other. Look for these categories of di
 - Acceptance criteria in a feature PRD contradict architectural decisions
 - Edge cases handled differently across specs
 
+#### Tasks ↔ PRD Conflicts
+For any feature that has a `gspec/features/<feature>.tasks.md` file, validate the tasks file against its PRD:
+- A task's `covers:` line quotes capability text that does not exist in the PRD (orphan task)
+- A PRD capability is not `covers:`-referenced by any task in the tasks file (orphan capability — every unchecked capability must be covered by at least one task)
+- A task's checkbox is `- [x]` but its covered capability is still `- [ ]` in the PRD, or vice versa (state inconsistency)
+- A task's `deps:` references a task ID that does not exist in the file
+- The tasks file's `feature:` frontmatter slug does not match its filename's feature slug
+
 **Do NOT flag:**
 - Minor wording or style differences that don't change meaning
 - Missing information (gaps are for `gspec-architect` to handle)

package/dist/claude/gspec-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-audit
-description: Audit gspec/ documents against the actual codebase to find drift between what the specs say and what the code does, then walk the user through reconciling each discrepancy — typically by updating specs to match reality. Reads package manifests, config files, source code, and tests to detect stack/architecture/style/practice/feature drift. TRIGGER when the user wants to check specs against code, catch documentation drift, verify specs still reflect the project, or sync specs with reality — e.g. "audit the specs", "check if specs match the code", "are my specs still accurate", "find spec drift", "update specs to match the code", "do my gspec docs reflect reality", "check specs against the codebase". Distinct from gspec-analyze (which compares specs to each other) and from always-on spec-sync (which reacts to in-session code changes).
+description: Audit gspec/ documents against the actual codebase to find drift between what the specs say and what the code does, then walk the user through reconciling each discrepancy — typically by updating specs to match reality. Reads package manifests, config files, source code, and tests to detect stack/architecture/style/practice/feature drift, and detects **orphan capabilities** (coherent features the code implements that no PRD covers) — drafting a new feature PRD in gspec/features/ when the user accepts. TRIGGER when the user wants to check specs against code, catch documentation drift, verify specs still reflect the project, sync specs with reality, or find unspecced features in the codebase — e.g. "audit the specs", "check if specs match the code", "are my specs still accurate", "find spec drift", "update specs to match the code", "do my gspec docs reflect reality", "check specs against the codebase", "find features that aren't spec'd", "what does the code do that we never wrote a PRD for". Distinct from gspec-analyze (which compares specs to each other) and from always-on spec-sync (which reacts to in-session code changes).
 ---
 
 You are a Specification Auditor at a high-performing software company.
@@ -17,11 +17,12 @@ You should:
 - Read and deeply internalize all available gspec documents
 - Inspect the actual codebase — package manifests, source files, tests, configs, stylesheets, routes, data models, and git history where relevant
 - Identify concrete drift — not stylistic differences, but substantive mismatches where the spec and the code disagree on a fact, technology, behavior, or requirement
+- Identify **orphan capabilities** — coherent feature-level capabilities the code implements that no feature PRD describes
 - Present each discrepancy to the user one at a time, clearly showing what each side says
 - Offer resolution options with a recommendation
 - Wait for the user's decision before moving to the next discrepancy
-- Update the affected spec files to reflect each resolution
-- Never modify code as part of this command — audit only updates specs
+- Update the affected spec files to reflect each resolution; for orphan capabilities, draft a new feature PRD in `gspec/features/` when the user accepts
+- Never modify code as part of this command — audit only updates specs and adds new feature PRDs
 
 ---
 
@@ -39,6 +40,7 @@ Read **every** available gspec document in this order:
 6. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
 7. `gspec/research.md` — Competitive analysis and feature proposals (informational only — not audited against code)
 8. `gspec/features/*.md` — Individual feature requirements, priorities, and capability checkboxes
+9. `gspec/features/*.tasks.md` — When a feature has a tasks file, also read it. Tasks files declare a per-task execution checkbox state and `covers:` traceability to PRD capabilities; both are subject to drift checks against the code
 
 If the `gspec/` directory is empty, inform the user that there are no specs to audit and stop.
 
@@ -60,6 +62,11 @@ Build a picture of what the code **actually** is. Read the following, as availab
 - Component library usage — what the UI actually imports and composes
 - Test files — what framework, what coverage areas
 
+**Capability mapping**
+- Build a short mental list of the coherent, user-visible capabilities the code implements — not low-level details, but feature-level units (e.g. "users can export data as CSV", "admin can invite team members", "documents have version history"). A capability typically shows up as a cluster: a route + handler + UI surface + test, or an end-to-end flow.
+- For each capability, note whether it appears in any `gspec/features/*.md` PRD (by feature name, capability checkbox, or acceptance criteria). Capabilities with no PRD coverage are candidates for the **Orphan Capability** category in Phase 3.
+- Be deliberately conservative: a utility helper, an internal admin script, or a piece of plumbing is **not** a capability worth a PRD. Only flag things a user (end user, admin, integrator) would recognize as a feature.
+
 **Version control signals** (use sparingly; git log is authoritative only where the spec makes explicit claims about workflow)
 - `git log --oneline -n 20` for recent commit-message style (only if practices.md makes claims about commit conventions)
 - `git config --local --get-regexp '^branch\.'` / branch listing for branching strategy (only if practices.md makes claims about branching)
@@ -104,6 +111,22 @@ Systematically compare specs against the evidence from Phase 2. Look for these c
 - A feature PRD's acceptance criteria describe behavior that the code explicitly handles differently
 - A feature PRD references a data field, endpoint, or UI element whose implementation has diverged (e.g., PRD says "users can filter by tag", code has filter-by-category)
 
+#### Tasks Drift (only when a tasks file exists for the feature)
+- A task is marked `- [x]` in the tasks file but the code does not implement what the task describes
+- A task is marked `- [ ]` but the code clearly implements it (the checkbox should be updated)
+- A task's `covers:` references capability text the PRD no longer contains (the PRD was edited but the tasks file wasn't refreshed — recommend regenerating via `/gspec-tasks`)
+- A capability is marked `- [x]` in the PRD but one or more of its covering tasks is still `- [ ]` (or vice versa) — flag the inconsistency and recommend the user reconcile state
+
+#### Orphan Capability (code implements a feature that has no PRD)
+- The code ships a coherent, user-visible capability that no `gspec/features/*.md` PRD describes
+- Evidence is typically a cluster — a route + handler + UI surface + test — that adds up to something a user would call a feature
+- An orphan capability is **not** the same as Feature Drift: drift is divergence within a specced feature; an orphan is an entirely unspecced feature
+- Use the **capability mapping** from Phase 2 as your candidate list. Filter out:
+  - Internal utilities, admin scripts, dev tooling, or plumbing the user never sees
+  - Capabilities that *are* covered by an existing PRD even if checkboxes are stale (those are Feature Drift, not orphans)
+  - Capabilities that are partial enough that calling them a "feature" overstates them (note the partial work in the audit summary instead)
+- The recommended resolution is to draft a new feature PRD in `gspec/features/` so the capability is captured, its checkboxes can drive future audits, and `gspec-implement` can extend it correctly
+
 #### Profile Drift (rare; treat conservatively)
 - The profile's stated audience, scope, or value proposition conflicts with what the product actually does in code (e.g., profile says "B2B only" but the code has a consumer signup flow)
 - **Profile drift is usually a signal to update the product, not the spec.** Flag profile drift for user discussion rather than recommending an automatic spec update.
@@ -130,7 +153,7 @@ For each discrepancy, present:
 ```
 ### Drift [N]: [Brief title]
 
-**Category:** [Stack / Architecture / Style / Practice / Feature / Profile]
+**Category:** [Stack / Architecture / Style / Practice / Feature / Orphan Capability / Profile]
 
 **Spec says:**
 - **[File, section]**: [exact quote or precise summary]
@@ -150,6 +173,33 @@ For each discrepancy, present:
 Which would you like?
 ```
 
+For an **Orphan Capability** finding, the presentation differs slightly — there is no "spec says" side, and the resolution options are different:
+
+```
+### Drift [N]: Orphan Capability — [Capability name]
+
+**Category:** Orphan Capability
+
+**Spec says:** *(no PRD covers this capability)*
+
+**Code shows:**
+- **Capability:** [one-sentence description in user-facing terms]
+- **Evidence:** [route(s), handler file(s), UI file(s), test file(s) — concrete paths]
+- **Scope estimate:** [trivial / focused single feature / large enough to need decomposition]
+
+**Why this matters:** Without a PRD, future audits can't track this capability's completeness, `gspec-implement` won't know how to extend it correctly, and the team has no documented intent to compare against.
+
+**Recommended action:** Draft a new feature PRD in `gspec/features/` so the capability is captured.
+
+**Options:**
+1. **Draft a feature PRD now** — Audit will create `gspec/features/<slug>.md` following the gspec-feature schema, marking implemented capabilities as `- [x]` based on the code evidence. *(See Phase 5 for the inline drafting protocol.)*
+2. **Defer to `/gspec-feature` later** — Audit notes this in the code-follow-up summary so you can run `/gspec-feature` on it as a separate, deeper conversation.
+3. **Not actually a feature** — The code is internal plumbing or out of scope; audit drops the finding and won't re-flag it (note this back to the user as a hint they may want to add a comment in the code so future audits know).
+4. **Defer** — Skip for now.
+
+Which would you like?
+```
+
 **Wait for the user's response before proceeding.** The user may:
 - Choose an option by number
 - Propose a different resolution (e.g., partially update the spec)
@@ -169,31 +219,56 @@ When updating specs to match the code:
 - **Do not rewrite sections** — if a one-line change resolves the drift, make a one-line change
 - **Do not add changelog annotations** — git history captures what changed
 
+#### Drafting a new feature PRD for an Orphan Capability
+
+When the user picks option 1 ("Draft a feature PRD now") for an Orphan Capability finding, audit creates a new file in `gspec/features/`. The drafting follows the **same schema and rules as `gspec-feature`** — do not invent a different format. Specifically:
+
+- **Filename:** kebab-case slug derived from the capability name, e.g. `csv-export.md`, `team-invitations.md`. Confirm the slug with the user before writing if it's not obvious.
+- **Frontmatter:** the file must start with
+  ```
+  ---
+  spec-version: v1
+  ---
+  ```
+  followed by the main heading.
+- **Required sections** (in this order, no extras): Overview, Users & Use Cases, Scope, Capabilities, Dependencies, Assumptions & Risks, Success Metrics, Implementation Context.
+- **Capabilities section is the load-bearing one for audit:** list each user-visible capability the code already implements as a checkbox, and mark it `- [x]` when the code clearly satisfies it. Include 2–4 brief acceptance criteria per capability based on what the code actually does (read tests and handlers to extract these). If a capability is only partially implemented, leave it `- [ ]` and note the gap.
+- **Priority:** assign `P0`/`P1`/`P2` based on the capability's apparent centrality. Lean toward `P0` for capabilities the code clearly treats as core; `P1`/`P2` for ancillary ones.
+- **Technology agnosticism:** the PRD must not name specific frameworks, libraries, databases, or services even though you derived it from concrete code. Use generic terms ("data store", "API", "authentication service"). Refer to `gspec-feature`'s technology-agnostic vocabulary list if needed.
+- **Portability:** do not reference project-specific personas, design system details, or stack choices. Use generic role descriptions ("end users", "administrators").
+- **Resolve ambiguity inline before writing:** if the code's intent is unclear (e.g., is this admin-only or for all users? is this experimental or shipped?), ask the user 1–2 targeted questions in chat *before* writing the file. Do not embed unresolved questions in the PRD.
+- **Implementation Context block:** include the standard verbatim note at the bottom (see `gspec-feature`'s section 8).
+- **Decomposition:** if the orphan capability is actually a *cluster* of distinct features (audit's "Scope estimate" was "large enough to need decomposition"), pause and propose a breakdown to the user before writing — same protocol as `gspec-feature` for multi-feature output. Confirm the breakdown, then write one file per feature.
+
+After writing, briefly tell the user what was created (filename + capability list with checkbox states) and continue to the next finding.
+
 ### Phase 6: Final Verification
 
 After all discrepancies have been resolved (or deferred):
 
 1. **Re-read the updated specs** briefly to confirm the edits landed correctly
 2. **Present a summary:**
-   - Total discrepancies found, grouped by category
+   - Total discrepancies found, grouped by category (including Orphan Capability)
    - Number where spec was updated to match code
    - Number where spec was kept as-is (code flagged for follow-up)
+   - Number of new feature PRDs created (with filenames) and capabilities those PRDs cover
    - Number deferred
-   - List of files that were updated
+   - List of files that were updated or created
 3. **Flag code follow-ups**: if the user chose "Keep the spec and fix code" for any finding, list those at the end as a punch list so they don't get lost. Do not modify code — this is a reference list for the user or a follow-up implement run.
+4. **Flag orphan-capability hand-offs**: if the user picked "Defer to `/gspec-feature` later" for any orphan capability, list the capability and the evidence (file paths) so a follow-up `/gspec-feature` run has everything it needs.
 
 ---
 
 ## Rules
 
 - **Never modify code.** This command only reads code and updates specs. If a drift suggests the code should change, list it in the code-follow-up summary and let the user decide whether to run `/gspec-implement` or fix it themselves.
-- **Never create new spec files.** Audit only updates existing gspec documents.
-- **Never silently update specs.** Every change requires user approval via the drift resolution flow.
+- **Never create new foundation specs.** Audit must not create `profile.md`, `stack.md`, `style.md`/`style.html`, `practices.md`, `architecture.md`, or `research.md`. The only new files audit may create are feature PRDs in `gspec/features/`, and only as the explicit resolution to an Orphan Capability finding.
+- **Never silently update specs.** Every change — including creating a new feature PRD — requires user approval via the drift resolution flow.
 - **One discrepancy at a time.** Do not batch resolutions — the user decides each one individually.
 - **Be precise about the evidence.** Quote the spec, cite the file and line range where the code contradicts it. Vague drift reports ("the architecture is out of date") are not actionable.
-- **Prioritize by impact.** Present drifts that would cause incorrect implementation or confused future work first. Cosmetic drift comes last.
+- **Prioritize by impact.** Present drifts that would cause incorrect implementation or confused future work first. Cosmetic drift comes last. Orphan Capabilities sit alongside Feature Drift in priority — both directly affect what `gspec-implement` will produce next.
 - **Treat the profile conservatively.** Profile drift usually reflects an intentional pivot and deserves a human decision, not an automatic spec update.
-- **Respect the scope hint.** If the user passes a hint like "audit the stack only", stick to it.
+- **Respect the scope hint.** If the user passes a hint like "audit the stack only", stick to it. A scope hint of "audit features" includes Orphan Capability detection; a hint that excludes features (e.g. "audit the stack only") suppresses it.
 
 ---
 

package/dist/claude/gspec-feature/SKILL.md

@@ -191,6 +191,16 @@ When generating multiple features from a large request:
 
 ---
 
+## After Writing the PRD
+
+After saving each PRD, end your response with a brief next-step pointer:
+
+> *For larger features, run `/gspec-tasks <feature-slug>` to produce an ordered task plan with explicit dependencies and parallel-execution markers before running `/gspec-implement`. Trivial features can skip straight to `/gspec-implement`.*
+
+This is a one-line nudge, not a prompt — do not generate the tasks file from this skill, and do not block the user on it.
+
+---
+
 ## Tone & Style
 
 - Clear, neutral, product-led

package/dist/claude/gspec-implement/SKILL.md

@@ -26,6 +26,7 @@ Before writing any code, read all available gspec documents in this order:
 1. `gspec/profile.md` — Understand what the product is and who it's for
 2. `gspec/features/*.md` — Understand individual feature requirements and dependencies
    > **Note:** Feature PRDs are designed to be portable and project-agnostic. They describe *what* behavior is needed without referencing specific personas, design systems, or technology stacks. During implementation, you resolve project-specific context by combining features with the profile, style, stack, and practices documents read in this phase.
+3. `gspec/features/*.tasks.md` — For any feature in scope, also read its tasks file if one exists. Tasks files are produced by `gspec-tasks` and contain an ordered, dependency-aware breakdown of the PRD's capabilities into concrete implementation tasks with `[P]` parallel markers and explicit `deps:` lines. **When a tasks file exists, it is the authoritative build order for that feature.** When it doesn't exist, fall back to the PRD's checkbox capabilities directly.
 4. `gspec/stack.md` — Understand the technology choices
 5. `gspec/style.md` **or** `gspec/style.html` — Understand the visual design language. The style guide may be in either format; read whichever exists (or both, if both are present — the HTML file contains the renderable token definitions and visual examples, the Markdown file contains prose rationale)
 6. `gspec/design/**` — If this folder exists, read every mockup in it. Supported formats include HTML pages, SVG files, and image files (PNG, JPG, WEBP). These are visual mockups (typically produced by external design tools like Figma, v0, Framer AI, etc.) that show layout, composition, and visual intent for specific screens or flows. **Treat them as authoritative visual guidance** — when building UI for a feature, look for relevant mockups in `gspec/design/` and match their layout, spacing, and hierarchy within the constraints of the style guide
@@ -46,10 +47,16 @@ This command is designed to be **run multiple times** as features are added or e
 - **`- [ ]`** (unchecked) = capability not yet implemented — include in this run's scope
 - **No checkbox prefix** = treat as not yet implemented (backwards compatible with older PRDs)
 
+**When a feature has a tasks file** (`gspec/features/<feature>.tasks.md`), also assess task-level state:
+
+- A task with `- [x]` is complete; skip unless user requests re-implementation
+- A task with `- [ ]` is pending and goes into this run's scope
+- A capability is considered fully delivered only when **every** task whose `covers:` references it is `- [x]`. A PRD capability checkbox should never be checked while one of its covering tasks is still unchecked, and vice versa — flag any such inconsistency to the user
+
 For each feature PRD, build an implementation status summary:
 
-> **Feature: User Authentication** — 4/7 capabilities implemented (all P0 done, 3 P1/P2 remaining)
-> **Feature: Dashboard** — 0/5 capabilities implemented (new feature)
+> **Feature: User Authentication** — 4/7 capabilities implemented (all P0 done, 3 P1/P2 remaining); tasks file shows 8/14 tasks done
+> **Feature: Dashboard** — 0/5 capabilities implemented (new feature, no tasks file)
 
 Present this summary to the user so they understand the starting point. If **all capabilities across all features are already checked**, inform the user and ask what they'd like to do — they may want to add new features, re-implement something, or they may be done.
 
@@ -57,14 +64,15 @@ Present this summary to the user so they understand the starting point. If **all
 
 **Enter plan mode** and create a concrete, phased implementation plan.
 
-1. **Survey the full scope** — Review all feature PRDs and identify every unchecked capability that is in scope for this run
-2. **Organize into implementation phases** — Group related capabilities into logical phases that can be built and verified independently. Each phase should:
+1. **Survey the full scope** — Review all feature PRDs and identify every unchecked capability that is in scope for this run. For features that have a tasks file, the unchecked tasks (not just capabilities) are the actual unit of work.
+2. **Organize into implementation phases** — Group related work into logical phases that can be built and verified independently. Each phase should:
    - Have a clear name and objective (e.g., "Phase 1: Core Data Models & API", "Phase 2: Authentication Flow")
-   - List the specific capabilities (with feature PRD references) it will implement
+   - List the specific capabilities (with feature PRD references) it will implement, **and the specific tasks (by ID, e.g. T1, T2, T7) when a tasks file exists**
    - Identify files to create or modify
    - Note dependencies on prior phases
    - Include an estimated scope (small/medium/large)
-3. **Account for every unchecked capability** — The plan must explicitly place every unchecked capability from in-scope feature PRDs into a phase **or** list it under a "Proposed to Defer" section with a reason. No unchecked capability may be silently omitted from the plan. The user reviews and approves what gets deferred at plan approval time.
+   - **When tasks files exist for in-scope features**, respect the `deps:` ordering they declare (no task may be scheduled before its declared deps), and note `[P]`-marked tasks as parallel-safe within a phase so the phase can fan-out work where appropriate
+3. **Account for every unchecked unit of work** — The plan must explicitly place every unchecked capability (or every unchecked task, when a tasks file exists) from in-scope feature PRDs into a phase **or** list it under a "Proposed to Defer" section with a reason. Nothing unchecked may be silently omitted from the plan. The user reviews and approves what gets deferred at plan approval time.
 4. **Define test expectations per phase** — For each phase, specify what tests will be run to verify correctness before moving on (unit tests, integration tests, build verification, etc.)
 5. **Present the plan** — Show the user the full phased plan with clear phase boundaries and ask for approval
 
@@ -113,7 +121,10 @@ Present a brief scaffold summary to the user before proceeding to feature implem
    c. **Follow the style** — Apply the design system, tokens, and icon library from `gspec/style.md` or `gspec/style.html` (whichever exists). The style guide is the single authority for icon library choices. Component libraries (e.g., shadcn/ui) are defined in `gspec/stack.md`.
    d. **Match the mockups** — For UI work, if `gspec/design/` contains mockups relevant to the screen or flow you are building, match their layout, spacing, and visual hierarchy. Resolve any conflict between a mockup and the style guide in favor of the style guide's tokens and semantics, then adjust the layout to remain faithful to the mockup's intent. If a mockup shows a visual pattern that the style guide doesn't cover, pause and ask the user whether to extend the style guide or deviate from the mockup.
    e. **Satisfy the requirements** — Trace each piece of code back to a functional requirement in the feature PRD (if available) or to the user's stated goals and the approved implementation plan
-3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `spec-version` YAML frontmatter. If a file lacks frontmatter, add `---\nspec-version: v1\n---` at the top.
+3. **Mark progress as you go** — Update checkboxes incrementally, never in a batch at the end. This ensures that if the session is interrupted, progress is not lost.
+   - **Tasks (when a tasks file exists)**: as soon as a task is complete and verified, flip its checkbox in `gspec/features/<feature>.tasks.md` from `- [ ]` to `- [x]`.
+   - **Capabilities**: flip a PRD capability checkbox from `- [ ]` to `- [x]` only after every task whose `covers:` references it is checked. If no tasks file exists for that feature, flip the capability checkbox immediately on completion (the original behavior). If a capability line did not have a checkbox prefix, add one as `- [x]`.
+   - When updating gspec files, preserve existing `spec-version` YAML frontmatter. If a file lacks frontmatter, add `---\nspec-version: v1\n---` at the top.
 4. **Run tests** — Execute the tests defined for this phase (and any existing tests to catch regressions). Fix any failures before proceeding.
 6. **Surface new gaps** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 7. **Pause and report** — After completing the phase and confirming tests pass, present a phase completion summary to the user:
@@ -134,7 +145,7 @@ After implementation:
 2. **Review against acceptance criteria** — For each capability in the feature PRDs, check that every acceptance criterion listed under it is satisfied. These sub-listed conditions are the definition of "done" for each capability. If any criterion is not met, the capability should not be marked `[x]`.
 3. **Check the Definition of Done** from `gspec/practices.md`
 4. **Verify no unapproved deferrals** — Compare the final implementation against the approved plan. If any capability that was assigned to a phase was not implemented, **do not silently leave it unchecked**. Flag it to the user, explain why it wasn't completed, and get explicit approval before marking it as deferred. Only capabilities the user approved for deferral during planning (or explicitly approves now) may remain unchecked.
-5. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were approved for deferral by the user. Present a final status summary:
+5. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were approved for deferral by the user. **For features with tasks files**, also confirm task↔capability consistency: every checked capability has all its covering tasks checked, and every unchecked capability has at least one unchecked covering task. Present a final status summary:
 
 > **Implementation Summary:**
 > - Feature X: 7/7 capabilities implemented (complete)

package/dist/claude/gspec-tasks/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: gspec-tasks
+description: Decompose a feature PRD in gspec/features/ into an ordered, dependency-aware task plan with parallel-execution markers, written to gspec/features/<feature>.tasks.md. TRIGGER when the user wants to plan execution order, break a feature into tasks, identify what can run in parallel, sequence implementation work, or produce a build plan from a PRD — e.g. "break this feature into tasks", "what order should I build this in", "plan the implementation order", "make a task list for X", "what can run in parallel", "decompose feature Y", "ordered task plan". Run this AFTER gspec-feature and BEFORE gspec-implement when a feature is large or has non-obvious ordering. Prefer this skill over ad-hoc task lists.
+---
+
+You are a Senior Engineering Lead at a high-performing software company.
+
+Your task is to take a **feature PRD** from `gspec/features/` and decompose it into an **ordered, dependency-aware task plan** with parallel-execution markers. The output is a separate sibling file at `gspec/features/<feature>.tasks.md` that `gspec-implement` consumes during its planning phase.
+
+The PRD answers *what* and *why*. The tasks file answers *how* and *in what order*.
+
+## When to Run This Skill
+
+Run after `gspec-feature` and before `gspec-implement` when:
+
+- The feature is large enough that build order matters (more than 3-4 capabilities, or non-trivial cross-capability dependencies)
+- Work could be parallelized and you want that surfaced explicitly
+- You want a reviewable execution plan before code is written
+
+Skip this skill for trivial features — `gspec-implement`'s checkbox-driven planning is sufficient there.
+
+---
+
+## Inputs
+
+- **Required**: a feature PRD at `gspec/features/<feature>.md` (the user names the feature; if ambiguous, ask)
+- **Supporting context** (read but don't quote): `gspec/architecture.md`, `gspec/stack.md`. Use these only to inform task granularity and ordering — never to embed project-specific technology choices into the tasks file
+- **Existing tasks file** (if any) at `gspec/features/<feature>.tasks.md` — if present and non-empty, treat it as authoritative state and refuse to overwrite without explicit user confirmation
+
+---
+
+## Workflow
+
+### Phase 1: Discovery
+
+1. Read the target feature PRD in full. Extract every capability and its acceptance criteria.
+2. Read `gspec/architecture.md` and `gspec/stack.md` for ordering signals (e.g., schema must exist before API; API before UI).
+3. If a tasks file already exists for this feature, read it. Decide whether the user wants to (a) regenerate from scratch, (b) add tasks for newly added capabilities only, or (c) abort. Ask before proceeding.
+
+### Phase 2: Decompose
+
+For each unchecked PRD capability:
+
+1. Propose **1–N tasks** that, taken together, satisfy the capability's acceptance criteria.
+2. Tasks should be small enough that a single implementation pass can complete and verify each one (typically 1-3 files, 1-3 acceptance criteria worth of work).
+3. Carry the capability's priority (`P0`/`P1`/`P2`) onto each task.
+4. Record the **`covers:` line** verbatim — quote the capability text from the PRD so the trace is unambiguous. A single task may cover multiple capabilities; a single capability may be covered by multiple tasks.
+
+### Phase 3: Order & Mark Parallelism
+
+1. Identify dependencies. A task depends on another when:
+   - It writes files the other reads or extends
+   - It uses APIs/types/schemas the other introduces
+   - It tests behavior the other implements
+2. Emit a **topological ordering**: list tasks in an order where every `deps:` reference points strictly backwards.
+3. Mark a task `[P]` (parallel-safe) only when it satisfies **both** conditions:
+   - Its `deps:` are all already complete (i.e., earlier in the list and not currently in flight beside it)
+   - It does not write to the same files as another `[P]`-marked sibling at the same level
+   When in doubt, leave `[P]` off. False parallelism causes more pain than missed parallelism.
+
+### Phase 4: Plan-Mode Confirmation
+
+Enter plan mode and present the proposed tasks file content to the user. Show:
+
+- Total task count and how many `[P]`-marked
+- The full proposed file body
+- Any capabilities you could not decompose (explain why)
+- Any cross-feature dependencies you noticed (the user may want to address them in another feature's tasks file)
+
+Wait for approval. The user may edit individual tasks, change ordering, drop or add `[P]` markers, or split/merge tasks.
+
+### Phase 5: Write
+
+After approval, write `gspec/features/<feature>.tasks.md`. Never overwrite a non-empty existing file without explicit user confirmation in Phase 1.
+
+When writing, preserve any existing `spec-version` frontmatter from the prior tasks file. New files use `spec-version: v1`.
+
+---
+
+## Output Format
+
+The tasks file has YAML frontmatter and a single `## Tasks` section.
+
+```markdown
+---
+spec-version: v1
+feature: <feature-slug>
+---
+
+# Tasks: <Feature Name>
+
+## Tasks
+
+- [ ] **T1** [P] **P0** scaffold the Astro page route at `src/pages/index.astro`
+  - deps: —
+  - covers: "Page displays a clear tagline and one-line value proposition that communicates what gspec does"
+- [ ] **T2** **P0** wire CTA copy-to-clipboard interaction
+  - deps: T1
+  - covers: "Page displays a prominent install CTA with the install command"
+- [ ] **T3** [P] **P1** add the workflow diagram component
+  - deps: T1
+  - covers: "Page explains the gspec workflow in three or fewer steps"
+```
+
+### Field rules
+
+- **ID**: `T<n>`, monotonically increasing from `T1`. IDs are stable — never renumber existing tasks during a regenerate; append new ones with the next free number.
+- **`[P]`**: optional parallel marker. Place between the ID and the priority.
+- **Priority**: `P0`, `P1`, or `P2`, matching the source capability.
+- **Description**: one short imperative sentence. Concrete files or modules where useful, but no implementation code.
+- **`deps:`**: comma-separated task IDs. Use `—` (em dash) when there are no dependencies.
+- **`covers:`**: capability text from the PRD, quoted. For tasks covering multiple capabilities, separate quoted strings with `; `.
+
+### What NOT to write
+
+- ❌ No code blocks or pseudocode — that belongs in the implementation step.
+- ❌ No technology choices not already in `stack.md` or `architecture.md`.
+- ❌ No timeline estimates (hours, days, sprints) — see `gspec-feature` for the same rule.
+- ❌ No tasks for capabilities that are already `- [x]` in the PRD, unless the user explicitly requests re-implementation.
+- ❌ No "review" or "documentation" tasks unless the PRD's acceptance criteria explicitly require them.
+
+---
+
+## Relationship to PRD Checkboxes
+
+The tasks file and the PRD use **separate checkboxes**:
+
+- **Task checkboxes** (`- [ ]` / `- [x]` in the tasks file) track *execution state* — flip when the task is done.
+- **Capability checkboxes** (`- [ ]` / `- [x]` in the PRD) track *delivery state* — only flip when **every** task whose `covers:` references that capability is complete.
+
+`gspec-implement` is responsible for keeping both in sync. This skill only writes the initial unchecked tasks file.
+
+---
+
+## Output Rules
+
+- **Use plan mode** in Phase 4. Never write the tasks file before the user approves.
+- One tasks file per feature. Co-located with the PRD as `gspec/features/<feature>.tasks.md`.
+- Begin each file with the YAML frontmatter shown above.
+- Preserve existing frontmatter and existing task IDs when regenerating — append new tasks rather than renumbering.
+- If you discover the PRD itself is ambiguous (a capability has no clear acceptance criteria), pause and recommend the user run `gspec-feature` to refine the PRD before continuing. Do not invent acceptance criteria.
+
+---
+
+## Tone & Style
+
+- Decisive — pick an ordering and defend it; don't list options.
+- Tight — every task line earns its place.
+- Honest about dependencies — it's better to be slightly conservative on `[P]` than to claim parallelism that doesn't hold.
+
+---
+
+## Input Feature
+
+$ARGUMENTS

package/dist/codex/gspec-analyze/SKILL.md

@@ -36,6 +36,7 @@ Read **every** available gspec document in this order:
 6. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
 7. `gspec/research.md` — Competitive analysis and feature proposals
 8. `gspec/features/*.md` — Individual feature requirements and dependencies
+9. `gspec/features/*.tasks.md` — For any feature that has a tasks file, read it alongside the PRD. Tasks files declare a build order and parallelism strategy that must stay consistent with the PRD's capabilities
 
 If fewer than two spec files exist, inform the user that there is nothing to cross-reference and stop.
 
@@ -80,6 +81,14 @@ Systematically compare specs against each other. Look for these categories of di
 - Acceptance criteria in a feature PRD contradict architectural decisions
 - Edge cases handled differently across specs
 
+#### Tasks ↔ PRD Conflicts
+For any feature that has a `gspec/features/<feature>.tasks.md` file, validate the tasks file against its PRD:
+- A task's `covers:` line quotes capability text that does not exist in the PRD (orphan task)
+- A PRD capability is not `covers:`-referenced by any task in the tasks file (orphan capability — every unchecked capability must be covered by at least one task)
+- A task's checkbox is `- [x]` but its covered capability is still `- [ ]` in the PRD, or vice versa (state inconsistency)
+- A task's `deps:` references a task ID that does not exist in the file
+- The tasks file's `feature:` frontmatter slug does not match its filename's feature slug
+
 **Do NOT flag:**
 - Minor wording or style differences that don't change meaning
 - Missing information (gaps are for `gspec-architect` to handle)