CLAUDE.md · diff
git:20261116.afefe92 to git:20261116.75ffff6
28 added, 2 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# 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-readable guide for the skill
+ │ └── 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 `Task` tool with `subagent_type`
+ - 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)