Skip to content

usage.md

Latest commit

 

History

History
275 lines (209 loc) · 9.97 KB

usage.md

File metadata and controls

275 lines (209 loc) · 9.97 KB
Raw

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
Measure diagnosis scope and budget for an Agent forma agent tool diagnosis-budget [PATH]
Author or review durable rules forma agent profile [--target <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 or forma agent --help for the Agent-facing route guide, then select the command that matches the current job:

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 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 inspects representative code reality through the shared engineering-quality model. Its preflight combines forma doctor with forma agent tool diagnosis-budget. Work below the rough token notice threshold starts directly; broader work first reports approximately how many tokens it may use, then also starts directly. The estimate makes scale visible and does not limit the evidence needed for a well-supported diagnosis.

When a paired 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/code areas, exclusions, and separate conclusions for rule coverage and implementation quality.

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 tool diagnosis-budget

forma agent tool diagnosis-budget
forma agent tool diagnosis-budget /path/to/repository

Emits JSON-only measurements of the active file inventory, rule material, languages, structural areas, the resolved Profile include stack, exclusions, and rough token ranges for Basic, default Deep, and full-repository diagnosis. The ranges use repository structure, rule material, prior run calibration, and host overhead. The command measures repository structure; the diagnosis contract uses those facts when it plans semantic inspection and makes findings. Resolved Profile sources include per-file and total line counts so the Agent can prove that Profile evidence is complete. notice_threshold_tokens decides only whether the Agent emits a cost notice. Below it, diagnosis runs directly. Above it, the Agent states an approximate range and reason, then runs without asking or waiting. The estimate is not an execution cap; evidence sufficiency determines when diagnosis is complete.

agent profile

forma agent profile
forma agent profile --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.

agent stage

forma agent stage shape
forma agent stage hone --target claude-code

Supported stage identities are shape, gauge, seal, pour, flow, hone, and mend. 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 reconcile.

forma build bundle

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

Options:

  • --target codex|claude-code|opencode 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, keep a Profile-local reinstall-workflow.sh that covers generation, drift, verification, target refresh, and final visibility.

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, install Codex plugins through Codex marketplaces or the plugin UI. Install Claude Code plugin roots through forma install.

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 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

Required options are --target codex|claude-code|opencode and --scope user|project. Use --replace only when replacement is intended.

Install accepts verified local direct skills, skill bundles, and Claude Code plugin roots. It does not download URLs or install Codex plugin source.

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