forge-workflow 0.0.1

package/docs/plans/2026-03-05-forge-uto-design.md

@@ -0,0 +1,116 @@
+# Design Doc: forge-uto — Agent Config Cleanup + Codex CLI
+
+- **Feature**: forge-uto
+- **Date**: 2026-03-05
+- **Status**: approved
+- **Beads**: forge-uto
+
+---
+
+## Purpose
+
+Reduce maintenance surface and improve correctness of the forge setup CLI:
+
+1. `CLAUDE.md` currently duplicates `AGENTS.md` content — make it a symlink so Claude Code reads the single source of truth
+2. Google Antigravity is no longer a supported agent — remove all traces to avoid misleading users
+3. Aider requires complex, non-universal setup — drop plugin and setup logic
+4. OpenSpec is no longer part of the forge workflow — remove from setup CLI entirely
+5. Codex CLI is a supported agent that lacks a plugin — add it
+6. OpenCode plugin exists but has issues — fix it
+7. Stage listing in `bin/forge.js` says 9-stage (with `/research`) — update to current 7-stage
+
+---
+
+## Success Criteria
+
+- `CLAUDE.md` is a symlink pointing to `AGENTS.md` at repo root
+- `GEMINI.md` is deleted; no Antigravity references remain in `.clinerules`, `.windsurfrules`, `docs/SETUP.md`, `lib/agents/`
+- `lib/agents/aider.plugin.json` is deleted; `setupAiderAgent()` and `customSetup === 'aider'` branch are removed from `bin/forge.js`
+- `promptOpenSpecSetup()`, `checkForOpenSpec()`, `initializeOpenSpec()`, `isOpenSpecInitialized()` are removed from `bin/forge.js`; all call sites removed
+- `openspecInstallType` field removed from project status object
+- Stage listing in `bin/forge.js` updated from 9-stage to 7-stage (remove `/research` row and references)
+- `lib/agents/codex.plugin.json` exists with correct directories for AGENTS.md + `.codex/config.toml`
+- OpenCode plugin is verified correct and any issues fixed
+- `bun test` passes (0 failures)
+
+---
+
+## Out of Scope
+
+- Adding any new agents beyond Codex
+- Changing the content of `AGENTS.md`
+- Modifying the workflow stage commands themselves
+- Migrating existing user projects that have Antigravity or Aider set up
+
+---
+
+## Approach Selected
+
+**Direct surgical edits** to `bin/forge.js` + plugin files. No abstraction changes.
+
+- CLAUDE.md symlink: created by `bin/forge.js` setup (not pre-committed to repo, since it's generated per-project). The existing setup already handles CLAUDE.md creation — change the logic to create a symlink to AGENTS.md instead of copying content.
+- Removals: delete plugin JSONs, remove function definitions and all call sites
+- Codex plugin: new `lib/agents/codex.plugin.json` following existing plugin schema
+
+---
+
+## Constraints
+
+- `bin/forge.js` has strict ESLint with `--max-warnings 0` — no unused vars after removal
+- Unused parameters must be prefixed with `_`
+- Pre-push hooks run full test suite — all tests must pass before push
+
+---
+
+## Edge Cases
+
+- **Symlink on Windows**: `fs.symlinkSync` requires Developer Mode or admin on Windows. The setup CLI should catch `EPERM` and fall back to a redirect stub with a clear warning message.
+- **Existing CLAUDE.md**: If a project already has a CLAUDE.md with custom content, the setup should detect it and ask before overwriting with a symlink (current merge/keep logic already handles this).
+- **OpenSpec references in status display**: Lines 2486–2491 in `bin/forge.js` display OpenSpec status at setup end — these must also be removed.
+- **`openspecInstallType` in project status object**: Field at line 811 references `checkForOpenSpec()` — must be removed alongside the function.
+- **Line 3525**: Additional `openspecStatus` reference — must be removed.
+
+---
+
+## Ambiguity Policy
+
+Use the 7-dimension decision gate rubric. If a decision scores ambiguous mid-dev, pause and ask.
+
+---
+
+## Technical Research
+
+### DRY Check
+
+- Symlink creation: `fs.symlinkSync` already used at `bin/forge.js:589` — extend that pattern
+- Plugin JSON schema: established pattern in `lib/agents/` — codex plugin follows same structure
+- OpenSpec removal: 4 functions (`checkForOpenSpec`, `initializeOpenSpec`, `isOpenSpecInitialized`, `promptOpenSpecSetup`) + call sites at lines 808, 811, 2486–2491, 3438, 3525
+
+### OpenCode Issues Found
+
+The current `opencode.plugin.json` homepage is `https://github.com/opencode` — incorrect URL. The real project is at `https://opencode.ai`. This is a cosmetic issue but should be fixed. No structural issues found with directories or setup logic.
+
+### Codex CLI Config
+
+- Instructions: `AGENTS.md` at repo root (already exists in forge projects)
+- Tool config: `.codex/config.toml` (per-project) or `~/.codex/config.toml` (user-level)
+- Plugin needs: `rootConfig` pointing to AGENTS.md (already installed by forge setup), optional `.codex/` directory setup
+
+### OWASP Top 10 Analysis
+
+| Risk | Applies? | Mitigation |
+|------|----------|------------|
+| A01 Broken Access Control | No | No auth changes |
+| A02 Cryptographic Failures | No | No crypto |
+| A03 Injection | Low | `bin/forge.js` uses `secureExecFileSync` — existing pattern maintained; no new exec calls added |
+| A04 Insecure Design | No | Removing complexity, not adding |
+| A05 Security Misconfiguration | Low | Symlink creation — handle EPERM gracefully, don't silently fail |
+| A06–A10 | No | Not applicable to CLI config file changes |
+
+### TDD Test Scenarios
+
+1. **Happy path — Codex plugin loads**: `forge setup` with Codex selected → `lib/agents/codex.plugin.json` is read by plugin loader → Codex directories are created
+2. **OpenSpec removed — setup completes without prompt**: Running setup flow does not call `promptOpenSpecSetup` or display OpenSpec install prompt
+3. **Antigravity absent — plugin loader ignores deleted file**: No `antigravity.plugin.json` → plugin loader does not attempt Antigravity setup
+4. **Aider absent — no `.aider.conf.yml` created**: No `aider.plugin.json`, no `customSetup === 'aider'` branch → Aider setup never runs
+5. **CLAUDE.md symlink**: On supported filesystem, `forge setup` creates `CLAUDE.md` as symlink → `fs.lstatSync('CLAUDE.md').isSymbolicLink() === true`

package/docs/plans/2026-03-05-forge-uto-tasks.md

@@ -0,0 +1,244 @@
+# Task List: forge-uto — Agent Config Cleanup + Codex CLI
+
+- **Feature**: forge-uto
+- **Date**: 2026-03-05
+- **Design doc**: docs/plans/2026-03-05-forge-uto-design.md
+- **Beads**: forge-uto
+
+---
+
+## Task 1: Remove Antigravity plugin + files
+**File(s)**:
+- `lib/agents/antigravity.plugin.json` (delete)
+- `GEMINI.md` (delete)
+- `.agent/` directory (delete)
+
+**What to implement**:
+Delete the Antigravity plugin JSON, the GEMINI.md root config, and the entire `.agent/` directory tree. These contain Antigravity-specific workflows, rules, and skills that are no longer supported.
+
+**TDD steps**:
+1. Write test in `test/agent-detection.test.js`: assert that `lib/agents/antigravity.plugin.json` does not exist (file system check) and that loading the plugin list does not include `antigravity`
+2. Run test: confirm it fails — plugin file exists
+3. Delete `lib/agents/antigravity.plugin.json`, `GEMINI.md`, `.agent/`
+4. Run test: confirm it passes
+5. Commit: `feat: remove Antigravity plugin and files`
+
+**Expected output**: No Antigravity plugin file, no GEMINI.md, no `.agent/` directory.
+
+---
+
+## Task 2: Remove Windsurf plugin + files
+**File(s)**:
+- `lib/agents/windsurf.plugin.json` (delete)
+- `.windsurfrules` (delete)
+- `.windsurf/` directory (delete)
+
+**What to implement**:
+Delete the Windsurf plugin JSON, the `.windsurfrules` root config file, and the `.windsurf/` directory. Windsurf has been deprecated in favour of Antigravity (now also dropped).
+
+**TDD steps**:
+1. Write test: assert `lib/agents/windsurf.plugin.json` does not exist and plugin list does not include `windsurf`
+2. Run test: confirm it fails — plugin file exists
+3. Delete `lib/agents/windsurf.plugin.json`, `.windsurfrules`, `.windsurf/`
+4. Run test: confirm it passes
+5. Commit: `feat: remove Windsurf plugin and files`
+
+**Expected output**: No Windsurf plugin file, no `.windsurfrules`, no `.windsurf/` directory.
+
+---
+
+## Task 3: Remove Aider plugin + setup logic from bin/forge.js
+**File(s)**:
+- `lib/agents/aider.plugin.json` (delete)
+- `bin/forge.js` (remove `setupAiderAgent()` function at ~line 1938 and `customSetup === 'aider'` branch at ~line 2100)
+- `test/other-agents-config-generation.test.js` (remove Aider tests)
+- `test/agent-detection.test.js` (remove Aider detection tests)
+
+**What to implement**:
+Delete the Aider plugin JSON. Remove `setupAiderAgent()` function definition from `bin/forge.js`. Remove the `if (agent.customSetup === 'aider') { setupAiderAgent(); }` branch. Remove all Aider tests from test files.
+
+**TDD steps**:
+1. Write test: assert `lib/agents/aider.plugin.json` does not exist and setup flow never creates `.aider.conf.yml`
+2. Run test: confirm it fails — plugin and setup logic exist
+3. Delete plugin file; remove function + call site from `bin/forge.js`; remove Aider tests
+4. Run test + `bun run lint`: confirm passes with 0 ESLint warnings
+5. Commit: `feat: drop Aider support — remove plugin and setup logic`
+
+**Expected output**: No Aider plugin, no `.aider.conf.yml` created, no Aider references in setup flow.
+
+---
+
+## Task 4: Remove OpenSpec from bin/forge.js
+**File(s)**:
+- `bin/forge.js` (remove 4 functions + all call sites)
+
+**What to implement**:
+Remove these 4 functions entirely from `bin/forge.js`:
+- `checkForOpenSpec()` (~line 2972)
+- `isOpenSpecInitialized()` (~line 3011)
+- `initializeOpenSpec()` (~line 3038)
+- `promptOpenSpecSetup()` (~line 3244)
+
+Also remove all call sites:
+- `openspecInstallType: checkForOpenSpec()` in project status object (~line 811)
+- `hasOpenSpec: isOpenSpecInitialized()` (~line 808)
+- OpenSpec status display block (~lines 2485–2491)
+- `await promptOpenSpecSetup(question)` (~line 3438)
+- `const openspecStatus = checkForOpenSpec()` + `if (openspecStatus && !isOpenSpecInitialized())` block (~lines 3524–3529)
+- Stage listing line: `| 3 | \`/plan\` | Create implementation plan, branch, OpenSpec if strategic |` (~line 442) — update to remove OpenSpec mention
+
+**TDD steps**:
+1. Write test: `grep` the compiled/source `bin/forge.js` and assert strings `promptOpenSpecSetup`, `checkForOpenSpec`, `initializeOpenSpec`, `isOpenSpecInitialized` are absent
+2. Run test: confirm it fails — functions exist
+3. Remove all 4 functions and call sites from `bin/forge.js`
+4. Run test + `bun run lint`: 0 errors, 0 warnings
+5. Commit: `feat: remove OpenSpec from setup CLI`
+
+**Expected output**: `bin/forge.js` has no OpenSpec logic. `bun run lint` passes clean.
+
+---
+
+## Task 5: Update 9-stage → 7-stage listing in bin/forge.js
+**File(s)**:
+- `bin/forge.js` (~line 418 and surrounding stage table)
+
+**What to implement**:
+Find the description string `"9-stage TDD-first workflow"` at ~line 418 and any inline stage listing table that shows 9 stages (including the old `/research` stage). Update to say `"7-stage TDD-first workflow"` and align the stage table with the current 7 stages: `/plan`, `/dev`, `/validate`, `/ship`, `/review`, `/premerge`, `/verify`.
+
+**TDD steps**:
+1. Write test: parse `bin/forge.js` source and assert the string `9-stage` is absent and `7-stage` is present
+2. Run test: confirm it fails — `9-stage` string exists
+3. Update the description string and stage table
+4. Run test: confirm passes
+5. Commit: `docs: update stage count from 9 to 7 in forge setup description`
+
+**Expected output**: `bin/forge.js` says `7-stage`, stage table matches current workflow.
+
+---
+
+## Task 6: Add Codex CLI plugin
+**File(s)**:
+- `lib/agents/codex.plugin.json` (create)
+
+**What to implement**:
+Create a new plugin JSON for Codex CLI following the established schema. Codex uses `AGENTS.md` for instructions (already installed by forge setup — no extra step needed) and `.codex/config.toml` for tool config.
+
+Plugin JSON structure:
+```json
+{
+  "id": "codex",
+  "name": "OpenAI Codex CLI",
+  "version": "1.0.0",
+  "description": "OpenAI's terminal coding agent",
+  "homepage": "https://github.com/openai/codex",
+  "capabilities": {
+    "commands": false,
+    "skills": false,
+    "hooks": false
+  },
+  "directories": {},
+  "files": {
+    "rootConfig": "AGENTS.md"
+  },
+  "setup": {
+    "copyRules": false,
+    "createSkill": false
+  }
+}
+```
+
+**TDD steps**:
+1. Write test: assert `lib/agents/codex.plugin.json` exists and parses as valid JSON with `id === "codex"` and `files.rootConfig === "AGENTS.md"`
+2. Run test: confirm it fails — file does not exist
+3. Create `lib/agents/codex.plugin.json`
+4. Run test: confirm passes
+5. Commit: `feat: add Codex CLI agent plugin`
+
+**Expected output**: `lib/agents/codex.plugin.json` exists with correct schema.
+
+---
+
+## Task 7: Fix OpenCode plugin homepage URL
+**File(s)**:
+- `lib/agents/opencode.plugin.json`
+
+**What to implement**:
+Fix the incorrect `homepage` field. Current value: `"https://github.com/opencode"` (does not exist). Correct value: `"https://opencode.ai"`.
+
+**TDD steps**:
+1. Write test: parse `lib/agents/opencode.plugin.json` and assert `homepage` does not contain `github.com/opencode` and equals `https://opencode.ai`
+2. Run test: confirm it fails — wrong URL exists
+3. Update the `homepage` field in `lib/agents/opencode.plugin.json`
+4. Run test: confirm passes
+5. Commit: `fix: correct OpenCode plugin homepage URL`
+
+**Expected output**: `lib/agents/opencode.plugin.json` has `homepage: "https://opencode.ai"`.
+
+---
+
+## Task 8: Make CLAUDE.md a symlink to AGENTS.md in setup flow
+**File(s)**:
+- `bin/forge.js` (modify `_createClaudeReference()` → replace write with symlink, handle EPERM gracefully)
+
+**What to implement**:
+The function `_createClaudeReference()` at ~line 1486 currently writes a stub text file. Replace it with symlink creation:
+1. Use `fs.symlinkSync('AGENTS.md', destPath)` (relative target, so symlink points to sibling AGENTS.md)
+2. Catch `EPERM` (Windows without Developer Mode) — fall back to writing the stub with a console warning
+3. Remove `@private - Currently unused` comment — this function should now be wired into the active setup flow
+
+Also wire it: where `createClaudeMd: true` is set in `createInstructionFilesResult` flows, ensure `_createClaudeReference()` (renamed to `createClaudeSymlink()`) is called rather than creating a full copy.
+
+**TDD steps**:
+1. Write test: mock `fs.symlinkSync` to succeed → assert `createClaudeSymlink(destPath)` calls `symlinkSync('AGENTS.md', destPath)`; second test: mock `symlinkSync` to throw `EPERM` → assert fallback stub file is written and warning is logged
+2. Run tests: confirm they fail — function doesn't exist yet
+3. Rename `_createClaudeReference` to `createClaudeSymlink`, replace body, add EPERM catch
+4. Run tests: confirm passes
+5. Commit: `feat: CLAUDE.md created as symlink to AGENTS.md`
+
+**Expected output**: On supported filesystems, `CLAUDE.md` is a symlink pointing to `AGENTS.md`. On EPERM, a redirect stub is written with a warning.
+
+---
+
+## Task 9: Clean up doc references (clinerules, windsurfrules, SETUP.md)
+**File(s)**:
+- `.clinerules` (remove Antigravity row, Windsurf row, Aider row from agent table; remove GEMINI.md, `.agent/`, `.windsurf/` from directory tree)
+- `.windsurfrules` — **delete entirely** (Windsurf dropped)
+- `docs/SETUP.md` (remove `### Google Antigravity`, `### Windsurf`, Aider mention in `### Kilo Code, OpenCode...` heading; remove directory tree entries)
+- `docs/TOOLCHAIN.md` if it has Antigravity/Windsurf/Aider references
+
+**What to implement**:
+Pure doc cleanup — remove all references to dropped agents from rule files and documentation. Update agent support tables to reflect current supported agents only.
+
+**TDD steps**:
+1. Write test: `grep` `.clinerules` and `docs/SETUP.md` for strings `Antigravity`, `Windsurf`, `GEMINI.md`, `aider` — assert none found
+2. Run test: confirm fails — references exist
+3. Edit all files to remove dropped agent references
+4. Run test: confirm passes
+5. Commit: `docs: remove Antigravity, Windsurf, Aider references from docs`
+
+**Expected output**: No dropped agent references in any doc file. `.windsurfrules` deleted.
+
+---
+
+## Task 10: Update tests — remove deleted agent test coverage, add Codex test
+**File(s)**:
+- `test/agent-detection.test.js`
+- `test/other-agents-config-generation.test.js`
+- `test/cli/forge.test.js`
+- `test/cross-platform-install.test.js`
+- `test/e2e/setup-workflow.test.js`
+
+**What to implement**:
+- Remove any remaining test cases that reference Antigravity, Windsurf, or Aider (Tasks 1–3 may have done this partially — verify none remain)
+- Remove any `openspec`-related test cases
+- Add a test that `lib/agents/codex.plugin.json` loads correctly in the plugin registry
+- Verify `bun test` reports 0 failures
+
+**TDD steps**:
+1. Write test: load all plugin JSONs from `lib/agents/` — assert `codex` is present, `antigravity`/`windsurf`/`aider` are absent
+2. Run test: confirm it fails — codex missing, others present
+3. Clean up remaining stale tests across all affected files
+4. Run `bun test`: 0 failures
+5. Commit: `test: update agent test suite for removed and added agents`
+
+**Expected output**: `bun test` passes with 0 failures. No stale tests for dropped agents.

package/docs/plans/2026-03-10-command-creator-and-eval-decisions.md

@@ -0,0 +1,52 @@
+# Decisions Log: Command Creator & Eval
+
+- **Feature**: command-creator-and-eval
+- **Date**: 2026-03-14
+- **Task list**: docs/plans/2026-03-10-command-creator-and-eval-tasks.md
+- **Design doc**: docs/plans/2026-03-10-command-creator-and-eval-design.md
+
+---
+
+<!-- Decisions will be logged below as they arise during /dev -->
+
+## Decision: Skip agnix integration (Task 7)
+
+**Date**: 2026-03-14
+**Decision**: SKIP -- agnix does not provide sufficient value beyond our existing structural tests.
+
+### Evaluation Summary
+
+Ran `npx agnix@0.16.1 . --format json` against the repo.
+
+**Results**: 228 diagnostics (26 errors, 196 warnings, 6 info) across 128 files checked.
+
+### Rule Breakdown
+
+| Count | Rule | Level | Assessment |
+|-------|------|-------|------------|
+| 161 | XP-003 (cross-platform) | warning | **False positive.** Flags `.claude/` paths as portability issues. This is the standard Claude Code directory -- by design, not a bug. |
+| 16 | AS-010 (agent-skills) | warning | **Not applicable.** Wants "Use when..." trigger phrases in `.codex/skills/` SKILL.md frontmatter. Codex-specific formatting. |
+| 11 | AS-002 (agent-skills) | error | **Not applicable.** Missing `name` field in `.codex/skills/` frontmatter. Codex skills follow a different spec than the universal agent skills spec agnix expects. |
+| 7 | XML-003 (xml) | error | **False positive.** Flags `</HARD-GATE>` as unmatched XML. This is intentional prompt engineering markup in markdown, not XML. |
+| 5 | XP-SK-001 (cross-platform) | info | Noise. Client-specific frontmatter fields. |
+| 4 | CDX-AG-005 (codex) | warning | Codex-specific formatting suggestions. |
+| 3 | REF-002 (references) | error | **Partially valid.** Broken links in `.codex/skills/rollback/SKILL.md`. But our existing `command-files.test.js` already covers dead reference checks for `.claude/commands/`. |
+| 3 | PE-001 (prompt-engineering) | warning | Subjective. "Critical keyword in lost-in-the-middle zone." |
+| 18 | Various | mixed | Legacy `.cursorrules` warning, AGENTS.md duplicate (test fixture), misc. |
+
+### Why SKIP
+
+1. **70% false positives**: 161 of 228 diagnostics are XP-003 warnings about `.claude/` paths. These are not portability issues -- `.claude/` is the standard Claude Code directory structure.
+2. **XML false positives**: The 7 XML-003 errors about `<HARD-GATE>` are false positives. `HARD-GATE` is intentional prompt engineering markup, not XML.
+3. **Existing coverage**: Our structural tests (`command-files.test.js`, `command-contracts.test.js`, `command-sync.test.js`) already cover dead references, contract validation, and sync drift -- the categories where agnix has some valid findings.
+4. **Suppression burden**: Integrating agnix would require suppressing 200+ false positives to surface 3-5 genuinely useful findings. The maintenance cost exceeds the value.
+5. **No Forge-specific checks**: agnix checks generic multi-agent patterns but does not understand Forge's 7-stage workflow, HARD-GATE semantics, or command contract structure.
+
+### What agnix IS good at (for other projects)
+
+- Detecting broken markdown links across agent config files
+- Checking agent skill frontmatter against universal spec
+- Cross-platform portability analysis for repos targeting multiple AI tools
+- Prompt engineering anti-patterns (lost-in-the-middle, ambiguous terms)
+
+For Forge specifically, these checks either don't apply or are already covered by custom structural tests that understand our domain.