gspec 1.17.0 → 1.18.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`, `/gspec-tasks`, `/gspec-analyze`, and `/gspec-audit` — 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-plan`, `/gspec-analyze`, and `/gspec-audit` — add structure and rigor when the scope or complexity warrants it.
 
 ```mermaid
 flowchart LR
@@ -43,7 +43,7 @@ flowchart LR
     technical blueprint"]
 
     Plan["5. Plan
-    ordered tasks"]
+    ordered plan"]
 
     Analyze["6. Analyze & Audit
     reconcile specs
@@ -116,18 +116,18 @@ Use `/gspec-architect` when your feature involves significant technical complexi
 
 | 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 |
+| `/gspec-plan` | Engineering Lead | A sibling `gspec/features/<feature>.plan.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.
+Use `/gspec-plan` 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 every in-scope feature has a plan file, `/gspec-implement` skips its own plan-mode step and executes the plan file directly (the plan was already approved during `/gspec-plan`). Trivial features can skip this step and go straight to `/gspec-implement`, which falls back to PRD-checkbox-driven planning with its own plan-mode approval.
 
 **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 against **each other**, identifies contradictions, and walks you through reconciling each one |
+| `/gspec-analyze` | Specification Analyst | Cross-references specs against **each other**, identifies contradictions, and walks you through reconciling each one. Optionally takes a feature slug to scope to one PRD and add an ambiguity sweep against the document itself |
 | `/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 spec-to-spec conflicts before `/gspec-implement` sees them — for example, if the stack says PostgreSQL but the architecture references MongoDB. Pass a feature slug (`/gspec-analyze user-authentication`) to scope the run to one PRD and surface ambiguity inside it — missing acceptance criteria, vague verbs, undefined nouns, implicit state assumptions, missing edge cases, and unmeasurable success metrics. Especially useful on aged or imported PRDs that may have accumulated unstated assumptions.
 
 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.
 
@@ -135,7 +135,7 @@ Use `/gspec-audit` periodically — before a major release, after a long sprint,
 
 | Command | Role | What it does |
 |---|---|---|
-| `/gspec-implement` | Senior Engineer | Reads all specs (including any `*.tasks.md` files), plans the build order, and implements |
+| `/gspec-implement` | Senior Engineer | Reads all specs (including any `*.plan.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.
 

package/bin/emitters.js

