gspec 1.7.0 → 1.10.0

package/bin/gspec.js

@@ -9,6 +9,7 @@ import chalk from 'chalk';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = join(__dirname, '..', 'dist');
+const STARTERS_DIR = join(__dirname, '..', 'starters');
 const pkg = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
 
 const BANNER = `
@@ -51,6 +52,12 @@ const TARGETS = {
     label: 'Codex',
     layout: 'directory',
   },
+  opencode: {
+    sourceDir: join(DIST_DIR, 'opencode'),
+    installDir: '.opencode/skills',
+    label: 'Open Code',
+    layout: 'directory',
+  },
 };
 
 const TARGET_CHOICES = [
@@ -58,6 +65,7 @@ const TARGET_CHOICES = [
   { key: '2', name: 'cursor', label: 'Cursor' },
   { key: '3', name: 'antigravity', label: 'Antigravity' },
   { key: '4', name: 'codex', label: 'Codex' },
+  { key: '5', name: 'opencode', label: 'Open Code' },
 ];
 
 function promptTarget() {
@@ -70,7 +78,7 @@ function promptTarget() {
   console.log();
 
   return new Promise((resolve) => {
-    rl.question(chalk.bold('  Select [1-4]: '), (answer) => {
+    rl.question(chalk.bold('  Select [1-5]: '), (answer) => {
       rl.close();
       const trimmed = answer.trim().toLowerCase();
 
@@ -83,7 +91,7 @@ function promptTarget() {
       if (byName) return resolve(byName.name);
 
       console.error(chalk.red(`\nInvalid selection: "${answer.trim()}"`));
-      console.error(`Valid options: 1, 2, 3, 4, claude, cursor, antigravity, codex`);
+      console.error(`Valid options: 1, 2, 3, 4, 5, claude, cursor, antigravity, codex, opencode`);
       process.exit(1);
     });
   });
@@ -109,6 +117,246 @@ function promptConfirmNo(message) {
   });
 }
 
+// --- Feature dependency map ---
+// Maps feature slugs to their required feature dependencies (other feature slugs).
+// This is used to auto-include dependencies when a user selects a feature.
+const FEATURE_DEPENDENCIES = {
+  'home-page': [],
+  'about-page': ['home-page'],
+  'contact-page': ['home-page'],
+  'services-page': ['home-page'],
+  'responsive-navbar': ['home-page'],
+  'contact-form': ['contact-page'],
+  'site-footer': ['home-page', 'about-page', 'contact-page'],
+  'theme-switcher': ['home-page', 'about-page', 'contact-page'],
+};
+
+function resolveFeatureDependencies(selectedSlugs) {
+  const resolved = new Set(selectedSlugs);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const slug of [...resolved]) {
+      const deps = FEATURE_DEPENDENCIES[slug] || [];
+      for (const dep of deps) {
+        if (!resolved.has(dep)) {
+          resolved.add(dep);
+          changed = true;
+        }
+      }
+    }
+  }
+  return [...resolved];
+}
+
+// --- Starter template utilities ---
+
+async function parseStarterDescription(filePath) {
+  const content = await readFile(filePath, 'utf-8');
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return '';
+  const descLine = match[1].split('\n').find((l) => l.startsWith('description:'));
+  return descLine ? descLine.replace(/^description:\s*/, '').trim() : '';
+}
+
+async function listStarterTemplates(category) {
+  const dir = join(STARTERS_DIR, category);
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+  const mdFiles = entries.filter((f) => f.endsWith('.md'));
+  const templates = [];
+  for (const f of mdFiles) {
+    const slug = f.replace(/\.md$/, '');
+    const description = await parseStarterDescription(join(dir, f));
+    templates.push({ slug, description });
+  }
+  return templates;
+}
+
+function formatStarterName(slug) {
+  if (slug === '_none') return 'None';
+  return slug
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+function stampVersion(content) {
+  return content.replace(/^(---\s*\n[\s\S]*?)gspec-version:\s*.+/m, `$1gspec-version: ${pkg.version}`);
+}
+
+function promptSelect(message, choices) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  console.log(chalk.bold(`\n${message}\n`));
+  for (let i = 0; i < choices.length; i++) {
+    const label = formatStarterName(choices[i].slug);
+    const desc = choices[i].description ? ` — ${choices[i].description}` : '';
+    console.log(`  ${chalk.cyan(String(i + 1))}) ${label}${desc}`);
+  }
+  console.log();
+
+  return new Promise((resolve) => {
+    rl.question(chalk.bold(`  Select [1-${choices.length}]: `), (answer) => {
+      rl.close();
+      const num = parseInt(answer.trim(), 10);
+      if (num >= 1 && num <= choices.length) return resolve(choices[num - 1].slug);
+      console.error(chalk.red(`\nInvalid selection: "${answer.trim()}"`));
+      process.exit(1);
+    });
+  });
+}
+
+function promptMultiSelect(message, choices) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  console.log(chalk.bold(`\n${message}\n`));
+  for (let i = 0; i < choices.length; i++) {
+    const label = formatStarterName(choices[i].slug);
+    const desc = choices[i].description ? ` — ${choices[i].description}` : '';
+    console.log(`  ${chalk.cyan(String(i + 1))}) ${label}${desc}`);
+  }
+  console.log();
+
+  return new Promise((resolve) => {
+    rl.question(chalk.bold('  Enter numbers (comma-separated), "all", or press Enter to skip: '), (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      if (trimmed === '') return resolve([]);
+      if (trimmed === 'all') return resolve(choices.map((c) => c.slug));
+
+      const nums = trimmed.split(',').map((s) => parseInt(s.trim(), 10));
+      const invalid = nums.find((n) => isNaN(n) || n < 1 || n > choices.length);
+      if (invalid !== undefined) {
+        console.error(chalk.red(`\nInvalid selection: "${answer.trim()}"`));
+        process.exit(1);
+      }
+      resolve(nums.map((n) => choices[n - 1].slug));
+    });
+  });
+}
+
+async function seedStarterTemplates(cwd) {
+  const wantStarters = await promptConfirm(chalk.bold('  Would you like to start from a starter template? [y/N]: '));
+  if (!wantStarters) {
+    console.log(chalk.dim('\n  Skipped starter templates.\n'));
+    return;
+  }
+
+  const practices = await listStarterTemplates('practices');
+  const stacks = await listStarterTemplates('stacks');
+  const styles = await listStarterTemplates('styles');
+  const features = await listStarterTemplates('features');
+
+  if (practices.length === 0 || stacks.length === 0 || styles.length === 0) {
+    console.log(chalk.yellow('  Missing starter templates (practices, stacks, or styles). Skipping.\n'));
+    return;
+  }
+
+  const NONE_OPTION = { slug: '_none', description: 'I will define my own' };
+
+  // Single-select with auto-select for single-option categories
+  const practice = practices.length === 1
+    ? (console.log(chalk.dim(`\n  Using practice: ${formatStarterName(practices[0].slug)}`)), practices[0].slug)
+    : await promptSelect('Select a development practice', [...practices, NONE_OPTION]);
+
+  const stack = stacks.length === 1
+    ? (console.log(chalk.dim(`  Using stack: ${formatStarterName(stacks[0].slug)}`)), stacks[0].slug)
+    : await promptSelect('Select a technology stack', [...stacks, NONE_OPTION]);
+
+  const style = styles.length === 1
+    ? (console.log(chalk.dim(`  Using style: ${formatStarterName(styles[0].slug)}`)), styles[0].slug)
+    : await promptSelect('Select a visual style', [...styles, NONE_OPTION]);
+
+  let selectedFeatures = [];
+  if (features.length > 0) {
+    selectedFeatures = await promptMultiSelect('Select features (optional)', [...features, NONE_OPTION]);
+    selectedFeatures = selectedFeatures.filter(f => f !== '_none');
+  }
+
+  // Auto-include feature dependencies
+  if (selectedFeatures.length > 0) {
+    const resolved = resolveFeatureDependencies(selectedFeatures);
+    const added = resolved.filter((f) => !selectedFeatures.includes(f));
+    if (added.length > 0) {
+      console.log(chalk.cyan(`\n  Auto-including dependencies: ${added.map(formatStarterName).join(', ')}`));
+      selectedFeatures = resolved;
+    }
+  }
+
+  // Check for existing files
+  const gspecDir = join(cwd, 'gspec');
+  const filesToWrite = [];
+  if (practice !== '_none') {
+    filesToWrite.push({ src: join(STARTERS_DIR, 'practices', `${practice}.md`), dest: join(gspecDir, 'practices.md'), label: 'gspec/practices.md' });
+  }
+  if (stack !== '_none') {
+    filesToWrite.push({ src: join(STARTERS_DIR, 'stacks', `${stack}.md`), dest: join(gspecDir, 'stack.md'), label: 'gspec/stack.md' });
+  }
+  if (style !== '_none') {
+    filesToWrite.push({ src: join(STARTERS_DIR, 'styles', `${style}.md`), dest: join(gspecDir, 'style.md'), label: 'gspec/style.md' });
+  }
+  for (const feature of selectedFeatures) {
+    filesToWrite.push({
+      src: join(STARTERS_DIR, 'features', `${feature}.md`),
+      dest: join(gspecDir, 'features', `${feature}.md`),
+      label: `gspec/features/${feature}.md`,
+    });
+  }
+
+  const existingFiles = [];
+  for (const f of filesToWrite) {
+    try {
+      await stat(f.dest);
+      existingFiles.push(f.label);
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+
+  if (filesToWrite.length === 0) {
+    console.log(chalk.dim('\n  No starter templates selected. You can define these files using gspec commands.\n'));
+    return;
+  }
+
+  if (existingFiles.length > 0) {
+    console.log(chalk.yellow(`\n  The following files already exist and will be overwritten:\n`));
+    for (const label of existingFiles) {
+      console.log(`    ${chalk.yellow('!')} ${label}`);
+    }
+    console.log();
+    const confirmed = await promptConfirm(chalk.bold('  Continue and overwrite? [y/N]: '));
+    if (!confirmed) {
+      console.log(chalk.dim('\n  Skipped starter templates.\n'));
+      return;
+    }
+  }
+
+  // Copy files with version stamping
+  console.log(chalk.bold('\n  Seeding starter templates...\n'));
+  for (const f of filesToWrite) {
+    await mkdir(dirname(f.dest), { recursive: true });
+    const content = await readFile(f.src, 'utf-8');
+    await writeFile(f.dest, stampVersion(content), 'utf-8');
+    console.log(`  ${chalk.green('+')} ${f.label}`);
+  }
+
+  // Summary
+  console.log(chalk.bold('\n  Seeded gspec/ with:'));
+  console.log(`    Practice: ${practice === '_none' ? chalk.dim('(will define)') : formatStarterName(practice)}`);
+  console.log(`    Stack:    ${stack === '_none' ? chalk.dim('(will define)') : formatStarterName(stack)}`);
+  console.log(`    Style:    ${style === '_none' ? chalk.dim('(will define)') : formatStarterName(style)}`);
+  if (selectedFeatures.length > 0) {
+    console.log(`    Features: ${selectedFeatures.map(formatStarterName).join(', ')}`);
+  } else {
+    console.log(`    Features: ${chalk.dim('(will define)')}`);
+  }
+  console.log();
+}
+
 async function findExistingFiles(target, cwd) {
   const existing = [];
   const destBase = join(cwd, target.installDir);
@@ -257,6 +505,11 @@ const SPEC_SYNC = {
     mode: 'append',
     wrap: (content) => content,
   },
+  opencode: {
+    file: 'AGENTS.md',
+    mode: 'append',
+    wrap: (content) => content,
+  },
 };
 
 const GSPEC_SECTION_MARKER = '<!-- gspec:spec-sync -->';
@@ -312,6 +565,7 @@ const MIGRATE_COMMANDS = {
   cursor: '/gspec-migrate',
   antigravity: '/gspec-migrate',
   codex: '/gspec-migrate',
+  opencode: '/gspec-migrate',
 };
 
 function parseGspecVersion(content) {
@@ -326,7 +580,7 @@ async function collectGspecFiles(gspecDir) {
 
   const topEntries = await readdir(gspecDir);
   for (const entry of topEntries) {
-    if (entry.endsWith('.md')) {
+    if (entry.endsWith('.md') && entry.toLowerCase() !== 'readme.md') {
       files.push({ path: join(gspecDir, entry), label: `gspec/${entry}` });
     }
   }
@@ -394,7 +648,7 @@ program
   .name('gspec')
   .description('Install gspec specification commands')
   .version(pkg.version)
-  .option('-t, --target <target>', 'target platform (claude, cursor, antigravity, codex)')
+  .option('-t, --target <target>', 'target platform (claude, cursor, antigravity, codex, opencode)')
   .action(async (opts) => {
     console.log(BANNER);
 
@@ -406,12 +660,25 @@ program
 
     await install(targetName, process.cwd());
 
-    const skipSync = await promptConfirmNo(chalk.bold('  Enable automatic spec sync? (keeps gspec specs up to date as code changes) [Y/n]: '));
-    if (!skipSync) {
-      await installSpecSync(targetName, process.cwd());
-    }
+    await seedStarterTemplates(process.cwd());
+
+    await installSpecSync(targetName, process.cwd());
 
     await checkGspecFiles(process.cwd(), targetName);
+
+    // Post-install: instruct user to generate profile.md
+    const targetLabel = TARGETS[targetName].label;
+    console.log();
+    console.log(chalk.bold.cyan('  ═══ Next Step ═══════════════════════════════════════════════'));
+    console.log();
+    console.log(chalk.bold.white('  Generate your product profile before continuing.'));
+    console.log();
+    console.log(`  Run ${chalk.bold.yellow('/gspec-profile')} in ${targetLabel} to create gspec/profile.md`);
+    console.log(`  — it defines what your product is, who it serves, and why it`);
+    console.log(`  exists. All other gspec commands use the profile as their foundation.`);
+    console.log();
+    console.log(chalk.bold.cyan('  ═════════════════════════════════════════════════════════════'));
+    console.log();
   });
 
 program.parse();

package/commands/gspec.analyze.md

@@ -23,7 +23,7 @@ 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
-3. `gspec/style.md` — Visual design language, tokens, component patterns
+3. `gspec/style.md` — Visual design language, tokens, component styling
 4. `gspec/practices.md` — Development standards, testing, conventions
 5. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
 6. `gspec/research.md` — Competitive analysis and feature proposals

package/commands/gspec.implement.md

@@ -100,9 +100,9 @@ Present a brief scaffold summary to the user before proceeding to feature implem
 
 1. **Announce the phase** — State which phase you're starting, what it covers, and what capabilities will be implemented
 2. **Implement the phase:**
-   a. **Follow the stack** — Use the exact technologies, frameworks, and patterns defined in `gspec/stack.md`
-   b. **Follow the practices** — Adhere to coding standards, testing requirements, and conventions from `gspec/practices.md`
-   c. **Follow the style** — Apply the design system, tokens, and component patterns from `gspec/style.md`
+   a. **Follow the stack** — Use the exact technologies, frameworks, and patterns defined in `gspec/stack.md`. The stack is the single authority for technology choices (testing tools, CI/CD platform, package manager). Where stack-specific practices (Section 15 of `stack.md`) conflict with general practices in `practices.md`, the stack's technology-specific guidance takes precedence for framework-specific concerns.
+   b. **Follow the practices** — Adhere to coding standards, testing philosophy, pipeline structure, and conventions from `gspec/practices.md`
+   c. **Follow the style** — Apply the design system, tokens, and icon library from `gspec/style.md`. The style is the single authority for icon library choices. Component libraries (e.g., shadcn/ui) are defined in `gspec/stack.md`.
    d. **Satisfy the requirements** — Trace each piece of code back to a functional requirement in the feature PRD (if available) or to the user's stated goals and the approved implementation plan
 3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `gspec-version` YAML frontmatter. If a file lacks frontmatter, add `---\ngspec-version: <<<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.

