codex-workflows 0.1.0

package/README.md

@@ -0,0 +1,365 @@
+# codex-workflows
+
+[![Codex CLI](https://img.shields.io/badge/Codex%20CLI-Compatible-10a37f)](https://developers.openai.com/codex/cli)
+[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Spec%20Compliant-blue)](https://developers.openai.com/codex/skills/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**End-to-end AI coding workflows for [Codex CLI](https://developers.openai.com/codex/cli)** — specialized subagents handle requirements, design, implementation, and quality checks so you get code with explicit design docs, test coverage, and commit-level traceability — not just raw generations.
+
+Built on the [Agent Skills specification](https://developers.openai.com/codex/skills/) and [Codex subagents](https://developers.openai.com/codex/subagents). Works with GPT-5.4 and GPT-5.3-Codex-Spark.
+
+---
+
+## Quick Start
+
+```bash
+cd your-project
+npx codex-workflows install
+```
+
+Then in Codex CLI:
+
+```
+$recipe-implement Add user authentication with JWT
+```
+
+`$` is Codex CLI's syntax for invoking a skill explicitly. Type `$recipe-` to see all available recipes via tab completion.
+
+The framework runs a structured workflow — requirements → design → task decomposition → TDD implementation → quality gates — all through specialized subagents.
+
+---
+
+## Why codex-workflows?
+
+**Without codex-workflows:**
+- Code generation is inconsistent across large tasks
+- Requirements and design decisions are implicit — lost after the session
+- Refactoring and debugging become harder as context grows
+
+**With codex-workflows:**
+- Every change is traceable: PRD → Design Doc → Task → Commit
+- Built-in TDD and quality gates catch regressions before commit
+- Large tasks stay structured and reviewable through agent context separation
+
+---
+
+## What It Does
+
+A single request becomes a structured development process:
+
+1. **Understand** the problem (scale, constraints, affected files)
+2. **Design** the solution (ADR, Design Doc with acceptance criteria)
+3. **Break it into tasks** (atomic, 1 commit each)
+4. **Implement with tests** (TDD per task)
+5. **Run quality checks** (lint, test, build — no failing checks)
+
+Each step is handled by a specialized subagent in its own context, preventing context pollution and reducing error accumulation in long-running tasks:
+
+```
+User Request
+    ↓
+requirement-analyzer  →  Scale determination (Small / Medium / Large)
+    ↓
+prd-creator           →  Product requirements (Large scale)
+    ↓
+technical-designer    →  ADR + Design Doc with acceptance criteria
+    ↓
+document-reviewer     →  Quality gate
+    ↓
+acceptance-test-gen   →  Test skeletons from ACs
+    ↓
+work-planner          →  Phased execution plan
+    ↓
+task-decomposer       →  Atomic tasks (1 task = 1 commit)
+    ↓
+task-executor         →  TDD implementation per task
+    ↓
+quality-fixer         →  Lint, test, build — no failing checks
+    ↓
+Ready to commit
+```
+
+### The Diagnosis Pipeline
+
+```
+Problem → investigator → verifier (ACH + Devil's Advocate) → solver → Actionable solutions
+```
+
+### Reverse Engineering
+
+```
+Existing code → scope-discoverer → prd-creator → code-verifier → document-reviewer → Design Docs
+```
+
+---
+
+## Installation
+
+### Requirements
+
+- [Codex CLI](https://developers.openai.com/codex/cli) (latest)
+- Node.js >= 20
+
+### Install
+
+```bash
+cd your-project
+npx codex-workflows install
+```
+
+This copies into your project:
+- `.agents/skills/` — Codex skills (foundational + recipes)
+- `.codex/agents/` — Subagent TOML definitions
+- Manifest file for tracking managed files
+
+### Update
+
+```bash
+# Preview what will change
+npx codex-workflows update --dry-run
+
+# Apply updates
+npx codex-workflows update
+```
+
+Files you've modified locally are preserved — the updater compares each file against its hash at install time and skips any file you've changed. New files from the update are added automatically.
+
+```bash
+# Check installed version
+npx codex-workflows status
+```
+
+---
+
+## Recipe Workflows
+
+Invoke recipes with `$recipe-name` in Codex. Type `$recipe-` and use tab completion to see all available recipes.
+
+### Backend & General
+
+| Recipe | What it does | When to use |
+|--------|-------------|-------------|
+| `$recipe-implement` | Full lifecycle with layer routing (backend/frontend/fullstack) | New features — universal entry point |
+| `$recipe-task` | Single task with rule selection | Bug fixes, small changes |
+| `$recipe-design` | Requirements → ADR/Design Doc | Architecture planning |
+| `$recipe-plan` | Design Doc → test skeletons → work plan | Planning phase |
+| `$recipe-build` | Execute backend tasks autonomously | Resume backend implementation |
+| `$recipe-review` | Design Doc compliance validation with auto-fixes | Post-implementation check |
+| `$recipe-diagnose` | Problem investigation → verification → solution | Bug investigation |
+| `$recipe-reverse-engineer` | Generate PRD + Design Docs from existing code | Legacy system documentation |
+| `$recipe-add-integration-tests` | Add integration/E2E tests from Design Doc | Test coverage for existing code |
+| `$recipe-update-doc` | Update existing Design Doc / PRD / ADR with review | Spec changes, document maintenance |
+
+### Frontend (React/TypeScript)
+
+| Recipe | What it does | When to use |
+|--------|-------------|-------------|
+| `$recipe-front-design` | Requirements → UI Spec → frontend Design Doc | Frontend architecture planning |
+| `$recipe-front-plan` | Frontend Design Doc → test skeletons → work plan | Frontend planning phase |
+| `$recipe-front-build` | Execute frontend tasks with RTL + quality checks | Resume frontend implementation |
+| `$recipe-front-review` | Frontend compliance validation with React-specific fixes | Frontend post-implementation check |
+
+### Fullstack (Cross-Layer)
+
+| Recipe | What it does | When to use |
+|--------|-------------|-------------|
+| `$recipe-fullstack-implement` | Full lifecycle with separate Design Docs per layer | Cross-layer features |
+| `$recipe-fullstack-build` | Execute tasks with layer-aware agent routing | Resume cross-layer implementation |
+
+### Examples
+
+**Full feature development:**
+```
+$recipe-implement Add user authentication with JWT and role-based access control
+```
+
+**Quick fix with proper rule selection:**
+```
+$recipe-task Fix validation error message in checkout form
+```
+
+**Investigate a bug:**
+```
+$recipe-diagnose API returns 500 error on user login after deployment
+```
+
+**Document undocumented legacy code:**
+```
+$recipe-reverse-engineer src/auth module
+```
+
+---
+
+## Foundational Skills
+
+These load automatically when the conversation context matches — no explicit invocation needed:
+
+| Skill | What it provides |
+|-------|-----------------|
+| `coding-rules` | Code quality, function design, error handling, refactoring |
+| `testing` | TDD Red-Green-Refactor, test types, AAA pattern, mocking |
+| `ai-development-guide` | Anti-patterns, debugging (5 Whys), quality check workflow |
+| `documentation-criteria` | Document creation rules and templates (PRD, ADR, Design Doc, Work Plan) |
+| `implementation-approach` | Strategy selection: vertical / horizontal / hybrid slicing |
+| `integration-e2e-testing` | Integration/E2E test design, ROI calculation, review criteria |
+| `task-analyzer` | Task analysis, scale estimation, skill selection |
+| `subagents-orchestration-guide` | Multi-agent coordination, workflow flows, autonomous execution |
+
+Language-specific references are included for TypeScript/React projects (`coding-rules/references/typescript.md`, `testing/references/typescript.md`).
+
+---
+
+## Subagents
+
+Codex spawns these as needed during recipe execution. Each agent runs in its own context with specialized instructions and skill configurations.
+
+### Document Creation Agents
+
+| Agent | Role |
+|-------|------|
+| `requirement-analyzer` | Requirements analysis and work scale determination |
+| `prd-creator` | PRD creation and structuring |
+| `technical-designer` | ADR and Design Doc creation (backend) |
+| `technical-designer-frontend` | Frontend ADR and Design Doc creation (React) |
+| `ui-spec-designer` | UI Specification from PRD and optional prototype code |
+| `work-planner` | Work plan creation from Design Docs |
+| `document-reviewer` | Document consistency and approval |
+| `design-sync` | Cross-document consistency verification |
+
+### Implementation Agents
+
+| Agent | Role |
+|-------|------|
+| `task-decomposer` | Work plan → atomic task files |
+| `task-executor` | TDD implementation following task files (backend) |
+| `task-executor-frontend` | React implementation with Testing Library |
+| `quality-fixer` | Quality checks and fixes until all pass (backend) |
+| `quality-fixer-frontend` | React-specific quality checks (TypeScript, RTL, bundle) |
+| `acceptance-test-generator` | Test skeleton generation from acceptance criteria |
+| `integration-test-reviewer` | Test quality review |
+
+### Analysis Agents
+
+| Agent | Role |
+|-------|------|
+| `code-reviewer` | Design Doc compliance validation |
+| `code-verifier` | Document-code consistency verification |
+| `rule-advisor` | Skill selection via metacognitive analysis |
+| `scope-discoverer` | Codebase scope discovery for reverse docs |
+
+### Diagnosis Agents
+
+| Agent | Role |
+|-------|------|
+| `investigator` | Evidence collection and hypothesis enumeration |
+| `verifier` | Hypothesis validation (ACH + Devil's Advocate) |
+| `solver` | Solution derivation with tradeoff analysis |
+
+---
+
+## How It Works
+
+### Scale-Based Workflow Selection
+
+The framework automatically determines the right level of ceremony:
+
+| Scale | File Count | What Happens |
+|-------|------------|-------------|
+| Small | 1-2 | Simplified plan → direct implementation |
+| Medium | 3-5 | Design Doc → work plan → task execution |
+| Large | 6+ | PRD → ADR → Design Doc → test skeletons → work plan → autonomous execution |
+
+### Autonomous Execution Mode
+
+After work plan approval, the framework enters guided autonomous execution with escalation points:
+
+1. **task-executor** implements each task with TDD
+2. **quality-fixer** runs all checks (lint, tests, build) before every commit
+3. Escalation pauses execution when design deviation or ambiguity is detected
+4. Each task produces one commit — rollback-friendly granularity
+
+### Context Separation
+
+Each subagent runs in a fresh context. This matters because:
+- **document-reviewer** reviews without the author's bias
+- **investigator** collects evidence without confirmation bias
+- **code-reviewer** validates compliance without implementation context
+
+---
+
+## Project Structure
+
+After installation, your project gets:
+
+```
+your-project/
+├── .agents/skills/           # Codex skills
+│   ├── coding-rules/         # Foundational (auto-loaded)
+│   ├── testing/
+│   ├── ai-development-guide/
+│   ├── documentation-criteria/
+│   ├── implementation-approach/
+│   ├── integration-e2e-testing/
+│   ├── task-analyzer/
+│   ├── subagents-orchestration-guide/
+│   ├── recipe-implement/     # Recipes ($recipe-*)
+│   ├── recipe-design/
+│   ├── recipe-build/
+│   ├── recipe-plan/
+│   ├── recipe-review/
+│   ├── recipe-diagnose/
+│   ├── recipe-task/
+│   ├── recipe-update-doc/
+│   ├── recipe-reverse-engineer/
+│   └── recipe-add-integration-tests/
+├── .codex/agents/            # Subagent TOML definitions
+│   ├── requirement-analyzer.toml
+│   ├── technical-designer.toml
+│   ├── task-executor.toml
+│   └── ... (22 agents total)
+└── docs/                     # Created as you use the recipes
+    ├── prd/
+    ├── design/
+    ├── adr/
+    ├── ui-spec/
+    └── plans/
+        └── tasks/
+```
+
+---
+
+## FAQ
+
+**Q: What models does this work with?**
+
+A: Designed for GPT-5.4 (default). Subagents like rule-advisor use GPT-5.3-Codex-Spark for faster lightweight analysis. Models are configurable per agent in the TOML files.
+
+**Q: Can I customize the agents?**
+
+A: Yes. Edit the TOML files in `.codex/agents/` — change model, sandbox_mode, developer_instructions, or skills.config. Files you modify locally are preserved during `npx codex-workflows update`.
+
+**Q: What's the difference between `$recipe-implement` and `$recipe-fullstack-implement`?**
+
+A: `$recipe-implement` is the universal entry point. It runs requirement-analyzer first, detects affected layers from the codebase, and automatically routes to backend, frontend, or fullstack flow. `$recipe-fullstack-implement` skips the detection and goes straight into the fullstack flow (separate Design Docs per layer, design-sync, layer-aware task execution). Use `$recipe-implement` when you're not sure; use `$recipe-fullstack-implement` when you know upfront that the feature spans both layers.
+
+**Q: How does this relate to Claude Code Workflows?**
+
+A: codex-workflows is the Codex-native counterpart of [Claude Code Workflows](https://github.com/shinpr/claude-code-workflows). Same development philosophy, adapted for Codex CLI's subagent architecture and GPT model family.
+
+**Q: Does this work with MCP servers?**
+
+A: Yes. Codex skills and subagents work alongside [MCP](https://developers.openai.com/codex/mcp) — skills operate at the instruction layer while MCP operates at the tool transport layer. You can add MCP servers to any agent's TOML configuration.
+
+**Q: What if a subagent gets stuck?**
+
+A: Subagents escalate to the user when they encounter design deviations, ambiguous requirements, or specification conflicts. The framework stops autonomous execution and presents the issue with options.
+
+---
+
+## License
+
+MIT License — free to use, modify, and distribute.
+
+---
+
+Built and maintained by [@shinpr](https://github.com/shinpr)

package/bin/cli.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const MANIFEST_FILE = ".codex-workflows-manifest.json";
+const COPY_DIRS = [".agents", ".codex"];
+
+function main(argv = process.argv, cwd = process.cwd()) {
+  const command = argv[2];
+  const targetDir = cwd;
+  const sourceDir = path.resolve(__dirname, "..");
+
+  function getVersion() {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(sourceDir, "package.json"), "utf8")
+      );
+      return pkg.version;
+    } catch (e) {
+      console.error(`Error reading package.json: ${e.message}`);
+      process.exit(2);
+    }
+  }
+
+  function fileHash(filePath) {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash("sha256").update(content).digest("hex");
+  }
+
+  function copyDirRecursive(src, dest) {
+    let copied = 0;
+    if (!fs.existsSync(src)) return copied;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        copied += copyDirRecursive(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+        copied++;
+      }
+    }
+    return copied;
+  }
+
+  function collectFiles(dir, base) {
+    const files = [];
+    if (!fs.existsSync(dir)) return files;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.join(base, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...collectFiles(fullPath, relPath));
+      } else {
+        files.push(relPath);
+      }
+    }
+    return files;
+  }
+
+  function readManifest() {
+    const manifestPath = path.join(targetDir, MANIFEST_FILE);
+    if (!fs.existsSync(manifestPath)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    } catch (e) {
+      console.error(`Error: ${MANIFEST_FILE} is corrupt: ${e.message}`);
+      console.error("Delete the file and run 'install' again, or fix it manually.");
+      process.exit(2);
+    }
+  }
+
+  function writeManifest(fileHashes) {
+    const manifestPath = path.join(targetDir, MANIFEST_FILE);
+    const manifest = {
+      version: getVersion(),
+      installedAt: new Date().toISOString(),
+      files: fileHashes,
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  }
+
+  function install() {
+    const manifest = readManifest();
+    if (manifest) {
+      console.log(
+        `codex-workflows v${manifest.version} is already installed. Use 'update' to upgrade.`
+      );
+      process.exit(1);
+    }
+
+    const version = getVersion();
+    console.log(`Installing codex-workflows v${version}...\n`);
+
+    const fileHashes = {};
+    let totalCopied = 0;
+
+    for (const dir of COPY_DIRS) {
+      const src = path.join(sourceDir, dir);
+      const dest = path.join(targetDir, dir);
+      const copied = copyDirRecursive(src, dest);
+      totalCopied += copied;
+      for (const relPath of collectFiles(dest, dir)) {
+        fileHashes[relPath] = fileHash(path.join(targetDir, relPath));
+      }
+      if (copied > 0) console.log(`  ${dir}/ — ${copied} files`);
+    }
+
+    writeManifest(fileHashes);
+    console.log(`\nDone. ${totalCopied} files installed.`);
+  }
+
+  function update(dryRun) {
+    const manifest = readManifest();
+    if (!manifest) {
+      console.log("codex-workflows is not installed. Run 'install' first.");
+      process.exit(1);
+    }
+
+    // Migrate old manifest format (array) to new format (hash map)
+    const installedHashes = Array.isArray(manifest.files)
+      ? Object.fromEntries(manifest.files.map(f => [f, null]))
+      : manifest.files;
+
+    const currentVersion = manifest.version;
+    const newVersion = getVersion();
+    console.log(
+      `${dryRun ? "[DRY RUN] " : ""}Updating codex-workflows v${currentVersion} → v${newVersion}\n`
+    );
+
+    let updated = 0;
+    let added = 0;
+    let skipped = 0;
+    let preserved = 0;
+    const preservedFiles = new Set();
+
+    for (const dir of COPY_DIRS) {
+      const src = path.join(sourceDir, dir);
+      if (!fs.existsSync(src)) continue;
+      const sourceFiles = collectFiles(src, dir);
+      for (const relPath of sourceFiles) {
+        const srcFile = path.join(sourceDir, relPath);
+        const destFile = path.join(targetDir, relPath);
+
+        // New file — always add
+        if (!fs.existsSync(destFile)) {
+          if (dryRun) console.log(`  + ${relPath} (new)`);
+          else {
+            fs.mkdirSync(path.dirname(destFile), { recursive: true });
+            fs.copyFileSync(srcFile, destFile);
+          }
+          added++;
+          continue;
+        }
+
+        const srcContent = fs.readFileSync(srcFile);
+        const destContent = fs.readFileSync(destFile);
+
+        // Identical — skip
+        if (srcContent.equals(destContent)) { skipped++; continue; }
+
+        // Check if user modified the file since last install/update
+        const storedHash = installedHashes[relPath];
+        if (storedHash) {
+          const currentHash = crypto.createHash("sha256").update(destContent).digest("hex");
+          if (currentHash !== storedHash) {
+            // User modified this file — preserve their changes
+            console.log(`  ~ ${relPath} (modified locally, skipping)`);
+            preservedFiles.add(relPath);
+            preserved++;
+            continue;
+          }
+        }
+
+        // File unchanged by user (or not previously tracked) — safe to update
+        if (dryRun) console.log(`  * ${relPath} (updated)`);
+        else fs.copyFileSync(srcFile, destFile);
+        updated++;
+      }
+    }
+
+    if (!dryRun) {
+      const newHashes = {};
+      for (const dir of COPY_DIRS) {
+        for (const relPath of collectFiles(path.join(targetDir, dir), dir)) {
+          if (preservedFiles.has(relPath) && installedHashes[relPath]) {
+            // Keep original hash so preserved files stay protected on next update
+            newHashes[relPath] = installedHashes[relPath];
+          } else {
+            newHashes[relPath] = fileHash(path.join(targetDir, relPath));
+          }
+        }
+      }
+      writeManifest(newHashes);
+    }
+
+    const parts = [`${added} added`, `${updated} updated`, `${skipped} unchanged`];
+    if (preserved > 0) parts.push(`${preserved} preserved (local changes)`);
+    console.log(`\n${dryRun ? "[DRY RUN] " : ""}${parts.join(", ")}.`);
+  }
+
+  function status() {
+    const manifest = readManifest();
+    if (!manifest) {
+      console.log("codex-workflows is not installed.");
+      return;
+    }
+    const fileCount = Array.isArray(manifest.files)
+      ? manifest.files.length
+      : Object.keys(manifest.files).length;
+    console.log(`Version:   ${manifest.version}`);
+    console.log(`Installed: ${manifest.installedAt}`);
+    console.log(`Files:     ${fileCount} managed`);
+  }
+
+  function showHelp() {
+    console.log(`
+codex-workflows — Agentic coding skills & subagents for Codex CLI
+
+Usage:
+  npx codex-workflows install              Install skills and agents
+  npx codex-workflows update               Update managed files
+  npx codex-workflows update --dry-run     Preview changes without applying
+  npx codex-workflows status               Show installation info
+  npx codex-workflows --version            Show version
+  npx codex-workflows --help               Show this help
+`);
+  }
+
+  switch (command) {
+    case "install": install(); break;
+    case "update": update(argv.includes("--dry-run")); break;
+    case "status": status(); break;
+    case "--version": case "-v": console.log(getVersion()); break;
+    case "--help": case "-h": case undefined: showHelp(); break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      showHelp();
+      process.exit(1);
+  }
+}
+
+main();
+module.exports = { main };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "codex-workflows",
+  "version": "0.1.0",
+  "description": "Task-oriented agentic coding framework for OpenAI Codex CLI — skills, recipes, and subagents for structured development workflows",
+  "license": "MIT",
+  "author": "Shinsuke Kagawa",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shinpr/codex-workflows"
+  },
+  "bin": {
+    "codex-workflows": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    ".agents/",
+    ".codex/"
+  ],
+  "keywords": [
+    "codex",
+    "openai",
+    "agent-skills",
+    "agentic-coding",
+    "ai-coding",
+    "subagents",
+    "multi-agent",
+    "context-engineering",
+    "tdd",
+    "code-generation"
+  ],
+  "homepage": "https://github.com/shinpr/codex-workflows#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}