From b8b5e9d6efcf8cefb8f9a2dd245880afd45a58cd Mon Sep 17 00:00:00 2001 From: YusufKaraaslanSpyke Date: Fri, 30 Jan 2026 14:07:20 +0300 Subject: [PATCH] perf: Optimize LOCAL mode AI enhancement with parallel execution - Increase default batch size from 5 to 20 patterns per CLI call - Add parallel execution with 3 concurrent workers (configurable) - Add ai_enhancement settings to config_manager: - local_batch_size: patterns per Claude CLI call (default: 20) - local_parallel_workers: concurrent CLI calls (default: 3) - Expected speedup: 6-12x faster for large codebases Config settings can be changed via: skill-seekers config (coming soon) or editing ~/.config/skill-seekers/config.json Co-Authored-By: Claude Opus 4.5 --- docs/plans/SPYKE_INTEGRATION_NOTES.md | 265 ++++++++ docs/plans/SPYKE_SKILL_AGENT_PROPOSAL.md | 774 +++++++++++++++++++++++ spyke_confluence_analysis.md | 396 ++++++++++++ src/skill_seekers/cli/ai_enhancer.py | 145 ++++- src/skill_seekers/cli/config_manager.py | 33 + 5 files changed, 1597 insertions(+), 16 deletions(-) create mode 100644 docs/plans/SPYKE_INTEGRATION_NOTES.md create mode 100644 docs/plans/SPYKE_SKILL_AGENT_PROPOSAL.md create mode 100644 spyke_confluence_analysis.md diff --git a/docs/plans/SPYKE_INTEGRATION_NOTES.md b/docs/plans/SPYKE_INTEGRATION_NOTES.md new file mode 100644 index 0000000..714901b --- /dev/null +++ b/docs/plans/SPYKE_INTEGRATION_NOTES.md @@ -0,0 +1,265 @@ +# Spyke Games - Skill Seekers Integration Notes + +> Discussion notes for Claude Code + Skill Seekers integration at Spyke Games +> Date: 2026-01-06 + +--- + +## Current State Analysis + +### What They Have (Excellent Foundation) + +``` +knit-game-client/docs/ +├── workflows/ +│ └── feature-development-workflow.md # Complete dev workflow +├── templates/ +│ ├── ANALYSIS-CHECKLIST.md # 13-section feature analysis +│ ├── DESIGN-TEMPLATE.md # Feature design template +│ ├── TDD-TEMPLATE.md # Technical design doc +│ ├── PR-CHECKLIST.md # Review checklist with pitfalls +│ └── ISSUE-TEMPLATE.md # GitHub issue structure +└── features/ + └── area-cover-blocker/ # Example complete feature + ├── DESIGN.md # 549 lines, comprehensive + ├── EDGE-CASES.md + ├── TASKS.md + └── TDD.md +``` + +### Key Observations + +1. **Already using Claude Code skill references** in docs: + - `/knitgame-core` - Core gameplay patterns + - `/threadbox-blocker` - Grid blocker patterns + +2. **Documented Common Pitfalls** (PR-CHECKLIST.md): + - UnityEngine in Controller/Model (MVC violation) + - Stale references after async + - Memory leaks from events (missing Dispose) + - Animation ID leaks (missing try-finally) + - Missing PrepareForReuse state reset + - Double-despawn race conditions + - Play-on under-restoration + +3. **MVC Layer Rules** (CRITICAL): + | Layer | UnityEngine | Purpose | + |-------|-------------|---------| + | Model | NO | Pure C# data, state, logic | + | Controller | NO | Business logic, orchestration | + | View | YES | MonoBehaviour, visuals | + | Service | YES | Business logic needing Unity APIs | + +4. **Test Patterns**: + - Reflection-based DI injection (no Zenject in tests) + - NSubstitute for mocking + - Real models, mocked dependencies + +--- + +## Proposed Skill Layer Architecture + +### Layer 1: Workflow Skills (HOW to develop) + +| Skill | Source | Purpose | +|-------|--------|---------| +| `yarn-flow-workflow` | `docs/workflows/` | Feature development lifecycle | +| `yarn-flow-analysis` | `ANALYSIS-CHECKLIST.md` | Feature analysis patterns | +| `yarn-flow-pr-review` | `PR-CHECKLIST.md` | Review checklist, pitfalls | +| `yarn-flow-testing` | Test files + templates | Test patterns, reflection DI | + +### Layer 2: Pattern Skills (WHAT to implement) + +| Skill | Source | Purpose | +|-------|--------|---------| +| `yarn-flow-mvc` | Workflow docs + code | MVC layer rules | +| `yarn-flow-blockers` | Blocker implementations | Grid/Yarn/Bottom patterns | +| `yarn-flow-boosters` | Booster implementations | Booster patterns | +| `yarn-flow-async` | Code patterns | UniTask, cancellation, safety | +| `yarn-flow-pooling` | Generators | ObjectPool, PrepareForReuse | +| `yarn-flow-events` | Controllers | Event lifecycle (Init/Dispose) | +| `yarn-flow-di` | Installers | Zenject binding patterns | + +### Layer 3: Reference Skills (Examples to follow) + +| Skill | Source | Purpose | +|-------|--------|---------| +| `yarn-flow-threadbox` | ThreadBox implementation | Reference grid blocker | +| `yarn-flow-mystery` | Mystery implementation | Reference yarn blocker | +| `yarn-flow-areacover` | AreaCover + DESIGN.md | Recent, fully documented | + +--- + +## Proposed Agent Architecture + +### 1. Feature Analysis Agent + +``` +Trigger: "analyze feature {X}" or "what base class for {X}" +Skills: yarn-flow-analysis, yarn-flow-blockers, yarn-flow-boosters +Action: + - Runs ANALYSIS-CHECKLIST programmatically + - Identifies feature type (Grid/Yarn/Bottom Blocker, Booster) + - Suggests base class + - Maps system interactions + - Identifies edge cases + - Outputs gap analysis +``` + +### 2. Design Document Agent + +``` +Trigger: "create design doc for {X}" or when starting new feature +Skills: yarn-flow-workflow, yarn-flow-blockers, yarn-flow-reference +Action: + - Creates docs/features/{feature}/DESIGN.md from template + - Pre-populates interaction matrix based on feature type + - Suggests edge cases from similar features + - Creates EDGE-CASES.md skeleton +``` + +### 3. PR Review Agent + +``` +Trigger: PR created, "review PR", or pre-commit hook +Skills: yarn-flow-pr-review, yarn-flow-mvc, yarn-flow-async +Action: + - Scans for UnityEngine imports in Controller/Model + - Verifies IInitializable + IDisposable pair + - Checks event subscription/unsubscription balance + - Validates PrepareForReuse resets all state + - Checks async safety (CancellationToken, try-finally) + - Verifies test coverage for public methods +Output: Review comments with specific line numbers +``` + +### 4. Code Scaffold Agent + +``` +Trigger: "implement {type} {name}" after design approved +Skills: yarn-flow-blockers, yarn-flow-di, yarn-flow-pooling +Action: + - Generates Model extending correct base class + - Generates Controller with IInitializable, IDisposable + - Generates ModelGenerator with ObjectPool + - Generates View (MonoBehaviour) + - Adds DI bindings to installer + - Creates test file skeletons +Output: Complete scaffold following all patterns +``` + +--- + +## New Grad Pipeline Vision + +``` +FEATURE REQUEST + ↓ +┌─────────────────────────────────────────┐ +│ 1. ANALYSIS AGENT │ +│ "Analyze feature ThreadCutter" │ +│ → Suggests GridBlockerBaseModel │ +│ → Maps interactions │ +│ → Identifies 12 edge cases │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 2. DESIGN AGENT │ +│ "Create design doc" │ +│ → Generates DESIGN.md (80% complete) │ +│ → New grad fills in specifics │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 3. CODE SCAFFOLD AGENT │ +│ "Implement ThreadCutter" │ +│ → Generates 6 files with patterns │ +│ → All boilerplate correct │ +│ → New grad fills in business logic │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 4. NEW GRAD CODES │ +│ Has correct structure │ +│ Just writes the actual logic │ +│ Skills loaded = answers questions │ +└─────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 5. PR REVIEW AGENT │ +│ "Review my PR" │ +│ → Catches MVC violations │ +│ → Verifies async safety │ +│ → Checks test coverage │ +│ → Feedback before human review │ +└─────────────────────────────────────────┘ + ↓ +SENIOR-QUALITY CODE FROM JUNIOR DEV +``` + +--- + +## Implementation Priority + +### Phase 1: Core Skills (Week 1) +1. Generate skill from `knit-game-client` repo (full codebase) +2. Generate skill from `docs/` folder specifically +3. Install to Claude Code for all devs + +### Phase 2: Specialized Skills (Week 2) +1. Split into workflow vs pattern skills +2. Create reference skills from best implementations +3. Test with actual feature development + +### Phase 3: Agents (Week 3-4) +1. PR Review Agent (highest ROI - catches common pitfalls) +2. Analysis Agent (helps new devs start correctly) +3. Code Scaffold Agent (reduces boilerplate time) + +### Phase 4: CI/CD Integration (Week 5+) +1. PR Review Agent as GitHub Action +2. Auto-regenerate skills when docs change +3. Team-wide skill distribution + +--- + +## Questions to Resolve + +1. **Confluence Integration** + - How stale is Confluence vs docs/ folder? + - Should we scrape Confluence or focus on in-repo docs? + - Can we set up sync from Confluence → docs/ → skills? + +2. **Skill Granularity** + - One big `yarn-flow` skill vs many small skills? + - Recommendation: Start with 2-3 (workflow, patterns, reference) + - Split more if Claude context gets overloaded + +3. **Agent Deployment** + - Local per-developer vs team server? + - GitHub Actions integration? + - Slack/Teams notifications? + +4. **SDK Skills** + - Which SDKs cause most pain? + - Firebase? Analytics? Ads? IAP? + - Prioritize based on integration frequency + +--- + +## Related Discussions + +- Layered skill architecture (game → framework → external → base) +- New grad onboarding goal: "produce code near our standard" +- Manual review → automated agent review pipeline +- Confluence freshness concerns + +--- + +## Next Steps + +1. [ ] Generate skill from knit-game-client repo +2. [ ] Test with actual feature development +3. [ ] Identify highest-pain SDK for skill creation +4. [ ] Design PR Review Agent prompt +5. [ ] Pilot with 1-2 developers diff --git a/docs/plans/SPYKE_SKILL_AGENT_PROPOSAL.md b/docs/plans/SPYKE_SKILL_AGENT_PROPOSAL.md new file mode 100644 index 0000000..9eaf14a --- /dev/null +++ b/docs/plans/SPYKE_SKILL_AGENT_PROPOSAL.md @@ -0,0 +1,774 @@ +# Skill & Agent Integration Proposal + +## Spyke Games - Claude Code Enhanced Development Workflow + +> **Prepared for:** CTO Review +> **Date:** 2026-01-06 +> **Status:** Proposal + +--- + +## Executive Summary + +This proposal outlines an AI-augmented development workflow using **Claude Code** with custom **Skills** and **Agents** to: + +1. **Codify institutional knowledge** into reusable AI skills +2. **Automate quality gates** via specialized agents +3. **Enable pair programming** where Claude implements while developers observe and validate +4. **Ensure consistency** - any developer produces senior-quality code + +**Expected Outcome:** New team members can produce production-ready code that follows all architectural patterns, passes review automatically, and matches team standards from day one. + +--- + +## Current Workflow Challenges + +| Challenge | Impact | Current Mitigation | +|-----------|--------|-------------------| +| MVC violations (UnityEngine in Controller) | Breaks testability, requires refactoring | Manual code review | +| Async safety issues (stale refs, missing CancellationToken) | Race conditions, hard-to-debug bugs | Senior developer knowledge | +| Missing PrepareForReuse/Dispose | Memory leaks, level replay bugs | PR checklist (manual) | +| Inconsistent patterns across developers | Technical debt accumulation | Documentation (not always read) | +| Onboarding time for new developers | 2-3 months to full productivity | Mentorship, pair programming | + +--- + +## Proposed Solution: Skills + Agents + +### What Are Skills? + +Skills are **structured knowledge packages** that give Claude Code deep understanding of: +- Our codebase architecture (MVCN, Zenject, UniTask) +- Our coding patterns and conventions +- Our common pitfalls and how to avoid them +- Reference implementations to follow + +**When loaded, Claude Code "knows" our codebase like a senior developer.** + +### What Are Agents? + +Agents are **automated specialists** that perform specific tasks: +- Analyze feature requirements against our architecture +- Generate code following our patterns +- Review PRs for violations before human review +- Scaffold new features with correct boilerplate + +**Agents enforce consistency automatically.** + +--- + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ SKILL LAYERS │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ GAME LAYER - Yarn Flow Specific │ │ +│ │ │ │ +│ │ Workflow Skills: Pattern Skills: │ │ +│ │ ├─ yarn-flow-workflow ├─ yarn-flow-mvc │ │ +│ │ ├─ yarn-flow-analysis ├─ yarn-flow-blockers │ │ +│ │ ├─ yarn-flow-pr-review ├─ yarn-flow-boosters │ │ +│ │ └─ yarn-flow-testing ├─ yarn-flow-async │ │ +│ │ ├─ yarn-flow-pooling │ │ +│ │ Reference Skills: └─ yarn-flow-events │ │ +│ │ ├─ yarn-flow-threadbox │ │ +│ │ ├─ yarn-flow-mystery │ │ +│ │ └─ yarn-flow-areacover │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ FRAMEWORK LAYER - UPM Packages │ │ +│ │ ├─ upm-spyke-core │ │ +│ │ ├─ upm-spyke-services │ │ +│ │ ├─ upm-spyke-ui │ │ +│ │ └─ upm-spyke-sdks │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ EXTERNAL LAYER - Third-Party │ │ +│ │ ├─ zenject-skill │ │ +│ │ ├─ unitask-skill │ │ +│ │ ├─ dotween-skill │ │ +│ │ └─ addressables-skill │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ BASE LAYER - Unity │ │ +│ │ └─ unity-2022-lts-skill │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────┐ +│ AGENTS │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ +│ │ ANALYSIS │ │ SCAFFOLD │ │ PR REVIEW │ │ +│ │ AGENT │ │ AGENT │ │ AGENT │ │ +│ │ │ │ │ │ │ │ +│ │ Analyzes │ │ Generates │ │ Reviews code │ │ +│ │ requirements │ │ boilerplate │ │ for violations│ │ +│ │ Suggests │ │ Creates files │ │ Catches │ │ +│ │ architecture │ │ Adds DI │ │ pitfalls │ │ +│ └───────────────┘ └───────────────┘ └───────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Skill Definitions + +### Workflow Skills + +| Skill | Source | Purpose | +|-------|--------|---------| +| `yarn-flow-workflow` | `docs/workflows/feature-development-workflow.md` | Complete feature development lifecycle, phase gates | +| `yarn-flow-analysis` | `docs/templates/ANALYSIS-CHECKLIST.md` | 13-section feature analysis, system interaction matrix | +| `yarn-flow-pr-review` | `docs/templates/PR-CHECKLIST.md` | Review checklist, 20+ common pitfalls to catch | +| `yarn-flow-testing` | Test patterns from codebase | Reflection DI injection, NSubstitute mocking, test naming | + +### Pattern Skills + +| Skill | Source | Purpose | +|-------|--------|---------| +| `yarn-flow-mvc` | Controllers, Models, Views | MVC layer rules, UnityEngine boundaries | +| `yarn-flow-blockers` | Blocker implementations | Grid/Yarn/Bottom blocker patterns, base classes | +| `yarn-flow-boosters` | Booster implementations | BoosterControllerBase patterns, lifecycle | +| `yarn-flow-async` | Async code patterns | UniTask, CancellationToken, state revalidation | +| `yarn-flow-pooling` | Generators, PoolObjectBase | ObjectPool usage, PrepareForReuse, OnDespawn | +| `yarn-flow-events` | Controller lifecycle | IInitializable/IDisposable, event subscription balance | + +### Reference Skills + +| Skill | Source | Purpose | +|-------|--------|---------| +| `yarn-flow-threadbox` | ThreadBox implementation | Reference multi-cell grid blocker | +| `yarn-flow-mystery` | Mystery implementation | Reference yarn blocker with reveal | +| `yarn-flow-areacover` | AreaCover + DESIGN.md | Recent, fully documented blocker | + +--- + +## Agent Specifications + +### 1. Analysis Agent + +**Purpose:** Analyze feature requirements and map to architecture + +**Triggers:** +- "Analyze feature {name}" +- "What base class should I use for {description}" +- Starting any new feature + +**Skills Loaded:** +- `yarn-flow-analysis` +- `yarn-flow-blockers` +- `yarn-flow-boosters` + +**Input:** Feature name and description/ruleset + +**Output:** +```markdown +## Feature Analysis: {Name} + +### Classification +- Type: Grid Blocker +- Base Class: GridBlockerBaseModel +- Interface: IGridBlocker + +### System Interactions +| System | Interaction | Details | +|--------|-------------|---------| +| Unstitch | Blocks covered cells | Exclude from TryGetUnstitchTarget() | +| Belt | No direct interaction | - | +| Play-On | Counter restoration | Save/restore checkpoint | + +### Identified Edge Cases +1. Level ends during destruction animation +2. Multiple instances triggered simultaneously +3. Counter exceeds remaining (clamp to 0) +... + +### Similar Implementations +- ThreadBox (multi-cell, direction-based entry) +- KnitCover (single-cell cover) + +### Complexity Assessment: Medium +- Requires existing GridBlockerBaseModel patterns +- Direction-based entry adaptation needed + +### Next Steps +1. Create DESIGN.md with full specifications +2. Get stakeholder approval on edge case behaviors +3. Proceed to implementation +``` + +--- + +### 2. Scaffold Agent + +**Purpose:** Generate complete file structure following all patterns + +**Triggers:** +- "Implement {type} {name}" +- "Create scaffold for {feature}" +- After design approval + +**Skills Loaded:** +- `yarn-flow-blockers` or `yarn-flow-boosters` (based on type) +- `yarn-flow-di` +- `yarn-flow-pooling` +- `yarn-flow-events` + +**Input:** Feature type, name, and approved DESIGN.md + +**Output Files Generated:** + +``` +Assets/KnitGame/Scripts/ +├── Model/Blockers/ +│ └── {Feature}Model.cs +├── Controller/Blockers/{Feature}/ +│ ├── {Feature}Controller.cs +│ └── I{Feature}Controller.cs +├── Controller/Generators/ +│ └── {Feature}ModelGenerator.cs +├── View/Blockers/{Feature}/ +│ ├── {Feature}View.cs +│ └── {Feature}ViewGroup.cs (if multi-cell) +└── Tests/ + ├── {Feature}ModelTests.cs + └── {Feature}ControllerTests.cs + ++ DI bindings added to KnitGameInstaller.cs +``` + +**Code Quality Guarantees:** +- Models extend correct base class +- Controllers implement IInitializable, IDisposable +- PrepareForReuse implemented with all state reset +- ObjectPool used in generators +- Event subscriptions balanced (subscribe in Initialize, unsubscribe in Dispose) +- No UnityEngine imports in Model/Controller +- Test files with reflection DI helper + +--- + +### 3. PR Review Agent + +**Purpose:** Automated code review before human review + +**Triggers:** +- PR created +- "Review my PR" +- "Check this code" +- Pre-commit hook (optional) + +**Skills Loaded:** +- `yarn-flow-pr-review` +- `yarn-flow-mvc` +- `yarn-flow-async` +- `yarn-flow-pooling` + +**Checks Performed:** + +| Category | Check | Severity | +|----------|-------|----------| +| **MVC** | UnityEngine import in Controller | FAIL | +| **MVC** | UnityEngine import in Model | FAIL | +| **MVC** | Direct GameObject/Transform in Controller | FAIL | +| **Lifecycle** | IInitializable without IDisposable | WARN | +| **Lifecycle** | Event subscribe without unsubscribe | FAIL | +| **Lifecycle** | Missing PrepareForReuse | WARN | +| **Async** | Async method without CancellationToken | WARN | +| **Async** | State modification after await without check | FAIL | +| **Async** | Animation ID without try-finally | FAIL | +| **Async** | Missing `_gameModel.IsLevelEnded` check | WARN | +| **Pooling** | PoolObjectBase without OnDespawn override | WARN | +| **Pooling** | OnDespawn doesn't reset all fields | WARN | +| **Style** | Debug.Log instead of SpykeLogger | WARN | +| **Style** | Magic numbers without constants | INFO | +| **Testing** | Public method without test coverage | INFO | + +**Output Format:** +```markdown +## PR Review: #{PR_NUMBER} + +### Summary +- 2 FAIL (must fix) +- 3 WARN (should fix) +- 1 INFO (consider) + +### Issues Found + +#### FAIL: UnityEngine in Controller +`ThreadCutterController.cs:15` +```csharp +using UnityEngine; // VIOLATION: Controllers must be pure C# +``` +**Fix:** Remove UnityEngine dependency, use interface for view interaction + +#### FAIL: Missing CancellationToken Check +`ThreadCutterController.cs:89` +```csharp +await PlayAnimation(); +UpdateState(); // UNSAFE: State may have changed during await +``` +**Fix:** Add cancellation check before state modification: +```csharp +await PlayAnimation(); +if (_levelCts.Token.IsCancellationRequested) return; +UpdateState(); +``` + +#### WARN: Event Subscribe Without Unsubscribe +`ThreadCutterController.cs:45` +```csharp +_gridController.OnCellChanged += HandleCellChanged; +``` +**Fix:** Add unsubscribe in Dispose(): +```csharp +public void Dispose() +{ + _gridController.OnCellChanged -= HandleCellChanged; +} +``` + +### Recommendations +1. Fix both FAIL issues before merge +2. Address WARN issues to prevent technical debt +3. Consider INFO items for code quality improvement +``` + +--- + +## Development Workflow with Agents + +### Complete Feature Development Flow + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ FEATURE REQUEST RECEIVED │ +│ "Implement ThreadCutter blocker" │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ PHASE 1: ANALYSIS │ +│ ────────────────── │ +│ │ +│ Developer: "Analyze feature ThreadCutter - a grid blocker that │ +│ cuts threads when unstitch passes through" │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ ANALYSIS AGENT │ │ +│ │ │ │ +│ │ • Runs ANALYSIS-CHECKLIST │ │ +│ │ • Classifies as Grid Blocker → GridBlockerBaseModel │ │ +│ │ • Maps 8 system interactions │ │ +│ │ • Identifies 14 edge cases │ │ +│ │ • Suggests ThreadBox as reference │ │ +│ │ • Complexity: Medium │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ Developer: Reviews analysis, confirms understanding │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ PHASE 2: DESIGN │ +│ ─────────────── │ +│ │ +│ Developer: "Create design document for ThreadCutter" │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ CLAUDE CODE │ │ +│ │ (with skills loaded) │ │ +│ │ │ │ +│ │ • Creates docs/features/thread-cutter/DESIGN.md │ │ +│ │ • Populates from DESIGN-TEMPLATE │ │ +│ │ • Fills interaction matrix from analysis │ │ +│ │ • Creates EDGE-CASES.md with 14 identified cases │ │ +│ │ • Creates TDD.md skeleton │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ Developer: Reviews design, adds game-specific details │ +│ Stakeholders: Approve design document │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ PHASE 3: IMPLEMENTATION │ +│ ─────────────────────── │ +│ │ +│ Developer: "Implement ThreadCutter grid blocker per DESIGN.md" │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ SCAFFOLD AGENT │ │ +│ │ │ │ +│ │ Generates 8 files: │ │ +│ │ • ThreadCutterModel.cs │ │ +│ │ • ThreadCutterController.cs + Interface │ │ +│ │ • ThreadCutterModelGenerator.cs │ │ +│ │ • ThreadCutterView.cs + ViewGroup │ │ +│ │ • Test files │ │ +│ │ • DI bindings │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ CLAUDE CODE │ │ +│ │ (with skills loaded) │ │ +│ │ │ │ +│ │ • Implements business logic per DESIGN.md │ │ +│ │ • Handles all edge cases │ │ +│ │ • Writes comprehensive tests │ │ +│ │ • Follows all patterns from loaded skills │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ Developer: Observes, validates, runs tests, checks edge cases │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ PHASE 4: REVIEW │ +│ ────────────── │ +│ │ +│ Developer: "Review my PR" or creates PR │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ PR REVIEW AGENT │ │ +│ │ │ │ +│ │ Automated checks: │ │ +│ │ ✓ No UnityEngine in Controllers/Models │ │ +│ │ ✓ All events properly subscribed/unsubscribed │ │ +│ │ ✓ PrepareForReuse resets all state │ │ +│ │ ✓ CancellationToken used in async methods │ │ +│ │ ✓ Animation IDs cleaned up in finally blocks │ │ +│ │ ✓ Tests cover public methods │ │ +│ │ │ │ +│ │ Result: 0 FAIL, 1 WARN, 2 INFO │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ Developer: Addresses warnings, creates PR │ +│ Senior: Quick review (most issues already caught) │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ MERGE & DEPLOY │ +│ Production-ready code │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Developer Role Transformation + +### Before: Developer as Implementer + +``` +Developer receives task + → Reads docs (maybe) + → Writes code (varies by experience) + → Makes mistakes (caught in review) + → Refactors (wastes time) + → Eventually passes review + +Time: 3-5 days for feature +Quality: Depends on developer experience +``` + +### After: Developer as Validator + +``` +Developer receives task + → Analysis Agent analyzes requirements + → Claude Code creates design docs + → Developer validates design + → Scaffold Agent creates structure + → Claude Code implements logic + → Developer observes & validates + → PR Review Agent checks automatically + → Developer confirms & merges + +Time: 1-2 days for feature +Quality: Consistent senior-level regardless of developer experience +``` + +### Developer Responsibilities + +| Responsibility | Description | +|----------------|-------------| +| **Validate Analysis** | Confirm feature classification and edge cases | +| **Review Design** | Ensure design matches requirements | +| **Observe Implementation** | Watch Claude Code work, ask questions | +| **Test Functionality** | Run game, verify feature works correctly | +| **Verify Edge Cases** | Test each edge case from DESIGN.md | +| **Approve PR** | Final check before merge | + +--- + +## Implementation Roadmap + +### Phase 1: Foundation (Week 1-2) + +| Task | Description | Owner | +|------|-------------|-------| +| Generate `yarn-flow-core` skill | Full codebase analysis | DevOps | +| Generate `yarn-flow-docs` skill | All docs/ content | DevOps | +| Install skills to team Claude Code | All developers | DevOps | +| Test with real feature | Validate skill quality | 1 Developer | + +**Deliverable:** Skills working for all developers + +### Phase 2: Skill Specialization (Week 3-4) + +| Task | Description | Owner | +|------|-------------|-------| +| Split into workflow/pattern skills | Better context targeting | DevOps | +| Create reference skills | ThreadBox, Mystery, AreaCover | DevOps | +| Generate external skills | Zenject, UniTask, DOTween | DevOps | +| Validate skill loading | Test skill combinations | Team | + +**Deliverable:** Specialized skills for different tasks + +### Phase 3: Agent Development (Week 5-6) + +| Task | Description | Owner | +|------|-------------|-------| +| Build PR Review Agent | Automated code checking | DevOps | +| Build Analysis Agent | Feature analysis automation | DevOps | +| Build Scaffold Agent | Code generation | DevOps | +| Integration testing | Agents with skills | Team | + +**Deliverable:** Three working agents + +### Phase 4: Workflow Integration (Week 7-8) + +| Task | Description | Owner | +|------|-------------|-------| +| Update dev workflow docs | Incorporate agents | Tech Lead | +| Train team on new workflow | Hands-on sessions | Tech Lead | +| Pilot with 2-3 features | Real-world validation | Team | +| Iterate based on feedback | Refine agents/skills | DevOps | + +**Deliverable:** Production-ready workflow + +### Phase 5: CI/CD Integration (Week 9+) + +| Task | Description | Owner | +|------|-------------|-------| +| PR Review as GitHub Action | Automated on PR create | DevOps | +| Skill auto-regeneration | When docs/code changes | DevOps | +| Team-wide skill sync | Central skill repository | DevOps | +| Metrics dashboard | Track quality improvements | DevOps | + +**Deliverable:** Fully automated quality pipeline + +--- + +## Success Metrics + +### Quality Metrics + +| Metric | Current | Target | Measurement | +|--------|---------|--------|-------------| +| MVC violations per PR | ~2-3 | 0 | PR Review Agent | +| Async safety issues per PR | ~1-2 | 0 | PR Review Agent | +| PR review iterations | 2-3 | 1 | Git history | +| Bugs from pattern violations | Unknown | -80% | Bug tracking | + +### Efficiency Metrics + +| Metric | Current | Target | Measurement | +|--------|---------|--------|-------------| +| Time to implement blocker | 3-5 days | 1-2 days | Sprint tracking | +| Code review time | 1-2 hours | 15-30 min | Time tracking | +| Onboarding to productivity | 2-3 months | 2-3 weeks | HR tracking | + +### Consistency Metrics + +| Metric | Current | Target | Measurement | +|--------|---------|--------|-------------| +| Pattern compliance | ~70% | 98%+ | PR Review Agent | +| Test coverage | Varies | 80%+ | Coverage tools | +| Documentation completeness | Partial | Full | Checklist | + +--- + +## Risk Assessment + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| Skills become stale | Medium | High | Auto-regenerate on code changes | +| Over-reliance on AI | Medium | Medium | Developers still validate all code | +| Agent false positives | Low | Low | Tune thresholds, allow overrides | +| Claude API downtime | Low | Medium | Local fallback, manual workflow | +| Context size limits | Medium | Low | Split skills, load contextually | + +--- + +## Resource Requirements + +### Tools + +| Tool | Purpose | Cost | +|------|---------|------| +| Claude Code (Max) | AI pair programming | Existing subscription | +| Skill Seekers | Skill generation | Open source (free) | +| GitHub Actions | CI/CD integration | Existing | + +### Time Investment + +| Role | Initial Setup | Ongoing | +|------|---------------|---------| +| DevOps | 40 hours | 4 hours/week | +| Tech Lead | 16 hours | 2 hours/week | +| Developers | 4 hours training | Productivity gain | + +### Expected ROI + +| Investment | Return | +|------------|--------| +| 60 hours setup | 50% faster feature development | +| 6 hours/week maintenance | 80% fewer pattern violations | +| 4 hours training per dev | New devs productive in weeks, not months | + +--- + +## Appendix A: Skill Generation Commands + +```bash +# Generate core game skill +skill-seekers github \ + --repo spyke/knit-game-client \ + --name yarn-flow-core \ + --code-analysis-depth full \ + --enhance-local + +# Generate docs skill +skill-seekers scrape \ + --url file:///path/to/knit-game-client/docs \ + --name yarn-flow-docs \ + --enhance-local + +# Install to Claude Code +skill-seekers install-agent output/yarn-flow-core/ --agent claude +skill-seekers install-agent output/yarn-flow-docs/ --agent claude +``` + +## Appendix B: Agent Prompt Templates + +### PR Review Agent System Prompt + +``` +You are a code review agent for the Yarn Flow Unity game project. + +Your job is to review code changes and identify violations of project standards. + +LOADED SKILLS: +- yarn-flow-pr-review: PR checklist and common pitfalls +- yarn-flow-mvc: MVC layer rules +- yarn-flow-async: Async safety patterns + +REVIEW CHECKLIST: +1. MVC Violations + - Controllers/Models must NOT import UnityEngine + - Views implement interfaces defined by controllers + +2. Lifecycle Issues + - IInitializable requires IDisposable + - Events subscribed must be unsubscribed + - PrepareForReuse must reset ALL state + +3. Async Safety + - CancellationToken must be passed and checked + - State must be revalidated after await + - Animation IDs must use try-finally + +For each issue found, report: +- File and line number +- Severity (FAIL/WARN/INFO) +- Code snippet showing the problem +- Fix recommendation with corrected code +``` + +--- + +## Appendix C: Example Agent Output + +### Analysis Agent Output Example + +```markdown +## Feature Analysis: ThreadCutter + +### Classification +| Property | Value | +|----------|-------| +| Type | Grid Blocker | +| Base Class | `GridBlockerBaseModel` | +| Interface | `IGridBlocker` | +| Shape | Single-cell | +| Collection | Direction-based (cuts thread when unstitch passes through) | + +### System Interactions + +| System | Interacts | Details | +|--------|-----------|---------| +| Unstitch | YES | Cuts thread, decreases remaining count | +| Belt/Tray | NO | No direct interaction | +| Grid | YES | Registered in GridModel | +| Play-On | YES | Counter restoration needed | +| Level Goals | YES | Required goal type | +| ThreadBox | YES | Can coexist on same row | + +### Edge Cases Identified + +1. **Timing** + - Level ends during cut animation + - Multiple cuts triggered same frame + +2. **Spatial** + - ThreadCutter at grid edge + - Adjacent to another ThreadCutter + +3. **State** + - Counter reaches 0 during animation + - Play-on during cut animation + +### Complexity: Low-Medium +- Follows existing single-cell blocker patterns +- Direction-based collection similar to existing blockers + +### Reference Implementations +- `KnitCover` - Single-cell grid blocker +- `ThreadBox` - Direction-based entry +``` + +--- + +## Conclusion + +This proposal outlines a comprehensive system for AI-augmented game development that: + +1. **Captures institutional knowledge** in reusable skills +2. **Automates quality enforcement** via specialized agents +3. **Enables pair programming** with Claude Code as implementer +4. **Ensures consistency** across all developers regardless of experience + +The expected outcome is faster development, higher code quality, and dramatically reduced onboarding time for new team members. + +--- + +**Prepared by:** Claude Code + Skill Seekers +**For review by:** CTO, Tech Lead +**Next step:** Approve and begin Phase 1 implementation diff --git a/spyke_confluence_analysis.md b/spyke_confluence_analysis.md new file mode 100644 index 0000000..553d0c6 --- /dev/null +++ b/spyke_confluence_analysis.md @@ -0,0 +1,396 @@ +# Spyke Games Confluence Documentation Analysis & Skill Generation Plan + +## Executive Summary + +**Total Pages**: 147 +**Usable Content**: 127 pages (86%) +**Empty/Container**: 20 pages (14%) +**Legacy/Deprecated**: 17 pages (12%) +**Active & Valid**: ~110 pages (75%) + +--- + +## Document Hierarchy Overview + +``` +Engineering (root) +├── R&D/ +│ ├── Backend Architecture/ (5 docs) +│ ├── Client Architecture/ (9 docs + Addressables/5) +│ ├── Cloud Services/AWS notes/ (4 docs) +│ ├── Graphics/ (4 docs) +│ ├── Network Messaging/ (3 docs) +│ └── Tools/ (1 doc) +├── Backend Design/ (7 docs) +├── Team/ (4 docs) +├── Team Backend Notes/ (3 docs) +├── Cheatsheets/ (4 docs) +├── Tech Talks/ (3 docs) +├── Feature Flags/LiveOps Tooling/ (5+ docs) +├── Game Retrospectives/ (4 docs - legacy) +├── Reverse Engineering/ (7 docs - legacy) +├── Third Party SDKs/ (3 docs) +├── How To Add New Special Day Theme Assets/ (8 docs) +└── ~30 standalone pages +``` + +**Issues Found:** +- 3 orphaned docs (parent outside space) +- 20 empty container pages +- Inconsistent nesting (some topics deeply nested, others flat) +- Mixed languages (English + Turkish titles) + +--- + +## Skill Generation Recommendations + +### RECOMMENDED SKILLS TO GENERATE + +Based on content depth, code examples, and practical value: + +--- + +### 1. ⭐ SKILL: "spyke-unity-client" (HIGH VALUE) +**Content Sources**: 25 pages | ~59,000 chars | 12 with code + +**Topics to Include**: +- UI Panel Transitions +- Screen Scaling for mobile +- Addressables (caching, bundles, catalog structure) +- Scriptable Objects as Architecture +- MVCVM Architecture pattern +- Fast Generic Observers (SignalBus alternative) +- Persistent Data management +- Animation & Particle Performance +- Shader development (MultiLayerText, Blur) +- URP vs Legacy Render Pipeline + +**Why Generate**: +- Core Unity development patterns used across all games +- Reusable regardless of which game is active +- Good mix of code examples and explanations + +**Improvements Needed Before Generating**: +1. Finalize "Slot Game X - Architecture (MVCVM) - (Draft)" +2. Add code examples to "Scriptable Objects as Architecture" +3. Update "Built-in (Legacy) Render Pipeline vs URP" - mark Legacy as deprecated +4. Consolidate Addressables docs into cohesive guide + +--- + +### 2. ⭐ SKILL: "spyke-backend" (HIGH VALUE) +**Content Sources**: 16 pages | ~36,000 chars | 5 with code + +**Topics to Include**: +- Database Version Control/Migration (Flyway) +- Database Access Layer patterns +- Spring/Gradle architecture +- Game Server architecture +- Load testing approaches +- Security measures +- MySQL/Aurora patterns +- Chat backend implementation + +**Why Generate**: +- Backend patterns are game-agnostic +- Critical for onboarding backend devs +- Contains production-tested patterns + +**Improvements Needed Before Generating**: +1. Finalize "Backend Code Structure (draft)" +2. Finalize "Chat Mysql (draft)" +3. Finalize "Help Call Backend Notes (Draft)" +4. Translate Turkish content: "bonanza ve lucky spin..." → English +5. Add more code examples to architecture docs + +--- + +### 3. ⭐ SKILL: "spyke-aws" (MEDIUM VALUE) +**Content Sources**: 9 pages | ~22,000 chars | 3 with code + +**Topics to Include**: +- AWS account/users/groups/policies +- Elastic Beanstalk setup +- Gateway and ALB configuration +- Aurora database notes +- Performance testing with k6 +- AWS CLI access (secure) +- AWS Evidently for feature flags +- Cost saving strategies + +**Why Generate**: +- Infrastructure knowledge critical for ops +- k6 performance testing guide is excellent +- AWS patterns are reusable + +**Improvements Needed Before Generating**: +1. Finalize "Secure AWS CLI Access (DRAFT)" +2. Update AWS notes - verify if still using EB or migrated +3. Add more practical examples to account setup docs + +--- + +### 4. SKILL: "spyke-onboarding" (MEDIUM VALUE) +**Content Sources**: 13 pages | ~26,000 chars | 4 with code + +**Topics to Include**: +- Welcome To The Team +- Buddy System +- Code Review (How To) +- Release Manager responsibilities +- Git Submodule management +- New Project Setup from Bootstrap +- Unit Test Integration to Pipeline +- Mock Web Service Tool + +**Why Generate**: +- Essential for new engineer onboarding +- Process documentation is evergreen +- Reduces tribal knowledge + +**Improvements Needed Before Generating**: +1. Update "Welcome To The Team" with current tools/processes +2. Add current team structure to Team docs +3. Verify pipeline docs match current CI/CD + +--- + +### 5. SKILL: "spyke-sdks" (LOW VALUE - CONSIDER SKIP) +**Content Sources**: 7 pages | ~7,000 chars | 5 with code + +**Topics to Include**: +- MAX SDK integration +- OneSignal push notifications +- Braze platform notes +- AppsFlyer (if still used) +- i2 localization +- Huawei App Gallery + +**Why Generate**: SDK integration guides save time + +**Issues**: +- Most are version-specific and may be outdated +- Low content depth +- Better to link to official SDK docs + +**Recommendation**: Skip or merge into onboarding skill + +--- + +### 6. SKILL: "spyke-liveops" (LOW VALUE - NEEDS WORK) +**Content Sources**: ~10 pages | Content scattered + +**Topics to Include**: +- Feature Flags overview +- Split.io vs Unleash vs AWS Evidently comparison +- A/B Test Infrastructure +- Configuration Management + +**Issues**: +- Content is fragmented +- Many empty placeholder pages +- "The Choice and Things to Consider" has no conclusion + +**Recommendation**: Consolidate before generating + +--- + +## NOT RECOMMENDED FOR SKILLS + +### Legacy/Deprecated (17 pages) +- Coin Master, Tile Busters, Royal Riches, Island King, Pirate King docs +- **Action**: Archive in Confluence, do NOT include in skills +- **Exception**: "Learnings From X" docs have reusable insights - extract generic patterns + +### Empty Containers (20 pages) +- Engineering, R&D, Client, Backend, etc. +- **Action**: Either delete or add meaningful overview content + +### Game-Specific Workflows +- "How to add new Endless Offers (Tile Busters)" - deprecated +- "Tile Busters Particle Optimizations" - game-specific +- **Action**: Generalize or archive + +--- + +## Individual Document Improvements + +### HIGH PRIORITY (Block skill generation) + +| Document | Issue | Action | +|----------|-------|--------| +| Slot Game X - Architecture (MVCVM) - (Draft) | Still draft | Finalize or remove draft label | +| Backend Code Structure (draft) | Still draft | Finalize with current structure | +| Chat Mysql (draft) | Still draft | Finalize or archive | +| Secure AWS CLI Access (DRAFT) | Still draft | Finalize - important for security | +| Help Call Backend Notes (Draft) | Still draft | Finalize or archive | +| Submodule [Draft] | Still draft | Merge with Git Submodule doc | +| Creating New Team Event (DRAFT) | Still draft | Finalize | +| bonanza ve lucky spin... | Turkish title | Translate to English | + +### MEDIUM PRIORITY (Improve quality) + +| Document | Issue | Action | +|----------|-------|--------| +| Scriptable Objects as Architecture | No code examples | Add Unity C# examples | +| Built-in (Legacy) vs URP | Doesn't say which to use | Add clear recommendation: "Use URP" | +| Feature Flag System | No conclusion | Add recommendation on which system | +| The Choice and Things to Consider | Incomplete | Add final decision/recommendation | +| AWS notes (container) | Empty | Add overview or delete | +| Third Party SDKs (container) | Empty | Add overview or delete | +| All 20 empty containers | No content | Add overview content or delete | + +### LOW PRIORITY (Nice to have) + +| Document | Issue | Action | +|----------|-------|--------| +| Addressables (5 docs) | Scattered | Consolidate into single comprehensive guide | +| Animation Performance (2 docs) | Overlap | Merge benchmarks with tips | +| LiveOps Tools (5 docs) | Fragmented | Create summary comparison table | +| Game Retrospectives | Deprecated games | Extract generic learnings, archive rest | + +--- + +## Recommended Skill Generation Order + +1. **spyke-unity-client** (most value, good content) +2. **spyke-backend** (after drafts finalized) +3. **spyke-aws** (after drafts finalized) +4. **spyke-onboarding** (after process docs updated) +5. ~~spyke-sdks~~ (skip or merge) +6. ~~spyke-liveops~~ (needs consolidation first) + +--- + +## Implementation Steps + +### Phase 1: Content Cleanup +1. Finalize all 8 draft documents +2. Translate Turkish content to English +3. Delete or populate 20 empty container pages +4. Archive 17 legacy game docs + +### Phase 2: Generate Skills +1. Create unified config for each skill +2. Use Skill Seekers with Confluence scraper (to be built) +3. Generate and package skills + +### Phase 3: Ongoing Maintenance +1. Set up review schedule for docs +2. Add "Last Reviewed" date to each doc +3. Create Confluence template for new docs + +--- + +## Confluence Scraper Feature (New Development) + +To generate skills from Confluence, need to add: + +``` +src/skill_seekers/cli/confluence_scraper.py +``` + +Config format: +```json +{ + "name": "spyke-unity-client", + "type": "confluence", + "domain": "spykegames.atlassian.net", + "space_key": "EN", + "page_ids": ["70811737", "8880129", ...], + "exclude_patterns": ["coin master", "tile busters"], + "auth": { + "email": "$CONFLUENCE_EMAIL", + "token": "$CONFLUENCE_TOKEN" + } +} +``` + +--- + +## Summary + +| Metric | Count | +|--------|-------| +| Total Pages | 147 | +| Ready for Skills | ~80 | +| Need Improvement | ~30 | +| Archive/Delete | ~37 | +| Recommended Skills | 4 | +| Drafts to Finalize | 8 | +| Empty to Fix | 20 | + +--- + +## ACTION CHECKLIST FOR DOC CLEANUP + +### 1. Finalize Drafts (8 docs) +- [ ] [Slot Game X - Architecture (MVCVM) - (Draft)](https://spykegames.atlassian.net/wiki/spaces/EN/pages/63471723) +- [ ] [Backend Code Structure (draft)](https://spykegames.atlassian.net/wiki/spaces/EN/pages/637829184) +- [ ] [Chat Mysql (draft)](https://spykegames.atlassian.net/wiki/spaces/EN/pages/593330177) +- [ ] [Secure AWS CLI Access (DRAFT)](https://spykegames.atlassian.net/wiki/spaces/EN/pages/870744065) +- [ ] [Help Call Backend Notes (Draft)](https://spykegames.atlassian.net/wiki/spaces/EN/pages/695074823) +- [ ] [Submodule [Draft]](https://spykegames.atlassian.net/wiki/spaces/EN/pages/690356267) +- [ ] [Submodule View Management [Draft]](https://spykegames.atlassian.net/wiki/spaces/EN/pages/690126851) +- [ ] [Creating New Team Event (DRAFT)](https://spykegames.atlassian.net/wiki/spaces/EN/pages/759988225) + +### 2. Translate to English (1 doc) +- [ ] [bonanza ve lucky spin bittikten sonra odeme gelmesi sorunsalı](https://spykegames.atlassian.net/wiki/spaces/EN/pages/831324161) + +### 3. Delete or Populate Empty Containers (20 docs) +- [ ] Engineering (root page - add overview) +- [ ] R&D (add overview) +- [ ] Client (add overview or delete) +- [ ] Backend (add overview or delete) +- [ ] AWS notes (add overview or delete) +- [ ] Network Messaging (add overview or delete) +- [ ] Tools (add overview or delete) +- [ ] Cloud Services (add overview or delete) +- [ ] Graphics (add overview or delete) +- [ ] Client Architecture (add overview or delete) +- [ ] Backend Architecture (add overview or delete) +- [ ] Backend Design (add overview or delete) +- [ ] Third Party SDKs (add overview or delete) +- [ ] Tech Talks (add overview or delete) +- [ ] Cheatsheets (add overview or delete) +- [ ] Team (add overview or delete) +- [ ] Game Retrospectives (add overview or delete) +- [ ] Feature Flags / LiveOps Tooling (add overview or delete) +- [ ] How To Add New Special Day Theme Assets (add overview) +- [ ] Replacing Active App Icon On Player Settings (add content - only has link) + +### 4. Archive Legacy Game Docs (17 docs) +Move to "Archive" or "Legacy" section: +- [ ] Coin Master +- [ ] Coin Master Notes +- [ ] Bot - Coin Master +- [ ] Coin Trip Notes +- [ ] Island King +- [ ] Pirate King +- [ ] Learnings From Royal Riches - Client +- [ ] Learnings From Royal Riches - Backend +- [ ] Learnings From Tile Busters - Client +- [ ] Learnings From Tile Busters - Backend +- [ ] How to add new Endless Offers (Tile Busters) +- [ ] Tile Busters Level/AB Update Flow +- [ ] Tile Busters Backend Git Branch/Deployment Cycle +- [ ] Tile Busters Backend Git Branch/Deployment Cycle (v2) +- [ ] Tile Busters Particle Optimizations +- [ ] Automated Play Test for Tile Busters +- [ ] Automated Purchase Testing for Tile Busters + +### 5. Content Improvements (Optional but Recommended) +- [ ] Add code examples to "Scriptable Objects as Architecture" +- [ ] Add URP recommendation to "Built-in (Legacy) vs URP" +- [ ] Consolidate 5 Addressables docs into 1 +- [ ] Add conclusion to "Feature Flag System" +- [ ] Create comparison table in LiveOps Tools + +--- + +## AFTER CLEANUP: Come back and run skill generation + +Once the above items are addressed, return and I will: +1. Build a Confluence scraper for Skill Seekers +2. Generate the 4 recommended skills +3. Package and upload them diff --git a/src/skill_seekers/cli/ai_enhancer.py b/src/skill_seekers/cli/ai_enhancer.py index 6ae5ceb..68438ee 100644 --- a/src/skill_seekers/cli/ai_enhancer.py +++ b/src/skill_seekers/cli/ai_enhancer.py @@ -27,11 +27,19 @@ import logging import os import subprocess import tempfile +from concurrent.futures import ThreadPoolExecutor, as_completed from dataclasses import dataclass from pathlib import Path logger = logging.getLogger(__name__) +# Import config manager for settings +try: + from skill_seekers.cli.config_manager import get_config_manager + CONFIG_AVAILABLE = True +except ImportError: + CONFIG_AVAILABLE = False + @dataclass class AIAnalysis: @@ -65,6 +73,15 @@ class AIEnhancer: self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY") self.client = None + # Get settings from config (with defaults) + if CONFIG_AVAILABLE: + config = get_config_manager() + self.local_batch_size = config.get_local_batch_size() + self.local_parallel_workers = config.get_local_parallel_workers() + else: + self.local_batch_size = 20 # Default + self.local_parallel_workers = 3 # Default + # Determine actual mode if mode == "auto": if self.api_key: @@ -232,20 +249,68 @@ class PatternEnhancer(AIEnhancer): if not self.enabled or not patterns: return patterns - logger.info(f"🤖 Enhancing {len(patterns)} detected patterns with AI...") - - # Batch patterns to minimize API calls (max 5 per batch) - batch_size = 5 - enhanced = [] + # Use larger batch size for LOCAL mode (configurable) + if self.mode == "local": + batch_size = self.local_batch_size + parallel_workers = self.local_parallel_workers + logger.info( + f"🤖 Enhancing {len(patterns)} patterns with AI " + f"(LOCAL mode: {batch_size} per batch, {parallel_workers} parallel workers)..." + ) + else: + batch_size = 5 # API mode uses smaller batches + parallel_workers = 1 # API mode is sequential + logger.info(f"🤖 Enhancing {len(patterns)} detected patterns with AI...") + # Create batches + batches = [] for i in range(0, len(patterns), batch_size): - batch = patterns[i : i + batch_size] - batch_results = self._enhance_pattern_batch(batch) - enhanced.extend(batch_results) + batches.append(patterns[i : i + batch_size]) + + # Process batches (parallel for LOCAL, sequential for API) + if parallel_workers > 1 and len(batches) > 1: + enhanced = self._enhance_patterns_parallel(batches, parallel_workers) + else: + enhanced = [] + for batch in batches: + batch_results = self._enhance_pattern_batch(batch) + enhanced.extend(batch_results) logger.info(f"✅ Enhanced {len(enhanced)} patterns") return enhanced + def _enhance_patterns_parallel(self, batches: list[list[dict]], workers: int) -> list[dict]: + """Process pattern batches in parallel using ThreadPoolExecutor.""" + results = [None] * len(batches) # Preserve order + + with ThreadPoolExecutor(max_workers=workers) as executor: + # Submit all batches + future_to_idx = { + executor.submit(self._enhance_pattern_batch, batch): idx + for idx, batch in enumerate(batches) + } + + # Collect results as they complete + completed = 0 + total = len(batches) + for future in as_completed(future_to_idx): + idx = future_to_idx[future] + try: + results[idx] = future.result() + completed += 1 + if completed % 5 == 0 or completed == total: + logger.info(f" Progress: {completed}/{total} batches completed") + except Exception as e: + logger.warning(f"⚠️ Batch {idx} failed: {e}") + results[idx] = batches[idx] # Return unenhanced on failure + + # Flatten results + enhanced = [] + for batch_result in results: + if batch_result: + enhanced.extend(batch_result) + return enhanced + def _enhance_pattern_batch(self, patterns: list[dict]) -> list[dict]: """Enhance a batch of patterns""" # Prepare prompt @@ -321,20 +386,68 @@ class TestExampleEnhancer(AIEnhancer): if not self.enabled or not examples: return examples - logger.info(f"🤖 Enhancing {len(examples)} test examples with AI...") - - # Batch examples to minimize API calls - batch_size = 5 - enhanced = [] + # Use larger batch size for LOCAL mode (configurable) + if self.mode == "local": + batch_size = self.local_batch_size + parallel_workers = self.local_parallel_workers + logger.info( + f"🤖 Enhancing {len(examples)} test examples with AI " + f"(LOCAL mode: {batch_size} per batch, {parallel_workers} parallel workers)..." + ) + else: + batch_size = 5 # API mode uses smaller batches + parallel_workers = 1 # API mode is sequential + logger.info(f"🤖 Enhancing {len(examples)} test examples with AI...") + # Create batches + batches = [] for i in range(0, len(examples), batch_size): - batch = examples[i : i + batch_size] - batch_results = self._enhance_example_batch(batch) - enhanced.extend(batch_results) + batches.append(examples[i : i + batch_size]) + + # Process batches (parallel for LOCAL, sequential for API) + if parallel_workers > 1 and len(batches) > 1: + enhanced = self._enhance_examples_parallel(batches, parallel_workers) + else: + enhanced = [] + for batch in batches: + batch_results = self._enhance_example_batch(batch) + enhanced.extend(batch_results) logger.info(f"✅ Enhanced {len(enhanced)} examples") return enhanced + def _enhance_examples_parallel(self, batches: list[list[dict]], workers: int) -> list[dict]: + """Process example batches in parallel using ThreadPoolExecutor.""" + results = [None] * len(batches) # Preserve order + + with ThreadPoolExecutor(max_workers=workers) as executor: + # Submit all batches + future_to_idx = { + executor.submit(self._enhance_example_batch, batch): idx + for idx, batch in enumerate(batches) + } + + # Collect results as they complete + completed = 0 + total = len(batches) + for future in as_completed(future_to_idx): + idx = future_to_idx[future] + try: + results[idx] = future.result() + completed += 1 + if completed % 5 == 0 or completed == total: + logger.info(f" Progress: {completed}/{total} batches completed") + except Exception as e: + logger.warning(f"⚠️ Batch {idx} failed: {e}") + results[idx] = batches[idx] # Return unenhanced on failure + + # Flatten results + enhanced = [] + for batch_result in results: + if batch_result: + enhanced.extend(batch_result) + return enhanced + def _enhance_example_batch(self, examples: list[dict]) -> list[dict]: """Enhance a batch of examples""" # Prepare prompt diff --git a/src/skill_seekers/cli/config_manager.py b/src/skill_seekers/cli/config_manager.py index 94ea445..c775af4 100644 --- a/src/skill_seekers/cli/config_manager.py +++ b/src/skill_seekers/cli/config_manager.py @@ -34,6 +34,10 @@ class ConfigManager: }, "resume": {"auto_save_interval_seconds": 60, "keep_progress_days": 7}, "api_keys": {"anthropic": None, "google": None, "openai": None}, + "ai_enhancement": { + "local_batch_size": 20, # Patterns per Claude CLI call (default was 5) + "local_parallel_workers": 3, # Concurrent Claude CLI calls + }, "first_run": {"completed": False, "version": "2.7.0"}, } @@ -378,6 +382,30 @@ class ConfigManager: if deleted_count > 0: print(f"🧹 Cleaned up {deleted_count} old progress file(s)") + # AI Enhancement Settings + + def get_local_batch_size(self) -> int: + """Get batch size for LOCAL mode AI enhancement.""" + return self.config.get("ai_enhancement", {}).get("local_batch_size", 20) + + def set_local_batch_size(self, size: int): + """Set batch size for LOCAL mode AI enhancement.""" + if "ai_enhancement" not in self.config: + self.config["ai_enhancement"] = {} + self.config["ai_enhancement"]["local_batch_size"] = size + self.save_config() + + def get_local_parallel_workers(self) -> int: + """Get number of parallel workers for LOCAL mode AI enhancement.""" + return self.config.get("ai_enhancement", {}).get("local_parallel_workers", 3) + + def set_local_parallel_workers(self, workers: int): + """Set number of parallel workers for LOCAL mode AI enhancement.""" + if "ai_enhancement" not in self.config: + self.config["ai_enhancement"] = {} + self.config["ai_enhancement"]["local_parallel_workers"] = workers + self.save_config() + # First Run Experience def is_first_run(self) -> bool: @@ -443,6 +471,11 @@ class ConfigManager: print(f" • Auto-switch profiles: {self.config['rate_limit']['auto_switch_profiles']}") print(f" • Keep progress for: {self.config['resume']['keep_progress_days']} days") + # AI Enhancement settings + print("\nAI Enhancement (LOCAL mode):") + print(f" • Batch size: {self.get_local_batch_size()} patterns per call") + print(f" • Parallel workers: {self.get_local_parallel_workers()} concurrent calls") + # Resumable jobs jobs = self.list_resumable_jobs() if jobs: