gspec 1.6.0 → 1.10.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 `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, `implement` can take a plain-language description and start building. The remaining commands — `research`, `feature`, `epic`, `architect`, `analyze`, `dor`, and `record` — 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, `implement` can take a plain-language description and start building. The remaining commands — `research`, `feature`, `architect`, `analyze`, `dor`, and `record` — add structure and rigor when the scope or complexity warrants it.
 
 ```mermaid
 flowchart LR
@@ -37,7 +37,7 @@ flowchart LR
     competitive analysis"]
 
     Specify["3. Specify
-    feature · epic"]
+    feature"]
 
     Architect["4. Architect
     technical blueprint"]
@@ -97,10 +97,9 @@ Use `research` when you want to understand what competitors offer, identify tabl
 
 | Command | Role | What it produces |
 |---|---|---|
-| `gspec.feature` | Product Manager | PRD for a single feature with prioritized capabilities |
-| `gspec.epic` | Product Manager | Breaks a large epic into multiple feature PRDs with dependency mapping |
+| `gspec.feature` | Product Manager | One or more feature PRDs with prioritized capabilities |
 
-Use `feature` when you want a detailed PRD with prioritized capabilities and acceptance criteria before building. Use `epic` when a body of work is large enough to need decomposition into multiple features with dependency mapping. For smaller tasks or rapid prototyping, you can skip straight to `implement` with a plain-language description.
+Use `feature` when you want detailed PRDs with prioritized capabilities and acceptance criteria before building. It handles both single features and larger bodies of work — if the scope is large enough, it will propose a multi-feature breakdown for your approval. For smaller tasks or rapid prototyping, you can skip straight to `implement` with a plain-language description.
 
 **4. Architect** *(optional)* — Translate specs into a concrete technical blueprint.
 
@@ -182,8 +181,6 @@ project-root/
     ├── practices.md        # Development standards
     ├── architecture.md     # Technical architecture blueprint
     ├── research.md         # Competitive analysis and feature gaps
-    ├── epics/
-    │   └── onboarding-flow.md
     └── features/
         ├── user-authentication.md
         ├── dashboard-analytics.md

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,12 +23,11 @@ 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
-7. `gspec/epics/*.md` — Epic structure and feature dependencies
-8. `gspec/features/*.md` — Individual feature requirements
+7. `gspec/features/*.md` — Individual feature requirements and dependencies
 
 If fewer than two spec files exist, inform the user that there is nothing to cross-reference and stop.
 
@@ -64,7 +63,6 @@ Systematically compare specs against each other. Look for these categories of di
 #### Scope & Priority Conflicts
 - A feature capability is marked P0 in one place but P1 or P2 in another
 - Profile describes scope or positioning that conflicts with what features actually define
-- Epic dependency ordering conflicts with feature priority levels
 - Research recommendations conflict with decisions already made in other specs
 
 #### Behavioral Conflicts

package/commands/gspec.architect.md

@@ -4,7 +4,7 @@ Your task is to take the established product specifications and produce a **Tech
 
 Beyond defining the architecture, you are also responsible for **identifying technical gaps and ambiguities** in the existing specs and **proposing implementation solutions**. This is the place in the gspec workflow where underspecified technical behavior is surfaced and resolved — so that `gspec-implement` can focus on building rather than making architectural decisions.
 
-This command is meant to be run **after** the foundation specs (profile, stack, style, practices) and feature specs (features, epics) are defined, and **before** `gspec-implement`.
+This command is meant to be run **after** the foundation specs (profile, stack, style, practices) and feature specs are defined, and **before** `gspec-implement`.
 
 You should:
 - Read all existing gspec documents first — this architecture must serve the product, stack, style, and features already defined
@@ -27,8 +27,7 @@ Before generating the architecture document, read **all** existing gspec documen
 2. **`gspec/stack.md`** — Technology choices, frameworks, and infrastructure. Use this as the basis for all technical decisions — framework conventions, database choice, API style, etc.
 3. **`gspec/style.md`** — Design system and tokens. Use this to inform frontend architecture, theming approach, and where design token files belong.
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
-5. **`gspec/epics/*.md`** — Epic structure and feature dependencies. Use this to understand feature grouping and sequencing.
-6. **`gspec/features/*.md`** — Individual feature requirements. Use these to derive data entities, API endpoints, component structure, and integration points.
+5. **`gspec/features/*.md`** — Individual feature requirements and dependencies. Use these to derive data entities, API endpoints, component structure, and integration points.
 
 All of these provide essential context. If any are missing, note the gap and make reasonable assumptions — but flag them in the Open Decisions section.
 

package/commands/gspec.feature.md

@@ -1,6 +1,23 @@
 You are a senior Product Manager at a high-performing software company.
 
-Your task is to take the provided feature description (which may be vague or detailed) and produce a **Product Requirements Document (PRD)** that clearly defines *what* is being built and *why*, without deep technical or architectural implementation details.
+Your task is to take the provided feature description (which may be vague or detailed, small or large) and produce **one or more Product Requirements Documents (PRDs)** that clearly define *what* is being built and *why*, without deep technical or architectural implementation details.
+
+## Scope Assessment
+
+Before writing anything, assess whether the user's description is:
+
+1. **A single feature** — a focused piece of functionality that can be captured in one PRD (e.g., "user authentication", "CSV export", "dark mode support")
+2. **A large body of work** — something broad enough that it should be decomposed into multiple independent features (e.g., "a complete onboarding experience", "a full e-commerce checkout flow", "social features for the app")
+
+**If it's a single feature**, produce one PRD and save it to `gspec/features/`.
+
+**If it's large enough to warrant multiple features:**
+
+1. Propose a breakdown — list the distinct features you'd create, with a one-line description of each and their dependencies on each other
+2. **Ask the user to confirm, adjust, or reprioritize** the breakdown before writing any specs
+3. Once confirmed, generate a separate PRD for each feature in `gspec/features/`
+
+When in doubt, lean toward fewer features. Don't over-decompose — a feature should only be split out if it delivers independent user value and has a meaningfully different scope.
 
 ## Important: Agent-Oriented Documentation
 
@@ -57,19 +74,20 @@ Feature PRDs are designed to be **portable across projects**. A feature spec wri
 
 ## Output Rules
 
-- Output **ONLY** a single Markdown document
-- Save the file to the `gspec/features/` folder in the root of the project, create it if it doesn't exist
-- Name the file based on the feature (e.g., `user-authentication.md`, `dashboard-analytics.md`)
-- Begin the file with YAML frontmatter containing the gspec version:
+- Output one or more Markdown documents — **one per feature**
+- Save each file to the `gspec/features/` folder in the root of the project, create it if it doesn't exist
+- Name each file based on the feature (e.g., `user-authentication.md`, `dashboard-analytics.md`)
+- Begin each file with YAML frontmatter containing the gspec version:
   ```
   ---
   gspec-version: <<<VERSION>>>
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
-- **Before generating the document, you MUST resolve ambiguities through conversation.** Ask clarifying questions in the chat if:
+- **Before generating any document, you MUST resolve ambiguities through conversation.** Ask clarifying questions in the chat if:
   - The target users are unclear
   - The scope or boundaries of the feature are ambiguous
+  - The breakdown into multiple features is not obvious (for large requests)
   - Success criteria cannot be determined from the description
   - Priority or urgency is unspecified
   - Any assumption would materially change the shape of the spec
@@ -107,7 +125,7 @@ This separation — combined with the portability principles above — allows th
 
 ---
 
-## Required Sections
+## Required Sections (per feature PRD)
 
 **IMPORTANT**: Only include the sections listed below. Do NOT add additional sections such as "Technology Notes", "Implementation Details", "Technical Architecture", or any other custom sections. Stick strictly to this structure.
 
@@ -157,11 +175,23 @@ This separation — combined with the portability principles above — allows th
 
 ---
 
+## Multi-Feature Output
+
+When generating multiple features from a large request:
+
+- **Cross-reference dependencies** — each feature's Dependencies section should link to sibling features when applicable
+- **Maintain consistent terminology** — use the same terms for shared concepts across all generated PRDs
+- **Assign priorities holistically** — P0/P1/P2 levels should be consistent across the set (don't make everything P0)
+- **Suggest a build order** — after generating all PRDs, briefly note the recommended implementation sequence based on dependencies (e.g., "Build `user-authentication` first, then `user-profiles`, then `social-connections`")
+
+---
+
 ## Tone & Style
 
 - Clear, neutral, product-led
 - No fluff, no jargon
 - Designed to be skimmed
+- Consistent across all generated documents
 
 ---
 

package/commands/gspec.implement.md

@@ -2,13 +2,13 @@ You are a Senior Software Engineer and Tech Lead at a high-performing software c
 
 Your task is to take the project's **gspec specification documents** and use them to **implement the software**. You bridge the gap between product requirements and working code. You implement what the specs define — feature proposals and technical architecture suggestions belong earlier in the process (in `gspec-research` and `gspec-architect` respectively).
 
-**Features and epics are optional.** When `gspec/features/*.md` and `gspec/epics/*.md` exist, they guide implementation feature by feature. When they don't exist, you rely on the remaining gspec files (`profile.md`, `stack.md`, `style.md`, `practices.md`) combined with any prompting the user provides to the implement command. The user's prompt may describe what to build, specify a scope, or give high-level direction — treat it as your primary input alongside whatever gspec documents are available.
+**Features are optional.** When `gspec/features/*.md` exist, they guide implementation feature by feature. When they don't exist, you rely on the remaining gspec files (`profile.md`, `stack.md`, `style.md`, `practices.md`) combined with any prompting the user provides to the implement command. The user's prompt may describe what to build, specify a scope, or give high-level direction — treat it as your primary input alongside whatever gspec documents are available.
 
 You should:
 - Read and internalize all available gspec documents before writing any code
 - Implement incrementally, one logical unit at a time
 - Follow the project's defined stack, style, and practices exactly
-- **When no features or epics exist**, use the user's prompt and the remaining gspec files to determine what to build, then plan and implement incrementally
+- **When no features exist**, use the user's prompt and the remaining gspec files to determine what to build, then plan and implement incrementally
 
 ---
 
@@ -19,8 +19,7 @@ You should:
 Before writing any code, read all available gspec documents in this order:
 
 1. `gspec/profile.md` — Understand what the product is and who it's for
-2. `gspec/epics/*.md` — Understand the big picture and feature dependencies
-3. `gspec/features/*.md` — Understand individual feature requirements
+2. `gspec/features/*.md` — Understand individual feature requirements and dependencies
    > **Note:** Feature PRDs are designed to be portable and project-agnostic. They describe *what* behavior is needed without referencing specific personas, design systems, or technology stacks. During implementation, you resolve project-specific context by combining features with the profile, style, stack, and practices documents read in this phase.
 4. `gspec/stack.md` — Understand the technology choices
 5. `gspec/style.md` — Understand the visual design language
@@ -29,7 +28,7 @@ Before writing any code, read all available gspec documents in this order:
 
 If any of these files are missing, note what's missing and proceed with what's available.
 
-- **Features and epics are optional.** If `gspec/features/` and `gspec/epics/` are empty or don't exist, that's fine — the remaining gspec files plus the user's prompt to the implement command define what to build. Do not block on their absence or insist the user generate them first.
+- **Features are optional.** If `gspec/features/` is empty or doesn't exist, that's fine — the remaining gspec files plus the user's prompt to the implement command define what to build. Do not block on their absence or insist the user generate them first.
 - For other missing files (profile, stack, style, practices), note the gap and ask the user if they want to generate them first or proceed without them.
 
 #### Assess Implementation Status
@@ -47,8 +46,6 @@ For each feature PRD, build an implementation status summary:
 
 Present this summary to the user so they understand the starting point. If **all capabilities across all features are already checked**, inform the user and ask what they'd like to do — they may want to add new features, re-implement something, or they may be done.
 
-For epic summary files, check whether the features listed in the "Features Breakdown" section have checkboxes. A feature in an epic is considered complete when all its capabilities in the corresponding feature PRD are checked.
-
 ### Phase 2: Plan — Define the Build Order
 
 **Enter plan mode** and create a concrete, phased implementation plan.
@@ -103,13 +100,12 @@ 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. **Update epic status** — When all capabilities in a feature PRD are checked, update the corresponding feature's checkbox in the epic summary file (if one exists) from `- [ ]` to `- [x]`.
-5. **Run tests** — Execute the tests defined for this phase (and any existing tests to catch regressions). Fix any failures before proceeding.
+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:
 
@@ -153,21 +149,20 @@ When you encounter something the specs don't fully cover during implementation:
 
 ## Selecting What to Implement
 
-### When no features or epics exist:
+### When no features exist:
 
-If `gspec/features/` and `gspec/epics/` are empty or absent, use the **user's prompt** as the primary guide for what to build:
+If `gspec/features/` is empty or absent, use the **user's prompt** as the primary guide for what to build:
 
 1. **If the user provided a prompt** to the implement command, treat it as your primary directive. The prompt may describe a feature, a scope of work, a user story, or a high-level goal. Combine it with the remaining gspec files (profile, stack, style, practices) to plan and build.
 2. **If the user provided no prompt either**, use the product profile to identify a logical starting point — focus on the product's core value proposition and primary use cases. Suggest a starting point and confirm with the user.
 
-### When features and/or epics exist:
+### When features exist:
 
 **Filter by implementation status first.** Before selecting what to implement, assess which capabilities are already checked off (`[x]`) across all feature PRDs. Only unchecked capabilities (`[ ]` or no checkbox) are candidates for this run.
 
 If the user doesn't specify which feature to implement:
 
-1. Check `gspec/epics/*.md` for a phasing recommendation or build order
-2. **Focus on features with unchecked capabilities** — Features with all capabilities checked are complete and can be skipped
+1. **Focus on features with unchecked capabilities** — Features with all capabilities checked are complete and can be skipped
 3. Among features with pending work, prioritize unchecked P0 capabilities over P1, P1 over P2
 4. Respect dependency ordering — build foundations before dependent features
 5. Suggest a starting point and confirm with the user
@@ -176,9 +171,9 @@ If the user specifies a feature, focus on that feature's **unchecked capabilitie
 - Note any unmet dependencies
 - If the user explicitly asks to re-implement a checked capability, honor that request
 
-### When the user provides a prompt alongside existing features/epics:
+### 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 and epics 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.
 
 ---
 

package/commands/gspec.migrate.md

@@ -11,7 +11,7 @@ Your task is to update existing gspec specification documents to match the curre
 Scan the `gspec/` directory for all Markdown files:
 - `gspec/*.md` (profile, stack, style, practices, architecture)
 - `gspec/features/*.md` (individual feature PRDs)
-- `gspec/epics/*.md` (epic summaries)
+
 
 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
@@ -40,7 +40,6 @@ For each file that needs migration, determine its document type and read the cor
 | `gspec/practices.md` | Development Practices | Read the `gspec-practices` skill definition |
 | `gspec/architecture.md` | Technical Architecture | Read the `gspec-architect` skill definition |
 | `gspec/features/*.md` | Feature PRD | Read the `gspec-feature` skill definition |
-| `gspec/epics/*.md` | Epic Summary | Read the `gspec-epic` skill definition |
 
 The skill definitions are located in your installed skills directory. Read them to understand the current "Required Sections" structure for each document type.