gspec 1.13.2 → 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/commands/gspec.architect.md

@@ -29,7 +29,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 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.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -339,8 +339,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

package/commands/gspec.feature.md

@@ -163,8 +163,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

package/commands/gspec.research.md

@@ -154,7 +154,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: <<<SPEC_VERSION>>>\n---`

package/commands/gspec.stack.md

@@ -47,13 +47,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

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.
@@ -34,7 +34,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 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.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -344,8 +344,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

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.
@@ -168,8 +168,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

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.
@@ -159,7 +159,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

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.
@@ -52,13 +52,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

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.
@@ -34,7 +34,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 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.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -344,8 +344,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

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.
@@ -168,8 +168,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

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.
@@ -159,7 +159,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

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.
@@ -52,13 +52,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

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.
@@ -34,7 +34,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 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.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -344,8 +344,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

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.
@@ -168,8 +168,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

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.
@@ -159,7 +159,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

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.
@@ -52,13 +52,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

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.
@@ -33,7 +33,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 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.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -343,8 +343,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

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.
@@ -167,8 +167,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

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.
@@ -158,7 +158,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

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.
@@ -51,13 +51,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

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.
@@ -34,7 +34,7 @@ Before generating the architecture document, read **all** existing gspec documen
 4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
 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.
+All of these provide essential context. If any are missing, note the gap and ask the user to clarify before proceeding. If the user explicitly defers, make reasonable assumptions and record them in the Assumptions sub-section of the Technical Gap Analysis.
 
 ---
 
@@ -344,8 +344,9 @@ Examples of gaps to look for:
 - Technical decisions that were inferred rather than explicitly specified in existing specs
 
 ### 10. Open Decisions
-- Areas where the architecture may need to evolve as features are implemented
-- Questions that should be resolved before or during implementation
+- **All technical questions and decisions must be resolved by asking the user before the document is saved.** Do not save the architecture with unresolved questions.
+- If the user explicitly defers a decision, record it here with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
+- Areas where the architecture may need to evolve as features are implemented may be noted, but these must be acknowledged evolution points — not unresolved questions.
 
 ---
 

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.
@@ -168,8 +168,8 @@ This separation — combined with the portability principles above — allows th
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions — **only** unknowns that genuinely cannot be answered until implementation or real-world usage begins (e.g., performance thresholds pending benchmarking, exact rate limits pending load testing). Questions about scope, users, priorities, or feature design must be asked and resolved in the chat before the spec is written. If there are no open questions, omit this sub-section.
 - Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
+- **No open questions** — All questions must be resolved by asking the user in the chat before the spec is saved. If the user explicitly defers a question, record it as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit the sub-section entirely. Never embed unresolved questions in the document by default.
 
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working

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.
@@ -159,7 +159,7 @@ After writing `gspec/research.md`, ask the user:
    - Scope (in-scope goals, out-of-scope items, deferred ideas)
    - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability, each with 2-4 **acceptance criteria** as a sub-list)
    - Dependencies (on other features or external services)
-   - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
+   - Assumptions & Risks (assumptions, key risks and mitigations — all questions must be resolved in the chat before saving; only record explicitly deferred decisions)
    - Success Metrics
    - Implementation Context (standard portability note)
    - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`

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.
@@ -52,13 +52,8 @@ You should:
 - Deployment target (cloud, on-premise, hybrid)
 - Scale and performance requirements
 
-### 2. Open Questions & Clarifications
-**List any critical questions that need answers before finalizing technology choices**
-- Missing requirements that impact stack decisions
-- Unclear constraints or preferences
-- Team expertise or existing infrastructure questions
-- Budget or licensing considerations
-- **Mark as "None" if all information is clear**
+### 2. Clarifications
+**All questions that impact technology choices must be resolved by asking the user in the chat before the document is saved.** Do not save the stack spec with unresolved questions. If the user explicitly defers a decision, record it here as a "Deferred Decision" with context explaining what was deferred and why. If there are no deferred decisions, omit this section entirely.
 
 ### 3. Core Technology Stack
 

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.13.2",
+    "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,23 +4,44 @@ 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.
 
-2. **Update feature checkboxes** — When you implement a capability defined in a feature PRD (`gspec/features/*.md`), change its checkbox from `- [ ]` to `- [x]`.
+2. **Spec before you build** — If the user asks for a feature or capability that isn't covered by an existing feature PRD in `gspec/features/`, run the `gspec-feature` command to create a new feature PRD before implementing it. Every feature should be specified before it's built — don't skip straight to code.
+
+3. **Update feature checkboxes** — When you implement a capability defined in a feature PRD (`gspec/features/*.md`), change its checkbox from `- [ ]` to `- [x]`.
 
-3. **Update specs that your changes contradict** — If your code change makes a spec statement incorrect (e.g., you changed the data model, switched a dependency, altered a UI pattern, or added a new API endpoint), update the spec to reflect reality. Common candidates:
+4. **Update specs that your changes contradict** — If your code change makes a spec statement incorrect (e.g., you changed the data model, switched a dependency, altered a UI pattern, or added a new API endpoint), update the spec to reflect reality. Common candidates:
    - `gspec/architecture.md` — project structure, data model, API routes, component hierarchy
    - `gspec/stack.md` — dependencies, frameworks, infrastructure
    - `gspec/style.md` — design tokens, component styling, visual conventions
    - `gspec/practices.md` — coding standards, testing conventions, workflows
    - `gspec/profile.md` — product scope, target users, value proposition (rarely changes)
 
-4. **Be surgical** — Change only what is necessary. Preserve the existing voice, structure, and formatting of each spec document. Do not rewrite sections that are still accurate.
+5. **Be surgical** — Change only what is necessary. Preserve the existing voice, structure, and formatting of each spec document. Do not rewrite sections that are still accurate.
 
-5. **Announce spec updates** — When you update a spec, briefly mention what changed and why in your response. Never silently modify specs.
+6. **Announce spec updates** — When you update a spec, briefly mention what changed and why in your response. Never silently modify specs.
 
-6. **Preserve frontmatter** — gspec files use YAML frontmatter with a `spec-version` field. Preserve it when editing. If a file lacks frontmatter, leave it as-is.
+7. **Preserve frontmatter** — gspec files use YAML frontmatter with a `spec-version` field. Preserve it when editing. If a file lacks frontmatter, leave it as-is.
 
-7. **Don't create new foundation specs** — Only update existing spec files. If you believe a new spec document is needed, suggest it to the user rather than creating it yourself.
+8. **Don't create new foundation specs** — Only update existing spec files. If you believe a new spec document is needed, suggest it to the user rather than creating it yourself.