# kaotypr/context-circuit architecture

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

- Interactive diagram: https://gitdiagram.com/kaotypr/context-circuit
- Repository: https://github.com/kaotypr/context-circuit

## Overview

Context Circuit is a Git-committed project workspace template paired with a companion CLI. A human asks a coding agent to prepare a change; the agent consults shared product knowledge, clarifies the goal and open questions, and records an intent. Plans coordinate repository-specific work and dependencies; after implementation, knowledge can be reconciled and retained for future sessions. The graph reflects README-documented capabilities and paths in the tree; no runtime source excerpts were available, so internal call wiring is not inferred.

Main entry points: [`.agents/skills/cc-intent/SKILL.md`](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-intent/SKILL.md) (Ground the goal), [`.agents/skills/cc-plan/SKILL.md`](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-plan/SKILL.md) (Prepare plans), [`.agents/skills/cc-dispatch/SKILL.md`](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-dispatch/SKILL.md) (Coordinate work), [`.agents/skills/cc-complete/SKILL.md`](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-complete/SKILL.md) (Reconcile completion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Shared workspace"]
  node_workspace_files["Workspace files<br/>[workspace.yaml]"]
  node_workspace_docs["Workspace guidance<br/>[workspace.md]"]
  node_worktree_docs["Worktree guidance<br/>[worktrees.md]"]
end

subgraph group_workflow["Agent workflows"]
  node_intent_skill["Ground the goal<br/>[SKILL.md]"]
  node_plan_skill["Prepare plans<br/>[SKILL.md]"]
  node_dispatch_skill["Coordinate work<br/>[SKILL.md]"]
  node_complete_skill["Reconcile completion<br/>[SKILL.md]"]
  node_knowledge_skill["Maintain knowledge<br/>[SKILL.md]"]
  node_deliver_skill["Deliver changes<br/>[SKILL.md]"]
end

subgraph group_coordination["Change coordination"]
  node_intent_records["Intent records<br/>[README.md]"]
  node_plan_records["Plans and dependencies<br/>[README.md]"]
end

subgraph group_knowledge["Product knowledge"]
  node_context["Shared context<br/>[INDEX.md]"]
  node_glossary["Project glossary<br/>[glossary.md]"]
  node_sources["Task evidence<br/>[README.md]"]
end

node_human(("Human"))
node_agent(("Coding agent"))
node_cli["Companion CLI"]

node_human -->|"requests change"| node_agent
node_agent -->|"grounds goal"| node_intent_skill
node_intent_skill -->|"consults knowledge"| node_context
node_intent_skill -->|"checks vocabulary"| node_glossary
node_intent_skill -->|"reviews evidence"| node_sources
node_intent_skill -->|"records intent"| node_intent_records
node_human -->|"approves decisions"| node_intent_records
node_agent -->|"prepares work"| node_plan_skill
node_plan_skill -->|"records plans"| node_plan_records
node_agent -->|"coordinates repositories"| node_dispatch_skill
node_dispatch_skill -->|"uses dependencies"| node_plan_records
node_agent -->|"reconciles changes"| node_complete_skill
node_complete_skill -->|"updates knowledge"| node_knowledge_skill
node_knowledge_skill -->|"maintains context"| node_context
node_agent -->|"delivers work"| node_deliver_skill
node_agent -.->|"requests bookkeeping"| node_cli
node_cli -.->|"manages workspace"| node_workspace_files
node_agent -->|"follows guidance"| node_workspace_docs
node_agent -->|"uses worktrees"| node_worktree_docs

click node_workspace_files "https://github.com/kaotypr/context-circuit/blob/main/workspace.yaml"
click node_context "https://github.com/kaotypr/context-circuit/blob/main/context/INDEX.md"
click node_glossary "https://github.com/kaotypr/context-circuit/blob/main/context/glossary.md"
click node_sources "https://github.com/kaotypr/context-circuit/blob/main/sources/README.md"
click node_intent_records "https://github.com/kaotypr/context-circuit/blob/main/intent/README.md"
click node_plan_records "https://github.com/kaotypr/context-circuit/blob/main/plans/README.md"
click node_intent_skill "https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-intent/SKILL.md"
click node_plan_skill "https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-plan/SKILL.md"
click node_dispatch_skill "https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-dispatch/SKILL.md"
click node_complete_skill "https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-complete/SKILL.md"
click node_knowledge_skill "https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-knowledge/SKILL.md"
click node_deliver_skill "https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-deliver/SKILL.md"
click node_workspace_docs "https://github.com/kaotypr/context-circuit/blob/main/.context-circuit/docs/workspace.md"
click node_worktree_docs "https://github.com/kaotypr/context-circuit/blob/main/.context-circuit/docs/worktrees.md"

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_workspace_files,node_workspace_docs,node_worktree_docs toneBlue
class node_intent_skill,node_plan_skill,node_dispatch_skill,node_complete_skill,node_knowledge_skill,node_deliver_skill toneAmber
class node_intent_records,node_plan_records toneMint
class node_context,node_glossary,node_sources toneRose
class node_human,node_agent,node_cli toneIndigo
```

## Components

### Shared workspace

- [Workspace files](https://github.com/kaotypr/context-circuit/blob/main/workspace.yaml): `workspace.yaml`
- [Workspace guidance](https://github.com/kaotypr/context-circuit/blob/main/.context-circuit/docs/workspace.md): `.context-circuit/docs/workspace.md`
- [Worktree guidance](https://github.com/kaotypr/context-circuit/blob/main/.context-circuit/docs/worktrees.md): `.context-circuit/docs/worktrees.md`

### Agent workflows

- [Ground the goal](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-intent/SKILL.md): `.agents/skills/cc-intent/SKILL.md`
- [Prepare plans](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-plan/SKILL.md): `.agents/skills/cc-plan/SKILL.md`
- [Coordinate work](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-dispatch/SKILL.md): `.agents/skills/cc-dispatch/SKILL.md`
- [Reconcile completion](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-complete/SKILL.md): `.agents/skills/cc-complete/SKILL.md`
- [Maintain knowledge](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-knowledge/SKILL.md): `.agents/skills/cc-knowledge/SKILL.md`
- [Deliver changes](https://github.com/kaotypr/context-circuit/blob/main/.agents/skills/cc-deliver/SKILL.md): `.agents/skills/cc-deliver/SKILL.md`

### Change coordination

- [Intent records](https://github.com/kaotypr/context-circuit/blob/main/intent/README.md): `intent/README.md`
- [Plans and dependencies](https://github.com/kaotypr/context-circuit/blob/main/plans/README.md): `plans/README.md`

### Product knowledge

- [Shared context](https://github.com/kaotypr/context-circuit/blob/main/context/INDEX.md): `context/INDEX.md`
- [Project glossary](https://github.com/kaotypr/context-circuit/blob/main/context/glossary.md): `context/glossary.md`
- [Task evidence](https://github.com/kaotypr/context-circuit/blob/main/sources/README.md): `sources/README.md`

### Other components

- **Human**
- **Coding agent**
- **Companion CLI**

## Connections

- Human → Coding agent: requests change
- Coding agent → Ground the goal: grounds goal
- Ground the goal → Shared context: consults knowledge
- Ground the goal → Project glossary: checks vocabulary
- Ground the goal → Task evidence: reviews evidence
- Ground the goal → Intent records: records intent
- Human → Intent records: approves decisions
- Coding agent → Prepare plans: prepares work
- Prepare plans → Plans and dependencies: records plans
- Coding agent → Coordinate work: coordinates repositories
- Coordinate work → Plans and dependencies: uses dependencies
- Coding agent → Reconcile completion: reconciles changes
- Reconcile completion → Maintain knowledge: updates knowledge
- Maintain knowledge → Shared context: maintains context
- Coding agent → Deliver changes: delivers work
- Coding agent → Companion CLI: requests bookkeeping
- Companion CLI → Workspace files: manages workspace
- Coding agent → Workspace guidance: follows guidance
- Coding agent → Worktree guidance: uses worktrees