usage.md

Command Reference

Chinese version: usage.zh-CN.md

Most users install Forma and ask their coding Agent to create or update the project workflow. This page documents the commands that the Agent guide orchestrates, along with the same commands for manual inspection and debugging.

Route Summary

Goal	Command
Create Forma-owned project paths	forma setup [PATH]
Inspect repository operability	forma doctor [PATH]
Diagnose project-rule coverage	`forma agent diagnose [--depth basic
Author or review durable rules	forma agent profile [--target <target>]
Create a reusable family from two projects	forma agent profile --joint <project-a> <project-b>
Extend a project from another project's Profile	forma agent profile --extend-from <source-profile> [--project <target>]
Compare one rule with stage methodology	forma agent stage <stage> [--target <target>]
Build direct skills	forma build bundle ...
Build plugin source	forma build plugin ...
Verify generated output	forma verify <path>
Check generated freshness	forma drift ...
Install verified local output	forma install ...
Convert provenance into a Profile candidate	forma profile adopt ...

Run forma <command> --help for the installed version's exact options.

forma setup [PATH]

Creates Forma's minimal project-owned paths. It applies by default, preserves existing files, and is idempotent.

forma setup
forma setup /path/to/repository
forma setup --dry-run

Setup creates only missing .forma/ and .forma/.gitignore paths. It does not invent project rules or write a Profile.

forma doctor [PATH]

Reports repository facts that affect Agent operability.

forma doctor
forma doctor /path/to/repository
forma doctor --human

Structured JSON is the default output for Agent guidance. --human renders a concise report for a person who wants to understand whether the current repository is ready for AI coding. Doctor does not choose the next Agent action or emit an executable handoff. Both forms include the Git revision and dirty state when available. Readiness requires verified operability facts, including validation commands whose owning tool or module exists; directory or keyword presence alone is not enough.

forma agent

diagnose, profile, and stage print complete executable Markdown contracts to stdout. The nested tool namespace contains JSON-only programmatic primitives called by those contracts.

Run forma agent for the complete Agent-facing route guide, then select the contract that matches the current job. forma agent --help shows only the CLI command inventory.

Command	Agent job
agent diagnose	Compare declared project rules with repository evidence, find drift, and identify code practices worth making durable.
agent profile	Turn supported durable findings into a reviewable Profile proposal.
agent fix-durable-source	Execute the durable-source fixes of a completed diagnosis (draft, per-finding approval, apply).
agent stage	Place one durable rule in the narrowest existing methodology field.
agent tool ...	Supply programmatic preflight facts to an active Agent contract.

Give the selected command's complete stdout to the Agent. Diagnosis calls its own preflight tools. Profile authoring can consume durable candidates from a valid current-session diagnosis. Stage placement is used when Profile authoring needs that specific comparison.

agent diagnose

forma agent diagnose
forma agent diagnose --depth deep

basic evaluates declared rules from Profile source, Agent instructions, project docs, validation configuration, and current decisions. deep also checks those rules against recent work evidence: the five most recent commits, the five most recent Agent sessions that worked on the repository when session history is readable, and programmatic facts. Its preflight runs forma doctor for Agent-operability facts.

A Profile on a legacy stage-key schema does not block diagnosis: Forma evaluates it through the known key migration, and bringing the Profile current is the first step of the forma agent profile update flow. An unrecognized or broken Profile is treated as no Forma source and reported as a profile-schema finding.

When a preflight report already exists, the Agent shows its recorded snapshot and asks the user to choose reuse or rerun. It recommends reuse only for clean same-HEAD evidence and recommends rerun for dirty, changed, or unknown evidence. Every result declares its depth, snapshot and reuse decision, resolved Profile sources, inspected rule areas, work evidence used, exclusions, and separate conclusions for rule coverage and rule compliance in recent work.

The human-facing conclusion gives each finding one clear next action:

• add a supported durable practice to the Profile;
• correct drift or errors in existing project rule files;
• fix the code according to current project rules;
• define the reason and scope for an accepted exception;
• settle a missing project rule, ownership boundary, or engineering tradeoff.

Durable-rule findings include a Candidate Principle, evidence, durability, workflow impact, and the question that must be settled before Profile authoring. Diagnosis leaves Profile field placement and YAML authoring to agent profile. Internal route metadata connects those two contracts while the report keeps the next action readable.

agent profile

forma agent profile
forma agent profile --target codex
forma agent profile --joint <project-a> <project-b> [--family <name>] [--target codex]
forma agent profile --extend-from <source-project>/.forma/profile.yaml [--project <target-project>] [--family <name>] [--target codex]

Produces the contract for evidence-backed Profile authoring and review. The Agent reuses a valid current-session diagnosis instead of repeating repository analysis, then returns a Profile YAML Proposal and Profile Review Packet before writing durable source. It cannot make unresolved diagnosis content more specific.

--joint diagnoses two selected repositories together and proposes a family with one shared layer and one project layer per repository. --extend-from uses the explicitly selected source .forma/profile.yaml or .forma/profile-ref.yaml as the baseline for the target; --project defaults to the current directory. Passing the source project directory or another YAML file is rejected. The two operations are mutually exclusive. --project applies only to --extend-from, and --family applies only to a multi-project operation. A supplied family name must use lower kebab-case, for example payments-platform. --target accepts codex, claude-code, opencode, pi, or dsh as Agent context; it does not restrict the reusable Profile source to one output target.

Both commands emit Agent instructions only. The Agent must show the rule classification and complete write set, stop on destination conflicts, and get approval before writing. It copies accepted rules and resources into ~/.forma/profiles/<family>/; it never deletes, moves, or replaces an existing .forma/profile.yaml or its resources. Each shared and project layer has an independent profile.id and bundle.name and can be passed directly to forma build. Projects can keep building .forma/profile.yaml or explicitly choose the added .forma/profile-ref.yaml.

For example, these are separate build choices, not one combined stack:

forma build bundle --target codex --profile .forma/profile.yaml --output /tmp/local-workflow
forma build bundle --target codex --profile .forma/profile-ref.yaml --output /tmp/shared-workflow
forma build bundle --target codex --profile ~/.forma/profiles/<family>/shared.yaml --output /tmp/shared-layer
forma build bundle --target codex --profile ~/.forma/profiles/<family>/projects/<project-key>.yaml --output /tmp/project-layer

agent stage

forma agent stage plan
forma agent stage review --target claude-code

Supported stage identities are plan, inspect, finalize, execute, showhand, review, and rework. The contract compares a project-specific candidate rule with existing methodology and places a real addition in the narrowest Profile field. These are internal Profile stage keys; the Installed workflow keeps its configured skill names such as plan, execute, and review.

forma build bundle

forma build bundle \
  --target codex \
  --profile .forma/profile.yaml \
  --output /tmp/project-workflow-codex

Options:

• --target codex|claude-code|opencode|pi|dsh is required.
• --output <dir> is required.
• --profile <file> selects reviewed project source; omitting it builds the generic Plan-First workflow.
• --methodology <dir> overrides methodology source for development.
• --format human|agent|json controls the build report.

For reusable Profile-backed installs, use forma reinstall; it owns temporary generation, drift, verification, target refresh, visibility, and cleanup.

forma build plugin

forma build plugin \
  --target codex \
  --profile .forma/profile.yaml \
  --output /tmp/project-plugin

Plugin targets are codex and claude-code. Profile, methodology, output, and report-format options follow build bundle.

After verification, forma install creates or refreshes a stable local Forma Marketplace, registers it with the target CLI, installs the plugin selector, and verifies that the target reports it as visible:

forma install --target codex /tmp/project-plugin
forma install --target claude-code --scope project /tmp/project-plugin

Codex plugin install does not accept --scope. Claude Code plugin install requires --scope user|project. Neither plugin root is copied into a direct skills directory.

forma verify PATH

forma verify /tmp/project-workflow-codex
forma verify --json /tmp/project-workflow-codex

Verification checks generated bundles and plugin source for structure, target metadata, provenance, and methodology contracts.

forma reinstall

forma reinstall \
  --profile .forma/profile.yaml \
  --target codex \
  --artifact plugin

forma reinstall \
  --profile .forma/profile.yaml \
  --target claude-code \
  --artifact plugin \
  --scope project \
  --marketplace existing-team-marketplace

The command runs temporary build, drift, verify, install, target visibility, and cleanup. Bundle targets require --scope user|project. Claude Code plugins also require scope; Codex plugins reject it.

When --marketplace is omitted, Forma uses or creates its managed forma Marketplace. An explicitly named Marketplace must already be registered with the target CLI; a missing explicit Marketplace is an error and is never created.

forma drift [ARTIFACT_PATH]

forma drift /tmp/project-workflow-codex --profile .forma/profile.yaml
forma drift --release-surface
forma drift /tmp/project-workflow-codex --json

Use --profile when the artifact should match specific Profile source. Use --release-surface for Forma's committed dist/. With no Profile source, drift reports base-origin freshness only.

forma install PATH

forma install \
  --target codex \
  --scope project \
  /tmp/project-workflow-codex

--target codex|claude-code|opencode|pi|dsh is required. Direct skills and bundles require --scope user|project; Claude Code plugins also require scope, while Codex plugins reject it. --marketplace <name> selects an already registered Marketplace; omit it to use or create the managed forma Marketplace. Use --replace only when replacement is intended.

Install accepts verified local direct skills, skill bundles, Codex plugins, and Claude Code plugins. It does not download URLs.

forma profile adopt ARTIFACT_PATH

forma profile adopt /tmp/project-workflow-codex \
  --output /tmp/project-profile-candidate

Options include --profile-id, --replace, and --json. Adoption converts Forma provenance into a candidate Profile package. Regenerate and compare the candidate, then promote it only after human review.

Typical Maintenance Loop

Tell the Agent:

Update the Forma workflow for this project.

The Agent guide orchestrates the relevant parts of this maintenance path:

repository preflight → Agent diagnosis → Profile proposal
                     → build → verify → install → visibility check

Each target is regenerated from the same project Profile.

Installed CLI Boundary

Normal commands use runtime assets packaged with forma-cli; the installed CLI does not depend on this source checkout. --methodology is a development override.

Related Docs

• Quick Start
• Concepts
• Profile Schema
• Targets
• Verifier