CLAUDE.md · git:20261116.75ffff6 · 2026-11-16 · sha256 f56e953abbe690ed
CLAUDE.md git:20261116.75ffff6A
Immutable. This exact content never changes and is served at /api/v1/blob/f56e953abbe690ed.
# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Repository Overview This is `claude-swe-workflows`, a Claude Code plugin for software engineering workflows. It provides skills and agents that extend Claude Code's capabilities for systematic development. ## Plugin Structure ``` ├── .claude-plugin/ │ ├── marketplace.json # Marketplace manifest (lists plugins for installation) │ └── plugin.json # Plugin metadata (name, version, description, license) ├── agents/ # Agent definitions │ └── agent-name.md # Agent prompt with YAML frontmatter ├── skills/ # Skill definitions │ └── skill-name/ │ ├── SKILL.md # Skill prompt with YAML frontmatter │ └── references/ │ └── README.md # Human guide: when to use, what to expect (not the steps) ├── references/ # Cross-cutting reference and discipline docs │ ├── autonomy.md # Discipline for skills that act on granted authority │ ├── think.md # Design discipline for the /think-* namespace │ └── ... ├── scripts/ │ └── lint.py # Mechanical checks run by `make lint` and CI ├── .gitea/workflows/ # CI: runs `make lint` ├── Makefile ├── CHANGELOG.md ├── CONTRIBUTING.md └── README.md ``` ## Development Test the plugin locally: ```bash claude --plugin-dir . ``` The installed plugin runs this checkout, so changes made in a worktree are not live until merged. Test a branch with `claude --plugin-dir <worktree>`. Check your changes before committing: ```bash make lint ``` `make lint` (`scripts/lint.py`, standard library only) checks: - frontmatter: `name`, `description`, and a lowercase `model`; a skill's `name` matches its directory; - descriptions of at most 300 characters; - files under `skills/`, `agents/`, and `references/` of at most 500 lines; - markdown tables padded so their rows are the same width; - every agent and skill a doc cites exists. Removed skills may be named only on history lines: ones that cite "v12", "formerly", or "(now `/...`)". CHANGELOG.md is exempt; - no orphan agents. CI (`.gitea/workflows/lint.yml`) runs `make lint` on every push to master and on every pull request. ## Writing Skills and Agents **Skills** (in `skills/*/SKILL.md`): - YAML frontmatter: `name`, `description`, `model` (opus/sonnet/haiku/fable - lowercase) - Invoked by user with `/skill-name` - Define workflows, processes, or specialized behaviors **Agents** (in `agents/*.md`): - YAML frontmatter: `name`, `description`, `model` (lowercase) - Spawned programmatically via the `Agent` tool with `subagent_type` - Operate autonomously within defined scope **Model names must be lowercase** (`opus`, `sonnet`, `haiku`, `fable`) - capitalized names are not recognized. **Descriptions are for selection, not documentation.** They load into every session's context, for every user. Keep them to one or two sentences: what the skill or agent does and when to use it, with the trigger words a user would actually say. Put methodology in the body. **`SKILL.md` holds the procedure; `references/README.md` is the human guide.** The guide covers what a person needs to decide whether and how to use the skill: an overview and rationale, when to use it and when not to, what it asks and returns, worked examples, and at most one diagram at phase level. It links to `SKILL.md` for the steps and does not restate them. A procedure change then needs no README edit unless the user-facing contract changes. **New `/think-*` skills must pass the five tests in [`references/think.md`](references/think.md).** When proposing or designing a new `/think-*` skill, read `references/think.md` first and check the proposal against the tests there. Skills outside the `/think-*` namespace are admitted by different criteria — primarily, whether they earn their keep in real software-engineering work — though the practitioner-methodology and structured-discipline values described in `references/think.md` apply across the plugin. ## Workflow The skills form a layered system. Higher-level workflows orchestrate lower-level ones: ``` /implement (one ticket, a batch, or an open-ended goal) ├── fixed floor: concept inventory → build → practical verification → correctness review └── judgment-chosen repertoire: implementer, reviewers, /refactor, /review-*, /bug-hunt, /scope, … /bug-hunt (commander's intent: scope, severity floor, constraints, ticket/fix authority) └── loop: assess → hunt → triage → (fix via /implement, if authorized) until no finding above the floor /review-repo [focus] (commander's intent: context, scope, follow-up and ticket authority) ├── no focus: map (observe → orient → decide → act) → (with authority) the deeper │ reviews the map calls for, consolidated → tickets created (with authority) or proposed └── focus: architecture | dead-code | value | namespace → one deep review → ticket proposal ``` Planning feeds implementation: `/scope` → `/implement`. `/implement` takes one ticket, a batch, or an open-ended goal, and decides by judgment which of the below skills to invoke and when, over a small fixed floor (concept inventory, practical verification, tests green, an independent correctness review, no irreversible actions). Supporting workflows available at any level: **Reasoning and decisions:** - `/think-brainstorm` — divergent idea generation (with a framing check when the problem itself is in doubt) - `/think-diagnose` — abductive reasoning about causes (narrows ties by analysis of competing hypotheses) - `/think-deliberate` — adversarial decision-making - `/think-premortem` — prospective failure imagination - `/think-scrutinize` — adversarial idea critique - `/think-reflect` — retrospective learning **Bug work:** - `/bug-fix` — diagnosis-first bug fixing - `/bug-hunt` — proactive bug discovery (commander's intent with optional ticket/fix authority; iterates rounds until nothing is confirmed above a severity floor; advisory by default, fixes via `/implement` only when authorized) **Redesign:** - `/refactor` — simplification-first redesign (Musk's five steps; behavior pinned by a differential oracle against the incumbent; runs on its own `refactor/<slug>` branch with one checkpoint, the requirements menu; `/implement` runs it unattended with the menu answered from commander's intent) **Quality pipelines:** - `/test-mutation` — mutation testing - `/review-test` — five-phase test-suite survey (unit, integration, E2E for webapps, fuzz, test quality; advisory) - `/review-perf` — performance review (compute and/or web reviewers by project type; advisory) - `/review-a11y` — WCAG 2.2 Level AA accessibility audit (advisory) - `/review-security` — white-box security audit (isolated blue/red first pass, synthesized target list, focused red-teamers, iterates on exploit chains; advisory) - `/review-repo` — the entry point for whole-codebase review (advisory; never changes code). With no focus, it produces an evidence-cited map calibrated to a reference class. With follow-up authority, it runs the deeper reviews the map calls for and consolidates them; with ticket authority, it creates tickets, otherwise it proposes them. Focuses go straight to one deep review: - `architecture`: noun-analysis blueprint. - `dead-code`: confidence-tiered audit calibrated against dynamic dispatch. - `namespace`: cold-reader legibility probes. Search mode needs the operator and never runs unattended. - `value`: a requirement trade menu. The map runs this one only when intent asks, because its output is product decisions. Diff-scoped correctness review is not a skill. `/implement` and `/bug-fix` run `swe-correctness-reviewer` as a blocking gate, and Claude Code's built-in `/code-review` covers other diffs. **Releases:** - `/review-release` — pre-release readiness review (debug artifacts, version mismatches, changelog gaps, git hygiene, breaking changes, license compliance; advisory) - `/release` — cut a project release (discovers release procedure, always invokes `/review-release` as preflight, plans before executing, halts on first failure rather than attempting rollback) **Utility:** - `/pre-compact` — pre-compaction housekeeping (memory, git, trash, SBAR, resume prompt) - `/tidy-docs` — mechanical documentation hygiene (full audit by the `doc-maintainer` agent; fixes within its authority, surfaces judgment calls) - `/tidy-git` — mechanical local repo hygiene (prune stale refs, delete merged branches, report stashes/untracked/unpushed)