arch-sparring-agent 0.6.0

Multi-agent architecture review system using AWS Bedrock

Architecture Review Sparring Partner

Multi-agent system for architecture reviews. Analyzes requirements documents, CloudFormation templates, architecture diagrams, and source code, then challenges architectural decisions through interactive sparring.

Features

• 5-phase review process: Requirements → Architecture → Questions → Sparring → Final Review
• Interactive sparring: Challenges architectural gaps and pushes back on weak justifications
• Remediation mode: Discuss and resolve findings from previous reviews with session memory
• CI/CD mode: Non-interactive automated reviews with structured output and exit codes
• CDK support: Works with CloudFormation templates and CDK synthesized output (cdk.out/)
• Multimodal analysis: Analyzes architecture diagrams (PNG, JPEG) via Bedrock
• Full session export: Saves complete review session to markdown or JSON

Prerequisites

• Python 3.11+
• AWS credentials configured
• Nova 2 Lite model access in Bedrock console

Installation

pip install arch-sparring-agent

Usage

Interactive Mode (Default)

arch-review \
    --documents-dir ./docs \
    --templates-dir ./templates \
    --diagrams-dir ./diagrams

Outputs to .arch-review/ folder. Previous reviews are automatically archived to .arch-review/history/.

With Source Code Analysis

arch-review \
    --documents-dir ./docs \
    --templates-dir ./cdk.out \
    --diagrams-dir ./diagrams \
    --source-dir ./src/lambdas

CI/CD Mode

# Non-interactive (no history archiving by default)
arch-review --ci \
    --documents-dir ./docs \
    --templates-dir ./cdk.out \
    --diagrams-dir ./diagrams

# JSON output for programmatic processing
arch-review --json \
    --documents-dir ./docs \
    --templates-dir ./templates \
    --diagrams-dir ./diagrams

# CI with history archiving
arch-review --ci --keep-history \
    --documents-dir ./docs \
    --templates-dir ./cdk.out \
    --diagrams-dir ./diagrams

Remediation Mode

After running a review, discuss and resolve findings:

arch-review --remediate

• Loads gaps/risks from .arch-review/state.json
• Continues conversations across sessions via memory
• Saves notes to .arch-review/remediation-notes.md

Options

Option	Description
--documents-dir	Directory with markdown requirements/constraints
--templates-dir	CloudFormation templates or cdk.out/ directory
--diagrams-dir	Architecture diagrams (PNG, JPEG)
--source-dir	Lambda/application source code (optional)
--output-dir	Output directory (default: .arch-review)
--no-history	Don't archive previous reviews (default in CI mode)
--keep-history	Archive previous reviews even in CI mode
--no-state	Don't save state file after review
--remediate	Enter remediation mode
--no-remediation-output	Don't save remediation notes
--ci	CI/CD mode: non-interactive analysis
--json	Output as JSON (implies --ci)
--strict	Fail on any High impact risk (ignores verdict)
--reasoning-level	Reasoning effort: off, low, medium, high (default: low)
--skip-policy-check	Skip policy engine setup (development only)
-v, --verbose	Show detailed output (policy setup, debug info)
--model	Model: nova-2-lite or opus-4.6 (default: nova-2-lite)
--region	AWS region (default: eu-central-1)

Supported Models

The --model flag accepts a short name from the curated model registry. Only models with 1M context windows are supported to ensure reliable full-project reviews.

Short Name	Model	Context	--model value
Nova 2 Lite	Amazon Nova 2 Lite	1M	nova-2-lite
Claude Opus 4.6	Anthropic Claude Opus 4.6	1M	opus-4.6

Examples:

# Default (Nova 2 Lite with low reasoning)
arch-review --documents-dir ./docs --templates-dir ./cdk.out --diagrams-dir ./diagrams

# Claude Opus 4.6 with medium reasoning
arch-review --model opus-4.6 --reasoning-level medium \
    --documents-dir ./docs --templates-dir ./cdk.out --diagrams-dir ./diagrams

