# agenticnotetaking/arscontexta architecture

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

- Interactive diagram: https://gitdiagram.com/agenticnotetaking/arscontexta
- Repository: https://github.com/agenticnotetaking/arscontexta

## Overview

1. **What this repo is**
   Ars Contexta is a Claude Code plugin that derives a personal or domain knowledge system from conversation. The repo is mostly a content-and-template engine: markdown knowledge, shell hook scripts, plugin manifests, and generation specs rather than a conventional application codebase.

2. **Execution boundary**
   The runtime host is Claude Code. This repository contributes plugin commands, generated skill templates, and hooks that operate inside the user’s local workspace/vault. The architecture is local-first: plain files, wiki links, shell scripts, and optional semantic search integration.

3. **Primary orchestration path**
   The central flow is `/arscontexta:setup`: detect environment → ask 2–4 conversational questions → derive configuration choices from the research base → propose the system → generate files → validate the result. That setup pipeline is the main “engine” of the repo.

4. **Research-backed decision layer**
   `methodology/` is the system’s knowledge base: 249 short research claims that justify design choices like atomic notes, MOCs, hooks, session boundaries, and schema enforcement. This layer is not user data; it is the derivation source that informs generated architecture.

5. **Reference and kernel layer**
   `reference/` contains the formal architecture spec, especially `kernel.yaml` with the required primitives, plus claim maps, lifecycle docs, templates, test fixtures, and validation scripts. This layer defines what a valid generated system must include and is used as the constraint/verification boundary.

6. **Generated vault shape**
   The generated knowledge system is organized into three invariant spaces: `self/` for persistent agent identity and methodology, `notes/` for the domain knowledge graph, and `ops/` for operational state like sessions and queues. The repo’s docs emphasize that the names can adapt, but the separation is architectural.

7. **Command subsystem**
   There are two command families. `skills/` holds the plugin-level commands always available in Claude Code, such as setup, help, ask, health, recommend, architect, reseed, upgrade, and add-domain. `skill-sources/` holds the generated processing commands that become available after setup, such as reduce, reflect, reweave, verify, validate, seed, pipeline, tasks, stats, graph, next, learn, remember, rethink, and refactor.

8. **Processing pipeline**
   The core operational loop is the 6Rs: Record, Reduce, Reflect, Reweave, Verify, Rethink. This is the knowledge production path from raw capture to structured notes, navigation updates, backward maintenance, quality checks, and assumption challenge.

9. **Fresh-context task execution**
   The pipeline is designed to run with fresh context per phase, typically by spawning subagents rather than chaining everything in one prompt window. `agents/knowledge-guide.md` supports that orchestration, and `skill-sources/*` are built to perform bounded tasks with handoff state between steps.

10. **Automation and enforcement**
    `hooks/` implements event-driven quality control through Claude Code hook points. The important runtime hooks are Session Orient on session start, Write Validate on write events, Auto Commit as a non-blocking post-write action, and Session Capture on stop; together they enforce schema, preserve session state, and reduce manual memory failures.

11. **Generation system and composition**
    `generators/` contains composable feature blocks used to assemble the generated `CLAUDE.md` and related system files. This is where the repo’s modular architecture shows up: features are toggled/combined rather than hard-coded into one monolith.

12. **Platform adaptation and presets**
    `platforms/` holds adapter logic for Claude Code plus shared abstractions, while `presets/` provides pre-validated configurations for research, personal, and experimental use cases. These are the main adaptation boundaries: platform capability differences on one side, domain/use-case defaults on the other.

13. **Validation and utilities**
    Validation is part of the architecture, not an afterthought: the repo includes kernel validation, reference fixtures, and shell utilities under `scripts/` and `reference/validate-kernel.sh`. The optional qmd semantic search integration is external and only affects retrieval/navigation, not the core file-based architecture.

14. **How data moves through the system**
    In practice, the flow is: conversation and domain signals enter setup → configuration is derived against the methodology/references → the generator emits a vault structure, templates, skills, and hooks → daily use writes into notes and ops → hooks and skills maintain quality, navigation, and drift correction over time.

