Skip to main content

forge

A Codex-native agent toolkit for structured software delivery: investigation, planning, implementation, review, testing, diagnostics, and workflow continuity across sessions.

Recent Changes

Mock Flows + Numbered Handoff Menu (2026-05-07):

  • forge:test --mode flows authors end-to-end mock flows in 4 styles (scenario / BDD / HTTP-replay / workflow-dry-run). The skill detects your project layout, recommends the best-fit flow type with a confidence score, and progressively gates 8 quality criteria across scaffold → author → execute → report phases. Run with --flow-type <type> to override the recommendation, or --framework/--entry-point/--roles to fine-tune detection. Reference templates/mock-flow-types.md for per-type details.
  • Every skill's final step now presents a numbered handoff menu instead of a single hardcoded next-skill string. Reply with "yes" / "1" / "default" or pick a numbered alternative to steer the workflow. Use scripts/smoke.py as a CI-eligible end-to-end harness for the new flows mode.

State-lifecycle and authoring fixes (2026-05-07):

  • The plan skill now materializes a section-marker skeleton at step 1 (sourced from templates/writing-plans.md) and refuses to mark step 6 complete while any <!-- FORGE_SKELETON: ... --> markers remain.
  • forge resume --cleanup lists state files eligible for cleanup (dry-run by default). Add --force to delete; --all-stale --force for migration mode (clears every state file regardless of age).
  • Re-running step 1 of any skill now aborts when an in-progress same-skill session exists. To resume, use the --state <path> flag or run resume.py.
  • Over-cap --step invocations (e.g., --step 9 on an 8-step skill) now print a friendly "skill complete" message and exit 0 instead of erroring.
  • A failure_count field tracks consecutive same-step retries; after two failures, resume.py emits an "inspect logs" hint instead of producing a third retry command.

Install (pipx) — run in any repo

This repo ships a global forge launcher so you can install once and run workflows from any target repository (without copying scripts/ into each repo).

pipx install forge-codex

Then, from any target repo:

forge evaluate --step 1 --mode review
forge plan --step 1
forge status

Use --repo <path> to target a different repository root.

Quick Start (dev / contributors)

# Clone the repo
git clone https://github.com/your-org/forge-codex.git /path/to/forge-codex

# Enter the project
cd /path/to/forge-codex

Then use the repo as the home for Codex-oriented workflow assets, skills, prompts, and orchestrators.

Codex Config

If you want local Codex sessions to treat Forge skill invocation as implicit permission to use Forge agents, add a developer_instructions block to ~/.codex/config.toml:

developer_instructions = """
Invoking any `forge:*` skill implicitly authorizes the agent dispatch required by that workflow. Do not require the user to separately ask for delegation, sub-agents, or parallel agent work after invoking a Forge skill.

At the start of a fresh interactive session, begin the first user-visible response with exactly: Ready Player 1?
"""

You can verify the injected developer prompt with:

codex debug prompt-input

If a higher-priority launcher or hosted integration injects its own developer instructions, those may still override or compete with your local config.

Goals

  • Turn a structured multi-skill workflow model into a Codex-first environment
  • Support multi-step, resumable engineering workflows instead of one-shot prompts
  • Separate skill orchestration from reusable methodology templates
  • Preserve handoff context between phases and between sessions
  • Make review, verification, and diagnostics first-class parts of the workflow

Planned Skills

Skill Purpose Typical Invocation
develop Investigate a problem space and shape solution options develop <problem or feature>
plan Convert an approved direction into an implementation plan plan
evaluate Review a plan before or after implementation evaluate <plan>
implement Execute a plan in ordered or parallel waves implement
code-review Run structured review modes against code changes code-review <target>
test Execute tests, analyze failures, and identify coverage gaps test
diagnose Perform root-cause analysis on bugs and regressions diagnose <issue>
status Show workflow position, open findings, and next action status
resume Continue the active workflow from persisted state resume

Forge Skill Invocation Contract

Invoking a Forge workflow skill is intended to be enough to authorize the agent team that skill needs.

  • forge:develop, forge:plan, forge:implement, forge:code-review, forge:test, and forge:diagnose should auto-dispatch the relevant Forge agents when their workflow calls for it.
  • forge:evaluate should auto-dispatch the review team when team/review mode is active.
  • Users should not need to separately ask for "sub-agents", "delegation", or "parallel agent work" after invoking a Forge skill.
  • If the surrounding Codex session policy blocks agent spawning, that should be surfaced as an environment limitation rather than treated as normal Forge behavior.
  • Every spawned agent must be closed (close_agent) once it reports back or is no longer useful. Forge skills never leave agents open across wave / step / phase boundaries — Codex caps concurrent agents and leaked sessions eventually block further dispatch. See templates/codex-runtime.md for the lifecycle pattern.
  • At the end of each skill's workflow, a numbered handoff menu replaces the previous single next-skill prompt. Users can reply "yes", "1", "default", or a literal command; the menu makes workflow alternatives explicit.

Workflow Model

develop -> plan -> evaluate (pre) -> implement -> code-review -> test -> diagnose (if needed)

At any point:
- evaluate can run as a standalone critique workflow
- diagnose can run as an ad-hoc incident workflow
- status and resume can inspect or continue the current state

The intended model is composable rather than monolithic:

  • Each skill can run on its own
  • Skills can hand off context to the next skill in the chain
  • State files make interrupted workflows resumable
  • Review loops enforce quality gates before moving downstream

Agents

The Codex version is expected to use a small set of specialized roles rather than a single undifferentiated agent.

