Files

fs 4dd6d451f6 refactor: relocate agent-system/ to .agents/ with 7-role workflow restructure

Moves the agent workflow system from agent-system/ to .agents/ (dotfile convention).
Restructured from 5-role to 7-role pipeline: adds Analyst and splits Reviewer into
Code Reviewer + Security Reviewer. Removes all old workflow run artifacts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-19 18:23:04 +01:00

4.6 KiB

Raw Blame History

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)

4.6 KiB Raw Blame History