# maneeshchaturvedi/ai-engineering-harness architecture

> Architecture diagram of the GitHub repository maneeshchaturvedi/ai-engineering-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maneeshchaturvedi/ai-engineering-harness
- Repository: https://github.com/maneeshchaturvedi/ai-engineering-harness

## Overview

aih is a Go CLI that installs and operates an AI engineering harness in a user’s repository. Its main workflow moves from repository inspection and setup, through an interview and approved spec/design, to locked acceptance checks and scoped task work; hooks and GitHub CI enforce the rules at edit, commit, and merge time. The README documents these product stages and capabilities. Sampled source confirms several implementation responsibilities, but many lifecycle and integration details are unsampled, so the graph avoids asserting undocumented calls between those components.

Main entry points: [`internal/bootstrap/init.go`](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/bootstrap/init.go) (Initialize harness), [`internal/cli/root.go`](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/cli/root.go) (aih CLI), [`internal/lifecycle/more.go`](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/lifecycle/more.go) (Feature lifecycle), [`internal/hooks/guard.go`](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/hooks/guard.go) (Edit hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Repository setup"]
  node_bootstrap["Initialize harness<br/>[init.go]"]
  node_preflight["Preflight checks<br/>[preflight.go]"]
  node_detect["Project detection<br/>[detect.go]"]
  node_interview["Setup interview<br/>[form.go]"]
  node_render["Harness rendering<br/>[render.go]"]
  node_scaffold["Project scaffold<br/>[scaffold.go]"]
  node_plan["Setup plan<br/>[plan.go]"]
end

subgraph group_planning["Feature planning"]
  node_feature["Feature lifecycle<br/>[more.go]"]
  node_spec["Spec and design<br/>[spec.go]"]
  node_checks["Acceptance checks<br/>[blackbox.go]"]
end

subgraph group_work["Task execution"]
  node_task["Scoped task<br/>[scope.go]"]
  node_session["Copilot session<br/>[session.go]"]
  node_claude["Claude adapter<br/>[settings.go]"]
  node_kiro["Kiro adapter<br/>[kiro.go]"]
end

subgraph group_enforcement["Policy enforcement"]
  node_hooks["Edit hooks<br/>[guard.go]"]
  node_git_hooks["Git commit hooks<br/>[githooks.go]"]
  node_ci["Merge-time CI<br/>[approval.go]"]
end

subgraph group_operations["Harness operations"]
  node_cli["aih CLI<br/>[root.go]"]
  node_doctor["Harness doctor<br/>[doctor.go]"]
  node_github["GitHub setup<br/>[ghsetup.go]"]
end

node_person(("Person"))
node_github_actions["GitHub Actions"]
node_copilot(("Coding copilot"))
node_repo[("User repository")]

node_person -->|"runs commands"| node_cli
node_cli -->|"runs init"| node_bootstrap
node_bootstrap -->|"checks repository"| node_preflight
node_bootstrap -->|"detects project"| node_detect
node_bootstrap -->|"collects answers"| node_interview
node_bootstrap -->|"renders harness"| node_render
node_bootstrap -->|"previews changes"| node_plan
node_bootstrap -.->|"creates project"| node_scaffold
node_bootstrap -->|"writes harness"| node_repo
node_person -->|"starts feature"| node_cli
node_cli -->|"advances feature"| node_feature
node_feature -->|"creates and validates"| node_spec
node_person -->|"approves decisions"| node_spec
node_feature -->|"generates checks"| node_checks
node_person -->|"approves and locks"| node_checks
node_feature -->|"opens scoped work"| node_task
node_task -->|"sets session context"| node_session
node_session -->|"provides design context"| node_copilot
node_claude -.->|"configures hooks"| node_hooks
node_kiro -.->|"configures hooks"| node_hooks
node_copilot -->|"checked during edits"| node_hooks
node_person -->|"commits changes"| node_git_hooks
node_git_hooks -->|"checks approvals"| node_repo
node_github_actions -->|"runs merge checks"| node_ci
node_ci -->|"rechecks changes"| node_repo
node_cli -->|"checks installation"| node_doctor
node_bootstrap -->|"checks setup"| node_doctor
node_bootstrap -->|"offers GitHub setup"| node_github
node_github -.->|"sets up workflow"| node_github_actions

click node_cli "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/cli/root.go"
click node_bootstrap "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/bootstrap/init.go"
click node_preflight "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/preflight/preflight.go"
click node_detect "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/detect/detect.go"
click node_interview "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/interview/form.go"
click node_render "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/render/render.go"
click node_scaffold "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/scaffold/scaffold.go"
click node_feature "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/lifecycle/more.go"
click node_spec "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/spec/spec.go"
click node_plan "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/plan/plan.go"
click node_checks "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/blackbox/blackbox.go"
click node_task "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/scope/scope.go"
click node_session "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/hooks/session.go"
click node_claude "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/adapters/claude/settings.go"
click node_kiro "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/adapters/kiro/kiro.go"
click node_hooks "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/hooks/guard.go"
click node_git_hooks "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/githooks/githooks.go"
click node_ci "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/ci/approval.go"
click node_doctor "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/doctor/doctor.go"
click node_github "https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/ghsetup/ghsetup.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_preflight,node_detect,node_interview,node_render,node_scaffold,node_plan toneBlue
class node_feature,node_spec,node_checks,node_repo toneAmber
class node_task,node_session,node_claude,node_kiro toneMint
class node_hooks,node_git_hooks,node_ci toneRose
class node_cli,node_doctor,node_github,node_person,node_github_actions,node_copilot toneIndigo
```

## Components

### Repository setup

- [Initialize harness](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/bootstrap/init.go): `internal/bootstrap/init.go`
- [Preflight checks](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/preflight/preflight.go): `internal/preflight/preflight.go`
- [Project detection](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/detect/detect.go): `internal/detect/detect.go`
- [Setup interview](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/interview/form.go): `internal/interview/form.go`
- [Harness rendering](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/render/render.go): `internal/render/render.go`
- [Project scaffold](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/scaffold/scaffold.go): `internal/scaffold/scaffold.go`
- [Setup plan](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/plan/plan.go): `internal/plan/plan.go`

### Feature planning

- [Feature lifecycle](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/lifecycle/more.go): `internal/lifecycle/more.go`
- [Spec and design](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/spec/spec.go): `internal/spec/spec.go`
- [Acceptance checks](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/blackbox/blackbox.go): `internal/blackbox/blackbox.go`

### Task execution

- [Scoped task](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/scope/scope.go): `internal/scope/scope.go`
- [Copilot session](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/hooks/session.go): `internal/hooks/session.go`
- [Claude adapter](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/adapters/claude/settings.go): `internal/adapters/claude/settings.go`
- [Kiro adapter](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/adapters/kiro/kiro.go): `internal/adapters/kiro/kiro.go`

### Policy enforcement

- [Edit hooks](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/hooks/guard.go): `internal/hooks/guard.go`
- [Git commit hooks](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/githooks/githooks.go): `internal/githooks/githooks.go`
- [Merge-time CI](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/ci/approval.go): `internal/ci/approval.go`

### Harness operations

- [aih CLI](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [Harness doctor](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/doctor/doctor.go): `internal/doctor/doctor.go`
- [GitHub setup](https://github.com/maneeshchaturvedi/ai-engineering-harness/blob/main/internal/ghsetup/ghsetup.go): `internal/ghsetup/ghsetup.go`

### Other components

- **Person**
- **GitHub Actions**
- **Coding copilot**
- **User repository**

## Connections

- Person → aih CLI: runs commands (evidence: `README.md`)
- aih CLI → Initialize harness: runs init (evidence: `README.md`)
- Initialize harness → Preflight checks: checks repository (evidence: `internal/bootstrap/init.go`)
- Initialize harness → Project detection: detects project (evidence: `internal/bootstrap/init.go`)
- Initialize harness → Setup interview: collects answers (evidence: `internal/bootstrap/init.go`)
- Initialize harness → Harness rendering: renders harness (evidence: `internal/bootstrap/init.go`)
- Initialize harness → Setup plan: previews changes (evidence: `internal/bootstrap/init.go`)
- Initialize harness → Project scaffold: creates project
- Initialize harness → User repository: writes harness (evidence: `README.md`)
- Person → aih CLI: starts feature (evidence: `README.md`)
- aih CLI → Feature lifecycle: advances feature (evidence: `README.md`)
- Feature lifecycle → Spec and design: creates and validates (evidence: `README.md`)
- Person → Spec and design: approves decisions (evidence: `README.md`)
- Feature lifecycle → Acceptance checks: generates checks (evidence: `README.md`)
- Person → Acceptance checks: approves and locks (evidence: `README.md`)
- Feature lifecycle → Scoped task: opens scoped work (evidence: `README.md`)
- Scoped task → Copilot session: sets session context (evidence: `internal/hooks/session.go`)
- Copilot session → Coding copilot: provides design context (evidence: `internal/hooks/session.go`)
- Claude adapter → Edit hooks: configures hooks
- Kiro adapter → Edit hooks: configures hooks
- Coding copilot → Edit hooks: checked during edits (evidence: `README.md`)
- Person → Git commit hooks: commits changes (evidence: `README.md`)
- Git commit hooks → User repository: checks approvals (evidence: `README.md`)
- GitHub Actions → Merge-time CI: runs merge checks (evidence: `README.md`)
- Merge-time CI → User repository: rechecks changes (evidence: `README.md`)
- aih CLI → Harness doctor: checks installation (evidence: `README.md`)
- Initialize harness → Harness doctor: checks setup (evidence: `internal/bootstrap/init.go`)
- Initialize harness → GitHub setup: offers GitHub setup (evidence: `internal/bootstrap/init.go`)
- GitHub setup → GitHub Actions: sets up workflow