package/commands/gspec.practices.md

@@ -34,8 +34,10 @@ You should:
 - Focus on practices that matter for this specific project
 - Avoid generic advice that doesn't apply
 - **Do NOT include technology stack information** — this is documented separately
-- **Do NOT prescribe specific testing frameworks, tools, or libraries** — focus on testing principles, patterns, and practices, not which tools to use
+- **Do NOT prescribe specific testing frameworks, tools, or libraries** — focus on testing principles, patterns, and practices. The stack document (`gspec/stack.md`) is the single authority for which test tools are used.
+- **DO define CI/CD pipeline structure** — the practices document defines pipeline stages, gates, and ordering (lint → typecheck → test → build → deploy). The stack document defines which CI/CD platform technology is used (GitHub Actions, GitLab CI, etc.).
 - **Mark sections as "Not Applicable"** when they don't apply to this project
+- **Precedence rule**: Where this document conflicts with technology-specific practices in `gspec/stack.md`, the stack's technology-specific practices take precedence for framework-specific concerns (e.g., file naming conventions dictated by a framework). This document governs general engineering principles.
 
 ---
 

package/commands/gspec.stack.md

@@ -91,6 +91,8 @@ You should:
 - Responsive design tooling
 
 - **Note**: Visual design values (colors, typography, spacing) are documented separately as framework-agnostic design tokens; include here how the chosen CSS framework maps to those tokens
