gspec 1.16.0 → 1.17.0

package/README.md

@@ -25,7 +25,7 @@ These documents become the shared context for all subsequent AI interactions. Wh
 
 The only commands you *need* are the four fundamentals and `/gspec-implement`. Everything else exists to help when your project calls for it.
 
-The fundamentals give your AI tool enough context to build well — it knows what the product is, how it should look, what technologies to use, and what engineering standards to follow. From there, `/gspec-implement` can take a plain-language description and start building. The remaining commands — `/gspec-research`, `/gspec-feature`, `/gspec-architect`, `/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-tasks`, `/gspec-analyze`, and `/gspec-audit` — add structure and rigor when the scope or complexity warrants it.
 
 ```mermaid
 flowchart LR
@@ -42,11 +42,14 @@ flowchart LR
     Architect["4. Architect
     technical blueprint"]
 
-    Analyze["5. Analyze & Audit
+    Plan["5. Plan
+    ordered tasks"]
+
+    Analyze["6. Analyze & Audit
     reconcile specs
     check specs vs code"]
 
-    Build["6. Build
+    Build["7. Build
     implement"]
 
     Define --> Research
@@ -55,9 +58,12 @@ flowchart LR
     Research --> Specify
     Research --> Build
     Specify --> Architect
+    Specify --> Plan
     Specify --> Build
+    Architect --> Plan
     Architect --> Analyze
     Architect --> Build
+    Plan --> Build
     Analyze --> Build
     Build --> Define
 
@@ -65,6 +71,7 @@ flowchart LR
     style Research fill:#a855f7,color:#fff,stroke:none
     style Specify fill:#f59e0b,color:#fff,stroke:none
     style Architect fill:#f59e0b,color:#fff,stroke:none
+    style Plan fill:#f59e0b,color:#fff,stroke:none
     style Analyze fill:#f59e0b,color:#fff,stroke:none
     style Build fill:#22c55e,color:#fff,stroke:none
 ```
@@ -105,7 +112,15 @@ Use `/gspec-feature` when you want detailed PRDs with prioritized capabilities a
 
 Use `/gspec-architect` when your feature involves significant technical complexity — new data models, service boundaries, auth flows, or integration points that benefit from upfront design. It also **identifies technical gaps and ambiguities** in your specs and proposes solutions, so that `/gspec-implement` can focus on building rather than making architectural decisions. For straightforward features, `/gspec-implement` can make sound architectural decisions on its own using your `stack` and `practices` specs.
 
-**5. Analyze & Audit** *(optional)* — Reconcile discrepancies before building, and keep specs honest as the codebase evolves.
+**5. Plan** *(optional)* — Decompose a feature PRD into ordered work.
+
+| Command | Role | What it produces |
+|---|---|---|
+| `/gspec-tasks` | Engineering Lead | A sibling `gspec/features/<feature>.tasks.md` file with stable task IDs, explicit `deps:` lines, and `[P]` markers for parallel-safe work |
+
+Use `/gspec-tasks` after `/gspec-feature` (and after `/gspec-architect` when it exists) for any feature large enough that build order matters or that has work which could legitimately run in parallel. The output is what `/gspec-implement` consumes — when a tasks file exists for an in-scope feature, implement plans phases from it, respecting deps and surfacing `[P]`-marked tasks for parallel execution. Trivial features can skip this step and go straight to `/gspec-implement`, which falls back to PRD-checkbox-driven planning.
+
+**6. Analyze & Audit** *(optional)* — Reconcile discrepancies before building, and keep specs honest as the codebase evolves.
 
 | Command | Role | What it does |
 |---|---|---|
@@ -116,11 +131,11 @@ Use `/gspec-analyze` after `/gspec-architect` (or any time multiple specs exist)
 
 Use `/gspec-audit` periodically — before a major release, after a long sprint, or any time you suspect docs have drifted from code. Audit reads package manifests, configs, source files, and test output, then asks you per-finding whether to update the spec to match the code, keep the spec and fix the code separately, or defer. Each finding is presented one at a time with the spec quote and the code evidence side by side. Audit never modifies code.
 
