Standards & Patterns
Harness Configuration Reference
Maintained by: Ada (Agentic Pattern Designer) + Ivan (Infrastructure Engineer) Last updated: 2026-03-29 Decision: TFD-0014 (Component Taxonomy — Category 4)
Overview
Claude Code is both our factory tool and our product deployment format. This reference documents every configurable aspect of the harness — what each component does, when to use it, and how to configure it for different talent profiles.
Key insight: "Every harness component encodes an assumption about what the model can't do on its own." — Anthropic. Configure only what the model needs. Review assumptions at each major model release.
1. CLAUDE.md — The Brain
The core configuration file. Defines agent identity, rules, and workspace.
Standard Structure (9 Sections)
| Section | Purpose | Required | Complexity Scaling |
|---|---|---|---|
| 1. Role Definition | "You are a {type} agent for {client}" | Always | Fixed — 1-2 sentences |
| 2. Workspace Rules | File safety, conventions, language, safety | Always | Low — standard rules + client language |
| 3. Structure | Directory layout | Always | Low — standard + client-specific dirs |
| 4. Skills Table | All commands: name, usage, input, output, model | Always | Scales with skill count (10-40 rows) |
| 5. Workflow | Standard pipeline for this product type | If multi-step | Medium — depends on orchestration |
| 6. Conventions | Naming patterns, request numbering, decision format | Always | Low — client-specific naming |
| 7. Model Selection | Cost optimization matrix, per-skill assignments | Always | Low — reference model catalog |
| 8. Permissions | Autonomous / confirm / deny levels | Always | Low — standard tiers |
| 9. Known Issues | Caveats, workarounds | If applicable | Low — shrinks over time |
Complexity Profiles
| Profile | Sections Active | Typical Size | Example Product |
|---|---|---|---|
| Simple | 1-4, 6-8 | ~100 lines | Data validator, simple advisor |
| Standard | 1-8 | ~200 lines | EA agent, compliance agent |
| Complex | All 9, expanded workflow | ~300+ lines | Multi-framework orchestrated talent |
Template Location
production-lines/digital-talent/templates/CLAUDE-template.md
2. Settings — Runtime Behavior
settings.json ships with the talent. settings.local.json is dev-only (never ships).
Permission Modes
| Mode | Behavior | When to Use |
|---|---|---|
default |
Prompts user for each tool call | New/untested talents, security-sensitive |
bypassPermissions |
Allows all (with deny list) | Development only — never ship this |
allowedTools (allowlist) |
Only listed tools permitted | Production talents — explicit whitelist |
Permission Model Tiers
| Tier | Allow | Confirm | Deny | Use Case |
|---|---|---|---|---|
| Trusted | Read, Write, Edit, Glob, Grep, Bash (safe) | External API calls | Destructive ops, credentials access | Internal tools, non-sensitive domains |
| Standard | Read, Glob, Grep | Write, Edit, Bash | Destructive ops, system commands | Most client deployments |
| Restricted | Read, Glob, Grep | — | Everything else | Read-only analysis talents |
Deny List (Always Include)
{
"deny": [
"Bash(git push --force *)",
"Bash(git reset --hard *)",
"Bash(rm -rf *)",
"Bash(sudo *)",
"Read(.env)",
"Read(*credentials*)",
"Read(*secret*)",
"Read(*.pem)"
]
}
3. Hooks — Event-Driven Validation
Hooks fire on tool use events. Three types: PreToolUse, PostToolUse, Stop.
Hook Architecture
User Request → Tool Call → PreToolUse Hook → [ALLOW/BLOCK] → Tool Executes → PostToolUse Hook → Result
Available Hook Patterns
| Pattern | Type | Matcher | Purpose | Factory Example |
|---|---|---|---|---|
| Terminology enforcement | PreToolUse | Write|Edit |
Block writes that violate brand terms | "digital talent" not "digital employee" |
| Naming convention | PreToolUse | createJiraIssue |
Validate artifact names before creation | Jira summary format, Epic prefix codes |
| Content standards | PreToolUse | createJiraIssue |
Require mandatory sections in content | AC + DoD in stories/bugs |
| Output validation | PostToolUse | Write |
Verify output matches expected format | Template compliance check |
| Safety guard | PreToolUse | Bash |
Block dangerous commands | Deny destructive operations |
| Session reminder | SessionStart | — | Display onboarding info at start | Token-saving tips |
Hook Complexity Guide
| Talent Profile | Hooks Recommended | Examples |
|---|---|---|
| Simple | 0-1 | Session start reminder only |
| Standard | 1-3 | Terminology + naming conventions |
| Complex | 3-5 | Terminology + naming + content standards + output validation |
| Regulated | 5+ | All above + compliance checks + audit logging |
Hook Template
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hook": {
"type": "prompt",
"prompt": "Check this content against [rules]. If it violates any rule, respond BLOCK with the violation. Otherwise respond ALLOW."
}
}
]
}
}
4. Skills — Executable Capabilities
Skills live in .claude/commands/ as markdown files with frontmatter.
Skill Anatomy
| Component | Required | Purpose |
|---|---|---|
| Frontmatter | Yes | Name, description, usage, model recommendation |
| Input specification | Yes | What the skill expects, path resolution rules |
| Processing steps | Yes | Numbered steps the agent follows |
| Output specification | Yes | File name pattern, format, destination |
| Quality checks | Yes | Verification criteria before completion |
| Model recommendation | Yes | Which model tier for this skill |
Skill Count by Talent Profile
| Profile | Typical Count | Breakdown |
|---|---|---|
| Simple | 5-10 | Core domain skills only |
| Standard | 15-25 | Domain + utility + workflow skills |
| Complex | 25-40 | Domain + utility + workflow + orchestration + validation skills |
Reusability
Skills fall into three reuse categories:
| Category | Reuse Level | Examples |
|---|---|---|
| Generic | Cross-product | Orientation, status check, help |
| Domain | Within product type | EA-specific, compliance-specific |
| Client | Single deployment | Client naming, tool-specific integration |
5. MCP Servers — External Integration
See: departments/engineering/infrastructure-engineer-ivan/integration-catalog.md
MCP configuration ships in .mcp.json alongside the talent. Each server requires:
- Server package installation
- Authentication configuration
- Permission allowlisting in
settings.json
6. Memory — Persistence Across Sessions
Memory Patterns
| Pattern | Mechanism | Persistence | Use Case |
|---|---|---|---|
| Stateless | No memory config | None | Simple single-shot skills |
| Per-request | Working directory per request (e.g., demandes-ae/DAE-NNNN/) |
Request lifetime | Stateful workflows with file-based handoffs |
| Session memory | memory/MEMORY.md + index |
Cross-session | Talents that learn preferences over time |
| Shared state | Common files read/written by multiple skills | Within talent | Orchestrated talents with multiple phases |
Memory Configuration Guide
| Talent Profile | Recommended Pattern | Setup |
|---|---|---|
| Simple | Stateless or per-request | Working directory convention in CLAUDE.md |
| Standard | Per-request | Directory structure + naming convention |
| Complex | Per-request + session memory | MEMORY.md + request directories |
| Orchestrated | Shared state + session memory | Structured artifacts for phase handoffs |
7. Structured Storage & Context Historization
Not all talents can rely on file-based persistence. When a talent needs to query, aggregate, or track temporal state, structured storage is required.
When Files Aren't Enough
| Signal | Problem | Storage Needed |
|---|---|---|
| Talent queries data with filters/aggregates | Reading all files is slow, context-heavy | SQLite or structured store |
| Talent must search documents semantically | Reading every file wastes tokens | Vector store + embeddings (RAG) |
| Talent must maintain audit trail | Git history is implicit, not queryable | Structured historization (SQLite + timestamps) |
| Multi-agent talent shares state | File locks, race conditions | Shared state DB or Mem0 MCP |
| Talent switches between models | Context must transfer across model boundaries | External persistence layer (Mem0, LangGraph) |
Storage Options Catalog
| Option | Type | Complexity | Best For | MCP Available |
|---|---|---|---|---|
| File-based (markdown/JSON) | Flat files | None | Simple state, per-request dirs | N/A (native) |
| SQLite | Embedded relational DB | Low | Structured queries, audit trails, FTS5 search | Context Mode MCP (score 3.0) |
| Mem0 MCP | Universal memory layer | Medium | Cross-session memory, model-switching persistence | Yes — OpenMemory MCP (score 3.4) |
| LangGraph Persistence | Checkpoint store | Medium | Multi-agent state checkpoints, workflow recovery | PostgreSQL/Redis/DynamoDB backends |
| Vector store (Chroma, Pinecone) | Embedding index | High | Semantic search, RAG over large doc sets | Varies |
| Knowledge graph (Zep) | Temporal graph | High | Entity relationships, temporal reasoning | Not recommended (600K+ token footprint) |
Decision Tree: Do You Need Structured Storage?
Can the talent work with files only (read/write markdown, JSON)?
YES → File-based persistence (default)
NO → What kind of queries?
Structured (filter, aggregate, join) → SQLite
Semantic (find similar, search meaning) → Vector store + RAG
Temporal (what changed, when, audit trail) → SQLite with timestamps
Cross-model (persist across Claude ↔ local LLM) → Mem0 MCP
Multi-agent shared state → Mem0 MCP or LangGraph checkpoints
Context Historization Pattern
For talents that need audit trails or decision history:
| Component | Implementation |
|---|---|
| Event log | SQLite table: (id, timestamp, actor, action, input_hash, output_hash, decision) |
| Decision trail | Each skill appends a decision record with rationale |
| Query interface | Skill that queries historization DB for past decisions, patterns, or conflicts |
| Pruning policy | Age-based or size-based cleanup to prevent unbounded growth |
Maturity Note
Structured storage is R&D territory for product use. Riley evaluated the options (RD-0011, RD-0008). Currently:
- File-based is the only production-proven pattern
- SQLite is evaluated, not yet deployed in a talent
- Mem0 MCP is evaluated, recommended for Phase 3b (model-switching use case)
- Vector stores are not yet evaluated for factory use
References
- RD-0011: External context persistence evaluation (Mem0, LangGraph, Zep)
- RD-0008: Context Mode MCP evaluation (SQLite-backed)
- Agentic pattern: Retrieval-Augmented Generation (
patterns/memory/retrieval-augmented-generation.md) - Agentic pattern: Shared State (
patterns/memory/shared-state.md) - Agentic pattern: Memory Management (
patterns/memory/memory-management.md)
8. Context Management
Strategies
| Strategy | When to Use | How |
|---|---|---|
| Natural | Simple talents, short interactions | No special config — Claude manages context |
| File-based handoffs | Multi-phase workflows | Each phase writes output files; next phase reads them |
| Structured artifacts | Complex orchestration | JSON/markdown state files passed between agents |
| Context resets | Long-running talents | Start fresh sessions with state loaded from files |
Anti-Patterns
- Conversation-dependent state: Don't rely on conversation history for critical state. Write to files.
- Monolithic context: Don't load everything upfront. Load per-skill as needed.
- Compaction reliance: Don't trust automatic compaction to preserve critical details. Use explicit file state.
8. Plugins — Shareable Bundles
Plugins bundle skills, hooks, agents, and MCP configs. Current factory plugins:
| Plugin | Contents | Status |
|---|---|---|
superpowers |
Brainstorming, planning, TDD, debugging workflows | Active (factory) |
telegram |
Telegram channel integration | Active (factory) |
toolkit-catalog |
Cross-project reusable skills | Active (factory) |
Product use: Not yet. Plugins could package entire talent configurations for easier deployment — R&D opportunity.
Configuration Decision Tree
New talent → Start here:
1. CLAUDE.md → Which complexity profile? (simple/standard/complex)
2. Permissions → Which tier? (trusted/standard/restricted)
3. Hooks → How many validation layers? (0-5+)
4. Skills → How many skills? (5-10 / 15-25 / 25-40)
5. Memory → Which persistence pattern? (stateless / per-request / session / shared)
6. MCP → Which integrations? (none / read-only / read-write)
7. Model routing → Per-skill assignments from model catalog
Update Triggers
| Trigger | Action |
|---|---|
| New Claude Code feature (hooks, plugins, etc.) | Riley reports; Ada updates this reference |
| New MCP server available | Ivan tests; Ada adds to integration options |
| Production feedback (config issue) | Pablo reports; Ada adjusts guidance |
| New talent profile emerges | Ada adds profile to complexity guides |
| Anthropic harness evolution | Riley evaluates; Ada stress-tests assumptions |
References
- Assembly guide:
production-lines/digital-talent/assembly.md - CLAUDE template:
production-lines/digital-talent/templates/CLAUDE-template.md - Skill template:
production-lines/digital-talent/templates/skill-template.md - Factory settings:
.claude/settings.json - Model catalog:
departments/it-architecture/agentic-pattern-designer-ada/model-routing-catalog.md - Integration catalog:
departments/engineering/infrastructure-engineer-ivan/integration-catalog.md - Design principles:
docs/superpowers/specs/2026-03-29-component-taxonomy-design.md(Section 3.2)