@@ -0,0 +1,104 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// Placeholder pattern used in generic command files
+export const PLACEHOLDER_RE = /<<<\w+>>>/g;
+
+export function buildFrontmatter(fields) {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(fields)) {
+    lines.push(`${key}: ${value}`);
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+
+// Platform target definitions: how to emit a skill file for each AI tool.
+// Used by both `scripts/build.js` (writing to dist/) and `bin/gspec.js`
+// (writing user-installed extensions directly to a project's install dir).
+export const TARGETS = {
+  claude: {
+    label: 'Claude Code',
+    distSubdir: 'claude',
+    installDir: '.claude/skills',
+    layout: 'directory',
+    // .claude/skills/<name>/SKILL.md
+    async emit(outDir, content, meta) {
+      const frontmatter = buildFrontmatter({
+        name: meta.name,
+        description: meta.description,
+      });
+      const body = content.replace(PLACEHOLDER_RE, '$ARGUMENTS');
+      const skillDir = join(outDir, meta.name);
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(join(skillDir, 'SKILL.md'), frontmatter + '\n\n' + body, 'utf-8');
+    },
+  },
+  cursor: {
+    label: 'Cursor',
+    distSubdir: 'cursor',
+    installDir: '.cursor/commands',
+    layout: 'flat',
+    // .cursor/commands/<name>.mdc (flat file)
+    async emit(outDir, content, meta) {
+      const frontmatter = buildFrontmatter({
+        description: meta.description,
+      });
+      // Cursor has no $ARGUMENTS convention; strip the placeholder lines
+      const body = content.replace(/^.*<<<\w+>>>.*$\n?/gm, '');
+      await mkdir(outDir, { recursive: true });
+      await writeFile(join(outDir, `${meta.name}.mdc`), frontmatter + '\n\n' + body, 'utf-8');
+    },
+  },
+  antigravity: {
+    label: 'Antigravity',
+    distSubdir: 'antigravity',
+    installDir: '.agent/skills',
+    layout: 'directory',
+    // .agent/skills/<name>/SKILL.md
+    async emit(outDir, content, meta) {
+      const frontmatter = buildFrontmatter({
+        name: meta.name,
+        description: meta.description,
+      });
+      const body = content.replace(/^.*<<<\w+>>>.*$\n?/gm, '');
+      const skillDir = join(outDir, meta.name);
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(join(skillDir, 'SKILL.md'), frontmatter + '\n\n' + body, 'utf-8');
+    },
+  },
+  codex: {
+    label: 'Codex',
+    distSubdir: 'codex',
+    installDir: '.agents/skills',
+    layout: 'directory',
+    // .agents/skills/<name>/SKILL.md
+    async emit(outDir, content, meta) {
+      const frontmatter = buildFrontmatter({
+        name: meta.name,
+        description: meta.description,
+      });
+      const body = content.replace(/^.*<<<\w+>>>.*$\n?/gm, '');
+      const skillDir = join(outDir, meta.name);
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(join(skillDir, 'SKILL.md'), frontmatter + '\n\n' + body, 'utf-8');
+    },
+  },
+  opencode: {
+    label: 'Open Code',
+    distSubdir: 'opencode',
+    installDir: '.opencode/skills',
+    layout: 'directory',
+    // .opencode/skills/<name>/SKILL.md
+    async emit(outDir, content, meta) {
+      const frontmatter = buildFrontmatter({
+        name: meta.name,
+        description: meta.description,
+      });
+      const body = content.replace(/^.*<<<\w+>>>.*$\n?/gm, '');
+      const skillDir = join(outDir, meta.name);
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(join(skillDir, 'SKILL.md'), frontmatter + '\n\n' + body, 'utf-8');
+    },
+  },
+};

package/bin/gspec.js

@@ -7,7 +7,7 @@ import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import chalk from 'chalk';
-import { TARGETS as EMITTER_TARGETS } from '../scripts/emitters.js';
+import { TARGETS as EMITTER_TARGETS } from './emitters.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = join(__dirname, '..', 'dist');
@@ -40,7 +40,7 @@ const TARGETS = Object.fromEntries(
 
 // Names emitted by core gspec; user extensions cannot collide with these.
 const BUILTIN_SKILL_NAMES = new Set([
-  'gspec-profile', 'gspec-feature', 'gspec-tasks', 'gspec-style',
+  'gspec-profile', 'gspec-feature', 'gspec-plan', 'gspec-style',
   'gspec-stack', 'gspec-practices', 'gspec-architect', 'gspec-analyze',
   'gspec-audit', 'gspec-research', 'gspec-implement', 'gspec-migrate',
 ]);

package/commands/gspec.analyze.md

@@ -1,11 +1,25 @@
 You are a Specification Analyst at a high-performing software company.
 
-Your task is to read all existing gspec specification documents, identify discrepancies and contradictions between them, and guide the user through reconciling each one. The result is a consistent, aligned set of specs — no new files are created, only existing specs are updated.
+Your task is to read existing gspec specification documents, identify discrepancies and contradictions between them, and guide the user through reconciling each one. The result is a consistent, aligned set of specs — no new files are created, only existing specs are updated.
 
 This command is designed to be run **after** `gspec-architect` (or at any point when multiple specs exist) and **before** `gspec-implement`, to ensure the implementing agent receives a coherent, conflict-free set of instructions.
 
 > **Analyze vs. audit.** `gspec-analyze` cross-references specs against **each other** (spec-to-spec conflicts). `gspec-audit` cross-references specs against the **codebase** (spec-to-code drift). If the user's intent is "do my docs still reflect what the code does?", route to `gspec-audit` instead.
 
+## Scope
+
+This skill has two modes:
+
+- **All-specs mode (default)** — runs when no argument is passed. Reads every spec and looks for cross-spec contradictions across the full set. Use this before `gspec-implement` on a multi-spec project.
+- **Scoped mode** — runs when the user passes a feature slug (matching a file in `gspec/features/`). Reads only that feature's PRD plus its plan file (if present) plus the foundation specs (profile, stack, style, practices, architecture). Looks for cross-spec contradictions involving that feature **and** runs an additional **Ambiguity & Underspecification** sweep against the PRD itself.
+
+To resolve the argument:
+
+1. Read what the user passed via the input below. Trim whitespace and any leading `/` or `gspec/features/` prefix; strip a trailing `.md` if present.
+2. If the resolved slug matches a file at `gspec/features/<slug>.md`, switch to scoped mode and remember the slug.
+3. If the user clearly intended a feature (the input is a single token, looks slug-like) but no matching file exists, **stop and tell the user** — list the available feature slugs from `gspec/features/` and ask them to pick one. Do not silently fall back to all-specs mode in this case.
+4. If the input is empty, run in all-specs mode.
+
 You should:
 - Read and deeply cross-reference all available gspec documents
 - Identify concrete discrepancies — not style differences or minor wording variations, but substantive contradictions where two specs disagree on a fact, technology, behavior, or requirement
@@ -19,9 +33,11 @@ You should:
 
 ## Workflow
 
-### Phase 1: Read All Specs
+### Phase 1: Read the Specs in Scope
+
+Branch on the mode resolved above:
 
-Read **every** available gspec document in this order:
+**All-specs mode** — Read **every** available gspec document in this order:
 
 1. `gspec/profile.md` — Product identity, scope, audience, and positioning
 2. `gspec/stack.md` — Technology choices, frameworks, infrastructure
@@ -31,10 +47,19 @@ 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
+9. `gspec/features/*.plan.md` — For any feature that has a plan file, read it alongside the PRD. Plan 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.
 
+**Scoped mode** — Read just enough to evaluate the named feature in context:
+
+1. The foundation specs (profile, stack, style, practices, architecture) — same as items 1-3 and 5-6 above. These provide the environment the feature lives in.
+2. `gspec/features/<slug>.md` — the named feature's PRD. This is the document being scrutinized.
+3. `gspec/features/<slug>.plan.md` — the named feature's plan file, if present.
+4. **Skip** other feature PRDs, other plan files, `research.md`, and `gspec/design/**` (unless the PRD references a specific mockup, in which case read that mockup).
+
+In scoped mode, even when only one of the foundation specs is present, proceed — you still have a target PRD to evaluate against the foundations, and you can also run the ambiguity sweep against the PRD alone.
+
 ---
 
 ### Phase 2: Cross-Reference and Identify Discrepancies
@@ -76,17 +101,40 @@ 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:
+#### Plan ↔ PRD Conflicts
+For any feature that has a `gspec/features/<feature>.plan.md` file, validate the plan 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 PRD capability is not `covers:`-referenced by any task in the plan 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
+- The plan file's `feature:` frontmatter slug does not match its filename's feature slug
+
+#### Ambiguity & Underspecification *(scoped mode only)*
+
+This category runs **only in scoped mode** — it scrutinizes the target feature PRD for gaps and vague language that would make implementation guess. Skip this entirely in all-specs mode (too noisy across many features).
+
+Look for, inside the target PRD:
+
+- **Capabilities missing acceptance criteria** — every capability checkbox should have 2-4 testable conditions sub-listed under it. Bare capabilities are gaps.
+- **Vague verbs without subject/object resolution** — "manage", "handle", "process", "support", "deal with" used without specifying *what* and *under which conditions*.
+- **Undefined nouns referenced as if they exist** — the PRD says "the report" or "the dashboard" but never defines what fields it contains, who can see it, or where it appears.
+- **Implicit assumptions about state** — "the user is signed in", "the workspace is active", "the data is migrated" stated as preconditions only by inference, never declared in Scope or Assumptions.
+- **Missing edge-case coverage** — capabilities that describe a happy path with no mention of failure modes (validation errors, permission denial, empty states, network failure, concurrent edits).
+- **Priority gaps** — capabilities without `P0`/`P1`/`P2` markers, or a set where everything is `P0` (which means nothing is prioritized).
+- **Dependency hand-waving** — Dependencies section says "depends on auth" but doesn't link to a specific PRD or external service, leaving the implementer to guess.
+- **Success metrics that aren't measurable** — "users will love it", "performance will be good" — flag for sharpening into something an implementer can verify.
+
+**Do NOT flag in this category:**
+- Things explicitly listed under "Out of Scope" or "Deferred" — those are intentional gaps, not ambiguity.
+- Items the PRD's "Deferred Decisions" subsection (when present) explicitly defers — same reason. **Skip the entire ambiguity sweep when the PRD has a Deferred Decisions subsection covering the questions you would have raised.**
+- Style or tone preferences ("the copy could be punchier") — not the analyst's call.
+- Anything that overlaps with a foundation spec — if the PRD doesn't say what database to use, that's correct (see Technology Agnosticism in `gspec-feature`); the stack spec answers that.
 
-**Do NOT flag:**
+Present each ambiguity as a question rather than an error: *"Capability 'export user data' lists no acceptance criteria — what formats should be supported, and who can trigger it?"* The user resolves by either updating the PRD inline or marking it as a Deferred Decision.
+
+**Do NOT flag (across all categories):**
 - Minor wording or style differences that don't change meaning
-- Missing information (gaps are for `gspec-architect` to handle)
+- Missing information across other specs (gaps in foundation specs are for `gspec-architect` to handle)
 - Differences in level of detail (one spec being more detailed than another is expected)
 
 ---
@@ -129,6 +177,29 @@ Which would you like?
 
 After the user decides, immediately update the affected spec file(s) to reflect the resolution. Then present the next discrepancy.
 
+For an **Ambiguity** finding (only generated in scoped mode), the presentation differs — there is no second side to quote, so frame it as a question:
+
+```
+### Ambiguity [N]: [Brief title]
+
+**Category:** Ambiguity & Underspecification
+
+**Where:** [File, section, capability or line — be specific]
+
+**What's unclear:** [exact quote or precise paraphrase of the vague text]
+
+**Why this matters:** [1 sentence on what the implementer would have to guess]
+
+**Question:** [the specific thing the user needs to decide]
+
+**Options:**
+1. **Resolve inline** — Update [File, section] with [suggested concrete answer or 2-3 alternatives if you have them]
+2. **Mark as a Deferred Decision** — Add to the PRD's "Deferred Decisions" subsection so future analyze runs skip it
+3. **Defer** — Skip this finding for now without recording it
+
+Which would you like?
+```
+
 ---
 
 ### Phase 4: Apply Resolutions

package/commands/gspec.audit.md

@@ -35,7 +35,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
+9. `gspec/features/*.plan.md` — When a feature has a plan file, also read it. Plan 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.
 
@@ -106,10 +106,10 @@ 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
+#### Plan Drift (only when a plan file exists for the feature)
+- A task is marked `- [x]` in the plan 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 task's `covers:` references capability text the PRD no longer contains (the PRD was edited but the plan file wasn't refreshed — recommend regenerating via `/gspec-plan`)
 - 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)