-**6. Build** — Implement with full context.
+**7. Build** — Implement with full context.
 
 | Command | Role | What it does |
 |---|---|---|
-| `/gspec-implement` | Senior Engineer | Reads all specs, plans the build order, and implements |
+| `/gspec-implement` | Senior Engineer | Reads all specs (including any `*.tasks.md` files), plans the build order, and implements |
 
 **Spec Sync** — gspec includes always-on spec sync that automatically keeps your specification documents in sync as the code evolves. This is installed alongside the skills and requires no manual intervention — when code changes affect spec-documented behavior, the sync rules prompt your AI tool to update the relevant gspec files.
 
@@ -182,6 +197,18 @@ Saved specs are organized by type in `~/.gspec/` (profiles, stacks, styles, prac
 gspec restore playbook/my-starter
 ```
 
+## Extensions
+
+Author your own skills and have them auto-installed alongside the built-in `gspec-*` commands in every project. Extensions live in `~/.gspec/extensions/` as Markdown files with `name` and `description` frontmatter and the same shape as anything in `commands/`.
+
+```bash
+gspec extension save ./my-deploy.md   # Install a local skill file as a user extension
+gspec extension list                  # See what's installed
+gspec extension remove my-deploy      # Delete from ~/.gspec/extensions/
+```
+
+When you next run `npx gspec` in a project, the installer copies the built-in skills first, then emits each valid extension into the same per-platform install directory using the same formatting. Extension names that collide with built-in `gspec-*` skills are rejected with an error; malformed or duplicate extensions are skipped with a warning.
+
 ## Output Structure
 
 All specifications live in a `gspec/` directory at your project root:

package/bin/gspec.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
 import { program } from 'commander';
-import { readdir, readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { readdir, readFile, writeFile, mkdir, stat, unlink } from 'node:fs/promises';
 import { join, dirname, basename } from 'node:path';
 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';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = join(__dirname, '..', 'dist');
@@ -28,38 +29,21 @@ const BANNER = `
   ${chalk.white('═════════════════════════════baller.software═══')}
 `;
 
-const TARGETS = {
-  claude: {
-    sourceDir: join(DIST_DIR, 'claude'),
-    installDir: '.claude/skills',
-    label: 'Claude Code',
-    layout: 'directory',
-  },
-  cursor: {
-    sourceDir: join(DIST_DIR, 'cursor'),
-    installDir: '.cursor/commands',
-    label: 'Cursor',
-    layout: 'flat',
-  },
-  antigravity: {
-    sourceDir: join(DIST_DIR, 'antigravity'),
-    installDir: '.agent/skills',
-    label: 'Antigravity',
-    layout: 'directory',
-  },
-  codex: {
-    sourceDir: join(DIST_DIR, 'codex'),
-    installDir: '.agents/skills',
-    label: 'Codex',
-    layout: 'directory',
-  },
-  opencode: {
-    sourceDir: join(DIST_DIR, 'opencode'),
-    installDir: '.opencode/skills',
-    label: 'Open Code',
-    layout: 'directory',
-  },
-};
+// Derive install-side TARGETS from the shared emitter config so we have one source of truth.
+// `sourceDir` is computed from the shared `distSubdir`; `emit` is reused for installing user extensions.
+const TARGETS = Object.fromEntries(
+  Object.entries(EMITTER_TARGETS).map(([key, t]) => [key, {
+    ...t,
+    sourceDir: join(DIST_DIR, t.distSubdir),
+  }]),
+);
+
+// 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-stack', 'gspec-practices', 'gspec-architect', 'gspec-analyze',
+  'gspec-audit', 'gspec-research', 'gspec-implement', 'gspec-migrate',
+]);
 
 const TARGET_CHOICES = [
   { key: '1', name: 'claude', label: 'Claude Code' },
@@ -1397,6 +1381,8 @@ program
 
     await install(targetName, process.cwd());
 
+    await installExtensions(targetName, process.cwd());
+
     await seedFromSavedSpecs(process.cwd());
 
     await installSpecSync(targetName, process.cwd());
@@ -1424,6 +1410,176 @@ program
     }
   });
 
+// --- Extensions ---
+
+const EXTENSIONS_DIR = join(GSPEC_HOME, 'extensions');
+const EXTENSION_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+async function loadExtensions() {
+  let entries;
+  try {
+    entries = await readdir(EXTENSIONS_DIR);
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+
+  const files = entries.filter((f) => f.endsWith('.md'));
+  const loaded = [];
+  for (const file of files) {
+    const path = join(EXTENSIONS_DIR, file);
+    const content = await readFile(path, 'utf-8');
+    const { fields, body } = parseFrontmatter(content);
+    loaded.push({ file, path, fields, body, content });
+  }
+  return loaded;
+}
+
+function validateExtension(ext) {
+  const errors = [];
+  if (!ext.fields.name) errors.push("missing 'name' frontmatter");
+  if (!ext.fields.description) errors.push("missing 'description' frontmatter");
+  if (ext.fields.name && !EXTENSION_NAME_RE.test(ext.fields.name)) {
+    errors.push(`invalid name "${ext.fields.name}" (must match /^[a-z0-9][a-z0-9-]*$/)`);
+  }
+  if (ext.fields.name && BUILTIN_SKILL_NAMES.has(ext.fields.name)) {
+    errors.push(`name "${ext.fields.name}" collides with a built-in gspec skill`);
+  }
+  return errors;
+}
+
+async function installExtensions(targetName, cwd) {
+  const extensions = await loadExtensions();
+  if (extensions.length === 0) return;
+
+  const target = TARGETS[targetName];
+  const valid = [];
+  for (const ext of extensions) {
+    const errors = validateExtension(ext);
+    if (errors.length > 0) {
+      console.warn(chalk.yellow(`  ! Skipping extension ${ext.file}: ${errors.join('; ')}`));
+      continue;
+    }
+    valid.push(ext);
+  }
+
+  // Resolve duplicates by name (last write wins, with a warning)
+  const byName = new Map();
+  for (const ext of valid) {
+    if (byName.has(ext.fields.name)) {
+      console.warn(chalk.yellow(
+        `  ! Extension name "${ext.fields.name}" defined in two files; ${ext.file} overrides ${byName.get(ext.fields.name).file}`
+      ));
+    }
+    byName.set(ext.fields.name, ext);
+  }
+  const finalSet = Array.from(byName.values());
+  if (finalSet.length === 0) return;
+
+  console.log(chalk.bold(`\nInstalling ${finalSet.length} user extension${finalSet.length === 1 ? '' : 's'} from ~/.gspec/extensions/...\n`));
+  const installPath = join(cwd, target.installDir);
+  for (const ext of finalSet) {
+    const meta = { name: ext.fields.name, description: ext.fields.description };
+    await target.emit(installPath, ext.body, meta);
+    console.log(`  ${chalk.green('+')} ${ext.fields.name} ${chalk.dim('(extension)')}`);
+  }
+}
+
+async function extensionList() {
+  console.log(BANNER);
+  const extensions = await loadExtensions();
+  if (extensions.length === 0) {
+    console.log(chalk.dim('\n  No extensions installed in ~/.gspec/extensions/.\n'));
+    console.log(chalk.dim('  Use "gspec extension save <path>" to install one.\n'));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  ${extensions.length} extension${extensions.length === 1 ? '' : 's'} in ~/.gspec/extensions/:\n`));
+  for (const ext of extensions) {
+    const errors = validateExtension(ext);
+    const name = ext.fields.name || chalk.dim('(no name)');
+    const desc = ext.fields.description ? chalk.dim(` — ${ext.fields.description}`) : '';
+    if (errors.length > 0) {
+      console.log(`  ${chalk.yellow('!')} ${ext.file} → ${name}${desc}`);
+      console.log(`      ${chalk.yellow(errors.join('; '))}`);
+    } else {
+      console.log(`  ${chalk.green('•')} ${name}${desc}`);
+      console.log(`      ${chalk.dim(ext.file)}`);
+    }
+  }
+  console.log();
+}
+
+async function extensionSave(srcPath) {
+  console.log(BANNER);
+
+  if (!srcPath) {
+    console.error(chalk.red('\n  Usage: gspec extension save <path-to-extension.md>\n'));
+    process.exit(1);
+  }
+
+  let content;
+  try {
+    content = await readFile(srcPath, 'utf-8');
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      console.error(chalk.red(`\n  File not found: ${srcPath}\n`));
+      process.exit(1);
+    }
+    throw e;
+  }
+
+  const { fields } = parseFrontmatter(content);
+  const ext = { file: basename(srcPath), fields };
+  const errors = validateExtension(ext);
+  if (errors.length > 0) {
+    console.error(chalk.red(`\n  Cannot save extension: ${errors.join('; ')}\n`));
+    process.exit(1);
+  }
+
+  await mkdir(EXTENSIONS_DIR, { recursive: true });
+  const destPath = join(EXTENSIONS_DIR, `${fields.name}.md`);
+
+  try {
+    await stat(destPath);
+    const overwrite = await promptConfirm(chalk.yellow(`\n  Extension "${fields.name}" already exists. Overwrite? [y/N]: `));
+    if (!overwrite) {
+      console.log(chalk.dim('\n  Cancelled.\n'));
+      return;
+    }
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  await writeFile(destPath, content, 'utf-8');
+  console.log(chalk.green(`\n  ✓ Saved extension to ~/.gspec/extensions/${fields.name}.md\n`));
+  console.log(chalk.dim(`  It will be installed alongside core skills the next time you run "gspec" in a project.\n`));
+}
+
+async function extensionRemove(name) {
+  console.log(BANNER);
+
+  if (!name) {
+    console.error(chalk.red('\n  Usage: gspec extension remove <name>\n'));
+    process.exit(1);
+  }
+
+  const path = join(EXTENSIONS_DIR, `${name}.md`);
+  try {
+    await stat(path);
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      console.error(chalk.red(`\n  Extension not found: ~/.gspec/extensions/${name}.md\n`));
+      process.exit(1);
+    }
+    throw e;
+  }
+
+  await unlink(path);
+  console.log(chalk.green(`\n  ✓ Removed ~/.gspec/extensions/${name}.md\n`));
+  console.log(chalk.dim(`  Already-installed copies in projects (.claude/skills/, .cursor/commands/, etc.) are left in place — delete them manually if desired.\n`));
+}
+
 program
   .command('save')
   .description('Save a gspec spec to ~/.gspec for reuse across projects')
