wogiflow 1.0.21 → 1.0.22

package/.claude/docs/knowledge-base/02-task-execution/README.md

@@ -0,0 +1,173 @@
+# Task Execution Flow
+
+The `/wogi-start` command initiates a structured execution pipeline that ensures thorough, high-quality task completion. This is the heart of WogiFlow.
+
+---
+
+## The Execution Pipeline
+
+```
+1. Task Selection    →  2. Planning     →  3. Execution Loop  →  4. Verification  →  5. Completion
+   ─────────────────    ─────────────     ──────────────────     ──────────────      ────────────
+   • Task gating        • Story creation   • Self-completing    • Auto-inference    • Logging
+   • Size assessment    • Acceptance       • Durable sessions   • Quality gates     • Commits
+   • Dependency check     criteria         • Suspend/resume     • Browser tests     • Archival
+                        • Decomposition    • Hybrid mode                            • Cleanup
+```
+
+---
+
+## Why This Matters
+
+**The Problem**: Without structure, AI tends to:
+- Start coding without understanding the full scope
+- Miss edge cases and error handling
+- Leave tasks incomplete when "good enough"
+- Skip verification and break other features
+
+**The Solution**: WogiFlow enforces a pipeline that:
+- Gates implementation behind proper planning
+- Loops until ALL acceptance criteria pass
+- Verifies changes don't break existing functionality
+- Documents everything for future context
+
+---
+
+## Quick Start
+
+```bash
+# See available tasks
+/wogi-ready
+
+# Start a task (enters execution pipeline)
+/wogi-start TASK-012
+
+# Create a story with acceptance criteria first
+/wogi-story "Add user authentication"
+
+# Complete the task (runs quality gates)
+/wogi-done TASK-012
+```
+
+---
+
+## Pipeline Steps
+
+### Step 1: Task Selection & Planning
+Before any code is written, ensure the task is properly scoped.
+
+**Key Features:**
+- **Task Gating**: Implementation requires an existing task (no ad-hoc coding)
+- **Size Assessment**: Small/Medium/Large determines planning depth
+- **Story Creation**: Detailed acceptance criteria for non-trivial tasks
+
+[Read more: Task Planning](./01-task-planning.md)
+
+### Step 2: Execution Loop
+The core loop that ensures thorough completion.
+
+**Key Features:**
+- **Self-Completing Loops**: Cannot exit until all criteria pass
+- **Durable Sessions**: Crash recovery and progress tracking
+- **Suspend/Resume**: Handle long-running or blocked tasks
+- **Hybrid Mode**: Use local LLM for execution (85-95% token savings)
+
+[Read more: Execution Loop](./02-execution-loop.md)
+
+### Step 3: Verification
+Automated checks that validate the implementation.
+
+**Key Features:**
+- **Auto-Inference**: Automatic verification of file existence, function exports, etc.
+- **Quality Gates**: Lint, typecheck, test requirements per task type
+- **Browser Testing**: Visual verification for UI changes
+- **Pattern Enforcement**: Ensure code follows project decisions
+
+[Read more: Verification](./03-verification.md)
+
+### Step 4: Completion
+Proper wrap-up and documentation.
+
+**Key Features:**
+- **Request Logging**: Every change documented with tags
+- **App-Map Updates**: New components registered
+- **Commit Handling**: Approval workflow based on task type
+- **Session Archival**: Preserve context for learning
+
+[Read more: Completion](./04-completion.md)
+
+### Step 5: Session Review (Optional)
+Comprehensive code review before finalizing changes.
+
+**Key Features:**
+- **3 Parallel Agents**: Code/Logic, Security, Architecture
+- **Natural Triggers**: Say "please review" to run
+- **Consolidated Report**: Issues ranked by severity
+
+[Read more: Session Review](./05-session-review.md)
+
+---
+
+## Essential Configuration
+
+```json
+{
+  "enforcement": {
+    "strictMode": true,                    // Require tasks for implementation
+    "requireTaskForImplementation": true,   // Block ad-hoc coding
+    "requireStoryForMediumTasks": true      // Medium+ tasks need stories
+  },
+  "loops": {
+    "enforced": true,                      // Cannot exit until complete
+    "maxRetries": 5,                       // Failed verification retries
+    "maxIterations": 20                    // Total loop cycles
+  },
+  "qualityGates": {
+    "feature": {
+      "require": ["tests", "appMapUpdate", "requestLogEntry"]
+    }
+  }
+}
+```
+
+---
+
+## Trade-offs
+
+Understanding the trade-offs helps you configure WogiFlow for your needs:
+
+| Setting | Higher Value | Lower Value |
+|---------|-------------|-------------|
+| `loops.maxRetries` | More thorough, more tokens | Faster, might miss issues |
+| `loops.enforced` | Guaranteed completion | Manual control |
+| `qualityGates` | Fewer bugs in production | Faster development |
+| `hybrid.enabled` | 85-95% token savings | Full Claude quality |
+
+[Read more: Trade-offs](./trade-offs.md)
+
+---
+
+## Additional Features
+
+### External Integrations
+Import tasks from Jira and Linear for seamless project management integration.
+
+[Read more: External Integrations](./external-integrations.md)
+
+### Background Sync
+Keep workflow state synchronized across multiple sessions.
+
+[Read more: Sync Daemon](./sync-daemon.md)
+
+### Model Management
+Registry, routing, and statistics for multiple LLM providers.
+
+[Read more: Model Management](./model-management.md)
+
+---
+
+## Related
+
+- [Commands Reference](../../commands.md) - All slash commands
+- [Configuration Reference](../configuration/all-options.md) - All config options
+- [Safety & Guardrails](../06-safety-guardrails/) - Damage control, checkpoints

