Working with plans

Start with a brief

Before writing a plan, the agent calls plan_brief with your task. Wayform returns relevant decisions, constraints, and related work. The agent combines that brief with the repository in front of it to write the plan.

Wayform supplies context. Your coding agent writes the plan, and you decide whether the approach is right.

Make the reasoning visible

A useful plan contains:

• A concrete goal.
• Constraints and inherited decisions, with their identifiers.
• The proposed approach and affected parts of the codebase.
• A checklist with evidence that each task is complete.
• Open questions that are answered or explicitly deferred.

The agent saves it with create_plan. It receives a number such as #12, making it easy to reference from the app, another agent, or a pull request.

Move through the lifecycle

Draft, active, and building plans can be revised. Each body edit creates a new version. Shipped and superseded plans are frozen.

Plans use a revision number to detect conflicting edits. If someone else changes the plan before your save, reload their version and reconcile rather than overwriting their work blindly.

Build with your agent

Run from the initialized product repo:

wayform build 12 --client claude

You can use cursor or codex instead of claude. If the current repo doesn’t resolve the right project, supply it explicitly:

wayform build 12 --client codex --project acme

The command opens your own agent interactively with the Wayform build skill. That workflow briefs implementation tasks, tracks checklist progress, and includes independent review and security review.

Check before the PR

plan_check returns the plan’s contract, inherited decisions, and a rubric. The agent assesses its diff against that contract and includes the conformance table in the PR description.

This is an agent assessment with evidence to inspect. It is not a guarantee that code is correct or secure, and it doesn’t replace your normal tests or review.

Ship and keep the decisions

Linked PR events can move a plan to building when the PR opens and to shipped when it merges. Use the plan link instruction installed by wayform init; the PR body identifies the plan, for example:

Wayform-Plan: #12

With the GitHub recording integration configured for the product repo, merging closes the loop: resulting decisions are recorded for future plans. Manual transitions are also available through the agent’s plan tools.

When recording decisions, include the reasoning. “Reuse GitHub identity because team access should extend the existing membership flow” will help future work more than “auth done.”

See plans in the repo

An admin can enable the optional plan mirror. It writes current plans to .wayform/plans/ at session start. That folder is gitignored; it is a readable view, not the source of truth. Revise plans through Wayform so version history stays intact.