| name | wolf-adr |
| description | Architecture Decision Records index with searchable topics and phase-based organization (120+ ADRs from 50+ phases) |
| version | 1.1.0 |
| category | architecture |
| triggers | ["architecture decision","ADR","design decision","technical decision","system design"] |
| dependencies | ["wolf-principles"] |
| size | large |
Wolf Architecture Decision Records (ADRs)
Searchable index of 120+ Architecture Decision Records documenting Wolf's evolution through 50+ phases of development.
Overview
Wolf's ADRs capture critical architectural decisions, including:
- Context: Why the decision was needed
- Decision: What was chosen and why
- Consequences: Impact and tradeoffs
- Status: Proposed, Accepted, Superseded, Deprecated
- Related ADRs: Decision dependencies
How to Use This Skill
Finding Relevant ADRs
- By Topic: Use topic clusters below to find related decisions
- By Phase: Check phase-based organization for historical context
- By Keywords: Search for specific technologies or patterns
- Current Architecture: See "Living Snapshot" section
ADR Locations
All ADRs in /docs/adr/:
- Current/Active:
docs/adr/ADR-XXX-*.md and docs/adr/phase-*/shard-*/ADR-*.md
- Archived:
docs/adr/archive/ADR-*.md
- Living Snapshot:
docs/adr/phase-50/shard-50-5/current-architecture-2025-10-07.md
Topic Clusters
🏗️ MCP Server Architecture
Key Decisions:
- ADR-017: MCP Server Conversion Strategy (identified 15-20 packages)
- ADR-018: MCP Server Architecture (implementation of 3 operational servers)
- ADR-023: Knowledge-First Pivot ⭐ (critical shift from operational to knowledge-serving)
- Problem: Built operational tools that duplicated agent capabilities
- Solution: MCP servers should expose Wolf's accumulated knowledge
- Impact: 9 of 15 tools identified as redundant; pivot to knowledge access
- ADR-025: Hybrid MCP Consolidation Strategy
- Decision: Keep operational MCPs for Wolf-specific logic, sunset duplicates
- Result: wolf-knowledge-mcp (primary), wolf-governance-mcp, wolf-evals-mcp
When to Reference:
- Designing new MCP servers
- Deciding operational vs. knowledge tools
- Understanding Wolf's MCP evolution
Files:
/docs/adr/archive/ADR-017-mcp-server-conversion-strategy.md/docs/adr/archive/ADR-023-mcp-server-knowledge-first-pivot.md/docs/adr/archive/ADR-025-hybrid-mcp-consolidation.md
🔍 Verification & Quality Assurance
Key Decisions:
- ADR-043: Verification Architecture ⭐ (CoVe, HSP, RAG)
- CoVe: Chain of Verification for systematic fact-checking
- HSP: Hierarchical Safety Prompts for multi-level validation
- RAG: Grounding evidence retrieval
- Integration: 3-layer verification pipeline
- ADR-0051: Retrieval-CoVe Hybrid (combining retrieval with verification)
- ADR-0061: Hallucination Drift Watchdog (detecting and preventing hallucinations)
- ADR-0050: Policy Intelligence Engine Accuracy Enhancement
When to Reference:
- Implementing self-verification
- Building quality gates
- Hallucination detection
- Evidence-based validation
Files:
/docs/adr/phase-43/shard-00/ADR-0043-verification-architecture.md (if exists)/docs/adr/archive/ADR-0051-retrieval-cove-hybrid.md/docs/adr/archive/ADR-0061-hallucination-drift-watchdog.md
🐳 Sandbox & Containerization
Key Decisions:
- ADR-0063: Sandbox Containerization Strategy
- Problem: Need isolated code execution environment
- Solution: Docker-based sandbox with security constraints
- ADR-0064: Sandbox Quota Enforcement Architecture
- Resource Limits: CPU, memory, disk I/O quotas
- Enforcement: Pre-execution checks and runtime monitoring
- ADR-0065: Sandbox Security Architecture
- Security Layers: Network isolation, filesystem restrictions, capability dropping
When to Reference:
- Implementing code execution environments
- Setting resource limits
- Security hardening for sandboxes
Files:
/docs/adr/archive/ADR-0063-sandbox-containerization-strategy.md/docs/adr/archive/ADR-0064-sandbox-quota-enforcement-architecture.md/docs/adr/archive/ADR-0065-sandbox-security-architecture.md
###⚙️ CI/CD & GitHub Actions
Key Decisions:
- ADR-072: GitHub Actions Workflow Standards ⭐ (mandatory patterns)
- Problem: 37% failure rate due to missing checkout steps, 100% failure with wrong API fields
- Solution: Mandatory checkout step, correct API field names, permissions declaration
- Impact: Prevents infrastructure failures across all workflows
- ADR-071: CI Workflow Optimization Strategy (workflow consolidation, cost management)
- ADR-056: Composite Actions Standard
- Reusable Workflows: Extract common patterns into composite actions
- Benefits: DRY, consistency, maintainability
- ADR-048-5: Actions Audit (audit trail for GitHub Actions)
- ADR-070: Agent Build Pipeline (agent-specific CI/CD)
When to Reference:
- Creating new GitHub workflows
- Fixing workflow failures
- Implementing composite actions
- Workflow optimization
Files:
/docs/adr/ADR-072-github-actions-workflow-standards.md/docs/adr/archive/ADR-056-composite-actions.md (if exists)/docs/adr/archive/ADR-070-agent-build-pipeline.md
📦 Packaging & Dependencies
Key Decisions:
- ADR-016: Dependency Optimization Strategy
- Approach: Fork and optimize 279 npm packages
- Result: 83.3% of dependencies optimized via
jdmiranda/* repos
- Branches: All forks use
perf/* branches
- ADR-055: Packaging Standard
- Conventions: Package naming, versioning, distribution
- Quality Gates: Build, test, publish standards
When to Reference:
- Adding new dependencies
- Optimizing existing packages
- Package publishing decisions
Files:
/docs/adr/archive/ADR-016-dependency-optimization-strategy.md/docs/adr/archive/ADR-055-packaging-standard.md
📊 Metrics, Monitoring & Evals
Key Decisions:
- ADR-0048-2: Metrics Framework
- Categories: Agent efficiency, workflow latency, quality scores
- Collection: Privacy-preserving metrics with PII redaction
- ADR-0061: Baseline-Target Tracking (performance baseline establishment)
- wolf-evals-mcp: Agent efficiency metrics (latency, efficiency, token tracking)
When to Reference:
- Implementing telemetry
- Performance monitoring
- Establishing baselines
- Efficiency tracking
Files:
/docs/adr/archive/ADR-0048-2-metrics.md/docs/adr/archive/ADR-0061-baseline-target-tracking.md
🛡️ Security & Compliance
Key Decisions:
- ADR-0065: Sandbox Security Architecture (isolation, restrictions, capability dropping)
- Security Hardener Archetype: Threat reduction priority, defense-in-depth
- Governance Framework: Mandatory security validation for security-labeled work
When to Reference:
- Security architecture decisions
- Threat modeling
- Compliance requirements
- Secure code execution
🎭 Agent Roles & Behavioral Archetypes
Key Decisions:
- ADR-0049: Role Card Integrity
- Problem: Role card drift and inconsistency
- Solution: Validation framework, schema enforcement
- Archetype System: 11 behavioral profiles (ADR embedded in archetype registry)
- product-implementer, security-hardener, perf-optimizer, reliability-fixer, etc.
- Lens System: 4 overlay lenses (performance, security, accessibility, observability)
When to Reference:
- Defining new agent roles
- Modifying existing archetypes
- Understanding agent behavioral adaptation
Files:
/docs/adr/archive/ADR-0049-role-card-integrity.md/agents/archetypes/registry.yml (contains embedded archetype decisions)/agents/lenses/registry.yml (contains lens application rules)
📝 Governance & Process
Key Decisions:
- ADR-0048-7: Conditional Approvals (automated approval workflows)
- ADR-0048-10: Research Hygiene (research phase standards)
- ADR-047-C: Output Summary Validation (standardized output format)
- Emergency Governance Activation: Override mechanisms for critical issues
When to Reference:
- Governance policy decisions
- Approval workflow design
- Process standardization
Files:
/docs/adr/archive/ADR-0048-7-conditional-approvals.md/docs/adr/archive/ADR-0048-10-research-hygiene.md/docs/adr/archive/ADR-047-C-output-summary-validation.md
🧪 Research & Experimentation
Key Decisions:
- ADR-0053: Research Agent Workflow
- Process: Hypothesis → Experiment → Validation → Documentation
- Time-boxing: Fixed duration for research spikes
- Research-Prototyper Archetype: Hypothesis testing, feasibility analysis
When to Reference:
- Planning research spikes
- Experimentation workflows
- Proof-of-concept development
Files:
/docs/adr/archive/ADR-0053-research-agent-workflow.md
🔧 Tooling & Infrastructure
Key Decisions:
- wolfctl: Safe command runner with policy enforcement
- Command Policy:
tools/wolfctl/command-policy.json
- Hardened Shell: Policy-enforced execution
- ADR-024: MCP Tool Candidates Comprehensive Discovery
- Survey: Identified 15-20 candidate packages for MCP conversion
- ADR-0069: Claude Code SDK Integration (Phase 3 before/after analysis)
When to Reference:
- Tool development decisions
- Infrastructure patterns
- SDK integration approaches
Files:
/docs/adr/archive/ADR-024-mcp-tool-candidates-comprehensive-discovery.md/docs/adr/archive/ADR-0069-claude-code-sdk-integration.md
Phase-Based Organization
Phase Evolution
Phases 1-40: Foundation
- Agent role definitions
- Core principles establishment
- Initial workflow patterns
Phases 41-45: Quality Systems
- Verification frameworks (CoVe, HSP, RAG)
- Testing pipelines
- Quality gates
Phases 46-50: MCP Integration
- ADR-017: MCP conversion strategy
- ADR-023: Knowledge-first pivot ⭐
- ADR-025: Hybrid consolidation
- wolf-knowledge-mcp operational
Phase 50+ (Current): Refinement
- ADR-072: Workflow standards
- Composite actions
- Enhanced verification
Key Phase Milestones
| Phase | Key Decision | ADR | Impact |
|---|
| 43 | Verification Architecture | ADR-043 | 3-layer verification (CoVe/HSP/RAG) |
| 46-48 | MCP Server Strategy | ADR-017/018 | Operational MCP servers built |
| 49 | Knowledge-First Pivot | ADR-023 | Recognized operational redundancy |
| 50 | Hybrid Consolidation | ADR-025 | wolf-knowledge-mcp primary |
| 50+ | Workflow Standards | ADR-072 | Mandatory GitHub Actions patterns |
Living Architecture Snapshot
Current Architecture (October 2025)
The most comprehensive current view is at:
/docs/adr/phase-50/shard-50-5/current-architecture-2025-10-07.md
This living document synthesizes all 50+ phases into a current system snapshot, including:
- 4 active MCP servers
- 44 agent roles with inheritance
- 3-layer verification architecture
- Docker-based sandbox infrastructure
- GitHub-native workflow integration
- 335 npm packages (279 optimized forks)
When to Use: Starting new work, onboarding, architecture review, system understanding
ADR Format Standard
Wolf ADRs follow this structure:
# ADR-XXX: Title
**Status**: Proposed | Accepted | Superseded | Deprecated
**Date**: YYYY-MM-DD
**Deciders**: Role names
**Related ADRs**: Links to related decisions
---
## Context
[Why this decision is needed, background, constraints]
## Problem Statement
[Specific problem being solved]
## Decision
[What was chosen and why]
## Consequences
[Impact, tradeoffs, what changes]
## Alternatives Considered
[Other options and why rejected]
---
## References
[Related docs, issues, PRs]
How to Navigate ADRs
By Status
- Proposed: Under review, not yet implemented
- Accepted: Approved and active
- Superseded: Replaced by newer ADR
- Deprecated: No longer applicable
By Priority
- ⭐ Critical ADRs (starred above): Must-read for architecture understanding
- Topic ADRs: Read when working in specific domain
- Historical ADRs: Context for evolution, not always current
Search Strategies
Problem-Based: "I need to solve X"
→ Check topic cluster for X
→ Read ADRs in that cluster
→ Follow related ADRs
Technology-Based: "I'm working with Y"
→ Search ADR index for Y
→ Check current architecture doc
→ Trace decision history
Phase-Based: "What changed in Phase Z?"
→ Look at phase-Z ADRs
→ Compare with previous phase
→ Understand evolution
Integration with Wolf Skills
Wolf ADR skill integrates with other Wolf skills:
Best Practices
Creating ADRs
- ✅ Document why not just what
- ✅ Include alternatives considered
- ✅ Link related ADRs
- ✅ Update status when superseded
- ❌ Don't create ADRs for trivial decisions
- ❌ Don't skip consequences section
Using ADRs
- ✅ Read current architecture first for overview
- ✅ Trace decision history for context
- ✅ Check status before applying patterns
- ✅ Reference ADRs in new decisions
- ❌ Don't assume old ADRs are current
- ❌ Don't skip related ADRs
Maintaining ADRs
- ✅ Mark superseded ADRs clearly
- ✅ Keep index up to date
- ✅ Archive old ADRs properly
- ✅ Update living architecture doc
- ❌ Don't delete ADRs (archive instead)
- ❌ Don't modify accepted ADRs (create new superseding ADR)
Related Skills
- wolf-principles: Foundation for many ADRs
- wolf-governance: Process decisions documented in ADRs
- wolf-archetypes: Behavioral archetype decisions
- wolf-workflows-ci: GitHub Actions patterns from ADR-072
- wolf-verification: Verification architecture from ADR-043
When ADRs Are REQUIRED vs OPTIONAL
REQUIRED (MUST create ADR)
✅ Architectural Changes:
- Changing system architecture or major component structure
- Adding/removing services or significant dependencies
- Modifying data flow or integration patterns
- Infrastructure architecture decisions
✅ Process Changes:
- Modifying Wolf's core workflows or methodology
- Changing governance policies or quality gates
- Updating agent role definitions or responsibilities
- Altering approval hierarchies or authority matrix
✅ Tool Selections:
- Choosing between competing technologies or frameworks
- Adopting new core dependencies (databases, frameworks, etc.)
- Changing build systems or CI/CD platforms
- MCP server architecture decisions
✅ Security Decisions:
- Authentication/authorization approaches
- Security architecture or threat mitigation strategies
- Compliance framework changes
OPTIONAL (Consider creating ADR)
⚠️ Significant Patterns:
- New code patterns that will be reused across codebase
- Design patterns that affect multiple components
- Performance optimization strategies
⚠️ Experimental Approaches:
- Research spikes with significant findings
- Proof-of-concept results that inform future direction
NOT REQUIRED (Skip ADR)
❌ Trivial Decisions:
- Bug fixes (use journal entry instead)
- Refactoring without behavior change (use journal entry)
- Minor code cleanup or formatting
- Documentation updates (unless process change)
❌ Implementation Details:
- Variable naming conventions
- File organization within existing structure
- Code comment standards
Rule of Thumb: If the decision affects future work or needs to be understood months later by different agents, create an ADR.
Red Flags - STOP
If you catch yourself thinking:
- ❌ "ADRs are optional documentation" - NO. ADRs are REQUIRED for architectural, process, and tool decisions. They prevent repeated debates.
- ❌ "I'll write the ADR later" - FORBIDDEN. ADRs must be created BEFORE or DURING decision-making, not after. Later = never.
- ❌ "This decision is too small for an ADR" - Wrong metric. If it affects future work or needs historical context, ADR is required.
- ❌ "I can modify an accepted ADR" - NO. Accepted ADRs are immutable. Create a new superseding ADR instead.
- ❌ "ADR format doesn't matter" - False. Wolf has a standard ADR format. Follow it for consistency and discoverability.
STOP. Create ADR using standard format BEFORE making architectural/process decisions.
After Using This Skill
RECOMMENDED NEXT STEPS:
ADRs document decisions - used for context and reference
-
Creating an ADR: Use wolf-governance for quality gates
- When: Before making architectural/process/tool decisions
- Why: ADRs are part of Definition of Done for architectural changes
- Tool: Use Skill tool to load wolf-governance
-
Understanding Decisions: Use wolf-principles for decision framework
- When: Evaluating alternatives for ADR
- Why: Principles guide decision-making (e.g., Research-First, Evidence-Based)
- Tool: Use Skill tool to load wolf-principles (focus on Principle #5: Evidence-Based Decisions)
-
No specific next skill: ADRs are referenced throughout work
- This skill provides ADR index and navigation
- wolf-governance specifies when ADRs are required
- wolf-principles guide ADR content (alternatives, consequences)
ADR Creation Checklist
Before claiming ADR complete:
Can't check all boxes? ADR incomplete. Return to this skill.
Good/Bad Examples: ADR Quality
Example 1: Well-Structured ADR
**ADR-072: GitHub Actions Workflow Standards**
Status: Accepted
Date: 2025-10-15
Deciders: DevOps Team, Code Reviewers
Related ADRs: ADR-071 (CI Workflow Optimization), ADR-056 (Composite Actions)
Context
GitHub Actions workflows across WolfAgents had a 37% failure rate due to:
- Missing checkout steps (37% of failures)
- Incorrect API field usage (100% failure when wrong fields used)
- Undeclared permissions causing authorization failures
Investigation of 43 workflows revealed systemic anti-patterns. Need standardized patterns to prevent infrastructure failures.
Problem Statement
How do we prevent recurring workflow failures caused by missing checkout steps, incorrect GitHub API usage, and permission errors?
Decision
Mandate the following standards for all GitHub Actions workflows:
-
Mandatory Checkout Step:
- uses: actions/checkout@v4
Rationale: Without checkout, workflows cannot access repository files.
-
Correct API Field Names:
- Use
closingIssuesReferences not closes for gh pr view
- Use
labels not label for gh issue view
Rationale: GitHub CLI expects specific field names; typos cause 100% failure.
-
Explicit Permissions:
permissions:
contents: read
pull-requests: write
issues: write
Rationale: Prevent authorization failures with least-privilege declarations.
Consequences
Positive:
- ✅ Eliminates 37% of workflow failures (missing checkout)
- ✅ Prevents 100% failure rate from API field typos
- ✅ Clear permission boundaries prevent security issues
- ✅ Reusable pattern across all 43+ workflows
Negative:
- ⚠️ Requires updating all existing workflows (one-time cost)
- ⚠️ Adds 3-5 lines to each workflow (minimal verbosity)
Alternatives Considered
Alternative 1: Documentation only (no enforcement)
- Rejected: Documentation alone didn't prevent recurring failures
- Teams repeatedly forgot checkout step despite documentation
Alternative 2: Pre-commit hooks to validate workflows
- Rejected: Hooks can be bypassed; workflow validation happens too late
- Better to mandate in CI template
Alternative 3: Composite action wrapper
- Rejected: Hides checkout step, makes debugging harder
- Mandatory explicit step is more transparent
References
- Issue #789: 37% workflow failure analysis
- PR #845: Workflow standards implementation
- docs/governance/workflow-validation.md
Why this is excellent:
- ✅ Context explains WHY (failure rates, specific problems)
- ✅ Decision documents WHAT + WHY + HOW (with code examples)
- ✅ Consequences lists both positive AND negative impacts
- ✅ Alternatives explained with rejection rationale
- ✅ Quantified impact (37% failure rate, 100% API field failures)
- ✅ Related ADRs linked for context
- ✅ References provide evidence trail
**ADR-999: Use Docker**
Status: Proposed
Date: 2025-10-20
Context
We should use Docker.
Decision
Use Docker for containerization.
Consequences
It will be good.
Why this is terrible:
- ❌ No context about WHY Docker is needed
- ❌ No problem statement (what problem does Docker solve?)
- ❌ Decision lacks rationale (WHY Docker vs alternatives?)
- ❌ "It will be good" is not a consequence (no tradeoffs, no specifics)
- ❌ No alternatives considered (why not Podman, VMs, native execution?)
- ❌ No related ADRs (surely there are related infra decisions?)
- ❌ No references (no evidence, no analysis)
- ❌ Not enough detail to understand decision months later
What this should include:
## Context
Current code execution happens on host machine, causing:
1. Security concerns (untrusted code access to host)
2. Resource contention (no isolation between jobs)
3. Dependency conflicts (version mismatches)
Analyzed 200+ execution failures: 45% due to dependency conflicts, 30% resource contention.
## Problem Statement
How do we provide isolated, reproducible code execution environments with resource limits and security boundaries?
## Decision
Use Docker containers for code execution with:
- Resource limits (CPU, memory, disk quotas)
- Network isolation
- Filesystem restrictions
- Capability dropping
Rationale:
- Industry standard (widespread knowledge, tooling)
- Strong isolation model (namespaces, cgroups)
- Reproducible environments (Dockerfile = config as code)
- Resource control (native cgroup support)
## Consequences
Positive:
- ✅ Eliminates 45% of dependency conflict failures
- ✅ Prevents resource contention (isolated CPU/memory)
- ✅ Stronger security boundaries (container escape harder than process escape)
- ✅ Reproducible across dev/CI/prod
Negative:
- ⚠️ Adds Docker dependency (ops overhead)
- ⚠️ Container startup latency (200-500ms vs instant process)
- ⚠️ Increased disk usage (images ~100-500MB)
- ⚠️ Requires Docker daemon (privilege escalation risk)
## Alternatives Considered
1. **Podman**: rootless containers
- Rejected: Less mature tooling, team unfamiliar
- May revisit if Docker security concerns grow
2. **VMs (Firecracker)**: microVMs
- Rejected: Higher overhead (2-3 second startup)
- Overkill for current security requirements
3. **Native Execution with chroot**: OS-level isolation
- Rejected: Weaker isolation, no resource limits
- Insufficient for untrusted code
## References
- Spike results: docs/research/containerization-spike-2025-10.md
- Security analysis: docs/security/execution-isolation-threats.md
- Performance benchmarks: docs/benchmarks/container-overhead.md
Now THAT would be an acceptable ADR.
Total ADRs: 120+
Active ADRs: ~70
Archived ADRs: ~50
Living Documents: 1 (current-architecture)
Last Updated: 2025-11-14
Phase: Superpowers Skill-Chaining Enhancement v2.0.0
Maintainer: Architecture Team
