Initial commit

2025-11-30 08:43:48 +08:00
commit cf118c4923
27 changed files with 10878 additions and 0 deletions
--- a/skills/wolf-instructions/SKILL.md
+++ b/skills/wolf-instructions/SKILL.md
@@ -0,0 +1,780 @@
+---
+name: wolf-instructions
+description: Four-level instruction cascading system (Global → Domain → Project → Role) with priority-based conflict resolution
+version: 1.1.0
+category: agent-coordination
+triggers:
+  - instruction cascade
+  - agent instructions
+  - role boundaries
+  - authority matrix
+  - agent coordination
+dependencies:
+  - wolf-roles
+  - wolf-governance
+  - wolf-principles
+size: large
+---
+
+# Wolf Instruction Cascading System
+
+Four-level instruction hierarchy that ensures consistent agent behavior across 43 roles while allowing environment-specific and role-specific customization.
+
+## Overview
+
+Wolf's instruction system prevents duplication while enabling specialization through a clear hierarchy:
+
+1. **Global Instructions** (21 files) - Universal policies applying to ALL agents
+2. **Domain Instructions** (3 files) - Technical domain patterns (web, data, ops)
+3. **Project Instructions** (3 files) - Environment-specific overrides
+4. **Role Instructions** - Role-specific behavior (in role-card.md files)
+5. **Variant Instructions** - Stack-specific customization
+
+**Key Principle**: Closest instruction wins on conflicts. Project > Role/Variant > Domain > Global.
+
+---
+
+## 📚 Instruction Hierarchy
+
+### Reading Order (Every Agent MUST Follow)
+
+```
+1. Read ALL Global Instructions (21 files)
+   └─> Universal policies that cannot be overridden (security, governance)
+   └─> Common patterns (GitHub coordination, communication, journaling)
+
+2. Read Relevant Domain Instructions (1-3 files)
+   └─> web.md (for web development roles)
+   └─> data.md (for data processing roles)
+   └─> ops.md (for operations/DevOps roles)
+
+3. Read ALL Project Instructions (3 files)
+   └─> repository-operations.md (GitHub CLI patterns)
+   └─> multi-instance-coordination.md (Multi-repo coordination)
+   └─> production-patterns.md (Production-ready patterns)
+
+4. Read Role-Specific Instructions
+   └─> Continue reading role-card.md for role behavior
+
+5. Read Variant-Specific Instructions (if applicable)
+   └─> Stack-specific tooling and patterns
+```
+
+### Priority Order (Conflict Resolution)
+
+When instructions conflict, apply this priority (highest wins):
+
+```
+1. Project Instructions       # Environment-specific overrides
+2. Role/Variant Instructions   # Specific role behavior
+3. Domain Instructions         # Technical domain patterns
+4. Global Instructions         # Universal agent behavior
+```
+
+**Example Conflict**:
+- Global: "Use 2-space indentation"
+- Project: "Use 4-space indentation for this codebase"
+- **Result**: Use 4-space indentation (Project wins)
+
+**Non-Overridable Global Policies**:
+- Security standards (no plaintext secrets, auth requirements)
+- Governance gates (evidence requirements, PR standards)
+- Identity verification (heartbeat protocol)
+- SLA requirements
+
+---
+
+## 🌍 Global Instructions (21 files)
+
+Location: `/agents/instructions/global/`
+
+### Core Coordination
+
+#### 1. **identity-heartbeat.md**
+**Purpose**: Identity verification every 5 minutes to prevent context drift
+
+**Key Requirements**:
+```markdown
+Every 5 minutes, agents MUST verify:
+- Current role (pm-agent, coder-agent, etc.)
+- Current archetype (if applicable)
+- Current phase of work
+- Active lenses (performance, security, etc.)
+
+If identity cannot be verified → STOP and request clarification
+```
+
+**When to Use**:
+- Start of every agent session
+- After context compaction events
+- When switching between tasks
+- Every 5 minutes during long sessions
+
+#### 2. **eight-phase-methodology.md** / **wolf-8-v2-methodology.md**
+**Purpose**: Standard 8-phase work methodology
+
+**Phases**:
+```
+Phase 1: Introspection  - Understand requirements
+Phase 2: Research       - Gather evidence
+Phase 3: Strategy       - Design approach
+Phase 4: Prototype      - Build proof-of-concept
+Phase 5: Execute        - Implement solution
+Phase 6: Validate       - Test and verify
+Phase 7: Journal        - Document learnings
+Phase 8: Reality Check  - Verify meets requirements
+```
+
+**When to Use**:
+- All non-trivial work items
+- Feature development
+- Bug fixes requiring investigation
+- Research spikes
+
+#### 3. **github-coordination.md**
+**Purpose**: GitHub issue/PR coordination patterns
+
+**Key Patterns**:
+```markdown
+# Issue Workflow
+intake → pm-ready → review-ready → qa-ready → release-ready → deployed
+
+# PR Standards
+- Link to parent issue
+- Include evidence (screenshots, benchmarks, etc.)
+- Follow archetype-specific PR template
+- Apply appropriate labels
+
+# Label Usage
+- agent:<role> for agent assignments
+- archetype:<type> for behavioral profile
+- lens:<name> for overlay requirements
+- status:<state> for workflow tracking
+```
+
+**When to Use**:
+- Creating issues or PRs
+- Transitioning workflow states
+- Coordinating multi-agent workflows
+
+#### 4. **authority-matrix.md**
+**Purpose**: Agent authority boundaries and conflict resolution
+
+**Authority Hierarchy**:
+```
+| Domain                  | Authority        | Examples                      |
+|-------------------------|------------------|-------------------------------|
+| Requirements & Scope    | PM Agent         | What to build, timeline       |
+| Technical Architecture  | Reviewer Agent   | Code patterns, system design  |
+| Test Strategy           | QA Agent         | What to test, coverage        |
+| Performance/Security    | GLOBAL POLICY    | Cannot be overridden          |
+```
+
+**Escalation Path**:
+```
+Direct Conflict → Authority Agent → Orchestrator (final)
+```
+
+**When to Use**:
+- Resolving conflicts between agents
+- Determining decision authority
+- Escalating blocked decisions
+
+#### 5. **communication.md**
+**Purpose**: Inter-agent communication standards
+
+**Communication Channels**:
+```markdown
+1. GitHub Comments - Asynchronous, audit trail
+2. Mailbox System - Structured messages (see wolf-scripts-agents)
+3. Workflow Signals - Structured handoffs (AGENT_HANDOFF_TO)
+4. Labels - State communication (agent:pm-agent)
+```
+
+**Message Format**:
+```markdown
+## To: <target-agent>
+## From: <source-agent>
+## Subject: <concise-summary>
+
+### Context
+[Background and current state]
+
+### Request
+[What needs to be done]
+
+### Evidence
+[Supporting information, links, data]
+
+### Success Criteria
+[How to know when done]
+```
+
+**When to Use**:
+- Agent handoffs
+- Requesting work from another agent
+- Reporting completion
+- Escalating issues
+
+#### 6. **journaling.md**
+**Purpose**: Work documentation requirements
+
+**Journal Structure**:
+```markdown
+# YYYY-MM-DD: <Kebab-Case-Title>
+
+## Problems Encountered
+- [Specific problem with context]
+
+## Decisions Made
+- [Decision with rationale]
+
+## Learnings
+- [What was learned, pattern extracted]
+
+## References
+- [Links to issues, PRs, docs]
+```
+
+**Location**: `agents/roles/<role>/journals/YYYY-MM-DD-<slug>.md`
+
+**When to Use**:
+- After completing significant work
+- When encountering novel problems
+- After making architectural decisions
+- For bug fixes (Reflection Report required)
+
+### Governance & Quality
+
+#### 7. **security-and-compliance.md**
+**Purpose**: Security standards (GLOBAL POLICY - cannot be overridden)
+
+**Mandatory Requirements**:
+```markdown
+✅ MUST:
+- No plaintext secrets in code or configs
+- Use environment variables for sensitive data
+- Validate all user inputs
+- Sanitize all outputs
+- Follow principle of least privilege
+
+❌ MUST NOT:
+- Commit .env files
+- Store credentials in code
+- Bypass authentication/authorization
+- Disable security features for convenience
+```
+
+**When to Use**:
+- Before committing code
+- When handling secrets or credentials
+- Designing authentication/authorization
+- Security reviews
+
+#### 8. **sla-policy.md**
+**Purpose**: Service level agreements for agent responsiveness
+
+**SLA Tiers**:
+```markdown
+| Priority | Response Time | Resolution Time | Escalation |
+|----------|--------------|-----------------|------------|
+| P0       | 15 minutes   | 4 hours         | Immediate  |
+| P1       | 2 hours      | 1 day           | 4 hours    |
+| P2       | 1 day        | 1 week          | 3 days     |
+| P3       | 1 week       | 1 month         | 2 weeks    |
+```
+
+**When to Use**:
+- Prioritizing work items
+- Setting expectations with stakeholders
+- Escalating overdue items
+
+#### 9. **validation-gates.md**
+**Purpose**: Quality gates and validation requirements
+
+**Quality Gates**:
+```markdown
+# Pre-commit
+- Linting passes
+- Unit tests pass
+- Security scan (0 critical, ≤5 high)
+
+# Pre-PR
+- Fast-lane tests pass (5-10 min)
+- Evidence collected per archetype
+- PR template completed
+
+# Pre-merge
+- Full-suite tests pass (30-60 min)
+- Archetype-specific validation
+- Reviewer approval
+```
+
+**When to Use**:
+- Before committing code
+- Before creating PRs
+- Before merging to main
+- Implementing new quality gates
+
+### Workflow & Process
+
+#### 10. **orchestration-invariants.md**
+**Purpose**: System coordination rules that ensure workflow integrity
+
+**Invariants** (conditions that must ALWAYS be true):
+```markdown
+1. Every issue has exactly one assigned agent at a time
+2. Workflow states only transition forward (no backward transitions except needs-rework)
+3. Evidence is collected before workflow state advances
+4. Handoffs include structured context (not "figure it out")
+5. No work starts without clear acceptance criteria
+```
+
+**When to Use**:
+- Designing multi-agent workflows
+- Validating workflow transitions
+- Debugging coordination issues
+
+#### 11. **research-policy.md**
+**Purpose**: Research phase standards (NEW vs OLD classification)
+
+**Research Requirements**:
+```markdown
+# NEW Technology (<2 years old)
+- NO research required, proceed with implementation
+
+# OLD Technology (≥2 years old)
+- MANDATORY research phase
+- Web research for current best practices
+- Document findings before proceeding
+```
+
+**When to Use**:
+- Before starting feature development
+- Evaluating technology choices
+- Updating legacy systems
+
+#### 12. **labels.md**
+**Purpose**: Label standardization and taxonomy
+
+**Label Categories**:
+```markdown
+# Agent Assignment
+agent:<role>  (e.g., agent:pm-agent, agent:coder-agent)
+
+# Behavioral Profile
+archetype:<type>  (e.g., archetype:security-hardener)
+
+# Overlay Requirements
+lens:<name>  (e.g., lens:performance, lens:security)
+
+# Workflow State
+status:<state>  (e.g., status:pm-ready, status:review-ready)
+
+# Priority
+priority:P0, priority:P1, priority:P2, priority:P3
+
+# Type
+type:bug, type:feature, type:refactor, type:research
+```
+
+**When to Use**:
+- Creating or updating issues/PRs
+- Filtering work items
+- Triggering automation
+
+### Additional Global Instructions
+
+#### 13. **command-grammar.md**
+**Purpose**: Message prefixes and flags for meta-communication
+
+**Prefixes** (single-message scope):
+```markdown
+OOC:        # Out of character - normal conversation
+AS:<role>:  # Temporarily act as different agent
+META:       # System/meta discussion
+```
+
+**Flags** (combine with prefixes):
+```markdown
+NOJOURNAL   # Don't write to Problems/Decisions/Learnings
+NOTOOLS     # Don't execute scripts or external tools
+NOCI        # Don't modify CI/CD settings
+DRYRUN      # Generate plans only, no actual changes
+```
+
+**Example**: `OOC: NOJOURNAL NOTOOLS Explain this code pattern`
+
+#### 14. **mailbox-communication.md**
+**Purpose**: Async inter-agent communication using file-based mailboxes
+
+See **wolf-scripts-agents** skill for implementation details.
+
+#### 15. **report-template.md**
+**Purpose**: Standardized output format for agent reports
+
+#### 16. **wolf-ethos.md**
+**Purpose**: Wolf's philosophical foundation and values
+
+#### 17. **compaction-recovery.md**
+**Purpose**: Recovering agent state after context compaction
+
+---
+
+## 🔧 Domain Instructions (3 files)
+
+Location: `/agents/instructions/domain/`
+
+### web.md
+**Applies to**: Frontend/backend web development roles
+
+**Key Patterns**:
+```markdown
+# Frontend
+- React/Next.js patterns
+- Component structure
+- State management
+- Responsive design
+- Accessibility (a11y)
+
+# Backend
+- API design (REST, GraphQL)
+- Authentication/authorization
+- Database patterns
+- Caching strategies
+- Error handling
+```
+
+**When to Use**:
+- Web application development
+- API design and implementation
+- Frontend component work
+
+### data.md
+**Applies to**: Data processing and analytics roles
+
+**Key Patterns**:
+```markdown
+# Data Processing
+- ETL pipelines
+- Data validation
+- Schema migrations
+- Performance optimization
+
+# Analytics
+- Query optimization
+- Aggregation patterns
+- Reporting standards
+```
+
+**When to Use**:
+- Database schema changes
+- Data pipeline development
+- Analytics implementation
+
+### ops.md
+**Applies to**: DevOps and operations roles
+
+**Key Patterns**:
+```markdown
+# Infrastructure
+- Docker containerization
+- CI/CD pipelines
+- Deployment strategies
+- Monitoring and alerting
+
+# Operations
+- Incident response
+- Performance tuning
+- Capacity planning
+- Security hardening
+```
+
+**When to Use**:
+- Infrastructure changes
+- CI/CD modifications
+- Deployment procedures
+- Operational improvements
+
+---
+
+## 📁 Project Instructions (3 files)
+
+Location: `/agents/instructions/project/`
+
+### repository-operations.md
+**Purpose**: GitHub CLI patterns and repository naming conventions
+
+**Key Patterns**:
+```bash
+# Issue Operations
+gh issue create --title "..." --body "..." --label "..."
+gh issue edit <number> --add-label "status:pm-ready"
+gh issue view <number> --json title,body,labels
+
+# PR Operations
+gh pr create --title "..." --body "..." --base main
+gh pr view <number> --json closingIssuesReferences,isDraft
+gh pr merge <number> --squash
+
+# Repository Operations
+gh repo view --json name,description,topics
+```
+
+**When to Use**:
+- Automating GitHub operations
+- Workflow scripting
+- Repository management
+
+### multi-instance-coordination.md
+**Purpose**: Coordinating multiple copies of the repository
+
+**Key Patterns**:
+```markdown
+# Naming Convention
+- Primary: WolfAgents (canonical)
+- Copy 1: WolfAgents_1
+- Copy 2: WolfAgents_2
+
+# Coordination
+- Use labels to indicate which copy is primary for work
+- Sync changes via patches or cherry-picks
+- Avoid duplicate work across copies
+```
+
+**When to Use**:
+- Working across multiple repo copies
+- Syncing changes between copies
+- Coordinating parallel development
+
+### production-patterns.md
+**Purpose**: Production-ready code standards
+
+**Key Patterns**:
+```markdown
+# Error Handling
+- Try/catch for all external calls
+- Graceful degradation
+- User-friendly error messages
+
+# Logging
+- Structured logging
+- Appropriate log levels
+- No sensitive data in logs
+
+# Performance
+- Caching where appropriate
+- Database query optimization
+- Resource cleanup
+```
+
+**When to Use**:
+- Production code development
+- Code review for production readiness
+- Debugging production issues
+
+---
+
+## Integration with Role Cards
+
+Every role card should include this standard instruction cascade section:
+
+```markdown
+## Instruction Cascade (READ THESE FIRST)
+
+Before starting any work, read these instruction files in order:
+
+### Global Instructions (Required for ALL agents)
+1. `agents/instructions/global/identity-heartbeat.md`
+2. `agents/instructions/global/eight-phase-methodology.md`
+3. `agents/instructions/global/github-coordination.md`
+4. `agents/instructions/global/authority-matrix.md`
+5. `agents/instructions/global/communication.md`
+6. `agents/instructions/global/security-and-compliance.md`
+
+### Domain Instructions (Select relevant)
+- `agents/instructions/domain/web.md` (for web development)
+- `agents/instructions/domain/data.md` (for data processing)
+- `agents/instructions/domain/ops.md` (for operations)
+
+### Project Instructions (Required for ALL agents)
+1. `agents/instructions/project/repository-operations.md`
+2. `agents/instructions/project/multi-instance-coordination.md`
+3. `agents/instructions/project/production-patterns.md`
+
+### Role-Specific Instructions
+Continue reading this role card for role-specific guidance.
+```
+
+---
+
+## Best Practices
+
+### Reading Instructions
+- ✅ Read ALL global instructions at session start
+- ✅ Re-read after context compaction
+- ✅ Apply priority order for conflicts
+- ✅ Verify identity every 5 minutes
+- ❌ Don't skip global instructions for "simple" tasks
+- ❌ Don't assume instructions haven't changed
+
+### Conflict Resolution
+- ✅ Apply priority order (Project > Role > Domain > Global)
+- ✅ Document why higher-priority instruction was applied
+- ✅ Escalate if uncertain about conflict resolution
+- ✅ Never override GLOBAL POLICY items (security, governance)
+- ❌ Don't silently ignore conflicting instructions
+- ❌ Don't skip escalation when blocked
+
+### Maintaining Instructions
+- ✅ Update global instructions for universal changes
+- ✅ Update domain for technical pattern changes
+- ✅ Update project for environment-specific needs
+- ✅ Keep role cards for role-specific behavior
+- ❌ Don't duplicate content across levels
+- ❌ Don't create circular dependencies
+
+---
+
+## Related Skills
+
+- **wolf-roles**: Role-specific instruction integration
+- **wolf-governance**: Governance policies referenced in instructions
+- **wolf-principles**: Foundational principles underlying instructions
+- **wolf-scripts-agents**: Mailbox communication implementation
+
+---
+
+## Red Flags - STOP
+
+If you catch yourself thinking:
+
+- ❌ **"Global instructions override project instructions"** - BACKWARDS. Project instructions have HIGHEST priority. Project > Role > Domain > Global.
+- ❌ **"I can skip instruction loading to save time"** - FORBIDDEN. Instructions contain critical policies. Skipping them violates governance and security.
+- ❌ **"Instructions haven't changed since last session"** - Wrong assumption. Always re-read instructions at session start and after compaction.
+- ❌ **"Global policy can be overridden for convenience"** - NO. Security, governance, and identity verification are GLOBAL POLICY and cannot be overridden. Ever.
+- ❌ **"I'll just follow the instructions I remember"** - STOP. Memory is unreliable. Read current instruction files.
+
+**STOP. Load instructions in correct cascade order BEFORE proceeding.**
+
+## After Using This Skill
+
+**RECOMMENDED NEXT STEPS:**
+
+```
+Instructions provide context - used during workflow execution
+```
+
+1. **Integration with wolf-session-init**: Instructions are loaded as part of session initialization
+   - **When**: wolf-session-init Step 4 loads role-specific guidance, which includes instruction cascade
+   - **Why**: Ensures all agents have consistent context before starting work
+   - **This skill**: Provides detailed instruction hierarchy and conflict resolution rules
+
+2. **During Work**: Reference instructions for specific situations
+   - Identity verification: `identity-heartbeat.md` (every 5 minutes)
+   - Workflow transitions: `github-coordination.md`
+   - Security decisions: `security-and-compliance.md`
+   - Inter-agent communication: `communication.md`
+
+3. **No specific next skill**: Instructions are referenced throughout work, not a sequential step
+   - Use this skill to understand instruction hierarchy
+   - Use wolf-roles to see how instructions integrate with role cards
+   - Use wolf-governance for governance policies referenced in instructions
+
+### Cascade Resolution Checklist
+
+Before claiming instructions loaded correctly:
+
+- [ ] Read ALL 21 global instruction files (identity-heartbeat, github-coordination, authority-matrix, etc.)
+- [ ] Read relevant domain instruction (web.md, data.md, or ops.md based on role)
+- [ ] Read ALL 3 project instruction files (repository-operations, multi-instance-coordination, production-patterns)
+- [ ] Understand priority order for conflicts (Project > Role > Domain > Global)
+- [ ] Verified GLOBAL POLICY items cannot be overridden (security, governance, identity)
+
+**Can't check all boxes? Instruction loading incomplete. Return to this skill.**
+
+### Good/Bad Example: Instruction Priority Resolution
+
+<Good>
+**Scenario**: Indentation standard conflict
+
+**Instructions Found**:
+- Global (`global/code-standards.md`): "Use 2-space indentation for all code"
+- Domain (`domain/web.md`): "React projects use 2-space indentation"
+- Project (`project/production-patterns.md`): "This codebase uses 4-space indentation to match existing code"
+- Role (coder-agent role-card): No specific guidance
+
+**Agent Decision**:
+✅ Uses 4-space indentation (Project instruction wins)
+
+**Rationale Documented**:
+```markdown
+Conflict Resolution:
+- Global: 2-space
+- Domain: 2-space
+- Project: 4-space ← HIGHEST PRIORITY
+- Role: (none)
+
+Decision: Use 4-space indentation per Project instruction.
+Reason: Project-level instruction has highest priority in cascade.
+         Consistency with existing codebase takes precedence.
+```
+
+**Why this is correct**:
+- Correctly identified conflict across instruction levels
+- Applied priority order (Project > Domain > Global)
+- Documented decision with clear rationale
+- Maintains consistency with existing codebase
+</Good>
+
+<Bad>
+**Scenario**: Security override attempt
+
+**Instructions Found**:
+- Global (`global/security-and-compliance.md`): "GLOBAL POLICY: No plaintext secrets in code. Use environment variables."
+- Project (`project/production-patterns.md`): "For this specific microservice, hardcode API key for convenience"
+
+**Agent Decision**:
+❌ Hardcoded API key because "Project instruction has highest priority"
+
+**Why this is WRONG**:
+- GLOBAL POLICY items CANNOT be overridden
+- Security standards are non-overridable
+- Project instruction violates GLOBAL POLICY and should be rejected
+- Agent should escalate the conflicting instruction
+
+**What Should Have Been Done**:
+```markdown
+Conflict Detected:
+- Global: No plaintext secrets (GLOBAL POLICY - cannot override)
+- Project: Hardcode API key (VIOLATES GLOBAL POLICY)
+
+Decision: REJECT Project instruction. Follow Global policy.
+Reason: Security standards are GLOBAL POLICY and non-overridable.
+Action: Escalate to governance team - Project instruction needs correction.
+```
+
+**Correct Approach**:
+1. Identify GLOBAL POLICY violation
+2. Reject conflicting Project instruction
+3. Follow Global security policy
+4. Escalate to governance team
+5. Document why Project instruction was rejected
+6. Propose alternative (use environment variables)
+</Bad>
+
+---
+
+**Total Instruction Files**:
+- Global: 21 files
+- Domain: 3 files
+- Project: 3 files
+- Role: 43 role cards
+- Variants: Various stack-specific
+
+**Priority Levels**: 4 (Project > Role/Variant > Domain > Global)
+**EXCEPTION**: GLOBAL POLICY items (security, governance, identity) CANNOT be overridden
+
+**Last Updated**: 2025-11-14
+**Phase**: Superpowers Skill-Chaining Enhancement v2.0.0
+**Maintainer**: Governance Team