arch-sparring-agent 0.3.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)
--skip-policy-check	Skip policy engine setup (development only)
-v, --verbose	Show detailed output (policy setup, debug info)
--model	Bedrock model ID (default: Nova 2 Lite)
--region	AWS region (default: eu-central-1)

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	Bedrock model ID
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

• Model: Nova 2 Lite (300K context, multimodal)
• 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