# Compare with reasoning off
arch-review --model opus-4.6 --reasoning-level off \
    --documents-dir ./docs --templates-dir ./cdk.out --diagrams-dir ./diagrams

Reasoning levels:

• off -- disable extended thinking entirely
• low -- minimal reasoning (default, fastest)
• medium -- balanced reasoning
• high -- maximum reasoning (slowest, best quality)

Model Quotas & Cost

AWS Bedrock enforces daily token quotas per model at the account level. These quotas are shared across all users and workloads on the same AWS account.

Model	Cross-Region Daily Quota	Relative Cost
nova-2-lite	~432M tokens	Low
opus-4.6	~2.6M tokens	High

Warning: Opus 4.6 has a very low default daily token quota (~2.6M tokens for cross-region inference). A single architecture review involves multiple agent calls (requirements, architecture, questions, sparring, final review), each consuming tokens. You may only get 1–2 reviews per day before hitting the limit.

Additionally, Opus 4.6 uses adaptive thinking with automatic interleaved thinking between tool calls. Thinking tokens are billed as output tokens (docs) and most Claude models apply a 5x burndown rate on output tokens (1 output token = 5 tokens from your quota). This significantly amplifies quota consumption.

For Nova 2 Lite, reasoning tokens are also charged even though reasoning content is redacted (docs).

For iterative development and frequent reviews, nova-2-lite (the default) is strongly recommended. Reserve opus-4.6 for cases where higher reasoning quality is critical.

These quotas are marked as non-adjustable in AWS Service Quotas. Contact AWS Support to request an increase.

Environment Variables

All options can be set via environment variables:

Variable	Description
ARCH_REVIEW_DOCUMENTS_DIR	Documents directory
ARCH_REVIEW_TEMPLATES_DIR	Templates directory
ARCH_REVIEW_DIAGRAMS_DIR	Diagrams directory
ARCH_REVIEW_SOURCE_DIR	Source code directory
ARCH_REVIEW_OUTPUT_DIR	Output directory
ARCH_REVIEW_MODEL	Model short name (nova-2-lite, opus-4.6)
ARCH_REVIEW_REASONING_LEVEL	Reasoning effort: off, low, medium, high
AWS_REGION	AWS region
CI	Enable CI mode (true/1/yes)

Exit Codes

Code	Meaning
0	PASS - no significant issues found
1	FAIL (or --strict with High impact)
2	PASS WITH CONCERNS - gaps found but non-critical
3	Error during execution

AWS Credentials

The tool uses the standard AWS credential chain.

Local Development

Configure credentials using any standard method:

# Option 1: AWS CLI profile
aws configure

# Option 2: Environment variables
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

# Option 3: AWS SSO
aws sso login --profile my-profile
export AWS_PROFILE=my-profile

CI/CD Environments

Each platform has its own credential mechanism:

Platform	Recommended Method	Credential Source
GitHub	OIDC	IAM Identity Provider for GitHub
GitLab	OIDC	IAM Identity Provider for GitLab
AWS CodeBuild	Service Role	Attached IAM role (automatic)
Jenkins	Instance Profile or Secrets	EC2 role or credential plugin

Required IAM Permissions

Note: For production use, scope Resource to your specific account/region ARNs.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockModelAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:Converse",
        "bedrock:ListFoundationModels"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AgentCorePolicyAndGateway",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicyEngine",
        "bedrock-agentcore:ListPolicyEngines",
        "bedrock-agentcore:CreatePolicy",
        "bedrock-agentcore:UpdatePolicy",
        "bedrock-agentcore:GetPolicy",
        "bedrock-agentcore:ListPolicies",
        "bedrock-agentcore:CreateGateway",
        "bedrock-agentcore:GetGateway",
        "bedrock-agentcore:UpdateGateway",
        "bedrock-agentcore:ListGateways"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AgentCoreMemory",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateMemory",
        "bedrock-agentcore:ListMemories"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CallerIdentity",
      "Effect": "Allow",
      "Action": "sts:GetCallerIdentity",
      "Resource": "*"
    }
  ]
}