+- **Component library** (if applicable) — e.g., shadcn/ui, Headless UI, Radix UI. Component libraries are framework-specific technology choices and belong in the stack, not the style guide.
+- **Note**: Icon libraries (e.g., HeroIcons, Lucide) are defined in `gspec/style.md`, not here. The stack defines the CSS framework and component library; the style defines the icon set. Do NOT include an iconography section in the stack document.
 
 ### 5. Backend Stack
 **Mark as N/A if this is a frontend-only or static site project**
@@ -129,9 +131,9 @@ You should:
 - Scaling approach
 
 #### CI/CD Pipeline
-- CI/CD platform (GitHub Actions, GitLab CI, Jenkins, etc.)
-- Pipeline stages
-- Deployment automation
+- CI/CD platform technology (GitHub Actions, GitLab CI, Jenkins, etc.) and rationale
+- Deployment automation and trigger configuration
+- **Note**: The stack defines *which CI/CD technology* is used. The pipeline structure (stages, gates, ordering) is defined in `gspec/practices.md`. Include platform-specific configuration details here (e.g., workflow YAML format, runner setup), not pipeline philosophy.
 
 #### Infrastructure as Code
 - IaC tool (Terraform, CloudFormation, Pulumi, etc.)
@@ -189,10 +191,13 @@ You should:
 
 ### 10. Testing Infrastructure
 