package/.claude/docs/knowledge-base/02-task-execution/external-integrations.md

@@ -0,0 +1,133 @@
+# External Integrations
+
+Import and sync tasks from external project management tools.
+
+---
+
+## Supported Integrations
+
+| Platform | Script | Commands |
+|----------|--------|----------|
+| Jira | `flow-jira-integration.js` | `flow jira list/sync/push/config` |
+| Linear | `flow-linear-integration.js` | `flow linear list/sync/push/config` |
+
+---
+
+## Jira Integration
+
+### Configuration
+
+Add to `.workflow/config.json`:
+
+```json
+{
+  "integrations": {
+    "jira": {
+      "enabled": true,
+      "baseUrl": "https://yourcompany.atlassian.net",
+      "projectKey": "PROJ",
+      "apiToken": "$JIRA_API_TOKEN",
+      "email": "your@email.com"
+    }
+  }
+}
+```
+
+### Commands
+
+```bash
+# List assigned issues
+flow jira list
+
+# Import issues to ready.json
+flow jira sync
+
+# Push completed tasks back to Jira
+flow jira push
+
+# Show configuration
+flow jira config
+```
+
+### Environment Variables
+
+- `JIRA_API_TOKEN` - Your Jira API token
+- `JIRA_EMAIL` - Your Jira email (optional, can be in config)
+
+---
+
+## Linear Integration
+
+### Configuration
+
+Add to `.workflow/config.json`:
+
+```json
+{
+  "integrations": {
+    "linear": {
+      "enabled": true,
+      "apiKey": "$LINEAR_API_KEY",
+      "teamId": "TEAM-123"
+    }
+  }
+}
+```
+
+### Commands
+
+```bash
+# List assigned issues
+flow linear list
+
+# Import issues to ready.json
+flow linear sync
+
+# Push completed tasks back to Linear
+flow linear push
+
+# Show configuration
+flow linear config
+```
+
+### Environment Variables
+
+- `LINEAR_API_KEY` - Your Linear API key
+
+---
+
+## Combined View
+
+```bash
+# List tasks from all integrations
+flow external-tasks
+```
+
+---
+
+## Task Mapping
+
+When importing, external tasks are mapped to WogiFlow tasks:
+
+| External Field | WogiFlow Field |
+|----------------|----------------|
+| Title/Summary | `title` |
+| Description | `description` |
+| Priority | `priority` |
+| Labels/Tags | `tags` |
+| Issue Key | `externalId` |
+
+---
+
+## Sync Behavior
+
+- **Import**: Creates new tasks in `ready.json` with `source: "jira"` or `source: "linear"`
+- **Push**: Updates external issue status when task is completed via `/wogi-done`
+- **Duplicates**: Checks `externalId` to avoid re-importing same issue
+
+---
+
+## Related
+
+- [Task Planning](./01-task-planning.md) - How tasks are structured
+- [Background Sync](./sync-daemon.md) - Automated sync

package/.claude/docs/knowledge-base/02-task-execution/model-management.md

