seaweedfs/sw-block/design/agent_dev_process.md

Agent Development Process

Date: 2026-03-30 Status: active Purpose: define the working split between sw, tester, and review/management roles so each phase and slice has a clear delivery path

Why This Exists

The project is now beyond pure exploration.

The expensive part is no longer only writing code. The expensive part is:

1. delivery
2. review
3. fixes
4. re-review

So the process must reduce repeated full-stack review and make each role responsible for a distinct layer.

Roles

manager

Primary role:

• phase/plan owner

Responsibilities:

1. define the phase/slice direction and scope
2. accept the planning package before coding starts
3. decide whether a carry-forward is acceptable or must become a gate
4. perform the final round review for overall logic, omissions, and product-path fit

architect

Primary role:

• plan and technical reviewer

Responsibilities:

1. review the plan before implementation starts
2. tighten algorithm wording, scope edges, and expectation framing
3. review technical correctness during implementation
4. review API/state/resource/fail-closed behavior
5. catch semantic drift, scope drift, and V1/V1.5 leakage

sw

Primary role:

• implementation owner

Responsibilities:

1. implement the accepted slice
2. state changed contracts
3. state fail-closed handling
4. state resources acquired/released
5. state carry-forward items
6. add or update tests

tester

Primary role:

• evidence owner

Responsibilities:

1. define what the slice must prove before implementation starts
2. maintain the failure-class checklist
3. define reject conditions and required test level
4. confirm that implementation claims are actually covered by evidence

Default Routine

Each slice should follow this order:

1. manager defines the plan direction
2. architect reviews and tightens the plan / algorithm / expectation framing
3. tester writes the expectation template
4. manager accepts the package and records it in the phase docs
5. sw implements and submits with the delivery template
6. architect reviews the technical layer until clean enough
7. tester performs validation and evidence closure
8. manager performs round-two review for overall logic and omissions

Urgent exception:

• if early work already shows major scope drift, protocol contradiction, or V1/V1.5 leakage, architecture review may short-circuit before implementation grows further

Delivery Template For sw

Each delivery should include:

1. changed contracts
2. fail-closed handling added
3. resources acquired/released
4. test inventory
5. known carry-forward notes
6. reuse note:
   • files updated in place
   • files used as references only
   • files copied and why

This template is required between:

1. implementation
2. implementation/fail-closed review

It should accompany the delivery before reviewers start detailed review.

Suggested format:

Changed contracts:
- ...

Fail-closed handling:
- ...

Resources acquired/released:
- ...

Test inventory:
- ...

Carry-forward notes:
- ...

Reuse note:
- ...

Phase Doc Usage

Use the three phase documents differently:

phase-xx.md

Use for:

1. current execution direction
2. current scope
3. current guardrails
4. current accepted status
5. current assignments

Keep it short and execution-oriented.

phase-xx-log.md

Use for:

1. detailed planning evolution
2. review feedback
3. carry-forward discussion
4. open observations
5. why wording or scope changed
6. slice-level reuse instructions:
   • update in place
   • reference only
   • copy is allowed

This document may be longer and more detailed.

phase-xx-decisions.md

Use for:

1. durable phase-level decisions
2. accepted boundaries that later rounds should inherit
3. gate decisions
4. decisions that should not be re-argued without new evidence

This document should stay compact and hold only the more important global decisions.

Expectation Template For tester

Before or at slice start, tester should define:

1. must-pass expectations
2. failure-class checklist
3. required test level for each behavior
4. reject conditions

tester should re-engage after technical review is mostly clean, to confirm final evidence closure before the manager's second-round review.

Suggested format:

Expectation:
- ...

Required level:
- entry path / engine / unit

Reject if:
- ...

Failure classes covered:
- ...

Review Checklist For architect

Review these first:

1. nil handling
2. missing-resource handling
3. wrong-state / wrong-kind rejection
4. stale ID / stale authority rejection
5. resource pin / release symmetry
6. plan/execute/complete argument correctness
7. fail-closed cleanup on partial failure

Failure-Class Checklist

This checklist should be kept active across phases.

Minimum recurring classes:

1. changed-address restart
2. stale epoch / stale session
3. missing resource pin
4. cleanup after failed plan
5. replay range mis-derived
6. false trusted-base selection
7. truncation missing but completion attempted
8. bounded catch-up not escalating

Process Rules

Rule 1: Do not wait until the end to define proof

Each slice should begin with a statement of:

1. what must be proven
2. which failure classes must stay closed

Rule 2: Do not let convenience wrappers silently become model truth

Any convenience flow must be explicitly classified as:

1. test-only convenience
2. stepwise engine task
3. planner/executor split

Rule 3: Prefer evidence quality over object growth

New work should preferentially improve:

1. traceability
2. diagnosability
3. failure-class closure
4. adapter contracts

not just add:

1. more structs
2. more states
3. more helper APIs

Rule 4: Use V1 as validation source, not architecture template

Use:

1. learn/projects/sw-block/
2. weed/storage/block*

for:

1. constraints
2. failure gates
3. implementation reality

Do not use them as the default V2 architecture template.

Rule 5: Reuse reality, not inherited semantics

When later implementation reuses existing Seaweed / V1 paths:

1. reuse control-plane reality
2. reuse storage/runtime reality
3. reuse execution mechanisms

but do not silently inherit:

1. address-shaped identity
2. old recovery classification semantics
3. old committed-truth assumptions
4. old failover authority assumptions

Any such reuse should be reviewed explicitly as:

1. safe reuse
2. reuse with explicit boundary
3. temporary carry-forward
4. hard gate before later phases

Rule 6: Every substantial slice should declare reuse instructions

Before implementation grows, the slice package should state:

1. which existing files are expected to be updated in place
2. which existing files are reference-only
3. whether any copying is allowed and why

This helps prevent:

1. accidental scope growth
2. unclear ownership of old files
3. hidden semantic inheritance from V1/V1.5 paths

Current Direction

The project has moved from exploration-heavy work to evidence-first engine work.

From Phase 06 onward, the default is:

1. plan first
2. review plan before coding
3. implement
4. review technical layer
5. close evidence
6. do final manager review