Devwork Skills

A structured feature development workflow for Claude Code. Each skill is a phase — run them in order.

Installation

Pick one of the two options below. Do not use both at the same time — having the same skills loaded from two locations will cause conflicts.

Option A: Add as an additional directory (recommended)

Clone this repo and register it in your Claude Code settings. Skills stay in the repo so you can git pull to update.

1. Clone the repo:

   git clone ssh://git@git.wihslon.com:2222/jbr870/devwork-skills.git ~/devwork-skills
   

2. Add to ~/.claude/settings.json:

   {
     "permissions": {
       "additionalDirectories": [
         "/home/<your-username>/devwork-skills"
       ]
     }
   }
   

   If additionalDirectories doesn't grant access on your platform (known issue), use a shell alias instead:

   alias claude='claude --add-dir ~/devwork-skills'
   

3. Restart Claude Code. Skills are loaded automatically.

Option B: Copy into your skills folder

Copy the skill folders directly into any .claude/skills/ directory (e.g. ~/.claude/skills/ for global, or <project>/.claude/skills/ for project-scoped):

cp -r devwork-skills/.claude/skills/* ~/.claude/skills/

This gives you:

~/.claude/skills/
  _shared/
  setup/
  git-worktrees/
  requirements/
  technical-plan/
  develop/
  simplify-report/
  code-review/
  fix/
  e2e-validate/
  e2e-tests/
  a11y-validate/
  a11y-tests/
  api-validate/
  api-tests/
  security-validate/
  api-security-test/
  closeout/
  integrate/
  worktree-cleanup/

Restart Claude Code after copying. Note: you won't get updates automatically — you'll need to re-copy after pulling new changes.

Workflow

/setup → /git-worktrees → /requirements → /technical-plan → /develop
  → /simplify → /simplify-report → /code-review → /fix
  → /e2e-validate → /e2e-tests
  → /a11y-validate → /a11y-tests
  → /api-validate → /api-tests
  → /security-validate → /api-security-test
  → /closeout → /integrate → /worktree-cleanup

Planning & implementation

#	Skill	What it does	Output
0	/setup	Interactive project setup — validates CLAUDE.md, detects workspace layout (mono/multirepo), checks tooling, fills gaps	readiness-report.md
1	/git-worktrees	Create an isolated worktree + branch for the feature	Worktree with deps installed, env files copied
2	/requirements	Readiness guard + guided requirements gathering	Approved PREQ.md
3	/technical-plan	Codebase analysis, approach selection, expert review, SREQ decomposition	plan.md + sreqs/SR-XXX.md files
4	/develop	Parallel agent teams implement SREQs via TDD	Implemented code, UAT approval

QA suite

Run after /develop. Each validate/test pair is sequential (validate produces the report, tests generates scripts from it), but the pairs themselves are independent.

#	Skill	What it does	Output
5a	/simplify	Review changed code for reuse, quality, and efficiency, then fix issues	Simplified code
5b	/simplify-report	Document what /simplify changed for devwork traceability	simplify-report.md
5c	/code-validate	Code validation — Dependency Verifier, Bug Hunter, Static Security, Spec Checker agents	code-report.md
5d	/code-fix	Fix verified issues from /code-validate	Clean code-report.md
5e	/e2e-validate	Walk through test scenarios in the browser via Playwright MCP	e2e-report.md + e2e-journal.md
5f	/e2e-tests	Generate Playwright regression test scripts from validation artifacts	e2e/<feature>.spec.ts
5g	/a11y-validate	WCAG compliance, keyboard nav, ARIA, focus management, color contrast	a11y-report.md + a11y-journal.md
5h	/a11y-tests	Generate accessibility regression tests using @axe-core/playwright	e2e/<feature>.a11y.spec.ts
5i	/api-validate	Validate API endpoints — status codes, payloads, error handling, contracts	api-report.md + api-journal.md
5j	/api-tests	Generate API regression test scripts from validation results	API test files
5k	/security-browser-validate	Browser-level security — XSS, CSRF, auth bypass, headers, data exposure	security-browser-report.md + security-browser-journal.md
5l	/security-api-validate	API-level security — auth enforcement, IDOR, injection, rate limiting	security-api-report.md + security-api-journal.md

Wrap-up

#	Skill	What it does	Output
6	/closeout	Traceability matrix, MR description, learning analysis	Documentation artifacts + CLAUDE.md improvements
7	/integrate	Rebase onto integration branch, test, fast-forward merge	Feature merged into develop/staging
8	/worktree-cleanup	Remove worktree, branches, and per-worktree databases	Clean slate

Each skill picks up from the previous one's disk artifacts. No state is passed between them.

Human gates

You'll be asked to approve at three points:

1. PREQ approval (after /requirements) — confirm the requirements before planning
2. Plan approval (after /technical-plan) — confirm the approach before implementation
3. UAT (after /develop) — test the feature before closing out

Prerequisites

Run /setup first on any new project. It interactively checks and configures everything below:

• CLAUDE.md in your project root with: tech stack, test/lint commands, git conventions, devwork root path. /setup analyzes the codebase and helps create or fill gaps.
• Workspace layout — monorepo or multirepo (with repos: directive in CLAUDE.md). /setup auto-detects child git repositories and prompts to configure.
• Agent Teams — required for /develop and /code-review (parallel multi-agent work). See Enabling Agent Teams below.
• Sandbox environment recommended (devcontainer/Docker) since /develop runs agents with --permission-mode=dontAsk. Use a Debian-based image (e.g. bookworm) — Alpine is musl-based and Playwright browser binaries may not work reliably on it. /setup will warn if it detects Alpine.
• Playwright MCP — the QA validation skills (/e2e-validate, /a11y-validate, /security-validate) require the Playwright MCP server. Configure it in your project's .mcp.json with --headless (recommended — prevents the browser window from stealing focus, and required in environments without a display):

  {
    "mcpServers": {
      "playwright": {
        "command": "npx",
        "args": ["@playwright/mcp@latest", "--browser", "chromium", "--headless"]
      }
    }
  }
  

• @playwright/test — the test generation skills (/e2e-tests, /a11y-tests) produce scripts that import @playwright/test. Install it as a dev dependency: npm install --save-dev @playwright/test.
• Devwork templates at $DEVWORK_ROOT/templates/ (preq-template.md, sreq-template.md). /setup offers to create defaults if missing.

Subsequent skills check for the readiness report ($DEVWORK_ROOT/readiness-report.md) and will stop with a prompt to run /setup if it's missing or stale.

Enabling Agent Teams

Several skills (/develop, /code-review) use Agent Teams — an experimental Claude Code feature that lets a lead agent coordinate multiple teammate agents working in parallel. For example, /develop spawns one teammate per SREQ, and /code-review spawns Bug Hunter, Security Reviewer, and Spec Checker agents simultaneously.

To enable Agent Teams, add the following to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Restart Claude Code after making this change.

How it works

• A team lead (the orchestrating Claude session) creates a team and spawns teammates — separate Claude instances that run autonomously.
• Teammates communicate via an inbox/messaging system (the SendMessage tool).
• Team state persists in ~/.claude/teams/<team-name>/ with config and per-member inboxes, so work survives across sessions.
• Teammates iterate until their task is truly complete, signaling done via a completion promise the team lead waits on.

Typical team compositions

Skill	Teammates	Purpose
/develop	One dev agent per SREQ + optional fix agent	Parallel TDD implementation of sub-requirements
/code-review	Bug Hunter, Security Reviewer, Spec Checker	Static analysis from three perspectives

Notes

• /git-worktrees and /worktree-cleanup are bookends — use them if you want branch isolation, but they're not mandatory for the core flow.
• You can skip /git-worktrees and just work on a feature branch directly.
• /integrate expects a develop or staging branch. Configure integration_branch in CLAUDE.md if yours is named differently.
• The _shared/ folder contains common procedures (workspace resolution, readiness guard) used by all skills. Don't remove it.
• /setup can also be re-run at any time to update your project configuration. If CLAUDE.md changes after setup, the readiness guard in other skills will detect the staleness and ask you to re-run /setup.