English | 中文

Turn 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 turns project rules into workflows that agents can execute. Before working on a task, the agent explains how those rules apply: what it will do, how it will check the result, and when it should stop for review.

The rules are not applied ad hoc during execution. They first become the task boundary; after confirmation, the agent works within that boundary and leaves validation records. That means less repeated explanation, less drift, and work that is easier to review.

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.

Forma's difference is that project rules enter the workflow, so the agent writes different planning priorities. You do not have to remind it every time.

This is not a required checklist. It shows how the same request can produce different planning boundaries and acceptance checks under different project rules.

Most users see three things:

Commit the profile only when the rules need long-term reuse. For a trial workflow, it can be a temporary file and does not need to be kept.

The default workflow uses four stages to manage the task contract lifecycle, plus one continuous execution entrypoint:

showhand is the continuous execution entrypoint: once a plan is locked, it continues remaining tasks until blocked, validation fails, or human input is needed.

Trigger names depend on the installed output. A Forma plugin exposes plugin-local stages like plan and supports Codex-qualified triggers such as forma:plan. A direct skill bundle is installed as standalone skills with the forma-* prefix.

When the team updates a profile, it updates which rules the workflow asks the agent to enforce.

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 install, verify, or explain execution semantics.
  Do not restore removed command aliases.

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 records live in plans/issue-cli-agent-facing-help/.

The lightest path is to have the agent summarize project rules, then generate and install a workflow:

pipx install forma-cli

Then tell the agent:

Use Forma to manage this project's engineering rules as a Codex workflow.
Extract the rules, show me the profile you propose, then after I approve it, build, verify, and install the workflow.

The agent should load Forma's profile guidance itself, then generate, verify, and install the workflow after you approve the rules.

After the generated workflow is installed, start a fresh conversation:

Use forma:plan to plan this issue first.

Issue:
<your task or issue>

If you installed a direct skill bundle rather than a plugin, use the matching forma-* skill trigger instead.

The first useful response should be a proposal before file edits.

If the agent edits files immediately, the workflow was not loaded or was not triggered; Forma is not running.

If the rules should be shared or maintained long term, keep the profile in version control. If you already have a reviewed profile, build workflow output with forma build bundle or forma build plugin. 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, evidence records, and stop conditions.

Generated example output is no longer committed. If a sample profile is useful, build it locally with forma build bundle or forma build plugin and inspect the generated output in a temporary or project-chosen path.

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 execution records. 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 task contract and validation records 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 .forma/profile.yaml.

Start here:

Reference:

Apache-2.0 - see LICENSE