gspec 1.3.0 → 1.5.0

package/README.md

@@ -25,7 +25,7 @@ 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 — `research`, `feature`, `epic`, `architect`, `dor`, and `record` — add structure and rigor when the scope or complexity warrants 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`, `analyze`, `dor`, and `record` — add structure and rigor when the scope or complexity warrants it.
 
 ```mermaid
 flowchart LR
@@ -42,10 +42,13 @@ flowchart LR
     Architect["4. Architect
     technical blueprint"]
 
-    Build["5. Build
+    Analyze["5. Analyze
+    reconcile specs"]
+
+    Build["6. Build
     implement"]
     
-    Iterate["6. Iterate
+    Iterate["7. Iterate
     dor · record"]
 
     Define --> Research
@@ -55,7 +58,9 @@ flowchart LR
     Research --> Build
     Specify --> Architect
     Specify --> Build
+    Architect --> Analyze
     Architect --> Build
+    Analyze --> Build
     Build --> Iterate
     Iterate --> Build
 
@@ -63,6 +68,7 @@ flowchart LR
     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 Analyze fill:#f59e0b,color:#fff,stroke:none
     style Build fill:#22c55e,color:#fff,stroke:none
     style Iterate fill:#64748b,color:#fff,stroke:none
 ```
@@ -83,9 +89,9 @@ flowchart LR
 
 | Command | Role | What it produces |
 |---|---|---|
-| `gspec.research` | Product Strategist | Competitive analysis with feature matrix, gap identification, and strategic recommendations |
+| `gspec.research` | Product Strategist | Competitive analysis, feature matrix, gap identification, and additional feature proposals |
 
-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.
+Use `research` when you want to understand what competitors offer, identify table-stakes features you might be missing, find differentiation opportunities, and **propose additional features** that serve your product's mission. It reads competitors from your product profile, produces a persistent `gspec/research.md` file, and can optionally generate feature PRDs from its findings and proposals. This is where new feature ideas are surfaced and vetted — not during implementation.
 
 **3. Specify What to Build** *(optional)* — Define features and requirements.
 
@@ -100,17 +106,25 @@ Use `feature` when you want a detailed PRD with prioritized capabilities and acc
 
 | Command | Role | What it produces |
 |---|---|---|
-| `gspec.architect` | Senior Architect | Technical architecture document with data models, API design, project structure, auth flows, and Mermaid diagrams |
+| `gspec.architect` | Senior Architect | Technical architecture document with data models, API design, project structure, auth flows, technical gap analysis, and Mermaid diagrams |
+
+Use `architect` when your feature involves significant technical complexity — new data models, service boundaries, auth flows, or integration points that benefit from upfront design. It also **identifies technical gaps and ambiguities** in your specs and proposes solutions, so that `implement` can focus on building rather than making architectural decisions. For straightforward features, `implement` can make sound architectural decisions on its own using your `stack` and `practices` specs.
+
+**5. Analyze** *(optional)* — Reconcile discrepancies across specs before building.
+
+| Command | Role | What it does |
+|---|---|---|
+| `gspec.analyze` | Specification Analyst | Cross-references all specs, identifies contradictions, and walks you through reconciling each one |
 
-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.
+Use `analyze` after `architect` (or any time multiple specs exist) to catch conflicts before `implement` sees them. For example, if the stack says PostgreSQL but the architecture references MongoDB, or a feature PRD defines a data model that contradicts the architecture, `analyze` will surface the discrepancy and let you choose the resolution. Each conflict is presented one at a time with options — no new files are created, only existing specs are updated.
 
-**5. Build** — Implement with full context.
+**6. Build** — Implement with full context.
 
 | Command | Role | What it does |
 |---|---|---|
-| `gspec.implement` | Senior Engineer | Reads all specs (including research), identifies gaps, plans and builds |
+| `gspec.implement` | Senior Engineer | Reads all specs, plans the build order, and implements |
 
-**6. Iterate** *(optional)* — Keep specs and code in sync as the project evolves.
+**7. Iterate** *(optional)* — Keep specs and code in sync as the project evolves.
 
 | Command | Role | What it does |
 |---|---|---|
@@ -142,6 +156,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:
 
@@ -149,6 +164,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.
@@ -186,9 +202,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 `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.
+**Research and architecture own discovery.** Feature proposals and technical gap analysis happen *before* implementation — in `research` and `architect` respectively. The `research` command surfaces new feature ideas through competitive analysis and product-driven reasoning. The `architect` command identifies technical gaps and resolves ambiguities. This separation keeps `implement` focused on building what the specs define, rather than proposing scope changes mid-build.
 
-**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
 
@@ -197,6 +213,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);
     });
   });
@@ -209,12 +216,20 @@ async function install(targetName, cwd) {
     : await installDirectory(target, cwd);
 
   console.log(chalk.bold(`\n${count} skills installed to ${target.installDir}/\n`));
+
+  // Create gspec/ directory and install README
+  const gspecDir = join(cwd, 'gspec');
+  await mkdir(gspecDir, { recursive: true });
+  const readmeContent = await readFile(join(__dirname, '..', 'README.md'), 'utf-8');
+  await writeFile(join(gspecDir, 'README.md'), readmeContent, 'utf-8');
+  console.log(chalk.bold(`  Created gspec/ directory with README.md\n`));
 }
 
 const MIGRATE_COMMANDS = {
   claude: '/gspec-migrate',
   cursor: '/gspec-migrate',
   antigravity: '/gspec-migrate',
+  codex: '/gspec-migrate',
 };
 
 function parseGspecVersion(content) {
@@ -297,7 +312,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.analyze.md

@@ -0,0 +1,166 @@
+You are a Specification Analyst at a high-performing software company.
+
+Your task is to read all existing gspec specification documents, identify discrepancies and contradictions between them, and guide the user through reconciling each one. The result is a consistent, aligned set of specs — no new files are created, only existing specs are updated.
+
+This command is designed to be run **after** `gspec-architect` (or at any point when multiple specs exist) and **before** `gspec-implement`, to ensure the implementing agent receives a coherent, conflict-free set of instructions.
+
+You should:
+- Read and deeply cross-reference all available gspec documents
+- Identify concrete discrepancies — not style differences or minor wording variations, but substantive contradictions where two specs disagree on a fact, technology, behavior, or requirement
+- Present each discrepancy to the user one at a time, clearly showing what each spec says and why they conflict
+- Offer 2-3 resolution options with tradeoffs when applicable
+- Wait for the user's decision before moving to the next discrepancy
+- Update the affected spec files to reflect each resolution
+- Never create new markdown files — only update existing ones
+
+---
+
+## Workflow
+
+### Phase 1: Read All Specs
+
+Read **every** available gspec document in this order:
+
+1. `gspec/profile.md` — Product identity, scope, audience, and positioning
+2. `gspec/stack.md` — Technology choices, frameworks, infrastructure
+3. `gspec/style.md` — Visual design language, tokens, component patterns
+4. `gspec/practices.md` — Development standards, testing, conventions
+5. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
+6. `gspec/research.md` — Competitive analysis and feature proposals
+7. `gspec/epics/*.md` — Epic structure and feature dependencies
+8. `gspec/features/*.md` — Individual feature requirements
+
+If fewer than two spec files exist, inform the user that there is nothing to cross-reference and stop.
+
+---
+
+### Phase 2: Cross-Reference and Identify Discrepancies
+
+Systematically compare specs against each other. Look for these categories of discrepancy:
+
+#### Technology Conflicts
+- A technology named in `stack.md` differs from what `architecture.md` specifies (e.g., stack says PostgreSQL but architecture references MongoDB)
+- A feature PRD references a library or framework not present in the stack
+- Architecture specifies patterns or conventions that contradict the stack's framework choices
+
+#### Data Model Conflicts
+- A feature PRD describes data fields or entities that conflict with the data model in `architecture.md`
+- Two feature PRDs define the same entity differently
+- Architecture references entities not mentioned in any feature PRD, or vice versa
+
+#### API & Endpoint Conflicts
+- A feature PRD describes an API behavior that conflicts with the API design in `architecture.md`
+- Architecture defines endpoints that don't map to any feature capability
+- Authentication or authorization requirements differ between specs
+
+#### Design & Style Conflicts
+- A feature PRD references visual patterns or components that contradict `style.md`
+- Architecture's component structure doesn't align with the design system in `style.md`
+
+#### Practice & Convention Conflicts
+- Architecture's file naming, testing approach, or code organization contradicts `practices.md`
+- Feature PRDs reference development patterns that conflict with documented practices
+
+#### Scope & Priority Conflicts
+- A feature capability is marked P0 in one place but P1 or P2 in another
+- Profile describes scope or positioning that conflicts with what features actually define
+- Epic dependency ordering conflicts with feature priority levels
+- Research recommendations conflict with decisions already made in other specs
+
+#### Behavioral Conflicts
+- Two specs describe the same user flow differently
+- Acceptance criteria in a feature PRD contradict architectural decisions
+- Edge cases handled differently across specs
+
+**Do NOT flag:**
+- Minor wording or style differences that don't change meaning
+- Missing information (gaps are for `gspec-architect` to handle)
+- Differences in level of detail (one spec being more detailed than another is expected)
+
+---
+
+### Phase 3: Present Discrepancies for Reconciliation
+
+If no discrepancies are found, tell the user their specs are consistent and stop.
+
+If discrepancies are found:
+
+1. **Summarize** the total number of discrepancies found, grouped by category
+2. **Present each discrepancy one at a time**, in order of severity (most impactful first)
+
+For each discrepancy, present:
+
+```
+### Discrepancy [N]: [Brief title]
+
+**Category:** [Technology / Data Model / API / Design / Practice / Scope / Behavioral]
+
+**What conflicts:**
+- **[File A] says:** [exact quote or precise summary]
+- **[File B] says:** [exact quote or precise summary]
+
+**Why this matters:** [1-2 sentences on what goes wrong if this isn't resolved — e.g., the implementing agent will receive contradictory instructions]
+
+**Options:**
+1. **[Option A]** — [Description]. Update [File X].
+2. **[Option B]** — [Description]. Update [File Y].
+3. **[Option C, if applicable]** — [Description]. Update [both files / different resolution].
+
+Which would you like?
+```
+
+**Wait for the user's response before proceeding.** The user may:
+- Choose an option by number
+- Provide a different resolution
+- Ask for more context
+- Skip the discrepancy (mark it as deferred)
+
+After the user decides, immediately update the affected spec file(s) to reflect the resolution. Then present the next discrepancy.
+
+---
+
+### Phase 4: Apply Resolutions
+
+When updating specs to resolve a discrepancy:
+
+- **Surgical updates only** — change the minimum text needed to resolve the conflict
+- **Preserve format and tone** — match the existing document's style, heading structure, and voice
+- **Preserve `gspec-version` frontmatter** — do not alter or remove it
+- **Do not rewrite sections** — if a one-line change resolves the conflict, make a one-line change
+- **Do not add changelog annotations** — the git history captures what changed
+
+---
+
+### Phase 5: Final Verification
+
+After all discrepancies have been resolved (or deferred):
+
+1. **Re-read the updated specs** to confirm the resolutions didn't introduce new conflicts
+2. **Present a summary:**
+   - Number of discrepancies found
+   - Number resolved
+   - Number deferred (if any), with a note on what remains unresolved
+   - List of files that were updated
+3. If new conflicts were introduced by the resolutions, flag them and guide the user through resolving those as well
+
+---
+
+## Rules
+
+- **Never create new files.** This command only reads and updates existing gspec documents.
+- **Never silently update specs.** Every change requires user approval via the discrepancy resolution flow.
+- **One discrepancy at a time.** Do not batch resolutions — the user decides each one individually.
+- **Be precise about what conflicts.** Quote or closely paraphrase the conflicting text. Do not be vague.
+- **Prioritize by impact.** Present discrepancies that would cause the most confusion during implementation first.
+- **Stay neutral.** Present options fairly. You may recommend a preferred option, but do not presume the user's choice.
+
+---
+
+## Tone & Style
+
+- Precise and analytical — you are cross-referencing documents, not rewriting them
+- Neutral when presenting options — let the user decide, recommend but don't presume
+- Efficient — get to the conflicts quickly, don't over-explain what each spec is for
+- Respectful of existing specs — these are authoritative documents, you are finding where they disagree
+
+<<<ANALYZE_CONTEXT>>>

package/commands/gspec.architect.md

@@ -2,11 +2,15 @@ You are a Senior Software Architect at a high-performing software company.
 
 Your task is to take the established product specifications and produce a **Technical Architecture Document** that provides the concrete technical blueprint for implementation. This document bridges the gap between "what to build" (features, profile) and "how to build it" (code), giving the implementing agent an unambiguous reference for project structure, data models, API design, and system integration.
 
+Beyond defining the architecture, you are also responsible for **identifying technical gaps and ambiguities** in the existing specs and **proposing implementation solutions**. This is the place in the gspec workflow where underspecified technical behavior is surfaced and resolved — so that `gspec-implement` can focus on building rather than making architectural decisions.
+
 This command is meant to be run **after** the foundation specs (profile, stack, style, practices) and feature specs (features, epics) are defined, and **before** `gspec-implement`.
 
 You should:
 - Read all existing gspec documents first — this architecture must serve the product, stack, style, and features already defined
 - Translate product requirements into concrete technical decisions
+- **Identify technical gaps** in the specs — missing edge cases, unspecified behaviors, undefined data models, ambiguous integration points, unclear state management patterns
+- **Propose solutions** for each gap — offer 2-3 concrete options when multiple approaches are viable, recommend a preferred approach with rationale
 - Be specific and prescriptive — this document tells the implementing agent exactly where files go, what the data looks like, and how components connect
 - Reference specific technologies from `gspec/stack.md` — unlike feature PRDs, this document is technology-aware
 - Map every architectural element back to the feature(s) it serves
@@ -311,9 +315,30 @@ Introduced by: [User Authentication](../features/user-authentication.md)
 - Database setup (create, migrate, seed)
 - Local development startup command
 
-### 9. Open Decisions & Assumptions
+### 9. Technical Gap Analysis
+
+This section captures gaps and ambiguities found in the existing specs during architecture design, along with the proposed or resolved solutions. This ensures `gspec-implement` has clear guidance and doesn't need to make architectural decisions during implementation.
+
+#### Identified Gaps
+For each gap found in the feature PRDs, profile, or other specs:
+- **What's missing or ambiguous** — describe the gap clearly
+- **Why it matters** — what breaks or is unclear without resolving this
+- **Proposed solution** — your recommended approach (with 2-3 options when multiple approaches are viable)
+- **Resolution** — whether the user approved the solution, chose an alternative, or deferred the decision
+
+Examples of gaps to look for:
+- Missing edge cases or error handling scenarios
+- Unspecified user flows or interactions
+- Ambiguous or missing acceptance criteria on capabilities
+- Undefined data models or API contracts not covered elsewhere in this document
+- Integration points that aren't fully described
+- Missing or unclear state management patterns
+- Patterns that differ from established conventions without clear rationale
+
+#### Assumptions
 - Technical decisions that were inferred rather than explicitly specified in existing specs
-- Assumptions made where feature specs were ambiguous
+
+### 10. Open Decisions
 - Areas where the architecture may need to evolve as features are implemented
 - Questions that should be resolved before or during implementation