ralph-teams-codex 1.5.1

package/AGENTS.md

@@ -0,0 +1,6 @@
+# Repo Instructions
+
+- This repository is a Codex skill pack, not a Claude plugin.
+- Prefer Codex skills in `skills/` and subagent prompts in `agents/` over marketplace-style packaging.
+- When changing frontend or UI behavior in downstream projects, verify with MCP Playwright by default.
+- Keep skill instructions tool-accurate for Codex. Use `spawn_agent` and `wait_agent` for subagent workflows, then `close_agent` as soon as the finished agent's output has been handled.

package/FLOW.md

@@ -0,0 +1,47 @@
+# Execution Flow
+
+```mermaid
+flowchart TD
+    classDef user fill:#ffdfba,stroke:#ffb347,stroke-width:2px,color:#333
+    classDef orch fill:#bae1ff,stroke:#5facff,stroke-width:2px,color:#333
+    classDef agent fill:#baffc9,stroke:#42d669,stroke-width:2px,color:#333
+    classDef doc fill:#ffffba,stroke:#e6e65a,stroke-width:2px,color:#333
+    classDef cmd fill:#f3e8ff,stroke:#c084fc,stroke-width:2px,color:#333
+    classDef optional fill:#ffe4e1,stroke:#ff9999,stroke-width:1px,stroke-dasharray:4,color:#333
+
+    P1["teams-plan - Discuss feature, write plan, get approval"]:::cmd
+    P[".ralph-teams/PLAN.md"]:::doc
+    CX1["Codex second opinion on plan (optional)"]:::optional
+
+    P1 --> P
+    P --> CX1
+
+    P2["teams-run - Build each task sequentially"]:::cmd
+
+    CX1 -->|"approved"| P2
+
+    subgraph Build[" "]
+        direction TB
+        B1["Builder Agent - Task 1"]:::agent
+        B2["Builder Agent - Task 2"]:::agent
+        BN["Builder Agent - Task N"]:::agent
+        B1 --> B2 --> BN
+    end
+
+    P2 -->|"one fresh agent per task"| Build
+
+    R["Reviewer Agent - Reviews all changes"]:::agent
+    CX2["Codex second opinion on review (optional)"]:::optional
+    REV[".ralph-teams/REVIEW.md"]:::doc
+    BF["Builder Agent - Fixes"]:::agent
+    DOCS["Docs update agent (optional)"]:::optional
+
+    Build --> R
+    R --> CX2
+    CX2 --> REV
+    REV --> BF
+    BF --> DOCS
+
+    P3["teams-verify - Walk through scenarios manually"]:::cmd
+    DOCS --> P3
+```

package/README.md

