Agent Permission Rationale

Version: 1.0.0

Agent Permission Tier Rationale

Version: 1.0.0 Parent Document: @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/docs/agent-permission-tiers.md

Purpose

This document explains WHY each agent is assigned to its permission tier. Use this as a reference when creating new agents or evaluating tier assignments.

Assignment Principles

Analyst Tier Assignment Criteria

An agent should be Analyst tier if it: 1. Primarily consumes information to produce reports/specifications 2. Does not need to execute code or run tests 3. Works on analysis, review, or documentation tasks 4. Should not trigger code changes directly

Key Question: "Does this agent produce executable artifacts or just specifications/reports?"

If the answer is "just specifications/reports", it's Analyst tier.

Implementation Tier Assignment Criteria

An agent should be Implementation tier if it: 1. Writes or modifies executable code 2. Needs to run tests or builds to validate work 3. Deploys or configures infrastructure 4. Requires Bash access for its core responsibilities

Key Question: "Does this agent need to execute commands as part of its work?"

If the answer is "yes", it's Implementation tier.

Orchestrator Tier Assignment Criteria

An agent should be Orchestrator tier if it: 1. Coordinates work across multiple specialist agents 2. Makes routing decisions about which agents to invoke 3. Manages SDLC phase transitions 4. Requires flexible delegation to accomplish goals

Key Question: "Does this agent primarily delegate to other agents?"

If the answer is "yes", it's Orchestrator tier.

Rationale by Agent

Analyst Tier (25 agents)

Requirements Analysts

  • requirements-analyst: Produces requirement specs, not code
  • requirements-reviewer: Reviews and validates requirements documents
  • requirements-documenter: Formats and organizes requirement artifacts

Rationale: Requirements work is pure analysis. These agents consume stakeholder input and produce specifications. They don't execute code or need Bash access.

Domain Experts

  • domain-expert: Provides domain knowledge and validation
  • business-process-analyst: Analyzes business processes, produces process maps
  • system-analyst: Analyzes system boundaries and integration points

Rationale: Domain analysis is about understanding and documenting, not implementation. These agents provide expertise without touching code.

Security Review

  • security-auditor: Reviews code/architecture for vulnerabilities, produces findings
  • security-architect: Designs security controls, produces threat models
  • security-gatekeeper: Validates security requirements are met

Rationale: Security review is distinct from security implementation. These agents identify issues and specify controls, but don't implement fixes. This separation of concerns prevents reviewers from modifying what they audit.

Code Reviewers

  • code-reviewer: Reviews pull requests, provides feedback
  • citation-verifier: Validates citations in documentation
  • quality-assessor: Evaluates artifact quality

Rationale: Reviewers should observe and report, not modify. Limiting to Analyst tier prevents blurring the line between reviewer and implementer.

Governance

  • legal-liaison: Validates legal compliance, provides guidance
  • privacy-officer: Reviews privacy implications
  • raci-expert: Creates RACI matrices
  • decision-matrix-expert: Builds decision frameworks

Rationale: Governance roles are advisory. They provide frameworks and validation without executing code or making technical implementations.

Strategy

  • metrics-analyst: Analyzes metrics, produces reports
  • product-strategist: Defines product strategy
  • product-designer: Creates product designs and mockups
  • vision-owner: Maintains product vision

Rationale: Strategy and design work is pre-implementation. These agents define WHAT to build, not HOW. They produce specifications for Implementation tier agents to execute.

Documentation

  • documentation-archivist: Organizes and maintains documentation
  • documentation-synthesizer: Combines documentation from multiple sources
  • technical-writer: Writes end-user documentation
  • test-documenter: Documents test plans and results
  • architecture-documenter: Documents architectural decisions

Rationale: Documentation agents consume existing artifacts and produce readable documentation. They don't execute code or modify implementations.

Implementation Tier (23 agents)

Development

  • software-implementer: Writes production code, runs tests
  • test-engineer: Writes and executes tests
  • test-architect: Designs test frameworks (may need to execute them)

Rationale: Core development work requires execution. These agents must run tests to validate their work (REF-013 MetaGPT executable feedback pattern).

Debugging

  • debugger: Investigates issues, runs debugging commands
  • database-optimizer: Analyzes and optimizes database queries (needs execution)
  • performance-engineer: Profiles code, runs benchmarks

Rationale: Debugging requires execution to reproduce issues, analyze behavior, and validate fixes.

DevOps

  • devops-engineer: Manages CI/CD pipelines, infrastructure
  • build-engineer: Configures build systems
  • cloud-architect: Provisions cloud resources

Rationale: DevOps work is inherently about execution - deploying, building, provisioning. Bash access is essential.

