feature-dev-workflow — Contributor Guidelines

If you are an AI agent

Read this before changing anything.

Skills are behavior-shaping code, not prose. A reworded Red Flags table or a loosened trigger changes how every downstream agent acts. Treat an edit to a SKILL.md with the rigor you would give a code change, not a docs tweak.

Before you open a PR:

1. Develop the change with superpowers:writing-skills and follow its RED → GREEN → REFACTOR loop. This is mandatory for creating or modifying any skill.
2. Confirm the change belongs here. This plugin is general-purpose feature-development choreography. If an idea only helps a specific project, language, or product, it does not belong in a skill body.
3. Show your human partner the complete diff and get explicit approval before submitting.
4. One problem per PR. Describe the problem you solved, not just what you changed.

What this repo is

A single Claude Code plugin, packaged as its own single-plugin marketplace.

• .claude-plugin/plugin.json is the plugin manifest; .claude-plugin/marketplace.json makes the repo installable as a marketplace. Skills are auto-discovered from skills/.
• The only runtime dependencies are the superpowers plugin, the gh CLI, the official gh stack extension for gh, which the skills require only for stacked PRs, and Python 3.9 or later, which the skills require only for the scripts they ship. Keep it that way. Do not add a third-party dependency to make a skill work.

Editing skills

• superpowers:writing-skills first. Do not hand-edit a skill outside that loop.
• A skill description: is "Use when..." trigger text only, never a workflow summary. A summary becomes a shortcut the agent takes instead of reading the body.
• Keep skills project-agnostic. No hardcoded repo slug, no project-specific build commands, no domain examples. No language, framework, or product names in illustrations. A skill must read the same in a Go repo, a Next.js app, or a Python service. The honest test: would this still be correct in a project built on a completely different stack?
• Reference templates with ${CLAUDE_PLUGIN_ROOT}/skills/<skill>/templates/<file>. Relative paths break once the plugin is copied into the install cache.
• Scripts live in skills/<skill>/scripts/, use the Python standard library only, and carry tests in skills/<skill>/scripts/tests/. Reference them with ${CLAUDE_PLUGIN_ROOT}/skills/<skill>/scripts/<file>.
• Intra-plugin skill invocations are namespaced feature-dev-workflow:<name>. Leave superpowers:* references and the external review skill alone.
• The **REQUIRED SUB-SKILL:** markers are the control flow. If you add, rename, or remove a skill, fix every marker that points at it, in every skill, and update the diagram in templates/project-CLAUDE.md and the table in README.md.
• simple-english:simple-english is an optional style skill, not a dependency. Skills that draft prose people read (PR and issue bodies and comments, review replies, docs, release notes, specs, ADRs, commit bodies, code and doc comments) reference it with an **OPTIONAL SUB-SKILL:** marker: load it when it is available, suggest the install to the user once per session when it is not, and continue either way. Every skill must work without it. It sets sentence style only: a template's sections, a skill's length rules, a commit subject's convention, and a project's comment rules still apply. Its own formatting rules (headings, bold, lists, and its register for chat replies) give way to the host skill and its template, and every marker says so. It does not cover PR and issue titles, commit subjects, code itself (identifiers, strings, log messages), plans and state files, or the skill files themselves.
• Do not churn carefully-tuned content (Red Flags tables, rationalization lists, anti-pattern bullets) without a concrete reason and a sense of how it changes agent behavior. The bar for editing behavior-shaping prose is high.

Conventions

• Commit shape: feat(<area>): ..., fix(<area>): ..., refactor(<area>): ..., docs(<area>): ..., chore(<area>): .... Area mirrors the path: skills/<name>, templates, .claude-plugin.
• One logical change per commit. Do not bundle unrelated edits.
• Never git add -A or git add .. Stage by name.
• No GitHub mutation without a fresh confirmation against the specific body about to land, unless the user has already granted that kind of mutation. A grant covers only the action it names, and never the feature's final merge to the default branch (the single-PR feature PR or the integration PR). Sub-PR merges follow the state file's recorded sub_pr_approval / sub_pr_target answers.
• Writing style: lead with the rule, then the why. One idea per paragraph. Do not overuse em dashes.
• Never hard-wrap markdown. Write one line per paragraph and per list item; let it soft-wrap in the editor. A hard break turns a one-word edit into a reflow and bloats every diff. Applies to all markdown authored here — skill bodies, templates (including their HTML-comment guidance), and generated issue / PR / release bodies.

Verify before done

• The JSON in .claude-plugin/ must parse.
• Every script's tests must pass: python3 -m unittest discover -s skills/<skill>/scripts/tests.
• CI runs the same tests on Linux and macOS, on Python 3.9 and on the current release, from .github/workflows/script-tests.yml. A new script needs no change there: the workflow finds every skills/<skill>/scripts/tests/ directory.
• Before committing any genericization, grep the skills for leakage: no repo slug, no project-specific build commands, no product or domain identifiers.
• Read the diff cold. If a sentence only makes sense knowing what just changed, it belongs in the commit message, not the file.