Auto Devflow

Adaptive Devflow

Run the lowest sufficient devflow. The main agent remains the controller, but the amount of ceremony and delegation scales with task complexity:

lite < normal < pro < max < ultra

A lower mode may absorb a phase into the controller; it must not discard that phase's responsibility. For example, lite replaces a review subagent with a controller self-review, not with no review.

Non-Negotiables

These rules apply in every mode:

• The main agent owns scope, mode selection, approvals, TodoWrite, git safety, and final reporting.
• Use the smallest safe mode, but never trade away correctness, security, or required verification to save steps.
• Subagents do focused work only. Do not let a subagent silently broaden scope.
• Run writable phases sequentially. Never run two coding agents against the same checkout at the same time.
• Ask before destructive operations, branch changes, commits, or scope expansion. Never commit unless the user explicitly requested it.
• Inspect the actual diff and collect verification evidence before claiming completion.
• Treat user-visible behavior, public contracts, persistent data, security boundaries, and irreversible operations as risk signals, regardless of file count.

Select a Mode

Accept an explicit mode in forms such as:

/auto-devflow lite fix the typo
/auto-devflow pro implement issue 123
use max mode for this migration

Selection order:

1. If the user explicitly names a mode, use it as the requested mode.
2. Scan scope, uncertainty, coupling, reversibility, and verification burden.
3. Raise the requested mode to any applicable safety floor.
4. If no mode was named, choose the lowest mode whose conditions all fit.
5. Perform only enough initial inspection to validate the choice before coding.

Do not ask the user to choose a mode when the evidence is sufficient. State the decision in one line:

Mode: pro — cross-module behavior needs dedicated exploration and independent review.

For lite and normal, record this line in the visible plan or TodoWrite. For pro, max, and ultra, also record it in 00-context.md, including required and omitted gates.

Mode Anchors

File counts are indicators, not quotas. Ownership boundaries and risk dominate raw size.

Automatic selection uses this order after applying an explicit request and safety floors:

1. ultra when the task meets the ultra anchor.
2. max when any safety floor or max anchor applies.
3. lite when every lite condition is true.
4. pro when dedicated exploration/planning is needed or a meaningful boundary is crossed.
5. normal for the remaining bounded work.

This makes normal the fallback, not the universal default.

Safety Floors

Use at least max for behavioral changes involving any of these:

• authentication, authorization, secrets, privacy, or other security boundaries
• schema/data migrations, destructive transforms, or difficult rollback
• public API, wire protocol, persisted serialization, or compatibility contracts
• concurrency, async lifecycle, event-loop ownership, or race-sensitive state
• cross-crate or cross-service architecture boundaries with user-visible impact

Use ultra when a max-level task also has multiple independent subsystems, rollout/rollback workstreams, or competing designs that need parallel evidence. Do not choose ultra merely because a task is described as “large.”

If the user requests a mode below a safety floor, state the override and reason before coding. A user may always request a higher mode.

Reclassification

Mode selection is not permanent:

• Escalate immediately when new scope, uncertainty, or risk appears.
• An auto-selected mode may move down before coding if inspection disproves the higher-risk signal.
• Never silently downgrade an explicitly requested mode.
• Do not downgrade after coding merely to remove an outstanding review or verification gate.
• Record every change as Mode: old → new — reason; update 00-context.md when it exists.
• If escalation adds user-visible cost, architecture decisions, or approval gates, tell the user before proceeding.

Completion criterion: the chosen mode, reason, safety floor, required phases, and deliberately absorbed/omitted phases are unambiguous.

Strategy Matrix

A phase shown as controller-owned is still required. Do not dispatch an agent merely to make the workflow look larger.

Handoff Policy

lite and normal do not create .peri/plans/ ceremony. In normal, the coder's returned result must state changed files, commands, residual risks, and blockers; the controller verifies those claims against the diff.

For pro, max, and ultra, create one directory per devflow:

.peri/plans/<title>/
  00-context.md
  01-explore.md
  02-plan.md
  02-plan-review.md       # max/ultra
  03-code.md
  04-review.md
  05-verification.md

Use a kebab-case task title and append an issue id when present. ultra may add lens-specific files such as 01-explore-tests.md or 02-plan-review-security.md, but it must synthesize them into the canonical files above before the next phase.

Each handoff file must contain:

# <Phase> Handoff

## Goal
<one sentence>

## Scope
<in scope / out of scope>

## Findings or Changes
<phase-specific details>

## Files
<relevant file paths>

## Commands
<commands run and outcomes, or "not run">

## Open Questions
<none, or exact blockers>

## Next Prompt
<self-contained prompt for the next subagent>

Use handoff files whenever two or more subagents exchange work. Read-only subagents return the complete handoff content to the controller; the controller writes it to the canonical file before dispatching the next phase. Completion criterion: the next subagent can proceed from the canonical handoffs plus the original request without hidden context or guessing.

Flow

1. Intake and Mode Gate

For every mode:

• capture the original request, success criteria, and user constraints
• read applicable repository guides, standards, active specs, and neighboring code
• inspect current branch/status and identify overlapping dirty changes
• select and announce the mode before dispatching subagents or editing
• identify approvals required for commits, branch changes, destructive work, or scope expansion

For pro+, write 00-context.md with the above plus the mode rationale, safety floor, required gates, and absorbed/omitted phases.

Stop and ask only when the target, success criteria, or a required user decision remains ambiguous. Do not use mode selection itself as a reason to ask when it can be inferred.

Completion criterion: the task has a checkable success condition and can safely enter its selected flow.

2. Explore

Scale exploration by mode:

• lite: the controller reads the target and enough surrounding code to confirm the obvious seam and test.
• normal: the controller performs bounded searches, reads neighboring conventions, and prepares a self-contained coder prompt.
• pro: dispatch one read-only explorer to inspect execution paths, ownership, tests, conventions, and risks; the controller writes its returned handoff to 01-explore.md.
• max: use a dedicated explorer; require explicit contract, rollback, regression, and dirty-worktree findings, then have the controller write 01-explore.md.
• ultra: run two or three independent read-only lenses in parallel, such as architecture/behavior, tests/regressions, and safety/rollout. Give each lens a distinct question, then synthesize all evidence into 01-explore.md.

Parallelize only independent read-only work. If two streams need the same evolving result, sequence them instead.

Completion criterion: likely files, ownership boundaries, tests, known traps, and at least one implementation seam are known at the depth required by the selected mode.

3. Plan and Plan Review

• lite: state one to three implementation/verification steps inline. Do not create a plan file.
• normal: the controller writes a concise, self-contained coder prompt with exact scope and verification expectations.
• pro: dispatch plan using 00-context.md and 01-explore.md; the controller writes the returned handoff to 02-plan.md, then self-checks scope, files, safety, and verification.
• max: create 02-plan.md, then dispatch an independent read-only plan reviewer. The controller writes its verdict to 02-plan-review.md, which must say APPROVED or list concrete issues. Resolve every critical issue before coding.
• ultra: synthesize one canonical plan with slice boundaries, dependencies, rollback points, and verification ownership. Run independent plan-review lenses in parallel, then merge their verdicts into 02-plan-review.md. Resolve every critical issue before coding.

For max and ultra, the plan review is a mandatory gate. Present the plan summary to the user and wait when it changes user-visible behavior, public contracts, persistent data, migrations, architecture boundaries, or requires destructive work. Otherwise the controller may approve the gate after all critical findings are resolved.

Completion criterion: the coder can implement exact ordered slices without guessing, and every mandatory review gate is approved.