Skip to main content

Agent SDLC Setup

Open Repo Download ZIP

git clone https://github.com/AEEF-AI/aeef-transform.git

The Agent SDLC is the governance framework for AI agents operating within your software development lifecycle. It defines which agents exist, what they can do, how they hand off work to each other, and how their actions are validated in CI. This page covers the practical setup using files from the Transformation tier reference implementation.

For the full conceptual framework, see Agent SDLC Orchestration.

What the Agent SDLC Provides​

The AEEF Agent SDLC model defines up to 11 agent roles that can participate in the development process. At the Transformation tier, you configure:

  • Agent registry -- A central manifest of all active agents
  • Agent contracts -- Interface definitions specifying agent capabilities and boundaries
  • Handoff templates -- Structured protocols for inter-agent communication
  • Role prompts -- System prompts that align each agent to its AEEF role
  • CI validation -- Automated checks that agent metadata in PRs conforms to the schema

Setting Up the Agent Registry​

The agent registry is a JSON file that declares every agent active in your environment:

{
  "$schema": "../schemas/agent-registry.schema.json",
  "version": "1.0.0",
  "agents": [
    {
      "id": "developer-agent",
      "name": "Developer Agent",
      "role": "developer",
      "trustLevel": "supervised",
      "tools": ["code-generation", "refactoring", "test-generation"],
      "environments": ["development", "staging"],
      "owner": "platform-team",
      "status": "active"
    },
    {
      "id": "qa-agent",
      "name": "QA Agent",
      "role": "qa",
      "trustLevel": "supervised",
      "tools": ["test-execution", "coverage-analysis", "mutation-testing"],
      "environments": ["development", "staging"],
      "owner": "qa-team",
      "status": "active"
    },
    {
      "id": "security-agent",
      "name": "Security Agent",
      "role": "security",
      "trustLevel": "autonomous",
      "tools": ["sast-scanning", "sca-scanning", "secret-detection"],
      "environments": ["development", "staging", "production"],
      "owner": "security-team",
      "status": "active"
    }
  ]
}

Place this file at ai/agents/registry.json in your repository.

Creating Agent Contracts​

Each agent has a contract that defines its interface -- what it can read, what it can write, and what services it can invoke:

{
  "$schema": "../../schemas/agent-contract.schema.json",
  "agentId": "developer-agent",
  "version": "1.0.0",
  "inputs": {
    "accepts": ["task-description", "codebase-context", "test-requirements"],
    "maxContextTokens": 128000
  },
  "outputs": {
    "produces": ["source-code", "unit-tests", "commit-message"],
    "requiresReview": true
  },
  "permissions": {
    "read": ["src/**", "tests/**", "docs/**"],
    "write": ["src/**", "tests/**"],
    "deny": [".env*", "secrets/**", "infrastructure/**"]
  },
  "constraints": {
    "maxFilesPerChange": 10,
    "requiresTests": true,
    "requiresDocumentation": false
  }
}

Place contracts at ai/contracts/<agent-id>.json.

Handoff Templates​

Handoff templates define how agents pass context when transitioning between SDLC phases:

{
  "$schema": "../../schemas/handoff-template.schema.json",
  "handoffId": "developer-to-qa",
  "from": "developer-agent",
  "to": "qa-agent",
  "trigger": "pull-request-created",
  "context": {
    "required": ["changed-files", "commit-messages", "test-coverage-report"],
    "optional": ["architecture-notes", "known-risks"]
  },
  "validation": {
    "preConditions": ["all-tests-passing", "lint-clean"],
    "postConditions": ["qa-review-complete", "coverage-threshold-met"]
  }
}

Place handoff templates at ai/handoffs/<handoff-id>.json.

Role Prompts​

Role prompts are system-level instructions that configure each agent's behavior:

# Developer Agent - System Prompt

You are the Developer Agent operating under AEEF governance.

## Your Role
- Generate and modify source code based on task descriptions
- Write unit tests for all new code (minimum 80% coverage)
- Follow the project's coding standards (ESLint/Ruff/golangci-lint)

## Constraints
- NEVER modify files outside src/ and tests/ directories
- NEVER access or generate .env files or secrets
- ALWAYS disclose AI assistance in commit messages
- ALWAYS follow conventional commit format

## Handoff Protocol
When your work is complete, generate a handoff summary for the QA Agent including:
1. List of changed files
2. Test coverage delta
3. Known edge cases not covered

Place role prompts at ai/agents/<agent-id>.prompt.md.

Integration with CI​

The Transformation tier CI pipeline validates agent metadata in PRs:

- name: Validate Agent Metadata
  run: |
    # Validate registry schema
    npx ajv validate -s schemas/agent-registry.schema.json -d ai/agents/registry.json

    # Validate all contracts
    for contract in ai/contracts/*.json; do
      npx ajv validate -s schemas/agent-contract.schema.json -d "$contract"
    done

    # Validate handoff templates
    for handoff in ai/handoffs/*.json; do
      npx ajv validate -s schemas/handoff-template.schema.json -d "$handoff"
    done

This ensures that any changes to agent configuration are schema-compliant before they reach the main branch.

Scaling to the Full 11-Agent Model​

The Transformation tier typically starts with 3-5 agents. The full 11-agent model (Product, Scrum, Architect, Developer, QA, Security, Compliance, Platform, DevMgr, Ops, Executive) is detailed in the Agent Specifications. Scale by:

  1. Adding new agent entries to the registry
  2. Creating contracts for each new agent
  3. Defining handoff templates between agent pairs
  4. Writing role prompts aligned to AEEF specifications
  5. Updating CI validation to cover new files

Live Orchestration with the AEEF CLI​

The configurations on this page define the agent contracts, handoffs, and prompts as static files. To run the Agent SDLC as a live workflow using Claude Code, use the AEEF CLI Wrapper:

# The CLI injects these contracts, prompts, and handoff templates automatically
aeef --role=product    # Uses product-agent contract + prompt
aeef --role=developer  # Uses developer-agent contract + prompt + quality gates
aeef --role=qc         # Uses qa-agent contract + prompt (read-only mode)

The CLI translates the static configurations into Claude Code hooks, skills, and rules that enforce contracts in real-time during agent execution.

Skills Catalog Registry and Intake Mapping​

PRD-STD-017 adds a governed skills layer on top of the agent registry and contracts described above.

In practice, teams SHOULD maintain:

  • a quarantined external intake area for community skills catalogs
  • an attribution manifest per intake snapshot
  • a triage record that evaluates candidate skills against AEEF controls
  • an internal approved/provisional catalog file with role/environment gates

See:

Next Steps​

Last updated on by BalrogEg