# e1i/mikoshi-construct architecture

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

- Interactive diagram: https://gitdiagram.com/e1i/mikoshi-construct
- Repository: https://github.com/e1i/mikoshi-construct

## Overview

mikoshi-construct is a CLI bootstrap and lifecycle toolkit for AI-native software projects. Its main workflow detects repository facts, lets the user configure a preset and agent target, materializes policy, contracts, harness tooling and agent instructions, then records provenance and model data. The generated repository is handed to an agent for discovery, planning and verified implementation. Separate commands support upkeep and inspection, including sync, doctor, attach/detach, graph, cost and task intake/mutation. Relationships for documented but unsampled subsystems are based on the README; their internal calls are not inferred.

Main entry points: [`src/commands/init.ts`](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/init.ts) (Initialize project), [`src/materialize/plan.ts`](https://github.com/e1i/mikoshi-construct/blob/main/src/materialize/plan.ts) (Plan materialization), [`src/commands/doctor/index.ts`](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/doctor/index.ts) (Repository doctor), [`scripts`](https://github.com/e1i/mikoshi-construct/tree/main/scripts) (Quality harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Project Bootstrap"]
  node_cli["Construct CLI<br/>[program.ts]"]
  node_init["Initialize project<br/>[init.ts]"]
  node_detect["Detect repository<br/>[index.ts]"]
  node_presets["Preset configuration<br/>[index.ts]"]
  node_materialize["Plan materialization<br/>[plan.ts]"]
  node_templates["Project templates"]
end

subgraph group_records["Project Records"]
  node_manifest[("Provenance manifest<br/>[manifest.ts]")]
  node_model["Knowledge model<br/>[schema.ts]"]
end

subgraph group_maintenance["Repository Maintenance"]
  node_sync["Template sync<br/>[replay.ts]"]
  node_doctor["Repository doctor<br/>[index.ts]"]
  node_attach["Attach workflow<br/>[index.ts]"]
  node_detach["Detach workflow<br/>[index.ts]"]
end

subgraph group_agent["Agent Lifecycle"]
  node_agentfiles["Agent instructions<br/>[lore.ts]"]
  node_harness["Quality harness"]
  node_discovery["Repository discovery"]
end

subgraph group_inspection["Inspection Tools"]
  node_graph["Model graph<br/>[graph.ts]"]
  node_intake["Task intake<br/>[index.ts]"]
  node_mutate["Mutation tools<br/>[index.ts]"]
  node_cost["Usage reporting<br/>[index.ts]"]
  node_board["Work board<br/>[index.ts]"]
end

node_user(("Project owner"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches init"| node_init
node_init -->|"detects facts"| node_detect
node_init -->|"configures preset"| node_presets
node_init -->|"plans files"| node_materialize
node_presets -.->|"selects groups"| node_materialize
node_materialize -->|"renders templates"| node_templates
node_init -->|"records provenance"| node_manifest
node_init -->|"reads model"| node_model
node_materialize -.->|"materializes instructions"| node_agentfiles
node_materialize -.->|"materializes harness"| node_harness
node_user -->|"hands off repository"| node_discovery
node_discovery -->|"fills markers"| node_agentfiles
node_user -->|"requests sync"| node_sync
node_sync -->|"replays provenance"| node_manifest
node_user -->|"requests checks"| node_doctor
node_doctor -->|"reads records"| node_manifest
node_doctor -->|"reads records"| node_model
node_user -->|"requests attach"| node_attach
node_user -->|"requests detach"| node_detach
node_user -->|"requests graph"| node_graph
node_graph -->|"draws model"| node_model
node_user -->|"starts planning"| node_intake
node_user -->|"records mutations"| node_mutate
node_user -->|"requests usage"| node_cost
node_user -.->|"views work"| node_board
node_intake -->|"defines acceptance"| node_harness
node_harness -->|"verifies implementation"| node_agentfiles

click node_cli "https://github.com/e1i/mikoshi-construct/blob/main/src/program.ts"
click node_init "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/init.ts"
click node_detect "https://github.com/e1i/mikoshi-construct/blob/main/src/detect/index.ts"
click node_presets "https://github.com/e1i/mikoshi-construct/blob/main/src/presets/index.ts"
click node_materialize "https://github.com/e1i/mikoshi-construct/blob/main/src/materialize/plan.ts"
click node_templates "https://github.com/e1i/mikoshi-construct/tree/main/templates"
click node_manifest "https://github.com/e1i/mikoshi-construct/blob/main/src/manifest.ts"
click node_model "https://github.com/e1i/mikoshi-construct/blob/main/src/model/schema.ts"
click node_sync "https://github.com/e1i/mikoshi-construct/blob/main/src/sync/replay.ts"
click node_doctor "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/doctor/index.ts"
click node_attach "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/attach/index.ts"
click node_detach "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/detach/index.ts"
click node_agentfiles "https://github.com/e1i/mikoshi-construct/blob/main/src/ui/lore.ts"
click node_harness "https://github.com/e1i/mikoshi-construct/tree/main/scripts"
click node_discovery "https://github.com/e1i/mikoshi-construct/tree/main/templates/ai"
click node_graph "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/graph.ts"
click node_intake "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/intake/index.ts"
click node_mutate "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/mutate/index.ts"
click node_cost "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/cost/index.ts"
click node_board "https://github.com/e1i/mikoshi-construct/blob/main/src/commands/board/index.ts"

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_init,node_detect,node_presets,node_materialize,node_templates toneBlue
class node_manifest,node_model toneAmber
class node_sync,node_doctor,node_attach,node_detach toneMint
class node_agentfiles,node_harness,node_discovery toneRose
class node_graph,node_intake,node_mutate,node_cost,node_board,node_user toneIndigo
```

## Components

### Project Bootstrap

- [Construct CLI](https://github.com/e1i/mikoshi-construct/blob/main/src/program.ts): `src/program.ts`
- [Initialize project](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/init.ts): `src/commands/init.ts`
- [Detect repository](https://github.com/e1i/mikoshi-construct/blob/main/src/detect/index.ts): `src/detect/index.ts`
- [Preset configuration](https://github.com/e1i/mikoshi-construct/blob/main/src/presets/index.ts): `src/presets/index.ts`
- [Plan materialization](https://github.com/e1i/mikoshi-construct/blob/main/src/materialize/plan.ts): `src/materialize/plan.ts`
- [Project templates](https://github.com/e1i/mikoshi-construct/tree/main/templates): `templates`

### Project Records

- [Provenance manifest](https://github.com/e1i/mikoshi-construct/blob/main/src/manifest.ts): `src/manifest.ts`
- [Knowledge model](https://github.com/e1i/mikoshi-construct/blob/main/src/model/schema.ts): `src/model/schema.ts`

### Repository Maintenance

- [Template sync](https://github.com/e1i/mikoshi-construct/blob/main/src/sync/replay.ts): `src/sync/replay.ts`
- [Repository doctor](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/doctor/index.ts): `src/commands/doctor/index.ts`
- [Attach workflow](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/attach/index.ts): `src/commands/attach/index.ts`
- [Detach workflow](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/detach/index.ts): `src/commands/detach/index.ts`

### Agent Lifecycle

- [Agent instructions](https://github.com/e1i/mikoshi-construct/blob/main/src/ui/lore.ts): `src/ui/lore.ts`
- [Quality harness](https://github.com/e1i/mikoshi-construct/tree/main/scripts): `scripts`
- [Repository discovery](https://github.com/e1i/mikoshi-construct/tree/main/templates/ai): `templates/ai`

### Inspection Tools

- [Model graph](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/graph.ts): `src/commands/graph.ts`
- [Task intake](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/intake/index.ts): `src/commands/intake/index.ts`
- [Mutation tools](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/mutate/index.ts): `src/commands/mutate/index.ts`
- [Usage reporting](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/cost/index.ts): `src/commands/cost/index.ts`
- [Work board](https://github.com/e1i/mikoshi-construct/blob/main/src/commands/board/index.ts): `src/commands/board/index.ts`

### Other components

- **Project owner**

## Connections

- Project owner → Construct CLI: runs commands (evidence: `README.md`)
- Construct CLI → Initialize project: dispatches init (evidence: `src/program.ts`)
- Initialize project → Detect repository: detects facts (evidence: `src/commands/init.ts`)
- Initialize project → Preset configuration: configures preset (evidence: `src/commands/init.ts`)
- Initialize project → Plan materialization: plans files (evidence: `src/commands/init.ts`)
- Preset configuration → Plan materialization: selects groups (evidence: `src/materialize/plan.ts`)
- Plan materialization → Project templates: renders templates (evidence: `src/materialize/plan.ts`)
- Initialize project → Provenance manifest: records provenance (evidence: `src/commands/init.ts`)
- Initialize project → Knowledge model: reads model (evidence: `src/commands/init.ts`)
- Plan materialization → Agent instructions: materializes instructions (evidence: `README.md`)
- Plan materialization → Quality harness: materializes harness (evidence: `README.md`)
- Project owner → Repository discovery: hands off repository (evidence: `README.md`)
- Repository discovery → Agent instructions: fills markers (evidence: `README.md`)
- Project owner → Template sync: requests sync (evidence: `README.md`)
- Template sync → Provenance manifest: replays provenance (evidence: `README.md`)
- Project owner → Repository doctor: requests checks (evidence: `README.md`)
- Repository doctor → Provenance manifest: reads records (evidence: `README.md`)
- Repository doctor → Knowledge model: reads records (evidence: `README.md`)
- Project owner → Attach workflow: requests attach (evidence: `README.md`)
- Project owner → Detach workflow: requests detach (evidence: `README.md`)
- Project owner → Model graph: requests graph (evidence: `README.md`)
- Model graph → Knowledge model: draws model (evidence: `README.md`)
- Project owner → Task intake: starts planning (evidence: `README.md`)
- Project owner → Mutation tools: records mutations (evidence: `README.md`)
- Project owner → Usage reporting: requests usage (evidence: `README.md`)
- Project owner → Work board: views work
- Task intake → Quality harness: defines acceptance (evidence: `README.md`)
- Quality harness → Agent instructions: verifies implementation (evidence: `README.md`)
