Wolf Adr

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

1. By Topic: Use topic clusters below to find related decisions
2. By Phase: Check phase-based organization for historical context
3. By Keywords: Search for specific technologies or patterns
4. 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

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:

• wolf-governance: Search governance rules (may include ADR references)

  • Use: Skill tool → wolf-governance
  • Purpose: Understand governance requirements that drive ADR creation

• wolf-principles: Query principles (foundational to many ADRs)

  • Use: Skill tool → wolf-principles
  • Purpose: Ensure ADRs align with Wolf's 10 core principles

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

1. 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

2. 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)

3. 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:

• Status clearly marked (Proposed, Accepted, Superseded, Deprecated)
• Context section explains WHY decision is needed (not just WHAT)
• Decision section documents WHAT was chosen AND WHY
• Consequences section lists tradeoffs and impacts (positive AND negative)
• Alternatives Considered section documents rejected options with rationale
• Related ADRs linked (if decision builds on or supersedes previous ADRs)
• ADR follows standard format (Context → Problem → Decision → Consequences → Alternatives)

Can't check all boxes? ADR incomplete. Return to this skill.

Good/Bad Examples: ADR Quality

Example 1: Well-Structured ADR

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:

1. Missing checkout steps (37% of failures)
2. Incorrect API field usage (100% failure when wrong fields used)
3. 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:

1. Mandatory Checkout Step:

   - uses: actions/checkout@v4  # MUST be first step
   

   Rationale: Without checkout, workflows cannot access repository files.

2. 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.

3. 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

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