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
• README.md feature claims must reflect actual completion state (.claude/CLAUDE.md deliberately carries no status summary — see .claude/skills/docs/SKILL.md)
• .claude/rules/*.md must match current code patterns (not aspirational)
• docs/known-limitations.md must be verified against actual implementation
• All THREE MCP manifest copies must be in sync — mcp-server/manifest/commands.json (source) = web/src/data/commands.json = apps/docs/data/commands.json (one copy per deploy root)

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 manifest identical in all 3 locations	bash .claude/tools/validate-mcp.sh sync

Definition of Done (DoD)

A ticket can be moved to done only when:

1. All DoQ dimensions pass — no exceptions, no "we'll fix it later"
2. Subtasks completed — every implementation step toggled
3. Acceptance criteria verified — each Given/When/Then confirmed
4. Context updated — .claude/rules/, MEMORY.md, CLAUDE.md reflect any new patterns
5. Cross-IDE configs current — if skills, agents, hooks or tools changed, every provider config is updated AND the generated Codex CLI surface is regenerated (refresh below); bash .claude/tools/dx-audit.sh runs all three gates CI's Agentic Config Sync job runs (step 5 of refresh lists them)
6. 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:

1. Check all subtasks toggled
2. Run DoQ validation
3. Check acceptance criteria (requires manual spec review)
4. 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:

1. Read current skills list from .claude/skills/*/SKILL.md
2. Read current tools list from .claude/tools/*.sh
3. Update the hand-written provider configs: .cursorrules, GEMINI.md, AGENTS.md, .github/copilot-instructions.md
4. Regenerate the mirror other assistants read. .agents/skills/, .codex/agents/ and .codex/hooks.json are GENERATED from .claude/ — never hand-edit them:

   git add .claude/skills .claude/agents   # only files git TRACKS are mirrored; a new one is reported as `untracked:` until staged
   node tools/agentic-sync/port.mjs --write

   Commit what it regenerates together with the source change.
5. Verify consistency — the three gates CI's Agentic Config Sync job runs:

   bash scripts/check-agentic-sync.sh && bash scripts/check-codex-port.sh && bash scripts/check-copilot-hooks.sh

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, or a skill/agent/hook edited	refresh	Keep provider configs consistent and the generated Codex mirror in sync — a stale mirror fails Agentic Config Sync in CI
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:

1. Are there patterns that keep failing? → Automate the check
2. Are there manual steps that could be scripted? → Add to .claude/tools/
3. Are there configs that keep drifting? → Add to hook enforcement
4. Are there onboarding pain points? → Fix the source, not the docs
5. 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