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 build

Integration 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 GREEN

Skill 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

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.

starwards-workflow