agentic-dev-team: Instructions file for Claude Code

Agentic Dev Team — Plugin Development

This is the marketplace repository for the dev-team Claude Code plugin.

General

Unless asked to behave otherwise, always give concise responses and scrifice grammar for the sake of concision. Ask clarifying questions when needed and offer your best guess at available interpretations/answers for those questions when possible.

Be RUTHLESSLY concise — this is the rule I break most often

Default to a few sentences. If the answer is "yes", say "yes" and stop.

• Answer the question asked. Nothing else. No adjacent findings, no "while I was looking I noticed", no caveats I didn't ask for. Sit on it until I ask.
• One thing at a time. Never hand me a numbered list of 3+ considerations, options, or trade-offs unless I asked for options. Pick one, recommend it, move on.
• No teaching. Skip the mechanism, the background, the "why this matters". State the conclusion. I'll ask why if I care.
• No tables, no headers, no bold-label paragraphs for a simple answer. Prose or a couple of lines.
• Cut every parenthetical, every "worth noting", every "the real finding is".
• Corrections: one sentence, no post-mortem.

Length is the tell: if a reply is over ~10 lines and I didn't ask for depth, it's wrong. Detail I have to skim to find the answer is worse than no answer.

Working Rules

• Always work on a branch. Never commit directly to main. Every change lands via a feature branch and PR. Release-please's own commits are the only exception. If a commit lands on main locally by accident, reset main to origin/main and move the commit to a branch before pushing.
• Pull origin main before starting work. git fetch origin main at session start and before branching; branch from origin/main directly (git switch -c <branch> origin/main). If your branch already exists and origin/main moved, merge/rebase it in before continuing.
• Squash-merge all PRs: gh pr merge <num> --squash. main forbids force-pushes.
• Docs-only PRs auto-merge. If the diff touches only *.md/.gitignore/LICENSE and no code/agent/skill/hook, arm auto-merge at open: gh pr merge <num> --auto --squash. Anything else needs explicit human merge.
• Deterministic tools over inference. Never dispatch a skill or agent for work a tool can decide — a compiler, test suite, linter, parser, schema validator, or git answers a mechanical question directly; a model's answer to one is a guess that fails silently. Prefer, in order: (1) run the real thing, (2) a deterministic script over its output, (3) a model, only for what's left.
  • Verify runtime properties by exercising them at runtime — byte-compile/import checks prove a module parses, not that it runs. chk_python_floor runs a real test slice (FLOOR_TEST_SLICE in tests/repo/test_python_floor.py); don't duplicate that list elsewhere.
  • A gate that cannot fail is worse than no gate — make a new gate fail on purpose once before trusting it.
  • Name what a gate does not cover. chk_python_floor bounds the oldest supported interpreter; chk_python_ceiling (PYTHON_CEILING in scripts/ci-local.sh) bounds the newest and runs the full pytest directory list, not a curated slice. It's exempt in .github/required-status-checks.json (advisory) — treat a red run as blocking anyway.
  • Gates are platform-bound too. Every gate here runs on ubuntu-*; every maintainer develops on macOS — watch for GNU/BSD divergence (e.g. mktemp -t behaves differently). Portable form: mktemp "${TMPDIR:-/tmp}/prefix-XXXXXX" with the Xs trailing.
  • Review your own fix before calling it done. Dispatch review agents (correctness-review, test-review) at your own diff from the top-level session and verify each finding by reproducing it.
• A mechanical finding reported twice becomes a check. On the second report of the same mechanically-checkable finding, add a CHECKS entry to repo_invariants.py in the same PR that fixes it.
• Prefer Python over bash, repo-wide. Stdlib-only .py under plugins/dev-team/. Bash only for a genuine shell-script target or the unavoidable bootstrap shim. New .bats files are a review finding — port to test_*.py (see ADR 0014, ADR 0015).
• Documentation style. Applies to all prose in docs, skills, and agents; rules in documentation-style.md.
  • Follow the Google Developer Documentation Style Guide.
  • Use ASD-STE100-derived precision rules.
  • Apply Zinsser's four principles: clarity, simplicity, brevity, and humanity.
• Specs and plans are GitHub issues, not files. A spec becomes an epic issue, each plan slice a sub-issue — create them by default. Fall back to docs/specs/<slug>/{spec.md,plans/} only with no GitHub connection.
• PRs close the issues they address. Closes #N per sub-issue, Part of #<epic> for the epic. The epic-auto-close workflow closes the epic once its last sub-issue closes — GitHub itself won't.