wogiflow 1.0.21 → 1.0.22

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

@@ -0,0 +1,301 @@
+# Project-Level Learning
+
+How WogiFlow learns project-specific patterns and conventions.
+
+---
+
+## Overview
+
+Project-level learning captures:
+- Coding patterns unique to your project
+- Architectural decisions
+- Team conventions
+- Feedback history
+
+These are stored in `.workflow/state/` and applied to all future work.
+
+---
+
+## decisions.md
+
+The primary store for project-specific patterns.
+
+### Structure
+
+```markdown
+# Project Decisions
+
+## Tech Stack
+- **Language**: TypeScript
+- **Framework**: Next.js
+- **Database**: PostgreSQL (Prisma)
+
+## Conventions
+- Use functional components
+- All API calls through `lib/api.ts`
+- State management with Zustand
+
+## Patterns
+
+### API Calls
+Always use the axios wrapper from `lib/api.ts`:
+```typescript
+import { api } from '@/lib/api';
+const data = await api.get('/users');
+```
+
+### Error Boundaries
+Wrap page components with ErrorBoundary:
+```typescript
+<ErrorBoundary fallback={<ErrorPage />}>
+  <PageContent />
+</ErrorBoundary>
+```
+
+## Anti-Patterns
+
+### ❌ Direct fetch calls
+Don't use raw fetch - use the api wrapper for error handling.
+
+### ❌ Class components
+Use functional components with hooks.
+```
+
+### How It's Updated
+
+1. **During Correction**: AI offers to persist pattern
+2. **Manual Edit**: User adds patterns directly
+3. **Automatic Extraction**: From repeated feedback
+4. **On Onboarding**: From detected conventions
+
+---
+
+## Feedback Patterns
+
+History of corrections stored in `feedback-patterns.md`.
+
+### Structure
+
+```markdown
+# Feedback Patterns
+
+## 2024-01-15
+
+### Pattern: API Error Handling
+**Trigger**: User corrected missing error handling
+**Resolution**: Always wrap API calls in try/catch
+**Persisted to**: decisions.md
+
+### Pattern: Import Ordering
+**Trigger**: User preferred specific import order
+**Resolution**: React imports first, then third-party, then local
+**Persisted to**: decisions.md
+```
+
+### Purpose
+
+- Track correction history
+- Identify recurring issues
+- Feed into automatic learning
+
+---
+
+## Automatic Pattern Extraction
+
+When `autoExtract` is enabled:
+
+```json
+{
+  "skillLearning": {
+    "autoExtract": true,
+    "triggers": {
+      "onCommit": true,
+      "onTaskComplete": true,
+      "onCompact": true
+    },
+    "minCorrectionsToLearn": 1
+  }
+}
+```
+
+### Extraction Process
+
+1. **Trigger**: On configured events
+2. **Analyze**: Review recent corrections and feedback
+3. **Extract**: Identify patterns from corrections
+4. **Propose**: Suggest adding to decisions.md
+5. **Confirm**: User approves or rejects
+
+---
+
+## Request Log as Memory
+
+The request log serves as institutional memory:
+
+```markdown
+### R-047 | 2024-01-15 14:30
+**Type**: new
+**Tags**: #screen:login #component:AuthService
+**Request**: "Add user authentication"
+**Result**: Created AuthService using existing api wrapper pattern
+**Files**: src/services/AuthService.ts
+```
+
+### How It's Used
+
+- **Context**: AI reads recent entries for patterns
+- **Consistency**: Previous approaches inform new work
+- **Audit Trail**: Track decisions over time
+
+---
+
+## Component Registry Growth
+
+As new components are created:
+
+1. **Added to app-map.md**: With descriptions and usage
+2. **Preferred for Reuse**: AI checks before creating new
+3. **Variant Detection**: Suggest variants over new components
+
+```json
+{
+  "componentRules": {
+    "preferVariants": true,
+    "requireAppMapEntry": true
+  }
+}
+```
+
+---
+
+## Correction Workflow
+
+When user corrects the AI:
+
+```
+User: "Don't use raw fetch, use the api wrapper"
+           ↓
+AI: "I'll fix that. Should I persist this pattern?"
+    Options:
+    1. Add to decisions.md ← Best for project patterns
+    2. Add to agents/developer.md
+    3. Add to config.json
+    4. Skip (one-time fix)
+           ↓
+User: "1"
+           ↓
+AI: Updates decisions.md with pattern
+    Commits change
+    Logs to feedback-patterns.md
+```
+
+---
+
+## Configuration
+
+```json
+{
+  "corrections": {
+    "mode": "inline",              // Where to show corrections
+    "detailPath": ".workflow/corrections"  // Detailed reports
+  },
+  "skillLearning": {
+    "enabled": true,
+    "minCorrectionsToLearn": 1    // Min corrections before extraction
+  }
+}
+```
+
+---
+
+## Correction Reports
+
+For significant bugs, create detailed reports:
+
+```bash
+/wogi-correction
+
+# Creates detailed report with:
+# - Root cause analysis
+# - Fix description
+# - Prevention pattern
+# - Files affected
+```
+
+### Report Structure
+
+```markdown
+# Correction Report: Auth Token Refresh
+
+## Issue
+API calls failed after token expiration
+
+## Root Cause
+No token refresh logic in api wrapper
+
+## Fix Applied
+Added interceptor to refresh expired tokens
+
+## Prevention Pattern
+All API wrappers should include token refresh:
+```typescript
+api.interceptors.response.use(null, async (error) => {
+  if (error.response?.status === 401) {
+    await refreshToken();
+    return api.request(error.config);
+  }
+  throw error;
+});
+```
+
+## Persisted To
+- decisions.md (pattern added)
+- lib/api.ts (code updated)
+```
+
+---
+
+## Best Practices
+
+1. **Persist Important Corrections**: Don't skip the prompt
+2. **Be Specific**: Include code examples when helpful
+3. **Use Categories**: Organize patterns in decisions.md
+4. **Include Anti-Patterns**: Document what NOT to do
+5. **Review Regularly**: Clean up outdated patterns
+
+---
+
+## Troubleshooting
+
+### Patterns Not Applied
+
+Check if pattern is in decisions.md:
+```bash
+grep -i "pattern-keyword" .workflow/state/decisions.md
+```
+
+### Too Many Prompts
+
+Reduce correction prompts:
+```json
+{
+  "corrections": {
+    "mode": "inline"  // vs "detailed"
+  }
+}
+```
+
+### Pattern Conflicts
+
+If patterns conflict:
+1. Check decisions.md for contradictions
+2. Remove outdated patterns
+3. Clarify with specific examples
+
+---
+
+## Related
+
+- [Skill Learning](./skill-learning.md) - Framework-level patterns
+- [Model Learning](./model-learning.md) - Per-model optimization
+- [Task Execution](../02-task-execution/) - Where patterns apply

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

