skill-seekers-reference/docs/plans/SPYKE_SKILL_AGENT_PROPOSAL.md

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:

## 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:

## 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

await PlayAnimation();
UpdateState();  // UNSAFE: State may have changed during await

Fix: Add cancellation check before state modification:

await PlayAnimation();
if (_levelCts.Token.IsCancellationRequested) return;
UpdateState();

WARN: Event Subscribe Without Unsubscribe

ThreadCutterController.cs:45

_gridController.OnCellChanged += HandleCellChanged;

Fix: Add unsubscribe in Dispose():

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

## 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