@@ -0,0 +1,157 @@
+# ralph-teams-codex
+
+A Codex skill pack for planning and building features with sequential builder subagents (gpt-5.4-mini or gpt-5.4 based on phase complexity). Each phase is broken into tasks the builder works through in one session — automated E2E verification, a review pass, and integrated debug and documentation skills.
+
+## Does Codex Support Plugins?
+
+Not in the Claude marketplace sense. Codex is extended through:
+
+- `skills/` with `SKILL.md` metadata and instructions
+- `AGENTS.md` for repo-level behavior
+- MCP tools such as Playwright and Maestro
+- subagents started with `spawn_agent`
+
+This repo packages the original workflow in that Codex-native form.
+
+## Quick Start
+
+```text
+teams-plan
+```
+
+Describe what you want to build. Codex handles planning, sequential phase execution, review, and verification.
+
+## Install
+
+This repo now includes a Codex installer CLI, following the same basic model as GSD: runtime-specific assets are copied into Codex's config directory.
+
+If this package is published to npm, the intended install flow is:
+
+```bash
+npx ralph-teams-codex --global
+```
+
+Local install into the current project:
+
+```bash
+npx ralph-teams-codex --local
+```
+
+Right now this package is not published to the npm registry, so `npx ralph-teams-codex ...` will return a 404. Until it is published, run the installer from a local clone:
+
+```bash
+node bin/ralph-teams-codex.js --global
+node bin/ralph-teams-codex.js --local
+```
+
+Or link the local package once, then use the command name directly:
+
+```bash
+npm link
+ralph-teams-codex --global
+ralph-teams-codex --local
+```
+
+Install only specific skills:
+
+```bash
+node bin/ralph-teams-codex.js --global --skills teams-plan,teams-run,teams-verify
+```
+
+Uninstall:
+
+```bash
+node bin/ralph-teams-codex.js --global --uninstall
+node bin/ralph-teams-codex.js --local --uninstall
+```
+
+Global installs target `~/.codex/skills` by default, or `$CODEX_HOME/skills` if `CODEX_HOME` is set. Local installs target `./.codex/skills`.
+
+Restart Codex after installing or uninstalling skills.
+
+## How It Works
+
+```mermaid
+flowchart TD
+    classDef user fill:#ffdfba,stroke:#ffb347,stroke-width:2px,color:#333
+    classDef orch fill:#bae1ff,stroke:#5facff,stroke-width:2px,color:#333
+    classDef agent fill:#baffc9,stroke:#42d669,stroke-width:2px,color:#333
+    classDef doc fill:#ffffba,stroke:#e6e65a,stroke-width:2px,color:#333
+    classDef cmd fill:#f3e8ff,stroke:#c084fc,stroke-width:2px,color:#333
+    classDef optional fill:#ffe4e1,stroke:#ff9999,stroke-width:1px,stroke-dasharray:4,color:#333
+
+    P1["teams-plan - Discuss feature, write plan, get approval"]:::cmd
+    P[".ralph-teams/PLAN.md"]:::doc
+    CX1["Codex second opinion on plan (optional)"]:::optional
+
+    P1 --> P
+    P --> CX1
+
+    P2["teams-run - Build each phase sequentially"]:::cmd
+
+    CX1 -->|"approved"| P2
+
+    subgraph Build[" "]
+        direction TB
+        B1["mini/5.4 Builder - Phase 1"]:::agent
+        B2["mini/5.4 Builder - Phase 2"]:::agent
+        BN["mini/5.4 Builder - Phase N"]:::agent
+        B1 --> B2 --> BN
+    end
+
+    P2 -->|"one fresh agent per phase"| Build
+
+    R["Reviewer Agent - Reviews all changes"]:::agent
+    CX2["Codex second opinion on review (optional)"]:::optional
+    REV[".ralph-teams/REVIEW.md"]:::doc
+    BF["Builder Agent - Fixes"]:::agent
+    DOCS["Scribe Agent - Updates docs (optional)"]:::optional
+
+    Build --> R
+    R --> CX2
+    CX2 --> REV
+    REV --> BF
+    BF --> DOCS
+
+    P3["teams-verify - Walk through scenarios manually"]:::cmd
+    DBG["teams-debug - Fix bugs against the plan"]:::optional
+    DOCS --> P3
+    P3 --> DBG
+```
+
+Each phase runs in its own isolated subagent with a clean 200k token context window. Phases are meaningful feature areas (targeting 50–60% context fill) broken into tasks — the builder completes all tasks within one session. Results are committed after each phase so you can always resume with `teams-run`.
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `teams-plan` | Discuss, plan, optionally review the plan, execute phases sequentially, review, then apply fixes if needed |
+| `teams-run` | Resume an existing plan from where it left off |
+| `teams-verify` | Walk through manual E2E verification scenario by scenario |
+| `teams-debug` | Fix a bug in relation to the active plan — usable anytime |
+| `teams-document` | Update existing docs (README, ARCHITECTURE.md, etc.) for the latest plan |
+
+## Output
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  RALPH-TEAMS  Plan #3 — 2 of 4 phases complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✓  Phase 1: Project Setup          [done]        (mini)
+  ✓  Phase 2: Auth System            [done]        (5.4)
+  ►  Phase 3: API Routes             [building...]  (5.4)
+  ○  Phase 4: Frontend               [pending]      (mini)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Status symbols: `✓` done · `►` building · `✗` failed · `○` pending · `(mini)` simple phase · `(5.4)` standard phase
+
+## Output Files
+
+All build artifacts are written to `./.ralph-teams/` in your project:
+
+| File | Contents |
+|------|----------|
+| `.ralph-teams/PLAN.md` | Plan ID, phases with complexity, acceptance criteria, verification scenarios |
+| `.ralph-teams/REVIEW.md` | Reviewer findings |
+| `.ralph-teams/VERIFY.md` | Manual verification results |

