Skip to main content

AEEF CLI Wrapper

Open Repo Download ZIP

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

The aeef CLI is a bash wrapper around Claude Code that orchestrates agent roles through Git branches. Each invocation spawns Claude Code with a specific agent persona, enforced constraints via hooks, and produces a PR as handoff to the next agent in the pipeline.

Adaptation Pack Status​

Latest public repo update PR for MCP/A2A adaptation assets:

Cross-repo migration notes:

Architecture​

aeef CLI (bash)
  │
  ├─ Sets up .claude/ directory with role-specific:
  │   ├── CLAUDE.md (role context)
  │   ├── settings.json (hooks config)
  │   ├── rules/contract.md (constraints)
  │   └── skills/ (aeef-handoff, aeef-gate, aeef-provenance)
  │
  ├─ Spawns `claude` with:
  │   ├── --append-system-prompt (role injection)
  │   ├── --allowedTools / --disallowedTools (per-role restrictions)
  │   └── --model (configurable)
  │
  └─ On completion:
      ├── git commit with AI-Usage metadata
      ├── gh pr create to downstream branch
      └── Handoff artifact in PR body

Branch Workflow​

The CLI uses a branch-per-role model where PRs serve as the handoff mechanism:

main ──────────────────────────────────────────────► main
  │                                                    ▲
  ▼                                                    │
aeef/product ── PR ──► aeef/architect ── PR ──► aeef/dev ── PR ──► aeef/qc ── PR ──┘
RoleBranchMerges FromPRs ToOn Failure
Productaeef/productmainaeef/architectRevert to main
Architectaeef/architectaeef/productaeef/devRevert to aeef/product
Developeraeef/devaeef/architectaeef/qcRevert to aeef/architect
QCaeef/qcaeef/devmainRevert to aeef/dev

Prerequisites​

Installation​

git clone https://github.com/AEEF-AI/aeef-cli.git
cd aeef-cli
./install.sh

The installer symlinks bin/aeef to ~/.local/bin/aeef and verifies dependencies.

Immediate Adoption (Install + Apply Hooks)​

Use this path if you want to apply the wrapper to an existing Git repo immediately before running any agent.

# Verify local prerequisites + target repository
aeef doctor --project ./my-project

# Apply AEEF hooks/rules/skills into the repo
aeef bootstrap --project ./my-project --role product --with-branches

# Start the first agent role
aeef --role product --project ./my-project

aeef bootstrap copies the role profile into .claude/ (hooks, settings, rules, skills) and prepares .aeef/ artifact directories so the repo is ready for the branch-per-role workflow.

Adoption Profiles (Minimum Agents vs Full 11 Agents)​

The CLI is designed to support a progressive adoption path:

  • Small-team CLI baseline: Start with the built-in 4-role baseline (product, architect, developer, qc)
  • Enterprise / production rollout: Use the same CLI core and extend it with additional role profiles aligned to the 11-agent orchestration model

Recommended pattern:

  1. Keep aeef-cli as the shared wrapper/binary
  2. Add role packs (extra roles/<name>/ configs, prompts, contracts, skills) for specialized agents
  3. Reuse the Production tier agent contracts/prompts/handoffs as the source of truth for full 11-agent definitions

This avoids maintaining a second CLI project while still supporting advanced operating models.

Apply the same CLI core using different implementation guides:

Starter role-pack (enterprise path):

Open Enterprise Role-Pack Repo Download ZIP

export AEEF_ROLE_PACK_DIR=/path/to/aeef-enterprise-role-pack
aeef --role qa --project ./my-project

Usage​

Product Agent — Requirements​

cd my-project
aeef --role product

Creates aeef/product branch, injects product agent context, spawns Claude Code. Claude translates business requirements into user stories with acceptance criteria. On completion, commits and creates PR to aeef/architect.

Architect Agent — Design​

aeef --role architect

Merges from aeef/product, injects architect context. Claude designs architecture (diagrams, API contracts, docker-compose). Creates PR to aeef/dev.

Developer Agent — Implementation​

aeef --role developer

Merges from aeef/architect, injects developer context with quality gates. Claude implements code, writes tests, runs lint/typecheck/test. Creates PR to aeef/qc.

QC Agent — Validation​

aeef --role qc

Merges from aeef/dev, injects QC context (read-only for source code). Claude runs test suites, generates release recommendation. Creates final PR to main and cleans up .claude/ and .aeef/ artifacts.

CI Mode​

aeef --role qc --ci --max-turns 20 --budget 5.00

Non-interactive mode for CI/CD pipelines. Adds -p --output-format json --dangerously-skip-permissions to the Claude invocation.

How Hooks Enforce Compliance​

The CLI configures five Claude Code hooks that run automatically:

HookEventPurpose
pre-tool-use.shPreToolUseBlocks forbidden actions per role contract
post-tool-use.shPostToolUseLogs tool usage to audit trail
session-start.shSessionStartInjects AEEF environment variables
stop.shStopVerifies quality gates before completion
user-prompt-submit.shUserPromptSubmitBlocks prompts containing secrets or policy violations

Contract Enforcement Examples​

Product Agent cannot run Bash commands or edit source code files:

✗ Blocked: Bash(npm install) — Product agents cannot execute shell commands
✗ Blocked: Edit(src/app.ts) — Product agents cannot modify source code
✓ Allowed: Write(stories/user-login.md) — Product agents can write stories

QC Agent cannot modify any files (read-only + test execution):

✗ Blocked: Edit(src/service.ts) — QC agents cannot modify source code
✗ Blocked: Write(src/new-file.ts) — QC agents cannot create source files
✓ Allowed: Bash(npm test) — QC agents can run test suites
✓ Allowed: Read(src/service.ts) — QC agents can read any file

Built-in Skills​

Three skills are available as slash commands within the Claude Code session:

/aeef-handoff​

Generates a structured handoff artifact JSON file that gets included in the PR body:

{
  "handoff_id": "HO-developer-qc-20250115-103000",
  "source_agent": "developer",
  "target_agent": "qc",
  "change_summary": {
    "what_changed": "Implemented user login endpoint with JWT auth",
    "files_touched": ["src/routes/auth.ts", "src/middleware/jwt.ts", "tests/auth.test.ts"],
    "rationale": "Story US-042 acceptance criteria"
  },
  "evidence": {
    "contract_version": "1.0.0",
    "test_evidence": "12/12 tests passing, 87% coverage",
    "security_scan_result": "pass"
  }
}

/aeef-gate​

Runs quality gate checks and reports pass/fail:

Quality Gate Results
━━━━━━━━━━━━━━━━━━
✓ Lint ............... PASS
✓ Type Check ......... PASS
✓ Tests .............. PASS (12/12)
✓ Coverage ........... PASS (87% > 80%)
✗ SAST ............... FAIL (1 high finding)
━━━━━━━━━━━━━━━━━━
Result: BLOCKED — 1 gate failed

/aeef-provenance​

Generates a provenance record tracking AI contribution lineage for compliance.

Tool Execution Tiers (Elicitation Pattern)​

The CLI's hook system naturally maps to the three tool execution tiers defined in PRD-STD-009 REQ-009-20:

TierHook MechanismExample
Auto-executeTool passes pre-tool-use.sh without outputRead, Glob, Grep — all roles
ElicitHook returns a structured question via AskUserQuestionDeveloper encounters two valid API patterns — hook injects a structured choice
ApproveHook blocks the tool and emits "decision": "block" with reasonBash(rm -rf ...), Edit(infrastructure/...) — requires human confirmation

The pre-tool-use.sh hook already enforces Approve (block) and Auto-execute (pass) tiers. To add Elicit behavior, configure the role contract to list tools that require structured user input before proceeding:

# roles/developer/rules/contract.md (excerpt)
tool_tiers:
  auto_execute:
    - Read
    - Glob
    - Grep
    - Bash:npm test
    - Bash:npm run lint
  elicit:
    - Write:src/*/new-*      # new files need user confirmation of placement
    - Bash:npm install *      # new dependencies need user approval
  approve:
    - Bash:rm *
    - Bash:git push *
    - Edit:infrastructure/*
    - Edit:.github/workflows/*

This three-tier model ensures agents act autonomously where safe, ask structured questions where ambiguous, and block where dangerous — all enforced through the same hook pipeline.

Extending to More Roles (Same CLI Core)​

The CLI ships with a 4-role baseline (product, architect, developer, qc). To reach the full AEEF 11-agent model, extend the same CLI with additional role profiles (for example: scrum, security, compliance, platform, devmgr, ops, executive).

To add a new role:

  1. Create roles/<role-name>/ directory with CLAUDE.md, settings.json, and rules/contract.md
  2. Add entries to a role-pack roles-map.sh file (or patch lib/roles.sh directly)
  3. Optionally add role-specific skills to roles/<role-name>/skills/

See Agent Orchestration Model and Agent SDLC Orchestration for the full 11-agent model specification and rollout path.

CLI Reference​

aeef [OPTIONS]

Options:
  --role=ROLE         Agent role (product|architect|developer|qc) [required]
  --backend-cmd=CMD   Backend command (default: claude)
  --project=DIR       Project directory (default: current directory)
  --model=MODEL       AI model to use (default: sonnet)
  --role-pack-dir=DIR Optional enterprise role-pack directory (adds roles like qa/security/platform/ops)
  --prompt=TEXT        Initial prompt to send to Claude
  --max-turns=N       Maximum turns in CI mode
  --budget=USD        Maximum budget in CI mode
  --ci                Enable CI mode (non-interactive)
  --help              Show help message

Repository​

github.com/AEEF-AI/aeef-cli

Last updated on by BalrogEg