Home/Agent System

agent_secure_setup v2March 29, 2026 · 22:57

Agent Orchestration System

Hard-boundary architecture: agents run isolated with no secrets. All sensitive operations flow through an executor with IAM-scoped identity. Ambiguities are batched — never interrupt the build.

Agent proposes → Human decides → Executor executes

Agent Roles

🔨

Builder Agent

Writes code, refactors, implements features.

✓Write code in /workspace

✓Run tests

✓Create ambiguity reports

✗Access secrets

✗Execute deployment directly

✗Bypass executor

✓

Test Agent

Writes and runs tests. Identifies regressions. Prepares validation reports.

✓Run test suite

✓Write test files

✓Report regressions

✗Modify production code

✗Access .env

✗Skip test failures

◎

Review Agent

Checks invariants, flow rules, hidden coupling. Flags architectural violations.

✓Read all workspace files

✓Flag violations

✓Suggest corrections

✗Modify files directly

✗Override invariants

✗Mark violations as resolved

📄

Docs Agent

Updates ADRs, specs, and operator notes.

✓Write ADRs

✓Update specs

✓Record decisions

✗Write code

✗Access secrets

✗Modify executor config

Work Cycle

01OperatorWrite spec → /workspace/spec.md

02BuilderImplement. File ambiguities to /.agent/ambiguities/ — never halt.

03TestWrite and run tests. File its own ambiguities.

04ReviewCheck invariants, flow rules, hidden coupling.

05DocsUpdate ADRs, specs, operator notes.

06OperatorRead ambiguity queue summary. Resolve in batch.

07ExecutorPerform sensitive actions via POST /execute.

Ambiguity Queue

Agents work start-to-finish with no oversight. When something is unclear, it is filed to /.agent/ambiguities/ — never a reason to stop. Human resolves in batch.

File format

### Question

### Why It Blocks Progress

### Options Considered

### Recommended Option

### Impact

### Default Held

Blocks execution entirely

Blocks deployment or migration

Blocks polish or hardening

Optional improvement

Executor Contract

Executor runs with AWS IAM role. Reads only approved SSM Parameter Store paths. Returns booleans, summaries, status — never raw secrets.

deploy_stagingDeploy current workspace to staging environment

run_testsExecute full test suite, return pass/fail summary

fetch_metrics_summaryReturn aggregated metrics (never raw data)

get_staging_config_valuesReturn filtered config values (never raw secrets)

run_db_migration_planExecute migration plan, return outcome

✗ expose raw secrets · ✗ arbitrary shell · ✗ unrestricted SSM reads

Security Architecture

OPERATOR

resolves ambiguity batches · makes final decisions

↕

AGENT LAYER

isolated container · /workspace only · no secrets · no .env

↕

EXECUTOR LAYER

AWS IAM identity · POST /execute · validates + logs · returns status

↕

SECRETS LAYER

AWS SSM Parameter Store · executor-only reads · never surface to agent

Invariants That Never Break

01Nothing leaves Employer

02Agent proposes, human decides, executor executes

03Capture first, decide later

04Don't guess the flow

05All ambiguity goes into queue — never halt the build

06All sensitive execution through executor

07No secrets in agent filesystem

08Promotion is intentional