Environment Promotion Model
Code moves through environments. Agents move through stages. This guide defines how the 7-stage agent pipeline maps to environment promotion — ensuring that the right agents perform the right validations in the right environment.
Environment Architecture
┌────────────────────────────────────────────────────────────────────────────┐
│ ENVIRONMENT PROMOTION FLOW │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ DEVELOPMENT │────>│ STAGING │────>│ PRODUCTION │ │
│ │ │ │ │ │ │ │
│ │ Stages 1-3 │ │ Stages 4-5 │ │ Stages 6-7 │ │
│ │ │ │ │ │ │ │
│ │ product-agent│ │ qa-agent │ │platform-agent│ │
│ │ scrum-agent │ │ security- │ │ ops-agent │ │
│ │ architect- │ │ agent │ │ executive- │ │
│ │ agent │ │ compliance- │ │ agent │ │
│ │ developer- │ │ agent │ │ │ │
│ │ agent │ │ devmgr-agent │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────────┘ │
│ │ │ ▲ │
│ Gate 3 Gate 5 Gate 6 │
│ (Code Ready) (Release Ready) (Deploy Approved) │
│ │
│ ◄──────── ROLLBACK PATH (any environment can trigger) ────────────► │
└────────────────────────────────────────────────────────────────────────────┘
Environment Definitions
Development Environment
Purpose: Where ideas become code. Agents explore, implement, and produce initial artifacts.
| Aspect | Details |
|---|---|
| Active agents | product-agent, scrum-agent, architect-agent, developer-agent |
| Active stages | Stage 1 (Requirements), Stage 2 (Design), Stage 3 (Implementation) |
| Data allowed | Synthetic data only. No production data, no PII, no Confidential/Restricted data |
| Branch strategy | Feature branches only. No direct commits to main/develop |
| CI checks | Lint, unit tests, basic SAST, AI metadata validation |
| Exit gate | Gate 3 — code compiles, tests pass, AI attribution present |
Agent-specific rules in Development:
| Agent | Allowed | Not Allowed |
|---|---|---|
product-agent | Draft stories, refine acceptance criteria | Access staging/production data |
scrum-agent | Estimate, assess capacity | Override developer estimates |
architect-agent | Validate design, check constraints | Make implementation decisions |
developer-agent | Write code, write tests, create PRs | Merge to protected branches, access production |
Staging Environment
Purpose: Where code proves it works. Agents validate quality, security, and compliance before production.
| Aspect | Details |
|---|---|
| Active agents | qa-agent, security-agent, compliance-agent, devmgr-agent |
| Active stages | Stage 4 (Testing), Stage 5 (Security & Compliance) |
| Data allowed | Anonymized production-like data. No real PII without data masking |
| Branch strategy | Release branches or main branch (post-merge) |
| CI checks | Full test suite, integration tests, E2E tests, SAST, DAST, SCA, license scan |
| Exit gate | Gate 5 — all tests pass, security cleared, compliance evidence complete |
Agent-specific rules in Staging:
| Agent | Allowed | Not Allowed |
|---|---|---|
qa-agent | Run tests, generate test matrices, classify defects | Modify source code, approve its own changes |
security-agent | Run scans, classify findings, produce remediation guidance | Waive critical findings, access production secrets |
compliance-agent | Verify evidence, check licenses, validate audit trail | Grant waivers without human approval |
devmgr-agent | Assess metrics, validate evidence completeness | Override security or compliance decisions |
Production Environment
Purpose: Where code serves users. Agents deploy, monitor, and report.
| Aspect | Details |
|---|---|
| Active agents | platform-agent, ops-agent, executive-agent |
| Active stages | Stage 6 (Deployment), Stage 7 (Operations) |
| Data | Real production data. All data handling per classification policy |
| Branch strategy | Only release-tagged commits from staging |
| Deployment | Canary → progressive rollout → full deployment |
| Exit gate | Gate 7 — health checks pass, no critical incidents, feedback captured |
Agent-specific rules in Production:
| Agent | Allowed | Not Allowed |
|---|---|---|
platform-agent | Execute deployment plan, configure monitoring, manage feature flags | Deploy without human approval, modify code |
ops-agent | Monitor metrics, detect anomalies, generate alerts, propose rollback | Execute rollback without human approval, modify code |
executive-agent | Aggregate metrics, generate reports, calculate ROI | Make operational decisions, modify infrastructure |
Promotion Gates
Gate 3: Development → Staging
Who decides: Automated CI pipeline + Developer review
| Check | Automated? | Blocking? |
|---|---|---|
| Code compiles | Yes | Yes |
| Lint passes | Yes | Yes |
| Unit tests pass | Yes | Yes |
AI metadata present (AI-Usage, Agent-IDs, AI-Prompt-Ref) | Yes | Yes |
| Basic SAST scan (critical only) | Yes | Yes |
| Developer code review | Human | Yes |
| PR approved by qualified reviewer | Human | Yes |
On failure: Code stays in Development. developer-agent receives failure details and iterates.
Gate 5: Staging → Production (Release Candidate)
Who decides: QA Lead + Security Engineer + Compliance Officer (human approvals for Tier 2+)
| Check | Automated? | Blocking? |
|---|---|---|
| Integration tests pass | Yes | Yes |
| E2E tests pass | Yes | Yes |
| Test coverage meets threshold | Yes | Yes |
| Full SAST scan | Yes | Yes |
| DAST scan | Yes | Yes |
| Dependency/license scan | Yes | Yes |
| No unresolved critical/high security findings | Yes | Yes |
| Compliance evidence pack complete | Yes | Yes |
| QA release readiness: PASS | Human (auto at Trust Level 3) | Yes |
| Security sign-off | Human for critical/high | Yes |
| Compliance sign-off for Tier 3+ | Human | Yes |
On failure: Code stays in Staging. Failure routes to the appropriate agent:
- Test failure →
developer-agent(fix code) orqa-agent(fix test) - Security finding →
developer-agent(remediate) +security-agent(re-scan) - Compliance gap →
compliance-agent(identify requirement) + relevant agent (produce evidence)
Gate 6: Staging → Production (Deployment Approval)
Who decides: Human approver (always, regardless of trust level)
| Check | Automated? | Blocking? |
|---|---|---|
| All Gate 5 checks passed | Yes | Yes |
| Deployment plan reviewed | Human | Yes |
| Rollback procedure tested | Human | Yes |
| Monitoring configured | Yes | Yes |
| Feature flags configured | Yes | Yes (if applicable) |
| Human deployment approval | Human | Always blocking |
On failure: Deployment blocked. platform-agent receives feedback to adjust configuration.
Rollback Protocol
Rollback can be triggered from any environment. The agent responsible depends on where the issue is detected.
ISSUE DETECTED IN:
Production ──> ops-agent proposes rollback ──> Human approves ──> platform-agent executes
│
Incident record
created
│
Routes to:
- developer-agent (code fix)
- security-agent (if vuln)
- qa-agent (if test gap)
Staging ──> qa-agent or security-agent flags issue ──> Routes back to Development
│
developer-agent fixes
Re-enters Gate 3
Development ──> developer-agent iterates locally ──> No rollback needed
Rollback Decision Matrix
| Severity | Detection Point | Decision Maker | Max Response Time | Action |
|---|---|---|---|---|
| Critical (data loss, security breach) | Production | Immediate — ops-agent auto-proposes, human approves | 15 minutes | Immediate rollback + incident response |
| High (major functionality broken) | Production | ops-agent proposes, Platform Engineer approves | 1 hour | Rollback or hotfix decision |
| Medium (degraded performance) | Production | ops-agent flags, Platform Engineer decides | 4 hours | Hotfix in next deployment window |
| Low (cosmetic, minor) | Production | ops-agent logs, next sprint | Next sprint | Fix in normal flow |
| Any severity | Staging | Automated — routes back to Development | Same sprint | Fix and re-promote |
Data Flow Between Environments
| Data Type | Development | Staging | Production |
|---|---|---|---|
| Source code | Feature branches | Release branches | Tagged releases |
| Test data | Synthetic only | Anonymized production-like | Real production data |
| Secrets | Dev secrets vault | Staging secrets vault | Production secrets vault |
| AI prompts | Full prompt content logged | Full prompt content logged | Prompt references only (no content) |
| Agent run records | Stored locally | Stored in audit system | Stored in audit system |
| Monitoring data | Basic metrics | Full metrics (simulated load) | Full production metrics |
warning
No data flows backward. Production data MUST NOT enter Staging or Development without anonymization. Staging data MUST NOT enter Development. Agent prompts in Production MUST NOT contain Confidential or Restricted data — use reference IDs instead.
Environment-Specific Agent Configuration
Each agent's contract is scoped to the environment it operates in. The same agent identity (developer-agent) may have different permissions in different environments.
# Example: developer-agent contract by environment
agent_id: developer-agent
contracts:
development:
allowed_inputs: [approved-story, architecture-constraints, existing-code]
allowed_outputs: [code-patch, unit-tests, implementation-notes]
forbidden_actions: [merge-main, access-staging, access-production]
data_classification_max: Internal
staging:
allowed_inputs: [test-failure-details, security-finding-details]
allowed_outputs: [code-fix-patch, remediation-notes]
forbidden_actions: [merge-main, access-production, modify-test-data]
data_classification_max: Internal
production:
allowed_inputs: [] # developer-agent does not operate in production
allowed_outputs: []
forbidden_actions: [all]
data_classification_max: none
This ensures that even if an agent's credentials are compromised, the blast radius is limited to the environment it is authorized for.