Main entry points: [`skills/setup/SKILL.md`](https://github.com/agenticnotetaking/arscontexta/blob/main/skills/setup/SKILL.md) (Setup command), [`hooks`](https://github.com/agenticnotetaking/arscontexta/tree/main/hooks) (Hooks), [`skill-sources`](https://github.com/agenticnotetaking/arscontexta/tree/main/skill-sources) (Skill sources), [`generators/features`](https://github.com/agenticnotetaking/arscontexta/tree/main/generators/features) (Generator features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Claude Code runtime"]
  node_n1["Plugin manifest<br/>[plugin.json]"]
  node_n2["Setup command<br/>skill command<br/>[SKILL.md]"]
  node_n3["Core skills<br/>command suite"]
end

subgraph group_g2["Derivation engine"]
  node_n5["Generator features<br/>feature modules"]
  node_n6["CLAUDE.md generator<br/>[claude-md.md]"]
  node_n15["Agents guide<br/>orchestration guide<br/>[knowledge-guide.md]"]
end

subgraph group_g3["Knowledge base"]
  node_n7["Methodology corpus<br/>research base"]
  node_n8["Kernel spec<br/>architecture spec<br/>[kernel.yaml]"]
  node_n9["Reference docs<br/>validation spec"]
end

subgraph group_g4["Generated system"]
  node_n4["Skill sources<br/>generated commands"]
  node_n13["Vault spaces<br/>generated topology"]
  node_n14(("6Rs loop<br/>processing pipeline"))
end

subgraph group_g5["Platform and presets"]
  node_n10["Claude Code adapter<br/>platform adapter"]
  node_n11["Shared blocks<br/>shared library"]
  node_n12["Presets"]
  node_n19["Platform hooks<br/>hook templates"]
end

subgraph group_g6["Validation and enforcement"]
  node_n16["Hooks<br/>event enforcement"]
  node_n17["Hook scripts<br/>runtime scripts"]
  node_n18["Validation script<br/>checker<br/>[validate-kernel.sh]"]
end

node_n1 -->|"exposes"| node_n2
node_n1 -->|"packages"| node_n3
node_n2 -->|"derives from"| node_n7
node_n2 -->|"constrained by"| node_n8
node_n2 -->|"selects"| node_n12
node_n2 -->|"emits"| node_n6
node_n6 -->|"composes"| node_n5
node_n5 -->|"reuses"| node_n11
node_n10 -->|"instantiates"| node_n19
node_n10 -->|"adapts"| node_n6
node_n11 -->|"supports"| node_n4
node_n4 -->|"implements"| node_n14
node_n14 -->|"writes to"| node_n13
node_n15 -->|"orchestrates"| node_n14
node_n16 -->|"runs"| node_n17
node_n19 -->|"defines"| node_n16
node_n16 -->|"validates with"| node_n18
node_n18 -->|"checks against"| node_n8
node_n9 -->|"documents"| node_n8
node_n9 -->|"specifies"| node_n13
node_n7 -.->|"informs"| node_n5
node_n12 -->|"preset for"| node_n13
node_n3 -->|"invokes"| node_n2
node_n4 -.->|"observes"| node_n16

click node_n1 "https://github.com/agenticnotetaking/arscontexta/blob/main/.claude-plugin/plugin.json"
click node_n2 "https://github.com/agenticnotetaking/arscontexta/blob/main/skills/setup/SKILL.md"
click node_n3 "https://github.com/agenticnotetaking/arscontexta/tree/main/skills"
click node_n4 "https://github.com/agenticnotetaking/arscontexta/tree/main/skill-sources"
click node_n5 "https://github.com/agenticnotetaking/arscontexta/tree/main/generators/features"
click node_n6 "https://github.com/agenticnotetaking/arscontexta/blob/main/generators/claude-md.md"
click node_n7 "https://github.com/agenticnotetaking/arscontexta/tree/main/methodology"
click node_n8 "https://github.com/agenticnotetaking/arscontexta/blob/main/reference/kernel.yaml"
click node_n9 "https://github.com/agenticnotetaking/arscontexta/tree/main/reference"
click node_n10 "https://github.com/agenticnotetaking/arscontexta/tree/main/platforms/claude-code"
click node_n11 "https://github.com/agenticnotetaking/arscontexta/tree/main/platforms/shared"
click node_n12 "https://github.com/agenticnotetaking/arscontexta/tree/main/presets"
click node_n14 "https://github.com/agenticnotetaking/arscontexta/tree/main/skill-sources/pipeline"
click node_n15 "https://github.com/agenticnotetaking/arscontexta/blob/main/agents/knowledge-guide.md"
click node_n16 "https://github.com/agenticnotetaking/arscontexta/tree/main/hooks"
click node_n17 "https://github.com/agenticnotetaking/arscontexta/tree/main/hooks/scripts"
click node_n18 "https://github.com/agenticnotetaking/arscontexta/blob/main/reference/validate-kernel.sh"
click node_n19 "https://github.com/agenticnotetaking/arscontexta/tree/main/platforms/claude-code/hooks"

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_n1,node_n2,node_n3 toneBlue
class node_n5,node_n6,node_n15 toneAmber
class node_n7,node_n8,node_n9 toneMint
class node_n4,node_n13,node_n14 toneRose
class node_n10,node_n11,node_n12,node_n19 toneIndigo
class node_n16,node_n17,node_n18 toneTeal
```

## Components

### Claude Code runtime

Plugin-facing entrypoints and manifests that run inside Claude Code.

- [Plugin manifest](https://github.com/agenticnotetaking/arscontexta/blob/main/.claude-plugin/plugin.json): manifest · Claude Code plugin metadata and marketplace registration. · `.claude-plugin/plugin.json`
- [Setup command](https://github.com/agenticnotetaking/arscontexta/blob/main/skills/setup/SKILL.md): skill command · Primary orchestration entrypoint that detects environment, asks questions, derives config, generates files, and validates the result. · `skills/setup/SKILL.md`
- [Core skills](https://github.com/agenticnotetaking/arscontexta/tree/main/skills): command suite · Always-available plugin commands such as help, ask, health, recommend, architect, reseed, upgrade, and add-domain. · `skills`

### Derivation engine

Setup orchestration and generation logic that turns conversation plus research into a configured knowledge system.

- [Generator features](https://github.com/agenticnotetaking/arscontexta/tree/main/generators/features): feature modules · Composable blocks assembled into CLAUDE.md and related system files. · `generators/features`
- [CLAUDE.md generator](https://github.com/agenticnotetaking/arscontexta/blob/main/generators/claude-md.md): generator · Template that composes feature modules into the active context file and system scaffold. · `generators/claude-md.md`
- [Agents guide](https://github.com/agenticnotetaking/arscontexta/blob/main/agents/knowledge-guide.md): orchestration guide · Fresh-context task guidance for subagent-based phase execution and handoff state. · `agents/knowledge-guide.md`

### Knowledge base

Research claims and formal reference material that constrain and justify generated architecture.

- [Methodology corpus](https://github.com/agenticnotetaking/arscontexta/tree/main/methodology): research base · Dense set of research claims that justify design choices and processing patterns. · `methodology`
- [Kernel spec](https://github.com/agenticnotetaking/arscontexta/blob/main/reference/kernel.yaml): architecture spec · Formal primitive set and constraints for a valid generated knowledge system. · `reference/kernel.yaml`
- [Reference docs](https://github.com/agenticnotetaking/arscontexta/tree/main/reference): validation spec · Claim maps, lifecycle docs, templates, fixtures, and validation guidance that define expected behavior. · `reference`

### Generated system

The produced vault shape, commands, and operational loops used during daily knowledge work.

- [Skill sources](https://github.com/agenticnotetaking/arscontexta/tree/main/skill-sources): generated commands · Post-setup processing commands for reduce, reflect, reweave, verify, validate, seed, pipeline, tasks, stats, graph, next, learn, remember, rethink, and refactor. · `skill-sources`
- **Vault spaces**: generated topology · Invariant spaces of the generated system: self, notes, and ops.
- [6Rs loop](https://github.com/agenticnotetaking/arscontexta/tree/main/skill-sources/pipeline): processing pipeline · Record, Reduce, Reflect, Reweave, Verify, and Rethink as the main knowledge-production cycle. · `skill-sources/pipeline`

### Platform and presets

Adaptation layers for Claude Code plus validated use-case defaults.

- [Claude Code adapter](https://github.com/agenticnotetaking/arscontexta/tree/main/platforms/claude-code): platform adapter · Platform-specific generator and hook templates for Claude Code. · `platforms/claude-code`
- [Shared blocks](https://github.com/agenticnotetaking/arscontexta/tree/main/platforms/shared): shared library · Reusable skill blocks and templates shared across generated commands and platform implementations. · `platforms/shared`
- [Presets](https://github.com/agenticnotetaking/arscontexta/tree/main/presets): use-case presets · Validated starter configurations for research, personal, and experimental systems. · `presets`
- [Platform hooks](https://github.com/agenticnotetaking/arscontexta/tree/main/platforms/claude-code/hooks): hook templates · Claude Code-specific hook templates used to instantiate runtime enforcement. · `platforms/claude-code/hooks`

### Validation and enforcement

Hooks and scripts that keep generated systems consistent and drift-resistant.

- [Hooks](https://github.com/agenticnotetaking/arscontexta/tree/main/hooks): event enforcement · Session orient, write validate, auto commit, and session capture runtime controls. · `hooks`
- [Hook scripts](https://github.com/agenticnotetaking/arscontexta/tree/main/hooks/scripts): runtime scripts · Shell implementations for validation, session management, and non-blocking maintenance actions. · `hooks/scripts`
- [Validation script](https://github.com/agenticnotetaking/arscontexta/blob/main/reference/validate-kernel.sh): checker · Kernel validation and reference-backed verification entrypoint. · `reference/validate-kernel.sh`

## Connections

- Plugin manifest → Setup command: exposes · The plugin manifest registers the setup command as the primary entrypoint.
- Plugin manifest → Core skills: packages · The plugin ships the always-available command set.
- Setup command → Methodology corpus: derives from · Setup decisions are grounded in the research corpus.
- Setup command → Kernel spec: constrained by · Generation must satisfy the kernel primitives and rules.
- Setup command → Presets: selects · Setup adapts defaults through validated presets.
- Setup command → CLAUDE.md generator: emits · The setup flow materializes the active Claude context file.
- CLAUDE.md generator → Generator features: composes · The generator assembles feature modules into the final context file.
- Generator features → Shared blocks: reuses · Features draw on shared blocks and templates.
- Claude Code adapter → Platform hooks: instantiates · Claude Code adapter supplies platform-specific hook templates.
- Claude Code adapter → CLAUDE.md generator: adapts · Platform adapter shapes how the generated context is emitted for Claude Code.
- Shared blocks → Skill sources: supports · Shared blocks provide the reusable logic behind generated skill commands.
- Skill sources → 6Rs loop: implements · Generated commands operationalize the 6Rs loop and related tasks.
- 6Rs loop → Vault spaces: writes to · The loop produces and maintains content in the vault spaces.
- Agents guide → 6Rs loop: orchestrates · Agents guide describes bounded phase execution with fresh context.
- Hooks → Hook scripts: runs · Hook definitions dispatch to shell scripts.
- Platform hooks → Hooks: defines · Platform hook templates become the runtime enforcement layer.
- Hooks → Validation script: validates with · Write and session hooks rely on validation checks.
- Validation script → Kernel spec: checks against · Validation confirms the generated system matches the kernel spec.
- Reference docs → Kernel spec: documents · Reference material expands and operationalizes the kernel constraints.
- Reference docs → Vault spaces: specifies · Reference templates and lifecycle docs define the vault shape.
- Methodology corpus → Generator features: informs · Research claims justify module selection and composition.
- Presets → Vault spaces: preset for · Presets parameterize the generated vault topology and vocabulary.
- Core skills → Setup command: invokes · Core commands route users into setup and other maintenance flows.
- Skill sources → Hooks: observes · Processing commands are complemented by hook-based enforcement.
