Forma: An Open-source Framework for Generating Structured Task Contracts for AI Coding Agents

Forma is an open-source project that transforms team engineering practices into concrete task contracts, enabling AI coding agents (like Codex, Claude Code) to declare compliance with rules before execution and provide verifiable execution traces. It introduces the Plan-First paradigm to address the pain point of AI agents not truly following team rules (lack of verifiability/traceability). Key benefits include improved traceability, constraint, reviewability, and team knowledge accumulation.

With AI coding agents widely used in software development, a core issue arises: how to make AI not just "read" but "follow" team rules? Traditional documentation only gives vague promises (e.g., "I will follow rules") without verifiability or traceability. Forma was created to solve this by proposing the Plan-First workflow: converting team engineering principles into specific task contracts so AI agents explicitly state their work approach before execution and provide a reviewable evidence chain during execution.

Task Contract: Transforms abstract team rules into concrete commitments for specific tasks, answering key questions like evidence basis, modification boundaries, verification steps, evidence records, and stop conditions. Three-layer Architecture: 1. Profile (YAML file storing team engineering principles like coding standards, review processes); 2. Harness (toolkit generated from Profile, including skills like forma-plan, forma-ground, forma-lock, forma-execute, forma-showhand);3. Task Contract (per-task commitment stored in plans/issue-/ directory with execution plan and verification requirements).

The workflow includes four steps: 1. Generate Toolkit: Use forma create-bundle to generate a skill package for AI agents (e.g., Codex) from the team's Profile, then verify with forma verify. 2. Plan Phase: Start with forma-plan to clarify task goals, scope, constraints without executing work.3. Evidence Collection & Lock: Use forma-ground to collect relevant evidence (code, docs, tests), then forma-lock to materialize the plan into plan.md and tasks.md (lock the contract).4. Execute & Verify: Use forma-execute to run tasks with verification and record evidence; use forma-showhand to continue multiple tasks within the locked plan until blocked or needing human input.

1. Traceability: Breaks workflow into clear phases (plan, evidence, lock, execute, verify) with explicit inputs/outputs and records, reducing "black box" issues.2. Constraint: Profile-defined rules control AI's behavior (e.g., prohibit modifying core config files, mandatory review for DB changes).3. Reviewability: Materialized contracts (plan.md, tasks.md) enable pre-execution plan review and post-execution result verification.4. Knowledge Accumulation: Profile evolves with the project, helping new members understand team practices and AI agents adapt to latest rules.

Forma is in early stages. Limitation: It provides a control interface but can't guarantee AI agents follow the generated skills (depends on underlying models and host environment). Future directions: Simplify Plan-First workflow installation; lower Profile writing threshold; improve toolkit verification; add real process examples. Note: Forma uses Plan-First for its own development (dogfooding), with its source code Profile in profiles/forma-self/.

Forma is suitable for:1. Large Team Collaboration: Unified Profile ensures consistent engineering standards across AI agents.2. Critical System Development: Boundary control and verification provide extra security for core code.3.** Compliance Requirements**: Evidence collection and records meet detailed development process documentation needs.4.** Knowledge Transfer**: Encoding senior engineers' experience into Profile helps new members get started quickly.

Forma represents a new AI-aided development paradigm: from "AI free play" to "AI working under clear constraints". This isn't limiting AI's capabilities but making them more reliable via contracts and verification. As AI coding agents become more prevalent, control frameworks like Forma will grow in importance—it's both a technical tool and an engineering mindset (balancing efficiency with quality/control). It's a recommended solution for tech leads looking to integrate AI coding agents into team workflows.