gspec 1.1.1 → 1.3.0

package/README.md

@@ -23,9 +23,52 @@ These documents become the shared context for all subsequent AI interactions. Wh
 
 ### The Workflow
 
+The only commands you *need* are the four fundamentals and `implement`. Everything else exists to help when your project calls for it.
+
+The fundamentals give your AI tool enough context to build well — it knows what the product is, how it should look, what technologies to use, and what engineering standards to follow. From there, `implement` can take a plain-language description and start building. The remaining commands — `research`, `feature`, `epic`, `architect`, `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
 ```
-Define → Specify → Architect → Build → Iterate
-```
+
+> **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.
 
@@ -36,32 +79,46 @@ 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** — 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 |
 |---|---|---|
 | `gspec.feature` | Product Manager | PRD for a single feature with prioritized capabilities |
 | `gspec.epic` | Product Manager | Breaks a large epic into multiple feature PRDs with dependency mapping |
 
-**3. Architect** — Translate specs into a concrete technical blueprint.
+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.
+
+**4. Architect** *(optional)* — Translate specs into a concrete technical blueprint.
 
 | Command | Role | What it produces |
 |---|---|---|
 | `gspec.architect` | Senior Architect | Technical architecture document with data models, API design, project structure, auth flows, and Mermaid diagrams |
 
-**4. Build** — Implement with full context.
+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.
+
+**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** — 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 |
 |---|---|---|
 | `gspec.dor` | Engineer + Doc Lead | Makes code changes and updates specs to match |
 | `gspec.record` | Doc Lead | Updates specs to reflect decisions or changes — no code modifications |
 
+Use `dor` and `record` when you want your specification documents to stay accurate as the project evolves. If you're moving fast and specs are secondary, you can skip them — but as a project matures, keeping specs in sync prevents the context drift that degrades AI output over time.
+
 **Maintenance** — Keep specs up to date with the latest gspec format.
 
 | Command | Role | What it does |
@@ -108,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/
@@ -128,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,9 +31,9 @@ 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 clarifying questions when essential information is missing rather than guessing
+- **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
 - Ensure features can be built incrementally and independently when possible
 - Consider dependencies between features
@@ -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
 
@@ -71,13 +77,15 @@ If these files don't exist, proceed without them — they are optional context,
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
-- **Before generating the documents**, ask clarifying questions if:
+- **Before generating the documents, you MUST resolve ambiguities through conversation.** Ask clarifying questions in the chat if:
   - The target users are unclear
   - The scope or boundaries of the epic are ambiguous
   - The breakdown into features is not obvious
   - Success criteria cannot be determined from the description
   - Priority or sequencing is unclear
+  - Any assumption would materially change the shape of the specs
 - **When asking questions**, offer 2-3 specific suggestions to guide the discussion
+- **Do NOT embed unresolved questions in the generated specs.** All questions about scope, users, priorities, capabilities, feature boundaries, and sequencing must be resolved through conversation before writing the documents. The specs should reflect decisions, not open debates.
 - Create an epic summary document at `gspec/epics/[epic-name].md` that:
   - Lists all features in the epic
   - Shows dependencies between features
@@ -111,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
 
@@ -159,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
@@ -187,16 +195,20 @@ For each feature, create a separate file in `gspec/features/[feature-name].md` w
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions (non-blocking unknowns to resolve during implementation)
+- 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 specs are 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)
 
 ### 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
-2. **Ask clarifying questions** if the epic scope, users, or goals are unclear
+2. **Ask clarifying questions in the chat** and wait for answers before proceeding — do not generate specs with embedded questions
 3. **Break down into features** that:
    - Can be built and shipped incrementally
    - Deliver independent user value (when possible)

package/commands/gspec.feature.md

@@ -23,8 +23,8 @@ 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
-- Ask clarifying questions when essential information is missing rather than guessing
+- **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
 - Write for automated implementation with human validation
@@ -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
 
 ---
 
@@ -61,12 +67,14 @@ If these files don't exist, proceed without them — they are optional context,
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
-- **Before generating the document**, ask clarifying questions if:
+- **Before generating the document, you MUST resolve ambiguities through conversation.** Ask clarifying questions in the chat if:
   - The target users are unclear
   - The scope or boundaries of the feature are ambiguous
   - Success criteria cannot be determined from the description
   - Priority or urgency is unspecified
+  - Any assumption would materially change the shape of the spec
 - **When asking questions**, offer 2-3 specific suggestions to guide the discussion
+- **Do NOT embed unresolved questions in the generated spec.** All questions about scope, users, priorities, capabilities, and feature boundaries must be resolved through conversation before writing the document. The spec should reflect decisions, not open debates.
 - Avoid deep system architecture or low-level implementation
 - Avoid detailed workflows or step-by-step descriptions of how the feature functions
 - No code blocks except where examples add clarity
@@ -95,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.
 
 ---
 
@@ -109,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
@@ -137,12 +145,16 @@ This separation allows the same feature spec to be implemented using different t
 
 ### 6. Assumptions & Risks
 - Assumptions (what we're taking as true)
-- Open questions (non-blocking unknowns to resolve during implementation)
+- 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)
 
 ### 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