How agenticnotetaking/arscontexta works
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: SKILL.md Setup command · hooks Hooks · skill-sources Skill sources · features Generator features
Components 19
Claude Code runtime
Plugin-facing entrypoints and manifests that run inside Claude Code.
- Plugin manifest · Claude Code plugin metadata and marketplace registration.
.claude-plugin/plugin.json - Setup command · Primary orchestration entrypoint that detects environment, asks questions, derives config, generates files, and validates the result.
skills/setup/SKILL.md - Core skills · 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 · Composable blocks assembled into CLAUDE.md and related system files.
generators/features - CLAUDE.md generator · Template that composes feature modules into the active context file and system scaffold.
generators/claude-md.md - Agents 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 · Dense set of research claims that justify design choices and processing patterns.
methodology - Kernel spec · Formal primitive set and constraints for a valid generated knowledge system.
reference/kernel.yaml - Reference docs · 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 · 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 · Invariant spaces of the generated system: self, notes, and ops.
- 6Rs loop · 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 · Platform-specific generator and hook templates for Claude Code.
platforms/claude-code - Shared blocks · Reusable skill blocks and templates shared across generated commands and platform implementations.
platforms/shared - Presets · Validated starter configurations for research, personal, and experimental systems.
presets - Platform hooks · 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 · Session orient, write validate, auto commit, and session capture runtime controls.
hooks - Hook scripts · Shell implementations for validation, session management, and non-blocking maintenance actions.
hooks/scripts - Validation script · Kernel validation and reference-backed verification entrypoint.
reference/validate-kernel.sh
Connections 24
- 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.