Starwards Development Workflow
Overview
This is the master index for all Starwards Claude skills. Use this to understand the complete development workflow and when to activate each skill.
Skill Map
┌─────────────────────────────────────────────────────────────────┐
│ STARWARDS WORKFLOW │
└─────────────────────────────────────────────────────────────────┘
┌──────────────┐
│ NEW TASK │
└──────┬───────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. PLANNING PHASE │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ │
│ │ writing-plans │───────▶│ executing-plans │ │
│ │ (if complex) │ │ (batch execution)│ │
│ └─────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. DEVELOPMENT PHASE (Red-Green-Refactor) │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ starwards-tdd │ │
│ │ • Write failing test (RED) │ │
│ │ • Verify it fails correctly │ │
│ │ • Minimal implementation (GREEN) │ │
│ │ • Verify it passes │ │
│ │ • Refactor & repeat │ │
│ └──────────────────────────────────────────────┘ │
│ │ │
│ │ (if test fails unexpectedly) │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ starwards-debugging │ │
│ │ Phase 1: Root cause investigation │ │
│ │ Phase 2: Pattern analysis │ │
│ │ Phase 3: Hypothesis testing │ │
│ │ Phase 4: Implementation │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. VERIFICATION PHASE │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ starwards-verification │ │
│ │ • npm run test:types (TypeScript) │ │
│ │ • npm run test:format (ESLint/Prettier) │ │
│ │ • npm run build (all modules) │ │
│ │ • npm test (unit/integration) │ │
│ │ • npm run test:e2e (Playwright) │ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. COMPLETION PHASE │
│ │
│ • Git commit with descriptive message │
│ • Push to feature branch │
│ • Create PR (if ready) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ SUPPORTING SKILLS (use as needed throughout) │
│ │
│ ┌──────────────────┐ ┌─────────────────┐ ┌────────────────┐│
│ │starwards-monorepo│ │starwards-colyseus│ │using-superpowers│
│ │Build order │ │@gameField │ │Skill discovery │ │
│ │3-terminal setup │ │State sync │ │Mandatory use │ │
│ │Module deps │ │JSON Pointer │ │Announcements │ │
│ └──────────────────┘ └─────────────────┘ └────────────────┘│
└─────────────────────────────────────────────────────────────────┘Skills Quick Reference
| Skill | When to Use | Key Activities |
|---|---|---|
| using-superpowers | Start of ANY conversation | Check for relevant skills, announce usage |
| writing-plans | Complex multi-step feature | Create detailed implementation roadmap |
| executing-plans | Following a plan | Batch execution with checkpoints |
| starwards-tdd | Implementing ANY feature/fix | Write test first, RED-GREEN-REFACTOR |
| starwards-debugging | Encountering bugs/failures | 4-phase systematic root cause analysis |
| starwards-ci-debugging | GitHub Actions CI failures | Install gh CLI, download logs, analyze errors |
| starwards-verification | Before claiming "done" | Run full test suite, verify evidence |
| starwards-monorepo | Build issues, workspace setup | Understand module dependencies, build order |
| starwards-colyseus | State sync issues, multiplayer | @gameField patterns, room architecture |
Common Workflows
Workflow 1: New Ship System
1. using-superpowers → Announce using starwards-tdd
2. starwards-monorepo → Ensure core watch mode running (Terminal 1)
3. starwards-tdd:
a. Write unit test (modules/core/test/shield.spec.ts) → RED
b. Implement system (modules/core/src/ship/shield.ts) → GREEN
c. Add to ShipState with @gameField
d. Write integration test with ShipTestHarness → RED
e. Create manager, add to update loop → GREEN
4. starwards-colyseus → Verify @gameField decorator order
5. starwards-verification → Run npm test, npm run build
6. Commit: "feat: add shield system with recharge mechanics"Workflow 2: UI Widget
1. using-superpowers → Announce using starwards-tdd
2. starwards-monorepo → Ensure all 3 terminals running
3. starwards-tdd:
a. Write E2E test (modules/e2e/test/shield-widget.spec.ts) → RED
b. Create widget (modules/browser/src/widgets/shield.ts) → GREEN
c. Register in Dashboard
d. Test with data-id selector
4. starwards-verification → Run npm run test:e2e
5. Commit: "feat: add shield status widget to engineering screen"Workflow 3: Bug Fix
1. starwards-debugging:
Phase 1: Investigate (read error, reproduce, check changes)
Phase 2: Pattern analysis (find working examples, compare)
Phase 3: Hypothesis (form single hypothesis, test minimally)
Phase 4: Implementation (see step 2 below)
2. starwards-tdd:
a. Write failing test reproducing bug → RED
b. Implement fix → GREEN
3. starwards-verification → Full test suite
4. Commit: "fix: shield strength not syncing to clients"Workflow 4: Multiplayer Feature
1. starwards-colyseus → Review state sync patterns
2. starwards-tdd:
a. Write MultiClientDriver test → RED
b. Add @gameField to state
c. Implement command handler
d. Test with 2+ clients → GREEN
3. starwards-verification → npm test, npm run test:e2e
4. Commit: "feat: multi-crew shield power distribution"Workflow 5: Monorepo Build Issues
1. starwards-debugging → Phase 1: Check which module failing
2. starwards-monorepo:
- Verify build order (core → others)
- Check if core watch mode running
- Try fresh build: npm run clean && npm run build
3. If still broken → starwards-debugging Phase 2-4
4. starwards-verification → Verify clean buildIntegration Matrix
| From Skill | To Skill | When |
|---|---|---|
| using-superpowers | ANY | Start of conversation |
| writing-plans | executing-plans | Plan complete, ready to implement |
| executing-plans | starwards-tdd | Implementing each task in plan |
| starwards-tdd | starwards-debugging | Test fails unexpectedly |
| starwards-debugging | starwards-tdd | Found root cause, write test for fix |
| starwards-tdd | starwards-verification | Implementation complete |
| starwards-verification | (commit) | All checks pass |
| starwards-monorepo | starwards-tdd | Setting up dev environment |
| starwards-colyseus | starwards-tdd | Implementing state sync feature |
| starwards-colyseus | starwards-debugging | State sync not working |
Skill Dependencies
using-superpowers (master skill)
├─→ ALL other skills
starwards-tdd
├─→ starwards-monorepo (understand build workflow)
├─→ starwards-colyseus (when testing state sync)
└─→ starwards-debugging (when tests fail)
starwards-debugging
├─→ starwards-tdd (write test for fix)
├─→ starwards-monorepo (debug build issues)
└─→ starwards-colyseus (debug state sync)
starwards-verification
├─→ starwards-monorepo (understand test commands)
└─→ starwards-tdd (verification patterns)MANDATORY First Response Protocol
Before responding to ANY user message:
- ☐ Check: Does this match any skill?
- ☐ Read: Use Skill tool to load relevant skill
- ☐ Announce: "I'm using [Skill Name] to [task]"
- ☐ Follow: Execute skill instructions exactly
Example:
User: "Add a new cloaking device system to ships"
Claude:
1. Checks skills → starwards-tdd matches (implementing new feature)
2. Reads starwards-tdd skill
3. Announces: "I'm using starwards-tdd to implement the cloaking device"
4. Follows TDD cycle: write test → verify RED → implement → verify GREENSkill Activation Triggers
| User Says | Activate Skill |
|---|---|
| "Add X", "Implement Y", "Create Z" | starwards-tdd |
| "Fix bug", "X is broken", "Not working" | starwards-debugging |
| "Is it done?", "Does it work?", "Can I commit?" | starwards-verification |
| "Build fails", "Can't find module", "Import error" | starwards-monorepo |
| "State not syncing", "@gameField issue" | starwards-colyseus |
| "Plan out X", "How should I implement Y?" | writing-plans |
| "Follow this plan..." | executing-plans |
Version History
- 2025-11-04: Initial workflow master index created
Related Documentation
- CLAUDE.md - Quick reference for AI assistants
- docs/DEVELOPMENT.md - Development setup
- docs/testing/README.md - Testing guide
- docs/PATTERNS.md - Code patterns
Quick Links
Skills:
- using-superpowers.md - Master skill activation
- starwards-tdd.md - Test-driven development
- starwards-debugging.md - Systematic debugging
- starwards-verification.md - Verification commands
- starwards-monorepo.md - Monorepo workflow
- starwards-colyseus.md - Multiplayer patterns
- writing-plans.md - Planning complex features
- executing-plans.md - Plan execution
The Bottom Line
Development workflow in 4 steps:
- Plan (if complex) → writing-plans
- Develop (always) → starwards-tdd (RED-GREEN-REFACTOR)
- Verify (always) → starwards-verification (full test suite)
- Commit → git commit & push
When stuck:
- Bug/failure → starwards-debugging (4 phases)
- Build issue → starwards-monorepo (check dependencies)
- State sync → starwards-colyseus (check @gameField)
Remember: using-superpowers is MANDATORY at start of every conversation.