Turn project standards into reusable workflows for coding Agents.
Forma distills durable engineering standards from repository rules, established code practices, and reviewed work evidence, then packages them as installable Agent workflows.
Before implementation, the Agent states how those standards apply to the current task. After approval, Plan files lock the goal, scope, constraints, validation, and evidence requirements. Implementation and delivery review then use the same basis.
The same request should not be implemented the same way in every repository. Forma makes the project's own definition of good delivery explicit before work starts and reviewable when it ends.
Project standards become workflow behavior · Application explicit before implementation · Implementation and delivery use the same basis · Evidence-backed unwritten practices can become durable · One Profile, four targets
Projects can give rules to an Agent in several ways. These approaches solve different problems and can be used together.
| Approach | Rule source | How it applies to the current task | Shared basis afterward |
|---|---|---|---|
| General workflow | A predefined development method | Provides a stable process without knowing this repository's engineering standards | The process is consistent; project-specific judgment remains with the Agent |
AGENTS.md and other rule files |
Durable rules written by the project | The Agent reads them and decides what applies and how | They remain authoritative sources but do not automatically become a task contract |
| Task prompt | Instructions in the current conversation | Can correct or constrain the current task directly | Flexible, but difficult to reuse consistently across tasks, Agents, and sessions |
| Forma | Reviewed project rules, code practices, and work evidence | Makes the applicable standards and their task-specific application explicit before implementation, then records them in Plan files | Implementation, validation, evidence, and delivery evaluation use the same project standard |
Forma does not replace AGENTS.md. Rule files remain important project
sources. Forma compiles confirmed standards into the workflow stages that use
them and requires the Agent to make their task-specific application visible
before implementation.
Suppose two projects both need to “add rate limiting to an existing API”:
| Public API project | User-facing product project | |
|---|---|---|
| Planning focus | Identify affected endpoints, error contracts, clients, and generated code | Define the user-visible state, messaging, retry behavior, and degraded experience |
| Implementation constraints | Reuse the existing gateway and configuration path, preserve API compatibility, and provide rollout controls and rollback | Reuse established request-state and messaging components while keeping copy and accessibility behavior consistent |
| Validation requirements | Run contract, integration, and client-compatibility checks | Validate the complete interaction path, component states, recovery behavior, and observability |
| Delivery standard | Prove that existing callers remain compatible and that the change can be rolled out and reversed safely | Prove that rate-limit behavior is understandable and usable, and that failures are recoverable and observable |
The requirement is the same, but the project workflow changes what the Agent must do to deliver it well.
The Agent starts with a read-only Forma diagnosis. It examines:
- project standards that are already written down;
- drift between rule sources, code, and their consumers;
- evidence-backed practices that may deserve durable reuse;
- boundaries, tradeoffs, and exceptions that still need an owner decision.
Basic diagnosis focuses on declared project rules. Deep diagnosis can also use recent commits and readable Agent sessions as work evidence.
Findings do not become project rules automatically. The Agent prepares a Profile proposal, and the user decides which standards should be reused across future tasks.
Forma works through three public artifacts:
| Artifact | Purpose |
|---|---|
| Profile | Project-owned YAML source for durable engineering standards, execution boundaries, validation, and evidence requirements |
| Installed workflow | Skills or a plugin generated from the Profile and installed into a target Agent |
| Plan files | The current task's plan.md and tasks.md, recording how project standards apply to this task |
project rules and practices
→ reviewed Profile
→ Installed workflow
→ current-task Plan files
→ implementation, validation, and delivery evidence
→ delivery review and rework
The Profile stores durable standards, the Installed workflow applies them, and the Plan files fix their meaning for the current task.
A working feature with passing agreed tests may satisfy the minimum task requirements. Delivery review still needs to ask:
- Is ownership in the right module?
- Does the implementation reuse established project paths?
- Are failure, recovery, and boundary behavior validated?
- Are compatibility, rollback, and maintenance boundaries present?
- Is the evidence strong enough to support the conclusion?
When review is enabled, the Agent evaluates the Plan files, actual changes,
and delivery evidence. It reports whether the requirements were met, what was
checked, the material findings and their engineering impact, and whether to
accept the work, route it to rework, or stop because the evidence is
insufficient.
Install the Forma CLI:
pipx install forma-cliThen tell your Agent:
Use the
formacommand to analyze the current project.
The Agent starts with a read-only diagnosis. Profile authoring, workflow generation, and installation happen only after the relevant findings and project standards have been reviewed.
After installation:
Use
<workflow-name>for this task.
To start explicitly with planning:
Use <workflow-name>:plan to plan this task first.
If the workflow is named backend, a plugin exposes names such as
backend:plan, while a direct skill bundle exposes names such as
backend-plan.
See Quick Start for the complete first-use path and the Command Reference for command and maintenance details.
Version note: This page describes the current
mainbranch. As of this writing,pipx install forma-cliinstalls release 0.1.3. Until the next release, pi support, DeepSeek Harness support, Profile-family reuse,forma reinstall, and the current plain-language stage names are available onmainbut are not 0.1.3 claims.
Current main target output:
| Agent platform | Direct skills | Plugin |
|---|---|---|
| Codex | Supported | Supported |
| Claude Code | Supported | Supported |
| OpenCode | Supported | — |
| pi | Supported | — |
| DeepSeek Harness | Supported | — |
Forma can deterministically generate, verify, and install workflow structure, and it can lock task boundaries, validation requirements, and delivery evidence. It cannot guarantee that every model will satisfy every semantic constraint perfectly. The result still depends on the Agent, model, and task context.
Forma is most useful for projects that already use coding Agents, have durable engineering standards spread across rules and practice, and need those standards applied consistently across planning, implementation, validation, and delivery review. A one-off script or a project with no reusable engineering standard may need only a direct prompt.
Forma uses its own workflow to maintain this repository:
plans/issue-project-rule-workflow-quality/contains Plan files, tasks, implementation decisions, and recorded run evidence from one complete iteration.examples/profiles/contains sanitized Profile sources. They demonstrate source shape and composition, not a guarantee about every runtime outcome..forma/profile.yamlis Forma's own project Profile.CHANGELOG.mdis the source of truth for released and unreleased capability claims.
| Document | What it covers |
|---|---|
| Quick Start | Diagnose a project, then generate, verify, and install its first workflow |
| Concepts | Profile, Installed workflow, Plan files, and delivery evaluation |
| Plan files | How a task records its goal, scope, validation, and evidence |
| Profile Schema | How a Profile represents durable project standards |
| Targets | Generation and installation boundaries for each Agent platform |
| Command Reference | Complete CLI and maintenance behavior |
Apache-2.0 — see LICENSE