refactor(outfitter): restructure skills with workflow files

[galligan]

refactor(outfitter): restructure skills with workflow files

Migrate skills to modular workflow-based format:

• Compact SKILL.md with routing logic
• Separate workflow files for detailed guides
• XML-style tags for structure (, , etc.)

Affected skills:

• claude-commands: v2.0.0 → v3.0.0
• typescript-dev: adds workflows/ directory

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

refactor(outfitter): add router pattern to debugging and tdd skills

• debugging: 326 → 135 lines (59% reduction)
• tdd: 358 → 169 lines (53% reduction)
• Add 4 workflows each: stage-based for debugging, phase-based for tdd
• Add intake questions and routing tables to both skills

Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com

[galligan]

• refactor(skills): add lifecycle workflows to domain skills #52
• refactor(agents): expand under-specified agent prompts #51
• refactor(outfitter): restructure skills with workflow files #50 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Skills Restructure with Workflow Files

Summary

This is an excellent refactoring that significantly improves the maintainability and usability of the Outfitter skills. The migration to a modular workflow-based format with router patterns is well-executed.

---

✅ Strengths

1. Architecture & Design

• Progressive disclosure pattern: The new structure with compact SKILL.md files and separate workflow files is excellent. This reduces cognitive load and allows users to dive deeper only when needed.
• Router pattern: The <intake> and <routing> sections provide clear entry points and decision trees. This is particularly well-done in all modified skills.
• Consistency: All four skills follow the same structural pattern, making them predictable and easy to navigate.

2. Code Quality

• Significant reduction in complexity:
  • debugging: 326 → 135 lines (59% reduction)
  • tdd: 358 → 169 lines (53% reduction)
  • claude-commands: 351 → 78 lines (78% reduction in main file)
• Clear separation of concerns: Router logic separate from detailed workflows
• Well-structured workflows: Each workflow file (e.g., collect-evidence.md, red-phase.md) has consistent sections: <when_to_use>, <process>, <success_criteria>, <next_steps>

3. Documentation

• Excellent use of XML-style tags: <intake>, <routing>, <rules>, <references> provide clear structure
• Action-oriented content: activeForm fields ("Collecting evidence", "Writing failing test") are well-chosen
• Clear success criteria: Each workflow includes checkboxes for completion verification
• Good anti-patterns sections: Help users avoid common mistakes

4. User Experience

• Stage tracking integration: References to maintain-tasks skill for progress tracking
• Red flags sections: Help users self-correct (e.g., debugging's "STOP and return to Stage 1 if...")
• Quick reference sections: Bash commands, TypeScript patterns readily available
• Version bumps: Appropriate major version bumps (v2→v3 for breaking changes)

---

🔍 Observations & Minor Suggestions

1. Missing Changeset

According to .claude/rules/changesets.md, this PR should include a changeset since it includes breaking changes (major version bumps):

• claude-commands: v2.0.0 → v3.0.0
• debugging: v2.x → v3.0.0
• tdd: v2.x → v3.0.0

Recommendation: Add a changeset:

bun changeset
# Select: outfitter (major)
# Summary: Restructure skills with workflow-based router pattern

2. Consistency in Formatting

The skills follow .claude/rules/FORMATTING.md well with XML tags and structural consistency. One minor note:

• Some workflow files use ## Step N while the main SKILL.md files use <tags> - this is actually good (different scopes), but worth noting for future contributors.

3. Reference File Validation

The <references> sections reference many supporting files that aren't visible in this PR:

• references/evidence-patterns.md
• references/test-patterns.md
• references/zod-integration.md
• etc.

Question: Do these reference files exist? If not, they should be created or the references should be removed to avoid broken links.

4. Testing Coverage

This refactoring doesn't include test coverage for the skills themselves. While skills are instruction-based (not code), consider:

• Validation scripts to check YAML frontmatter
• Linting for broken reference links
• Example validation tests

---

🛡️ Security & Performance

No concerns identified. This is purely documentation/instruction refactoring with no security implications.

---

📊 Metrics

Metric	Before	After	Change
Total files	4	22	+18 workflow/ref files
Lines added	-	3,215	-
Lines deleted	-	1,173	-
Net change	-	+2,042	Detailed workflows
Skill.md avg	~334 lines	~113 lines	66% reduction

---

✅ Recommendations

1. Add changeset (as noted above) ← Blocking for release
2. Verify reference files exist - ensure all referenced references/*.md and examples/*.md files are present
3. Consider adding:
   • A migration guide for users of v2 skills
   • Validation scripts for skill structure
4. Future: Consider extracting the router pattern itself into a meta-skill or template for future skill authors

---

🎯 Verdict

Approve with minor action items. This is high-quality work that significantly improves the skill system's maintainability and usability. The only blocking item is the missing changeset for proper version management.

The refactoring demonstrates strong architectural thinking with the progressive disclosure pattern and router abstraction. The consistency across all modified skills makes this a solid foundation for future skill development.

Great work! 🚀

---

Action Items:

• Add changeset for version tracking
• Verify all referenced files exist
• Consider adding migration guide (optional)