DevFoundry/AGENTS.md

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.
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.