Agent Role
architect Investigation lead, solution design, architecture review
planner Implementation planning, sequencing, dependency mapping
backend-dev Backend implementation with tests
frontend-dev Frontend implementation with tests
critic Challenges assumptions, stresses weak logic, finds hidden risks
qa-reviewer Validates behavior, testing quality, and verification depth
security-reviewer Reviews security-sensitive changes and operational risk
doc-writer Produces user-facing and developer-facing documentation and tracks documentation debt

Methodology Coverage

forge-codex is intended to bundle practical engineering methods instead of vague “best practices”.

Investigation and diagnostics

  • 5 Whys
  • Kepner-Tregoe IS/IS-NOT
  • Fishbone / Ishikawa
  • FMEA
  • MECE decomposition
  • Bayesian evidence updates
  • hypothesis-driven debugging
  • change analysis
  • counterfactual reasoning
  • barrier analysis

Solution design

  • divergent and convergent option generation
  • trade-off scoring
  • pre-mortem analysis
  • reversibility checks
  • constraint analysis

Planning

  • phased execution
  • dependency mapping
  • parallelization opportunities
  • rollback planning
  • explicit verification steps
  • documentation-in-the-loop

Review and testing

  • structured finding severity
  • behavior verification
  • edge-case analysis
  • regression coverage review
  • failure triage
  • operational readiness checks

Architecture

The repo is expected to follow a script-driven orchestration model.

  • Skill orchestrators drive state progression for each workflow
  • Prompt templates provide repeatable phase instructions
  • Shared templates hold reusable review and planning patterns
  • State files persist current step, completed step, findings, and handoffs
  • Memory files carry context between adjacent skills
  • Reports provide durable outputs from evaluate, review, and diagnose flows

State and Continuity

Cross-session continuity is a core design goal.

  • Each active skill should persist its own state file
  • Resume logic should distinguish between a true conflict and an unrelated active session
  • Standalone skills should not pause just because another non-conflicting workflow exists
  • Handoff files should summarize completed work and recommend the next step
  • Status tooling should surface active sessions, findings, and next actions without requiring manual inspection

Design Principles

  • Codex-first: optimize for Codex workflows, not a direct port of another assistant’s toolkit model
  • Actionable outputs: produce plans, findings, commands, and reports that can be used immediately
  • Resumable by default: interrupted work should be recoverable
  • Verification over narration: claims should be tied to code, tests, or runtime evidence
  • Composable workflows: users should be able to run a single skill or the full chain
  • Minimal hidden state: the workflow should be inspectable from files in the repo

Current Project Structure

forge-codex/
├── README.md
├── agents/
├── prompts/
│   ├── develop/
│   ├── plan/
│   ├── evaluate/
│   ├── implement/
│   ├── code-review/
│   ├── test/
│   └── diagnose/
├── templates/
│   ├── review/
│   ├── planning/
│   ├── reporting/
│   └── handoff/
├── scripts/
│   ├── shared/
│   ├── develop/
│   ├── plan/
│   ├── evaluate/
│   ├── implement/
│   ├── code-review/
│   ├── test/
│   └── diagnose/
├── skills/
│   ├── develop/
│   ├── plan/
│   ├── evaluate/
│   ├── implement/
│   ├── code-review/
│   ├── test/
│   ├── diagnose/
│   ├── status/
│   └── resume/
└── templates/

Initial Roadmap

Phase 1: Skeleton

  • define repository layout
  • add shared orchestration primitives
  • add status and resume foundations
  • document the state model

Phase 2: Core Skills

  • implement evaluate
  • implement diagnose
  • implement develop
  • add report generation and state cleanup rules

Phase 3: Delivery Flow

  • implement plan
  • implement implement
  • implement code-review
  • implement test

Phase 4: Hardening

  • add regression tests for state handling
  • verify conflict detection logic
  • tighten workflow transitions
  • document extension points for future agents and skills

Current Status

This repository now contains the copied Codex workflow assets, reorganized into a Codex-first layout. Assistant-specific packaging has been removed, and the top-level structure has been normalized around agents/, skills/, scripts/, prompts/, and templates/.

License

MIT

Metadata

Release files for forge-codex 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for forge-codex 0.1.0
File Size Uploaded Provenance Actions
forge_codex-0.1.0.tar.gz 217.6 kB Without provenance Details for forge_codex-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for forge-codex 0.1.0
File Interpreter ABI Platform Actions
forge_codex-0.1.0-py3-none-any.whl Python 3 none any Details for forge_codex-0.1.0-py3-none-any.whl

Total release size: 483.2 kB

Release files / forge_codex-0.1.0.tar.gz

Download URL forge_codex-0.1.0.tar.gz
Size 217.6 kB
Tags Source
SHA-256 checksum
How to use checksums
d5c13147d536076814637cdc8276fe12db9f8990793a9b59914cfc089f89c2bc
BLAKE2b-256 checksum
How to use checksums
6f717d952e09580ce1bd0f03682b26b09242e34ead7edd95dd7e51afebea2322
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.13

Release files / forge_codex-0.1.0-py3-none-any.whl

Download URL forge_codex-0.1.0-py3-none-any.whl
Size 265.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
74f1e676b12771c9d342f661cf6c356f45e6d58a432f75b429f8e585d27857a1
BLAKE2b-256 checksum
How to use checksums
8b106de97ad944cafdb4de7e6b33f205fde1e4513cb00af219dda3104ce82292
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.13

Security for forge-codex 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page