Compile project rules into a dedicated agent workflow.
AGENTS.md, custom skills, and Superpowers can give an agent rules and process. For lightweight projects, that is usually enough.
Forma compiles project rules into workflow skills. Those skills make the agent preview how the rules apply to the current task before implementation, then execute against a task contract and leave proof.
Once Forma is installed, one sentence can have the agent generate that workflow from the current project.
Good fit: repositories with many rules, boundaries, validation needs, and reviewable planning or execution records.
Not a good fit: lightweight cases that only need a few personal agent preferences.
For the same goal, "add rate limiting to settings", a plain plan may say: read the code, add the limiter, run tests.
Different teams define an acceptable plan differently. Forma-generated workflow skills bring those standards into planning, so the agent must state boundaries and acceptance criteria before it edits code.
| Team concern | Constraint in the task contract |
|---|---|
| API contract stability | Classify API impact, response shape, and generator proof before changing handlers. |
| Runtime control stability | Reuse existing config, rollout switches, or limiter paths; cover allowed, limited, disabled, and invalid-config cases. |
| Design-system consistency | Map to an existing component state, name the copy source, and record responsive and accessibility proof. |
| Operator efficiency | Put the state where an operator can act, preserve table and filter flow, and align runbook, telemetry, and audit behavior. |
Four teams receiving the same issue can produce four different task contracts. Forma does not decide which standard is right; it compiles the standard your team already trusts.
Forma produces three things:
| Output | Meaning |
|---|---|
profile |
Team-approved practices kept in version control for review and maintenance. |
workflow bundle / plugin |
Agent workflow installed into Codex, Claude Code, or OpenCode. |
task contract |
The plan contract the agent writes for one task, recorded under plans/issue-<id>/. |
The default workflow uses four stage skills to manage the task contract lifecycle, plus one continuous execution entrypoint:
| Skill | Purpose |
|---|---|
forma-plan |
Align the goal with project rules and produce a reviewable proposal; do not write files or execute work. |
forma-ground |
Gather the evidence required by the rules from code, docs, issues, tests, and related sources. |
forma-lock |
Write the accepted approach into plan.md and tasks.md, locking the task contract. |
forma-execute |
Execute one accepted task, run validation, record proof, and stop when review is needed. |
forma-showhand is the continuous execution entrypoint: once a plan is locked,
it continues remaining tasks until blocked, validation fails, or human input is
needed.
When the team updates a profile, it updates which rules the workflow guards. Regenerate the bundle or plugin, and the agent plans and executes against the new constraints.
This is a simplified excerpt from one real Forma plan.md:
Goal:
Make Forma CLI help clear enough for agents to choose
the right command path without trial and error.
Scope:
Update root CLI help, no-argument behavior, tests/test_cli.py,
docs/usage.md, and docs/usage.zh-CN.md.
Out of scope:
Do not change create-bundle, create-plugin, install, verify,
build-creator, or explain execution semantics.
Do not restore forma create or add a compatibility alias.
Approach:
Make `forma` with no arguments exit 0 and print the same
agent-facing routing guidance as `forma --help`.
Each command help should say what the agent should run next.
Validation:
uv run --extra dev python -m pytest -p no:cacheprovider tests/test_cli.py
uv run --extra dev forma
uv run --extra dev forma --help
This is not a note added after implementation. It is the task boundary the agent
locks before editing code. The task list and execution proof are recorded in
plans/issue-cli-agent-facing-help/.
The lightest path is to install forma-creator and let the agent read the
current project rules to generate a trial workflow:
pipx install forma-cli
forma build-creator --target codex --output /tmp/forma-creator
forma verify /tmp/forma-creator/codex/forma-creator
forma install --target codex --scope project /tmp/forma-creator/codex/forma-creatorThen tell the agent:
Use forma-creator to customize a workflow for this project.
Summarize the key rules for me first.
After I confirm, generate and install it from the hints.
After the generated workflow is installed, start a new thread:
Use forma-plan to plan this issue first.
Issue:
<your task or issue>
The first useful response should be a proposal, not a patch.
If the agent edits files immediately, the workflow was not loaded or was not triggered; Forma is not running.
For shared or long-lived team rules, use the tracked profile path:
Use Forma to extract engineering rules from this project's docs and code,
and draft a profile for review.
After I confirm the profile, generate, verify, and install the target workflow
from it.
If you already have a reviewed profile, use forma create-bundle --profile <profile.yaml> or forma create-plugin --profile <profile.yaml> to generate
workflow output. Full commands are in Quick Start and
Usage.
Good fit:
- Repositories that use coding agents frequently
- Projects with generated files, fixtures, migrations, public APIs, or sensitive data paths
- Teams whose rules are hard to apply reliably through prompts alone
- Teams that need reviewable agent plans and execution records
- Work where the agent should stop when scope, evidence, or permission is unclear
Probably not a good fit:
- Spelling fixes, one-off summaries, or tiny edits
The repository contains more than concept docs.
examples/profiles/ contains sanitized profiles derived from real workflow
families. They show how teams express engineering rules, source-reading rules,
validation depth, proof, and stop conditions.
examples/generated/ contains committed baselines compiled from those profiles.
They are used to inspect generated output and catch drift; they do not prove
that a real agent will always execute correctly.
plans/issue-*/ is Forma's own development record. Each issue records plan.md,
tasks.md, and runs/task-*.md with real task contracts, validation results,
and proof. Judge a run by those records.
Forma is still early. It supports skill bundles for Codex, Claude Code, and OpenCode today. Plugin source is supported for Codex and Claude Code.
It helps agents plan before they act and leave evidence after they act. Each run still needs to be judged by the contract and proof it leaves behind.
Current focus: easier profile generation, smoother bundle/plugin installation, stronger verification, and more real runs.
Forma also uses its own plan-before-execute workflow for development; this
repository's profile source lives in
profiles/forma-self/.
Start here:
| Quick Start | First run, creator path, and tracked-profile path. |
| Concepts | Project rules, workflow outputs, task contracts, and stage boundaries. |
| Workflow Contract | How task contracts organize evidence, boundaries, validation, and proof. |
Reference:
| Profile Schema | YAML source for durable engineering rules. |
| Forma Creator | Conversational workflow generation and temporary injection. |
| Skill Bundle | Generated output layout. |
| Verifier | What verification checks and cannot prove. |
| Targets | Codex, Claude Code, and OpenCode target behavior. |
| Examples | Sanitized sample profiles, generated baselines, and real tracked runs. |
| Usage | Command reference. |
Apache-2.0 - see LICENSE