# an0099/toothpaste-kit architecture

> Architecture diagram of the GitHub repository an0099/toothpaste-kit, 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/an0099/toothpaste-kit
- Repository: https://github.com/an0099/toothpaste-kit

## Overview

Toothpaste Kit is a human-governed toolkit for multi-agent work: skills guide agent and person workflows, while a relay protocol defines cross-surface handoffs and sensitivity-aware routing. Its main workflow is a person or lead agent invoking a skill or protocol to coordinate work, preserve legible state, and halt for human decisions at gates. The README documents substantial skills, orchestration, registry, schemas, and example-workspace capabilities; these are represented at their exact directories where implementation excerpts were unavailable. Sampled scripts are peripheral mechanical checks, not the product runtime.

Main entry points: [`orchestration/protocol.md`](https://github.com/an0099/toothpaste-kit/blob/main/orchestration/protocol.md) (Relay Protocol), [`docs/standing-documents.md`](https://github.com/an0099/toothpaste-kit/blob/main/docs/standing-documents.md) (Standing Documents), [`scripts/check-workspace-stubs.py`](https://github.com/an0099/toothpaste-kit/blob/main/scripts/check-workspace-stubs.py) (Stub Checker), [`skills/session-close`](https://github.com/an0099/toothpaste-kit/tree/main/skills/session-close) (Session Procedures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_skills["Agent Skills"]
  node_behavior["Behavior Skills"]
  node_writing["Document Skills"]
  node_surface["Surface Regimes"]
  node_creation["Skill Lifecycle"]
  node_discovery["Skill Discovery"]
  node_session["Session Procedures"]
  node_reviews["Review Procedures"]
  node_capture["Capture Procedures"]
  node_redaction{{"Redaction Gate"}}
end

subgraph group_relay["Agent Relay"]
  node_relayprotocol["Relay Protocol<br/>[protocol.md]"]
  node_routing{{"Sensitivity Routing"}}
  node_taxonomy["Capability Taxonomy<br/>[taxonomy.md]"]
  node_registry[("Surface Registry")]
  node_schemas["Message Schemas"]
  node_handoff["Handoff Templates"]
end

subgraph group_workspace["Workspace State"]
  node_workspace["Workspace Stubs"]
  node_standing["Standing Documents"]
end

subgraph group_mechanics["Mechanical Gates"]
  node_hooks["Hook Rules"]
  node_lint["Markdown Linter<br/>[mdlint.py]"]
  node_reflow["Markdown Reflow<br/>[reflow-md.py]"]
  node_stubcheck["Stub Checker"]
end

node_person(("Person"))
node_lead(("Lead Agent"))

node_person -->|"invokes"| node_session
node_person -->|"invokes"| node_reviews
node_person -->|"decides at"| node_redaction
node_lead -->|"loads"| node_behavior
node_lead -->|"loads"| node_writing
node_lead -->|"detects regime"| node_surface
node_lead -->|"uses"| node_creation
node_lead -->|"uses"| node_discovery
node_lead -->|"records with"| node_capture
node_lead -->|"relays work"| node_relayprotocol
node_relayprotocol -->|"gates dispatch"| node_routing
node_relayprotocol -->|"uses messages"| node_schemas
node_relayprotocol -.->|"consults surfaces"| node_registry
node_relayprotocol -.->|"classifies capability"| node_taxonomy
node_relayprotocol -.->|"uses templates"| node_handoff
node_session -->|"updates"| node_standing
node_reviews -->|"reads"| node_standing
node_workspace -->|"stubs describe"| node_standing
node_hooks -.->|"warns on reads"| node_redaction
node_person -.->|"checks documents"| node_lint
node_person -.->|"reflows documents"| node_reflow
node_stubcheck -->|"checks names"| node_workspace
node_stubcheck -->|"checks listing"| node_standing

click node_behavior "https://github.com/an0099/toothpaste-kit/tree/main/skills/working-preferences"
click node_writing "https://github.com/an0099/toothpaste-kit/tree/main/skills/document-standards"
click node_surface "https://github.com/an0099/toothpaste-kit/tree/main/skills/surface-regimes"
click node_creation "https://github.com/an0099/toothpaste-kit/tree/main/skills/skill-creation"
click node_discovery "https://github.com/an0099/toothpaste-kit/tree/main/skills/skill-discovery"
click node_session "https://github.com/an0099/toothpaste-kit/tree/main/skills/session-close"
click node_reviews "https://github.com/an0099/toothpaste-kit/tree/main/skills/daily-review"
click node_capture "https://github.com/an0099/toothpaste-kit/tree/main/skills/session-log"
click node_redaction "https://github.com/an0099/toothpaste-kit/tree/main/skills/redaction-gate"
click node_relayprotocol "https://github.com/an0099/toothpaste-kit/blob/main/orchestration/protocol.md"
click node_routing "https://github.com/an0099/toothpaste-kit/blob/main/orchestration/ROUTING-THRESHOLD.md"
click node_taxonomy "https://github.com/an0099/toothpaste-kit/blob/main/orchestration/taxonomy.md"
click node_registry "https://github.com/an0099/toothpaste-kit/tree/main/orchestration/registry"
click node_schemas "https://github.com/an0099/toothpaste-kit/tree/main/orchestration/schemas"
click node_handoff "https://github.com/an0099/toothpaste-kit/tree/main/orchestration/templates"
click node_workspace "https://github.com/an0099/toothpaste-kit/tree/main/examples/workspace"
click node_standing "https://github.com/an0099/toothpaste-kit/blob/main/docs/standing-documents.md"
click node_hooks "https://github.com/an0099/toothpaste-kit/tree/main/hooks"
click node_lint "https://github.com/an0099/toothpaste-kit/blob/main/scripts/mdlint.py"
click node_reflow "https://github.com/an0099/toothpaste-kit/blob/main/scripts/reflow-md.py"
click node_stubcheck "https://github.com/an0099/toothpaste-kit/blob/main/scripts/check-workspace-stubs.py"

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_behavior,node_writing,node_surface,node_creation,node_discovery,node_session,node_reviews,node_capture,node_redaction toneBlue
class node_relayprotocol,node_routing,node_taxonomy,node_registry,node_schemas,node_handoff toneAmber
class node_workspace,node_standing toneMint
class node_hooks,node_lint,node_reflow,node_stubcheck toneRose
class node_person,node_lead toneIndigo
```

## Components

### Agent Skills

- [Behavior Skills](https://github.com/an0099/toothpaste-kit/tree/main/skills/working-preferences): `skills/working-preferences`
- [Document Skills](https://github.com/an0099/toothpaste-kit/tree/main/skills/document-standards): `skills/document-standards`
- [Surface Regimes](https://github.com/an0099/toothpaste-kit/tree/main/skills/surface-regimes): `skills/surface-regimes`
- [Skill Lifecycle](https://github.com/an0099/toothpaste-kit/tree/main/skills/skill-creation): `skills/skill-creation`
- [Skill Discovery](https://github.com/an0099/toothpaste-kit/tree/main/skills/skill-discovery): `skills/skill-discovery`
- [Session Procedures](https://github.com/an0099/toothpaste-kit/tree/main/skills/session-close): `skills/session-close`
- [Review Procedures](https://github.com/an0099/toothpaste-kit/tree/main/skills/daily-review): `skills/daily-review`
- [Capture Procedures](https://github.com/an0099/toothpaste-kit/tree/main/skills/session-log): `skills/session-log`
- [Redaction Gate](https://github.com/an0099/toothpaste-kit/tree/main/skills/redaction-gate): `skills/redaction-gate`

### Agent Relay

- [Relay Protocol](https://github.com/an0099/toothpaste-kit/blob/main/orchestration/protocol.md): `orchestration/protocol.md`
- [Sensitivity Routing](https://github.com/an0099/toothpaste-kit/blob/main/orchestration/ROUTING-THRESHOLD.md): `orchestration/ROUTING-THRESHOLD.md`
- [Capability Taxonomy](https://github.com/an0099/toothpaste-kit/blob/main/orchestration/taxonomy.md): `orchestration/taxonomy.md`
- [Surface Registry](https://github.com/an0099/toothpaste-kit/tree/main/orchestration/registry): `orchestration/registry`
- [Message Schemas](https://github.com/an0099/toothpaste-kit/tree/main/orchestration/schemas): `orchestration/schemas`
- [Handoff Templates](https://github.com/an0099/toothpaste-kit/tree/main/orchestration/templates): `orchestration/templates`

### Workspace State

- [Workspace Stubs](https://github.com/an0099/toothpaste-kit/tree/main/examples/workspace): `examples/workspace`
- [Standing Documents](https://github.com/an0099/toothpaste-kit/blob/main/docs/standing-documents.md): `docs/standing-documents.md`

### Mechanical Gates

- [Hook Rules](https://github.com/an0099/toothpaste-kit/tree/main/hooks): `hooks`
- [Markdown Linter](https://github.com/an0099/toothpaste-kit/blob/main/scripts/mdlint.py): `scripts/mdlint.py`
- [Markdown Reflow](https://github.com/an0099/toothpaste-kit/blob/main/scripts/reflow-md.py): `scripts/reflow-md.py`
- [Stub Checker](https://github.com/an0099/toothpaste-kit/blob/main/scripts/check-workspace-stubs.py): `scripts/check-workspace-stubs.py`

### Other components

- **Person**
- **Lead Agent**

## Connections

- Person → Session Procedures: invokes (evidence: `README.md`)
- Person → Review Procedures: invokes (evidence: `README.md`)
- Person → Redaction Gate: decides at (evidence: `README.md`)
- Lead Agent → Behavior Skills: loads (evidence: `README.md`)
- Lead Agent → Document Skills: loads (evidence: `README.md`)
- Lead Agent → Surface Regimes: detects regime (evidence: `README.md`)
- Lead Agent → Skill Lifecycle: uses (evidence: `README.md`)
- Lead Agent → Skill Discovery: uses (evidence: `README.md`)
- Lead Agent → Capture Procedures: records with (evidence: `README.md`)
- Lead Agent → Relay Protocol: relays work (evidence: `README.md`)
- Relay Protocol → Sensitivity Routing: gates dispatch (evidence: `README.md`)
- Relay Protocol → Message Schemas: uses messages (evidence: `README.md`)
- Relay Protocol → Surface Registry: consults surfaces
- Relay Protocol → Capability Taxonomy: classifies capability
- Relay Protocol → Handoff Templates: uses templates
- Session Procedures → Standing Documents: updates (evidence: `README.md`)
- Review Procedures → Standing Documents: reads (evidence: `README.md`)
- Workspace Stubs → Standing Documents: stubs describe (evidence: `README.md`)
- Hook Rules → Redaction Gate: warns on reads
- Person → Markdown Linter: checks documents
- Person → Markdown Reflow: reflows documents
- Stub Checker → Workspace Stubs: checks names (evidence: `scripts/check-workspace-stubs.py`)
- Stub Checker → Standing Documents: checks listing (evidence: `scripts/check-workspace-stubs.py`)
