gspec 1.16.0 → 1.17.1

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/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

@@ -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 './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)