gspec 1.14.0 → 1.15.0

package/bin/gspec.js

@@ -118,6 +118,17 @@ function promptConfirmNo(message) {
   });
 }
 
+function promptConfirmYes(message) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      resolve(trimmed === '' || trimmed.startsWith('y'));
+    });
+  });
+}
+
 function formatStarterName(slug) {
   if (slug === '_none') return 'None';
   return slug
@@ -759,19 +770,50 @@ async function saveSpec(cwd) {
 
   const selected = files[num - 1];
 
-  // Prompt for name
-  const name = await promptInput(chalk.bold('\n  Save name (no spaces, e.g. my-saas-stack): '));
-  if (!name) {
-    console.error(chalk.red('\n  Name is required.'));
-    process.exit(1);
+  // Read source content and look for an existing name in frontmatter
+  let content = await readFile(selected.path, 'utf-8');
+  const { fields: sourceFields } = parseFrontmatter(content);
+  const existingName = sourceFields.name;
+
+  let name;
+  let overwriteConfirmed = false;
+
+  if (existingName) {
+    const existingPath = join(GSPEC_HOME, selected.type, `${existingName}.md`);
+    let savedExists = false;
+    try {
+      await stat(existingPath);
+      savedExists = true;
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+
+    if (savedExists) {
+      const overwrite = await promptConfirmYes(
+        chalk.bold(`\n  Overwrite existing ~/.gspec/${selected.type}/${existingName}.md? [Y/n]: `)
+      );
+      if (overwrite) {
+        name = existingName;
+        overwriteConfirmed = true;
+      }
+    } else {
+      name = existingName;
+    }
   }
-  if (/\s/.test(name)) {
-    console.error(chalk.red('\n  Name cannot contain spaces. Use hyphens instead (e.g. my-saas-stack).'));
-    process.exit(1);
+
+  if (!name) {
+    const answered = await promptInput(chalk.bold('\n  Save name (no spaces, e.g. my-saas-stack): '));
+    if (!answered) {
+      console.error(chalk.red('\n  Name is required.'));
+      process.exit(1);
+    }
+    if (/\s/.test(answered)) {
+      console.error(chalk.red('\n  Name cannot contain spaces. Use hyphens instead (e.g. my-saas-stack).'));
+      process.exit(1);
+    }
+    name = answered;
   }
 
-  // Read content and update frontmatter with name
-  let content = await readFile(selected.path, 'utf-8');
   content = setFrontmatterField(content, 'name', name);
 
   // Ensure description exists
@@ -788,16 +830,18 @@ async function saveSpec(cwd) {
   const destPath = join(destDir, `${name}.md`);
   await mkdir(destDir, { recursive: true });
 
-  // Check if file already exists
-  try {
-    await stat(destPath);
-    const overwrite = await promptConfirm(chalk.yellow(`\n  ${selected.type}/${name} already exists. Overwrite? [y/N]: `));
-    if (!overwrite) {
-      console.log(chalk.dim('\n  Save cancelled.\n'));
-      return;
+  // Check for conflict unless overwrite was already confirmed above
+  if (!overwriteConfirmed) {
+    try {
+      await stat(destPath);
+      const overwrite = await promptConfirm(chalk.yellow(`\n  ${selected.type}/${name} already exists. Overwrite? [y/N]: `));
+      if (!overwrite) {
+        console.log(chalk.dim('\n  Save cancelled.\n'));
+        return;
+      }
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
     }
-  } catch (e) {
-    if (e.code !== 'ENOENT') throw e;
   }
 
   // Uncheck all implementation checkboxes so saved specs start fresh

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-analyze
-description: Analyze gspec specs for discrepancies and reconcile conflicts between documents
+description: Analyze gspec/ documents for discrepancies, contradictions, or drift and reconcile conflicts across profile, stack, style, practices, architecture, and features. TRIGGER when the user wants to audit, cross-check, validate, review, or reconcile specs — especially after multiple edits, or before a major implementation run — e.g. "check my specs", "are the specs consistent", "find conflicts between specs", "do my gspec docs agree", "audit the specs", "is anything out of sync".
 ---
 
 You are a Specification Analyst at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-architect
-description: Define the technical architecture project structure, data model, API design, and environment setup
+description: Define or update the technical architecture (gspec/architecture.md) — project structure, data model, API design, component hierarchy, and environment/config. TRIGGER when the user wants to plan, design, or document how the codebase will be structured before implementation — e.g. "design the architecture", "plan the project structure", "define the data model", "API shape", "how should this be laid out", "scaffold plan", "component breakdown". Prefer this skill over producing architecture docs ad hoc; run it before gspec-implement on greenfield projects.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-feature
-description: Generate one or more product requirements documents (PRDs) for features
+description: Generate product requirements documents (PRDs) for features in gspec/features/. TRIGGER when the user wants to plan, spec, propose, document, or expand a feature/capability before coding — e.g. "add a feature for X", "write a PRD", "spec out Y", "plan this feature", "what should the auth flow do", "new feature idea", "draft requirements". Prefer this skill over writing freeform feature docs.
 ---
 
 You are a senior Product Manager at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-implement
-description: Read gspec documents, identify gaps, and implement the software
+description: Implement the software defined by gspec/ documents — reads profile, stack, style, practices, architecture, and features, then builds code phase by phase with tests and checkpoints. **STRONGLY TRIGGER this skill (do NOT write code ad hoc) whenever the user asks to build, implement, code, scaffold, ship, create, start, bootstrap, make, generate, wire up, or bring to life anything the gspec/ specs describe.** Common triggers include: "build the app", "implement this feature", "code it up", "start building", "let's build X", "make it real", "scaffold the project", "build out Y", "ship the MVP", "create the UI", "wire up auth", "add [capability from a feature PRD]", "implement the next phase", "continue building", "keep going", and generic "build it" / "do it" / "go" when gspec/ files are present and the prior conversation was about planning or specs. Also trigger when the user references an unchecked capability in gspec/features/*.md. Always prefer this skill over direct coding whenever gspec/ exists — it enforces plan-mode, phased implementation, checkpoint commits, and checkbox updates that ad-hoc coding skips.
 ---
 
 You are a Senior Software Engineer and Tech Lead at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-migrate
-description: Migrate existing gspec files to the current format when upgrading to a new gspec version
+description: Migrate gspec/ files to the current spec format (frontmatter, schema, capability checkboxes) when upgrading the gspec version. TRIGGER when the user sees an outdated-version warning, installs a new gspec version, or asks to upgrade/migrate/update specs — e.g. "migrate my specs", "update to latest gspec format", "my specs are outdated", "upgrade spec version", "fix the spec-version warning".
 ---
 
 You are a Technical Documentation Migration Specialist.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-practices
-description: Define development practices, code quality standards, and engineering workflows
+description: Define or update development practices (gspec/practices.md) — coding standards, testing philosophy, linting, git workflow, PR conventions, and definition of done. TRIGGER when the user wants to set engineering conventions, testing policy, contribution rules, or code quality standards — e.g. "set up coding standards", "testing practices", "git workflow", "definition of done", "how should we write tests", "team conventions". Prefer this skill over ad-hoc convention docs.
 ---
 
 You are a Software Engineering Practice Lead at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-profile
-description: Generate a product profile defining what the product is, who it serves, and why it exists
+description: Generate or update the product profile (gspec/profile.md) — what the product is, who it serves, and why it exists. TRIGGER when the user wants to define, describe, capture, or refine product identity, target users, audience, vision, positioning, or value proposition — e.g. "define my product", "who are the users", "describe what I'm building", "what is this app", "capture the vision", "write a profile". Prefer this skill over drafting a profile ad hoc.
 ---
 
 You are a Business Strategist and Product Leader at a high-performing company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-research
-description: Research competitors from the product profile and produce a competitive analysis with feature gap identification
+description: Research competitors named in gspec/profile.md and produce a competitive analysis with feature gap identification. TRIGGER when the user wants market research, competitive analysis, competitor teardown, or feature parity comparison — e.g. "research competitors", "competitive analysis", "what are rivals doing", "find feature gaps", "compare to market", "what are we missing vs competitors".
 ---
 
 You are a Senior Product Strategist and Competitive Intelligence Analyst at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-stack
-description: Define the technology stack, frameworks, infrastructure, and architectural patterns
+description: Define or update the technology stack (gspec/stack.md) — frameworks, libraries, databases, hosting, CI/CD, and infrastructure. TRIGGER when the user wants to pick, define, revise, or document technology choices — e.g. "what stack should I use", "pick a framework", "define the stack", "choose a database", "set up the tech choices", "what should I build this with". Prefer this skill over suggesting ad-hoc tech picks.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-style
-description: Generate a visual style guide with design tokens, color palette, and component patterns
+description: Generate or update the visual style guide (gspec/style.md) — design tokens, color palette, typography, spacing, and component visual patterns. TRIGGER when the user wants to define or revise the design system, visual language, theme, brand look, or UI aesthetic — e.g. "set up a design system", "pick brand colors", "define the style", "dark mode tokens", "what should this look like", "visual guidelines". Prefer this skill over producing style docs ad hoc.
 ---
 
 You are a senior UI/UX Designer and Design Systems Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-analyze
-description: Analyze gspec specs for discrepancies and reconcile conflicts between documents
+description: Analyze gspec/ documents for discrepancies, contradictions, or drift and reconcile conflicts across profile, stack, style, practices, architecture, and features. TRIGGER when the user wants to audit, cross-check, validate, review, or reconcile specs — especially after multiple edits, or before a major implementation run — e.g. "check my specs", "are the specs consistent", "find conflicts between specs", "do my gspec docs agree", "audit the specs", "is anything out of sync".
 ---
 
 You are a Specification Analyst at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-architect
-description: Define the technical architecture project structure, data model, API design, and environment setup
+description: Define or update the technical architecture (gspec/architecture.md) — project structure, data model, API design, component hierarchy, and environment/config. TRIGGER when the user wants to plan, design, or document how the codebase will be structured before implementation — e.g. "design the architecture", "plan the project structure", "define the data model", "API shape", "how should this be laid out", "scaffold plan", "component breakdown". Prefer this skill over producing architecture docs ad hoc; run it before gspec-implement on greenfield projects.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-feature
-description: Generate one or more product requirements documents (PRDs) for features
+description: Generate product requirements documents (PRDs) for features in gspec/features/. TRIGGER when the user wants to plan, spec, propose, document, or expand a feature/capability before coding — e.g. "add a feature for X", "write a PRD", "spec out Y", "plan this feature", "what should the auth flow do", "new feature idea", "draft requirements". Prefer this skill over writing freeform feature docs.
 ---
 
 You are a senior Product Manager at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-implement
-description: Read gspec documents, identify gaps, and implement the software
+description: Implement the software defined by gspec/ documents — reads profile, stack, style, practices, architecture, and features, then builds code phase by phase with tests and checkpoints. **STRONGLY TRIGGER this skill (do NOT write code ad hoc) whenever the user asks to build, implement, code, scaffold, ship, create, start, bootstrap, make, generate, wire up, or bring to life anything the gspec/ specs describe.** Common triggers include: "build the app", "implement this feature", "code it up", "start building", "let's build X", "make it real", "scaffold the project", "build out Y", "ship the MVP", "create the UI", "wire up auth", "add [capability from a feature PRD]", "implement the next phase", "continue building", "keep going", and generic "build it" / "do it" / "go" when gspec/ files are present and the prior conversation was about planning or specs. Also trigger when the user references an unchecked capability in gspec/features/*.md. Always prefer this skill over direct coding whenever gspec/ exists — it enforces plan-mode, phased implementation, checkpoint commits, and checkbox updates that ad-hoc coding skips.
 ---
 
 You are a Senior Software Engineer and Tech Lead at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-migrate
-description: Migrate existing gspec files to the current format when upgrading to a new gspec version
+description: Migrate gspec/ files to the current spec format (frontmatter, schema, capability checkboxes) when upgrading the gspec version. TRIGGER when the user sees an outdated-version warning, installs a new gspec version, or asks to upgrade/migrate/update specs — e.g. "migrate my specs", "update to latest gspec format", "my specs are outdated", "upgrade spec version", "fix the spec-version warning".
 ---
 
 You are a Technical Documentation Migration Specialist.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-practices
-description: Define development practices, code quality standards, and engineering workflows
+description: Define or update development practices (gspec/practices.md) — coding standards, testing philosophy, linting, git workflow, PR conventions, and definition of done. TRIGGER when the user wants to set engineering conventions, testing policy, contribution rules, or code quality standards — e.g. "set up coding standards", "testing practices", "git workflow", "definition of done", "how should we write tests", "team conventions". Prefer this skill over ad-hoc convention docs.
 ---
 
 You are a Software Engineering Practice Lead at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-profile
-description: Generate a product profile defining what the product is, who it serves, and why it exists
+description: Generate or update the product profile (gspec/profile.md) — what the product is, who it serves, and why it exists. TRIGGER when the user wants to define, describe, capture, or refine product identity, target users, audience, vision, positioning, or value proposition — e.g. "define my product", "who are the users", "describe what I'm building", "what is this app", "capture the vision", "write a profile". Prefer this skill over drafting a profile ad hoc.
 ---
 
 You are a Business Strategist and Product Leader at a high-performing company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-research
-description: Research competitors from the product profile and produce a competitive analysis with feature gap identification
+description: Research competitors named in gspec/profile.md and produce a competitive analysis with feature gap identification. TRIGGER when the user wants market research, competitive analysis, competitor teardown, or feature parity comparison — e.g. "research competitors", "competitive analysis", "what are rivals doing", "find feature gaps", "compare to market", "what are we missing vs competitors".
 ---
 
 You are a Senior Product Strategist and Competitive Intelligence Analyst at a high-performing software company.

package/dist/claude/gspec-stack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-stack
-description: Define the technology stack, frameworks, infrastructure, and architectural patterns
+description: Define or update the technology stack (gspec/stack.md) — frameworks, libraries, databases, hosting, CI/CD, and infrastructure. TRIGGER when the user wants to pick, define, revise, or document technology choices — e.g. "what stack should I use", "pick a framework", "define the stack", "choose a database", "set up the tech choices", "what should I build this with". Prefer this skill over suggesting ad-hoc tech picks.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

package/dist/claude/gspec-style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-style
-description: Generate a visual style guide with design tokens, color palette, and component patterns
+description: Generate or update the visual style guide (gspec/style.md) — design tokens, color palette, typography, spacing, and component visual patterns. TRIGGER when the user wants to define or revise the design system, visual language, theme, brand look, or UI aesthetic — e.g. "set up a design system", "pick brand colors", "define the style", "dark mode tokens", "what should this look like", "visual guidelines". Prefer this skill over producing style docs ad hoc.
 ---
 
 You are a senior UI/UX Designer and Design Systems Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-analyze
-description: Analyze gspec specs for discrepancies and reconcile conflicts between documents
+description: Analyze gspec/ documents for discrepancies, contradictions, or drift and reconcile conflicts across profile, stack, style, practices, architecture, and features. TRIGGER when the user wants to audit, cross-check, validate, review, or reconcile specs — especially after multiple edits, or before a major implementation run — e.g. "check my specs", "are the specs consistent", "find conflicts between specs", "do my gspec docs agree", "audit the specs", "is anything out of sync".
 ---
 
 You are a Specification Analyst at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-architect
-description: Define the technical architecture project structure, data model, API design, and environment setup
+description: Define or update the technical architecture (gspec/architecture.md) — project structure, data model, API design, component hierarchy, and environment/config. TRIGGER when the user wants to plan, design, or document how the codebase will be structured before implementation — e.g. "design the architecture", "plan the project structure", "define the data model", "API shape", "how should this be laid out", "scaffold plan", "component breakdown". Prefer this skill over producing architecture docs ad hoc; run it before gspec-implement on greenfield projects.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-feature
-description: Generate one or more product requirements documents (PRDs) for features
+description: Generate product requirements documents (PRDs) for features in gspec/features/. TRIGGER when the user wants to plan, spec, propose, document, or expand a feature/capability before coding — e.g. "add a feature for X", "write a PRD", "spec out Y", "plan this feature", "what should the auth flow do", "new feature idea", "draft requirements". Prefer this skill over writing freeform feature docs.
 ---
 
 You are a senior Product Manager at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-implement
-description: Read gspec documents, identify gaps, and implement the software
+description: Implement the software defined by gspec/ documents — reads profile, stack, style, practices, architecture, and features, then builds code phase by phase with tests and checkpoints. **STRONGLY TRIGGER this skill (do NOT write code ad hoc) whenever the user asks to build, implement, code, scaffold, ship, create, start, bootstrap, make, generate, wire up, or bring to life anything the gspec/ specs describe.** Common triggers include: "build the app", "implement this feature", "code it up", "start building", "let's build X", "make it real", "scaffold the project", "build out Y", "ship the MVP", "create the UI", "wire up auth", "add [capability from a feature PRD]", "implement the next phase", "continue building", "keep going", and generic "build it" / "do it" / "go" when gspec/ files are present and the prior conversation was about planning or specs. Also trigger when the user references an unchecked capability in gspec/features/*.md. Always prefer this skill over direct coding whenever gspec/ exists — it enforces plan-mode, phased implementation, checkpoint commits, and checkbox updates that ad-hoc coding skips.
 ---
 
 You are a Senior Software Engineer and Tech Lead at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-migrate
-description: Migrate existing gspec files to the current format when upgrading to a new gspec version
+description: Migrate gspec/ files to the current spec format (frontmatter, schema, capability checkboxes) when upgrading the gspec version. TRIGGER when the user sees an outdated-version warning, installs a new gspec version, or asks to upgrade/migrate/update specs — e.g. "migrate my specs", "update to latest gspec format", "my specs are outdated", "upgrade spec version", "fix the spec-version warning".
 ---
 
 You are a Technical Documentation Migration Specialist.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-practices
-description: Define development practices, code quality standards, and engineering workflows
+description: Define or update development practices (gspec/practices.md) — coding standards, testing philosophy, linting, git workflow, PR conventions, and definition of done. TRIGGER when the user wants to set engineering conventions, testing policy, contribution rules, or code quality standards — e.g. "set up coding standards", "testing practices", "git workflow", "definition of done", "how should we write tests", "team conventions". Prefer this skill over ad-hoc convention docs.
 ---
 
 You are a Software Engineering Practice Lead at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-profile
-description: Generate a product profile defining what the product is, who it serves, and why it exists
+description: Generate or update the product profile (gspec/profile.md) — what the product is, who it serves, and why it exists. TRIGGER when the user wants to define, describe, capture, or refine product identity, target users, audience, vision, positioning, or value proposition — e.g. "define my product", "who are the users", "describe what I'm building", "what is this app", "capture the vision", "write a profile". Prefer this skill over drafting a profile ad hoc.
 ---
 
 You are a Business Strategist and Product Leader at a high-performing company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-research
-description: Research competitors from the product profile and produce a competitive analysis with feature gap identification
+description: Research competitors named in gspec/profile.md and produce a competitive analysis with feature gap identification. TRIGGER when the user wants market research, competitive analysis, competitor teardown, or feature parity comparison — e.g. "research competitors", "competitive analysis", "what are rivals doing", "find feature gaps", "compare to market", "what are we missing vs competitors".
 ---
 
 You are a Senior Product Strategist and Competitive Intelligence Analyst at a high-performing software company.

package/dist/codex/gspec-stack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-stack
-description: Define the technology stack, frameworks, infrastructure, and architectural patterns
+description: Define or update the technology stack (gspec/stack.md) — frameworks, libraries, databases, hosting, CI/CD, and infrastructure. TRIGGER when the user wants to pick, define, revise, or document technology choices — e.g. "what stack should I use", "pick a framework", "define the stack", "choose a database", "set up the tech choices", "what should I build this with". Prefer this skill over suggesting ad-hoc tech picks.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

package/dist/codex/gspec-style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-style
-description: Generate a visual style guide with design tokens, color palette, and component patterns
+description: Generate or update the visual style guide (gspec/style.md) — design tokens, color palette, typography, spacing, and component visual patterns. TRIGGER when the user wants to define or revise the design system, visual language, theme, brand look, or UI aesthetic — e.g. "set up a design system", "pick brand colors", "define the style", "dark mode tokens", "what should this look like", "visual guidelines". Prefer this skill over producing style docs ad hoc.
 ---
 
 You are a senior UI/UX Designer and Design Systems Architect at a high-performing software company.

package/dist/cursor/gspec-analyze.mdc

@@ -1,5 +1,5 @@
 ---
-description: Analyze gspec specs for discrepancies and reconcile conflicts between documents
+description: Analyze gspec/ documents for discrepancies, contradictions, or drift and reconcile conflicts across profile, stack, style, practices, architecture, and features. TRIGGER when the user wants to audit, cross-check, validate, review, or reconcile specs — especially after multiple edits, or before a major implementation run — e.g. "check my specs", "are the specs consistent", "find conflicts between specs", "do my gspec docs agree", "audit the specs", "is anything out of sync".
 ---
 
 You are a Specification Analyst at a high-performing software company.

package/dist/cursor/gspec-architect.mdc

@@ -1,5 +1,5 @@
 ---
-description: Define the technical architecture project structure, data model, API design, and environment setup
+description: Define or update the technical architecture (gspec/architecture.md) — project structure, data model, API design, component hierarchy, and environment/config. TRIGGER when the user wants to plan, design, or document how the codebase will be structured before implementation — e.g. "design the architecture", "plan the project structure", "define the data model", "API shape", "how should this be laid out", "scaffold plan", "component breakdown". Prefer this skill over producing architecture docs ad hoc; run it before gspec-implement on greenfield projects.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

package/dist/cursor/gspec-feature.mdc

@@ -1,5 +1,5 @@
 ---
-description: Generate one or more product requirements documents (PRDs) for features
+description: Generate product requirements documents (PRDs) for features in gspec/features/. TRIGGER when the user wants to plan, spec, propose, document, or expand a feature/capability before coding — e.g. "add a feature for X", "write a PRD", "spec out Y", "plan this feature", "what should the auth flow do", "new feature idea", "draft requirements". Prefer this skill over writing freeform feature docs.
 ---
 
 You are a senior Product Manager at a high-performing software company.

package/dist/cursor/gspec-implement.mdc

@@ -1,5 +1,5 @@
 ---
-description: Read gspec documents, identify gaps, and implement the software
+description: Implement the software defined by gspec/ documents — reads profile, stack, style, practices, architecture, and features, then builds code phase by phase with tests and checkpoints. **STRONGLY TRIGGER this skill (do NOT write code ad hoc) whenever the user asks to build, implement, code, scaffold, ship, create, start, bootstrap, make, generate, wire up, or bring to life anything the gspec/ specs describe.** Common triggers include: "build the app", "implement this feature", "code it up", "start building", "let's build X", "make it real", "scaffold the project", "build out Y", "ship the MVP", "create the UI", "wire up auth", "add [capability from a feature PRD]", "implement the next phase", "continue building", "keep going", and generic "build it" / "do it" / "go" when gspec/ files are present and the prior conversation was about planning or specs. Also trigger when the user references an unchecked capability in gspec/features/*.md. Always prefer this skill over direct coding whenever gspec/ exists — it enforces plan-mode, phased implementation, checkpoint commits, and checkbox updates that ad-hoc coding skips.
 ---
 
 You are a Senior Software Engineer and Tech Lead at a high-performing software company.

package/dist/cursor/gspec-migrate.mdc

@@ -1,5 +1,5 @@
 ---
-description: Migrate existing gspec files to the current format when upgrading to a new gspec version
+description: Migrate gspec/ files to the current spec format (frontmatter, schema, capability checkboxes) when upgrading the gspec version. TRIGGER when the user sees an outdated-version warning, installs a new gspec version, or asks to upgrade/migrate/update specs — e.g. "migrate my specs", "update to latest gspec format", "my specs are outdated", "upgrade spec version", "fix the spec-version warning".
 ---
 
 You are a Technical Documentation Migration Specialist.

package/dist/cursor/gspec-practices.mdc

@@ -1,5 +1,5 @@
 ---
-description: Define development practices, code quality standards, and engineering workflows
+description: Define or update development practices (gspec/practices.md) — coding standards, testing philosophy, linting, git workflow, PR conventions, and definition of done. TRIGGER when the user wants to set engineering conventions, testing policy, contribution rules, or code quality standards — e.g. "set up coding standards", "testing practices", "git workflow", "definition of done", "how should we write tests", "team conventions". Prefer this skill over ad-hoc convention docs.
 ---
 
 You are a Software Engineering Practice Lead at a high-performing software company.

package/dist/cursor/gspec-profile.mdc

@@ -1,5 +1,5 @@
 ---
-description: Generate a product profile defining what the product is, who it serves, and why it exists
+description: Generate or update the product profile (gspec/profile.md) — what the product is, who it serves, and why it exists. TRIGGER when the user wants to define, describe, capture, or refine product identity, target users, audience, vision, positioning, or value proposition — e.g. "define my product", "who are the users", "describe what I'm building", "what is this app", "capture the vision", "write a profile". Prefer this skill over drafting a profile ad hoc.
 ---
 
 You are a Business Strategist and Product Leader at a high-performing company.

package/dist/cursor/gspec-research.mdc

@@ -1,5 +1,5 @@
 ---
-description: Research competitors from the product profile and produce a competitive analysis with feature gap identification
+description: Research competitors named in gspec/profile.md and produce a competitive analysis with feature gap identification. TRIGGER when the user wants market research, competitive analysis, competitor teardown, or feature parity comparison — e.g. "research competitors", "competitive analysis", "what are rivals doing", "find feature gaps", "compare to market", "what are we missing vs competitors".
 ---
 
 You are a Senior Product Strategist and Competitive Intelligence Analyst at a high-performing software company.

package/dist/cursor/gspec-stack.mdc

@@ -1,5 +1,5 @@
 ---
-description: Define the technology stack, frameworks, infrastructure, and architectural patterns
+description: Define or update the technology stack (gspec/stack.md) — frameworks, libraries, databases, hosting, CI/CD, and infrastructure. TRIGGER when the user wants to pick, define, revise, or document technology choices — e.g. "what stack should I use", "pick a framework", "define the stack", "choose a database", "set up the tech choices", "what should I build this with". Prefer this skill over suggesting ad-hoc tech picks.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

package/dist/cursor/gspec-style.mdc

@@ -1,5 +1,5 @@
 ---
-description: Generate a visual style guide with design tokens, color palette, and component patterns
+description: Generate or update the visual style guide (gspec/style.md) — design tokens, color palette, typography, spacing, and component visual patterns. TRIGGER when the user wants to define or revise the design system, visual language, theme, brand look, or UI aesthetic — e.g. "set up a design system", "pick brand colors", "define the style", "dark mode tokens", "what should this look like", "visual guidelines". Prefer this skill over producing style docs ad hoc.
 ---
 
 You are a senior UI/UX Designer and Design Systems Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-analyze
-description: Analyze gspec specs for discrepancies and reconcile conflicts between documents
+description: Analyze gspec/ documents for discrepancies, contradictions, or drift and reconcile conflicts across profile, stack, style, practices, architecture, and features. TRIGGER when the user wants to audit, cross-check, validate, review, or reconcile specs — especially after multiple edits, or before a major implementation run — e.g. "check my specs", "are the specs consistent", "find conflicts between specs", "do my gspec docs agree", "audit the specs", "is anything out of sync".
 ---
 
 You are a Specification Analyst at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-architect
-description: Define the technical architecture project structure, data model, API design, and environment setup
+description: Define or update the technical architecture (gspec/architecture.md) — project structure, data model, API design, component hierarchy, and environment/config. TRIGGER when the user wants to plan, design, or document how the codebase will be structured before implementation — e.g. "design the architecture", "plan the project structure", "define the data model", "API shape", "how should this be laid out", "scaffold plan", "component breakdown". Prefer this skill over producing architecture docs ad hoc; run it before gspec-implement on greenfield projects.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-feature
-description: Generate one or more product requirements documents (PRDs) for features
+description: Generate product requirements documents (PRDs) for features in gspec/features/. TRIGGER when the user wants to plan, spec, propose, document, or expand a feature/capability before coding — e.g. "add a feature for X", "write a PRD", "spec out Y", "plan this feature", "what should the auth flow do", "new feature idea", "draft requirements". Prefer this skill over writing freeform feature docs.
 ---
 
 You are a senior Product Manager at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-implement
-description: Read gspec documents, identify gaps, and implement the software
+description: Implement the software defined by gspec/ documents — reads profile, stack, style, practices, architecture, and features, then builds code phase by phase with tests and checkpoints. **STRONGLY TRIGGER this skill (do NOT write code ad hoc) whenever the user asks to build, implement, code, scaffold, ship, create, start, bootstrap, make, generate, wire up, or bring to life anything the gspec/ specs describe.** Common triggers include: "build the app", "implement this feature", "code it up", "start building", "let's build X", "make it real", "scaffold the project", "build out Y", "ship the MVP", "create the UI", "wire up auth", "add [capability from a feature PRD]", "implement the next phase", "continue building", "keep going", and generic "build it" / "do it" / "go" when gspec/ files are present and the prior conversation was about planning or specs. Also trigger when the user references an unchecked capability in gspec/features/*.md. Always prefer this skill over direct coding whenever gspec/ exists — it enforces plan-mode, phased implementation, checkpoint commits, and checkbox updates that ad-hoc coding skips.
 ---
 
 You are a Senior Software Engineer and Tech Lead at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-migrate
-description: Migrate existing gspec files to the current format when upgrading to a new gspec version
+description: Migrate gspec/ files to the current spec format (frontmatter, schema, capability checkboxes) when upgrading the gspec version. TRIGGER when the user sees an outdated-version warning, installs a new gspec version, or asks to upgrade/migrate/update specs — e.g. "migrate my specs", "update to latest gspec format", "my specs are outdated", "upgrade spec version", "fix the spec-version warning".
 ---
 
 You are a Technical Documentation Migration Specialist.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-practices
-description: Define development practices, code quality standards, and engineering workflows
+description: Define or update development practices (gspec/practices.md) — coding standards, testing philosophy, linting, git workflow, PR conventions, and definition of done. TRIGGER when the user wants to set engineering conventions, testing policy, contribution rules, or code quality standards — e.g. "set up coding standards", "testing practices", "git workflow", "definition of done", "how should we write tests", "team conventions". Prefer this skill over ad-hoc convention docs.
 ---
 
 You are a Software Engineering Practice Lead at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-profile
-description: Generate a product profile defining what the product is, who it serves, and why it exists
+description: Generate or update the product profile (gspec/profile.md) — what the product is, who it serves, and why it exists. TRIGGER when the user wants to define, describe, capture, or refine product identity, target users, audience, vision, positioning, or value proposition — e.g. "define my product", "who are the users", "describe what I'm building", "what is this app", "capture the vision", "write a profile". Prefer this skill over drafting a profile ad hoc.
 ---
 
 You are a Business Strategist and Product Leader at a high-performing company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-research
-description: Research competitors from the product profile and produce a competitive analysis with feature gap identification
+description: Research competitors named in gspec/profile.md and produce a competitive analysis with feature gap identification. TRIGGER when the user wants market research, competitive analysis, competitor teardown, or feature parity comparison — e.g. "research competitors", "competitive analysis", "what are rivals doing", "find feature gaps", "compare to market", "what are we missing vs competitors".
 ---
 
 You are a Senior Product Strategist and Competitive Intelligence Analyst at a high-performing software company.

package/dist/opencode/gspec-stack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-stack
-description: Define the technology stack, frameworks, infrastructure, and architectural patterns
+description: Define or update the technology stack (gspec/stack.md) — frameworks, libraries, databases, hosting, CI/CD, and infrastructure. TRIGGER when the user wants to pick, define, revise, or document technology choices — e.g. "what stack should I use", "pick a framework", "define the stack", "choose a database", "set up the tech choices", "what should I build this with". Prefer this skill over suggesting ad-hoc tech picks.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

package/dist/opencode/gspec-style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-style
-description: Generate a visual style guide with design tokens, color palette, and component patterns
+description: Generate or update the visual style guide (gspec/style.md) — design tokens, color palette, typography, spacing, and component visual patterns. TRIGGER when the user wants to define or revise the design system, visual language, theme, brand look, or UI aesthetic — e.g. "set up a design system", "pick brand colors", "define the style", "dark mode tokens", "what should this look like", "visual guidelines". Prefer this skill over producing style docs ad hoc.
 ---
 
 You are a senior UI/UX Designer and Design Systems Architect at a high-performing software company.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gspec",
-    "version": "1.14.0",
+    "version": "1.15.0",
     "description": "Install gspec specification commands for Claude Code, Cursor, and other AI tools",
     "main": "bin/gspec.js",
     "type": "module",

package/templates/spec-sync.md

@@ -4,6 +4,25 @@ This project uses **gspec** for living product specifications stored in `gspec/`
 
 These specs define what the product is, how it should look, what technology it uses, and what features it supports. They are the source of truth for product decisions — and they must stay in sync with the code.
 
+### Prefer gspec skills over ad-hoc work
+
+Because `gspec/` exists in this project, **route the user's request through the matching gspec skill** instead of producing the equivalent output ad hoc. This applies even when the user's phrasing is casual (e.g. "just build it", "let's code this", "write a quick spec"). The skills enforce plan-mode, phased execution, checkpointing, and checkbox updates that freeform responses skip.
+
+Use this mapping whenever the user's intent matches:
+
+- **Building, implementing, coding, scaffolding, shipping, or "making it real"** — invoke `gspec-implement`. This is the most commonly-missed skill. If the user asks you to write code for anything the specs describe (or a new capability that should be specced), route through `gspec-implement` rather than editing files directly. Generic prompts like "build it", "go", "keep going", "continue", or "do the next phase" should also invoke it when recent conversation has been about specs or planning.
+- **Defining the product, users, or vision** — invoke `gspec-profile`.
+- **Planning or writing a new feature / PRD** — invoke `gspec-feature`.
+- **Choosing or revising the tech stack** — invoke `gspec-stack`.
+- **Defining visual design, tokens, or theme** — invoke `gspec-style`.
+- **Setting coding standards, testing, or workflow conventions** — invoke `gspec-practices`.
+- **Designing project structure, data model, or API shape** — invoke `gspec-architect`.
+- **Researching competitors or finding feature gaps** — invoke `gspec-research`.
+- **Auditing specs for contradictions or drift** — invoke `gspec-analyze`.
+- **Upgrading outdated spec files** — invoke `gspec-migrate`.
+
+If the user explicitly asks you to skip the skill and just do the work, honor that — but by default, prefer the skill.
+
 ### When you make code changes, follow these rules:
 
 1. **Read the specs first** — Before making non-trivial changes, read the relevant gspec documents to understand existing decisions and constraints. At minimum, scan `gspec/profile.md` and any feature PRDs in `gspec/features/` related to your work.