package/commands/gspec.feature.md

@@ -190,9 +190,9 @@ When generating multiple features from a large request:
 
 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`.*
+> *For larger features, run `/gspec-plan <feature-slug>` to produce an ordered 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.
+This is a one-line nudge, not a prompt — do not generate the plan file from this skill, and do not block the user on it.
 
 ---
 

package/commands/gspec.implement.md

@@ -21,7 +21,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.
+3. `gspec/features/*.plan.md` — For any feature in scope, also read its plan file if one exists. Plan files are produced by `gspec-plan` 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 plan file exists, it is the authoritative, already-approved build order for that feature** — its Phase 4 plan-mode approval in `gspec-plan` is what licenses this skill to skip its own plan-mode step (see Phase 2). 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
@@ -42,7 +42,7 @@ 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:
+**When a feature has a plan file** (`gspec/features/<feature>.plan.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
@@ -50,24 +50,38 @@ This command is designed to be **run multiple times** as features are added or e
 
 For each feature PRD, build an implementation status summary:
 
-> **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)
+> **Feature: User Authentication** — 4/7 capabilities implemented (all P0 done, 3 P1/P2 remaining); plan file shows 8/14 tasks done
+> **Feature: Dashboard** — 0/5 capabilities implemented (new feature, no plan 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.
 
 ### Phase 2: Plan — Define the Build Order
 
+#### Skip plan mode when every in-scope feature has a plan file
+
+Before entering plan mode, check whether **every** in-scope feature has a `gspec/features/<feature>.plan.md` file. If so, **do not enter plan mode** — the plan files are the build order, and they were already approved by the user during `gspec-plan`'s Phase 4. Re-asking for approval here is redundant and slows the user down.
+
+When the skip condition is met:
+
+1. Build the phase breakdown directly from the plan files — group unchecked tasks into phases by their `deps:` ordering, treating `[P]`-marked tasks as parallel-safe siblings within a phase. The phase boundaries should fall at natural dependency frontiers.
+2. **Verify plan-file ↔ PRD coverage before proceeding.** For each in-scope feature, confirm that every unchecked PRD capability has at least one covering task in the plan file. If you find an unchecked capability with no covering task (the PRD was extended after the plan file was written), flag it to the user and ask whether to (a) extend the plan via `/gspec-plan`, (b) implement that capability under an ad-hoc plan-mode pass for just those capabilities, or (c) defer it. Do not silently skip uncovered capabilities.
+3. Present a one-screen build summary — phases, task IDs per phase, parallel groups, and total task count — and start Phase 3 immediately. The summary is informational, not a plan-mode gate; the user can interrupt if they want to redirect, but no explicit approval is required.
+
+When the skip condition is **not** met (at least one in-scope feature has no plan file), run the full plan-mode workflow below for the entire scope. Features that do have plan files still drive their own ordering from their plan files inside the larger plan, but the user reviews the consolidated plan as a whole.
+
+#### Full plan mode (when one or more in-scope features lack a plan file)
+
 **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. For features that have a tasks file, the unchecked tasks (not just capabilities) are the actual unit of work.
+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 plan 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, **and the specific tasks (by ID, e.g. T1, T2, T7) when a tasks file exists**
+   - List the specific capabilities (with feature PRD references) it will implement, **and the specific tasks (by ID, e.g. T1, T2, T7) when a plan file exists**
    - Identify files to create or modify
    - Note dependencies on prior phases
    - Include an estimated scope (small/medium/large)
-   - **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.
+   - **When plan 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 plan 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
 
@@ -117,8 +131,8 @@ Present a brief scaffold summary to the user before proceeding to feature implem
    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 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]`.
+   - **Tasks (when a plan file exists)**: as soon as a task is complete and verified, flip its checkbox in `gspec/features/<feature>.plan.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 plan 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: <<<SPEC_VERSION>>>\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
@@ -140,7 +154,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. **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:
+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 plan 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)
@@ -195,7 +209,7 @@ The user's prompt takes priority for scoping. Use it to determine focus, and ref
 
 ## Output Rules
 
-- **Use plan mode** in Phase 2 to present the implementation plan. Wait for user approval before proceeding.
+- **Use plan mode** in Phase 2 to present the implementation plan, **unless every in-scope feature has a plan file** — in that case, skip plan mode and proceed directly to Phase 3 using the plan files as the authoritative build order. Wait for user approval whenever plan mode runs.
 - **Pause between implementation phases** — After completing each phase in Phase 3, run tests and wait for user confirmation before starting the next phase
 - Reference specific gspec documents and section numbers when discussing requirements
 - Create files following the project structure defined in `gspec/architecture.md` (or `gspec/stack.md` and `gspec/practices.md` if no architecture document exists)

package/commands/gspec.migrate.md

@@ -12,6 +12,7 @@ Scan the `gspec/` directory for all spec files:
 - `gspec/*.md` (profile, stack, style, practices, architecture)
 - `gspec/style.html` (HTML design system, if present — the style guide may be in either Markdown or HTML)
 - `gspec/features/*.md` (individual feature PRDs)
+- `gspec/features/*.plan.md` (plan files; legacy `*.tasks.md` files are also scanned and renamed — see Migration Rules below)
 
 Do **not** migrate files under `gspec/design/` — those are external design mockups (HTML, SVG, PNG, JPG) that are dropped in manually and are not owned by gspec. Leave them untouched.
 
@@ -102,6 +103,12 @@ After migrating all files:
 - If capabilities lack acceptance criteria (current format requires them), add placeholder criteria: "Acceptance criteria to be defined"
 - Preserve priority levels (P0, P1, P2)
 
+**Rename legacy `*.tasks.md` plan files to `*.plan.md`.** Before gspec renamed the `tasks` skill to `plan`, plan files lived at `gspec/features/<feature>.tasks.md`. During migration:
+- For every `gspec/features/*.tasks.md` file, rename it to `gspec/features/<same-slug>.plan.md` (use `git mv` when the project is a git repo so history is preserved; otherwise plain move)
+- Inside the renamed file, update the top-of-file heading from `# Tasks: <Feature Name>` to `# Plan: <Feature Name>` and the section heading from `## Tasks` to `## Plan`. Leave everything else (frontmatter, task IDs, `[P]` markers, `deps:`, `covers:`, checkbox states) unchanged
+- Preserve task IDs verbatim — `T1`, `T2`, etc. remain stable; do not renumber
+- Confirm the rename plan with the user before applying, in the same approval flow as other migrations
+
 **Handle missing sections gracefully.** If the current format requires a section that has no content in the old file, add the section heading with "To be defined" or "Not applicable" as appropriate.
 
 **Frontmatter handling (Markdown files):**

package/commands/{gspec.tasks.md → gspec.plan.md}

@@ -1,8 +1,8 @@
 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.
+Your task is to take a **feature PRD** from `gspec/features/` and decompose it into an **ordered, dependency-aware plan** with parallel-execution markers. The output is a separate sibling file at `gspec/features/<feature>.plan.md` that `gspec-implement` consumes as its build order.
 
-The PRD answers *what* and *why*. The tasks file answers *how* and *in what order*.
+The PRD answers *what* and *why*. The plan file answers *how* and *in what order*.
 
 ## When to Run This Skill
 
@@ -19,8 +19,8 @@ Skip this skill for trivial features — `gspec-implement`'s checkbox-driven pla
 ## 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
+- **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 plan file
+- **Existing plan file** (if any) at `gspec/features/<feature>.plan.md` — if present and non-empty, treat it as authoritative state and refuse to overwrite without explicit user confirmation
 
 ---
 
@@ -30,7 +30,7 @@ Skip this skill for trivial features — `gspec-implement`'s checkbox-driven pla
 
 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.
+3. If a plan 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
 
@@ -55,26 +55,28 @@ For each unchecked PRD capability:
 
 ### Phase 4: Plan-Mode Confirmation
 
-Enter plan mode and present the proposed tasks file content to the user. Show:
+Enter plan mode and present the proposed plan 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)
+- Any cross-feature dependencies you noticed (the user may want to address them in another feature's plan file)
 
 Wait for approval. The user may edit individual tasks, change ordering, drop or add `[P]` markers, or split/merge tasks.
 
+The user's approval here is what lets `gspec-implement` skip its own plan-mode step when it later consumes this file. Be deliberate — the plan you write here is the build order.
+
 ### 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.
+After approval, write `gspec/features/<feature>.plan.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: <<<SPEC_VERSION>>>`.
+When writing, preserve any existing `spec-version` frontmatter from the prior plan file. New files use `spec-version: <<<SPEC_VERSION>>>`.
 
 ---
 
 ## Output Format
 
-The tasks file has YAML frontmatter and a single `## Tasks` section.
+The plan file has YAML frontmatter and a single `## Plan` section.
 
 ```markdown
 ---
@@ -82,9 +84,9 @@ spec-version: <<<SPEC_VERSION>>>
 feature: <feature-slug>
 ---
 
-# Tasks: <Feature Name>
+# Plan: <Feature Name>
 
-## Tasks
+## Plan
 
 - [ ] **T1** [P] **P0** scaffold the Astro page route at `src/pages/index.astro`
   - deps: —
@@ -118,19 +120,19 @@ feature: <feature-slug>
 
 ## Relationship to PRD Checkboxes
 
-The tasks file and the PRD use **separate checkboxes**:
+The plan file and the PRD use **separate checkboxes**:
 
-- **Task checkboxes** (`- [ ]` / `- [x]` in the tasks file) track *execution state* — flip when the task is done.
+- **Task checkboxes** (`- [ ]` / `- [x]` in the plan 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.
+`gspec-implement` is responsible for keeping both in sync. This skill only writes the initial unchecked plan 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`.
+- **Use plan mode** in Phase 4. Never write the plan file before the user approves.
+- One plan file per feature. Co-located with the PRD as `gspec/features/<feature>.plan.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.