+> **The stack is the single authority for test tooling choices.** Define which frameworks and tools are used here. Testing philosophy, patterns, and coverage requirements are defined in `gspec/practices.md`.
+
 #### Testing Frameworks
-- Unit testing framework
+- Unit testing framework (Vitest, Jest, pytest, etc.) and rationale
 - Integration testing tools
-- E2E testing framework (Playwright, Cypress, etc.)
+- E2E testing framework (Playwright, Cypress, etc.) and rationale
+- Component testing tools (if applicable)
 
 #### Test Data Management
 - Test database strategy
@@ -219,7 +224,7 @@ You should:
 ### 12. Development Tools
 
 #### Package Management
-- Package manager (npm, yarn, pnpm, pip, maven, etc.)
+- **Package manager** — Explicitly declare the package manager (npm, yarn, pnpm, pip, maven, etc.) with rationale for the choice. This must be stated clearly so all other gspec commands and CI/CD configuration use the correct tool.
 - Dependency management strategy
 - Private package registry (if applicable)
 

package/commands/gspec.style.md

@@ -110,34 +110,27 @@ You should:
 - Component color adjustments
 - Contrast considerations
 
-#### Theme Switching
-- How themes interact with the color palette
-- Token mapping between themes
+### 6. Component Styling
 
-### 6. Components
+> **Focus on visual styling only** — colors, borders, typography, spacing, and state appearances. Do NOT define component structure, layout behavior, or interaction patterns (those belong in feature PRDs). The goal is to answer "what does it look like?" not "how does it work?"
 
 #### Buttons
