Forge: Codex Product Harness

Forge guides Codex through five gated stages:

BRAINSTORM -> PLAN -> BUILD -> REVIEW -> SHIP

Use $forge-<stage> in Codex chat for the intelligent workflow. Use forge <stage> and forge approve <stage> in the terminal for state and approval.

Setup

Requirements: Node.js 20+ and Codex CLI, IDE extension, or desktop app.

cd E:\MyWorkSpace\Harness
npm link
forge init

Without npm link, replace forge with node .\bin\forge.mjs.

Install directly from GitHub

The shortest public npm command is:

npx --yes @nhax-work/forge-harness init

To install the forge command globally:

npm install -g @nhax-work/forge-harness

The private GitHub repository remains an alternative source:

After this repository is uploaded, install the CLI globally with one command:

npm install -g github:nhax-work/forge-harness

Then initialize Forge inside any product repository:

cd path\to\your-product
forge init

forge init creates .forge, installs the five skills into .agents/skills, and adds Forge's AGENTS.md only when the project does not already have one. Existing AGENTS.md files are preserved.

To update later:

npm install -g github:nhax-work/forge-harness@main

For a one-time setup without global installation, run directly from the private GitHub repository:

npx --yes github:nhax-work/forge-harness init

This command requires Git credentials authorized to read the private repository.

Codex discovers repository skills from .agents/skills. Start a new Codex session if newly added skills do not appear.

Invoke skills

Enter /skills in Codex CLI or the IDE extension to open the skill selector, or invoke one directly:

$forge-brainstorm
$forge-plan
$forge-build
$forge-review
$forge-ship

The syntax is $forge-build, not /skill forge-build; /skills opens the selector.

Complete workflow

1. Brainstorm

$forge-brainstorm Tôi muốn xây ứng dụng quản lý chi tiêu cá nhân

Inspect 01-brainstorm.md, then approve in the terminal:

forge approve brainstorm

2. Plan

$forge-plan Hãy lập kế hoạch triển khai MVP đã duyệt

forge approve plan

3. Build

$forge-build Hãy thực hiện kế hoạch đã duyệt

forge verify
forge approve build

4. Review

$forge-review Hãy review toàn bộ thay đổi

Blocking findings return to Build for correction and another Review.

forge approve review

5. Ship

$forge-ship Hãy chuẩn bị sản phẩm để phát hành

Ship prepares release readiness. It does not automatically commit, push, merge, publish, deploy, or run production migrations.

forge approve ship
forge finish

State commands

forge status
forge resume
forge verify
forge help

Forge refuses to skip stages or approve artifacts containing TODO. Only the user runs approval commands.

Verification configuration

After forge init, edit .forge/config.json:

{
  "verify": [
    "npm run lint",
    "npm run typecheck",
    "npm test",
    "npm run build"
  ]
}

Commands run sequentially and stop at the first failure.

Runtime artifacts

.forge/
|-- config.json
|-- state.json
`-- tasks/<task-id>/
    |-- 01-brainstorm.md
    |-- 02-plan.md
    |-- 03-build.md
    |-- 04-review.md
    `-- 05-ship.md

Commit artifacts when product decisions should be reviewed with the code. Never store secrets or raw private data in them.