@@ -0,0 +1,372 @@
+# Skill-Level Learning
+
+Framework-specific patterns, anti-patterns, and skill creation.
+
+---
+
+## Overview
+
+Skills encapsulate framework-specific knowledge:
+- Best practices for React, NestJS, FastAPI, etc.
+- Common anti-patterns to avoid
+- Framework-specific code snippets
+- Official documentation references
+
+---
+
+## Skill Structure
+
+```
+.claude/skills/
+├── react/
+│   ├── skill.md                  # Skill definition
+│   └── knowledge/
+│       ├── patterns.md           # Best practices
+│       └── anti-patterns.md      # What to avoid
+├── nestjs/
+│   ├── skill.md
+│   └── knowledge/
+│       ├── patterns.md
+│       └── anti-patterns.md
+└── ...
+```
+
+---
+
+## Configuration
+
+```json
+{
+  "skillLearning": {
+    "enabled": true,
+    "autoExtract": true,
+    "triggers": {
+      "onCommit": true,
+      "onTaskComplete": true,
+      "onCompact": true
+    },
+    "minCorrectionsToLearn": 1,
+    "autoCreateSkills": "ask",        // "ask" | "auto" | "off"
+    "autoDetectFrameworks": true,
+    "fetchOfficialDocs": true
+  },
+  "skills": {
+    "installed": ["react", "nestjs"]
+  }
+}
+```
+
+---
+
+## Auto-Skill Creation
+
+When a framework is detected but no skill exists:
+
+```json
+{
+  "skillLearning": {
+    "autoCreateSkills": "ask"    // Prompt before creating
+  }
+}
+```
+
+### Options
+
+| Value | Behavior |
+|-------|----------|
+| `"ask"` | Prompt user before creating |
+| `"auto"` | Create automatically |
+| `"off"` | Never auto-create |
+
+### Creation Flow
+
+```
+Framework Detected: NestJS
+         ↓
+No existing skill found
+         ↓
+┌─────────────────────────────────────────┐
+│ Create NestJS skill? [y/n]              │
+│                                         │
+│ This will create:                       │
+│ - .claude/skills/nestjs/skill.md                │
+│ - .claude/skills/nestjs/knowledge/patterns.md   │
+│ - .claude/skills/nestjs/knowledge/anti-patterns.md
+└─────────────────────────────────────────┘
+         ↓
+User confirms → Skill created
+```
+
+---
+
+## Skill Definition (skill.md)
+
+```markdown
+# NestJS Skill
+
+## Framework
+NestJS - A progressive Node.js framework
+
+## When Active
+This skill applies when working with:
+- `.module.ts` files
+- `.controller.ts` files
+- `.service.ts` files
+- `@nestjs/*` imports
+
+## Key Concepts
+- Dependency injection via decorators
+- Module-based architecture
+- Guard/Interceptor/Pipe patterns
+
+## Official Docs
+https://docs.nestjs.com
+```
+
+---
+
+## Pattern Files
+
+### patterns.md
+
+```markdown
+# NestJS Patterns
+
+## Module Organization
+
+Every feature should have its own module:
+```typescript
+@Module({
+  imports: [TypeOrmModule.forFeature([User])],
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService]
+})
+export class UsersModule {}
+```
+
+## Service Layer
+
+Keep controllers thin, put logic in services:
+```typescript
+@Injectable()
+export class UsersService {
+  constructor(
+    @InjectRepository(User)
+    private usersRepository: Repository<User>,
+  ) {}
+
+  findAll(): Promise<User[]> {
+    return this.usersRepository.find();
+  }
+}
+```
+
+## DTOs
+
+Always validate input with class-validator:
+```typescript
+export class CreateUserDto {
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @IsEmail()
+  email: string;
+}
+```
+```
+
+### anti-patterns.md
+
+```markdown
+# NestJS Anti-Patterns
+
+## ❌ Business Logic in Controllers
+
+Don't put business logic in controllers:
+```typescript
+// BAD
+@Controller('users')
+export class UsersController {
+  @Post()
+  create(@Body() dto: CreateUserDto) {
+    // Logic here is wrong
+    const user = { ...dto, createdAt: new Date() };
+    return this.repo.save(user);
+  }
+}
+
+// GOOD
+@Controller('users')
+export class UsersController {
+  @Post()
+  create(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
+  }
+}
+```
+
+## ❌ Circular Dependencies
+
+Avoid circular module dependencies:
+```typescript
+// BAD: Module A imports B, B imports A
+
+// GOOD: Use forwardRef() or restructure
+@Module({
+  imports: [forwardRef(() => ModuleB)]
+})
+export class ModuleA {}
+```
+```
+
+---
+
+## Pattern Extraction
+
+When corrections relate to a framework:
+
+1. **Detect Framework**: Match against installed skills
+2. **Extract Pattern**: Identify the learning
+3. **Route Appropriately**: Skill patterns vs project decisions
+4. **Update Skill**: Add to patterns.md or anti-patterns.md
+
+```
+User: "In NestJS, services should be @Injectable"
+         ↓
+Detected: NestJS-specific correction
+         ↓
+Added to: .claude/skills/nestjs/knowledge/patterns.md
+```
+
+---
+
+## Official Docs Integration
+
+When `fetchOfficialDocs` is enabled:
+
+```json
+{
+  "skillLearning": {
+    "fetchOfficialDocs": true,
+    "officialDocsUrls": {
+      "nestjs": "https://docs.nestjs.com",
+      "react": "https://react.dev"
+    }
+  }
+}
+```
+
+Benefits:
+- Reference official patterns
+- Stay updated with best practices
+- Cite authoritative sources
+
+---
+
+## Manual Learning Trigger
+
+```bash
+/wogi-skill-learn
+
+# Output:
+# 🎓 Skill Learning Extraction
+#
+# Analyzing recent commits and corrections...
+#
+# Found patterns:
+#   1. NestJS: Use ConfigService for env vars
+#   2. React: Prefer named exports for components
+#
+# Add to skills? [y/n]
+```
+
+---
+
+## Continual Learning Skills
+
+Some skills continuously learn:
+
+```markdown
+# skill.md
+
+## Continual Learning
+This skill should:
+- Track new patterns from corrections
+- Update with latest best practices
+- Learn from code review feedback
+```
+
+---
+
+## Skill Activation
+
+Skills activate based on context:
+
+```
+Working on src/users/users.module.ts
+         ↓
+Detect: NestJS module file
+         ↓
+Activate: nestjs skill
+         ↓
+Apply: NestJS patterns from skill
+```
+
+### Activation Triggers
+
+| File Pattern | Skill Activated |
+|--------------|-----------------|
+| `*.tsx`, `*.jsx` | react |
+| `*.module.ts`, `*.controller.ts` | nestjs |
+| `*.vue` | vue |
+| `main.py` + fastapi | fastapi |
+
+---
+
+## Custom Skills
+
+Create project-specific skills:
+
+```bash
+mkdir -p .claude/skills/my-skill/knowledge
+
+cat > .claude/skills/my-skill/skill.md << 'EOF'
+# My Custom Skill
+
+## When Active
+When working with internal-api patterns
+
+## Key Concepts
+- All API calls must use v2 endpoint
+- Auth tokens must be refreshed
+EOF
+
+cat > .claude/skills/my-skill/knowledge/patterns.md << 'EOF'
+# Internal API Patterns
+
+## V2 Endpoints
+Always use v2 API endpoints:
+```typescript
+const response = await api.get('/api/v2/users');
+```
+EOF
+```
+
+Add to config:
+```json
+{
+  "skills": {
+    "installed": ["my-skill"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [Project Learning](./project-learning.md) - Project-specific patterns
+- [Model Learning](./model-learning.md) - Per-model optimization
+- [Framework Detection](../01-setup-onboarding/framework-detection.md)