12 KiB
name, description, version, triggers
| name | description | version | triggers | |||||
|---|---|---|---|---|---|---|---|---|
| wolf-principles | Wolf's 10 core principles for agent behavior and system design | 1.2.0 |
|
Wolf Principles Skill
This skill provides access to Wolf's 10 core principles that guide the design, implementation, and operation of the Wolf Agents multi-agent system. These principles have been refined over 50+ phases of real-world development.
When to Use This Skill
- ALWAYS before making architectural decisions
- When justifying design choices or trade-offs
- During planning and implementation of new features
- When resolving conflicts between competing priorities
- For onboarding new team members or agents
The 10 Core Principles
1. Artifact-First Development
Principle: All work produces durable, verifiable artifacts rather than ephemeral conversations.
Implementation:
- Pull Requests (PRs) are the primary unit of work and evidence
- Every change must be committed, reviewed, and merged
- Conversations and decisions are captured in issues, ADRs, and journals
- No work is considered complete without a merged artifact
Example Application:
Instead of: "I fixed the bug, it works now"
Do this: Create PR with fix, tests, and documentation of root cause
2. Role Isolation and Separation of Concerns
Principle: Each agent role has clearly defined responsibilities with minimal overlap and strict boundaries.
Implementation:
- Individual GitHub Apps per role with minimal required permissions
- Agents cannot merge their own implementations
- Clear ownership matrices and authority boundaries
- Role cards define exact scope, non-goals, and collaboration patterns
Example Application:
PM Agent: Defines requirements and acceptance criteria
Coder Agent: Implements solution meeting criteria
Reviewer Agent: Validates implementation quality
QA Agent: Verifies functionality and tests
3. Research-Before-Code
Principle: All implementation work must be preceded by structured research and evidence-based recommendations. This applies at TWO levels:
- Level 1 - Architectural Research (research-agent, 2-8 hours): "Should we use this approach?"
- Level 2 - Documentation Lookup (coder-agent, 2-5 minutes): "How do I use this library's current API?"
Implementation:
Level 1 - Architectural Research:
- Mandatory Research Agent analysis before any coding begins
- Structured research comments with evidence, findings, and advised solutions
researchlabel as a blocking gate for implementation- Implementation must align with or justify deviations from research
- Time scale: 2-8 hours for feasibility, approach, and architecture decisions
Level 2 - Documentation Lookup:
- Use WebSearch/WebFetch for official API documentation before using libraries
- Verify syntax/patterns against authoritative sources (not model memory)
- Check for breaking changes, new features, and current best practices
- Look up version-specific documentation matching your project
- Time scale: 2-5 minutes per library (prevents "cold start" coding from memory)
Why Two Levels:
- Level 1 addresses unknown unknowns (architectural risks, feasibility)
- Level 2 addresses known unknowns (current API syntax, recent changes)
- Both prevent wasted implementation time from outdated assumptions
Example Application:
Task: Add authentication to API
Level 1 - Architectural Research (research-agent, 4 hours):
- Analyze existing auth patterns, security requirements, compliance needs
- Compare JWT vs OAuth2 vs Passport.js approaches
- Evaluate security implications, scalability, maintenance burden
- Deliver recommendation: "Use Passport.js with JWT strategy"
→ Output: ADR documenting decision and rationale
Level 2 - Documentation Lookup (coder-agent, 3 minutes):
- WebSearch "passport.js jwt strategy official documentation 2025"
- WebFetch https://www.passportjs.org/packages/passport-jwt/
- Verify: Current version is 4.0.1, check for breaking changes from 3.x
- Review: Example code for JWT verification and token extraction
→ Output: Implementation using current, verified API patterns
Result: Implementation informed by both architectural research (Level 1)
and current documentation (Level 2), avoiding both strategic and tactical errors.
4. Advisory-First Enforcement
Principle: New policies and constraints are tested in advisory mode before becoming hard gates.
Implementation:
- Shadow-mode validation for new rules and patterns
- Gradual rollout with confidence thresholds
- Evidence collection before enforcement
- Fallback and rollback mechanisms for all gates
Example Application:
New Rule: All PRs must have 90% test coverage
Phase 1: Report coverage but don't block (2 weeks)
Phase 2: Block if <70% coverage (2 weeks)
Phase 3: Enforce 90% threshold (ongoing)
5. Evidence-Based Decision Making
Principle: All decisions must be supported by concrete evidence and measurable outcomes.
Implementation:
- Performance budgets with measurement requirements
- Security scans and validation evidence
- Test coverage and quality metrics
- Documented trade-offs with quantified impacts
Example Application:
Decision: Choose between REST and GraphQL
Evidence Required:
- Latency benchmarks for typical queries
- Bundle size impact measurements
- Developer productivity metrics
- Maintenance cost analysis
6. Self-Improving Systems
Principle: The system continuously learns from its operations and evolves based on evidence.
Implementation:
- Comprehensive journaling of problems, decisions, and learnings
- Regular retrospectives and pattern identification
- Automated metrics collection and analysis
- Feedback loops from operations back to design
Example Application:
Problem: CI failures increasing
Journal: Document failure patterns
Analysis: Identify common root causes
Improvement: Add pre-commit checks for identified patterns
Measurement: Track CI failure rate reduction
7. Multi-Provider Resilience
Principle: The system must operate reliably across multiple AI providers with graceful fallback.
Implementation:
- Provider-agnostic interfaces and abstractions
- Automated failover between providers
- Rate limit awareness and throttling
- Provider-specific optimizations without vendor lock-in
Example Application:
Primary: OpenAI GPT-4 for complex reasoning
Fallback 1: Claude for continued operation
Fallback 2: Local models for basic functionality
Circuit Breaker: Automatic switching based on availability
8. GitHub-Native Integration
Principle: Leverage GitHub platform primitives to minimize custom infrastructure and operational overhead.
Implementation:
- GitHub Apps for authentication and authorization
- GitHub Actions for automation and workflows
- Issues and PRs for coordination and communication
- GitHub API for all programmatic interactions
Example Application:
Instead of: Custom task tracking system
Use: GitHub Issues with labels and milestones
Instead of: Custom CI/CD pipeline
Use: GitHub Actions with reusable workflows
9. Incremental Value Delivery
Principle: All work should be broken into small, independently valuable increments.
Implementation:
- Target 2-8 hour work increments for AI-accelerated development
- Each PR represents complete, testable functionality
- Continuous integration and deployment patterns
- Feature flags for gradual rollout
Example Application:
Feature: User Dashboard
Increment 1: Basic layout and navigation (2h)
Increment 2: User profile widget (3h)
Increment 3: Activity feed (4h)
Increment 4: Settings panel (2h)
Each increment is fully functional and deployable
10. Transparent Governance
Principle: All decisions, processes, and constraints must be openly documented and auditable.
Implementation:
- Public documentation of all policies and procedures
- Clear audit trails for all changes
- Role-based access controls with justification
- Regular governance reviews and updates
Example Application:
Decision: Change deployment frequency
Documentation: ADR with rationale
Audit Trail: Git history of decision
Review: Monthly governance meeting
Update: Adjust based on operational metrics
How to Query Principles
You can ask about specific principles or search across all principles:
Query by Number
"What is principle 5?" → Returns Evidence-Based Decision Making
Query by Topic
"How does Wolf handle security?" → Returns relevant principles (2, 5, 7)
Query by Implementation
"How to make decisions?" → Returns principles 3, 5, 6
Get All Principles
"Show all principles" → Returns complete list with summaries
Principle Conflicts Resolution
When principles appear to conflict, use this priority order:
- Security and Safety (Principles 2, 7)
- Evidence and Quality (Principles 3, 5, 6)
- Operational Efficiency (Principles 1, 8, 9)
- Governance and Compliance (Principles 4, 10)
Integration with Other Skills
- wolf-archetypes: Principles inform archetype behavior
- wolf-roles: Each role implements relevant principles
- wolf-governance: Principles guide governance rules
Scripts Available
query.js- Search principles by ID, keyword, or topicapply.js- Generate principle-based recommendations for specific scenarios
Evolution and Updates
These principles evolve based on operational evidence. Changes require:
- Evidence collection showing insufficiency
- Impact analysis on existing systems
- Community review from all roles
- Advisory-first deployment
- Post-implementation assessment
Red Flags - STOP
If you catch yourself thinking:
- ❌ "This is too simple to need principles" - Simple decisions cascade. Even trivial choices compound over time. Query principles BEFORE proceeding.
- ❌ "I know the right approach already" - Evidence before opinions (Principle 5). Your intuition needs validation against principles.
- ❌ "Principles don't apply to this work type" - ALL work has principles. Research? Use Principle 3. Bug fix? Use Principle 1. No exceptions.
- ❌ "I'll check principles after implementation" - Too late. Principles guide implementation, not justify it post-hoc.
- ❌ "This conflicts with deadline pressure" - Principles ENABLE speed by preventing rework. Skipping principles slows you down.
- ❌ "I'm just prototyping" - Prototypes become production (always). Use Principle 9 (incremental value) even for experiments.
STOP. Use Skill tool to load wolf-principles BEFORE proceeding.
After Using This Skill
REQUIRED NEXT STEPS:
Sequential skill chain - DO NOT skip steps
-
REQUIRED NEXT SKILL: Use wolf-archetypes to determine behavioral archetype
- Why: Principles are strategic guidance. Archetypes translate them into tactical requirements for your specific work type.
- Gate: Cannot proceed to implementation without archetype selection
- Tool: Use Skill tool to load wolf-archetypes
-
REQUIRED NEXT SKILL: Use wolf-governance to identify quality gates
- Why: Archetypes define priorities. Governance defines acceptance criteria and Definition of Done.
- Gate: Cannot claim work complete without meeting governance requirements
- Tool: Use Skill tool to load wolf-governance
-
REQUIRED NEXT SKILL: Use wolf-roles to understand collaboration patterns
- Why: Work rarely happens in isolation. Roles define who does what and how handoffs occur.
- Gate: Cannot proceed without understanding role boundaries
- Tool: Use Skill tool to load wolf-roles
DO NOT PROCEED to implementation without completing steps 1-3.
Verification Checklist
Before claiming you've applied principles:
- Queried wolf-principles for relevant guidance
- Selected archetype using wolf-archetypes
- Identified quality gates using wolf-governance
- Loaded role guidance using wolf-roles
- Created artifact (PR, ADR, journal entry) documenting decisions
Can't check all boxes? Work is incomplete. Return to this skill.
Source: docs/principles.md (lines 292-527) Last Updated: 2025-11-14 Phase: Superpowers Skill-Chaining Enhancement v2.0.0