gspec 1.1.2 → 1.4.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 |
 |---|---|---|
@@ -97,6 +142,7 @@ The CLI will ask which platform you're installing for:
 | Claude Code | `.claude/skills/` |
 | Cursor | `.cursor/commands/` |
 | Antigravity | `.agent/skills/` |
+| Codex | `.agents/skills/` |
 
 You can skip the prompt by passing a target directly:
 
@@ -104,6 +150,7 @@ You can skip the prompt by passing a target directly:
 npx gspec --target claude
 npx gspec --target cursor
 npx gspec --target antigravity
+npx gspec --target codex
 ```
 
 That's it. The commands are immediately available in your AI tool.
@@ -120,6 +167,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,9 +188,9 @@ 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.
+**Platform-agnostic.** A single set of source commands builds for Claude Code, Cursor, Antigravity, and Codex. The build system handles platform-specific formatting so the commands stay consistent across tools.
 
 ## Supported Platforms
 
@@ -151,6 +199,7 @@ These are standard Markdown files. They live in your repo, are version-controlle
 | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Skills format | Supported |
 | [Cursor](https://www.cursor.com/) | Commands format | Supported |
 | [Antigravity](https://www.antigravity.dev/) | Skills format | Supported |
+| [Codex](https://developers.openai.com/codex/cli/) | Skills format | Supported |
 
 ## Project Status
 

package/bin/gspec.js

@@ -45,12 +45,19 @@ const TARGETS = {
     label: 'Antigravity',
     layout: 'directory',
   },
+  codex: {
+    sourceDir: join(DIST_DIR, 'codex'),
+    installDir: '.agents/skills',
+    label: 'Codex',
+    layout: 'directory',
+  },
 };
 
 const TARGET_CHOICES = [
   { key: '1', name: 'claude', label: 'Claude Code' },
   { key: '2', name: 'cursor', label: 'Cursor' },
   { key: '3', name: 'antigravity', label: 'Antigravity' },
+  { key: '4', name: 'codex', label: 'Codex' },
 ];
 
 function promptTarget() {
@@ -63,7 +70,7 @@ function promptTarget() {
   console.log();
 
   return new Promise((resolve) => {
-    rl.question(chalk.bold('  Select [1-3]: '), (answer) => {
+    rl.question(chalk.bold('  Select [1-4]: '), (answer) => {
       rl.close();
       const trimmed = answer.trim().toLowerCase();
 
@@ -76,7 +83,7 @@ function promptTarget() {
       if (byName) return resolve(byName.name);
 
       console.error(chalk.red(`\nInvalid selection: "${answer.trim()}"`));
-      console.error(`Valid options: 1, 2, 3, claude, cursor, antigravity`);
+      console.error(`Valid options: 1, 2, 3, 4, claude, cursor, antigravity, codex`);
       process.exit(1);
     });
   });
@@ -215,6 +222,7 @@ const MIGRATE_COMMANDS = {
   claude: '/gspec-migrate',
   cursor: '/gspec-migrate',
   antigravity: '/gspec-migrate',
+  codex: '/gspec-migrate',
 };
 
 function parseGspecVersion(content) {
@@ -297,7 +305,7 @@ program
   .name('gspec')
   .description('Install gspec specification commands')
   .version(pkg.version)
-  .option('-t, --target <target>', 'target platform (claude, cursor, antigravity)')
+  .option('-t, --target <target>', 'target platform (claude, cursor, antigravity, codex)')
   .action(async (opts) => {
     console.log(BANNER);
 

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