FORGE is a skills-first governance workflow for AI-assisted coding.
Turn AI coding from chaotic one-shot prompting into a reliable engineering workflow. FORGE gives you clear task boundaries, safer commits, review gates, and team-ready coordination so agents can ship real work without losing control of the project.
The canonical skill pack lives in skills/forge/. This repo also includes install scripts, verification helpers, optional CI enforcement, tool-scaffolding scripts, and philosophy docs.
Install the skill pack:
bash install.shOr install it with Vercel's skills CLI:
npx skills add https://github.com/redteamlife/forge.gitThen choose the setup profile you want:
Use the forge skill to bootstrap this repo in solo-simple mode for a new project.
Use the forge skill to bootstrap this repo in solo-governed mode. I want one task branch per governed task, and the agent must never merge into main unless I say so explicitly.
Use the forge skill to bootstrap this repo in team-full mode. We want repo agent surfaces, CI enforcement scaffolding, and team coordination from the start.
In editors that expose slash-command skills, FORGE subskills are intentionally grouped as /forge-*:
/forge-bootstrap/forge-execute-task/forge-critique/forge-security-review/forge-evaluation/forge-memory/forge-tool-workflow
Review the generated docs/forge/ files, adjust anything important, then kick off work with:
Use the forge skill to start working on tasks.
If you want the agent to keep moving until it hits a real decision point, say:
Use the forge skill to start working on tasks, do not stop until done.
Via npx skills add, FORGE follows the shared Agent Skills ecosystem used by Vercel's skills tooling. Vercel documents support for 18+ AI agents, including Claude Code, GitHub Copilot, Cursor, Cline, and many others, and the CLI compatibility table also includes Codex. See:
The manual install scripts in this repo currently provide explicit target helpers for:
- shared
~/.agents/skills - Claude Code
- Codex
- Cursor
- Windsurf
See GETTING_STARTED.md for the fuller flow and MIGRATION.md for upgrading older FORGE repos.
skills/forge/- canonical FORGE skill packskills/forge/assets/ci/- optional governance validators, hooks, and workflow templates that ship with the skill (used byteam-fullandsolo-governedprofiles)skills/forge/assets/scripts/install-forge-hooks.{sh,ps1}- idempotent git-hook installer bundled with the skill
install.sh,install.ps1,uninstall.sh,uninstall.ps1- install helpersverify-install.sh,verify-repo.py- verification helpersscripts/- tool-development scaffolding (forge-tool-init,forge-publish,forge-sync-public)philosophy/- design rationale and background material
Reusable agent/editor onboarding files live in skills/forge/assets/agent-surfaces/.
Repo-specific operational files such as GitHub workflows stay at the root where the platform expects them.
Copy those agent-surface files into downstream repos when you want the repo itself to remind agents to use FORGE or stop and ask for installation before governed work.
Agent-specific behavior is summarized in skills/forge/references/agent-flavors.md.
FORGE treats:
- skills as the stable execution contract
docs/forge/or the configured issue tracker as project-local state- CI and hooks as optional external enforcement
task_source in docs/forge/AI.md controls where tasks live:
local:docs/forge/TASKS.yamlgithub: GitHub Issues viaghgitlab: GitLab Issues viaglabexternal: Jira, Linear, or another tracker managed through MCP, CLI, or human workflow
repo_flavor is an optional routing hint, set only when the repo shape changes generated docs or task selection:
contract-first: OpenAPI, protobuf, GraphQL, generated clients, or other shared interface filestooling: private/public tool release workflows
security_profile controls optional DevSecOps gate guidance:
baseline: task-local checklist reviewrepo-fortress: branch protection, CODEOWNERS, security policy, and risk visibilityci-security: repo-fortress plus SAST, secret scanning, dependency/SCA, and findings visibilityfull-devsecops: CI security plus CD pre-flight, DAST, SBOM, provenance, and cleanup evidence
application_docs: true enables a separate human-facing docs/ tree alongside docs/forge/. It generates a profile-aware subset of overview, architecture, threat model, developer guide, interfaces, deployment, runbook, and ADR templates with maintenance triggers wired into execute, critique, and evaluation. Default is false.
In solo-simple, the agent should finish one task, update TASKS.yaml, create a Conventional Commit, and stop before moving on.
In solo-governed, the agent should still preserve one-task checkpoints, but it should use task branches and must not merge or promote into the release branch without explicit human instruction.
In team-full, FORGE supports:
- task claiming through GitHub/GitLab Issues when selected, or
forge-statefor local task ledgers - feature branches for implementation
- an integration branch such as
develop - a release branch such as
main - per-task checkpoints and Conventional Commits
- explicit
implemented/integrated/completecloseout checkpoints - optional CI enforcement from
ci/ - contract-file discipline for API, schema, generated client, and integration-boundary changes
- optional DevSecOps gates for repository hardening, CI/CD security, supply-chain scanning, and SBOM evidence
Commit history should describe the work only and must not include AI attribution such as Generated by Claude or Coded with Cursor.
FORGE is meant to feel simple in practice:
- describe the project once
- let the skill scaffold a clean
docs/forge/contract - review the plan
- tell the agent to start working
- only step in when a real blocker or decision appears
The goal is not more process for its own sake. The goal is to let agents move faster without turning your repo into chaos.
FORGE is easiest to understand as three starting profiles:
solo-simple: smallest useful governance for one operatorsolo-governed: solo work, but with task branches and human-controlled mergesteam-full: full repo-local docs and team coordination first, followed by an explicit choice about copying repo agent surfaces and CI scaffolding
If a user asks for "the full experience", FORGE should treat that as team-full unless the user clearly describes a solo repo.
FORGE helps agents work one real task at a time instead of wandering across the repo. That means cleaner commits, easier review, and much less "the agent changed five unrelated things" pain.
When the work gets ambiguous, risky, or architecturally fuzzy, FORGE is designed to stop and surface the decision instead of bluffing. That makes it much easier to trust the agent on meaningful work.
FORGE is not just for solo sessions. It includes team coordination patterns for people and agents working together:
- task claiming
- branch discipline
- integration vs release flow
- CI-backed enforcement when you want it
FORGE includes explicit critique and evaluation steps so "it compiled" is not the only definition of done. You can keep the workflow lean, but you still get a real gate before a task is treated as finished.
FORGE ships with a dedicated security-review pass and modular checklist assets for common web and application surfaces. Instead of treating security like an afterthought, you can make it part of the normal delivery loop.
The checklists are also customizable:
- use the shared baseline checklists in
skills/forge/assets/security-checklists/ - generate only the sections that fit your project
- extend the project-local
docs/forge/SECURITY_CHECKLISTS.mdwith your own stack, framework, or deployment-specific concerns
FORGE is designed to reduce drift without adding huge prompt overhead. The skill pack holds the stable workflow, project docs hold only local state, and the response rules push agents toward short, useful updates instead of long assistant monologues.
FORGE is one install, but it is made of focused subskills so agents can load only the part they need:
forge-bootstrap- scaffold or refresh a leandocs/forge/contract for a projectforge-execute-task- select the next bounded task and implement it safelyforge-critique- check for scope drift, gaps, and architecture conflicts before completionforge-security-review- run checklist-based security review against the actual change surfaceforge-evaluation- apply definition-of-done and evidence gates before a task is treated as completeforge-memory- keep reusable lessons and failure notes so future sessions start smarterforge-tool-workflow- support the private/public tool development workflow when a project needs it
That structure is what makes FORGE feel lightweight in use even when the workflow itself is serious.
FORGE also includes a specialized workflow for tool projects where you want to keep internal planning and governance private while still publishing the tool publicly.
This is useful when:
- you want a private development repo with full FORGE docs, task history, architecture notes, and internal discussion
- you want a separate public repo for open-source release or public distribution
- you want to accept public contributions without losing attribution
- you do not want the full internal FORGE governance process exposed in the public repo
In that model:
- the private dev repo stays authoritative for planning, evaluation, memory, and governed implementation
- the public repo is the release surface
- accepted public changes can be pulled back into the private dev flow before the next governed publish
To scaffold that setup, use:
scripts/forge-tool-init.shscripts/forge-tool-init.ps1
These scripts seed minimal docs/forge/ files, create the tool workflow scaffolding, and set up the private-dev/public-release structure that FORGE's forge-tool-workflow skill understands.
If you are just building a normal app or website in one repo, you can ignore this section completely. The tool workflow is an optional pattern for projects that need that private/public split.
To verify the repo and install flow:
python3 verify-repo.py