Configuration & State Management
Relevant source files
The following files were used as context for generating this wiki page:
Configuration and State Management in the claude-skills project defines how agentic tools discover, store, and manipulate environment-specific settings and long-lived workflow data. The system organizes configuration into three primary tiers: global session rules, repository-specific engineering settings, and advisor-bound workflow state. This structure ensures that AI agents operate with consistent domain knowledge and execution boundaries across different repositories and tasks.
The system emphasizes durability by placing governing designs and workflow history outside the Git checkout in a dedicated state root. It uses a specific hierarchy of markdown files and SQLite ledgers to maintain continuity during session compactions or resumes.
Sources: CLAUDE.md:1-10, skills/execution-planning/SKILL.md:10-25, skills/setup-matt-pocock-skills/SKILL.md:5-15
Repository-Specific Configuration
Each repository requires a ## Agent skills block in either CLAUDE.md or AGENTS.md to define its operating environment. This block serves as a pointer to detailed configuration files located in docs/agents/. These files inform engineering skills about the issue tracker, triage labels, and domain documentation layout.
Configuration Layout
The system scaffolds three primary configuration areas for a repo:
- Issue Tracker: Defines the location and CLI tool (GitHub/GitLab/Local) used for tracking work.
- Triage Labels: Maps canonical triage roles to repo-specific label strings.
- Domain Docs: Specifies if the repo uses a single-context or multi-context layout.
Sources: skills/setup-matt-pocock-skills/SKILL.md:7-15, skills/setup-matt-pocock-skills/SKILL.md:106-120
The diagram shows the relationship between the root manifest and the detailed configuration files in docs/agents/.
Sources: skills/setup-matt-pocock-skills/SKILL.md:106-130
Triage State Machine
The state management for issues follows a specific role-based state machine. Every triaged issue carries exactly one category role and one state role.
| Role Type | Role Name | Description |
|---|---|---|
| Category | bug | Indicates something is broken. |
| Category | enhancement | Indicates a new feature or improvement. |
| State | needs-triage | Initial evaluation required by maintainer. |
| State | needs-info | Waiting on the reporter for more information. |
| State | ready-for-agent | Fully specified, ready for automated implementation. |
| State | ready-for-human | Requires human implementation due to complexity or judgment. |
| State | wontfix | Will not be actioned; record moved to .out-of-scope/. |
Sources: skills/triage/SKILL.md:20-35
Workflow & Durable State
Durable state management exists outside the Git checkout to prevent polluting the repository while maintaining execution context across AI turns. The system uses a workflow state root, typically defined by the CLAUDE_WORKFLOW_STATE_ROOT environment variable.
State Storage Structure
Workflow state is organized by repository keys and workflow IDs.
- Workflow State Root: Defaults to
${CLAUDE_HOME:-$HOME/.claude}/state. - Design Path:
<workflow-state-root>/<repo-key>/designs/<workflowId>.md. - Event Ledger: A SQLite event ledger and its active projection track workflow continuity.
Sources: skills/execution-planning/SKILL.md:28-40, CLAUDE.md:235-245
Workflow State Transitions
The system manages state through a strict order of skill invocations, where each step records evidence into the workflow ledger.
The diagram illustrates the flow of state from initialization to completion, tracking intent and design evidence in a durable ledger.
Sources: CLAUDE.md:220-245, skills/execution-planning/SKILL.md:40-60
Global Session State
Global rules in CLAUDE.md define the session-wide state management policies. This includes "Hard Production Invariants" that cannot be weakened by specific skills.
Key State Invariants
- Mock Ban: Verification must cross the real production interface. Mocks or stubs are not accepted as production proof.
- Imaginary-Risk Ban: Theoretical failures cannot justify new guards or abstractions without demonstrated occurrence.
- Root-Cause-First: No production fix begins until the symptom is reproduced and the cause is traced.
Sources: CLAUDE.md:25-50
Execution Pacing & Background Tasks
The system manages state for long-running operations (like PR merge windows) using specific tools to avoid passive loops:
- ScheduleWakeup: Resumes execution at a specific deadline.
- Monitor: Streams events from background processes to trigger wakeups.
- CronCreate: Manages genuinely recurring schedules.
Sources: CLAUDE.md:120-140
Domain Modeling & Context State
Domain state is managed through CONTEXT.md files. These files act as a ubiquitous language glossary.
Context Layouts
The system identifies the domain state structure based on the presence of specific files:
- Single-Context: One
CONTEXT.mdanddocs/adr/at the repo root. - Multi-Context: A
CONTEXT-MAP.mdat the root pointing to per-contextCONTEXT.mdfiles in subdirectories (e.g.,src/ordering/CONTEXT.md).
Sources: skills/domain-modeling/SKILL.md:15-35, skills/setup-matt-pocock-skills/domain.md:15-30
This diagram shows the relationship between the Context Map, individual context definitions, and Architectural Decision Records (ADRs).
Sources: skills/domain-modeling/SKILL.md:15-50, skills/setup-matt-pocock-skills/domain.md:15-35
Conclusion
Configuration and State Management in claude-skills provides a robust framework for AI agents to operate safely within complex software environments. By separating local repository settings from durable workflow state and global session rules, the project ensures that execution intent and architectural decisions remain persistent and verifiable even as the underlying codebase changes. This dual-layered approach—combining file-based configuration with ledger-tracked state—allows for reliable automation of triage, design, and implementation tasks.