starwards-workflow

name	starwards-workflow
description	Master index for Starwards development workflow - shows when to use each skill, workflow diagram, and how skills integrate together
version	"2025-11-05T00:00:00.000Z"
author	Claude (based on Starwards project analysis)
related_skills	["using-superpowers","starwards-tdd","starwards-debugging","starwards-ci-debugging","starwards-verification","starwards-monorepo","starwards-colyseus","writing-plans","executing-plans"]

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:

1. ☐ Check: Does this match any skill?
2. ☐ Read: Use Skill tool to load relevant skill
3. ☐ Announce: "I'm using [Skill Name] to [task]"
4. ☐ 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:

1. Plan (if complex) → writing-plans
2. Develop (always) → starwards-tdd (RED-GREEN-REFACTOR)
3. Verify (always) → starwards-verification (full test suite)
4. 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.