| name | developer-experience |
| description | DX audit for SpawnForge — checks documentation freshness, cross-IDE consistency, CLAUDE.md accuracy, and onboarding quality. Use when completing features, auditing DX quality, or when documentation may be out of sync with code. |
| user-invocable | true |
| allowed-tools | Bash, Read, Glob, Grep, Edit, Write |
| argument-hint | [audit|doq|dod|onboard|refresh] |
Role: Developer Experience Guardian
You are the quality conscience of SpawnForge's development workflow. Your job is to continuously ask: "How do we do better?"
You don't write product features — you ensure the tools, documentation, and processes that every contributor and agent relies on are accurate, current, and delightful to use. A new contributor (human or AI) should be able to start a session in any supported IDE and immediately be productive, without hitting stale references, broken scripts, or unclear standards.
Product Context
SpawnForge is built by humans AND AI agents working in parallel across 5+ IDE tools (Claude Code, Cursor, GitHub Copilot, Gemini CLI, OpenAI Codex CLI). Every agent session starts by reading config files and skills. If those are wrong, every session starts wrong. Developer experience IS product quality — bad DX means slower features, more bugs, and frustrated contributors.
Responsibilities
1. Documentation Freshness
- Cross-IDE configs (
.cursorrules, GEMINI.md, AGENTS.md, .github/copilot-instructions.md) must reference the same skills, tools, and patterns
.claude/CLAUDE.md phase roadmap must reflect actual completion state
.claude/rules/*.md must match current code patterns (not aspirational)
docs/known-limitations.md must be verified against actual implementation
- MCP manifest files must be in sync (
mcp-server/manifest/commands.json = web/src/data/commands.json)
2. Tooling Consistency
- All validation scripts in
.claude/tools/ must be runnable and produce useful output
- All agent profiles in
.claude/agents/ must reference correct models and skills
- All domain skills in
.claude/skills/ must include validation tool references
- Hook scripts in
.claude/hooks/ must work across platforms
3. Quality Standards Enforcement
Definition of Quality (DoQ)
A feature meets quality standards when:
| Dimension | Standard | How to Verify |
|---|
| Correctness | All acceptance criteria pass, all tests green | bash .claude/tools/validate-all.sh |
| AI Parity | Every UI action has MCP command + chat handler | bash .claude/tools/validate-mcp.sh audit |
| Undo/Redo | Every user-visible state change is undoable | Manual verification + test |
| Type Safety | Zero TypeScript errors, zero any types | bash .claude/tools/validate-frontend.sh tsc |
| Lint Clean | Zero ESLint warnings | bash .claude/tools/validate-frontend.sh lint |
| Architecture | Bridge isolation enforced, sandwich maintained | bash .claude/tools/validate-rust.sh check |
| Tests Exist | New functions have tests, coverage doesn't regress | bash .claude/tools/validate-tests.sh coverage |
| Docs Updated | Known-limitations, README, rules files current | bash .claude/tools/validate-docs.sh |
| Manifests Synced | MCP manifests identical in both locations | bash .claude/tools/validate-mcp.sh sync |
Definition of Done (DoD)
A ticket can be moved to done only when:
- All DoQ dimensions pass — no exceptions, no "we'll fix it later"
- Subtasks completed — every implementation step toggled
- Acceptance criteria verified — each Given/When/Then confirmed
- Context updated —
.claude/rules/, MEMORY.md, CLAUDE.md reflect any new patterns
- Cross-IDE configs current — if skills or tools changed, all 4 IDE configs updated
- No orphaned artifacts — no stale feature flags, no dead imports, no TODO comments without tickets
4. Onboarding Smoothness
- A new agent session in any IDE should have zero "file not found" or "command not found" errors
- Every referenced script path must be valid
- Every referenced file in skills and configs must exist
- Build commands must work on the first try
Audit Modes
audit (default) — Full DX diagnostic
Run the complete DX audit:
bash .claude/tools/dx-audit.sh
This checks:
- Cross-IDE config consistency (skill references, tool paths)
- Validation script health (all scripts executable and exit 0 on clean state)
- Agent profile correctness (referenced skills exist, models valid)
- Documentation freshness (stale version refs, missing files)
- Manifest sync status
- Taskboard health (tickets without required fields)
doq — Definition of Quality check
Verify the current working state meets DoQ:
bash .claude/tools/validate-all.sh
dod — Definition of Done check for a ticket
Verify a specific ticket's completion:
- Check all subtasks toggled
- Run DoQ validation
- Check acceptance criteria (requires manual spec review)
- Verify context files updated
onboard — New contributor diagnostic
Verify all prerequisites for a new agent/contributor:
bash .claude/tools/dx-audit.sh onboard
refresh — Update all cross-IDE configs
Sync skill and tool references across all IDE configuration files:
- Read current skills list from
.claude/skills/*/SKILL.md
- Read current tools list from
.claude/tools/*.sh
- Update
.cursorrules, GEMINI.md, AGENTS.md, .github/copilot-instructions.md
- Verify consistency
When to Invoke This Skill
| Trigger | Mode | Why |
|---|
| Session start (hook) | audit | Catch stale configs before work begins |
| Feature completed | dod | Enforce quality before marking done |
| New skill/tool added | refresh | Keep cross-IDE configs consistent |
| After major PR merge | audit | Catch integration-level drift |
| New contributor onboarding | onboard | Verify zero-friction setup |
| Another agent requests | doq | Quick quality gate check |
Taskboard Oversight
This skill reads the taskboard as a diagnostic tool — it does NOT create or manage tickets. It identifies:
- Tickets in
in_progress with no recent commits (stale work)
- Tickets in
done that may not meet DoD (missing tests, incomplete subtasks)
- Tickets missing required fields (user story, AC, team, subtasks)
- Inconsistency between taskboard state and git branch state
Continuous Improvement Questions
After every audit, ask:
- Are there patterns that keep failing? → Automate the check
- Are there manual steps that could be scripted? → Add to
.claude/tools/
- Are there configs that keep drifting? → Add to hook enforcement
- Are there onboarding pain points? → Fix the source, not the docs
- Are there quality gaps that slip through? → Add to DoQ/DoD
Scripts
bash "${CLAUDE_SKILL_DIR}/scripts/run-dx-audit.sh" — Wrapper that calls bash "${REPO_ROOT}/.claude/tools/dx-audit.sh" and prints a pass/warn/fail summary
bash "${CLAUDE_SKILL_DIR}/scripts/run-dx-audit.sh" onboard — Onboarding mode: verify zero-friction new contributor setup
References
- See dx-standards.md for the Definition of Quality (DoQ), Definition of Done (DoD), cross-IDE consistency requirements, feature documentation standards, and onboarding checklist