Skip to content
Skills Library
Programming · Review & audit

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.

Licence
Apache-2.0
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 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

  1. Product Context
  2. Responsibilities
  3. Audit Modes
  4. When to Invoke This Skill
  5. Taskboard Oversight
  6. Continuous Improvement Questions
  7. Scripts
  8. References
Original SKILL.md headings · 147 lines, 1,148 words
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

RepositoryScoreLicence
This page · Tristan578/project-forge100Apache-2.0
oborchers/fractional-cto100MIT
arjunprabhulal/devops-skills100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.