126 lines
4.6 KiB
Markdown
126 lines
4.6 KiB
Markdown
|
# Agent Workflow
|
||
|
|
|
||
|
|
Last updated: 2026-03-19
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
This project uses a 7-role workflow for issue and feature delivery.
|
||
|
|
|
||
|
|
```
|
||
|
|
Analyst → Planner → Executor → Code Reviewer ──┐
|
||
|
|
├→ Finalizer
|
||
|
|
Security Reviewer ──────┤
|
||
|
|
Acceptance Tester ───────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
Primary goals:
|
||
|
|
- Front-load context gathering (Analyst) so downstream roles start informed
|
||
|
|
- Separate code quality review from security review for focused attention
|
||
|
|
- Explicit guard IDs (`GR-*`), gate IDs (`QG-*`), and success criteria (`SC-*`) across all roles
|
||
|
|
- Fast retry loop from reviewers back to executor
|
||
|
|
|
||
|
|
Source of truth:
|
||
|
|
- Guard catalog (22 guards): `.agents/checks/guard-catalog.json`
|
||
|
|
- Quality gates (9 gates): `.agents/checks/quality-gates.json`
|
||
|
|
- Contracts: `.agents/contracts/`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Roles
|
||
|
|
|
||
|
|
### Analyst
|
||
|
|
- **Input:** issue description or feature request
|
||
|
|
- **Output:** `analysis.json` (see `.agents/contracts/analyst.schema.json`)
|
||
|
|
- Gathers context: affected layers, files, patterns, tests, security surface
|
||
|
|
- Does NOT propose solutions — only structures facts for the Planner
|
||
|
|
|
||
|
|
### Planner
|
||
|
|
- **Input:** `analysis.json`
|
||
|
|
- **Output:** `plan.json` (see `.agents/contracts/planner.schema.json`)
|
||
|
|
- Defines scope, guard selection, success criteria, implementation steps, risks
|
||
|
|
- References concrete file paths from analysis — does not re-explore codebase
|
||
|
|
|
||
|
|
### Executor
|
||
|
|
- **Input:** approved `plan.json`
|
||
|
|
- **Output:** `execution-report.json` (see `.agents/contracts/executor.schema.json`)
|
||
|
|
- Implements plan, runs quality gates, provides guard evidence
|
||
|
|
|
||
|
|
### Code Reviewer
|
||
|
|
- **Input:** code diff + `execution-report.json`
|
||
|
|
- **Output:** `review-code.json` (see `.agents/contracts/reviewer-code.schema.json`)
|
||
|
|
- Scope: architecture, conventions, testing, UI standards (13 guards)
|
||
|
|
- Guards: `GR-CORE-*`, `GR-TEST-*`, `GR-UI-*`
|
||
|
|
|
||
|
|
### Security Reviewer
|
||
|
|
- **Input:** code diff + `execution-report.json`
|
||
|
|
- **Output:** `review-security.json` (see `.agents/contracts/reviewer-security.schema.json`)
|
||
|
|
- Scope: authz, tenant scope, CSRF, input validation, crypto, file storage (9 guards)
|
||
|
|
- Guards: `GR-SEC-*`
|
||
|
|
- Any `critical` or `high` finding forces `fail` verdict
|
||
|
|
|
||
|
|
### Acceptance Tester
|
||
|
|
- **Input:** code diff + `plan.json`
|
||
|
|
- **Output:** `review-acceptance.json` (see `.agents/contracts/reviewer-acceptance.schema.json`)
|
||
|
|
- Verifies each `SC-*` success criterion is met
|
||
|
|
|
||
|
|
### Finalizer
|
||
|
|
- **Input:** `review-code.json` + `review-security.json` + `review-acceptance.json`
|
||
|
|
- **Output:** `finalize.json` (see `.agents/contracts/finalizer.schema.json`)
|
||
|
|
- All three reviews must pass. CI must be green. Otherwise: hold.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## State Machine
|
||
|
|
|
||
|
|
```
|
||
|
|
analyzed → planned → executing → reviewing → finalize → done
|
||
|
|
↑ |
|
||
|
|
└────────────┘ (on any FAIL)
|
||
|
|
```
|
||
|
|
|
||
|
|
The reviewing state runs Code Reviewer, Security Reviewer, and Acceptance Tester.
|
||
|
|
If any reviewer returns `FAIL`, state goes back to `executing` with explicit findings.
|
||
|
|
|
||
|
|
## Handover Artifacts
|
||
|
|
|
||
|
|
| Role | Artifact |
|
||
|
|
|---|---|
|
||
|
|
| Analyst | `analysis.json` |
|
||
|
|
| Planner | `plan.json` |
|
||
|
|
| Executor | `execution-report.json` |
|
||
|
|
| Code Reviewer | `review-code.json` |
|
||
|
|
| Security Reviewer | `review-security.json` |
|
||
|
|
| Acceptance Tester | `review-acceptance.json` |
|
||
|
|
| Finalizer | `finalize.json` |
|
||
|
|
|
||
|
|
## Fail Loop Rule
|
||
|
|
|
||
|
|
No free-text "please improve". Every fail must include:
|
||
|
|
- `id`
|
||
|
|
- `severity`
|
||
|
|
- `file`
|
||
|
|
- expected fix
|
||
|
|
|
||
|
|
## Guard Assignment
|
||
|
|
|
||
|
|
Guards are split by reviewer role (see `reviewer` field in guard-catalog.json):
|
||
|
|
|
||
|
|
**Code Reviewer** (13 guards): GR-CORE-003, GR-CORE-007, GR-CORE-010, GR-CORE-011, GR-CORE-012, GR-TEST-001, GR-TEST-002, GR-UI-014, GR-UI-LIST, GR-UI-DETAIL, GR-UI-A11Y, GR-UI-I18N, GR-UI-REUSE
|
||
|
|
|
||
|
|
**Security Reviewer** (9 guards): GR-SEC-001 through GR-SEC-009
|
||
|
|
|
||
|
|
## What automated tests already enforce
|
||
|
|
|
||
|
|
The following concerns are covered by QG-001/QG-003/QG-004 and do NOT need manual guard review:
|
||
|
|
- Layering boundaries (CoreStarterkitContractTest)
|
||
|
|
- No direct service instantiation in pages (structural rg checks)
|
||
|
|
- No superglobals in pages (architecture tests)
|
||
|
|
- PSR-4 namespace alignment (autoloader + QG-003)
|
||
|
|
- PHP code style (QG-006)
|
||
|
|
- Module namespace isolation (ModuleStructureContractTest)
|
||
|
|
- Module UI via slots only (NoBookmarksHardcodingTest, NoAddressBookHardcodingTest)
|
||
|
|
- Runtime fingerprint (web/index.php fail-fast)
|
||
|
|
- Repository sanitizeLimitOffset (RepositoryInterfaceContractTest)
|
||
|
|
- List init standard, legacy filter toggle, template RBAC (architecture tests)
|
||
|
|
- Component lifecycle contract (architecture tests)
|