wogiflow 1.0.21 → 1.0.22

package/.claude/docs/knowledge-base/03-self-improvement/skill-matching.md

@@ -0,0 +1,304 @@
+# Skill Matching
+
+<!-- PINS: overview, matching-flow, trigger-types, scoring, configuration, auto-invoke, debugging -->
+
+How skills are automatically matched to task context based on keywords, file patterns, and task types.
+
+---
+
+## Overview
+<!-- PIN: overview -->
+
+Skill matching enables model-invoked skills - automatically loading relevant framework knowledge based on what you're working on. No manual activation required.
+
+---
+
+## How Matching Works
+<!-- PIN: matching-flow -->
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                      SKILL MATCHING FLOW                             │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│   Task Context                    Matching Engine                    │
+│   ────────────                    ───────────────                    │
+│                                                                      │
+│   Description:                                                       │
+│   "Create user service"  ──────▶  Keywords: service, user           │
+│                                         ↓                            │
+│   Files modified:                       ↓                            │
+│   users.service.ts      ──────▶  File patterns: *.service.ts        │
+│                                         ↓                            │
+│   Task type:                            ↓                            │
+│   feature               ──────▶  Task types: feature                │
+│                                         ↓                            │
+│                                   ┌─────────────┐                    │
+│                                   │  MATCHED:   │                    │
+│                                   │  nestjs ●●●●○                    │
+│                                   │  react  ●○○○○                    │
+│                                   └─────────────┘                    │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Trigger Types
+<!-- PIN: trigger-types -->
+
+### 1. Keywords
+
+Words in task description that trigger a skill:
+
+```json
+{
+  "nestjs": {
+    "keywords": ["nestjs", "module", "controller", "service", "entity", "dto"]
+  },
+  "react": {
+    "keywords": ["react", "component", "hook", "usestate", "jsx", "tsx"]
+  }
+}
+```
+
+### 2. File Patterns
+
+File extensions and naming patterns:
+
+```json
+{
+  "nestjs": {
+    "filePatterns": ["*.module.ts", "*.controller.ts", "*.service.ts"]
+  },
+  "react": {
+    "filePatterns": ["*.tsx", "*.jsx", "use*.ts"]
+  }
+}
+```
+
+### 3. Task Types
+
+The type of task being worked on:
+
+```json
+{
+  "nestjs": {
+    "taskTypes": ["feature", "bugfix", "refactor"]
+  }
+}
+```
+
+### 4. Categories
+
+Broader categorization:
+
+```json
+{
+  "nestjs": {
+    "categories": ["backend", "api", "database"]
+  }
+}
+```
+
+---
+
+## Scoring System
+<!-- PIN: scoring -->
+
+Each trigger type contributes to the match score:
+
+| Trigger Type | Weight | Example |
+|--------------|--------|---------|
+| Exact keyword | +3 | "nestjs" in description |
+| Partial keyword | +1 | "service" (common word) |
+| File pattern | +2 | Editing `*.controller.ts` |
+| Task type | +1 | feature task |
+| Category | +1 | backend category |
+
+Score display: `●●●●○` = 4/5 score
+
+---
+
+## Configuration
+<!-- PIN: configuration -->
+
+### Installed Skills
+
+```json
+{
+  "skills": {
+    "installed": ["nestjs", "react", "figma-analyzer", "python"],
+    "autoInvoke": true,           // Auto-load matched skills
+    "autoDiscoverNested": true,   // Auto-discover nested skills
+    "minScore": 2                 // Minimum score to invoke
+  }
+}
+```
+
+### Nested Skills (v1.0.3+)
+
+Skills can be organized in nested directories for better categorization:
+
+```
+.claude/skills/
+├── nestjs/                    # Flat skill (traditional)
+├── frontend/                  # Category directory
+│   ├── react/                # Nested skill: "frontend/react"
+│   └── vue/                  # Nested skill: "frontend/vue"
+└── backend/                   # Category directory
+    └── express/              # Nested skill: "backend/express"
+```
+
+**Nested skills are auto-discovered** when `autoDiscoverNested: true` (default).
+
+Create nested skills:
+```bash
+flow skill-create frontend/react
+flow skill-create backend/express
+```
+
+Reference in config:
+```json
+{
+  "skills": {
+    "installed": ["nestjs", "frontend/react", "backend/express"]
+  }
+}
+```
+
+**Max nesting depth**: 3 levels (e.g., `domain/category/framework`)
+
+### Custom Triggers
+
+Override default triggers in skill.md:
+
+```markdown
+---
+name: my-skill
+---
+
+## Triggers
+
+- keywords: ["custom", "keywords"]
+- filePatterns: ["*.custom.ts"]
+- taskTypes: ["feature"]
+- categories: ["backend"]
+```
+
+---
+
+## Skill Priority
+
+When multiple skills match:
+
+1. **Exclusive skills** (if marked) prevent others from loading
+2. **Higher score** wins for conflicting patterns
+3. **Explicit install** takes priority over auto-detected
+
+---
+
+## Auto-Invoke Behavior
+<!-- PIN: auto-invoke -->
+
+When `autoInvoke: true`:
+
+```
+/wogi-start wf-012
+         ↓
+Load task context
+         ↓
+Run skill matcher
+         ↓
+┌─────────────────────────────────────────┐
+│ 🔧 Matched Skills:                       │
+│    nestjs [●●●●○]                       │
+│    keyword: "service", file: *.service.ts│
+└─────────────────────────────────────────┘
+         ↓
+Load: .claude/skills/nestjs/knowledge/patterns.md
+Load: .claude/skills/nestjs/knowledge/anti-patterns.md
+```
+
+---
+
+## Default Triggers
+
+Built-in triggers for common frameworks:
+
+| Skill | Key Triggers |
+|-------|--------------|
+| `nestjs` | module, controller, service, entity, dto, *.module.ts |
+| `react` | component, hook, useState, *.tsx, *.jsx |
+| `python` | pip, django, flask, fastapi, *.py |
+| `figma-analyzer` | figma, design, design-system, tokens |
+
+> **Note**: Long input processing (transcripts, specs, requirements) is now handled automatically by the `long-input-gate` hook, not as a skill.
+
+---
+
+## Disabling Auto-Invoke
+
+Per-task:
+```bash
+/wogi-start wf-012 --no-skills
+```
+
+Globally:
+```json
+{
+  "skills": {
+    "autoInvoke": false
+  }
+}
+```
+
+---
+
+## Skill Loading Sequence
+
+1. **Match skills** against task context
+2. **Filter** by minimum score
+3. **Sort** by score (highest first)
+4. **Load** skill.md for each matched skill
+5. **Load** knowledge files (patterns.md, anti-patterns.md)
+6. **Apply** to current context
+
+---
+
+## Debugging Matches
+<!-- PIN: debugging -->
+
+Check why a skill was/wasn't matched:
+
+```bash
+# Show matching details
+node scripts/flow-skill-matcher.js debug "create user service"
+
+# Output:
+# Task: "create user service"
+#
+# nestjs: 4/5
+#   - keyword "service": +3
+#   - category "backend": +1
+#
+# react: 1/5
+#   - keyword "user": +1
+```
+
+---
+
+## Best Practices
+
+1. **Keep keywords specific** - "nestjs" over "backend"
+2. **Use file patterns** - More reliable than keywords
+3. **Set appropriate minScore** - Too low = noise, too high = misses
+4. **Review matches** - Check output on `/wogi-start`
+
+---
+
+## Related
+
+- [Skill Learning](./skill-learning.md) - How skills are created and updated
+- [Task Execution](../02-task-execution/) - Where skills are applied
+- [Configuration](../configuration/all-options.md) - Full skill settings

