# zomarit/stamity architecture

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

- Interactive diagram: https://gitdiagram.com/zomarit/stamity
- Repository: https://github.com/zomarit/stamity

## Overview

stamity is a TypeScript CLI that turns one canonical agent-setup corpus into client-specific coding environments. The principal workflow is: run `init` to inspect a repository and create setup state, then `sync` to plan and write generated artifacts; `check` and `validate` provide verification. Separate capabilities manage packs, plugins, workspaces, worktrees, and agent handoffs. The README documents these product-level relationships; source excerpts and the index additionally support selected internal links. Several subsystem implementations were not sampled, so their internal calls are not inferred.

Main entry points: [`src/cli/kit/program.ts`](https://github.com/zomarit/stamity/blob/main/src/cli/kit/program.ts) (CLI program), [`src/cli/commands/sync.ts`](https://github.com/zomarit/stamity/blob/main/src/cli/commands/sync.ts) (Sync setup), [`src/emit/planner.ts`](https://github.com/zomarit/stamity/blob/main/src/emit/planner.ts) (Emission planner), [`src/manifest/manifest.ts`](https://github.com/zomarit/stamity/blob/main/src/manifest/manifest.ts) (Setup manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["CLI program<br/>[program.ts]"]
  node_init["Initialize setup<br/>[init.ts]"]
  node_sync["Sync setup<br/>[sync.ts]"]
  node_check["Check setup<br/>[check.ts]"]
  node_validate["Validate inputs<br/>[validate.ts]"]
end

subgraph group_generation["Setup generation"]
  node_repoanalysis["Repository analysis<br/>[repoAnalyzer.ts]"]
  node_corpus["Canonical corpus<br/>[catalog.ts]"]
  node_frontmatter["Artifact parsing<br/>[frontmatter.ts]"]
  node_planner["Emission planner<br/>[planner.ts]"]
  node_clientadapters["Client adapters"]
  node_managedwrites["Managed file writes<br/>[managedBlocks.ts]"]
end

subgraph group_state["Setup state"]
  node_manifest[("Setup manifest<br/>[manifest.ts]")]
  node_ledger[("File ownership ledger<br/>[ledger.ts]")]
  node_workspace["Workspace management<br/>[sync.ts]"]
  node_worktrees["Git worktrees<br/>[setup.ts]"]
end

subgraph group_extensions["Extensions and integrations"]
  node_packinstall["Pack installation<br/>[install.ts]"]
  node_packtrust["Pack trust and signing<br/>[trust.ts]"]
  node_plugins["Plugin support<br/>[capabilityFile.ts]"]
  node_mcp["MCP wiring<br/>[emit.ts]"]
  node_safety["Content safety scans<br/>[denyScan.ts]"]
end

subgraph group_agentops["Agent operations"]
  node_hooks["Hooks and commands<br/>[scripts.ts]"]
  node_learnings[("Learnings<br/>[store.ts]")]
  node_handoffs[("Handoffs<br/>[store.ts]")]
  node_runledger[("Run ledger<br/>[ledgerStore.ts]")]
end

node_operator(("Repository operator"))

node_operator -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_sync
node_cli -->|"dispatches"| node_check
node_cli -->|"dispatches"| node_validate
node_init -.->|"inspects repository"| node_repoanalysis
node_init -->|"creates setup state"| node_manifest
node_sync -->|"reads setup state"| node_manifest
node_sync -->|"plans output"| node_planner
node_corpus -->|"parses artifacts"| node_frontmatter
node_planner -->|"selects content"| node_corpus
node_planner -->|"projects setup"| node_clientadapters
node_clientadapters -->|"emits managed blocks"| node_managedwrites
node_planner -->|"plans MCP output"| node_mcp
node_mcp -->|"reads MCP selection"| node_manifest
node_sync -->|"records ownership"| node_ledger
node_sync -->|"writes generated files"| node_managedwrites
node_check -->|"checks setup"| node_manifest
node_validate -.->|"validates content"| node_corpus
node_operator -->|"adds packs"| node_packinstall
node_packinstall -.->|"verifies signed packs"| node_packtrust
node_operator -->|"manages plugins"| node_plugins
node_operator -->|"manages workspace"| node_workspace
node_operator -->|"sets up worktrees"| node_worktrees
node_hooks -->|"validates handoffs"| node_handoffs
node_hooks -->|"validates learnings"| node_learnings
node_hooks -->|"uses run records"| node_runledger
node_handoffs -->|"scans submissions"| node_safety
node_learnings -->|"scans submissions"| node_safety

click node_cli "https://github.com/zomarit/stamity/blob/main/src/cli/kit/program.ts"
click node_init "https://github.com/zomarit/stamity/blob/main/src/cli/commands/init.ts"
click node_sync "https://github.com/zomarit/stamity/blob/main/src/cli/commands/sync.ts"
click node_check "https://github.com/zomarit/stamity/blob/main/src/cli/commands/check.ts"
click node_validate "https://github.com/zomarit/stamity/blob/main/src/cli/commands/validate.ts"
click node_repoanalysis "https://github.com/zomarit/stamity/blob/main/src/detect/repoAnalyzer.ts"
click node_corpus "https://github.com/zomarit/stamity/blob/main/src/content/catalog.ts"
click node_frontmatter "https://github.com/zomarit/stamity/blob/main/src/content/frontmatter.ts"
click node_planner "https://github.com/zomarit/stamity/blob/main/src/emit/planner.ts"
click node_clientadapters "https://github.com/zomarit/stamity/tree/main/src/adapters"
click node_managedwrites "https://github.com/zomarit/stamity/blob/main/src/merge/managedBlocks.ts"
click node_manifest "https://github.com/zomarit/stamity/blob/main/src/manifest/manifest.ts"
click node_ledger "https://github.com/zomarit/stamity/blob/main/src/manifest/ledger.ts"
click node_workspace "https://github.com/zomarit/stamity/blob/main/src/workspace/sync.ts"
click node_worktrees "https://github.com/zomarit/stamity/blob/main/src/worktree/setup.ts"
click node_packinstall "https://github.com/zomarit/stamity/blob/main/src/pack/install.ts"
click node_packtrust "https://github.com/zomarit/stamity/blob/main/src/pack/trust.ts"
click node_plugins "https://github.com/zomarit/stamity/blob/main/src/plugins/capabilityFile.ts"
click node_mcp "https://github.com/zomarit/stamity/blob/main/src/mcp/emit.ts"
click node_safety "https://github.com/zomarit/stamity/blob/main/src/denyscan/denyScan.ts"
click node_hooks "https://github.com/zomarit/stamity/blob/main/src/hooks/scripts.ts"
click node_learnings "https://github.com/zomarit/stamity/blob/main/src/learnings/store.ts"
click node_handoffs "https://github.com/zomarit/stamity/blob/main/src/handoffs/store.ts"
click node_runledger "https://github.com/zomarit/stamity/blob/main/src/runs/ledgerStore.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_sync,node_check,node_validate toneBlue
class node_repoanalysis,node_corpus,node_frontmatter,node_planner,node_clientadapters,node_managedwrites toneAmber
class node_manifest,node_ledger,node_workspace,node_worktrees toneMint
class node_packinstall,node_packtrust,node_plugins,node_mcp,node_safety toneRose
class node_hooks,node_learnings,node_handoffs,node_runledger,node_operator toneIndigo
```

## Components

### CLI workflow

- [CLI program](https://github.com/zomarit/stamity/blob/main/src/cli/kit/program.ts): `src/cli/kit/program.ts`
- [Initialize setup](https://github.com/zomarit/stamity/blob/main/src/cli/commands/init.ts): `src/cli/commands/init.ts`
- [Sync setup](https://github.com/zomarit/stamity/blob/main/src/cli/commands/sync.ts): `src/cli/commands/sync.ts`
- [Check setup](https://github.com/zomarit/stamity/blob/main/src/cli/commands/check.ts): `src/cli/commands/check.ts`
- [Validate inputs](https://github.com/zomarit/stamity/blob/main/src/cli/commands/validate.ts): `src/cli/commands/validate.ts`

### Setup generation

- [Repository analysis](https://github.com/zomarit/stamity/blob/main/src/detect/repoAnalyzer.ts): `src/detect/repoAnalyzer.ts`
- [Canonical corpus](https://github.com/zomarit/stamity/blob/main/src/content/catalog.ts): `src/content/catalog.ts`
- [Artifact parsing](https://github.com/zomarit/stamity/blob/main/src/content/frontmatter.ts): `src/content/frontmatter.ts`
- [Emission planner](https://github.com/zomarit/stamity/blob/main/src/emit/planner.ts): `src/emit/planner.ts`
- [Client adapters](https://github.com/zomarit/stamity/tree/main/src/adapters): `src/adapters`
- [Managed file writes](https://github.com/zomarit/stamity/blob/main/src/merge/managedBlocks.ts): `src/merge/managedBlocks.ts`

### Setup state

- [Setup manifest](https://github.com/zomarit/stamity/blob/main/src/manifest/manifest.ts): `src/manifest/manifest.ts`
- [File ownership ledger](https://github.com/zomarit/stamity/blob/main/src/manifest/ledger.ts): `src/manifest/ledger.ts`
- [Workspace management](https://github.com/zomarit/stamity/blob/main/src/workspace/sync.ts): `src/workspace/sync.ts`
- [Git worktrees](https://github.com/zomarit/stamity/blob/main/src/worktree/setup.ts): `src/worktree/setup.ts`

### Extensions and integrations

- [Pack installation](https://github.com/zomarit/stamity/blob/main/src/pack/install.ts): `src/pack/install.ts`
- [Pack trust and signing](https://github.com/zomarit/stamity/blob/main/src/pack/trust.ts): `src/pack/trust.ts`
- [Plugin support](https://github.com/zomarit/stamity/blob/main/src/plugins/capabilityFile.ts): `src/plugins/capabilityFile.ts`
- [MCP wiring](https://github.com/zomarit/stamity/blob/main/src/mcp/emit.ts): `src/mcp/emit.ts`
- [Content safety scans](https://github.com/zomarit/stamity/blob/main/src/denyscan/denyScan.ts): `src/denyscan/denyScan.ts`

### Agent operations

- [Hooks and commands](https://github.com/zomarit/stamity/blob/main/src/hooks/scripts.ts): `src/hooks/scripts.ts`
- [Learnings](https://github.com/zomarit/stamity/blob/main/src/learnings/store.ts): `src/learnings/store.ts`
- [Handoffs](https://github.com/zomarit/stamity/blob/main/src/handoffs/store.ts): `src/handoffs/store.ts`
- [Run ledger](https://github.com/zomarit/stamity/blob/main/src/runs/ledgerStore.ts): `src/runs/ledgerStore.ts`

### Other components

- **Repository operator**

## Connections

- Repository operator → CLI program: invokes (evidence: `README.md`)
- CLI program → Initialize setup: dispatches (evidence: `src/cli/kit/program.ts`)
- CLI program → Sync setup: dispatches (evidence: `src/cli/kit/program.ts`)
- CLI program → Check setup: dispatches (evidence: `src/cli/kit/program.ts`)
- CLI program → Validate inputs: dispatches (evidence: `src/cli/kit/program.ts`)
- Initialize setup → Repository analysis: inspects repository
- Initialize setup → Setup manifest: creates setup state (evidence: `README.md`)
- Sync setup → Setup manifest: reads setup state (evidence: `README.md`)
- Sync setup → Emission planner: plans output
- Canonical corpus → Artifact parsing: parses artifacts (evidence: `src/content/catalog.ts`)
- Emission planner → Canonical corpus: selects content (evidence: `src/emit/planner.ts`)
- Emission planner → Client adapters: projects setup (evidence: `src/emit/planner.ts`)
- Client adapters → Managed file writes: emits managed blocks (evidence: `src/adapters/claude.ts`)
- Emission planner → MCP wiring: plans MCP output (evidence: `src/emit/planner.ts`)
- MCP wiring → Setup manifest: reads MCP selection (evidence: `src/mcp/emit.ts`)
- Sync setup → File ownership ledger: records ownership
- Sync setup → Managed file writes: writes generated files
- Check setup → Setup manifest: checks setup (evidence: `README.md`)
- Validate inputs → Canonical corpus: validates content
- Repository operator → Pack installation: adds packs (evidence: `README.md`)
- Pack installation → Pack trust and signing: verifies signed packs
- Repository operator → Plugin support: manages plugins (evidence: `README.md`)
- Repository operator → Workspace management: manages workspace (evidence: `README.md`)
- Repository operator → Git worktrees: sets up worktrees (evidence: `README.md`)
- Hooks and commands → Handoffs: validates handoffs
- Hooks and commands → Learnings: validates learnings
- Hooks and commands → Run ledger: uses run records
- Handoffs → Content safety scans: scans submissions
- Learnings → Content safety scans: scans submissions
