starwards Starwards Development Workflow
Overview
This is the master index for all Starwards Codex 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"
Codex:
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
- AGENTS.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.