feat: package AgentFlow SDLC roles as reusable role agents

[smota]

Epic: #115

Background & Problem Statement

AgentFlow SDLC roles reduce ambiguity, but most roles are currently implemented as phase labels and templates rather than reusable role-agent packages. To leverage more AI intelligence without increasing user cognitive load, each role needs a clear agent profile that can be run inline, as a sub-agent, in another session, or manually while producing the same evidence.

Proposed Solution

Package each SDLC role as a portable role-agent definition with goals, inputs, outputs, tools, mutation authority, collaboration triggers, escalation criteria, and required evidence. These role agents should remain subordinate to the opinionated SDLC and must not create new process branches.

Requirements

• Define a canonical role-agent package shape.
• Create role-agent definitions for analyst, architect, developer-planning, developer, tester, review, tech-writer, pr-readiness, product-manager/JTBD, and qa-expert.
• Define tool permissions per role.
• Define collaboration triggers per role.
• Define handoff input/output contract per role.
• Preserve single-agent use: parent can still perform all roles using these profiles.
• Preserve review read-only defaults and high-assurance human gates.

Technical Design

Suggested package shape:

agents/roles/<role>/
├── AGENT.md
├── checklist.md
├── inputs.md
├── outputs.md
├── tools.md
└── examples.md

Role-local intelligence panels may be defined for high-leverage phases:

• analyst: requirements gap scout, acceptance criteria scout;
• architect: risk scout, implementation strategist, testability scout, docs-impact scout;
• tester: coverage planner, failure analyst;
• review: security reviewer, maintainability reviewer, evidence auditor;
• pr-readiness: manifest auditor, issue-link auditor.

Feature Tracking

• Define role-agent package template.
• Add analyst role agent.
• Add architect role agent and advisory scout panel.
• Add developer-planning role agent.
• Add developer role agent.
• Add tester role agent and test intelligence loop hooks.
• Add review role agent and red-team panel hooks.
• Add tech-writer role agent.
• Add pr-readiness role agent and evidence-auditor hooks.
• Add product-manager/JTBD role agent.
• Add qa-expert sidecar package or align existing docs.

Acceptance criteria

• Each role has a reusable profile usable by humans, parent agents, and sub-agents.
• Role profiles say what not to do, not only what to do.
• Role profiles preserve role-pass and handover evidence.
• Harnesses can map role profiles to local subagents/sessions without redefining semantics.

Test plan

• Run pnpm format:check.
• Run pnpm test:workflow.
• Run package completeness check for role-agent files.

Workflow classification

• Profile: standard
• Risk: low
• Effort: high
• Change surfaces: docs, agent package, templates
• Review: self-review acceptable; human editorial review useful.

Agent-builder refinement

Role-agent packages must follow the agent-builder portable-agent model, not only phase-template docs.

Additional requirements

• Include role-level starter prompts or realistic invocation examples.
• Include activation triggers and explicit “must not activate when” rules for each role.
• Include current/target maturity notes for role-agent packages where relevant.
• Include tool/action contracts and safe fallbacks per role.
• Include knowledge-source/freshness expectations per role.
• Include adapter notes or mapping guidance for Pi, Claude, Codex, Agy, and manual execution when role behavior differs by harness.

Suggested role-agent package shape update

agents/roles/<role>/
├── AGENT.md
├── README.md
├── starter-prompts.md
├── checklist.md
├── inputs.md
├── outputs.md
├── tools.md
├── knowledge-sources.md
├── guardrails.md
└── examples.md

Acceptance criteria additions

• Role agents are harness-neutral by default and harness-capability-aware when runtime support exists.
• Role agents can be used inline by the parent orchestrator or delegated to a sub-agent/session without changing semantics.
• Role-agent examples show both human-readable use and agent/sub-agent invocation.

[github-actions]

Integrated into development by PR #116: #116

Merge commit: 5d08ddbe7e3cefe8fe59d9421a86cea781514495
Release/promotion to main is tracked separately.

[github-actions]

Integrated into development by PR #117: #117

Merge commit: 0a19c0a24cb234e21f9f48dd7034f0a4a7ad55bd
Release/promotion to main is tracked separately.

[github-actions]

Integrated into development by PR #118: #118

Merge commit: 6cd23f4289fff1ffd01dfca4605711030dd333f0
Release/promotion to main is tracked separately.