@@ -1446,4 +1602,29 @@ program
     await createPlaybook();
   });
 
+const extensionCmd = program
+  .command('extension')
+  .description('Manage user-authored gspec extension skills in ~/.gspec/extensions/');
+
+extensionCmd
+  .command('list')
+  .description('List installed extensions')
+  .action(async () => {
+    await extensionList();
+  });
+
+extensionCmd
+  .command('save <path>')
+  .description('Save a local .md skill file as a user extension in ~/.gspec/extensions/')
+  .action(async (path) => {
+    await extensionSave(path);
+  });
+
+extensionCmd
+  .command('remove <name>')
+  .description('Remove a user extension from ~/.gspec/extensions/ (does not uninstall already-emitted copies)')
+  .action(async (name) => {
+    await extensionRemove(name);
+  });
+
 program.parse();

package/commands/gspec.analyze.md

@@ -31,6 +31,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.
 
@@ -75,6 +76,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/commands/gspec.audit.md

@@ -12,11 +12,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
 
 ---
 
@@ -34,6 +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
 
 If the `gspec/` directory is empty, inform the user that there are no specs to audit and stop.
 
@@ -55,6 +57,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)
@@ -99,6 +106,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.
@@ -125,7 +148,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]
@@ -145,6 +168,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)
@@ -164,31 +214,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: <<<SPEC_VERSION>>>
+  ---
+  ```
+  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/commands/gspec.feature.md

@@ -186,6 +186,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