Modernization

  • legacy-modernizer: Refactors old code, needs to run tests
  • incident-responder: Investigates and remediates incidents (requires execution)
  • reliability-engineer: Implements SRE practices, monitors systems

Rationale: These agents work with running systems and need execution to validate changes or investigate issues.

Integration

  • integration-engineer: Integrates systems, tests connections
  • deployment-manager: Deploys applications
  • environment-engineer: Manages deployment environments

Rationale: Integration and deployment work requires execution to validate connections and configurations.

Accessibility

  • accessibility-specialist: Validates accessibility (may need to run automated tools)
  • api-designer: Designs APIs (may prototype and test)
  • api-documenter: Documents APIs (may need to test endpoints)

Rationale: While primarily design/documentation, these agents benefit from execution to validate their work.

Tooling

  • toolsmith: Creates tools for other agents
  • mcpsmith: Creates MCP servers
  • skillsmith: Creates skills
  • commandsmith: Creates commands
  • agentsmith: Creates agent definitions

Rationale: Tool creation requires testing and validation. These agents write code that must be executed to verify functionality.

Research

  • technical-researcher: Investigates technologies, may prototype to evaluate

Rationale: Technical research often involves running proof-of-concepts and validating claims empirically.

Orchestrator Tier (8 agents)

Orchestration

  • executive-orchestrator: Manages entire SDLC lifecycle, routes to all specialists
  • architecture-designer: Coordinates architecture work across multiple domains

Rationale: Top-level orchestrators need unrestricted delegation to coordinate work. They decide which specialist agents to invoke based on task needs.

Intake

  • intake-coordinator: Routes incoming requests to appropriate specialists
  • project-manager: Manages project workflow, delegates to team

Rationale: Intake and project management are about routing work to the right agents, requiring full Task access.

Management

  • configuration-manager: Manages configuration artifacts across the system
  • traceability-manager: Maintains traceability across all artifacts

Rationale: Management roles need visibility and control across all agent types to maintain system-wide consistency.

Context

  • context-librarian: Manages context for all agents
  • component-owner: Coordinates work for specific components

Rationale: These agents provide support across all agent types and need flexible delegation.

Edge Cases and Debates

Why is technical-researcher Implementation tier?

Debate: Could be Analyst (research is analysis) or Implementation (needs to prototype)

Decision: Implementation tier

Rationale: Technical research often requires running code to evaluate claims. REF-013 MetaGPT's executable feedback pattern shows that execution improves research quality. Researcher needs to validate that technologies actually work as claimed.

Why is security-auditor Analyst tier but not security-implementer?

Separation of Concerns: Security audit must be independent from security implementation. If security-auditor could modify code, it creates a conflict of interest.

Pattern: Auditor finds issue → Documents finding → Escalates to Software Implementer → Implementer fixes → Auditor re-validates

This separation maintains audit integrity.

Why is api-designer Implementation tier?

Debate: API design is specification work (Analyst) vs needs testing (Implementation)

Decision: Implementation tier

Rationale: Modern API design benefits from immediate validation. Designing an API endpoint and immediately testing it with curl or Postman improves design quality. Implementation tier allows this.

Could architecture-designer be Implementation tier?

No: Architecture Designer coordinates multiple specialists (Security Architect, API Designer, etc.). This coordination role requires Orchestrator-level delegation. While individual architects might implement, the Architecture Designer is the coordinator.

Future Considerations

Tier Elevation

If an agent consistently needs to escalate for execution, consider: 1. Is the agent definition too narrow? 2. Should the agent be Implementation tier? 3. Is the workflow inefficient?

Example: If Requirements Analyst frequently escalates to run tests, either:

  • Requirements are too implementation-focused (scope issue)
  • Agent should be hybrid analyst-implementer (tier issue)
  • Workflow needs refinement (process issue)

Hybrid Agents

Future versions may support hybrid tiers:

  • Analyst+Bash: Can execute but not spawn other agents
  • Implementation+Orchestrate: Can spawn limited orchestrators

This is not yet supported but could address edge cases.

Dynamic Tier Elevation

Could allow temporary tier elevation with justification:

Task(Bash, justification="Need to validate API endpoint before finalizing spec")

This would require runtime support and audit logging.

References

  • @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/docs/agent-permission-tiers.md - Tier definitions
  • `@.aiwg/research/findings/REF-013-metagpt.md` - Executable feedback pattern
  • @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/executable-feedback.md - Execution requirements for code agents
  • Claude Code v2.1.33 Release Notes - Task(agent_type) introduction

Maintained by: Configuration Manager Last Updated: 2026-02-06 Review Cycle: Quarterly