gspec 1.7.0 → 1.11.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

@@ -57,8 +57,9 @@ Present this summary to the user so they understand the starting point. If **all
    - Identify files to create or modify
    - Note dependencies on prior phases
    - Include an estimated scope (small/medium/large)
-3. **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.)
-4. **Present the plan** — Show the user the full phased plan with clear phase boundaries and ask for approval
+3. **Account for every unchecked capability** — The plan must explicitly place every unchecked capability from in-scope feature PRDs into a phase **or** list it under a "Proposed to Defer" section with a reason. No unchecked capability may be silently omitted from the plan. The user reviews and approves what gets deferred at plan approval time.
+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
 
 **Wait for user approval before proceeding to Phase 3.** The user may reorder phases, adjust scope, or split/merge phases.
 
@@ -100,9 +101,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.
@@ -124,8 +125,8 @@ After implementation:
 1. **Walk through each functional requirement** from the feature PRD (if available) or the approved implementation plan and confirm it's satisfied
 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. **Note any deferred items** — Requirements that were intentionally postponed or descoped during implementation
-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 intentionally deferred. Present a final status summary:
+4. **Verify no unapproved deferrals** — Compare the final implementation against the approved plan. If any capability that was assigned to a phase was not implemented, **do not silently leave it unchecked**. Flag it to the user, explain why it wasn't completed, and get explicit approval before marking it as deferred. Only capabilities the user approved for deferral during planning (or explicitly approves now) may remain unchecked.
+5. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were approved for deferral by the user. Present a final status summary:
 
 > **Implementation Summary:**
 > - Feature X: 7/7 capabilities implemented (complete)
@@ -144,6 +145,7 @@ When you encounter something the specs don't fully cover during implementation:
 - **If the ambiguity is significant** (e.g., unclear user flow, missing data model, conflicting requirements), pause and consult the user rather than making silent assumptions
 - **Never silently implement unspecified behavior** that contradicts or significantly extends the original spec — ask first
 - **Never override explicit spec decisions** with your own preferences
+- **Never skip or descope a PRD capability without user approval** — ambiguity in *how* to implement something is not grounds for dropping it. If a capability seems too complex, unclear, or problematic, raise it with the user rather than omitting it
 
 ---
 
@@ -173,7 +175,7 @@ If the user specifies a feature, focus on that feature's **unchecked capabilitie
 
 ### When the user provides a prompt alongside existing features:
 
-The user's prompt takes priority for scoping. Use it to determine focus, and reference existing feature PRDs as supporting context rather than the sole driver.
+The user's prompt takes priority for scoping. Use it to determine focus, and reference existing feature PRDs as supporting context rather than the sole driver. However, if the user's prompt narrows scope such that some unchecked PRD capabilities will not be implemented this run, explicitly list those excluded capabilities in the plan under "Out of Scope for This Run" so the user can see what is being deferred and why.
 
 ---
 

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.11.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.11.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

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

@@ -62,8 +62,9 @@ Present this summary to the user so they understand the starting point. If **all
    - Identify files to create or modify
    - Note dependencies on prior phases
    - Include an estimated scope (small/medium/large)
-3. **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.)
-4. **Present the plan** — Show the user the full phased plan with clear phase boundaries and ask for approval
+3. **Account for every unchecked capability** — The plan must explicitly place every unchecked capability from in-scope feature PRDs into a phase **or** list it under a "Proposed to Defer" section with a reason. No unchecked capability may be silently omitted from the plan. The user reviews and approves what gets deferred at plan approval time.
+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
 
 **Wait for user approval before proceeding to Phase 3.** The user may reorder phases, adjust scope, or split/merge phases.
 
@@ -105,11 +106,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.11.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:
@@ -129,8 +130,8 @@ After implementation:
 1. **Walk through each functional requirement** from the feature PRD (if available) or the approved implementation plan and confirm it's satisfied
 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. **Note any deferred items** — Requirements that were intentionally postponed or descoped during implementation
-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 intentionally deferred. Present a final status summary:
+4. **Verify no unapproved deferrals** — Compare the final implementation against the approved plan. If any capability that was assigned to a phase was not implemented, **do not silently leave it unchecked**. Flag it to the user, explain why it wasn't completed, and get explicit approval before marking it as deferred. Only capabilities the user approved for deferral during planning (or explicitly approves now) may remain unchecked.
+5. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were approved for deferral by the user. Present a final status summary:
 
 > **Implementation Summary:**
 > - Feature X: 7/7 capabilities implemented (complete)
@@ -149,6 +150,7 @@ When you encounter something the specs don't fully cover during implementation:
 - **If the ambiguity is significant** (e.g., unclear user flow, missing data model, conflicting requirements), pause and consult the user rather than making silent assumptions
 - **Never silently implement unspecified behavior** that contradicts or significantly extends the original spec — ask first
 - **Never override explicit spec decisions** with your own preferences
+- **Never skip or descope a PRD capability without user approval** — ambiguity in *how* to implement something is not grounds for dropping it. If a capability seems too complex, unclear, or problematic, raise it with the user rather than omitting it
 
 ---
 
@@ -178,7 +180,7 @@ If the user specifies a feature, focus on that feature's **unchecked capabilitie
 
 ### When the user provides a prompt alongside existing features:
 
-The user's prompt takes priority for scoping. Use it to determine focus, and reference existing feature PRDs as supporting context rather than the sole driver.
+The user's prompt takes priority for scoping. Use it to determine focus, and reference existing feature PRDs as supporting context rather than the sole driver. However, if the user's prompt narrows scope such that some unchecked PRD capabilities will not be implemented this run, explicitly list those excluded capabilities in the plan under "Out of Scope for This Run" so the user can see what is being deferred and why.
 
 ---