gspec 1.0.3 → 1.1.0

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

@@ -11,6 +11,29 @@ Generate multiple Product Requirements Documents (PRDs) from a high-level epic d
 
 Take the provided epic description (a large body of work) and break it down into **multiple focused Product Requirements Documents (PRDs)**, each representing a distinct feature or component that can be built independently.
 
+## Important: Agent-Oriented Documentation
+
+**These epics and PRDs are designed for automated agent consumption** (via `gspec-implement`), with humans validating the content for accuracy and completeness. Write documents that are:
+
+- **Implementation-ready blueprints**, not project plans
+- Focused on **what** to build and **why**, not **when** or **how long**
+- Clear on technical and functional requirements an agent needs to execute
+
+**AVOID project management details:**
+- ❌ Sprint planning, week numbers, or timeline estimates
+- ❌ Team assignments or resource allocation
+- ❌ Velocity or story point estimates
+- ❌ Delivery schedules or milestone dates
+- ❌ "Phase 1 ships in Q2" or similar calendar commitments
+
+**DO include implementation guidance:**
+- ✅ Clear functional requirements and acceptance criteria
+- ✅ Dependencies between features (technical, not temporal)
+- ✅ Priority levels (P0, P1, P2) for scope decisions
+- ✅ Build order recommendations based on technical dependencies
+- ✅ Minimum viable epic (MVE) scope definition
+- ✅ Feature sequencing based on what must be built first
+
 ## Guidelines
 
 - **Read existing gspec documents first** to ground the epic and its features in established product context
@@ -20,7 +43,7 @@ Take the provided epic description (a large body of work) and break it down into
 - Ensure features can be built incrementally and independently when possible
 - Consider dependencies between features
 - Focus on user value, scope, and outcomes
-- Write for product, design, and engineering audiences
+- Write for automated implementation with human validation
 - Be concise, structured, and decisive
 
 ---