-- Primary, secondary, tertiary styles
-- States (default, hover, active, disabled)
-- Sizes and padding
-- Border radius
+- Color treatments for primary, secondary, ghost variants
+- States: default, hover, active, disabled appearances
+- Sizes and border radius
 
 #### Form Elements
-- Input fields
-- Dropdowns, checkboxes, radio buttons
-- Labels and helper text
-- Validation states
+- Input field colors, borders, and focus ring styles
+- Label and helper text typography
+- Validation state colors (error, success)
 
 #### Cards & Containers
-- Background colors
-- Border styles
-- Shadow elevations
-- Corner radius
+- Background colors and border styles
+- Shadow elevations and corner radius
 
-#### Navigation
-- Header/navbar styles
-- Menu patterns
-- Active states
+#### Navigation Elements
+- Link colors: default, hover, active states
+- Background treatments for navigation surfaces
 
 ### 7. Visual Effects
 
@@ -157,11 +150,13 @@ You should:
 
 ### 8. Iconography
 
-#### Icon Style
-- Outlined vs filled
+> **The style guide is the single authority for icon library choices.** The stack document defines the CSS framework and component library (e.g., shadcn/ui); the style guide defines which icon set is used. This separation ensures icon decisions are driven by design rationale (visual consistency, stroke style) while component library decisions remain with the technology stack (framework compatibility).
+
+#### Icon Library
+- Specific icon library recommendation with rationale
+- Outlined vs filled style
 - Stroke width
 - Size standards
