# aicspec/aic architecture

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

- Interactive diagram: https://gitdiagram.com/aicspec/aic
- Repository: https://github.com/aicspec/aic

## Overview

AIC is a TypeScript library and CLI for authoring, inspecting, and checking YAML Architecture Implementation Contracts. The main workflow is to load or bundle a contract, parse and model it, validate its rules and maturity, then produce agent briefs, implementation plans, verification checklists, and conformance verdicts. The repository also ships contract documentation and agent skill prompts. Edges reflect the shown imports, calls, exports, and README descriptions; some CLI dispatch details and skill internals were not sampled, so those relationships are omitted or documented only where supported.

Main entry points: [`src/cli.ts`](https://github.com/aicspec/aic/blob/main/src/cli.ts) (AIC CLI), [`src/index.ts`](https://github.com/aicspec/aic/blob/main/src/index.ts) (Library API), [`src/core/model.ts`](https://github.com/aicspec/aic/blob/main/src/core/model.ts) (Contract model), [`src/agent/brief.ts`](https://github.com/aicspec/aic/blob/main/src/agent/brief.ts) (Module briefs and plans)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and agent workflow"]
  node_cli["AIC CLI<br/>[cli.ts]"]
  node_public["Library API<br/>[index.ts]"]
  node_brief["Module briefs and plans<br/>[brief.ts]"]
  node_report["Validation report<br/>[report.ts]"]
  node_checklist["Verification checklist and verdict<br/>[verify.ts]"]
end

subgraph group_contract["Contract processing"]
  node_contract_reader["Agent contract reader<br/>[contract.ts]"]
  node_bundler["Reference bundler<br/>[bundle.ts]"]
  node_yaml["YAML parser and writer<br/>[yaml.ts]"]
  node_model["Contract model<br/>[model.ts]"]
  node_schema["Contract schema"]
end

subgraph group_analysis["Architecture analysis"]
  node_validator["Contract validator<br/>[validate.ts]"]
  node_maturity["Maturity analysis<br/>[maturity.ts]"]
end

subgraph group_resources["Shipped resources"]
  node_docs["Reference documents<br/>[documents.ts]"]
  node_skills["Agent skill prompts"]
end

node_engineer(("Engineer or agent"))
node_contract_files["Contract YAML files"]
node_results["Checklist results"]

node_engineer -->|"runs commands"| node_cli
node_contract_files -->|"provides contract"| node_cli
node_cli -->|"bundles references"| node_bundler
node_cli -->|"loads and writes"| node_yaml
node_cli -->|"requests plans"| node_brief
node_cli -->|"requests reports"| node_report
node_cli -->|"requests checks"| node_checklist
node_cli -->|"reads references"| node_docs
node_cli -->|"installs prompts"| node_skills
node_cli -->|"reads results"| node_results
node_contract_reader -->|"parses text"| node_yaml
node_yaml -->|"uses schema helpers"| node_model
node_model -->|"loads schema"| node_schema
node_validator -->|"inspects contract"| node_model
node_maturity -->|"inspects contract"| node_model
node_brief -->|"derives module context"| node_model
node_brief -->|"computes readiness"| node_maturity
node_brief -->|"checks violations"| node_validator
node_report -->|"validates contract"| node_validator
node_report -->|"summarizes maturity"| node_maturity
node_checklist -->|"builds checks"| node_model
node_checklist -->|"reuses interface data"| node_brief
node_public -->|"exports model"| node_model
node_public -->|"exports YAML tools"| node_yaml
node_public -->|"exports validation"| node_validator
node_public -->|"exports maturity"| node_maturity
node_public -->|"exports bundler"| node_bundler
node_public -->|"exports agent briefs"| node_brief
node_public -->|"exports reports"| node_report
node_public -->|"exports verification"| node_checklist

click node_cli "https://github.com/aicspec/aic/blob/main/src/cli.ts"
click node_public "https://github.com/aicspec/aic/blob/main/src/index.ts"
click node_brief "https://github.com/aicspec/aic/blob/main/src/agent/brief.ts"
click node_report "https://github.com/aicspec/aic/blob/main/src/agent/report.ts"
click node_checklist "https://github.com/aicspec/aic/blob/main/src/agent/verify.ts"
click node_contract_reader "https://github.com/aicspec/aic/blob/main/src/agent/contract.ts"
click node_bundler "https://github.com/aicspec/aic/blob/main/src/core/bundle.ts"
click node_yaml "https://github.com/aicspec/aic/blob/main/src/core/yaml.ts"
click node_model "https://github.com/aicspec/aic/blob/main/src/core/model.ts"
click node_schema "https://github.com/aicspec/aic/blob/main/schema/aic-contract-0.1.schema.json"
click node_validator "https://github.com/aicspec/aic/blob/main/src/core/validate.ts"
click node_maturity "https://github.com/aicspec/aic/blob/main/src/core/maturity.ts"
click node_docs "https://github.com/aicspec/aic/blob/main/src/documents.ts"
click node_skills "https://github.com/aicspec/aic/tree/main/skills/aic"

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_cli,node_public,node_brief,node_report,node_checklist toneBlue
class node_contract_reader,node_bundler,node_yaml,node_model,node_schema toneAmber
class node_validator,node_maturity toneMint
class node_docs,node_skills toneRose
class node_engineer,node_contract_files,node_results toneIndigo
```

## Components

### CLI and agent workflow

- [AIC CLI](https://github.com/aicspec/aic/blob/main/src/cli.ts): `src/cli.ts`
- [Library API](https://github.com/aicspec/aic/blob/main/src/index.ts): `src/index.ts`
- [Module briefs and plans](https://github.com/aicspec/aic/blob/main/src/agent/brief.ts): `src/agent/brief.ts`
- [Validation report](https://github.com/aicspec/aic/blob/main/src/agent/report.ts): `src/agent/report.ts`
- [Verification checklist and verdict](https://github.com/aicspec/aic/blob/main/src/agent/verify.ts): `src/agent/verify.ts`

### Contract processing

- [Agent contract reader](https://github.com/aicspec/aic/blob/main/src/agent/contract.ts): `src/agent/contract.ts`
- [Reference bundler](https://github.com/aicspec/aic/blob/main/src/core/bundle.ts): `src/core/bundle.ts`
- [YAML parser and writer](https://github.com/aicspec/aic/blob/main/src/core/yaml.ts): `src/core/yaml.ts`
- [Contract model](https://github.com/aicspec/aic/blob/main/src/core/model.ts): `src/core/model.ts`
- [Contract schema](https://github.com/aicspec/aic/blob/main/schema/aic-contract-0.1.schema.json): `schema/aic-contract-0.1.schema.json`

### Architecture analysis

- [Contract validator](https://github.com/aicspec/aic/blob/main/src/core/validate.ts): `src/core/validate.ts`
- [Maturity analysis](https://github.com/aicspec/aic/blob/main/src/core/maturity.ts): `src/core/maturity.ts`

### Shipped resources

- [Reference documents](https://github.com/aicspec/aic/blob/main/src/documents.ts): `src/documents.ts`
- [Agent skill prompts](https://github.com/aicspec/aic/tree/main/skills/aic): `skills/aic`

### Other components

- **Engineer or agent**
- **Contract YAML files**
- **Checklist results**

## Connections

- Engineer or agent → AIC CLI: runs commands (evidence: `README.md`)
- Contract YAML files → AIC CLI: provides contract (evidence: `src/cli.ts`)
- AIC CLI → Reference bundler: bundles references (evidence: `src/cli.ts`)
- AIC CLI → YAML parser and writer: loads and writes (evidence: `src/cli.ts`)
- AIC CLI → Module briefs and plans: requests plans (evidence: `src/cli.ts`)
- AIC CLI → Validation report: requests reports (evidence: `src/cli.ts`)
- AIC CLI → Verification checklist and verdict: requests checks (evidence: `src/cli.ts`)
- AIC CLI → Reference documents: reads references (evidence: `src/cli.ts`)
- AIC CLI → Agent skill prompts: installs prompts (evidence: `src/cli.ts`)
- AIC CLI → Checklist results: reads results (evidence: `src/cli.ts`)
- Agent contract reader → YAML parser and writer: parses text (evidence: `src/agent/contract.ts`)
- YAML parser and writer → Contract model: uses schema helpers (evidence: `src/core/yaml.ts`)
- Contract model → Contract schema: loads schema (evidence: `src/core/model.ts`)
- Contract validator → Contract model: inspects contract (evidence: `src/core/validate.ts`)
- Maturity analysis → Contract model: inspects contract (evidence: `src/core/maturity.ts`)
- Module briefs and plans → Contract model: derives module context (evidence: `src/agent/brief.ts`)
- Module briefs and plans → Maturity analysis: computes readiness (evidence: `src/agent/brief.ts`)
- Module briefs and plans → Contract validator: checks violations (evidence: `src/agent/brief.ts`)
- Validation report → Contract validator: validates contract (evidence: `src/agent/report.ts`)
- Validation report → Maturity analysis: summarizes maturity (evidence: `src/agent/report.ts`)
- Verification checklist and verdict → Contract model: builds checks (evidence: `src/agent/verify.ts`)
- Verification checklist and verdict → Module briefs and plans: reuses interface data (evidence: `src/agent/verify.ts`)
- Library API → Contract model: exports model (evidence: `src/index.ts`)
- Library API → YAML parser and writer: exports YAML tools (evidence: `src/index.ts`)
- Library API → Contract validator: exports validation (evidence: `src/index.ts`)
- Library API → Maturity analysis: exports maturity (evidence: `src/index.ts`)
- Library API → Reference bundler: exports bundler (evidence: `src/index.ts`)
- Library API → Module briefs and plans: exports agent briefs (evidence: `src/index.ts`)
- Library API → Validation report: exports reports (evidence: `src/index.ts`)
- Library API → Verification checklist and verdict: exports verification (evidence: `src/index.ts`)