wogiflow 1.0.21 → 1.0.22

package/.claude/docs/knowledge-base/01-setup-onboarding/team-setup.md

@@ -0,0 +1,346 @@
+# Team Setup
+
+Configure team sync and shared knowledge.
+
+---
+
+## Purpose
+
+Team features enable:
+- **Shared Decisions**: Team-wide coding patterns
+- **Knowledge Transfer**: Share learnings across projects
+- **Consistent Configuration**: Import/export workflow profiles
+- **Audit Trails**: Track changes across team members
+
+---
+
+## Quick Start
+
+### Export Your Profile
+
+```bash
+/wogi-export
+```
+
+Creates a shareable profile with your configuration.
+
+### Import Team Profile
+
+```bash
+/wogi-import
+```
+
+Import a team's shared configuration.
+
+---
+
+## Configuration
+
+```json
+{
+  "team": {
+    "enabled": false,
+    "teamId": null,
+    "userId": null,
+    "projectId": null,
+    "apiKey": null,
+    "backendUrl": "https://api.wogi-flow.com",
+    "syncInterval": 300000,
+    "autoSync": true,
+    "sync": {
+      "decisions": true,
+      "appMap": true,
+      "componentIndex": true,
+      "skills": true,
+      "memory": true,
+      "requestLog": "recent",
+      "tasks": false
+    },
+    "conflictResolution": "newest-wins"
+  }
+}
+```
+
+---
+
+## What Gets Synced
+
+| Item | Default | Description |
+|------|---------|-------------|
+| `decisions` | `true` | Coding patterns and conventions |
+| `appMap` | `true` | Component registry |
+| `componentIndex` | `true` | Auto-scanned components |
+| `skills` | `true` | Installed skill packages |
+| `memory` | `true` | Learned facts and patterns |
+| `requestLog` | `"recent"` | Change history (recent only) |
+| `tasks` | `false` | Task queues |
+
+---
+
+## Profile Export
+
+```bash
+/wogi-export
+
+# Output:
+# 📤 Exporting workflow profile...
+#
+# Profile includes:
+#   - config.json settings
+#   - decisions.md patterns
+#   - app-map.md components
+#   - Installed skills
+#
+# Saved to: .workflow/exports/profile-2024-01-15.json
+```
+
+### Export File Structure
+
+```json
+{
+  "version": "2.0.0",
+  "exportedAt": "2024-01-15T10:30:00Z",
+  "exportedBy": "user-id",
+  "config": {...},
+  "state": {
+    "decisions": "...",
+    "appMap": "..."
+  },
+  "skills": ["react", "nestjs"]
+}
+```
+
+---
+
+## Profile Import
+
+```bash
+/wogi-import
+
+# Prompts for:
+# - Profile file path or URL
+# - What to import (all or select)
+# - Conflict resolution preference
+```
+
+### Import Options
+
+| Option | Description |
+|--------|-------------|
+| Import all | Full profile replacement |
+| Select items | Choose specific parts |
+| Merge | Combine with existing |
+| Replace | Overwrite existing |
+
+---
+
+## Team Sync (Future)
+
+When team backend is available:
+
+### Enable Team Mode
+
+```json
+{
+  "team": {
+    "enabled": true,
+    "teamId": "team-123",
+    "apiKey": "your-api-key"
+  }
+}
+```
+
+### Auto-Sync Behavior
+
+1. **On Session Start**: Pull latest team changes
+2. **On Session End**: Push local changes
+3. **Continuous**: Sync every 5 minutes (configurable)
+
+### Conflict Resolution
+
+```json
+{
+  "team": {
+    "conflictResolution": "newest-wins"
+  }
+}
+```
+
+Options:
+- `newest-wins` - Latest timestamp wins
+- `local-wins` - Prefer local changes
+- `remote-wins` - Prefer team changes
+- `ask` - Prompt for each conflict
+
+---
+
+## Knowledge Routing
+
+Control where learnings go:
+
+```json
+{
+  "knowledgeRouting": {
+    "autoDetect": true,
+    "confirmWithUser": true,
+    "defaultScope": "local"
+  }
+}
+```
+
+### Routing Logic
+
+```
+New Pattern Learned
+      ↓
+┌─────────────────────────────────────────┐
+│ Is this project-specific?               │
+├─────────────────────────────────────────┤
+│ YES → Save to local decisions.md        │
+│ NO  → Continue                          │
+└─────────────────────────────────────────┘
+      ↓
+┌─────────────────────────────────────────┐
+│ Is this team-applicable?                │
+├─────────────────────────────────────────┤
+│ YES → Promote to team (with approval)   │
+│ NO  → Keep local                        │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Automatic Promotion
+
+Share valuable patterns team-wide:
+
+```json
+{
+  "automaticPromotion": {
+    "enabled": false,
+    "threshold": 3,              // Uses before promoting
+    "minRelevance": 0.8,
+    "destinations": ["decisions.md"],
+    "requireApproval": true,
+    "autoApplyTeamApproved": true
+  }
+}
+```
+
+### Promotion Flow
+
+1. Pattern used successfully 3+ times
+2. Relevance score > 0.8
+3. Suggest promotion to team
+4. Team admin approves
+5. Pattern synced to all team members
+
+---
+
+## Manual Setup (No Backend)
+
+Without team backend, use file-based sharing:
+
+### Share Configuration
+
+```bash
+# Export
+/wogi-export
+# Share: .workflow/exports/profile-2024-01-15.json
+
+# Import on other machine
+/wogi-import
+# Select exported file
+```
+
+### Share via Git
+
+```bash
+# Include workflow in repo
+git add .workflow/
+git commit -m "Share workflow config"
+git push
+```
+
+Team members:
+```bash
+git pull
+# Workflow config now shared
+```
+
+---
+
+## Multi-Project Setup
+
+For multiple projects:
+
+### Shared Team Profile
+
+```json
+{
+  "team": {
+    "projectScope": true  // Scope to current project
+  }
+}
+```
+
+### Cross-Project Knowledge
+
+```json
+{
+  "team": {
+    "projectScope": false  // Share across all projects
+  }
+}
+```
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/wogi-import` | Import team profile |
+| `/wogi-export` | Export current profile |
+| `/wogi-health` | Check team sync status |
+
+---
+
+## Best Practices
+
+1. **Export Before Major Changes**: Create backup profile
+2. **Review Imported Config**: Check for conflicts
+3. **Use Project Scope**: Keep project-specific decisions local
+4. **Regular Sync**: Keep team knowledge up-to-date
+5. **Document Team Decisions**: Use decisions.md for patterns
+
+---
+
+## Troubleshooting
+
+### Import Fails
+
+```bash
+# Check file format
+node -e "JSON.parse(require('fs').readFileSync('profile.json'))"
+```
+
+### Sync Conflicts
+
+Check sync status:
+```bash
+/wogi-health
+# Shows sync status and conflicts
+```
+
+### Missing Team Features
+
+Team backend is optional. Most features work with file-based sharing.
+
+---
+
+## Related
+
+- [Configuration Reference](../configuration/all-options.md)
+- [Self-Improvement](../03-self-improvement/) - Knowledge learning
+- [Memory & Context](../04-memory-context/) - Memory systems

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

