firefrost-gaming/skill-seekers-reference
3
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore: Post-merge cleanup - remove client docs and fix linter errors

Browse Source 
- Remove SPYKE-related client documentation files
- Fix critical ruff linter errors:
  - Remove unused 'os' import in test_analyze_e2e.py
  - Remove unused 'setups' variable in test_test_example_extractor.py
  - Prefix unused output_dir parameter in codebase_scraper.py
  - Fix import sorting in test_integration.py
- Update CHANGELOG.md with comprehensive PR #272 feature documentation

These changes were part of PR #272 cleanup but didn't make it into the squash merge.
This commit is contained in:
yusyus
2026-01-31 14:58:09 +03:00
parent aa57164d34
commit 86e77e2a30
8 changed files with 68 additions and 1442 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
docs/plans/SPYKE_INTEGRATION_NOTES.md
View File

@@ -1,265 +0,0 @@
# 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

774
docs/plans/SPYKE_SKILL_AGENT_PROPOSAL.md
View File

@@ -1,774 +0,0 @@
# 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