Forgewright
Forgewright is a local-first engineering harness for AI-assisted software delivery. It brings task definition, specialist workflows, code intelligence, tool controls, verification, and project continuity into one repository. Use it with the model runtime and tools you configure—not a mandatory hosted service or a second model subscription.
The difference is not a longer prompt or a larger cast of agents. It is a delivery contract: what should change, who may change it, how it is checked, and what remains unverified.
Why Forgewright
| Engineering problem | What Forgewright adds |
|---|---|
| The agent writes code before understanding the task | A goal, explicit acceptance criteria, risk assessment, and the minimum safe scope. |
| Every specialist reads the entire conversation | Compact routing, on-demand skill overlays, bounded task context, and artifact references. |
| Parallel workers overwrite one another | Dependency-aware dispatch, explicit ownership, and isolated worktrees where configured. |
| “Done” means the model says it is done | Project-owned checks and schema-v2 evidence tied to the command, acceptance criteria, and exact worktree. |
| A stopped task leaves effects or processes behind | Owned process leases, cancellation, lifecycle accounting, and honest cleanup status. |
| The next session forgets decisions | Project-scoped checkpoints and canonical documentation; retrieved memory remains context, not authority. |
84 skills. 24 operating modes. One delivery pipeline. The product manifest and capability inventory keep those claims tied to the repository rather than marketing copy.
What you can build
Web products and internal tools. Shape a brief, define architecture and acceptance, coordinate implementation and review, and retain the decisions needed for maintenance. The Product Factory source includes intent, environment-adapter, outcome-verification, and release contracts.
Games and mobile projects. Coordinate systems design, engineering, art direction, QA, performance work, and release evidence. The Game Studio workflow covers concept through release; Unity, Android, and web environment adapters have local tests. Each target still needs its own build tools, devices, and production evidence.
Existing codebases. Investigate bugs, assess refactor impact, generate tests, review security-sensitive changes, and keep documentation aligned with the code. Start with a bounded task; parallel execution is an option, not a requirement.
A practical request
Add save/continue to this game.
Preserve the current gameplay and existing tests.
Define acceptance for resume, corrupt saves, and duplicate rewards.
Inspect affected systems before editing.
Implement the smallest safe change, run the checks, and report:
changed files · observed results · remaining risks · rollback
Do not publish or deploy without approval.
This is an example input, not a fabricated execution transcript. Actual results depend on the connected runtime, project, tools, and checks.
How it works
INTERPRET → DEFINE → BUILD → HARDEN → SHIP → SUSTAIN
flowchart LR
A[Request and acceptance] --> B[Scope and risk]
B --> C[Select context and specialists]
C --> D[Execute through controlled tools]
D --> E[Tests and independent review]
E --> F{Evidence supports acceptance?}
F -->|Yes| G[Owner-approved delivery]
F -->|No| H[Revise or report blocker]
H --> B
G --> I[Checkpoint and maintain]
Clear local work stays small. Security, billing, concurrency, public contracts, and release changes require stronger checks. A worker's successful generation is not product acceptance, and stopping a retry loop never turns an unverified result into a verified one.
The pipeline reference describes orchestration; the canonical runtime ADR documents the implemented enforcement boundaries.
Quick start
1. Install Forgewright as a plugin (recommended)
Forgewright now ships one provider-neutral plugin source for Codex and Claude Code. It installs the entry workflow and specialist skills without requiring a second model subscription.
Codex CLI
codex plugin marketplace add buiphucminhtam/forgewright --ref main
codex plugin add forgewright@forgewright-marketplace
Claude Code
claude plugin marketplace add buiphucminhtam/forgewright
claude plugin install forgewright@forgewright-marketplace --scope user
Start a fresh session after installation and ask for normal engineering work; trigger-only skill descriptions let the host discover the relevant skill on demand. The entry skill is an orchestration alias, so the canonical specialist inventory remains 84 skills.
Plugin installation is skills-only by default: no executable SessionStart hook and no local MCP side effect. Configure the richer local runtime separately when you want machine-local tools.
Verify both installers in isolated profiles:
npm run verify:plugins
2. Build the full local toolchain (advanced)
Use Node.js 22+, Python 3.11+, and Git. The optional Pi package requires Node.js 22.19+. Clone the repository when you need Forge CLI, Docs Hub, MCP, local gates, or framework development:
git clone https://github.com/buiphucminhtam/forgewright.git
cd forgewright
npm run ci:bootstrap
npm run build
npm run build:cli
node src/cli/dist/index.js --help
ci:bootstrap installs checked-in verification dependencies and configures this clone's Git hooks. It does not enable Pi, start production services, or require hosted CI. Model calls use the provider/account you explicitly configure.
You can inspect/onboard a local project without a model call:
node src/cli/dist/index.js --json init /path/to/your-project
node src/cli/dist/index.js --json onboard /path/to/your-project
3. Pin the full framework inside a project (advanced)
For a repository-pinned runtime and local MCP setup, keep the Git-submodule workflow:
git submodule add -b main https://github.com/buiphucminhtam/forgewright.git forgewright
git submodule update --init --recursive
bash forgewright/scripts/forgewright-mcp-setup.sh
Review the setup script and generated configuration. Merge relevant instructions into existing project rules instead of overwriting them. Plugin installation and submodule adoption are complementary: the plugin supplies portable skills; the submodule/full clone supplies reproducible local runtime code and project-owned gates.
What's new
Plugin distribution + behavioral skill quality
Forgewright can now be consumed as a Codex/Claude plugin from the same repository instead of requiring every user to clone or submodule the framework first. One shared skills/ tree remains the source of truth; harness manifests point at it rather than maintaining copied skill packs.
The Superpowers-inspired upgrade also makes skill changes measurable:
| Upgrade | What it changes |
|---|---|
| Skill Quality Engine | Compares baseline → current → candidate behavior across trigger accuracy, required/forbidden events, pressure scenarios, rationalization traps, abstention, tool calls, context bytes, and latency. Promotion fails closed on regressions or critical forbidden behavior. |
| Trigger-only metadata | Boot skill descriptions say when to load the skill, not how to execute it. Workflow details remain in the skill body, reducing routing/context leakage. |
| Minimal worker packets | PLAN_LOCKED compiles into a digest-bound packet containing only objective, acceptance, owned scope, selected skill, decisions/interfaces, constraints, and verifier refs. Parent-only accounting is excluded from worker payloads. |
| Scoped review packages | Review material is bound to exact BASE..HEAD. Task review stays task-scoped; branch/release review requires a planned final review or a named cross-cutting risk. |
| Plan-scoped runtime state | Transient execution state is namespaced by goal_id + plan_digest + base SHA; successful runs clean it, failed runs retain it for diagnosis/resume. |
| Failure classification | Debugging distinguishes hypothesis_wrong, implementation_wrong, environment_wrong, and architecture_wrong; the same approach failing twice forbids a third cosmetic retry. |
The engine itself is deterministic and provider-neutral. A real model benchmark remains separate evidence; Forgewright does not claim universal quality, token, or latency gains from the framework change alone.
Optional Pi execution, under Forgewright control
The Pi integration adds an isolated worker option without replacing Hermes, the current dispatcher, or Forgewright's ownership of goals and acceptance.
| Upgrade | Behavior |
|---|---|
| Pinned SDK | An independent lockfile pins @earendil-works/pi-agent-core@0.85.1; root installation does not install the optional package. |
| Canonical host bridge | Uses the existing model/tool gateways, containment, lifecycle coordinator, and trajectory ledger. start() returns a session; wait() owns settlement. |
| Explicit authority | Host-owned model, account, policy, tool registry, approvals, and scope; task text cannot grant permission. |
| Account-level budgets | One billing-account cap spans multiple workspaces. Never-dispatched reservations are released; uncertain invoked calls retain escrow. |
| Cancellation and deadlines | Late success cannot reopen a closed attempt. Cancellation also releases undispatched reservations when a binding callback hangs. |
| Bounded context and receipts | Preserve acceptance and current bindings; missing native usage or price remains unavailable, not zero. |
| Evaluation and rollback controls | Paired-report comparison plus default-off, single-active-worker canary admission, kill switch, and quarantine. |
Status: experimental, explicitly opt-in. The public delegate CLI now runs a real Pi worker from the parent project. It supports an existing authorized Codex/Pi OAuth subscription or an explicit loopback model server, without TypeSafe or a new paid API fallback. A host-approved task permits only named files, compare-and-swap patches and immutable verifier IDs. The original zero-tool analysis pilot remains available; it is not the coding-worker entrypoint.
npm --prefix integrations/pi ci --ignore-scripts --no-audit --no-fund
npm run build
npm run build:cli
npm --prefix integrations/pi run test:all
After building the CLI and MCP above, run from the parent project, not inside its submodule:
node forgewright/src/cli/dist/index.js delegate on --worker pi --provider openai-codex --auth-source codex --model <exact-codex-model-id>
node forgewright/src/cli/dist/index.js delegate status --worker pi
node forgewright/src/cli/dist/index.js delegate run --worker pi --contract task.json
node forgewright/src/cli/dist/index.js delegate resources
# node forgewright/src/cli/dist/index.js delegate cancel <run-id>
Settings live in the parent's existing .production-grade.yaml; unrelated settings are preserved. current is convenience-only and accepts a Codex-compatible unprefixed model selection; custom providers and provider-prefixed external routes are rejected instead of being reinterpreted as OpenAI. For deterministic setup, prefer the explicit openai-codex command above. To explicitly use an existing Codex subscription, select --provider openai-codex --auth-source codex --model <exact-model-id>. CODEX_HOME is respected. Subscription access is read-only and still consumes its existing quota; expired authorization reports pi_auth_required, not a paid fallback. Local execution needs a configured loopback model endpoint. Verifier isolation currently requires macOS and a single-process command; fork/spawn, network access and source writes are denied. Unsupported platforms fail closed. The governed delegate run entrypoint refuses legacy Agy execution until it has a compatible host-admission/cleanup contract; its low-level adapter and configuration are retained, not silently used as fallback. ready means prerequisites are present, while a successful task receipt requires actual execution. See the Pi ADR for the task contract, local-provider setup, cancellation, limitations and live-measurement gates.
Leaner context and clearer project state
System-1 routing now uses bounded English/Vietnamese rules and optional exact caching, then abstains when the intent is ambiguous. It does not import or call Jev, require TYPESAFE_API_KEY, download a classifier, or spend an extra model call. It takes Jev's bounded-choice approach without claiming to run the Jev model. Progressive skill loading and compact execution summaries keep unrelated context out of the worker.
A shared per-user SQLite admission authority limits Pi clients across projects to at most two active workers and one heavy verifier, with one worker on the low-memory profile, pressure backoff, project fairness and uncertain-operation quarantine. Default scheduling estimates are 192 MiB per Pi worker and 128 MiB per single-process verifier, calibrated against observed target-Mac process RSS (~71–84 MiB for the loaded Pi runtime and ~42 MiB for a small Node verifier). These are admission estimates, not hard RSS caps; memory pressure still blocks new work and preserves host headroom. A small IPC broker starts on demand and exits after 15 idle seconds; project contexts and credentials remain separate. These are concurrency limits, not certified throughput for every 4 GiB workload. Unmanaged IDEs/processes are not killed. Savings and whole-machine overhead still require representative measurement.
The Docs Hub builds a searchable local HTML control center from approved Markdown/JSON. Project structure, roadmap, blockers, and Mermaid-derived flow views come from canonical sources—not another manually maintained dashboard.
node src/cli/dist/index.js docs build .
node src/cli/dist/index.js docs doctor . --strict
Open .forgewright/docs-hub/site/index.html. See the Docs Hub guide for multi-project registration, privacy allowlists, and Obsidian export.
Core Capabilities
The maturity labels below follow the capability inventory: beta means automated local evidence, experimental means incomplete production evidence, and docs-only means a documented integration or workflow—not a supported production runtime claim.
Explore all 14 capability areas
1. Code Intelligence (GitNexus)
Docs-only integration. Navigate relationships and assess impact before refactoring supported codebases. Stale indexes and dynamic code remain limitations; compatibility paths and user overrides are not universally enforced. Guide.
2. Autonomous Testing Stack
Beta. Project-owned checks, property-based tests, controlled mutations, and acceptance-bound evidence. Existing behavioral oracles cannot be weakened merely to make a suite green. Testing guide.
3. Persistent Cognitive Memory (FluxMem)
Experimental. Optional local retrieval and project context across sessions. Current files and canonical checkpoints outrank recalled material; memory never grants tool authority. Architecture.
4. Parallel Skill Dispatch
Experimental. Decompose genuinely independent work into owned lanes and combine checked results. Keep coupled work serial; more workers are not automatically faster or cheaper. Pipeline.
5. Multi-Project Hub
Docs-only management integration. The broader multi-project management surface remains a documented capability. The implemented Docs Hub separately provides local project registration and static source-backed views. Docs Hub.
6. Token Tracking & Cost Analytics
Beta. Track reported usage, budget reservations, and benchmark observations. Distinguish measured usage, estimates, and unavailable pricing. ForgeBench source.
7. MCP Tool Sandbox
Beta application controls—not OS isolation. Canonical gateway admission, policy checks, containment, and bounded output processing. These controls are not a guarantee against every prompt injection or malicious same-user host. Runtime contract.
8. The Adaptive Self-Improving Protocol (ASIP)
Experimental legacy workflow. Retain useful lessons, but do not automatically promote them into shared rules. The canonical stuck rule stops repeated failed approaches and requires new evidence or escalation. Kernel.
9. Runtime Lifecycle Guard
Beta. Track owned process leases, reuse eligible services, and inspect cleanup and disk budgets. Unowned processes stay outside automatic reclamation. Lifecycle ADR.
10. Game Studio Control Plane
Beta optional pack. Phase-aware handoffs from concept and systems design through production, polish, and release evidence. Real builds, devices, playtests, and store approval are project-specific. Game Studio workflow.
11. Token Efficiency Engine & System-1 Routing (Jev Integration)
Experimental. Compact overlays plus keyless, bounded local EN/VI routing with honest abstention. The historical Jev adapter is not on the default route; no classifier/model download or cloud routing call is required. No universal quality or savings percentage is promised. Efficiency protocol.
12. Optional Pi Worker Pilot
Experimental, opt-in. Pinned Pi SDK and a public consumer-project coding worker with scoped file tools, immutable verifiers, cancellation and shared low-memory admission. Existing subscription/local transport is explicit; no autonomous production migration or paired-savings claim. Pi ADR.
13. Codex & Claude Plugin Distribution
Beta. Portable manifests, a shared plugin entry skill, lazy skill discovery, and an isolated install verifier support Codex and Claude Code from one source tree. The default plugin has no executable hook or local MCP side effect. Plugin ADR.
14. Behavioral Skill Quality Engine
Experimental. Deterministic RED/GREEN-style scenario scoring, pressure/rationalization checks, trigger-metadata linting, compact worker/reviewer packets, and promotion gates make skill changes testable. Real-model candidate comparisons remain provider-specific evidence and are not inferred from fixture tests. Skill evals.
Verification
Forgewright's evidence is executable locally. Hosted CI can mirror it, but is not required.
# Core checks
npm run lint
npm run build
npm test
npm run typecheck:cli
npm run build:cli
# Documentation and declared roadmap contracts
npm run ci:docs
npm run verify:product-truth
npm run verify:roadmap
npm run verify:plugins
# Complete project-owned local pipeline
npm run ci:local
Run optional Pi tests separately with the commands above; they include contract checks, real-SDK runtime checks, and owner-gated workflows in separate Node processes. python3 scripts/ci/verify-readme.py checks both front pages and runs the documented init/onboard commands in a disposable project without a model call. The roadmap completion manifest separates implementation, integration, activation, production evidence, and measured outcome. A passing unit suite, a signed commit, and an accepted product outcome are different things.
Trust boundaries
The core is provider-neutral; execution stays within the selected provider's configured ecosystem. Local-first does not mean all data stays on-device: a remote model may receive prompts, selected code, and tool results. Use an appropriate local runtime when that is required.
Tool containment is application-level, not a kernel sandbox. Trusted host callbacks retain host privileges. Hash-bound evidence detects mismatches; it does not authenticate against a same-user attacker. Production Pi activation, live adaptive routing, and arbitrary autonomous process execution require their separate gates. See security guidance and the active roadmap.
Documentation
| Start here | Purpose |
|---|---|
| Product overview | Scope, delivery model, and product direction. |
| Architecture / pipeline reference | Components, ownership, and execution flow. |
| Quickstart details | Deterministic initialization and onboarding. |
| Docs Hub | Source-backed local documentation and project views. |
| Visual grounding | Design direction based on inspected references and evidence. |
| Game Studio | Game-production phases and handoff requirements. |
| Pi integration | Optional worker architecture, limits, and rollout gates. |
| Capability inventory / active roadmap | What exists, its maturity, and what remains open. |
| Changelog | Maintained change history. |
Contributing and support
Bring a concrete problem, a bounded change, and the checks that demonstrate it. Preserve existing behavioral tests; include a failing reproduction for a fix, update the canonical documentation, and run the local gates before opening a pull request. Do not commit generated runtime evidence, credentials, or personal workspace state.
Use GitHub issues for reproducible bugs and proposals. Security reports follow SECURITY.md. Package-specific licensing is declared in the relevant package metadata, including the CLI's MIT declaration; review those declarations and upstream dependency licenses before redistribution.
Build with more leverage. Ship with evidence.