Create a planner handoff

The planner workflow asks the general model for a structured plan and passes a handoff to the code specialist. A generated plan is a proposal; it does not authorize file changes, deployment, or shell execution.

The handoff contract

The versioned template is scripts/handoff-schema.yaml. Its major fields are:

Field	Required meaning
objective, task_type	What should be achieved and what kind of work it is
constraints	Boundaries the executor must preserve
prerequisites	Required packages or binaries and their installation commands
acceptance_criteria	Observable conditions for success
tasks	Concrete files, actions, verification, and risks
handoff	Self-contained instructions for the executor

Generate a plan without executing it

From the development repository root in WSL Bash, with the backend running and the helper configured to use your lab key:

mkdir -p /tmp/devai
bash scripts/plan_exec.sh --plan-only "Plan a small Python client for the existing query API; do not change the backend."

The default schema mode writes the plan to /tmp/devai/current_plan.txt unless TMP_DIR overrides that location. Create that directory before the first call. Flags must precede the task text. Inspect the output before proceeding. Plan-only avoids the script’s execution phase, but still sends requests and writes its plan/log files. The CLI walkthrough covers phase selection and model overrides.

For a draft followed by schema compression, the script also supports PLAN_STYLE=twopass. It makes additional model calls and may exceed the committed API input limit, so first establish that a short one-pass plan succeeds.

The template currently uses multiline scalar fields for constraints, prerequisites, acceptance_criteria, files, actions, verify, risks, and handoff; tasks is a list. Do not mistake bullet-looking text within a scalar for a YAML list. Use the actual versioned template when writing a validator or consuming the output.

Review the plan

1. Supply the task and real repository context. Do not expect the model to know local files automatically.
2. Inspect the planner script’s help and choose its plan-only mode before experimenting.
3. Compare output with the schema template. YAML-looking text alone is not validation.
4. Check every referenced file, service, command, and assumption.
5. Approve execution separately and inspect resulting diffs and test evidence.

The script includes draft, schema, and two-pass planning logic. Its generated request can exceed the committed API query limit for large prompts. Shorten context or use a separately reviewed backend change; this documentation update does not change that limit.

Boundaries

Prompt metadata such as requires_human_gate affects routing/context. It is not an independently enforced permission system. The operator or agent harness must enforce approvals.

Next: Engineering framework or experimental training.