English | 中文

Forma

Turn project standards into a dedicated workflow your coding Agent will follow.

Forma discovers and distills durable execution standards from a repository's written rules and established code practices. It uses those standards to tailor how an Agent plans, implements, validates, and evaluates delivery, then packages the result as an installable, reusable project workflow.

Fixed workflows provide a general development method. AGENTS.md records static project rules for an Agent to read. Forma requires the Agent to explain before implementation how project standards will apply to the current task and locks that decision into the Plan files. Implementation, validation, and delivery evaluation then use the same basis.

Run the same task through different project workflows, and the Agent gets different planning priorities, execution constraints, validation requirements, and delivery standards. At delivery, the same project standard answers not only “Is it done?” but also “How well was it done?”

Project standards become workflow behavior · Their application is explicit before implementation · Delivery quality is evaluated against the same standard

Build the Workflow from the Project

The Agent uses Forma to inspect the project's current rule sources and code practices, identifying:

• project standards that are clearly stated and consistently followed;
• drift and errors in rule sources;
• strong practices established in code that deserve durable reuse.

The Agent presents a proposed Profile for your review. Accepted project standards go into the Profile, and Forma generates and installs a named Installed workflow from it.

Artifact	Purpose
Profile	A project-owned YAML source that records durable engineering standards, execution boundaries, validation requirements, and evidence expectations.
Installed workflow	A set of skills or a plugin generated from the Profile and installed into the target Agent for repeated use across project tasks.
Plan files	The current task's plan.md and tasks.md, which record exactly how project standards will be applied to that task.

One Profile can generate workflows for Codex, Claude Code, and OpenCode. When project standards change, update the Profile and regenerate the Installed workflow for each target.

Same Task, Different Project Workflows

Suppose two projects both need to “add rate limiting to an existing API”:

	Public API project workflow	User-facing product workflow
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 full interaction path, component states, recovery behavior, and telemetry.
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; the project workflow changes what the Agent must do to deliver it well.

Done vs. Done Well

If rate limiting works and the agreed tests pass, the task has met its minimum requirements.

Engineering quality still needs to be evaluated:

• Is ownership in the right module?
• Does the implementation reuse the project's existing configuration and error handling?
• Are failure, recovery, and boundary paths validated?
• Are monitoring, rollback, and maintenance boundaries in place?
• Is the delivery evidence strong enough to support the review conclusion?

When reconcile is enabled, the Agent evaluates the Plan files, actual code changes, and delivery evidence, then reports:

• whether the task requirements were met;
• a 0–100 engineering-quality score;
• the achieved quality band;
• the material findings affecting delivery;
• whether to accept the work or continue with rework.

When more work is needed, rework turns confirmed findings into explicit, executable, traceable requirements and sends them back through the same implementation and validation workflow.

Where Forma Helps

Forma is useful whenever one of these situations sounds familiar:

• You already use coding Agents for everyday development, but want them to work more like developers who know the repository. They should know where a change belongs, what to reuse, how far to validate, and what delivery means for this project.

• Project standards live across rule files, documentation, code, and accumulated practice. You want the most valuable parts distilled into how the Agent works.

• The same task gets different approaches and quality across Agents or sessions. You want them to plan, implement, validate, and deliver against the same project standard.

• You want to see how the Agent plans to follow project standards before it starts coding. Planning priorities, execution boundaries, validation requirements, and stop conditions should be clear first.

• A feature can work and its tests can pass while implementation quality still matters. Architecture, ownership, maintenance cost, risk, and evidence quality should be part of delivery evaluation.

• Project rules and code practices keep evolving. You want future Agent tasks to pick up the new standard after one Profile update.

Getting Started

Install the Forma CLI:

pipx install forma-cli

Then tell your Agent:

Use Forma to create and install a project workflow tailored to this repository.

The Agent analyzes project rules and code practices, prepares the Profile, generates and verifies the Installed workflow, and installs it into the target Agent.

Once installation is complete:

Use <workflow-name> for this task.

To start explicitly with planning:

Use <workflow-name>:plan to plan this task first.

See Quick Start and the Command Reference for complete installation and maintenance instructions.

How the Installed Workflow Runs a Task

Before implementation, plan defines the goal, scope, approach, and validation requirements, while ground gathers the necessary evidence from code, documentation, issues, and tests. Once the proposal is accepted, lock writes and locks the Plan files.

During implementation, execute completes one accepted task, runs its validation, and records delivery evidence. showhand continues through the remaining locked tasks and stops at a blocker or failed validation gate.

When delivery evaluation is enabled, reconcile checks whether the task requirements were met and evaluates the achieved engineering quality. rework turns confirmed findings into locked rework requirements that go through implementation and validation again.

Every skill applies the same Profile where its standards matter, so planning, repository evidence, implementation, validation, delivery proof, and quality evaluation use one consistent project standard.

You choose the workflow name. If it is named backend:

• a plugin exposes backend:plan and backend:execute;
• a direct skill bundle exposes backend-plan and backend-execute.

Real Artifacts and Run Evidence

This simplified excerpt comes from a real Forma development plan:

Goal:
  Apply project standards consistently across planning, implementation,
  validation, and delivery evaluation.

Constraints:
  Preserve the existing workflow stages and Profile schema.
  Keep durable standards in the Profile and current-task requirements
  in the Plan files.

Validation:
  Run task-specific validation.
  Check generated artifacts for drift.
  Verify every affected bundle and plugin.

The corresponding Plan files, task list, and run evidence live in plans/issue-project-rule-workflow-quality/.

examples/profiles/ contains sanitized Profiles showing how projects express engineering standards, execution boundaries, validation depth, evidence requirements, and stop conditions.

Forma's own Profile lives at .forma/profile.yaml.

Current Support

Agent platform	Skills	Plugin
Codex	Supported	Supported
Claude Code	Supported	Supported
OpenCode	Supported	—

Forma ensures that an Agent can execute an Installed workflow. Whether it fully and accurately satisfies every workflow constraint still depends on the reasoning ability of the Agent and its underlying model.

From there, all we can do is pray that the Agent is smart—and doesn't suddenly lose half its IQ when it matters most.

Documentation

Document	What it covers
Quick Start	Generate, verify, and install a project workflow for the first time.
Concepts	Profile, Installed workflow, Plan files, and quality evaluation.
Plan files	How the current task records its goal, boundaries, validation, and evidence.
Profile Schema	How a Profile represents durable project standards.
Targets	Target behavior for Codex, Claude Code, and OpenCode.
Command Reference	Complete commands and maintenance instructions.

Apache-2.0 — see LICENSE