gspec 1.1.2 → 1.3.0

package/README.md

@@ -25,14 +25,51 @@ These documents become the shared context for all subsequent AI interactions. Wh
 
 The only commands you *need* are the four fundamentals and `implement`. Everything else exists to help when your project calls for it.
 
-The fundamentals give your AI tool enough context to build well — it knows what the product is, how it should look, what technologies to use, and what engineering standards to follow. From there, `implement` can take a plain-language description and start building. The remaining commands — `feature`, `epic`, `architect`, `dor`, and `record` — add structure and rigor when the scope or complexity warrants it.
-
-```
-Define → Build
-Define → Specify → Build
-Define → Specify → Architect → Build → Iterate
+The fundamentals give your AI tool enough context to build well — it knows what the product is, how it should look, what technologies to use, and what engineering standards to follow. From there, `implement` can take a plain-language description and start building. The remaining commands — `research`, `feature`, `epic`, `architect`, `dor`, and `record` — add structure and rigor when the scope or complexity warrants it.
+
+```mermaid
+flowchart LR
+    Define["1. Define
+    profile · style
+    stack · practices"]
+
+    Research["2. Research
+    competitive analysis"]
+
+    Specify["3. Specify
+    feature · epic"]
+
+    Architect["4. Architect
+    technical blueprint"]
+
+    Build["5. Build
+    implement"]
+    
+    Iterate["6. Iterate
+    dor · record"]
+
+    Define --> Research
+    Define --> Specify
+    Define --> Build
+    Research --> Specify
+    Research --> Build
+    Specify --> Architect
+    Specify --> Build
+    Architect --> Build
+    Build --> Iterate
+    Iterate --> Build
+
+    style Define fill:#4a9eff,color:#fff,stroke:none
+    style Research fill:#a855f7,color:#fff,stroke:none
+    style Specify fill:#f59e0b,color:#fff,stroke:none
+    style Architect fill:#f59e0b,color:#fff,stroke:none
+    style Build fill:#22c55e,color:#fff,stroke:none
+    style Iterate fill:#64748b,color:#fff,stroke:none
 ```
 
+> **Blue** = required foundation. **Purple/Yellow** = optional depth. **Green** = implementation. **Gray** = maintenance.
+> Every path starts with Define and passes through Build. The steps in between depend on your project's complexity.
+
 **1. Define the Fundamentals** — Establish the foundation that drives every decision.
 
 | Command | Role | What it produces |
@@ -42,7 +79,15 @@ Define → Specify → Architect → Build → Iterate
 | `gspec.stack` | Software Architect | Technology stack, frameworks, infrastructure, architecture |
 | `gspec.practices` | Engineering Lead | Development standards, code quality, testing, workflows |
 
-**2. Specify What to Build** *(optional)* — Define features and requirements.
+**2. Research the Market** *(optional)* — Understand the competitive landscape before building.
+
+| Command | Role | What it produces |
+|---|---|---|
+| `gspec.research` | Product Strategist | Competitive analysis with feature matrix, gap identification, and strategic recommendations |
+
+Use `research` when you want to understand what competitors offer, identify table-stakes features you might be missing, and find differentiation opportunities. It reads competitors from your product profile, produces a persistent `gspec/research.md` file, and can optionally generate feature PRDs from the findings. The `implement` command automatically uses this file when it exists.
+
+**3. Specify What to Build** *(optional)* — Define features and requirements.
 
 | Command | Role | What it produces |
 |---|---|---|
@@ -51,7 +96,7 @@ Define → Specify → Architect → Build → Iterate
 
 Use `feature` when you want a detailed PRD with prioritized capabilities and acceptance criteria before building. Use `epic` when a body of work is large enough to need decomposition into multiple features with dependency mapping. For smaller tasks or rapid prototyping, you can skip straight to `implement` with a plain-language description.
 
-**3. Architect** *(optional)* — Translate specs into a concrete technical blueprint.
+**4. Architect** *(optional)* — Translate specs into a concrete technical blueprint.
 
 | Command | Role | What it produces |
 |---|---|---|
@@ -59,13 +104,13 @@ Use `feature` when you want a detailed PRD with prioritized capabilities and acc
 
 Use `architect` when your feature involves significant technical complexity — new data models, service boundaries, auth flows, or integration points that benefit from upfront design. For straightforward features, `implement` can make sound architectural decisions on its own using your `stack` and `practices` specs.
 
-**4. Build** — Implement with full context.
+**5. Build** — Implement with full context.
 
 | Command | Role | What it does |
 |---|---|---|
-| `gspec.implement` | Senior Engineer | Reads all specs, identifies gaps, researches competitors, plans and builds |
+| `gspec.implement` | Senior Engineer | Reads all specs (including research), identifies gaps, plans and builds |
 
-**5. Iterate** *(optional)* — Keep specs and code in sync as the project evolves.
+**6. Iterate** *(optional)* — Keep specs and code in sync as the project evolves.
 
 | Command | Role | What it does |
 |---|---|---|
@@ -120,6 +165,7 @@ project-root/
     ├── stack.md            # Technology stack and architecture
     ├── practices.md        # Development standards
     ├── architecture.md     # Technical architecture blueprint
+    ├── research.md         # Competitive analysis and feature gaps
     ├── epics/
     │   └── onboarding-flow.md
     └── features/
@@ -140,7 +186,7 @@ These are standard Markdown files. They live in your repo, are version-controlle
 
 **Incremental implementation.** Feature PRDs use checkboxes to track which capabilities have been built. The `implement` command reads these to know what's done and what's remaining, so it can be run multiple times as your project grows.
 
-**Competitive research.** The `implement` command can optionally research competitors named in your product profile, identifying table-stakes features you might be missing and opportunities for differentiation.
+**Competitive research.** The `research` command analyzes competitors named in your product profile, identifying table-stakes features you might be missing and opportunities for differentiation. Its output is saved to `gspec/research.md` and automatically used by `implement` when present.
 
 **Platform-agnostic.** A single set of source commands builds for Claude Code, Cursor, and Antigravity. The build system handles platform-specific formatting so the commands stay consistent across tools.
 

package/commands/gspec.epic.md

@@ -31,7 +31,7 @@ Take the provided epic description (a large body of work) and break it down into
 
 ## Guidelines
 
-- **Read existing gspec documents first** to ground the epic and its features in established product context
+- **Read existing feature PRDs and epics** in `gspec/features/` and `gspec/epics/` to understand already-specified work and avoid overlap
 - Identify distinct features that make up the epic
 - **Ask all clarifying questions in the chat before writing specs** — never embed unresolved questions in the generated documents
 - When asking questions, offer 2-3 specific suggestions to guide the discussion
@@ -43,21 +43,27 @@ Take the provided epic description (a large body of work) and break it down into
 
 ---
 
-## Context Discovery
+## Portability
 
-Before generating epic and feature documents, check for and read any existing gspec documents in the project root's `gspec/` folder. These provide established product context that should inform the breakdown:
+Epic summaries and the feature PRDs they produce are designed to be **portable across projects**. A feature spec written for one project should be reusable in a different project with a different profile, design system, tech stack, and development practices. Project-specific context is resolved at implementation time by `gspec-implement`, which reads all gspec documents (profile, style, stack, practices) alongside the feature PRDs.
 
-1. **`gspec/profile.md`** — Product identity, target audience, value proposition, market context, and competitive landscape. Use this to align the epic with the product's mission, ensure features target the right users, and understand what's table-stakes vs. differentiating.
-2. **`gspec/style.md`** — Visual design language, component patterns, and UX principles. Use this to inform UX requirements in individual feature PRDs and ensure consistency with the established design system.
-3. **`gspec/stack.md`** — Technology choices and architecture. Use this to understand technical constraints that may affect feature scoping, sequencing, and dependency mapping.
-4. **`gspec/practices.md`** — Development standards and conventions. Use this to understand delivery constraints, quality expectations, and testing requirements that may influence phasing.
+**To maintain portability, DO NOT read or incorporate context from:**
+- `gspec/profile.md` — Do not reference project-specific personas, competitive landscape, or positioning
+- `gspec/style.md` — Do not reference a specific design system or component library
+- `gspec/stack.md` — Do not reference specific technologies (already covered by Technology Agnosticism)
+- `gspec/practices.md` — Do not reference project-specific development standards
 
-If these files don't exist, proceed without them — they are optional context, not blockers. When they do exist, incorporate their context naturally:
-- Reference the product's target users and personas from the profile rather than defining them from scratch
-- Align epic and feature success metrics with metrics already established in the profile
-- Ensure feature boundaries and UX requirements respect the established design system
-- Let the competitive landscape inform priority levels and MVE scope
-- Use technical stack constraints to inform realistic dependency mapping and sequencing
+**DO read existing feature PRDs and epics** in `gspec/features/` and `gspec/epics/` to:
+- Avoid duplicating or contradicting already-specified features
+- Identify cross-feature and cross-epic dependencies
+- Ensure consistent scope boundaries and terminology
+
+**Write in generic, portable terms:**
+- Use relative role descriptions ("primary users", "administrators", "content creators") not project-specific persona names
+- Justify priorities based on intrinsic user value and technical dependencies, not competitive landscape
+- Describe desired UX behavior generically ("clear error feedback", "responsive layout") without referencing a specific design system
+- Define success metrics in terms of each feature's own outcomes, not project-level KPIs
+- Sequence features based on logical dependencies, not project-specific stack constraints
 
 ## Output Rules
 
@@ -113,7 +119,7 @@ If these files don't exist, proceed without them — they are optional context,
 - ❌ 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.
+This separation — combined with the portability principles above — allows the same epic and feature specs to be reused across projects with different technology stacks, design systems, and product contexts.
 
 ## Epic Summary Document Structure
 
@@ -161,7 +167,7 @@ For each feature, create a separate file in `gspec/features/[feature-name].md` w
 - **Parent Epic** (link to epic summary)
 
 ### 2. Users & Use Cases
-- Primary users
+- Primary users (use generic role descriptions like "end users", "administrators", "content managers" — not project-specific persona names)
 - Key use cases (3-4 scenarios showing how users benefit)
 
 ### 3. Scope
@@ -195,6 +201,10 @@ For each feature, create a separate file in `gspec/features/[feature-name].md` w
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working
 
+### 8. Implementation Context
+- Include the following standard note verbatim:
+  > This feature PRD is portable and project-agnostic. During implementation, consult the project's `gspec/profile.md` (target users, positioning), `gspec/style.md` (design system), `gspec/stack.md` (technology choices), and `gspec/practices.md` (development standards) to resolve project-specific context.
+
 ## Workflow
 
 1. **Analyze the epic description** and identify logical feature boundaries

package/commands/gspec.feature.md

@@ -23,7 +23,7 @@ Your task is to take the provided feature description (which may be vague or det
 - ✅ Build order recommendations based on technical dependencies
 
 You should:
-- **Read existing gspec documents first** to ground the PRD in established product context
+- **Read existing feature PRDs** in `gspec/features/` to understand already-specified features and avoid overlap
 - **Ask all clarifying questions in the chat before writing the spec** — never embed unresolved questions in the generated document
 - When asking questions, offer 2-3 specific suggestions to guide the discussion
 - Focus on user value, scope, and outcomes
@@ -32,20 +32,26 @@ You should:
 
 ---
 
-## Context Discovery
+## Portability
 
-Before generating the PRD, check for and read any existing gspec documents in the project root's `gspec/` folder. These provide established product context that should inform the feature definition:
+Feature PRDs are designed to be **portable across projects**. A feature spec written for one project should be reusable in a different project with a different profile, design system, tech stack, and development practices. Project-specific context is resolved at implementation time by `gspec-implement`, which reads all gspec documents (profile, style, stack, practices) alongside the feature PRDs.
 
-1. **`gspec/profile.md`** — Product identity, target audience, value proposition, market context, and competitive landscape. Use this to align the feature with the product's mission, target users, and positioning.
-2. **`gspec/style.md`** — Visual design language, component patterns, and UX principles. Use this to inform any UX-related guidance or capability descriptions in the PRD.
-3. **`gspec/stack.md`** — Technology choices and architecture. Use this to understand technical constraints that may affect feature scope or feasibility.
-4. **`gspec/practices.md`** — Development standards and conventions. Use this to understand delivery constraints or quality expectations.
+**To maintain portability, DO NOT read or incorporate context from:**
+- `gspec/profile.md` — Do not reference project-specific personas, competitive landscape, or positioning
+- `gspec/style.md` — Do not reference a specific design system or component library
+- `gspec/stack.md` — Do not reference specific technologies (already covered by Technology Agnosticism)
+- `gspec/practices.md` — Do not reference project-specific development standards
 
-If these files don't exist, proceed without them — they are optional context, not blockers. When they do exist, incorporate their context naturally:
-- Reference the product's target users from the profile rather than defining them from scratch
-- Align success metrics with metrics already established in the profile
-- Ensure capabilities respect the product's stated non-goals and positioning
-- Let the competitive landscape inform what's table-stakes vs. differentiating
+**DO read existing feature PRDs** in `gspec/features/` to:
+- Avoid duplicating or contradicting already-specified features
+- Identify cross-feature dependencies
+- Ensure consistent scope boundaries
+
+**Write in generic, portable terms:**
+- Use relative role descriptions ("primary users", "administrators", "content creators") not project-specific persona names
+- Justify priorities based on the feature's intrinsic user value, not competitive landscape
+- Describe desired UX behavior generically ("clear error feedback", "responsive layout") without referencing a specific design system
+- Define success metrics in terms of the feature's own outcomes, not project-level KPIs
 
 ---
 
@@ -97,7 +103,7 @@ If these files don't exist, proceed without them — they are optional context,
 - ❌ 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.
+This separation — combined with the portability principles above — allows the same feature spec to be reused across projects with different technology stacks, design systems, and product contexts.
 
 ---
 
@@ -111,7 +117,7 @@ This separation allows the same feature spec to be implemented using different t
 - Problem being solved and why it matters now
 
 ### 2. Users & Use Cases
-- Primary users
+- Primary users (use generic role descriptions like "end users", "administrators", "content managers" — not project-specific persona names)
 - Key use cases (3-4 scenarios showing how users benefit)
 
 ### 3. Scope
@@ -145,6 +151,10 @@ This separation allows the same feature spec to be implemented using different t
 ### 7. Success Metrics
 - 2-4 measurable outcomes that define whether this feature is working
 
+### 8. Implementation Context
+- Include the following standard note verbatim:
+  > This feature PRD is portable and project-agnostic. During implementation, consult the project's `gspec/profile.md` (target users, positioning), `gspec/style.md` (design system), `gspec/stack.md` (technology choices), and `gspec/practices.md` (development standards) to resolve project-specific context.
+
 ---
 
 ## Tone & Style

package/commands/gspec.implement.md

@@ -8,9 +8,9 @@ When feature specs exist, they are a **guide to key functionality, not a compreh
 
 You should:
 - Read and internalize all available gspec documents before writing any code
-- **Research competitors** called out in the product profile to understand the competitive landscape and identify feature expectations
+- **Use competitive research** from `gspec/research.md` when available to understand the competitive landscape and identify feature expectations
 - Identify gaps, ambiguities, or underspecified behaviors in the specs
-- **Propose additional features** informed by competitor research, product business needs, target users, and mission — even if not listed in the existing feature specs
+- **Propose additional features** informed by competitive research (when available), product business needs, target users, and mission — even if not listed in the existing feature specs
 - Use your engineering judgment and imagination to propose solutions for gaps
 - **Always vet proposals with the user before implementing them** — use plan mode to present your reasoning and get approval
 - Implement incrementally, one logical unit at a time
@@ -28,10 +28,12 @@ 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
+   > **Note:** Feature PRDs are designed to be portable and project-agnostic. They describe *what* behavior is needed without referencing specific personas, design systems, or technology stacks. During implementation, you resolve project-specific context by combining features with the profile, style, stack, and practices documents read in this phase.
 4. `gspec/stack.md` — Understand the technology choices
 5. `gspec/style.md` — Understand the visual design language
 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.
+8. `gspec/research.md` — If this file exists, read the competitive research findings. This provides pre-conducted competitor analysis including the competitive feature matrix, categorized findings, and accepted feature recommendations produced by `gspec-research`.
 
 If any of these files are missing, note what's missing and proceed with what's available.
 
@@ -55,107 +57,24 @@ Present this summary to the user so they understand the starting point. If **all
 
 For epic summary files, check whether the features listed in the "Features Breakdown" section have checkboxes. A feature in an epic is considered complete when all its capabilities in the corresponding feature PRD are checked.
 
-**Pay special attention** to the product profile's **Market & Competition** section. Extract:
-- All named **direct competitors**
-- All named **indirect competitors or alternatives**
-- The **white space or gaps** the product claims to fill
-- The **differentiation** and **competitive advantages** stated in the Value Proposition
+### Phase 2: Analysis — Identify Gaps & Plan
 
-These will inform competitor research if the user opts in.
+After reading the specs, **enter plan mode** and:
 
-#### Ask: Competitor Research
-
-After reading the specs, **ask the user whether they want you to conduct competitor research** before planning. Present this as a clear choice:
-
-- **Yes** — You will research the competitors named in the product profile, build a competitive feature matrix, and use the findings to identify gaps and propose features. This adds depth but takes additional time.
-- **No** — You will plan and implement based solely on the existing gspec documents and the user's prompt. Only features explicitly defined in `gspec/features/` (if any) and capabilities the user requests will be built.
-
-**If the user declines competitor research**, skip Phase 2 entirely. In all subsequent phases, ignore instructions that reference competitor research findings — rely only on the gspec documents and user input. Inform the user: *"Understood — I'll plan and build based on your gspec documents and any direction you provide. Only features defined in your specs (or that you request) will be implemented."*
-
-**If the user accepts**, proceed to Phase 2.
-
-### Phase 2: Competitor Research — Understand the Landscape
-
-> **This phase only runs if the user opted in during Phase 1.**
-
-Research the competitors identified in `gspec/profile.md` to ground your feature proposals in market reality. This ensures the product doesn't miss table-stakes features and capitalizes on genuine differentiation opportunities.
-
-#### Step 1: Research Each Competitor
-
-For every direct and indirect competitor named in the profile:
-
-1. **Research their product** — Investigate their publicly available information (website, documentation, product pages, feature lists, reviews, changelogs)
-2. **Catalog their key features and capabilities** — What core functionality do they offer? What does their product actually do for users?
-3. **Note their UX patterns and design decisions** — How do they structure navigation, onboarding, key workflows? What conventions has the market established?
-4. **Identify their strengths and weaknesses** — What do users praise? What do reviews and discussions criticize? Where do they fall short?
-
-#### Step 2: Build a Competitive Feature Matrix (IF a competitor is mentioned)
-
-Synthesize your research into a structured comparison:
-
-| Feature / Capability | Competitor A | Competitor B | Competitor C | Our Product (Specified) |
-|---|---|---|---|---|
-| Feature X | ✅ | ✅ | ✅ | ✅ |
-| Feature Y | ✅ | ✅ | ❌ | ❌ (gap) |
-| Feature Z | ❌ | ❌ | ❌ | ❌ (opportunity) |
-
-#### Step 3: Categorize Findings
-
-Classify every feature and capability into one of three categories:
-
-1. **Table-Stakes Features** — Features that *every* or *nearly every* competitor offers. Users will expect these as baseline functionality. If our specs don't cover them, they are likely P0 gaps.
-2. **Differentiating Features** — Features that only *some* competitors offer. These represent opportunities to match or exceed competitors. Evaluate against the product's stated differentiation strategy.
-3. **White-Space Features** — Capabilities that *no* competitor does well (or at all). These align with the product profile's claimed white space and represent the strongest differentiation opportunities.
-
-#### Step 4: Assess Alignment
-
-Compare the competitive landscape against the product's existing specs:
-
-- Which **table-stakes features** are missing from our feature specs? Flag these as high-priority gaps.
-- Which **differentiating features** align with our stated competitive advantages? Confirm these are adequately specified.
-- Which **white-space opportunities** support the product's mission and vision? These may be the most strategically valuable features to propose.
-- Are there competitor features that contradict our product's "What It Isn't" section? Explicitly exclude these.
-
-#### Step 5: Present Findings and Ask Feature-by-Feature Questions
-
-Present the competitive feature matrix to the user, then **walk through each gap or opportunity individually** and ask the user whether they want to include it. Do not dump a summary and wait — make it a conversation.
-
-**5a. Show the matrix.** Present the competitive feature matrix from Step 2 so the user can see the full landscape at a glance.
-
-**5b. For each gap or opportunity, ask a specific question.** Group and present them by category (table-stakes first, then differentiators, then white-space), and for each one:
-
-1. **Name the feature or capability**
-2. **Explain what it is** and what user need it serves
-3. **State the competitive context** — which competitors offer it, how they handle it, and what category it falls into (table-stakes / differentiator / white space)
-4. **Give your recommendation** — should the product include this? Why or why not?
-5. **Ask the user**: *"Do you want to include this feature?"* — Yes, No, or Modified (let them adjust scope)
-
-Example:
-> **CSV Export** — Competitors A and B both offer CSV export for all data views. This is a table-stakes feature that users will expect. I recommend including it as P1.
-> → Do you want to include CSV export?
-
-**5c. Compile the accepted list.** After walking through all items, summarize which features the user accepted, rejected, and modified. This accepted list carries forward into Phase 3 planning alongside any pre-existing gspec features.
-
-**Do not proceed to Phase 3 until all questions are resolved.**
-
-### Phase 3: Analysis — Identify Gaps & Plan
-
-After reading the specs (and completing competitor research if the user opted in), **enter plan mode** and:
-
-> **Competitor research is conditional.** Throughout this phase, instructions that reference competitor research findings only apply if the user opted into Phase 2. If they declined, skip those sub-steps and rely solely on gspec documents and user input. Features accepted during Phase 2's question-driven review are treated as approved scope alongside any pre-existing gspec features.
+> **Competitive research is conditional.** Throughout this phase, instructions that reference competitive research findings only apply if `gspec/research.md` exists and was read during Phase 1. If no research file exists, skip those sub-steps and rely solely on gspec documents and user input. Features listed in `gspec/research.md`'s "Accepted Findings" section are treated as approved scope alongside any pre-existing gspec features.
 
 #### When features/epics exist:
 
 1. **Summarize your understanding** of the feature(s) to be implemented. **Distinguish between already-implemented capabilities (checked `[x]`) and pending capabilities (unchecked `[ ]`).** Only pending capabilities are in scope for this run. Reference already-implemented capabilities as context — they inform how new capabilities should integrate, but do not re-implement them unless the user explicitly requests it.
-2. **Propose additional features** informed by the product profile (and competitor research, if conducted):
+2. **Propose additional features** informed by the product profile (and competitive research, if available):
    - Review the product profile's mission, target audience, use cases, and value proposition
-   - *If competitor research was conducted:* Reference findings — identify where competitors set user expectations that our specs don't meet. Note that features already accepted during Phase 2 don't need to be re-proposed here.
+   - *If `gspec/research.md` exists:* Reference findings — identify where competitors set user expectations that our specs don't meet. Note that features listed in `gspec/research.md`'s "Accepted Findings" don't need to be re-proposed here.
    - Consider supporting features that would make specified features more complete or usable (e.g., onboarding, settings, notifications, error recovery)
    - Look for gaps between the product's stated goals/success metrics and the features specified to achieve them
    - For each proposed feature, explain:
      - What it is and what user need it serves
      - How it connects to the product profile's mission or target audience
-     - *If competitor research was conducted:* What the competitive landscape says — is this table-stakes, a differentiator, or white space?
+     - *If `gspec/research.md` exists:* What the competitive landscape says — is this table-stakes, a differentiator, or white space?
      - Suggested priority level (P0/P1/P2) and rationale
      - Whether it blocks or enhances any specified features
    - **The user decides which proposed features to accept, modify, or reject**
@@ -166,17 +85,17 @@ After reading the specs (and completing competitor research if the user opted in
    - 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
+   - *If `gspec/research.md` exists:* Patterns that differ from established competitor conventions without clear rationale — users may have ingrained expectations from competitor products
 4. **Propose solutions** for each gap:
    - Explain what's missing and why it matters
    - Offer 2-3 concrete options when multiple approaches are viable
-   - *If competitor research was conducted:* Reference how competitors handle the same problem when relevant — not to copy, but to inform
+   - *If `gspec/research.md` exists:* Reference how competitors handle the same problem when relevant — not to copy, but to inform
    - Recommend your preferred approach with rationale
    - Flag any proposals that deviate from or extend the original spec
 5. **Present an implementation plan** covering only pending (unchecked) capabilities, with:
    - Ordered list of components/files to create or modify
    - Dependencies between implementation steps
-   - Which gspec requirements each step satisfies (including any features approved during Phase 2 and this phase)
+   - Which gspec requirements each step satisfies (including any features accepted from `gspec/research.md` and this phase)
    - Estimated scope (small/medium/large) for each step
    - Note which already-implemented capabilities the new work builds on or integrates with
 
@@ -191,7 +110,7 @@ When feature PRDs and epics are absent, derive what to build from the **user's p
    - `gspec/style.md` — design system and UI patterns
    - `gspec/practices.md` — development standards and quality gates
 2. **Define the scope** — Based on the user's prompt and available gspec context, propose a clear scope of work: what you intend to build, broken into logical units
-3. **Propose additional capabilities** informed by the product profile (and competitor research if conducted), following the same guidelines as above (propose, explain rationale, let user decide)
+3. **Propose additional capabilities** informed by the product profile (and competitive research from `gspec/research.md` if available), following the same guidelines as above (propose, explain rationale, let user decide)
 4. **Identify gaps and ambiguities** in the user's prompt — areas where intent is unclear or important decisions need to be made. Propose solutions with 2-3 options where applicable.
 5. **Present an implementation plan** with:
    - Ordered list of components/files to create or modify
@@ -201,9 +120,9 @@ When feature PRDs and epics are absent, derive what to build from the **user's p
 
 **Wait for user approval before proceeding.** The user may accept, modify, or reject any of your proposals.
 
-### Phase 3b: Codify Approved Features
+### Phase 2b: Codify Approved Features
 
-After the user approves proposed features (whether from gap analysis, competitor research, or the user's own additions during planning), **write each approved feature as a formal PRD** in `gspec/features/` before implementing it. This ensures the project's spec library stays complete and that future implement runs have full context.
+After the user approves proposed features (whether from gap analysis, competitive research findings, or the user's own additions during planning), **write each approved feature as a formal PRD** in `gspec/features/` before implementing it. This ensures the project's spec library stays complete and that future implement runs have full context.
 
 For each approved feature that doesn't already have a PRD in `gspec/features/`:
 
@@ -217,17 +136,17 @@ For each approved feature that doesn't already have a PRD in `gspec/features/`:
    - Success Metrics
    - Begin the file with YAML frontmatter: `---\ngspec-version: <<<VERSION>>>\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
+3. **Keep the PRD portable** — use generic role descriptions (not project-specific persona names), define success metrics in terms of the feature's own outcomes (not project-level KPIs), and describe UX behavior generically (not tied to a specific design system). The PRD should be reusable across projects; project-specific context is resolved when `gspec-implement` reads all gspec documents at implementation time.
 4. **Keep the PRD product-focused** — describe *what* and *why*, not *how*. Implementation details belong in the code, not the PRD.
-5. **Note the feature's origin** — in the Assumptions section, note that this feature was identified and approved during implementation planning (e.g., from competitor research, gap analysis, or user direction)
+5. **Note the feature's origin** — in the Assumptions section, note that this feature was identified and approved during implementation planning (e.g., from competitive research, gap analysis, or user direction)
 
 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
+### Phase 2c: 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.
+After all approved features are codified as PRDs, **enter plan mode** and create a concrete, phased implementation plan. This is distinct from Phase 2'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
+1. **Survey the full scope** — Review all feature PRDs (both pre-existing and newly codified in Phase 2b) 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
@@ -237,12 +156,26 @@ After all approved features are codified as PRDs, **enter plan mode** and create
 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.
+**Wait for user approval before proceeding to Phase 3.** The user may reorder phases, adjust scope, or split/merge phases.
 
-### Phase 4: Implementation — Build It
+### Phase 3: Implementation — Build It
 
 Once the implementation plan is approved, execute it **phase by phase**.
 
+#### Pre-Implementation: Git Checkpoint
+
+Before writing any code, create a git commit to establish a clean rollback point:
+
+1. **Check for uncommitted changes** — Run `git status` to see if there are staged or unstaged changes in the working tree
+2. **If uncommitted changes exist**, stage and commit them:
+   - `git add -A`
+   - Commit with the message: `chore: pre-implement checkpoint`
+   - Inform the user: *"I've committed your existing changes as a checkpoint. If you need to roll back the implementation, you can return to this commit."*
+3. **If the working tree is clean**, inform the user: *"Working tree is clean — no checkpoint commit needed."*
+4. **If the project is not a git repository**, skip this step and note that no rollback point was created
+
+This step is not optional. A clean checkpoint ensures the user can always `git reset` or `git diff` against the pre-implementation state.
+
 #### 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).
@@ -267,7 +200,7 @@ Present a brief scaffold summary to the user before proceeding to feature implem
    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.
+   e. *If `gspec/research.md` exists:* **Leverage competitive insights** — When making UX or interaction design decisions not fully specified in the style guide, consider established patterns from the competitive 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: <<<VERSION>>>\n---` at the top.
 4. **Update epic status** — When all capabilities in a feature PRD are checked, update the corresponding feature's checkbox in the epic summary file (if one exists) from `- [ ]` to `- [x]`.
 5. **Run tests** — Execute the tests defined for this phase (and any existing tests to catch regressions). Fix any failures before proceeding.
@@ -282,14 +215,14 @@ Present a brief scaffold summary to the user before proceeding to feature implem
 
 **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
+### Phase 4: 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** — 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?
+4. *If `gspec/research.md` exists:* **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
 6. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were intentionally deferred. Present a final status summary:
 
@@ -308,8 +241,8 @@ When you encounter something the specs don't cover, follow these principles:
 - Propose sensible defaults based on the product profile and target users
 - Infer behavior from similar patterns already specified in the PRDs (if available) or from the product profile and user's prompt
 - Suggest industry-standard approaches for common problems (auth flows, error handling, pagination, etc.)
-- *If competitor research was conducted:* Reference competitor implementations to inform proposals — "Competitor X handles this with [approach], which works well because [reason]"
-- *If competitor research was conducted:* Use findings to validate table-stakes expectations — if every competitor offers a capability, users likely expect it
+- *If `gspec/research.md` exists:* Reference competitor implementations to inform proposals — "Competitor X handles this with [approach], which works well because [reason]"
+- *If `gspec/research.md` exists:* Use findings to validate table-stakes expectations — if every competitor offers a capability, users likely expect it
 - Consider the user experience implications of each decision
 - Present tradeoffs clearly (simplicity vs. completeness, speed vs. correctness)
 - **Propose features** that the product profile implies but no feature PRD covers — the user's feature list (if any) is a starting point, not a ceiling
@@ -323,8 +256,8 @@ When you encounter something the specs don't cover, follow these principles:
 - Assume technical constraints that aren't documented
 - Skip gap analysis because the implementation seems obvious
 - Propose features that contradict the product profile's "What It Isn't" section or stated non-goals
-- *If competitor research was conducted:* Blindly copy competitor features — research informs proposals, but the product's own identity, differentiation strategy, and stated non-goals take precedence
-- *If competitor research was conducted:* Treat competitor parity as an automatic requirement — some competitor features may be intentionally excluded per the product's positioning
+- *If `gspec/research.md` exists:* Blindly copy competitor features — research informs proposals, but the product's own identity, differentiation strategy, and stated non-goals take precedence
+- *If `gspec/research.md` exists:* Treat competitor parity as an automatic requirement — some competitor features may be intentionally excluded per the product's positioning
 
 ---
 
@@ -335,7 +268,7 @@ When you encounter something the specs don't cover, follow these principles:
 If `gspec/features/` and `gspec/epics/` are empty or absent, use the **user's prompt** as the primary guide for what to build:
 
 1. **If the user provided a prompt** to the implement command, treat it as your primary directive. The prompt may describe a feature, a scope of work, a user story, or a high-level goal. Combine it with the remaining gspec files (profile, stack, style, practices) to plan and build.
-2. **If the user provided no prompt either**, use the product profile to propose a logical starting point — focus on the product's core value proposition and primary use cases (and table-stakes features from competitor research, if conducted). Suggest a starting point and confirm with the user.
+2. **If the user provided no prompt either**, use the product profile to propose a logical starting point — focus on the product's core value proposition and primary use cases (and table-stakes features from `gspec/research.md`, if available). Suggest a starting point and confirm with the user.
 
 ### When features and/or epics exist:
 
@@ -349,14 +282,14 @@ If the user doesn't specify which feature to implement:
 2. **Focus on features with unchecked capabilities** — Features with all capabilities checked are complete and can be skipped
 3. Among features with pending work, prioritize unchecked P0 capabilities over P1, P1 over P2
 4. Respect dependency ordering — build foundations before dependent features
-5. *If competitor research was conducted:* Review findings for table-stakes gaps — missing table-stakes features may need to be addressed early to meet baseline user expectations
+5. *If `gspec/research.md` exists:* Review findings for table-stakes gaps — missing table-stakes features may need to be addressed early to meet baseline user expectations
 6. Review the product profile for business needs that aren't covered by any existing feature PRD — propose additional features where the gap is significant
 7. Suggest a starting point and confirm with the user
 
 If the user specifies a feature, focus on that feature's **unchecked capabilities** but:
 - Note any unmet dependencies
 - Flag any closely related capabilities that the product profile suggests but no feature PRD covers — these may be worth implementing alongside or immediately after the specified feature
-- *If competitor research was conducted:* Note if competitors handle related workflows differently — the user may want to consider alternative approaches informed by market conventions
+- *If `gspec/research.md` exists:* Note if competitors handle related workflows differently — the user may want to consider alternative approaches informed by market conventions
 - If the user explicitly asks to re-implement a checked capability, honor that request
 
 ### When the user provides a prompt alongside existing features/epics:
@@ -367,11 +300,11 @@ The user's prompt takes priority for scoping. Use it to determine focus, and ref
 
 ## Output Rules
 
-- **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
+- **Use plan mode twice** — once in Phase 2 for gap analysis and feature proposals, and again in Phase 2c for the concrete implementation plan. Both require user approval before proceeding.
+- **Pause between implementation phases** — After completing each phase in Phase 3, 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"
+- *If `gspec/research.md` exists:* When referencing findings, clearly attribute them — "Competitor X does Y" not "the industry does Y"
 - 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
@@ -383,5 +316,5 @@ The user's prompt takes priority for scoping. Use it to determine focus, and ref
 - Collaborative and consultative — you're a partner, not an order-taker
 - Technically precise when discussing implementation
 - Product-aware when discussing gaps — frame proposals in terms of user value
-- **Market-informed when proposing features** (if competitor research was conducted) — ground recommendations in competitive reality, not just abstract best practices
+- **Market-informed when proposing features** (if `gspec/research.md` exists) — ground recommendations in competitive reality, not just abstract best practices
 - Transparent about assumptions and tradeoffs