@@ -0,0 +1,202 @@
+# Model Management
+
+Registry, routing, and statistics for LLM models.
+
+---
+
+## Overview
+
+WogiFlow supports multiple LLM providers and tracks performance to optimize model selection.
+
+---
+
+## Model Registry
+
+**Script**: `flow-models.js`
+
+```bash
+# List all registered models
+flow models list
+
+# Show detailed model info
+flow models info <model>
+
+# Get routing recommendation for task type
+flow models route <task-type>
+
+# Show performance statistics
+flow models stats
+
+# Show cost analysis
+flow models cost
+```
+
+### Model List Output
+
+```
+Registered Models
+════════════════════════════════════════
+  claude-sonnet-4      Anthropic    200K context   $$
+  claude-opus-4        Anthropic    200K context   $$$
+  gpt-4o              OpenAI        128K context   $$
+  gemini-2.0-flash    Google        1M context     $
+  ollama-qwen         Local         32K context    Free
+```
+
+---
+
+## Intelligent Routing
+
+**Script**: `flow-model-router.js`
+
+```bash
+# Get routing recommendation
+flow route "<task description>"
+
+# Use specific strategy
+flow route --strategy quality-first "<task>"
+flow route --strategy cost-optimized "<task>"
+flow route --strategy learned "<task>"
+```
+
+### Routing Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `quality-first` | Prefer most capable model |
+| `cost-optimized` | Minimize cost while meeting requirements |
+| `learned` | Use historical success rates |
+
+### Routing Factors
+
+- Task complexity (estimated tokens)
+- Required capabilities (code, reasoning, context)
+- Historical success rate per model
+- Cost constraints
+
+---
+
+## Cascade Fallback
+
+**Script**: `flow-cascade.js`
+
+Automatically try alternate models on repeated failures.
+
+```bash
+# Show cascade state
+flow cascade status
+
+# Reset failure tracking
+flow cascade reset
+
+# Show configuration
+flow cascade config
+```
+
+### Configuration
+
+```json
+{
+  "cascade": {
+    "enabled": true,
+    "fallbackModel": "claude-sonnet-4",
+    "maxFailuresBeforeEscalate": 3,
+    "escalateOnCategories": ["capability_mismatch", "context_overflow"]
+  }
+}
+```
+
+### How Cascade Works
+
+1. Primary model fails 3x on same error category
+2. System escalates to fallback model
+3. Success rate tracked for future routing
+4. Failure count resets after successful completion
+
+---
+
+## Model Adapter
+
+**Script**: `flow-model-adapter.js`
+
+Per-model prompt adaptations and learned corrections.
+
+```bash
+# Show current adapter info
+flow model-adapter
+
+# Show per-model statistics
+flow model-adapter --stats
+```
+
+### Adapter Files
+
+Located in `.workflow/model-adapters/`:
+
+```
+├── claude-default.md      # Claude family defaults
+├── claude-sonnet-4.md     # Sonnet-specific
+├── ollama-qwen.md         # Local model adapter
+└── _template.md           # New adapter template
+```
+
+### Adapter Contents
+
+- Prompt style preferences
+- Known limitations
+- Learned corrections
+- Success patterns
+
+---
+
+## Performance Stats
+
+```bash
+flow models stats
+```
+
+### Output Example
+
+```
+Model Performance Statistics
+════════════════════════════════════════
+Model               Success   Avg Time   Tasks
+────────────────────────────────────────
+claude-sonnet-4     94%       12.3s      234
+claude-opus-4       98%       45.2s      45
+ollama-qwen         78%       8.5s       156
+gpt-4o              91%       15.1s      89
+```
+
+---
+
+## Tiered Learning
+
+**Script**: `flow-tiered-learning.js`
+
+```bash
+# Show patterns by confidence tier
+flow learning tiers
+
+# Show learning statistics
+flow learning stats
+
+# Manually apply a pattern
+flow learning apply <pattern-id>
+```
+
+### Learning Tiers
+
+| Tier | Confidence | Behavior |
+|------|------------|----------|
+| Auto-Apply | 90%+ | Applied without prompt |
+| Apply with Log | 70-90% | Applied, logged for review |
+| Queue for Review | <70% | Held for manual approval |
+
+---
+
+## Related
+
+- [Execution Loop](./02-execution-loop.md) - How models are invoked
+- [Hybrid Mode](./02-execution-loop.md#hybrid-mode) - Multi-model orchestration
+- [Memory Commands](../04-memory-context/memory-commands.md) - Learning storage