developer-experience
/developer-experience
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.
- Author
- Tristan578 ↗
- Repository
- project-forge ↗
- Licence
- Apache-2.0
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/run-dx-audit.sh
What it does and when to use it
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.
Arguments
/developer-experience [audit|doq|dod|onboard|refresh]
Original author 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.
How it works
- Product Context
- Responsibilities
- Audit Modes
- When to Invoke This Skill
- Taskboard Oversight
- Continuous Improvement Questions
- Scripts
- References
SKILL.md preview
---
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
- `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
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
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
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:
```bash
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
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](references/dx-standards.md) for the Definition of Quality (DoQ), Definition of Done (DoD), cross-IDE consistency requirements, feature documentation standards, and onboarding checklist
Files in this package (3)
- SKILL.md 8 KB
- references/dx-standards.md 7 KB
- scripts/run-dx-audit.sh 3 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Tristan578/project-forge | 100 | Apache-2.0 |
| oborchers/fractional-cto | 100 | MIT |
| arjunprabhulal/devops-skills | 100 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version bcc456d91daa (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90review-documentation
Reviews the accuracy and writing quality of documentation. Use when reviewing doc changes in a diff, checking a new or edited page, or auditing the documentation of a codebase. - 100docs
Write, update, and review SpawnForge docs — README, known-limitations, API references, user-facing copy, CLAUDE.md, and MCP command descriptions. Use when writing docs, reviewing doc quality (PASS/FAIL), or auditing for stale references. - 100tooling-engineer
Use this agent when you need to build or enhance developer tools including CLIs, code generators, build tools, and IDE extensions. - 100pr-code-review
Review a PR for SpawnForge bugs, security issues, and regressions. Posts inline GitHub comments with severity markers. Use when asked to "review PR", "code review", or "check this PR". Invoke with /pr-code-review <PR number>. - 100repo-consistency
Checks documentation consistency across the repository. Use when user asks to "check consistency", "are the documents consistent", "is everything aligned", "verify documentation", or "/repo-consistency". - 100dx-optimizer
Improve developer experience and tooling. Use when setting up projects or reducing friction.