# Agent Orchestration Protocol: AGENTS.md

## Workflow Lifecycle

```
[User Request]
      |
      v
[1. Requirements Analyst]  --> Creates/Refines Problem Statement & Acceptance Criteria
      |
      v
[2. Solution Architect]    --> Assigns next ID from specs/.spec-counter; creates
                                Technical Design & Schema in specs/active/SPEC-<id>-<short-name>.md
      |
      v
[User Approves Spec]       --> Spec Status changes from DRAFT to APPROVED (Frozen)
      |
      v
[3. Builder Agent]         --> Executes tasks step-by-step (Legacy Specialist or Modern Builder).
                                A post-freeze scope change goes through the REVISED amendment
                                flow in .devfoundry/skills/technical-spec.md, not a silent edit.
      |
      v
[4. QA Verifier]           --> Validates against Acceptance Criteria & Regression Matrix
      |
      v
[5. Process Improver]      --> Runs retrospective; logs lessons; escalates recurring
                                friction into proposed rule/skill/reference edits
      |
      v
[Archive Spec]             --> Moves spec to specs/archive/SPEC-<id>-<short-name>.md
```

## Agent Persona Routing Table

| Persona | Trigger / Scope | Primary Rule / Skill Reference |
| :--- | :--- | :--- |
| Requirements Analyst | Initial feature requests, bug reports, vague tickets | `.devfoundry/skills/spec-interview.md` |
| Solution Architect | Designing schemas, function signatures, multi-file changes | `.devfoundry/skills/technical-spec.md` |
| Legacy Specialist | Editing .asp, .vbs, .bas, .frm, .cls, .mdb, .accdb | `.devfoundry/rules/legacy-asp-vb6.md` |
| Modern Builder | Editing .cs, .php, .sql, Postgres, SQL Server scripts | `.devfoundry/rules/dotnet-csharp.md`, `.devfoundry/rules/php.md` |
| QA Verifier | Verifying completed implementation tasks | `.devfoundry/skills/regression-check.md` |
| Process Improver | Post-QA retrospective on any completed spec | `.devfoundry/skills/process-retrospective.md` |

## Collaboration Rules
1. **No Hallucinated Libraries:** Do not introduce third-party libraries/DLLs or modern framework features into legacy stacks unless specified in `.devfoundry/references/environments.md`. Exception: the RouteKit Classic ASP MVC framework (`.devfoundry/references/asp-classic-framework.md`) is the sanctioned framework for all ASP Classic web applications — use its conventions rather than treating it as an unapproved dependency.
2. **Schema Invariant:** Database modifications must specify fallback steps and preserve backward compatibility with existing legacy queries.
3. **Context Passing:** When adopting a role, explicitly reference the persona markdown file in `.devfoundry/personas/` and apply the relevant procedures in `.devfoundry/skills/`.
4. **Audit Gate:** Builder task checkboxes may be marked complete after their local verification passes, but a spec is only marked `COMPLETED` when the QA Verifier confirms all acceptance criteria pass without regression.
5. **Continuous Improvement Loop:** Every spec passes through the Process Improver before archiving. Lessons are appended to `.devfoundry/improvement-log.md`; friction that recurs 3+ times must be escalated into a proposed amendment to the relevant rule, skill, persona, or reference file, subject to user approval. This is how the workflow itself improves rather than repeating the same manual corrections across specs.
6. **Archive Reset Is Not Part of This Lifecycle:** Clearing `specs/archive/` (e.g. when this template is adopted to start a new project) uses `.devfoundry/skills/new-project-reset.md` and only ever runs on explicit request — never automatically, never as a substitute for the normal Archive step above.