CI/CD Integration

Example configurations are in examples/ci/.

GitHub Actions

Copy examples/ci/github-actions.yml to .github/workflows/arch-review.yml:

• Supports OIDC (recommended) or static credentials
• Comments results on PRs
• Uploads review as artifact

GitLab CI

Copy examples/ci/gitlab-ci.yml to .gitlab-ci.yml:

• Supports OIDC or CI/CD variables
• Runs on merge requests
• Optional JSON output job

AWS CodeBuild

Copy examples/ci/aws-codebuild.yml to buildspec.yml:

• Uses CodeBuild service role automatically
• No credential configuration needed
• Works with CodePipeline

Review Phases

1. Requirements Analysis: Extracts requirements, constraints, and NFRs from documents
2. Architecture Analysis: Analyzes CloudFormation templates and diagrams
3. Clarifying Questions (interactive) / Gap Identification (CI): Gathers context or identifies unknowns
4. Sparring (interactive) / Risk Analysis (CI): Challenges decisions or lists risks
5. Final Review: Produces structured review with gaps, risks, recommendations

Input Formats

Documents

Markdown files with requirements, constraints, NFRs, ADRs. No specific format required.

Templates

• CloudFormation: .yaml, .yml, .json
• CDK: Point to cdk.out/ directory

Diagrams

• PNG, JPEG images
• Export draw.io files to PNG/JPEG first

Project Structure

arch_sparring_agent/
├── agents/
│   ├── requirements_agent.py  # Phase 1: Document analysis
│   ├── architecture_agent.py  # Phase 2: Template/diagram analysis
│   ├── question_agent.py      # Phase 3: Interactive questions
│   ├── sparring_agent.py      # Phase 4: Interactive sparring
│   ├── ci_agents.py           # Phase 3-4: CI/CD non-interactive
│   ├── review_agent.py        # Phase 5: Final review
│   └── remediation_agent.py   # Remediation mode discussions
├── tools/
│   ├── document_parser.py     # Markdown file reader
│   ├── cfn_analyzer.py        # CloudFormation template reader
│   ├── diagram_analyzer.py    # Diagram analysis via Bedrock
│   └── source_analyzer.py     # Lambda/application source code reader
├── orchestrator.py            # Phase orchestration
├── config.py                  # Constants and AWS client setup
├── policy.py                  # Cedar policy management
├── gateway.py                 # Gateway setup and lifecycle
├── memory.py                  # AgentCore memory for sessions
├── exceptions.py              # Custom exception hierarchy
├── context_condenser.py       # Handles large inputs
├── state.py                   # Review state persistence
└── cli.py                     # CLI entry point
examples/ci/
├── github-actions.yml         # GitHub Actions example
├── gitlab-ci.yml              # GitLab CI example
└── aws-codebuild.yml          # AWS CodeBuild example

Development

uv sync                    # Install dependencies
uv run ruff format .       # Format code
uv run ruff check .        # Lint code

Policy Engine

The tool automatically creates and configures a full policy enforcement stack for security:

1. Creates a Gateway ("ArchReviewGateway") or uses an existing one
2. Creates a Policy Engine ("ArchReviewPolicyEngine") or uses an existing one
3. Creates Cedar policies restricting each agent to specific tools:
   • RequirementsAnalyst: Only document reading tools
   • ArchitectureEvaluator: Only CFN/diagram reading tools
   • DefaultDeny: Blocks unknown agents
4. Associates the Gateway with the Policy Engine for enforcement

Technical Details

• Default Model: Nova 2 Lite (1M context, multimodal)
• Multi-model: Curated registry with Nova 2 Lite and Claude Opus 4.6 via --model
• Framework: AWS Strands SDK
• Region: eu-central-1 (configurable)
• Policy Engine: AgentCore Policy Engine for tool access control

References

• Strands SDK
• Amazon Bedrock
• Amazon Nova 2 Models