zhongwei/gh-nice-wolf-studio-wolf-skills-marketplace-wolf-core

Fork 0

Files

Zhongwei Li cf118c4923 Initial commit

2025-11-30 08:43:48 +08:00

24 KiB

Raw Blame History

name, description, version, category, triggers, dependencies, size

name

description

version

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:

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)

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:

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

**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  # MUST be first step
```
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

24 KiB Raw Blame History

Wolf Architecture Decision Records (ADRs)

Overview

How to Use This Skill

Finding Relevant ADRs

ADR Locations

Topic Clusters

🏗️ MCP Server Architecture

🔍 Verification & Quality Assurance

🐳 Sandbox & Containerization

📦 Packaging & Dependencies

📊 Metrics, Monitoring & Evals

🛡️ Security & Compliance

🎭 Agent Roles & Behavioral Archetypes

📝 Governance & Process

🧪 Research & Experimentation

🔧 Tooling & Infrastructure

Phase-Based Organization

Phase Evolution

Key Phase Milestones

Living Architecture Snapshot

ADR Format Standard

How to Navigate ADRs

By Status

By Priority

Search Strategies

Integration with Wolf Skills

Best Practices

Creating ADRs

Using ADRs

Maintaining ADRs

Related Skills

When ADRs Are REQUIRED vs OPTIONAL

REQUIRED (MUST create ADR)

OPTIONAL (Consider creating ADR)

NOT REQUIRED (Skip ADR)

Red Flags - STOP

After Using This Skill

ADR Creation Checklist

Good/Bad Examples: ADR Quality

Example 1: Well-Structured ADR

Context

Problem Statement

Decision

Consequences

Alternatives Considered

References

Context

Decision

Consequences

24 KiB

Raw Blame History