package/agents/teams-builder.md

@@ -0,0 +1,74 @@
+---
+name: teams-builder
+description: "Builder subagent. Implements a single phase or applies review fixes, verifies with Playwright (web) or Maestro (mobile), then commits."
+model: gpt-5.4-mini
+---
+
+# Teams Builder
+
+You are a builder subagent. You receive a specific assignment from the orchestrator — either a phase to implement or review fixes to apply. You implement it, verify it works, commit, and return.
+
+---
+
+## Workflow
+
+### 1. Understand the Assignment
+
+The orchestrator passes you everything you need in your spawn prompt:
+- **Phase mode:** a specific phase number, description, its tasks, and the full plan
+- **Fix mode:** a list of blocking review findings from `.ralph-teams/REVIEW.md`
+- The platform (web or mobile)
+
+Read `.ralph-teams/PLAN.md` for additional context (acceptance criteria, verification scenarios).
+
+### 2. Write Tests First (Phase mode only)
+
+Before writing any implementation code, write the tests for what you are about to build:
+
+- Look at existing test files to understand the project's test framework and conventions.
+- Write unit and/or integration tests that cover the phase's acceptance criteria.
+- Run the tests — they should **fail** at this point (red). If they pass without implementation, the tests are not testing the right thing.
+- Now implement until the tests pass (green).
+
+**Fix mode:** skip TDD — just fix the blocking issues and confirm existing tests still pass.
+
+### 3. Implement
+
+- Follow existing conventions — don't introduce new ones arbitrarily.
+- **Phase mode:** work through the phase's tasks in order. Each task is a concrete step — complete all of them. No scope creep beyond the listed tasks.
+- **Fix mode:** fix each blocking issue listed. Nothing else.
+
+### 4. Verify
+
+**This step is mandatory.** Use the appropriate tool based on platform:
+
+- **Web app** → Use `mcp__playwright__*` tools (e.g., `mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`, `mcp__playwright__browser_click`) to open the app in a browser and verify the work against the relevant scenarios in `.ralph-teams/PLAN.md`.
+- **Mobile app** → Search your available tools for Maestro MCP tools (look for `mcp__maestro__*` or similar). Use them to run the relevant mobile verification flows.
+
+**If verification tools are not available:** fall back to running tests and lint (`npm test`, `npm run lint`, or the project's equivalent). Note in your summary that E2E verification was skipped because the tools were unavailable.
+
+If verification fails, fix the code and re-verify before committing.
+
+### 5. Commit
+
+Commit your changes with a descriptive message:
+- **Phase mode:** `feat: [phase name]` or similar
+- **Fix mode:** `fix: address review findings`
+
+Run `git rev-parse HEAD` to confirm the commit landed.
+
+### 6. Report Back
+
+Return a brief summary:
+- What was implemented or fixed
+- What was verified and the result (or "E2E skipped — tools unavailable")
+- The commit SHA
+
+---
+
+## Rules
+
+- **Write tests before implementation** (phase mode). Tests must fail before you implement, pass after.
+- **Always attempt verification.** Only skip E2E if the tools genuinely aren't available.
+- Implement only what you were assigned — no extras.
+- If you hit a blocker you cannot resolve, report it clearly in your summary instead of committing broken code.

package/agents/teams-reviewer.md

@@ -0,0 +1,109 @@
+---
+name: teams-reviewer
+description: "Reviewer subagent. Reviews the full implementation against acceptance criteria, runs build and test checks, seeks a Claude Opus second opinion only for complex phases or uncertain findings, writes findings to .ralph-teams/REVIEW.md."
+model: gpt-5.4
+---
+
+# Teams Reviewer
+
+You are a code reviewer. Your job: review the full implementation of a completed build, check it against all acceptance criteria, and produce a clear review report.
+
+---
+
+## Workflow
+
+### 1. Read the Plan
+
+Read `.ralph-teams/PLAN.md` to understand:
+- All phases that were implemented
+- The acceptance criteria
+- The verification scenarios
+
+### 2. Review the Implementation
+
+The orchestrator provides a `BASE_SHA` (the commit before the build started). Use it to see all changes:
+
+```bash
+git diff <BASE_SHA>..HEAD --stat
+git diff <BASE_SHA>..HEAD
+```
+
+Also review the commit history:
+```bash
+git log --oneline <BASE_SHA>..HEAD
+```
+
+Read all files that were changed. Evaluate:
+- Does the implementation meet every acceptance criterion?
+- Are there bugs, logic errors, or missing edge cases?
+- Is the code quality acceptable (no security issues, no broken patterns)?
+- Were all phases completed?
+- **Did the builder write tests?** Each phase should have unit or integration tests covering its acceptance criteria. Missing tests are a **blocking** finding.
+
+### 3. Build + Test Check
+
+Run the project's build and test commands to confirm nothing is broken:
+
+```bash
+# Detect and run — adapt to the project's tooling
+npm test 2>&1 || yarn test 2>&1 || go test ./... 2>&1 || python -m pytest 2>&1
+```
+
+Note any failures.
+
+### 4. Second Opinion (conditional)
+
+Only seek a second opinion if **all** of these are true:
+- The build contains complex phases (auth, migrations, architecture, security, algorithms)
+- Claude CLI is available: check with `which claude`
+
+If the phase is not complex, **skip this step entirely.**
+If `which claude` returns nothing, **skip this step entirely.**
+
+If both conditions are met, run:
+```bash
+claude --model claude-opus-4-6 -p "I reviewed this implementation and found the following. Do you agree? Anything I missed? Be concise.\n\n[findings summary + diff stats]"
+```
+
+Incorporate any additional valid findings.
+
+### 5. Write REVIEW.md
+
+Write your findings to `.ralph-teams/REVIEW.md`:
+
+```markdown
+# Review: [Feature Name]
+
+Date: [date]
+Reviewer: Opus
+Base commit: [BASE_SHA]
+
+## Overall Verdict
+PASS | NEEDS FIXES
+
+## Findings
+
+### Blocking
+- [ ] [Issue description — specific file:line if applicable]
+
+### Non-blocking (suggestions)
+- [ ] [Suggestion]
+
+## Build / Test Status
+- Tests: [pass | fail — details]
+- Lint: [pass | fail — details]
+
+## Acceptance Criteria Status
+- [x] Criterion 1: met
+- [ ] Criterion 2: NOT met — [reason]
+```
+
+---
+
+## Rules
+
+- Be specific. Vague findings are not actionable.
+- Only flag real issues — don't invent problems.
+- Distinguish blocking (must fix) from non-blocking (suggestions).
+- Always run build/tests — don't skip this step.
+- Always write `.ralph-teams/REVIEW.md` — this is your only output.

package/bin/ralph-teams-codex.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const repoRoot = path.resolve(__dirname, "..");
+const sourceSkillsDir = path.join(repoRoot, "skills");
+const skillDirectoryByName = {
+  "teams-plan": "teams-plan",
+  "teams-run": "teams-run",
+  "teams-verify": "teams-verify",
+  "teams-debug": "debug",
+  "teams-document": "teams-document"
+};
+const defaultSkillNames = [
+  "teams-plan",
+  "teams-run",
+  "teams-verify",
+  "teams-debug",
+  "teams-document"
+];
+
+function printHelp() {
+  console.log(`ralph-teams-codex
+
+Install or uninstall Codex skills from this package.
+
+Usage:
+  ralph-teams-codex --global
+  ralph-teams-codex --local
+  ralph-teams-codex --global --skills teams-plan,teams-run
+  ralph-teams-codex --global --uninstall
+
+Options:
+  --global        Install into ~/.codex/skills or $CODEX_HOME/skills
+  --local         Install into ./.codex/skills
+  --skills <csv>  Comma-separated list of skill names to install
+  --uninstall     Remove installed skills instead of copying them
+  --help          Show this help
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    scope: null,
+    uninstall: false,
+    skills: [...defaultSkillNames]
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--global") {
+      options.scope = "global";
+    } else if (arg === "--local") {
+      options.scope = "local";
+    } else if (arg === "--uninstall") {
+      options.uninstall = true;
+    } else if (arg === "--skills") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--skills requires a comma-separated value");
+      }
+      options.skills = value.split(",").map((item) => item.trim()).filter(Boolean);
+      i += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!options.help && !options.scope) {
+    throw new Error("Choose exactly one install scope: --global or --local");
+  }
+
+  return options;
+}
+
+function resolveTargetSkillsDir(scope) {
+  if (scope === "local") {
+    return path.resolve(process.cwd(), ".codex", "skills");
+  }
+
+  const codexHome = process.env.CODEX_HOME
+    ? path.resolve(process.env.CODEX_HOME)
+    : path.join(os.homedir(), ".codex");
+  return path.join(codexHome, "skills");
+}
+
+function ensureKnownSkills(skills) {
+  const unknown = skills.filter((skill) => !Object.hasOwn(skillDirectoryByName, skill));
+  if (unknown.length > 0) {
+    throw new Error(`Unknown skills: ${unknown.join(", ")}`);
+  }
+}
+
+function copyDirectory(sourceDir, targetDir) {
+  fs.cpSync(sourceDir, targetDir, { recursive: true, force: true });
+}
+
+function removeDirectory(targetDir) {
+  fs.rmSync(targetDir, { recursive: true, force: true });
+}
+
+function installSkills(targetSkillsDir, skills) {
+  fs.mkdirSync(targetSkillsDir, { recursive: true });
+  for (const skill of skills) {
+    const sourceDir = path.join(sourceSkillsDir, skillDirectoryByName[skill]);
+    const targetDir = path.join(targetSkillsDir, skill);
+    if (!fs.existsSync(sourceDir)) {
+      throw new Error(`Missing source skill directory: ${sourceDir}`);
+    }
+    copyDirectory(sourceDir, targetDir);
+    console.log(`Installed ${skill} -> ${targetDir}`);
+  }
+}
+
+function uninstallSkills(targetSkillsDir, skills) {
+  for (const skill of skills) {
+    const targetDir = path.join(targetSkillsDir, skill);
+    removeDirectory(targetDir);
+    console.log(`Removed ${targetDir}`);
+  }
+}
+
+function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      printHelp();
+      return;
+    }
+
+    ensureKnownSkills(options.skills);
+    const targetSkillsDir = resolveTargetSkillsDir(options.scope);
+
+    if (options.uninstall) {
+      uninstallSkills(targetSkillsDir, options.skills);
+      console.log("Done. Restart Codex to refresh installed skills.");
+      return;
+    }
+
+    installSkills(targetSkillsDir, options.skills);
+    console.log("Done. Restart Codex to load the new skills.");
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "ralph-teams-codex",
+  "version": "1.5.1",
+  "description": "Codex skill pack for planning and building features with sequential builder subagents and verification workflows.",
+  "license": "MIT",
+  "bin": {
+    "ralph-teams-codex": "./bin/ralph-teams-codex.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "agents",
+    "AGENTS.md",
+    "README.md",
+    "FLOW.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}