pmp-gywd 3.3.0

package/get-your-work-done/core/agent-patterns.md

@@ -0,0 +1,331 @@
+# GYWD v2.0 Agent Orchestration Patterns
+
+## Overview
+
+The Agent Orchestrator manages multiple AI agents working together, including
+adversarial agents that challenge assumptions and find flaws.
+
+## Agent Types
+
+### Planning Agents
+
+```yaml
+Architect:
+  purpose: High-level system design
+  inputs:
+    - Requirements
+    - Constraints
+    - Existing architecture (if brownfield)
+  outputs:
+    - Component diagram
+    - Interface definitions
+    - Decision recommendations
+  style: Conservative, considers long-term implications
+
+Implementer:
+  purpose: Detailed task breakdown
+  inputs:
+    - Architect's design
+    - Codebase context
+    - Developer profile
+  outputs:
+    - Task list with dependencies
+    - File change predictions
+    - Risk assessment per task
+  style: Practical, focused on executability
+
+Estimator:
+  purpose: Complexity and risk assessment
+  inputs:
+    - Task list
+    - Historical data
+    - Codebase metrics
+  outputs:
+    - Complexity scores
+    - Risk factors
+    - Potential blockers
+  style: Data-driven, cautious
+```
+
+### Execution Agents
+
+```yaml
+Coder:
+  purpose: Write implementation code
+  inputs:
+    - Task specification
+    - Relevant decisions
+    - Code context
+    - Developer profile (for style matching)
+  outputs:
+    - Code changes
+    - Inline documentation
+    - Test stubs
+  style: Matches developer preferences
+
+Tester:
+  purpose: Generate and run tests
+  inputs:
+    - Code changes
+    - Test patterns from codebase
+    - Coverage requirements
+  outputs:
+    - Test files
+    - Coverage report
+    - Edge cases identified
+  style: Thorough, adversarial to code
+
+Documenter:
+  purpose: Generate documentation
+  inputs:
+    - Code changes
+    - Decisions involved
+    - Existing doc style
+  outputs:
+    - API documentation
+    - Decision records
+    - README updates
+  style: Clear, matches existing conventions
+```
+
+### Review Agents (Adversarial)
+
+```yaml
+Critic:
+  purpose: Find logical and design flaws
+  personality: Skeptical, detail-oriented
+  questions_asked:
+    - "What happens if this fails?"
+    - "Is this the simplest solution?"
+    - "Does this violate any existing decisions?"
+  output_style: Specific, actionable critiques
+
+Devil's Advocate:
+  purpose: Argue for alternative approaches
+  personality: Contrarian, creative
+  questions_asked:
+    - "Why not do it this other way?"
+    - "What would [framework X] users do?"
+    - "Is there a third option we haven't considered?"
+  output_style: Alternative proposals with trade-offs
+
+Red Team:
+  purpose: Security attack simulation
+  personality: Adversarial, security-focused
+  attack_vectors:
+    - Input validation bypass
+    - Authentication weaknesses
+    - Data exposure risks
+    - Injection vulnerabilities
+  output_style: Vulnerability reports with severity
+
+Chaos:
+  purpose: Edge case and failure mode discovery
+  personality: Chaotic, thorough
+  scenarios_generated:
+    - Null/empty inputs
+    - Concurrent access
+    - Resource exhaustion
+    - Network failures
+    - Malformed data
+  output_style: Test scenarios with expected behavior
+
+Skeptic:
+  purpose: Question assumptions and requirements
+  personality: Philosophical, questioning
+  questions_asked:
+    - "Do we actually need this?"
+    - "Is the requirement correct?"
+    - "What assumptions are we making?"
+  output_style: Assumption list with validation suggestions
+```
+
+## Orchestration Patterns
+
+### Sequential Pattern
+```
+Use when: Tasks have clear dependencies
+Flow: A → B → C
+Example: Design → Implement → Test
+
+┌─────────┐     ┌─────────┐     ┌─────────┐
+│Architect│ ──► │Implement│ ──► │ Tester  │
+└─────────┘     └─────────┘     └─────────┘
+```
+
+### Parallel Pattern
+```
+Use when: Tasks are independent
+Flow: A | B | C (concurrent)
+Example: Multiple file changes in different modules
+
+┌─────────┐
+│ Coder A │ ─┐
+└─────────┘  │
+             │  ┌──────────┐
+┌─────────┐  ├─►│Synthesize│
+│ Coder B │ ─┤  └──────────┘
+└─────────┘  │
+             │
+┌─────────┐  │
+│ Coder C │ ─┘
+└─────────┘
+```
+
+### Adversarial Pattern
+```
+Use when: Need to validate decisions/code quality
+Flow: A vs B (competing proposals)
+Example: Two approaches to the same problem
+
+┌─────────────┐        ┌─────────────┐
+│ Approach A  │   vs   │ Approach B  │
+└──────┬──────┘        └──────┬──────┘
+       │                      │
+       └──────────┬───────────┘
+                  ▼
+          ┌─────────────┐
+          │   Compare   │
+          │  & Select   │
+          └─────────────┘
+```
+
+### Consensus Pattern
+```
+Use when: Critical decisions need multiple perspectives
+Flow: A + B + C → agreement
+Example: Architecture decisions
+
+┌──────────┐  ┌──────────┐  ┌──────────┐
+│ Security │  │  Perf    │  │  UX      │
+│ Expert   │  │  Expert  │  │  Expert  │
+└────┬─────┘  └────┬─────┘  └────┬─────┘
+     │             │             │
+     └─────────────┼─────────────┘
+                   ▼
+           ┌─────────────┐
+           │  Consensus  │
+           │   Builder   │
+           └─────────────┘
+```
+
+### Challenge Pattern
+```
+Use when: Running /gywd:challenge
+Flow: Proposal → Multiple adversarial attacks → Synthesis
+
+                    ┌─────────┐
+             ┌─────►│ Critic  │─────┐
+             │      └─────────┘     │
+             │                      │
+┌──────────┐ │      ┌─────────┐     │  ┌──────────┐
+│ Proposal │─┼─────►│ Devil's │─────┼─►│ Synthesis│
+└──────────┘ │      │Advocate │     │  └──────────┘
+             │      └─────────┘     │
+             │                      │
+             │      ┌─────────┐     │
+             ├─────►│Red Team │─────┤
+             │      └─────────┘     │
+             │                      │
+             │      ┌─────────┐     │
+             └─────►│  Chaos  │─────┘
+                    └─────────┘
+```
+
+## Agent Communication Protocol
+
+### Message Format
+```json
+{
+  "from": "agent_id",
+  "to": "agent_id | broadcast",
+  "type": "request | response | critique | proposal",
+  "priority": "low | medium | high | critical",
+  "payload": {
+    "content": "...",
+    "context_needed": ["file1", "decision2"],
+    "confidence": 0.85
+  },
+  "metadata": {
+    "timestamp": "...",
+    "in_response_to": "message_id",
+    "thread_id": "..."
+  }
+}
+```
+
+### Conflict Resolution
+
+When agents disagree:
+
+1. **Severity Assessment**: How critical is the disagreement?
+2. **Evidence Gathering**: What data supports each position?
+3. **Developer Profile Check**: What would the developer prefer?
+4. **Escalation**: If unresolved, present options to user
+
+```yaml
+resolution_strategies:
+  low_severity:
+    - Use developer profile preference
+    - Default to simpler option
+
+  medium_severity:
+    - Present both options with trade-offs
+    - Recommend based on project decisions
+
+  high_severity:
+    - Require explicit user decision
+    - Document for future reference
+```
+
+## Integration with Core Systems
+
+### Decision Graph Integration
+```
+- Agents query relevant decisions before work
+- Agents propose new decisions from their work
+- Decision conflicts trigger adversarial review
+```
+
+### Context Intelligence Integration
+```
+- Orchestrator requests optimal context for each agent
+- Agents report what context was useful
+- Context predictions refined based on agent outcomes
+```
+
+### Learning System Integration
+```
+- Agent outcomes recorded for learning
+- Agent selections refined over time
+- Agent personalities adapted to developer
+```
+
+## Performance Considerations
+
+### Token Budget Management
+```yaml
+budget_allocation:
+  planning_agents: 20%
+  execution_agents: 50%
+  review_agents: 25%
+  synthesis: 5%
+
+compression_triggers:
+  - Total exceeds 80% budget
+  - Individual agent exceeds allocation
+  - Redundant information detected
+```
+
+### Parallelization Strategy
+```yaml
+parallel_when:
+  - Independent file changes
+  - Multiple review perspectives needed
+  - Exploration of alternatives
+
+sequential_when:
+  - Output of one needed by another
+  - Consensus building required
+  - Critical path execution
+```