@@ -0,0 +1,259 @@
+# Task Planning
+
+Before implementation begins, WogiFlow ensures proper planning through task gating, size assessment, and story creation.
+
+---
+
+## Task Gating
+
+**The Problem**: AI tends to jump straight into coding without understanding scope, leading to incomplete or over-engineered solutions.
+
+**The Solution**: Task gating blocks implementation until a task exists with proper context.
+
+### How It Works
+
+1. User requests implementation
+2. System checks if task exists in `ready.json`
+3. If no task exists → blocks and asks for story/task creation
+4. If task exists → proceeds with context from acceptance criteria
+
+### Configuration
+
+```json
+{
+  "enforcement": {
+    "strictMode": true,                      // Master switch
+    "requireTaskForImplementation": true,    // Require task in ready.json
+    "requireStoryForMediumTasks": true,      // Medium+ need acceptance criteria
+    "requirePatternCitation": false          // Require citing decisions.md patterns
+  }
+}
+```
+
+### Strict Mode Flow
+
+```
+User: "Add a login button"
+          ↓
+┌─────────────────────────────────────────┐
+│ Is this an implementation request?      │
+├─────────────────────────────────────────┤
+│ YES → Check for existing task           │
+│ NO  → Handle normally (questions, etc.) │
+└─────────────────────────────────────────┘
+          ↓
+┌─────────────────────────────────────────┐
+│ Does task exist in ready.json?          │
+├─────────────────────────────────────────┤
+│ YES → /wogi-start TASK-XXX              │
+│ NO  → Assess size first                 │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Task Size Assessment
+
+Different task sizes require different levels of planning:
+
+| Size | Criteria | Planning Required |
+|------|----------|-------------------|
+| **Small** | < 3 files, < 1 hour, obvious scope | Minimal - create task inline |
+| **Medium** | 3-10 files, 1-4 hours, some complexity | Story with acceptance criteria |
+| **Large** | > 10 files, > 4 hours, new feature | Story + decomposition |
+
+### Configuration
+
+```json
+{
+  "enforcement": {
+    "taskSizeThresholds": {
+      "small": { "maxFiles": 3, "maxHours": 1 },
+      "medium": { "maxFiles": 10, "maxHours": 4 },
+      "large": { "minFiles": 10, "minHours": 4 }
+    }
+  }
+}
+```
+
+### Size Assessment Process
+
+When a task doesn't exist:
+
+1. **Analyze Request**: Extract scope indicators (files mentioned, feature complexity)
+2. **Classify Size**: Map to small/medium/large based on thresholds
+3. **Apply Rules**:
+   - Small → Create task inline, proceed
+   - Medium → Require story approval first
+   - Large → Require story + suggest decomposition
+
+---
+
+## Story Creation
+
+Stories define acceptance criteria that drive the execution loop.
+
+### Creating a Story
+
+```bash
+/wogi-story "Add user authentication"
+```
+
+This generates a structured story:
+
+```markdown
+# [TASK-015] Add user authentication
+
+## User Story
+**As a** user
+**I want** to log in with email and password
+**So that** I can access my personalized dashboard
+
+## Acceptance Criteria
+
+### Scenario 1: Successful login
+**Given** valid credentials
+**When** user submits login form
+**Then** user is redirected to dashboard
+
+### Scenario 2: Invalid credentials
+**Given** invalid email or password
+**When** user submits login form
+**Then** error message is displayed
+
+### Scenario 3: Form validation
+**Given** empty fields
+**When** user attempts to submit
+**Then** validation errors are shown
+
+## Technical Notes
+- Use existing AuthService from app-map
+- Follow project pattern for form handling (decisions.md)
+```
+
+### Story Workflow
+
+1. Story is created with proposed acceptance criteria
+2. User reviews and approves (or modifies)
+3. Task is added to `ready.json` with criteria attached
+4. `/wogi-start TASK-XXX` uses criteria to drive loop
+
+---
+
+## Story Decomposition
+
+For complex stories, automatic decomposition breaks them into manageable sub-tasks.
+
+### When Decomposition Happens
+
+```json
+{
+  "storyDecomposition": {
+    "autoDetect": true,              // Suggest when beneficial
+    "autoDecompose": false,          // Require approval (true = automatic)
+    "complexityThreshold": "medium", // Trigger on medium+ tasks
+    "minSubTasks": 5                 // Min subtasks to suggest decomposition
+  }
+}
+```
+
+### Decomposition Process
+
+1. **Complexity Analysis**: Assess story scope
+2. **Subtask Generation**: Break into granular tasks
+3. **Edge Case Expansion**: Add loading/error state tasks
+4. **Dependency Ordering**: Sequence tasks appropriately
+
+### Example Decomposition
+
+Original story: "Add user authentication"
+
+Decomposed tasks:
+```
+TASK-015-A: Create AuthService with login/logout methods
+TASK-015-B: Create LoginForm component
+TASK-015-C: Add form validation with error states
+TASK-015-D: Handle loading state during auth
+TASK-015-E: Add error handling for failed auth
+TASK-015-F: Integrate with existing routing
+TASK-015-G: Add session persistence
+```
+
+### Configuration Options
+
+```json
+{
+  "storyDecomposition": {
+    "autoDetect": true,           // Suggest decomposition for complex tasks
+    "autoDecompose": false,       // false = ask first, true = automatic
+    "complexityThreshold": "medium",
+    "minSubTasks": 5,
+    "edgeCases": true,            // Generate edge case tasks
+    "loadingStates": true,        // Generate loading state tasks
+    "errorStates": true           // Generate error handling tasks
+  }
+}
+```
+
+---
+
+## Multi-Approach Analysis
+
+For complex tasks, analyze multiple implementation approaches before committing.
+
+### When to Use
+
+- Task has high complexity assessment
+- Multiple valid implementation paths exist
+- Architecture decisions needed
+
+### Configuration
+
+```json
+{
+  "multiApproach": {
+    "enabled": true,
+    "mode": "suggest",              // "suggest" | "auto" | "off"
+    "triggerOn": ["large", "xl"],   // Complexity levels
+    "maxApproaches": 3,
+    "selectionStrategy": "first-passing"
+  }
+}
+```
+
+### How It Works
+
+1. Task is assessed for complexity
+2. If complex enough, multi-approach analysis is suggested
+3. Multiple implementation strategies are outlined with trade-offs
+4. User selects approach (or accepts recommendation)
+5. Execution proceeds with chosen approach
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/wogi-story "title"` | Create story with acceptance criteria |
+| `/wogi-story "title" --deep` | Create story with forced decomposition |
+| `/wogi-ready` | Show available tasks |
+| `/wogi-start TASK-XXX` | Start executing a task |
+| `/wogi-deps TASK-XXX` | Show task dependencies |
+
+---
+
+## Best Practices
+
+1. **Always create stories for non-trivial tasks** - The upfront planning saves time
+2. **Review acceptance criteria before starting** - Catch scope issues early
+3. **Use decomposition for features** - Smaller tasks = better results
+4. **Trust the size assessment** - It's tuned for AI task completion patterns
+
+---
+
+## Related
+
+- [Execution Loop](./02-execution-loop.md) - How tasks are executed
+- [Story Writer Agent](../../../agents/story-writer.md) - Story creation guidelines
+- [Configuration Reference](../configuration/all-options.md) - All config options