-- Icon library recommendation
 
 #### Usage Guidelines
 - When to use icons

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

@@ -28,7 +28,7 @@ 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
-3. `gspec/style.md` — Visual design language, tokens, component patterns
+3. `gspec/style.md` — Visual design language, tokens, component styling
 4. `gspec/practices.md` — Development standards, testing, conventions
 5. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
 6. `gspec/research.md` — Competitive analysis and feature proposals

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

@@ -45,7 +45,7 @@ All of these provide essential context. If any are missing, note the gap and mak
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

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

@@ -85,7 +85,7 @@ Feature PRDs are designed to be **portable across projects**. A feature spec wri
 - Begin each file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

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

@@ -105,11 +105,11 @@ Present a brief scaffold summary to the user before proceeding to feature implem
 
 1. **Announce the phase** — State which phase you're starting, what it covers, and what capabilities will be implemented
 2. **Implement the phase:**
-   a. **Follow the stack** — Use the exact technologies, frameworks, and patterns defined in `gspec/stack.md`
-   b. **Follow the practices** — Adhere to coding standards, testing requirements, and conventions from `gspec/practices.md`
-   c. **Follow the style** — Apply the design system, tokens, and component patterns from `gspec/style.md`
+   a. **Follow the stack** — Use the exact technologies, frameworks, and patterns defined in `gspec/stack.md`. The stack is the single authority for technology choices (testing tools, CI/CD platform, package manager). Where stack-specific practices (Section 15 of `stack.md`) conflict with general practices in `practices.md`, the stack's technology-specific guidance takes precedence for framework-specific concerns.
+   b. **Follow the practices** — Adhere to coding standards, testing philosophy, pipeline structure, and conventions from `gspec/practices.md`
+   c. **Follow the style** — Apply the design system, tokens, and icon library from `gspec/style.md`. The style is the single authority for icon library choices. Component libraries (e.g., shadcn/ui) are defined in `gspec/stack.md`.
    d. **Satisfy the requirements** — Trace each piece of code back to a functional requirement in the feature PRD (if available) or to the user's stated goals and the approved implementation plan
-3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `gspec-version` YAML frontmatter. If a file lacks frontmatter, add `---\ngspec-version: 1.7.0\n---` at the top.
+3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `gspec-version` YAML frontmatter. If a file lacks frontmatter, add `---\ngspec-version: 1.10.0\n---` at the top.
 4. **Run tests** — Execute the tests defined for this phase (and any existing tests to catch regressions). Fix any failures before proceeding.
 6. **Surface new gaps** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 7. **Pause and report** — After completing the phase and confirming tests pass, present a phase completion summary to the user:

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

@@ -5,7 +5,7 @@ description: Migrate existing gspec files to the current format when upgrading t
 
 You are a Technical Documentation Migration Specialist.
 
-Your task is to update existing gspec specification documents to match the current gspec format (version 1.7.0). You preserve all substantive content while ensuring documents follow the latest structural conventions.
+Your task is to update existing gspec specification documents to match the current gspec format (version 1.10.0). You preserve all substantive content while ensuring documents follow the latest structural conventions.
 
 ---
 