@@ -46,6 +69,13 @@ If these files don't exist, proceed without them — they are optional context,
 - Output **multiple** Markdown documents (one per feature)
 - Save each file to the `gspec/features/` folder in the root of the project (create if it doesn't exist)
 - Name each file based on the feature (e.g., `user-authentication.md`, `dashboard-analytics.md`)
+- Begin every output file (both epic summary and individual feature PRDs) with YAML frontmatter containing the gspec version:
+  ```
+  ---
+  gspec-version: 1.1.0
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
 - **Before generating the documents**, ask clarifying questions if:
   - The target users are unclear
   - The scope or boundaries of the epic are ambiguous
@@ -60,18 +90,44 @@ If these files don't exist, proceed without them — they are optional context,
   - Links to each individual feature PRD
 - Avoid deep system architecture or low-level implementation
 - No code blocks except where examples add clarity
-- Clear acceptance criteria are required for each feature
+- Clear acceptance criteria are required for each capability
 - Make tradeoffs and scope explicit
 
+### Technology Agnosticism
+
+**IMPORTANT**: Epic and feature PRDs must remain technology-agnostic to enable implementation with different technology stacks. The `gspec/stack.md` file is the single source of truth for technology choices.
+
+**DO use generic architectural terms:**
+- ✅ "database", "data store", "persistent storage"
+- ✅ "authentication service", "IAM", "identity provider"
+- ✅ "API", "backend service", "server"
+- ✅ "frontend", "client application", "user interface"
+- ✅ "message queue", "event system", "pub/sub"
+- ✅ "object storage", "file storage"
+- ✅ "cache", "caching layer"
+- ✅ "search index", "full-text search"
+
+**DO NOT reference specific technologies:**
+- ❌ React, Vue, Angular, Svelte
+- ❌ PostgreSQL, MySQL, MongoDB, DynamoDB
+- ❌ AWS Lambda, Google Cloud Functions, Azure Functions
+- ❌ Redis, Memcached
+- ❌ Elasticsearch, Algolia, Solr
+- ❌ S3, GCS, Azure Blob Storage
+- ❌ Kafka, RabbitMQ, SQS
+
+This separation allows the same epic and feature specs to be implemented using different technology stacks by swapping the Stack file.
+
 ## Epic Summary Document Structure
 
+**IMPORTANT**: Only include the sections listed below. Do NOT add additional sections such as "Technology Notes", "Implementation Details", "Technical Architecture", or any other custom sections. Stick strictly to this structure.
+
 Create a file at `gspec/epics/[epic-name].md` with:
 
 ### 1. Epic Overview
 - Epic name
 - Executive summary
 - Strategic objective
-- Target timeline or phases
 
 ### 2. Features Breakdown
 - List of all features with links to their PRDs, **using unchecked markdown checkboxes** (e.g., `- [ ] **P0**: [Feature Name](../features/feature-name.md) — Brief description`). The `gspec-implement` command will check these off (`- [x]`) as features are fully implemented, allowing incremental runs.
@@ -97,58 +153,50 @@ Create a file at `gspec/epics/[epic-name].md` with:
 
 ## Individual Feature PRD Structure
 
+**IMPORTANT**: Only include the sections listed below. Do NOT add additional sections such as "Technology Notes", "Implementation Details", "Technical Architecture", or any other custom sections. Stick strictly to this structure.
+
 For each feature, create a separate file in `gspec/features/[feature-name].md` with:
 
 ### 1. Overview
 - Feature name
-- Summary
-- Objective
+- Summary (1-2 sentences)
+- Problem being solved and why it matters now
 - **Parent Epic** (link to epic summary)
 
-### 2. Problem & Context
-- User problem
-- Why this matters now
-- Current pain points
-- How this fits into the larger epic
-
-### 3. Goals & Non-Goals
-- In-scope goals
-- Explicitly out-of-scope items
-
-### 4. Users & Use Cases
+### 2. Users & Use Cases
 - Primary users
-- Key use cases
-
-### 5. Assumptions & Open Questions
-- Assumptions
-- Open questions (non-blocking)
+- Key use cases (3-4 scenarios showing how users benefit)
 
-### 6. Functional Requirements
-- Numbered requirements
-- Written in user-focused language
-- Clear acceptance criteria
-- **Priority level** for each requirement (P0 = must-have, P1 = should-have, P2 = nice-to-have)
-- **Use unchecked markdown checkboxes** for each requirement to enable implementation tracking (e.g., `- [ ] **P0**: FR-1 — User can create an account`). The `gspec-implement` command will check these off (`- [x]`) as requirements are implemented.
-
-### 7. User Experience Requirements
-- UX principles
-- Key flows (high level)
-- Empty and error states
-
-### 8. Success Metrics
-- How success is measured
-- Leading vs lagging indicators
-
-### 9. Dependencies
+### 3. Scope
+- In-scope goals
+- Out-of-scope items (things this feature explicitly won't do)
+- Deferred ideas (things we may do later, but not now)
+
+### 4. Capabilities
+- What the feature provides to users, written in user-focused language
+- **Priority level** for each capability (P0 = must-have, P1 = should-have, P2 = nice-to-have)
+- Focus on *what* users can do, not *how* they do it — include UX expectations (empty states, error handling, key flows) as acceptance criteria on the relevant capabilities
+- **Use unchecked markdown checkboxes** for each capability to enable implementation tracking (e.g., `- [ ] **P0**: User can create an account`). The `gspec-implement` command will check these off (`- [x]`) as capabilities are implemented, allowing incremental runs.
+- **Each capability MUST include brief acceptance criteria** — 2-4 testable conditions that define "done" for that capability. These tell the implementing agent exactly when a capability is complete and give test writers concrete assertions. Format as a sub-list under each capability:
+  ```
+  - [ ] **P0**: User can create an account
+    - Valid email + strong password → account is created and confirmation is sent
+    - Duplicate email → error message explains email is taken
+    - Weak password → inline validation shows password requirements
+  ```
+
+### 5. Dependencies
 - Dependencies on other features in this epic
 - External dependencies
+- If none, state "None"
 
-### 10. Risks & Mitigations
-- Product or delivery risks
-- Mitigation strategies
+### 6. Assumptions & Risks
+- Assumptions (what we're taking as true)
+- Open questions (non-blocking unknowns to resolve during implementation)
+- Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
 
-### 11. Future Considerations
-- Explicitly deferred ideas
+### 7. Success Metrics
+- 2-4 measurable outcomes that define whether this feature is working
 
 ## Workflow
 

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

@@ -7,12 +7,32 @@ You are a senior Product Manager at a high-performing software company.
 
 Your task is to take the provided feature description (which may be vague or detailed) and produce a **Product Requirements Document (PRD)** that clearly defines *what* is being built and *why*, without deep technical or architectural implementation details.
 
+## Important: Agent-Oriented Documentation
+
+**These PRDs are designed for automated agent consumption** (via `gspec-implement`), with humans validating the content for accuracy and completeness. Write documents that are:
+
+- **Implementation-ready blueprints**, not project plans
+- Focused on **what** to build and **why**, not **when** or **how long**
+- Clear on technical and functional requirements an agent needs to execute
+
+**AVOID project management details:**
+- ❌ Sprint planning, week numbers, or timeline estimates
+- ❌ Team assignments or resource allocation
+- ❌ Velocity or story point estimates
+- ❌ Delivery schedules or milestone dates
+
+**DO include implementation guidance:**
+- ✅ Clear functional requirements and acceptance criteria
+- ✅ Dependencies between capabilities
+- ✅ Priority levels (P0, P1, P2) for scope decisions
+- ✅ Build order recommendations based on technical dependencies
+
 You should:
 - **Read existing gspec documents first** to ground the PRD in established product context
 - Ask clarifying questions when essential information is missing rather than guessing
 - When asking questions, offer 2-3 specific suggestions to guide the discussion
 - Focus on user value, scope, and outcomes
-- Write for product, design, and engineering audiences
+- Write for automated implementation with human validation
 - Be concise, structured, and decisive
 
 ---
@@ -39,6 +59,13 @@ If these files don't exist, proceed without them — they are optional context,
 - Output **ONLY** a single Markdown document
 - Save the file to the `gspec/features/` folder in the root of the project, create it if it doesn't exist
 - Name the file based on the feature (e.g., `user-authentication.md`, `dashboard-analytics.md`)
+- Begin the file with YAML frontmatter containing the gspec version:
+  ```
+  ---
+  gspec-version: 1.1.0
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
 - **Before generating the document**, ask clarifying questions if:
   - The target users are unclear
   - The scope or boundaries of the feature are ambiguous
@@ -50,48 +77,76 @@ If these files don't exist, proceed without them — they are optional context,
 - No code blocks except where examples add clarity
 - Make tradeoffs and scope explicit
 
+### Technology Agnosticism
+
+**IMPORTANT**: PRDs must remain technology-agnostic to enable implementation with different technology stacks. The `gspec/stack.md` file is the single source of truth for technology choices.
+
+**DO use generic architectural terms:**
+- ✅ "database", "data store", "persistent storage"
+- ✅ "authentication service", "IAM", "identity provider"
+- ✅ "API", "backend service", "server"
+- ✅ "frontend", "client application", "user interface"
+- ✅ "message queue", "event system", "pub/sub"
+- ✅ "object storage", "file storage"
+- ✅ "cache", "caching layer"
+- ✅ "search index", "full-text search"
+
+**DO NOT reference specific technologies:**
+- ❌ React, Vue, Angular, Svelte
+- ❌ PostgreSQL, MySQL, MongoDB, DynamoDB
+- ❌ AWS Lambda, Google Cloud Functions, Azure Functions
+- ❌ Redis, Memcached
+- ❌ Elasticsearch, Algolia, Solr
+- ❌ S3, GCS, Azure Blob Storage
+- ❌ Kafka, RabbitMQ, SQS
+
+This separation allows the same feature spec to be implemented using different technology stacks by swapping the Stack file.
+
 ---
 
 ## Required Sections
 
+**IMPORTANT**: Only include the sections listed below. Do NOT add additional sections such as "Technology Notes", "Implementation Details", "Technical Architecture", or any other custom sections. Stick strictly to this structure.
+
 ### 1. Overview
 - Feature name
-- Summary
-- Objective
-
-### 2. Problem & Context
-- User problem
-- Why this matters now
-- Current pain points
-
-### 3. Goals & Non-Goals
-- In-scope goals
-- Explicitly out-of-scope items
+- Summary (1-2 sentences)
+- Problem being solved and why it matters now
 
-### 4. Users & Use Cases
+### 2. Users & Use Cases
 - Primary users
-- Key use cases
+- Key use cases (3-4 scenarios showing how users benefit)
 
-### 5. Assumptions & Open Questions
-- Assumptions
-- Open questions (non-blocking)
+### 3. Scope
+- In-scope goals
+- Out-of-scope items (things this feature explicitly won't do)
+- Deferred ideas (things we may do later, but not now)
 
-### 6. Capabilities
+### 4. Capabilities
 - What the feature provides to users
 - **Priority level** for each capability (P0 = must-have, P1 = should-have, P2 = nice-to-have)
 - Focus on *what* users can do, not *how* they do it
 - **Use unchecked markdown checkboxes** for each capability to enable implementation tracking (e.g., `- [ ] **P0**: User can sign in with email and password`). The `gspec-implement` command will check these off (`- [x]`) as capabilities are implemented, allowing incremental runs.
+- **Each capability MUST include brief acceptance criteria** — 2-4 testable conditions that define "done" for that capability. These tell the implementing agent exactly when a capability is complete and give test writers concrete assertions. Format as a sub-list under each capability:
+  ```
+  - [ ] **P0**: User can sign in with email and password
+    - Valid credentials → user is redirected to dashboard and session is created
+    - Invalid credentials → error message is shown, no session is created
+    - Empty fields → inline validation prevents submission
+  ```
+
+### 5. Dependencies
+- Dependencies on other features (link to their PRDs if they exist)
+- External dependencies (third-party services, APIs, data sources)
+- If none, state "None"
+
+### 6. Assumptions & Risks
+- Assumptions (what we're taking as true)
+- Open questions (non-blocking unknowns to resolve during implementation)
+- Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
 
 ### 7. Success Metrics
-- How success is measured
-- Leading vs lagging indicators
-
-### 8. Risks & Mitigations
-- Product or delivery risks
-- Mitigation strategies
-
-### 9. Future Considerations
-- Explicitly deferred ideas
+- 2-4 measurable outcomes that define whether this feature is working
 
 ---
 

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

@@ -33,9 +33,10 @@ Before writing any code, read all available gspec documents in this order:
 1. `gspec/profile.md` — Understand what the product is and who it's for
 2. `gspec/epics/*.md` — Understand the big picture and feature dependencies
 3. `gspec/features/*.md` — Understand individual feature requirements
-4. `gspec/stack.md` — Understand the technology choices and architecture
+4. `gspec/stack.md` — Understand the technology choices
 5. `gspec/style.md` — Understand the visual design language
 6. `gspec/practices.md` — Understand development standards and conventions
+7. `gspec/architecture.md` — Understand the technical architecture: project structure, data model, API design, component architecture, and environment setup. **This is the primary reference for how to scaffold and structure the codebase.** If this file is missing, note the gap and suggest the user run `gspec-architect` first — but do not block on it.
 
 If any of these files are missing, note what's missing and proceed with what's available.
 
@@ -166,8 +167,8 @@ After reading the specs (and completing competitor research if the user opted in
 3. **Identify gaps** in the specified features — areas where the specs don't fully specify behavior:
    - Missing edge cases or error handling scenarios
    - Unspecified user flows or interactions
-   - Ambiguous acceptance criteria
-   - Undefined data models or API contracts
+   - Ambiguous or missing acceptance criteria on capabilities
+   - Undefined data models or API contracts (check `gspec/architecture.md`'s "Data Model" and "API Design" sections — if defined, use them as the basis for your data layer and API routes; if missing or incomplete, flag the gap)
    - Integration points that aren't fully described
    - Missing or unclear state management patterns
    - *If competitor research was conducted:* Patterns that differ from established competitor conventions without clear rationale — users may have ingrained expectations from competitor products
@@ -212,15 +213,14 @@ After the user approves proposed features (whether from gap analysis, competitor
 For each approved feature that doesn't already have a PRD in `gspec/features/`:
 
 1. **Generate a feature PRD** following the same structure used by the `gspec-feature` command:
-   - Overview (name, summary, objective)
-   - Problem & Context
-   - Goals & Non-Goals
+   - Overview (name, summary, problem being solved and why it matters now)
    - Users & Use Cases
-   - Assumptions & Open Questions
-   - Capabilities (with P0/P1/P2 priority levels, using **unchecked checkboxes** `- [ ]` for each capability)
+   - 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)
    - Success Metrics
-   - Risks & Mitigations
-   - Future Considerations
+   - Begin the file with YAML frontmatter: `---\ngspec-version: 1.1.0\n---`
 2. **Name the file** descriptively based on the feature (e.g., `gspec/features/onboarding-wizard.md`, `gspec/features/export-csv.md`)
 3. **Ground the PRD in existing gspec context** — reference the product profile's target users, align success metrics with established metrics, and respect stated non-goals
 4. **Keep the PRD product-focused** — describe *what* and *why*, not *how*. Implementation details belong in the code, not the PRD.
@@ -228,26 +228,71 @@ For each approved feature that doesn't already have a PRD in `gspec/features/`:
 
 This step is not optional. Every feature the agent implements should be traceable to either a pre-existing PRD or one generated during this phase. Skipping this step leads to undocumented features that future sessions cannot reason about.
 
+### Phase 3c: Implementation Plan — Define the Build Order
+
+After all approved features are codified as PRDs, **enter plan mode** and create a concrete, phased implementation plan. This is distinct from Phase 3's gap analysis — this is the tactical build plan.
+
+1. **Survey the full scope** — Review all feature PRDs (both pre-existing and newly codified in Phase 3b) and identify every unchecked capability that is in scope for this run
+2. **Organize into implementation phases** — Group related capabilities into logical phases that can be built and verified independently. Each phase should:
+   - Have a clear name and objective (e.g., "Phase 1: Core Data Models & API", "Phase 2: Authentication Flow")
+   - List the specific capabilities (with feature PRD references) it will implement
+   - Identify files to create or modify
+   - Note dependencies on prior phases
+   - Include an estimated scope (small/medium/large)
+3. **Define test expectations per phase** — For each phase, specify what tests will be run to verify correctness before moving on (unit tests, integration tests, build verification, etc.)
+4. **Present the plan** — Show the user the full phased plan with clear phase boundaries and ask for approval
+
+**Wait for user approval before proceeding to Phase 4.** The user may reorder phases, adjust scope, or split/merge phases.
+
 ### Phase 4: Implementation — Build It
 
-Once the plan is approved, implement the code:
+Once the implementation plan is approved, execute it **phase by phase**.
+
+#### Phase 0 (if needed): Project Scaffolding
+
+Before implementing any feature logic, ensure the project foundation exists. **Skip this step entirely if the project is already initialized** (i.e., a `package.json`, `pyproject.toml`, `go.mod`, or equivalent exists and dependencies are installed).
+
+For greenfield projects:
+
+1. **Initialize the project** using the setup commands from `gspec/architecture.md`'s "Project Setup" section (e.g., `npx create-next-app`, `npm init`, etc.). Fall back to `gspec/stack.md` if no architecture document exists.
+2. **Install core dependencies** listed in the architecture or stack document, organized by category (framework, database, testing, styling, etc.)
+3. **Create the directory structure** matching the layout defined in `gspec/architecture.md`'s "Project Structure" section — this is the canonical reference for where all files go
+4. **Set up configuration files** as listed in `gspec/architecture.md`'s "Environment & Configuration" section — create `.env.example`, framework configs, linting/formatting configs, etc.
+5. **Apply design tokens** — if `gspec/style.md` includes a CSS custom properties block (Design Tokens section), create the global stylesheet or theme configuration file with those exact values
+6. **Create the data layer** — if `gspec/architecture.md` defines a "Data Model" section, use it to set up initial database schemas/models, migration files, and type definitions
+7. **Verify the scaffold builds and runs** — run the dev server or build command to confirm the empty project compiles without errors before adding feature code
+
+Present a brief scaffold summary to the user before proceeding to feature implementation.
+
+#### For each phase in the approved plan:
+
+1. **Announce the phase** — State which phase you're starting, what it covers, and what capabilities will be implemented
+2. **Implement the phase:**
+   a. **Follow the stack** — Use the exact technologies, frameworks, and patterns defined in `gspec/stack.md`
+   b. **Follow the practices** — Adhere to coding standards, testing requirements, and conventions from `gspec/practices.md`
+   c. **Follow the style** — Apply the design system, tokens, and component patterns from `gspec/style.md`
+   d. **Satisfy the requirements** — Trace each piece of code back to a functional requirement in the feature PRD (if available) or to the user's stated goals and the approved implementation plan
+   e. *If competitor research was conducted:* **Leverage competitor insights** — When making UX or interaction design decisions not fully specified in the style guide, consider established patterns from competitor research. Don't blindly copy, but don't ignore proven conventions either.
+3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `gspec-version` YAML frontmatter. If a file lacks frontmatter, add `---\ngspec-version: 1.1.0\n---` at the top.
+4. **Update epic status** — When all capabilities in a feature PRD are checked, update the corresponding feature's checkbox in the epic summary file (if one exists) from `- [ ]` to `- [x]`.
+5. **Run tests** — Execute the tests defined for this phase (and any existing tests to catch regressions). Fix any failures before proceeding.
+6. **Surface new gaps** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
+7. **Pause and report** — After completing the phase and confirming tests pass, present a phase completion summary to the user:
+
+> **Phase 2 Complete: Authentication Flow**
+> - Capabilities implemented: 3/3 (login, signup, password reset)
+> - Tests: 12 passed, 0 failed
+> - PRDs updated: `gspec/features/authentication.md`
+> - Next up: Phase 3 — Dashboard & Navigation
 
-1. **Follow the stack** — Use the exact technologies, frameworks, and patterns defined in `gspec/stack.md`
-2. **Follow the practices** — Adhere to coding standards, testing requirements, and conventions from `gspec/practices.md`
-3. **Follow the style** — Apply the design system, tokens, and component patterns from `gspec/style.md`
-4. **Satisfy the requirements** — Trace each piece of code back to a functional requirement in the feature PRD (if available) or to the user's stated goals and the approved implementation plan
-5. **Implement incrementally** — Complete one logical unit at a time, verify it works, then move on
-6. **Surface new gaps as they arise** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
-7. *If competitor research was conducted:* **Leverage competitor insights during implementation** — When making UX or interaction design decisions not fully specified in the style guide, consider established patterns from competitor research. Don't blindly copy, but don't ignore proven conventions either.
-8. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost.
-9. **Update epic status** — When all capabilities in a feature PRD are checked, update the corresponding feature's checkbox in the epic summary file (if one exists) from `- [ ]` to `- [x]`.
+**Wait for user confirmation before starting the next phase.** This gives the user an opportunity to review the work, request adjustments, or reprioritize remaining phases.
 
 ### Phase 5: Verification — Confirm Completeness
 
 After implementation:
 
 1. **Walk through each functional requirement** from the feature PRD (if available) or the approved implementation plan and confirm it's satisfied
-2. **Review against acceptance criteria** — Does the implementation meet every stated criterion or approved goal?
+2. **Review against acceptance criteria** — For each capability in the feature PRDs, check that every acceptance criterion listed under it is satisfied. These sub-listed conditions are the definition of "done" for each capability. If any criterion is not met, the capability should not be marked `[x]`.
 3. **Check the Definition of Done** from `gspec/practices.md`
 4. *If competitor research was conducted:* **Verify competitive positioning** — Does the implemented feature meet table-stakes expectations? Does it deliver on the product's stated differentiation?
 5. **Note any deferred items** — Requirements that were intentionally postponed or descoped during implementation
@@ -327,11 +372,12 @@ The user's prompt takes priority for scoping. Use it to determine focus, and ref
 
 ## Output Rules
 
-- **Always start in plan mode** for gap analysis and implementation planning
+- **Use plan mode twice** — once in Phase 3 for gap analysis and feature proposals, and again in Phase 3c for the concrete implementation plan. Both require user approval before proceeding.
+- **Pause between implementation phases** — After completing each phase in Phase 4, run tests and wait for user confirmation before starting the next phase
 - Reference specific gspec documents and section numbers when discussing requirements
 - When proposing gap-fills, clearly distinguish between "the spec says X" and "I'm proposing Y"
 - *If competitor research was conducted:* When referencing findings, clearly attribute them — "Competitor X does Y" not "the industry does Y"
-- Create files following the project structure conventions from `gspec/stack.md` and `gspec/practices.md`
+- Create files following the project structure defined in `gspec/architecture.md` (or `gspec/stack.md` and `gspec/practices.md` if no architecture document exists)
 - Write code that is production-quality, not prototypical — unless the user requests otherwise
 - Include tests as defined by `gspec/practices.md` testing standards
 

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

@@ -0,0 +1,119 @@
+---
+name: gspec-migrate
+description: Migrate existing gspec files to the current format when upgrading to a new gspec version
+---
+
+You are a Technical Documentation Migration Specialist.
+
+Your task is to update existing gspec specification documents to match the current gspec format (version 1.1.0). You preserve all substantive content while ensuring documents follow the latest structural conventions.
+
+---
+
+## Workflow
+
+### Phase 1: Inventory — Scan All gspec Files
+
+Scan the `gspec/` directory for all Markdown files:
+- `gspec/*.md` (profile, stack, style, practices, architecture)
+- `gspec/features/*.md` (individual feature PRDs)
+- `gspec/epics/*.md` (epic summaries)
+
+For each file, check the YAML frontmatter at the top of the file:
+- If the file starts with `---` followed by YAML content and another `---`, read the `gspec-version` field
+- If no frontmatter exists, the file predates version tracking
+- If `gspec-version` matches `1.1.0`, the file is current — skip it
+
+Present an inventory to the user:
+
+> **gspec File Inventory:**
+> - `gspec/profile.md` — no version (needs migration)
+> - `gspec/stack.md` — version 1.0.3 (needs migration)
+> - `gspec/style.md` — version 1.1.0 (current, skipping)
+> - `gspec/features/user-auth.md` — no version (needs migration)
+
+Ask the user to confirm which files to migrate, or confirm all.
+
+### Phase 2: Reference — Read Current Format Definitions
+
+For each file that needs migration, determine its document type and read the corresponding gspec command skill to understand the current expected format:
+
+| gspec File | Document Type | Format Reference |
+|---|---|---|
+| `gspec/profile.md` | Product Profile | Read the `gspec-profile` skill definition |
+| `gspec/stack.md` | Technology Stack | Read the `gspec-stack` skill definition |
+| `gspec/style.md` | Visual Style Guide | Read the `gspec-style` skill definition |
+| `gspec/practices.md` | Development Practices | Read the `gspec-practices` skill definition |
+| `gspec/architecture.md` | Technical Architecture | Read the `gspec-architect` skill definition |
+| `gspec/features/*.md` | Feature PRD | Read the `gspec-feature` skill definition |
+| `gspec/epics/*.md` | Epic Summary | Read the `gspec-epic` skill definition |
+
+The skill definitions are located in your installed skills directory. Read them to understand the current "Required Sections" structure for each document type.
+
+### Phase 3: Migrate — Update Each File
+
+For each file to migrate:
+
+1. **Read the current file content** — Understand what information it contains
+2. **Read the format reference** — Understand the expected structure from the corresponding skill definition
+3. **Compare structures** — Identify:
+   - Sections that exist in both (may need renaming, reordering, or reformatting)
+   - Sections that are new in the current format (add with content from existing file where applicable, or mark as "To be defined")
+   - Sections that were removed in the current format (move content to the appropriate new section, or remove if truly obsolete)
+   - Formatting changes (e.g., checkbox format for capabilities, acceptance criteria requirements)
+4. **Preserve all substantive content** — Never discard information during migration. If a section was removed from the format, find the right place for its content or keep it in a "Legacy Content" section at the bottom.
+5. **Add or update the frontmatter** — Ensure the file starts with:
+   ```
+   ---
+   gspec-version: 1.1.0
+   ---
+   ```
+6. **Present the proposed changes** to the user before writing. Show what sections are being reorganized, what is being added, and confirm no content is being lost.
+
+### Phase 4: Verify — Confirm Migration
+
+After migrating all files:
+
+1. **Verify every migrated file** has the correct frontmatter
+2. **Verify no content was lost** — Briefly summarize what was preserved and any content that was relocated
+3. **Present a completion summary**:
+
+> **Migration Complete:**
+> - 4 files migrated to version 1.1.0
+> - 2 files were already current (skipped)
+> - Content preserved in all files
+> - Sections reorganized: [list any structural changes]
+
+---
+
+## Migration Rules
+
+**Content preservation is paramount.** The user's information must never be discarded. If the format changes eliminated a section, find the right home for that content in the new structure.
+
+**Maintain document voice.** Each gspec document was written with a specific tone and style. Restructure and reformat, but do not rewrite prose unless the meaning would be lost.
+
+**Handle feature PRD capabilities carefully.** If migrating feature PRDs:
+- Preserve checkbox states (`[x]` and `[ ]`) exactly as they are
+- If capabilities lack checkboxes (old format), add unchecked checkboxes
+- If capabilities lack acceptance criteria (current format requires them), add placeholder criteria: "Acceptance criteria to be defined"
+- Preserve priority levels (P0, P1, P2)
+
+**Handle missing sections gracefully.** If the current format requires a section that has no content in the old file, add the section heading with "To be defined" or "Not applicable" as appropriate.
+
+**Frontmatter handling:**
+- If the file has no frontmatter, add it at the very top
+- If the file has frontmatter without `gspec-version`, add the field
+- If the file has an outdated `gspec-version`, update it
+- Preserve any other frontmatter fields that may exist
+
+---
+
+## Tone & Style
+
+- Precise and careful — migration is a delicate operation
+- Transparent — show every change before making it
+- Conservative — when in doubt, preserve rather than discard
+
+---
+
+## Input
+

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

@@ -22,6 +22,13 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/practices.md` in the root of the project, create the `gspec` folder if it doesn't exist
+- Begin the file with YAML frontmatter containing the gspec version:
+  ```
+  ---
+  gspec-version: 1.1.0
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
 - **Before generating the document**, ask clarifying questions if:
   - Team size or experience level is unclear
   - Development timeline constraints are unspecified

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

@@ -22,6 +22,13 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/profile.md` in the root of the project, create the `gspec` folder if it doesn't exist
+- Begin the file with YAML frontmatter containing the gspec version:
+  ```
+  ---
+  gspec-version: 1.1.0
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
 - **Before generating the document**, ask clarifying questions if:
   - The target audience is unclear
   - The core value proposition is ambiguous