Conceptual reference architecture

Architecture layers: full reference

01: Work Tracking

Responsibility: Captures tickets with requirements and acceptance criteria, the canonical record of intent that every downstream agent reads and posts back to throughout the pipeline.

Inputs

• Human-authored requirements and acceptance criteria
• Priority and scope decisions set by the team

Outputs

• Structured work items consumed by the orchestration layer
• Running audit trail of agent actions posted as ticket comments

Governance question: Who owns ticket quality, and what review step confirms acceptance criteria are clear enough before work begins?

02: Orchestration

Responsibility: Reads each work item, sequences agent invocations, routes outputs between layers, and posts status updates back to the originating ticket at every transition.

Inputs

• Structured work items from the tracking layer
• Success, failure, or escalation signals from each downstream agent

Outputs

• Targeted invocations with context passed to each specialized agent
• Status comments, artifact links, and verdicts posted back to the ticket

Governance question: What is the escalation path when an agent reaches a decision boundary it cannot resolve autonomously?

03: Specialized Agents

Responsibility: Each agent owns one discrete step: writing code, reviewing a pull request diff, generating tests, or assessing quality. Each returns a structured result to the orchestration layer.

Inputs

• Ticket requirements and acceptance criteria from orchestration
• Current branch state and pull request context

Outputs

• A feature branch and draft pull request for code changes
• Review findings, generated test files, and quality verdicts, each surfaced on the ticket

Governance question: Under what conditions should a low-confidence or flagged finding halt the pipeline rather than continue to the next stage?

04: Quality Controls

Responsibility: Aggregates coverage, duplication, and issue-severity signals from static analysis and renders a pass or fail verdict that gates promotion to staging.

Inputs

• Pull request diff from the feature branch
• Static analysis results scoped to the changed code

Outputs

• A binary pass or fail verdict with supporting detail
• Verdict and evidence posted to both the ticket and the pull request

Governance question: Who sets the quality thresholds, and what approval process covers planned exceptions?

05: Staging

Responsibility: Resolves the preview deployment URL for the candidate change and surfaces it on the ticket, giving stakeholders a live environment for user acceptance review before production.

Inputs

• Approved pull request from the quality gate
• Deployment trigger from the orchestration layer

Outputs

• A live preview URL posted to the ticket for stakeholder review
• User acceptance sign-off signal once a human confirms the change is ready

Governance question: Who is authorized to grant user acceptance sign-off, and what does "accepted" mean for this class of change?

06: Production

Responsibility: Promotes a human-approved change to the live environment and closes the originating ticket on success. Every action is logged as a ticket comment so the full audit trail is intact.

Inputs

• Human approval from the staging review
• Deployment trigger from the orchestration layer

Outputs

• A live production deployment
• A closed ticket with the complete audit trail from ticket to production

Governance question: Who holds production deployment authority, and how is that approval recorded to satisfy audit requirements?