package/get-your-work-done/core/architecture.md

@@ -0,0 +1,334 @@
+# GYWD v2.0 Core Architecture
+
+## The Unified System
+
+v1.x was commands. v2.0 is intelligence.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        GYWD v2.0 Core                           │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
+│  │  Decision   │  │   Context   │  │   Agent     │             │
+│  │   Graph     │◄─┤ Intelligence│◄─┤Orchestrator │             │
+│  │   Engine    │  │   Engine    │  │             │             │
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘             │
+│         │                │                │                     │
+│         └────────┬───────┴────────┬───────┘                     │
+│                  │                │                             │
+│         ┌────────▼────────────────▼────────┐                   │
+│         │     Continuous Learning System    │                   │
+│         └───────────────────────────────────┘                   │
+│                          │                                      │
+├──────────────────────────┼──────────────────────────────────────┤
+│                          ▼                                      │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                    Command Layer                          │  │
+│  │  (extract-decisions, why, challenge, anticipate, etc.)   │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. Decision Graph Engine
+
+The central nervous system. Everything is a decision or derives from one.
+
+```yaml
+responsibilities:
+  - Store all extracted decisions
+  - Maintain causal links between decisions
+  - Answer "why" queries in O(1)
+  - Detect decision conflicts
+  - Track decision confidence over time
+
+data_structure:
+  nodes: Decision records
+  edges: Causal relationships (A led to B)
+  indexes:
+    - by_file: Decision[] per file path
+    - by_author: Decision[] per contributor
+    - by_time: Decision[] chronologically
+    - by_tag: Decision[] by category
+
+operations:
+  - addDecision(decision) → id
+  - linkDecisions(parent, child, relationship)
+  - queryByFile(path) → Decision[]
+  - queryByTimeRange(start, end) → Decision[]
+  - findConflicts() → Conflict[]
+  - traceDecision(id) → DecisionChain
+```
+
+### 2. Context Intelligence Engine
+
+Manages what the AI knows and why.
+
+```yaml
+responsibilities:
+  - Determine optimal context for any task
+  - Predict needed context before it's requested
+  - Manage context budget (prevent overflow)
+  - Learn which context was useful vs. noise
+
+subsystems:
+  context_selector:
+    - Analyzes current task
+    - Queries decision graph for relevant decisions
+    - Fetches related code patterns
+    - Assembles optimal context window
+
+  context_predictor:
+    - Monitors developer activity
+    - Predicts next likely needs
+    - Pre-fetches context in background
+    - Caches frequently-used patterns
+
+  context_optimizer:
+    - Tracks context usage effectiveness
+    - Compresses low-value context
+    - Expands high-value context
+    - Adapts to developer patterns
+```
+
+### 3. Agent Orchestrator
+
+Coordinates multiple AI agents, including adversarial ones.
+
+```yaml
+responsibilities:
+  - Spawn specialized agents for tasks
+  - Manage agent communication
+  - Synthesize multi-agent output
+  - Resolve agent conflicts
+  - Balance cooperation vs. adversarial review
+
+agent_types:
+  planning_agents:
+    - Architect: High-level design
+    - Implementer: Detailed task breakdown
+    - Estimator: Complexity and risk assessment
+
+  execution_agents:
+    - Coder: Implementation
+    - Tester: Test generation
+    - Documenter: Documentation
+
+  review_agents:
+    - Critic: Find flaws
+    - Devil's Advocate: Argue alternatives
+    - Red Team: Security attacks
+    - Chaos: Edge cases
+
+orchestration_patterns:
+  sequential: A → B → C (dependent tasks)
+  parallel: A | B | C (independent tasks)
+  adversarial: A vs B (competing proposals)
+  consensus: A + B + C → agreement
+```
+
+### 4. Continuous Learning System
+
+Gets smarter with every interaction.
+
+```yaml
+responsibilities:
+  - Learn from accepted/rejected suggestions
+  - Update developer profile
+  - Refine decision confidence scores
+  - Improve context predictions
+  - Adapt to project patterns
+
+learning_signals:
+  explicit:
+    - User feedback ("this was helpful/not helpful")
+    - Accepted vs rejected suggestions
+    - Edited vs used-as-is output
+
+  implicit:
+    - Time spent on suggestions
+    - Follow-up actions after suggestion
+    - Patterns in what user searches for
+    - Code changes after AI interaction
+
+feedback_loops:
+  - Decision extraction → user correction → improved extraction
+  - Context prediction → actual need → refined prediction
+  - Agent suggestion → user edit → better suggestions
+  - Profile inference → behavior observation → profile update
+```
+
+## Data Flow
+
+### On Project Start
+
+```
+1. User: /gywd:init or /gywd:new-project
+   │
+2. Decision Graph Engine: Extract decisions from history
+   │
+3. Context Intelligence: Build initial context model
+   │
+4. Learning System: Load/create developer profile
+   │
+5. Ready: Full project understanding loaded
+```
+
+### On Any Command
+
+```
+1. Command received
+   │
+2. Context Intelligence: Determine optimal context
+   │
+3. Decision Graph: Load relevant decisions
+   │
+4. Agent Orchestrator: Spawn appropriate agents
+   │
+5. Execute with full context awareness
+   │
+6. Learning System: Record outcomes
+```
+
+### On Code Change
+
+```
+1. File change detected
+   │
+2. Decision Graph: Update affected decisions
+   │
+3. Context Intelligence: Refresh predictions
+   │
+4. Learning System: Note patterns
+```
+
+## Integration Points
+
+### With Git
+
+```yaml
+triggers:
+  - pre-commit: Validate against decisions
+  - post-commit: Extract new decisions
+  - post-merge: Reconcile decision conflicts
+
+data_extraction:
+  - Commit messages → decisions
+  - PR descriptions → decisions
+  - Branch patterns → workflow learning
+```
+
+### With IDE/Editor
+
+```yaml
+events:
+  - file_open: Pre-load relevant context
+  - cursor_move: Update active context
+  - save: Trigger decision extraction
+  - error: Load similar past errors
+
+context_provision:
+  - Relevant decisions for current file
+  - Recent changes to related files
+  - Known issues in this area
+```
+
+### With Production
+
+```yaml
+data_import:
+  - Error rates per file/function
+  - Performance metrics per endpoint
+  - Cost attribution per service
+  - Incident history per code area
+
+context_enhancement:
+  - "This code handles 50K requests/day"
+  - "Last change here caused P1 incident"
+  - "This area costs $400/month in compute"
+```
+
+## File Structure
+
+```
+.planning/
+├── core/                    # v2.0 core data
+│   ├── decisions.json       # Decision graph
+│   ├── context-model.json   # Context intelligence state
+│   ├── learning-state.json  # Learning system state
+│   └── agent-history.json   # Agent interaction history
+│
+├── profile/                 # Developer digital twin
+│   ├── cognitive.yaml       # Thinking patterns
+│   ├── expertise.yaml       # Knowledge topology
+│   ├── preferences.yaml     # Style preferences
+│   └── history.yaml         # Interaction history
+│
+├── codebase/               # Codebase understanding
+│   ├── DECISIONS.md        # Human-readable decisions
+│   ├── decision-graph.json # Machine-readable graph
+│   └── [existing maps]     # Stack, architecture, etc.
+│
+└── [existing structure]    # PROJECT.md, ROADMAP.md, etc.
+```
+
+## Initialization Sequence
+
+```python
+def initialize_gywd_v2():
+    # 1. Load or create core data structures
+    decision_graph = DecisionGraph.load_or_create()
+    context_engine = ContextIntelligence.load_or_create()
+    learning_system = LearningSystem.load_or_create()
+    agent_orchestrator = AgentOrchestrator()
+
+    # 2. If new project, run initial extraction
+    if decision_graph.is_empty():
+        decisions = extract_decisions_from_history()
+        decision_graph.bulk_load(decisions)
+
+    # 3. Build initial context model
+    context_engine.initialize_from_decisions(decision_graph)
+
+    # 4. Load developer profile
+    profile = learning_system.load_profile()
+
+    # 5. Connect all systems
+    core = GYWDCore(
+        decisions=decision_graph,
+        context=context_engine,
+        learning=learning_system,
+        agents=agent_orchestrator
+    )
+
+    return core
+```
+
+## Command Integration
+
+Every v1.x command now goes through the core:
+
+```python
+# Before (v1.x): Direct execution
+def execute_command(cmd, args):
+    return cmd.run(args)
+
+# After (v2.0): Core-mediated execution
+def execute_command(cmd, args):
+    # Get optimal context
+    context = core.context.get_context_for(cmd, args)
+
+    # Load relevant decisions
+    decisions = core.decisions.get_relevant(cmd, args)
+
+    # Execute with full awareness
+    result = cmd.run(args, context=context, decisions=decisions)
+
+    # Learn from execution
+    core.learning.record(cmd, args, result)
+
+    return result
+```