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

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.