package/.claude/docs/knowledge-base/03-self-improvement/team-learning.md

@@ -0,0 +1,342 @@
+# Team-Level Learning
+
+Knowledge routing, pattern promotion, and shared learning across teams.
+
+---
+
+## Overview
+
+Team learning enables:
+- Sharing valuable patterns across projects
+- Promoting local learnings to team-wide standards
+- Routing new knowledge to appropriate scope
+- Maintaining consistent practices
+
+---
+
+## Knowledge Routing
+
+Decide where new learnings should go:
+
+```json
+{
+  "knowledgeRouting": {
+    "autoDetect": true,         // Analyze pattern scope
+    "confirmWithUser": true,    // Ask before routing
+    "defaultScope": "local",    // local | team | skill
+    "modelSpecificLearning": true
+  }
+}
+```
+
+### Routing Flow
+
+```
+New Pattern Learned
+         ↓
+┌─────────────────────────────────────────┐
+│ Analyze Pattern:                        │
+│ - Project-specific? → Local             │
+│ - Framework-related? → Skill            │
+│ - General best practice? → Team         │
+└─────────────────────────────────────────┘
+         ↓
+┌─────────────────────────────────────────┐
+│ Confirm with user (if enabled)          │
+│ "This pattern could benefit the team.   │
+│  Promote to team scope? [y/n]"          │
+└─────────────────────────────────────────┘
+         ↓
+Route to appropriate location
+```
+
+### Scope Determination
+
+| Pattern Type | Example | Scope |
+|--------------|---------|-------|
+| Project path | "Use /lib/api for calls" | Local |
+| Framework pattern | "NestJS services use DI" | Skill |
+| General practice | "Always handle errors" | Team |
+| Company standard | "Use our component lib" | Team |
+
+---
+
+## Automatic Promotion
+
+Valuable patterns can be auto-promoted:
+
+```json
+{
+  "automaticPromotion": {
+    "enabled": false,
+    "threshold": 3,              // Uses before promotion
+    "minRelevance": 0.8,         // Relevance score threshold
+    "destinations": ["decisions.md"],
+    "requireApproval": true,     // Require user approval
+    "autoApplyTeamApproved": true
+  }
+}
+```
+
+### Promotion Flow
+
+```
+Pattern used successfully 3+ times
+         ↓
+Relevance score > 0.8
+         ↓
+┌─────────────────────────────────────────┐
+│ Suggest promotion to team:              │
+│                                         │
+│ "Always use ErrorBoundary for pages"    │
+│ Used: 5 times, Success: 100%            │
+│                                         │
+│ Promote to team decisions? [y/n]        │
+└─────────────────────────────────────────┘
+         ↓
+(If approved)
+         ↓
+Sync to team backend or shared profile
+         ↓
+Available to all team members
+```
+
+---
+
+## Team Sync
+
+When team features are enabled:
+
+```json
+{
+  "team": {
+    "enabled": true,
+    "sync": {
+      "decisions": true,
+      "skills": true,
+      "memory": true
+    }
+  }
+}
+```
+
+### What Syncs
+
+| Item | Direction | Purpose |
+|------|-----------|---------|
+| decisions.md | Bidirectional | Team patterns |
+| Skills | Download | Framework knowledge |
+| Memory facts | Upload | Discovered patterns |
+
+### Sync Process
+
+```
+Local Change
+    ↓
+Check: Is this team-scoped?
+    ↓
+Yes → Queue for sync
+    ↓
+Sync interval (5 min) or manual trigger
+    ↓
+Push to team backend
+    ↓
+Other team members receive on next sync
+```
+
+---
+
+## Conflict Resolution
+
+When local and team patterns conflict:
+
+```json
+{
+  "team": {
+    "conflictResolution": "newest-wins"
+  }
+}
+```
+
+### Resolution Strategies
+
+| Strategy | Behavior |
+|----------|----------|
+| `newest-wins` | Latest timestamp wins |
+| `local-wins` | Prefer local changes |
+| `remote-wins` | Prefer team changes |
+| `ask` | Prompt for each conflict |
+
+### Conflict Example
+
+```
+Local: "Use axios for API calls"
+Team:  "Use fetch for API calls"
+
+With newest-wins:
+  - Check timestamps
+  - Apply newer pattern
+  - Log conflict for review
+
+With ask:
+  - Prompt user
+  - "Team uses fetch, you use axios. Keep which?"
+```
+
+---
+
+## Shared Skills
+
+Skills can be shared team-wide:
+
+```json
+{
+  "team": {
+    "sync": {
+      "skills": true
+    }
+  }
+}
+```
+
+### Skill Sharing Flow
+
+1. **Create Local**: Developer creates/updates skill
+2. **Mark for Sharing**: Promote skill to team
+3. **Review**: Team admin approves
+4. **Distribute**: Skill syncs to all members
+5. **Local Override**: Members can extend locally
+
+---
+
+## Team Memory
+
+Share discovered facts:
+
+```json
+{
+  "team": {
+    "sync": {
+      "memory": true
+    }
+  }
+}
+```
+
+### What's Shared
+
+- Architectural patterns
+- Common solutions
+- Performance findings
+- Security patterns
+
+### What's NOT Shared
+
+- Project-specific paths
+- Personal preferences
+- Temporary workarounds
+
+---
+
+## Manual Sharing
+
+Without team backend, use profile export:
+
+```bash
+# Export learnings
+/wogi-export
+
+# Share file with team
+# (via git, Slack, email, etc.)
+
+# Import on other machine
+/wogi-import
+```
+
+### Git-Based Sharing
+
+```bash
+# Include shared decisions in repo
+git add .workflow/state/decisions.md
+git commit -m "Update team patterns"
+git push
+
+# Team members pull changes
+git pull
+```
+
+---
+
+## Cross-Project Learning
+
+For teams with multiple projects:
+
+```json
+{
+  "team": {
+    "projectScope": false    // Share across projects
+  }
+}
+```
+
+### Cross-Project Flow
+
+```
+Project A learns pattern
+         ↓
+Pattern promoted to team
+         ↓
+Project B syncs
+         ↓
+Pattern available in Project B
+```
+
+### Scoped vs Global
+
+| Setting | Behavior |
+|---------|----------|
+| `projectScope: true` | Learnings stay in project |
+| `projectScope: false` | Learnings share across projects |
+
+---
+
+## Knowledge Hierarchy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    KNOWLEDGE FLOW                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   Local Discovery                                           │
+│        ↓                                                    │
+│   Project decisions.md                                      │
+│        ↓ (if valuable)                                      │
+│   Team decisions (promoted)                                 │
+│        ↓ (if framework-specific)                            │
+│   Shared skill patterns                                     │
+│                                                             │
+│   ────────────────────────────────────────                  │
+│                                                             │
+│   Team patterns flow DOWN to new projects                   │
+│   Local discoveries flow UP to team (with approval)         │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Best Practices
+
+1. **Start Local**: Don't over-share immediately
+2. **Validate First**: Pattern should work consistently
+3. **Get Consensus**: Team should agree before promotion
+4. **Document Why**: Include rationale with patterns
+5. **Review Periodically**: Remove outdated team patterns
+
+---
+
+## Related
+
+- [Project Learning](./project-learning.md) - Local patterns
+- [Skill Learning](./skill-learning.md) - Framework patterns
+- [Team Setup](../01-setup-onboarding/team-setup.md) - Team configuration