Auto Devflow

Start Devflow

Run a controlled devflow: the main agent stays the controller, each subagent owns one phase, and phase outputs are written to temporary handoff files before the next phase starts.

Use this when the user says things like "开始解决这个 issue", "start this issue", "fix this bug end-to-end", "实现这个功能", or asks for a multi-agent workflow rather than a single-agent edit.

Non-Negotiables

• The main agent owns scope, approvals, TodoWrite, git safety, and final reporting.
• Subagents do focused work only. Do not let a subagent silently broaden scope.
• Use handoff files as the shared memory. Do not rely on hidden subagent context.
• Run writable phases sequentially. Never run two coding subagents against the same checkout at the same time.
• Ask the user before destructive operations, branch changes, commits, or scope expansion.

Operating Modes

Pick a mode during Intake and record it in 00-context.md.

Relaxed Mode

Default for simple, low-risk tasks.

Use relaxed mode when:

• the request is small and localized
• the likely change touches a few files with obvious ownership
• failure impact is low and rollback is straightforward
• the agent has not already made repeated mistakes on this task

Relaxed flow:

Intake → Explore → Plan → Code → Review → Verify → Report

Plan review is optional. The main agent may self-check 02-plan.md instead of dispatching a separate reviewer.

Cautious Mode

Use cautious mode when the user says the task is hard, risky, subtle, or when the agent has already made too many mistakes. Also use it for public API changes, data/schema changes, security-sensitive code, concurrency, async lifecycle, rendering/event-loop bugs, or broad refactors.

Cautious flow:

Intake → Explore → Plan → Plan Review → User/Controller Gate → Code → Review → Verify → Report

Cautious mode adds a plan review before coding. Dispatch a read-only reviewer (plan or code-reviewer) to critique 02-plan.md and write 02-plan-review.md. Plan Review is a mandatory gate in cautious mode——coding must not start until every critical issue is fixed or explicitly accepted by the main agent/user. Historical evidence: Plan Review intercepted 9+ blocking issues across 3 major refactors (StageContext、ProviderAdapter、compact_v2) in 2026-07-16 alone.

Completion criterion: 00-context.md states Mode: relaxed or Mode: cautious, why that mode was chosen, and which gates are required.

Handoff Directory

Create one directory per devflow:

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

<title> 用任务标题的 kebab-case 形式（如 fix-auth-timeout、add-pagination），有 issue id 时附加 id。

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>

Completion criterion: a later subagent can start from the previous handoff file plus the original user request without guessing.

Flow

1. Intake

Clarify only if needed. If the user gave an issue id, URL, stack trace, or spec, capture it exactly in 00-context.md.

Write 00-context.md with:

• original request
• success criteria
• operating mode: relaxed or cautious, with reason
• constraints from the user and project memory
• current git branch/status summary
• explicit approval state for commits or branch changes

Stop and ask if success criteria or target issue is ambiguous.

2. Explore

Dispatch an explore subagent in read-only mode.

Prompt it to:

• inspect relevant files and tests
• identify execution paths and ownership boundaries
• find existing conventions
• write 01-explore.md
• not edit code

Completion criterion: 01-explore.md names likely files to touch, relevant tests, known traps, and at least one plausible implementation seam.

3. Plan

Dispatch a plan subagent in read-only mode, using 00-context.md and 01-explore.md.

Prompt it to:

• produce a small implementation plan
• identify risks and rollback points
• define verification commands
• write 02-plan.md
• not edit code

Completion criterion: 02-plan.md has ordered steps, exact files, verification commands, and a clear stop/ask condition.

3.5. Plan Review

In relaxed mode, the main agent self-checks the plan for missing files, missing verification, scope creep, and unsafe operations. Write the self-check result into 02-plan.md or 00-context.md.

In cautious mode, dispatch a read-only plan reviewer before coding.

Prompt it to:

• read 00-context.md, 01-explore.md, and 02-plan.md
• challenge assumptions and hidden risks
• check that planned files and tests match the exploration findings
• identify scope creep, missing rollback, missing verification, and unsafe steps
• write 02-plan-review.md
• not edit code

Completion criterion: relaxed mode has a recorded self-check; cautious mode has 02-plan-review.md with APPROVED or a concrete issue list. If the reviewer finds critical issues, update 02-plan.md and repeat plan review before coding.

If the plan changes user-visible behavior, public APIs, data format, migrations, or architecture boundaries, present the plan summary to the user and wait for approval before coding.