Skip to content

quick-start.md

Latest commit

 

History

History
168 lines (122 loc) · 5.77 KB

quick-start.md

File metadata and controls

168 lines (122 loc) · 5.77 KB
Raw

Quick Start

Chinese version: quick-start.zh-CN.md

The shortest path is to install Forma and ask your coding Agent to review the repository with the forma command. The Agent guide chooses the next CLI contract.

1. Install Forma

pipx install forma-cli

2. Ask The Agent To Review The Repository

Tell the Agent:

Use the forma command and follow its instructions to analyze the current project.

The Agent will:

  1. load the Forma Agent guide and run its read-only diagnosis;
  2. report the repository findings and recommend the next action;
  3. continue to a project-owned Profile only when you choose to create or update the project workflow;
  4. generate, verify, and install the workflow only after the Profile review.

When you continue to generation, you choose the workflow name. Forma can generate direct skills for Codex, Claude Code, OpenCode, pi, and DeepSeek Harness, as well as plugin output for Codex and Claude Code.

3. Use The Installed Workflow

For a new task, tell the Agent:

Use <workflow-name> for this task.

The Agent will use the workflow skills as the task progresses. To choose the planning entry point explicitly, use:

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

Plugins expose qualified names such as backend:plan. Direct skill bundles expose names such as backend-plan.

Before implementation, the Agent explains how the project standards apply to this task. The workflow then writes and locks:

  • plans/issue-<id>/plan.md: goal, scope, approach, project constraints, acceptance criteria, and shared validation;
  • plans/issue-<id>/tasks.md: accepted work units, dependencies, validation, and evidence responsibilities.

Implementation and delivery evaluation use these Plan files as the source of truth. Task runs can also record validation, snapshot, and completion evidence under plans/issue-<id>/runs/.

At delivery, the workflow binds validation results to the code snapshot. When review is enabled, it also reports whether the task passed and what engineering quality the implementation achieved.

What The Agent Runs

The one-sentence request above is the normal entry point. The Agent guide orchestrates the following Forma capabilities.

Diagnose The Repository

forma agent diagnose
forma agent diagnose --depth deep

The diagnosis contract tells the Agent how to run the programmatic preflight, which evidence to inspect, how to evaluate current rules against the codebase, and how to report its conclusions. Basic diagnosis focuses on declared project rules. Deep diagnosis also checks those rules against recent work evidence: the latest commits, the latest Agent sessions when readable, and programmatic facts.

The preflight uses:

forma doctor .

forma doctor returns structured repository-readiness facts. Add --format human to render the report for a person. The command collects programmatic facts; the Agent owns the engineering judgment.

If a report already exists, the Agent shows its repository snapshot and lets you choose whether to reuse it or rerun the preflight. A clean repository at the same commit is reusable evidence; a dirty or changed repository should be refreshed.

Create The Profile

forma agent profile --target codex

The Agent converts supported, durable findings into a Profile proposal. The proposal keeps long-lived project standards in the Profile and current-task requirements in Plan files. The Agent shows the proposed Profile changes before writing the project-owned YAML.

To reuse standards across repositories, choose one of these review-gated contracts instead:

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

--joint finds the genuinely shared rules across two repositories. --extend-from analyzes a target against the explicitly selected project .forma/profile.yaml or .forma/profile-ref.yaml; omitting --project uses the current directory. The Agent previews the family name, project keys, independent workflow names, and every file before writing anything. Existing Profile source is copied for reuse, never deleted or replaced.

Generate, Verify, And Install

For direct Codex skills, the underlying commands are:

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

forma verify /tmp/myproject-workflow

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

Codex and Claude Code plugin sources use forma install, which creates or refreshes a local Forma Marketplace and then invokes the target's Marketplace install commands. Direct bundles still install into target skill roots. See Targets for exact output and install boundaries.

Use forma reinstall to reproduce a reviewed Profile's generation, drift, verification, installation, visibility, and cleanup path. Plugin reinstall uses the managed forma Marketplace by default. Passing --marketplace <name> requires that Marketplace to be registered already.

Keep The Workflow Current

When project rules or code practices change, ask the Agent to update the Forma workflow. It will rerun the relevant diagnosis, propose Profile changes, and regenerate the affected Installed workflows from the same source.

Next Reads