# <Project Name> Agent Protocol

本项目使用 `docs/agent-collaboration-kit/` 中的多 Agent 协作规范。本文填入本项目自己的路径、命令和权限边界。

## Project Overview

- Project: `<project_name>`
- Stack: `<tech_stack>`
- Main app command: `<run_command>`
- Base URL: `<base_url>`
- Task board: `tasks.yaml`

## Roles

| Role | Responsibility | Validation |
|------|----------------|------------|
| Product/Test Coordinator | Defines requirements, writes task evidence, runs black-box retest, marks verified | Browser/API/integration tests |
| Developer Worker | Implements fixes/features, writes unit tests, runs build and white-box tests | Unit tests/build/local run |

## Path Scoping

| Path | Product/Test | Developer | Notes |
|------|:------------:|:---------:|------|
| `<spec_paths>` | R/W | Read-only | Product specs, API docs, plans |
| `<integration_test_paths>` | R/W | Read-only | Browser/API regression |
| `<test_records_path>` | R/W | Read-only | Run records |
| `<source_paths>` | Read-only | R/W | Application source |
| `<unit_test_paths>` | Read-only | R/W | Unit tests |
| `<shared_config_templates>` | Read-only | R/W | Committable config templates |
| `<local_config_paths>` | Read-only | Read-only | Local secrets/overrides |
| `tasks.yaml` | R/W | Limited R/W | Product/Test owns `verified`; Developer may write implementation status/evidence |

## Commands

Developer verification:

```bash
<unit_test_command>
<build_command>
<local_run_command>
```

Product/Test verification:

```bash
<preflight_command>
<api_smoke_command>
<browser_regression_command>
```

## Task Status Lifecycle

```text
open -> dispatched -> fixed_by_dev -> retesting -> verified
```

Failure states:

```text
blocked
failed_retest
leftover
```

Rules:

- `worker_done` is not completion. Product/Test must retest before `verified`.
- Each task can be dispatched to Developer at most 3 rounds.
- If still failing after 3 rounds, mark `leftover`, record evidence, and continue the next task.
- Do not commit or push unless the user explicitly asks.

## Orca Closed Loop

Use `docs/agent-collaboration-kit/orca-closed-loop.md` when the user asks for supervised implementation/retest loops.

Default loop:

```text
Product/Test records failure in tasks.yaml
  -> Orca task-create
  -> dispatch Developer Worker
  -> wait worker_done/escalation/decision_gate
  -> Product/Test retests
  -> verified / failed_retest / leftover
```

## Definition Of Done

A task is done only when:

- Developer reports files modified and verification commands.
- Product/Test verifies in the correct worktree/service.
- Relevant build/test/browser/API checks pass.
- `tasks.yaml` contains final evidence.