Starter Repo Blueprints

TypeScript orchestrator starter

typescript-orchestrator-starter/
  package.json
  src/
    contracts/
    hooks/
    gates/
    orchestration/
  policies/
    opa/
  prompts/
  tests/
    contract-validation/
    flow/
  .github/workflows/ci.yml

Python orchestrator starter

python-orchestrator-starter/
  pyproject.toml
  app/
    contracts/
    hooks/
    gates/
    orchestration/
  policies/
  tests/
    schemas/
    e2e/
  .github/workflows/ci.yml

Go governance gateway starter

go-governance-gateway-starter/
  go.mod
  cmd/gateway/
  internal/
    contracts/
    gates/
    ledger/
  policies/
  test/
  .github/workflows/ci.yml

Java governance gateway starter

java-governance-gateway-starter/
  pom.xml
  src/main/java/.../contracts/
  src/main/java/.../gates/
  src/main/java/.../ledger/
  src/test/java/.../
  policies/
  .github/workflows/ci.yml

Claude Code project structure (recommended)

A recommended directory layout for repositories using Claude Code with AEEF governance. This pattern places AI context files alongside the code they govern, giving each module its own scoped instructions.

my-project/
  CLAUDE.md                       # Root-level AI context (project overview, conventions)
  README.md
  docs/
    architecture.md               # Architecture decision log
    decisions/                    # ADRs (Architecture Decision Records)
    runbooks/                     # Operational runbooks
  .claude/
    settings.json                 # Hooks, permissions, model config
    hooks/
      pre-tool-use.sh             # Contract enforcement (per PRD-STD-009)
      post-tool-use.sh            # Audit trail logging
      stop.sh                     # Quality gate checks
    skills/
      code-review/
        SKILL.md                  # Reusable code review workflow
      refactor/
        SKILL.md                  # Guided refactoring skill
      release/
        SKILL.md                  # Release checklist skill
  tools/
    scripts/                      # Project-specific automation scripts
    prompts/                      # Reusable prompt templates
  src/
    api/
      CLAUDE.md                   # Module-scoped AI context (API conventions, auth patterns)
      ...
    persistence/
      CLAUDE.md                   # Module-scoped AI context (ORM patterns, migration rules)
      ...
    workers/
      CLAUDE.md                   # Module-scoped AI context (queue patterns, retry policies)
      ...

Per-module CLAUDE.md pattern

Place a CLAUDE.md in each major module directory to scope AI context to that area. This prevents agents from applying API conventions to persistence code or vice versa. Each module CLAUDE.md should include:

• Module purpose and boundaries
• Naming conventions specific to that module
• Key dependencies and their usage patterns
• Testing expectations (unit vs integration)
• Files the agent should never modify (e.g., generated code, migrations)

This pattern is already used in the aeef-transform and aeef-production reference repos. Adopting it in your own projects gives agents better scoped context and reduces cross-module mistakes.

Department agent catalog (.claude/agents/)

For organizations scaling beyond the 4-role CLI baseline, a .claude/agents/ directory organizes agent definitions by business function. Each .md file defines an agent persona with scoped instructions, tools, and constraints.

.claude/
  agents/
    engineering/
      frontend-developer.md
      backend-architect.md
      mobile-app-builder.md
      ai-engineer.md
      devops-automator.md
    product/
      trend-researcher.md
      feedback-synthesizer.md
      sprint-prioritizer.md
    design/
      ui-designer.md
      ux-researcher.md
      brand-guardian.md
    testing/
      api-tester.md
      performance-benchmarker.md
      test-results-analyzer.md
    operations/
      support-responder.md
      infrastructure-maintainer.md
      analytics-reporter.md

Each agent file should follow the agent contract schema from PRD-STD-009 and be registered in the skill/agent registry per PRD-STD-017. The directory-by-function layout scales naturally as teams add specialized agents without cluttering a flat namespace.

See AEEF CLI Wrapper for how to use these agent definitions with the --role-pack-dir flag.

Required CI gates for all starters

1. Contract schema validation (AgentContract, HookContract, GateDecision, HandoffArtifact, RunLedgerEntry)
2. Security scan gate
3. License compatibility gate
4. Attribution completeness gate
5. Unit and flow tests

Runnable minimal assets

For quick validation and training, use:

• reference-implementations/starter-repos/assets/typescript/
• reference-implementations/starter-repos/assets/python/
• reference-implementations/starter-repos/assets/go/
• reference-implementations/starter-repos/assets/java/