@@ -21,14 +21,14 @@ Scan the `gspec/` directory for all Markdown files:
 For each file, check the YAML frontmatter at the top of the file:
 - If the file starts with `---` followed by YAML content and another `---`, read the `gspec-version` field
 - If no frontmatter exists, the file predates version tracking
-- If `gspec-version` matches `1.7.0`, the file is current — skip it
+- If `gspec-version` matches `1.10.0`, the file is current — skip it
 
 Present an inventory to the user:
 
 > **gspec File Inventory:**
 > - `gspec/profile.md` — no version (needs migration)
 > - `gspec/stack.md` — version 1.0.3 (needs migration)
-> - `gspec/style.md` — version 1.7.0 (current, skipping)
+> - `gspec/style.md` — version 1.10.0 (current, skipping)
 > - `gspec/features/user-auth.md` — no version (needs migration)
 
 Ask the user to confirm which files to migrate, or confirm all.
@@ -63,7 +63,7 @@ For each file to migrate:
 5. **Add or update the frontmatter** — Ensure the file starts with:
    ```
    ---
-   gspec-version: 1.7.0
+   gspec-version: 1.10.0
    ---
    ```
 6. **Present the proposed changes** to the user before writing. Show what sections are being reorganized, what is being added, and confirm no content is being lost.
@@ -77,7 +77,7 @@ After migrating all files:
 3. **Present a completion summary**:
 
 > **Migration Complete:**
-> - 4 files migrated to version 1.7.0
+> - 4 files migrated to version 1.10.0
 > - 2 files were already current (skipped)
 > - Content preserved in all files
 > - Sections reorganized: [list any structural changes]

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

@@ -25,7 +25,7 @@ You should:
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -39,8 +39,10 @@ You should:
 - Focus on practices that matter for this specific project
 - Avoid generic advice that doesn't apply
 - **Do NOT include technology stack information** — this is documented separately
-- **Do NOT prescribe specific testing frameworks, tools, or libraries** — focus on testing principles, patterns, and practices, not which tools to use
+- **Do NOT prescribe specific testing frameworks, tools, or libraries** — focus on testing principles, patterns, and practices. The stack document (`gspec/stack.md`) is the single authority for which test tools are used.
+- **DO define CI/CD pipeline structure** — the practices document defines pipeline stages, gates, and ordering (lint → typecheck → test → build → deploy). The stack document defines which CI/CD platform technology is used (GitHub Actions, GitLab CI, etc.).
 - **Mark sections as "Not Applicable"** when they don't apply to this project
+- **Precedence rule**: Where this document conflicts with technology-specific practices in `gspec/stack.md`, the stack's technology-specific practices take precedence for framework-specific concerns (e.g., file naming conventions dictated by a framework). This document governs general engineering principles.
 
 ---
 

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

@@ -25,7 +25,7 @@ You should:
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

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

@@ -162,7 +162,7 @@ After writing `gspec/research.md`, ask the user:
    - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
    - Success Metrics
    - Implementation Context (standard portability note)
-   - Begin the file with YAML frontmatter: `---\ngspec-version: 1.7.0\n---`
+   - Begin the file with YAML frontmatter: `---\ngspec-version: 1.10.0\n---`
 2. **Name the file** descriptively based on the feature (e.g., `gspec/features/csv-export.md`, `gspec/features/onboarding-wizard.md`)
 3. **Keep the PRD portable** — use generic role descriptions (not project-specific persona names), define success metrics in terms of the feature's own outcomes (not project-level KPIs), and describe UX behavior generically (not tied to a specific design system). The PRD should be reusable across projects.
 4. **Keep the PRD product-focused** — describe *what* and *why*, not *how*. Implementation details belong in the code, not the PRD.
@@ -181,7 +181,7 @@ After writing `gspec/research.md`, ask the user:
 - Begin `gspec/research.md` with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -198,7 +198,7 @@ The `gspec/research.md` file must follow this structure:
 
 ```markdown
 ---
-gspec-version: 1.7.0
+gspec-version: 1.10.0
 ---
 
 # Competitive Research