Skip to content

🛠️ develop — Claude Code Plugin

Six development workflows — plan, feature, fix, refactor, debug, and review — help Claude Code understand a Python change before it edits production code. /develop:setup is the separate post-install command that delivers this plugin's rule symlinks.

The gates narrow the failure surface — they do not replace developer judgment on whether a generated change is correct or production-safe.

Changelog records version-by-version changes, including the plugin's earlier directory history.

Contributing or want internals? See DEVELOPMENT.md.

Works standalone — foundry is not required. Without it, agent dispatches fall back to general-purpose with role descriptions; with it, the same workflows can route to named specialists such as foundry:sw-engineer and foundry:qa-specialist.

📋 Contents

🤔 What is develop?

develop is a Claude Code plugin for validate-first Python development: scope work, pin a feature contract, reproduce a bug, preserve behavior during refactoring, investigate failures, and review local Python changes with explicit evidence and handoff artifacts.

Each workflow has gates that pause when the contract, reproduction, evidence, or safety net is missing.

Current boundaries: code-changing and review workflows target Python projects with pytest-style tooling; /develop:plan can analyze a broader task, but downstream implementation still assumes pytest. Dependency migrations, data migrations, codebase onboarding, and Python-free changes remain outside this plugin's current scope; use the project's native workflow or another tool. Broader language support could be added later, but is not promised here.

How work is organised

  • Small implementation uses a concise plan, brief parent self-challenge (not independent), acceptance within existing authority, useful bounded execution ownership or indivisible parent execution, and consolidation with independent result challenge and relevant verification.
  • Medium/large work retains independent plan challenge before acceptance.
  • Approval prompts only for actual missing authority or protected decisions; reuse accepted parent plans and establish core acceptance before optional expansion.
  • Validate a coherent bounded outcome or split it into smaller outcomes, then complete the active branch depth-first using a compact task map and context limited to the active piece, dependencies, and interfaces.
  • Complete required leaf challenge and verification before dependent work; dependency-ready siblings with agreed stable interfaces and disjoint owners may proceed.
  • Unknown causes or design choices first become bounded investigation or decision prerequisites; parent consolidation retains required gates.
  • This replaces broadly open workstreams and far-ahead detail to reduce context, coordination, and rework; that benefit is expected, not measured.

Review and challenge loops

  • Review loops fix feasible authorized findings, investigate repeated signatures, and continue whenever the weighted score decreases; structural labels alone do not stop remediation.
  • Completion prompts ask only for a missing decision or authorization, regardless of report length, and already-authorized next steps continue. Concrete gates for fresh scope, paid execution, sensitive or destructive actions, and remote changes remain in force.
  • Each round challenges and collects findings, reports the cumulative old/new table, resolves feasible authorized findings, escalates unfixable security/critical/high findings, then repeats until clean or plateau/non-convergence, subject to authority, evidence, recurrence and stricter caller budgets.
  • The table is Iteration | Security | Critical | High | Medium | Low | Nits | Weighted score; open and fixed-pending-verification signatures split into old and new, while verified-fixed and rejected findings stay excluded. Security and critical have separate columns; score weights remain 20/10/6/4/2/1. Empty rounds print no progress table.
  • The cumulative table is shown once after each newly validated challenge, before fixes or another review. Pending reviews and unrelated status updates do not repeat it; final handoffs retain their canonical Results table.
  • Each open finding needs a recorded fix, escalation, or justified deferral; chat table timing has no machine-readable delivery receipt.
  • A 1,500-output-token reviewer target is hard only when the runtime supports it; findings are never dropped to meet it.
  • Before the baseline review of a diff the parent or its resolver wrote, the author records an attestation (invariant, sibling routes, consumer, failing-before/passing-after check) and fixes the gaps it exposes; the reviewer never sees it and it never counts toward scoring.
  • Each round's cost lands in an advisory loop-metrics.jsonl.
  • Adversarial workflow reviews include unchanged downstream consumers and the next ordinary user action, checking whether local success actually establishes the promised outcome and recording untested handoffs.

Reports and Codemap context

  • Code review reports include the full reviewed commit SHA and distinguish source judgment from verification readiness; local path reviews identify the base commit even with --worktree, since existing worktrees and absolute targets may contain uncommitted changes.
  • Feature, review, fix, refactor, diagnosis, and plan report examples use short descriptive fields. Writing requirements are separate notes; completed reports replace fields with observed values and omit the notes.
  • Optional Codemap context and index-gate guidance ship with develop, so loading them does not depend on another plugin's private shared directory. The host-provided active installation takes precedence over other cached versions. Structural queries still require the codemap-py plugin; an unavailable CLI or local contract retains the file-read fallback.
  • Codemap review batches retain each child's success, freshness and scope metadata; failures are not empty answers. Package initializer changes stay in the affected-module scan.
  • Codemap reuse requires the same project/index/query, including flags; review-to-resolve cache stamps include the canonical index path. Static test links and mocks are not measured coverage, and source/test-quality reads remain available.

🎯 Why develop?

Without it, AI-assisted development tends to:

  • Implement before API contract pinned — discover wrong design after implementation
  • Fix bugs by guessing root cause — patches pass tests, don't fix actual problem
  • Refactor without safety net — break behavior silently
  • Apply multi-file changes blind to affected downstream callers

These workflows address common maintenance failures with concrete gates:

  • feature: failing demo test first — cannot write test = feature underspecified
  • fix: reproduce bug with failing regression test first — cannot reproduce = cannot verify fix
  • refactor: audit test coverage, lock characterization tests before moving one line
  • debug: gather all evidence, state one confirmed hypothesis before any fix
  • plan: scope complexity and blast radius; challenge the plan's feasibility before committing unless waived
  • review: local Python review across architecture, tests, performance, docs, lint, security, and API design.
  • Groups the relevant dimensions into spawn units (performance+architecture and docs+lint each share one agent) and runs the top three units by default, or all selected units with --full; no GitHub PR is required.
  • FEATURE/MIXED changes also get an isolated blind-solve pass outside the cap when a matching .plans/active/*.md exists: one agent sketches its own blueprint from that plan without seeing the diff, and the consolidated report lists where that blueprint diverges from the change (### Design Divergence), marking divergences that may be explained by context the agent lacked as questions rather than findings.
  • Before its follow-up gate the skill refreshes its compaction contract and prints a /compact hint, so a long wait at the gate can be spent compacted and resumed from the report file.

When Codemap is enabled, fix selects a route before retrieval: a fully localized file-and-symbol edit can use the explicit zero-query path, while unresolved callers, dependencies, blast radius, imports, or source scope receive only the matching compact query.

📦 Install

Prerequisites: Claude Code installed (claude --version) and Python 3.10+ with a project test runner for code-changing/review workflows. The plugin itself is installed from the borda-ai-rig marketplace; project dependencies remain your responsibility.

Install develop

claude plugin marketplace add Borda/AI-Rig
claude plugin install develop@borda-ai-rig

Then run /develop:setup once to link this plugin's rules into ~/.claude/rules/. Re-run it after every upgrade. A repository checkout may also run make sync-claude, but that is not required for a marketplace install.

Optional integrations

claude plugin install foundry@borda-ai-rig   # named specialist agents
claude plugin install oss@borda-ai-rig        # optional GitHub PR review (/oss:review <PR#>)
claude plugin install research@borda-ai-rig

foundry gives develop access to named specialist agents such as foundry:sw-engineer, foundry:qa-specialist, foundry:linting-expert, and foundry:doc-scribe. Without it, dispatches fall back to general-purpose with role descriptions. The develop plugin ships its own quality-stack and shared workflow files; foundry is not required for those files to load.

Verify installation

claude plugin list | grep -F 'develop@borda-ai-rig'

Expect enabled entry like develop@borda-ai-rig in output.

⚡ Quick start

Fastest value: scope next task before starting.

/develop:plan "extract data loading into a dedicated DataLoader class"

plan reads the codebase, classifies the task, identifies affected files and estimates complexity. For feature, fix and refactor work it writes a structured plan to .plans/active/ and challenges its feasibility unless --no-challenge is passed. A separate feasibility review runs only on explicit request. Unknown root cause routes to /develop:debug first without an implementation plan.

Plan -> .plans/active/plan_extract-data-loading-dataloader.md

Classification : refactor
Complexity     : medium
Affected files : 4 files across 2 modules
Key risks      : Public API changes in dataset.py — 3 callers
Agent review   : plan challenge completed; separate feasibility review not requested

-> /develop:refactor "extract data loading into a dedicated DataLoader class" when ready

🔧 Skills reference

All skills invoked with develop: prefix.

/develop:plan

Purpose: Scope task before committing. Produces structured plan: classification, complexity estimate, affected files, risks, suggested approach. No code written.

When to use: before non-trivial feature/fix/refactor; blast radius or complexity unclear; want agent-validated feasibility first.

Invocation:

/develop:plan "<goal>"

Flags:

Flag Description
--no-challenge Skip challenger adversarial gate
--codemap Require Codemap and an index; stop when unavailable
--no-codemap Disable Codemap even if available
--max-depth <N> Limit plan → debug → plan cycles (default: 3)

What happens:

  1. Spawns foundry:sw-engineer to classify task (feature / fix / refactor / debug), map affected files, estimate complexity (small / medium / large), list risks. With codemap: effort sizing structural, not file-count-based — reverse-dependency counts per affected module set blast tier (≥5 rdeps HIGH, 1–4 MODERATE, 0 LOW), co-change coupled pairs surface as risks. HIGH module or 3+ affected modules push complexity to large.
  2. Unknown root cause: after the depth checkpoint and any applicable breaking-change gate, recommend /develop:debug <goal> and stop without writing or challenging an implementation plan. At the depth cap, explicitly choosing Write the plan anyway continues with the unconfirmed cause recorded as a risk; resetting the cap recommends debug, and abort stops.
  3. Otherwise write a structured plan to .plans/active/<slug>.md. Skip separate feasibility review by default; run it only on explicit request.
  4. Challenge the plan once for design, feasibility and testability unless --no-challenge is passed; resolve feasible authorized findings and escalate unresolved blockers or protected decisions.
  5. Write a brief summary and the appropriate downstream handoff.

Output to terminal:

Plan -> .plans/active/plan_<slug>.md

Classification : feature | fix | refactor
Complexity     : small | medium | large
Affected files : N files across M modules
Key risks      : <one-liner>
Agent review   : challenge and optional feasibility review status, including skipped or unavailable coverage

-> /develop:feature|fix|refactor "<goal>" when ready

Passing plan to downstream skills: feature, fix and refactor accept --plan <path>.

  • The skill reads classification, affected files, risks and suggested approach, and incorporates the plan challenge and any explicitly requested feasibility review.
  • The plan's hash is recorded when it is read (.plans/ is gitignored, so edits leave no diff); these skills re-check it before the Final Report and lead with ! BLOCKED — plan changed during build when it differs. Detection only, nothing is reverted.
  • Simple and staged plans carry a Verification column and — verify: on each suggested step.
  • A direct debug recommendation has no implementation plan; /develop:debug hands off to /develop:fix --diagnosis <path>.
/develop:plan "add streaming response support"
/develop:feature "add streaming response support" --plan .plans/active/plan_add-streaming-response-support.md

What plan does NOT do: write code or tests. Analysis-only.

/develop:feature

Execution architecture — same diagram: see /develop:fix.

Purpose: TDD-first feature development. Crystallises API as failing demo test, drives implementation to pass, closes quality gaps via one independent challenge + docs update.

When to use: adding new behavior.

Not for: bug fixes — use /develop:fix.

Invocation:

/develop:feature "<goal>"
/develop:feature "<goal>" --plan <path>                     # skip cold analysis, use existing plan
/develop:feature 123 --repo owner/upstream-repo         # implement issue from upstream repo (fork workflow)
/develop:feature "<goal>" --team                            # parallel agents for complex/cross-module features

Flags:

Flag Description
--issue <N> Fetch issue <N> as the feature request; numeric positional arguments are also recognized as issue references
--repo <owner/repo> Route issue fetch to upstream repo. Use when working in fork and issue on original repo (e.g. --repo owner/my-project).
--plan <path> Read classification, scope, approach from existing plan file
--team Spawn parallel foundry:sw-engineer + foundry:qa-specialist + foundry:doc-scribe teammates. Use when feature spans 3+ modules, changes public API, or touches auth/payment/data scope
--worktree Run the whole skill in an isolated git worktree (.claude/worktrees/) on a new branch — you review + merge (never auto-merged). Codemap index is per-worktree, so parallel runs never race one index. Composes with --team.
--no-batch Default on, opt out with this flag. TDD loop groups non-overlapping tests/edits into fewer runs instead of one run per piece of functionality; bisects per-edit on batch failure to preserve attribution. Scoped to Step 3's loop only.
--no-codemap Disable codemap even if available
--codemap Require Codemap and an index; stop when unavailable
--accept-no-plan Skip inline plan generation for medium/large scope (trust own scoping)
--no-challenge Skip challenger adversarial gate
--challenge Accepted for compatibility; no effect, since the challenger runs at every size unless --no-challenge
--keep "<items>" Append items to compaction contract preserve field — keeps key context if auto-compaction fires mid-skill

Workflow:

  1. Scope analysis (foundry:sw-engineer): existing patterns, reuse opportunities, affected files, compatibility concerns. GitHub issue number given → fetches full issue + comments (upstream if --repo).
  2. Source verification (conditional): feature calls external library API → detects installed version from pyproject.toml, fetches official docs via WebFetch, cites relevant passage in code comments.
  3. Demo use-case: crystallises API contract as inline doctest (simple functions) or example script (complex features with setup). Demo must fail against current code before proceeding. Gate enforced via exit code — not output text.
  4. TDD implementation loop (foundry:sw-engineer): tests pass in non-overlapping groups by default (--no-batch for one run per piece of functionality), full-directory baseline on the first cycle only; every later cycle and the review run only the tests each change touches (dev_test_targets.py).
  5. Review and close gaps: 5-axis quality scan (correctness, readability, architecture, security, performance) → fix feasible gaps.
  6. Documentation (foundry:doc-scribe): updates docstrings and README content when the implementation changes a public API; a separate changelog step is used only when the project has a changelog convention.
  7. Quality stack: available ruff/mypy checks → full test suite (parallel via pytest-xdist when available, probed against the detected runner) — rerun in full after any later fix, max 3 gate iterations → optional Codemap blast-radius check → one bounded independent implementation challenge; iterative review only when explicitly requested.

! BREAKING (report format) — the quality stack folds --doctest-modules into the main suite run when a clean-collection check passes; Doctests: in the Final Report is now pass / fail / not-merged (was a plain pass/fail line). Flaky-test retry now re-runs only the specific failing node-ids (was a blind whole-directory re-run); a failure reproducing only under parallel execution is reported as a likely test-isolation bug, not marked flaky.

Realistic example:

/develop:plan "add CSV export to the results API"
/develop:feature "add CSV export to the results API" --plan .plans/active/plan_add-csv-export-results-api.md

Team mode coordination: two serialized waves.

  • Wave 1: foundry:sw-engineer implements the feature and must show the demo test failing before implementation; if it already passes, the run stops before Wave 2.
  • Wave 2: foundry:qa-specialist (edge-case and regression tests) and foundry:doc-scribe (docs) run in parallel against the actual implementation from Wave 1, so neither tests guessed APIs nor documents placeholder structure.

/develop:fix

Execution architecture — animated diagram of fans, joins and gates, shared with /develop:feature and /develop:refactor.

/develop:fix, /develop:feature and /develop:refactor execution architecture: solo spine, team branches and gates (animated)

Purpose: Reproduce-first bug resolution. Captures bug in failing regression test before any fix.

When to use: fixing known bug with traceback, failing test, or GitHub issue.

Not for: CI-only failures — use /develop:debug --ci-run <run-id> first; production incidents without CI run or traceback — use /foundry:investigate (requires foundry plugin); .claude/ config issues — use /foundry:audit (requires foundry plugin).

Invocation:

/develop:fix "<symptom description>"
/develop:fix 88                                     # GitHub issue number — fetches full issue + comments
/develop:fix 88 --repo owner/upstream-repo          # issue on upstream repo (fork workflow)
/develop:fix "<symptom>" --plan <path>              # use existing plan
/develop:fix "<symptom>" --diagnosis <path>         # skip root cause analysis; use debug output
/develop:fix "<symptom>" --team                     # parallel root-cause investigation

Flags:

Flag Description
--repo <owner/repo> Route issue fetch to upstream repo. Use when working in fork and issue on original repo (e.g. --repo owner/my-project).
--plan <path> Read scope and approach from existing plan file
--diagnosis <path> Read confirmed root cause from /develop:debug output file; skips Step 1 analysis entirely
--team Spawn 2-3 foundry:sw-engineer teammates, each investigating distinct root-cause hypothesis independently (read-only: they share your working tree, so no tracked-file edits or git stash/checkout/reset/restore; probes run in a temp copy or the run directory)
--worktree Run the whole skill in an isolated git worktree (.claude/worktrees/) on a new branch — you review + merge (never auto-merged). Codemap index is per-worktree, so parallel runs never race one index. Composes with --team.
--no-challenge Skip challenger adversarial gate entirely
--challenge Accepted for compatibility; no effect, since the challenger runs at every size unless --no-challenge
--keep "<items>" Append items to compaction contract preserve field — keeps key context if auto-compaction fires mid-skill

Workflow:

  1. Understand the problem (foundry:sw-engineer): reads full traceback, searches failing code path, traces call graph, identifies root cause, state mutation, blast radius. Argument = positive integer → fetches GitHub issue (upstream if --repo).
  2. Reproduce the bug (foundry:qa-specialist): writes regression test failing on unfixed code. Gate: test must exit non-zero before proceeding.
  3. Apply the fix (foundry:sw-engineer): minimal change — only what makes regression test pass. Then runs only the tests the change touches (dev_test_targets.py: Codemap test-impact, or name/import heuristics without Codemap).
  4. Review and close gaps: quality scan → fix feasible gaps and run targeted tests. Adjacent bugs documented as observations, handled in separate session — never fixed same pass.
  5. Quality stack: available ruff/mypy checks → full test suite (parallel via pytest-xdist when available) — the final gate after the loop, rerun in full after any later fix, max 3 gate iterations; a green full suite is the last test evidence → optional Codemap blast-radius check → one bounded independent implementation challenge; iterative review only when explicitly requested.

Realistic example:

/develop:fix "KeyError in transform pipeline when input has null values"
/develop:fix 124   # fix GitHub issue #124

Using debug output:

/develop:debug "intermittent timeout on /api/predict under load"
# After debug session writes .plans/active/debug_intermittent-timeout.md:
/develop:fix "intermittent timeout on /api/predict under load" --diagnosis .plans/active/debug_intermittent-timeout.md

Scope gate: root cause spans 3+ modules → asked narrow scope or proceed — prevents large unfocused fixes.

/develop:refactor

Execution architecture — same diagram: see /develop:fix.

Purpose: Test-first refactoring. Audits test coverage, adds characterization tests for gaps, restructures code with safety net catching any behavior change.

When to use: restructuring existing code — extracting classes, simplifying logic, cleaning API, removing dead code — without changing observed behavior.

Not for: bug fixes — use /develop:fix; new features — use /develop:feature.

Invocation:

/develop:refactor "<target file or directory> <goal>"
/develop:refactor "<goal>" --plan <path>
/develop:refactor "<goal>" --repo owner/upstream-repo   # context from upstream issue (fork workflow)
/develop:refactor "<goal>" --team                       # parallel: foundry:sw-engineer refactors + foundry:qa-specialist writes tests simultaneously

Flags:

Flag Description
--repo <owner/repo> Route issue fetch to upstream repo. Use when refactor context tied to upstream issue in fork. Parsed for consistency; refactor has no issue-fetch step by default.
--plan <path> Read scope and approach from existing plan file
--team Spawn foundry:sw-engineer (refactoring) + foundry:qa-specialist (characterization tests) parallel. Use when target is directory or spans multiple modules
--worktree Run the whole skill in an isolated git worktree (.claude/worktrees/) on a new branch — you review + merge (never auto-merged). Codemap index is per-worktree, so parallel runs never race one index. Composes with --team.
--no-batch Default on, opt out with this flag. Step 4 groups non-overlapping focused changes into fewer test runs instead of one run per change; bisects per-edit on batch failure to preserve attribution.
--no-codemap Disable codemap even if available
--codemap Require Codemap and an index; stop when unavailable
--accept-no-plan Skip inline plan generation for medium/large scope
--no-challenge Skip challenger adversarial gate
--challenge Accepted for compatibility; no effect, since the challenger runs at every size unless --no-challenge
--keep "<items>" Append items to compaction contract preserve field — keeps key context if auto-compaction fires mid-skill

Workflow:

  1. Scope and understand (foundry:sw-engineer): reads target code, maps public API surface, identifies complexity hotspots + coupling. Codemap for blast-radius when available. Scope gate: target spans 3+ modules, 5+ files, or any public-API rename → asks narrow or proceed.
  2. Audit test coverage: classifies each public function covered / partially covered / uncovered. No pytest-cov installed → falls back to "all uncovered" conservatively.
  3. Add characterization tests (foundry:qa-specialist): every uncovered/partial public API gets tests asserting current behavior (not desired). Gate: all characterization tests must pass on unmodified code before proceeding.
  4. Refactor with safety net: focused changes run in non-overlapping groups by default (--no-batch for one focused change per cycle), with only the tests each change touches after each (dev_test_targets.py: Codemap test-impact, or name/import heuristics without Codemap) — never the full suite inside the loop. Safety break: max 5 change-test cycles per inner session (edits, not cycles, unless --no-batch is set); max 10 total across all outer review cycles.
  5. Review and close gaps: behavior preservation, goal achievement, no new smells, no unintended API surface changes; rerun targeted tests after fixes.
  6. Quality stack: available ruff/mypy checks → full test suite (parallel via pytest-xdist when available) — the final gate after the loop (the repository's own test command when the quality stack is unavailable), rerun in full after any later fix, max 3 gate iterations; a green full suite is the last test evidence → optional Codemap blast-radius check → one bounded independent implementation challenge; iterative review only when explicitly requested.

Refactoring categories skill handles:

  • Logic simplification: replace complex conditionals, flatten nesting, extract helpers
  • API cleanup: rename for clarity, consolidate parameters, add type annotations
  • Structural: extract classes/modules, reduce coupling, apply design patterns
  • Performance: replace loops with vectorized ops, reduce allocations, batch I/O
  • Dead code removal: unused imports, unreachable branches, unexported public methods

Realistic example:

/develop:plan "extract data loading into a dedicated DataLoader class"
/develop:refactor "extract data loading into a dedicated DataLoader class" --plan .plans/active/plan_extract-data-loading-dataloader.md

Checkpoint and resume: creates .developments/<timestamp>/checkpoint.md after each step. Session interrupted → re-run offers resume from last completed step.

/develop:debug

Purpose: Investigation-first debugging. Gathers all signals, traces failure path, forms single confirmed root-cause hypothesis, writes diagnosis file, hands off to /develop:fix.

When to use: symptom without confirmed root cause; bug mysterious enough to warrant structured investigation before fixing.

Not for: production incidents without CI run ID or traceback — use /foundry:investigate (requires foundry plugin); .claude/ config issues — use /foundry:audit (requires foundry plugin). CI-only failures ARE supported — pass --ci-run <run-id or URL>.

Invocation:

/develop:debug "<symptom description>"
/develop:debug 88                                   # GitHub issue number
/develop:debug 88 --repo owner/upstream-repo        # issue on upstream repo (fork workflow)
/develop:debug "<symptom>" --team                   # parallel hypothesis investigation

Flags:

Flag Description
--issue <N> Force issue mode — fetch GitHub issue <N> instead of inferring mode from a bare numeric argument. Value form only; --issue=123 is not supported by design (mode-detect matches the bare token).
--repo <owner/repo> Route issue fetch to upstream repo. Use when working in fork and issue on original repo (e.g. --repo owner/my-project).
--team Spawn 2-3 foundry:sw-engineer teammates, each investigating distinct root-cause hypothesis independently (read-only: they share your working tree, so no tracked-file edits or git stash/checkout/reset/restore; probes run in a temp copy or the run directory). Use when root cause unclear after initial analysis, or failure spans 3+ modules
--worktree Run the investigation in an isolated git worktree (base: HEAD) so reproduction attempts never touch main sources. Diagnosis file is written to the main tree so /develop:fix can read it.
--ci-run <id-or-url> Fetch CI failure logs via gh run view <id> --log-failed instead of running pytest locally. Accepts bare run ID or any GitHub Actions URL (/actions/runs/<id> or /actions/runs/<id>/jobs/<job>). Use for CI-only failures, no local repro.
--codemap Require Codemap and an index; stop when unavailable
--no-codemap Disable codemap even if available
--no-challenge Skip challenger adversarial gate entirely
--challenge Accepted for compatibility; no effect, since the challenger runs at every size unless --no-challenge
--keep "<items>" Append items to compaction contract preserve field — keeps key context if auto-compaction fires mid-skill

Workflow:

  1. Understand the symptom (foundry:sw-engineer): reads full tracebacks, recent git changes near failing code, traces call path entry point → failure site. GitHub issue number → fetches full issue + comments (upstream if --repo).
  2. Pattern analysis: finds 2-3 similar working code paths, compares exhaustively against broken path — input, environment, call order, conditional branches, None/empty guards.
  3. Hypothesis and gate: states root cause explicitly with supporting + contradicting evidence and confidence (high / medium / low). Presents hypothesis, waits for confirmation before proceeding. Low confidence → targeted probe (minimal script, added assertion) for missing signal. Codemap enabled → one-time test-impact query on confirmed suspect module/function.
  4. Hand off to fix: writes diagnosis file to .plans/active/debug_<slug>.md, emits -> /develop:fix --diagnosis <path>. Fix's Step 1 pre-answered by diagnosis. Test-impact result (with index timestamp) written under ## Test Impact (codemap-py) section — /develop:fix reuses it (test-impact runs once across debug→fix flow), re-queries only if index moved or result stale.

Debug is investigation-only — no code changes. Fix happens in separate auditable session with own regression test gate.

Realistic example:

/develop:debug "intermittent timeout on /api/predict under load"
# -> /develop:fix --diagnosis .plans/active/debug_intermittent-timeout-api-predict.md

Team mode: teammates independently investigate competing hypotheses, lead facilitates cross-challenge, synthesises consensus before handing off to fix.

/develop:review

Execution architecture — animated diagram of fans, joins and gates.

/develop:review execution architecture: fans, joins and gates (animated)

Purpose: Review local Python files or the current git diff across architecture, tests, performance, docs, static analysis, security, and API design. No GitHub PR is required.

  • The classifier selects relevant dimensions, which fold into spawn units (performance+architecture share one agent, docs+lint share another; each merged unit still writes one findings file per dimension); the default fan-out is capped at three units, and --full runs every selected unit.
  • Test gaps default to [low]; [medium] requires a changed public entry point (or a reviewed one for file/directory targets) with zero tests exercising it, and never exceeds [medium].
  • Root-cause merges preserve each candidate’s validated severity and section; resolve uses the group’s highest severity and required-work routing when the oss plugin is available.

When to use: reviewing own changes before committing; structured feedback on local files; closing quality gaps before PR.

Not for: GitHub PR review — use /oss:review <PR#> (requires oss plugin); implementation work — use /develop:feature or /develop:fix.

PR numbers: a bare PR number (/develop:review 42 or #42, with or without flags beside it) is detected after flag parsing. With oss installed, the skill offers to run /oss:review 42 instead; without it, it asks for a local path to review. A file or directory named like a number (42.py, or an existing 42) is reviewed as a path.

Severity checklist: review agents and the consolidator apply the severity anchors, consolidation rules and suppressions in skills/review/templates/review-checklist.md, shipped with develop; no other plugin is needed for them.

Scope: Python source only. Non-Python files (YAML, Dockerfile, JSON, shell scripts) flagged in report header as "not reviewed" but presence noted — dependency/config changes can silently break reviewed Python code.

Report header and ratings:

  • The saved header retains develop-review and includes Title so the report-delivery hook accepts the shipped template.
  • Review output preserves its aggregate prose summary, verdict, confidence and detailed findings.
  • The header table adds Reviewers: Software engineer [3], QA specialist [2], Documentation reviewer [1]. Each rating appears in square brackets after the role name (Software engineer [3]). Its legend appears immediately below: 1 = Approve · 2 = Minor changes · 3 = Major revision · 4 = Insufficient, but a good initiative · 5 = Block.
  • Ratings describe actual reviewers' scoped judgments, never an averaged verdict. Reviewer names and finding authors show roles only, without execution-origin labels; skipped roles are omitted.
  • The findings overview adds an Author column retaining all contributors to deduplicated findings.
  • Missing coverage and unavailable checks stay factual review limits; a review beyond the invoked scope needs one explicit user decision, and a declined optional pass is not an action item.

Invocation:

/develop:review                          # review current git diff (staged + unstaged vs HEAD)
/develop:review src/mypackage/module.py  # review a specific file
/develop:review src/mypackage/           # review all Python files in a directory

Flags:

Flag Description
--no-challenge Skip challenger adversarial gate
--challenge Accepted for compatibility; no effect, since the challenger runs at every diff size unless --no-challenge is passed
--codemap Require Codemap and an index; stop when unavailable
--no-codemap Disable codemap even if available
--worktree Run the review in an isolated git worktree (base: HEAD) so no agent can mutate main sources. Report is written to the main tree; reviews the last commit (HEAD~1..HEAD; uncommitted changes not visible).
--full Run every spawn unit selected by classification instead of the default top-three-unit cap
--keep "<items>" Append items to compaction contract preserve field — keeps key context if auto-compaction fires mid-skill

Workflow:

  1. Identify scope: collects Python files from path or git diff HEAD. Classifies diff FIX / REFACTOR / FEATURE / CHORE / MIXED.
  2. Review depth follows the code path, not the diff size: with Codemap, every changed function's transitive callers set an Impact: tier.
  3. FULL means the change reaches a public function outside tests and leaf modules (visualization, plotting, examples, docs); LIGHT means it stays off that path; untraceable impact counts as FULL.
  4. A FIX skips foundry:perf-optimizer + foundry:solution-architect only at LIGHT; CHORE skips foundry:qa-specialist, foundry:perf-optimizer, foundry:solution-architect.
  5. foundry:challenger runs at every diff size, and the review never collapses to the orchestrator alone.
  6. Codex co-review (if bridge@borda-ai-rig is installed and enabled): adversarial diff review seeds pre-flagged issues list for specialist agents.
  7. Selected parallel agents (file-based handoff — each writes handover files to .temp/review/<timestamp>/; the default cap is three spawn units, --full removes that cap; merged units write one findings file per dimension):
  8. foundry:sw-engineer: architecture, SOLID, type safety, error handling, Python anti-patterns, security for touched auth/input/data paths
  9. foundry:qa-specialist: test coverage gaps, missing edge cases, ML non-determinism, seed pinning, boundary conditions
  10. foundry:perf-optimizer: algorithmic complexity, loops that should be NumPy/torch ops, unnecessary I/O, ML DataLoader config (skipped for FIX diffs)
  11. foundry:doc-scribe: public APIs without docstrings, Google-style section gaps, CHANGELOG entries, deprecated stdlib usage
  12. foundry:linting-expert: ruff violations, mypy errors, type annotation gaps on public API, suppressed violations
  13. foundry:solution-architect: API design quality, coupling, backward compatibility (only for public API boundary changes; skipped for REFACTOR and FIX)
  14. Cross-validate critical + blocking findings using same agent type that raised each finding.
  15. Consolidate (foundry:sw-engineer): reads all findings, deduplicates, ranks by impact, writes full report to .reports/review/<timestamp>/review-report.md. Signal-to-noise gate: small modules not padded with low-severity findings.
  16. Codex-eligible findings (optional): mechanical tasks — docstrings, missing tests for concrete scenarios, consistent renames — are listed under Recommended Next Steps as Codex candidates. The review names them and never edits code itself; implementation stays with the fix workflow or the user.

Validation: /develop:review validates every candidate against allowed source evidence before publication and retains capped independent critical verification.

  • Version-one review-validation.json separates five source judgments, nullable completed assessments, missing reviewer coverage and verification readiness; unresolved concerns retain owner/next check/closure.
  • Minor changes include bounded, low-impact correctness, test and compatibility fixes with localized repair and verification. Major revision requires evidenced material behavioral impact or substantial repair, even if a serious defect needs only a small patch. The verdict cites final finding IDs, impact and repair scope; finding counts, CI status and reviewer votes do not set it automatically. Required fixes remain actionable under Minor, and no unresolved required source change normally means source approval with readiness reported separately. Documentation-only corrections and missing or additional tests normally remain Minor unless concrete material consequences or a substantially incomplete required deliverable justify more; missing tests alone do not establish a production bug. These factors inform one combined judgment: high-impact findings can control the verdict and are never diluted by minor items. Use the strongest confirmed consequence as the baseline, account for proven joint effects, and keep severity, source disposition and verification separate. Missing tests no longer receive an automatic High rating; numeric topic discounts require independent calibration before they can determine verdicts.
  • The workflow remains read-only: actual runtime authorization/capability boundaries are recorded, and feasible unfinished parent checks mean incomplete.

Report structure:

Critical (must fix)
Architecture & Quality
Test Coverage Gaps
Performance Concerns
Documentation Gaps
Static Analysis
API Design
Codex Co-Review
Recommended Next Steps
Review Confidence (per-agent scores)

Realistic example:

git add src/mypackage/trainer.py tests/test_trainer.py
/develop:review src/mypackage/trainer.py

Follow-up from review findings:

  • Blocking bugs or regressions → /develop:fix
  • Structural or quality issues → /develop:refactor
  • Security findings → /develop:fix; run pip-audit if dependency files changed
  • Mechanical issues (docstrings, missing tests) → when bridge@borda-ai-rig is available, construct an implement brief that states the exact finding, target paths, current evidence, permitted edits, required result, stop condition, and verification command.
  • GitHub PR review for contributor → /oss:review <PR#> (requires oss plugin) instead

/develop:setup

Purpose: Deliver this plugin's rules/*.md into Claude's user-level rule namespace. Maintenance command, not part of any development workflow.

Setup probes the bare python command only (no python3 or py -3 fallback), because every later step runs bare python.

When to use: after installing develop on a new machine, or after upgrading it. make sync-claude runs it automatically for every installed managed plugin that ships a setup skill, so a normal sync needs no manual step.

Invocation:

/develop:setup            # interactive — asks before replacing anything it does not own
/develop:setup --approve  # non-interactive — used by make sync-claude

Each rule installs as a symlink at ~/.claude/rules/develop-<source-name>.md. The develop- prefix keeps the flat rule namespace collision-free — four plugins ship a rules/quality-gates.md. Because all four then load into every session, setup installs only one variant at develop-quality-gates.md:

  • When a foundry-owned foundry-quality-gates.md is already delivered, it links rules/quality-gates-delta.md — this plugin's review-loop scope and output-routing sections only, with every shared obligation read from foundry's copy.
  • Otherwise it links the complete rules/quality-gates.md, so a standalone install loses no rule.
  • The form is chosen on each run: after /foundry:setup (requires foundry plugin) first delivers its rules, or after foundry is removed, re-run /develop:setup so the link switches form.

A filename prefix does not change how Claude loads a rule or how its paths: frontmatter matches (verified against Claude Code 2.1.220).

How rules are delivered:

  • Rules are symlinked, not copied: Claude loads rules at session start, so a symlink serves the installed version after every upgrade, while a copy would silently serve stale content forever.
  • Setup delivers only this plugin's own rules — each plugin installs independently, and shipping a sibling's rules would break standalone installation and couple releases. The delta variant keeps that true: it only points at foundry's copy for the shared obligations rather than delivering it.
  • Loading all four complete quality-gates.md copies at once cost 51,274 B of context on every turn.
  • Only links this plugin provably owns are replaced or removed: the existing target must resolve under the current plugin root or under the same install-cache lineage. A real file, a link into another marketplace, a source checkout, or a dotfiles tree is reported as a conflict and left alone unless you approve replacing it.

What the shipped quality-gates rule requires:

  • For explicitly requested iterative independent review/fix loops, the quality-gates rule requires the local _full/adversarial-loop.md procedure, including first-pass coverage, invariant and sibling-route closure checks, and separate carried/new finding weight. One bounded independent challenge does not automatically start that loop.
  • Confidence describes the correctness of the delivered result and how it was produced and checked within scope. Report completion separately; a high score does not pass an unmet gate.

🗺️ Workflow overview

Skills chain naturally. Typical session:

New feature

# 1. Scope — understand what you're building before building it
/develop:plan "add rate limiting to the API gateway"

# 2. Implement — TDD contract pins the API, then implementation follows tests
/develop:feature "add rate limiting to the API gateway" --plan .plans/active/plan_add-rate-limiting-api-gateway.md

# 3. Review before committing (optional — quality stack already ran, but useful for a final check)
/develop:review src/gateway/

Bug fix

# Option A: symptom is clear enough — go straight to fix
/develop:fix "RateLimiter raises AttributeError when Redis connection fails"

# Option B: mysterious failure — investigate first
/develop:debug "API gateway returns 200 on every request under high load"
# Debug writes: .plans/active/debug_api-gateway-200-high-load.md
/develop:fix "API gateway returns 200 on every request under high load" --diagnosis .plans/active/debug_api-gateway-200-high-load.md

Safe refactor

/develop:plan "extract request parsing into a dedicated middleware layer"
/develop:refactor "extract request parsing into a dedicated middleware layer" --plan .plans/active/plan_extract-request-parsing-middleware.md

Review before a PR

/develop:review    # reviews the full current diff (staged + unstaged vs HEAD)

Fork workflow (upstream issue)

Forked repo, want to fix/implement issue reported on original upstream. Pass --repo <owner/repo> to route issue fetch to upstream instead of fork:

# Debug an upstream issue in your fork
/develop:debug 88 --repo owner/my-project

# Fix it — skip debug if root cause is clear
/develop:fix 88 --repo owner/my-project

# Implement a feature request from upstream
/develop:feature 123 --repo owner/my-project

--repo accepted by fix, feature, debug, refactor. Affects only gh issue view call fetching issue body + comments — rest of workflow operates on local fork as normal.

Complex or high-stakes work

Add --team to any code-changing skill. Spawns parallel specialist agents exploring implementation space independently.

Significantly higher token cost — reserve for multi-module changes, public API additions, auth/payment/data scope.

  • In feature and refactor, the team path still runs the Step 5 quality stack and the final gate before the Final Report, and never reports the suite green earlier.
  • Every team mode (feature, fix, refactor, debug) needs ~/.claude/TEAM_PROTOCOL.md, which /foundry:setup (requires foundry plugin) writes.
  • Without it the run stops with ! BLOCKED before creating a run directory or spawning anyone — run /foundry:setup, or re-run without --team for the solo path.
/develop:feature "add streaming response support" --team
/develop:fix "memory leak in batch inference" --team

Isolated runs — --worktree

Add --worktree to run the entire skill inside a fresh git worktree under .claude/worktrees/ on a new branch based off your current HEAD (via git worktree add HEAD + the harness EnterWorktree/ExitWorktree tools — not origin/<default>).

  • The main working tree is never touched; on completion the skill leaves the worktree + branch on disk and reports the path/branch — you review and merge (never auto-merged).
  • Uncommitted working-tree changes do not transfer into a worktree — commit or stash first if the run must see them.
  • Available on feature, fix, refactor (all work stays in the worktree); opt-in on the read-only debug + review (isolation guards sources, but the diagnosis/report deliverable is written to the main tree so downstream skills + your review can reach it). Not on plan (analysis-only, never edits).
/develop:fix "off-by-one in token expiry" --worktree
/develop:refactor src/loader.py "extract batching" --worktree --team
  • Codemap alignment — the index path is anchored to the git top-level (<root>/.cache/codemap/<project>.json), not to the session CWD, and a linked worktree is its own top-level, so the index still resolves per-worktree (<worktree>/.cache/codemap/…) — and resolves identically from any subdirectory inside it.
  • Each run owns its own ephemeral index, so any number of parallel --worktree runs never share or race one index; .cache/ is gitignored so a worktree index never merges back.
  • After you merge the branch, the main index is flagged stale on the next prompt and refreshes once.
  • Composes with --team — the orchestrator worktree is the integration point; --team teammates run inside it without their own worktrees, so their edits and handoff files land there directly with no merge step.

Worktree cleanup:

  • A --worktree run never checks or asks about other worktrees up front.
  • Only when creating its own worktree still fails after one retry does it report leaked worktrees it could reclaim — clean, ≥14-day-old agent-*/oss-* trees, including directories git no longer has registered (git worktree prune cannot see those; it removes the inverse case) — and ask whether to remove them. Nothing is deleted without that answer.
  • Separately, with foundry installed, its SessionEnd hook removes clean agent-*/oss-* trees after 2 hours idle; dev-* trees and trees holding uncommitted or ignored run output are never swept.
  • Trees holding uncommitted work are listed and kept at any age, and your own dev-* trees are never candidates.

⚙️ Configuration

Dependencies by capability

Dependency Required Unlocks
foundry plugin recommended Named specialist agents. Without it, agent-router falls back to general-purpose with role-description prompts; develop's own quality-stack files still load.
oss plugin optional /oss:review <PR#> for contributor-facing GitHub PR review; /develop:review <PR#> offers it when oss is installed. Local review ships its own severity checklist and never needs oss.
bridge@borda-ai-rig optional Read-only adversarial pre-pass and bounded mechanical follow-up when installed and enabled; skipped with an explicit status when absent or disabled.
codemap-py optional Structural context such as callers, imports, test impact, and blast radius. Auto mode uses an available index; absent/stale indexes follow the Codemap gate, and --no-codemap disables it.
gh CLI optional Fetches issue bodies for numeric issue arguments and GitHub Actions logs for /develop:debug --ci-run; required only for those paths. 
! BREAKING — `--semble` is gone from `/develop:plan`, `/develop:feature`, `/develop:fix`, `/develop:refactor`, and `/develop:review`, and the `semble` MCP server is no longer a dependency of any develop skill. Passing the flag now trips the unknown-flag prompt instead of enabling a semantic-search preflight. Measured on the blast-radius benchmark, the semble arm lost to both the plain and codemap arms on cost, input tokens, and recall.
Fix: drop `--semble` from saved invocations; Codemap-py auto mode (below) supplies the structural context the preflight used to add.

Codemap-py behavior

In auto mode, Codemap-py prepares a missing or stale project index under the active provider contract; no flag is needed. Explicit confirm-first, frozen and skip preferences remain controlling. Each gate persists its result before later consumers reload it, including stale continuation without query-time refresh.

Disabling Codemap disables structural lookup only. Feature, fix, refactor and batch test loops still select tests with path/import heuristics, execute the selection and propagate failures.

State Behavior
Installed + current index + auto mode Use Codemap context
Installed + no index + auto mode Gate A follows the active provider: automatic preparation by default, explicit confirm-first/frozen preferences preserved
Installed + stale index + auto mode Gate B per the installed contract: codemap-py ≥ 0.39.0 refreshes automatically (asks only if LAZY_CODEMAP is set); older installs ask first
Not installed + auto mode Continue without Codemap
Any unavailable state + --codemap Stop and report strict-mode failure
Any state + --no-codemap Always disabled

--codemap = strict assertion — useful in CI or to guarantee structural context always applied. --no-codemap skips codemap for specific run (e.g. non-Python submodule).

Python tooling

The quality stack is shipped by develop and auto-detects the project's runner (uv, Poetry, tox, Make, or python -m pytest). Missing optional tools such as ruff or mypy are reported and skipped; the test runner remains the decisive verification step.

Hooks

Hooks register automatically from hooks/hooks.json when the plugin is enabled — no settings.json edits needed.

  • Each hook runs node from PATH, then /opt/homebrew/bin/node or /usr/local/bin/node; when none exists, the hooks skip without blocking and one SessionStart check reports once per session that they are inactive.
  • The plugin's bin/python and native Windows bin/python.cmd preserve the shipped python command and probe candidate runtimes for Python 3.10+ before executing the workload once.
  • Plugin bin/ follows system directories on PATH, so an eligible system python takes precedence; missing eligible runtimes produce a clear diagnostic.
Hook Event Behaviour
agent-router.js PreToolUse (Agent) Reroutes Agent() calls when the requested agent is not installed: exact match → semantic match → general-purpose.
allow-dispatch.js PreToolUse (Bash) The only registered Bash auto-allow hook. Asks two decision modules in rank order and emits the first allow: blueprint-allow.js (exact match against this plugin's committed blueprint-manifest.json, so verbatim bash shipped in its own skills runs without a prompt) then sentinel-read-allow.js (pre-canned TMPDIR sentinel-read and $(date +FMT) idioms inside read-only commands). Anything else falls through to normal permission checks; exits 0 on every path.
audit-close.js PostToolUse, PostToolUseFailure (Bash), SessionStart, SessionEnd Appends one audit record per completed Bash call and per session boundary; writes nothing to stdout.
write-guard.js PreToolUse (Edit, Write, NotebookEdit) Grants nothing — forces a confirmation on writes to untracked files in the protected set (CLAUDE.md/AGENTS.md, .claude/settings*.json, .pre-commit-config.yaml, pyproject.toml). A tracked protected file never asks; a protected file the session created asks once on creation. Source, tests, .github/**, CHANGELOG.md and lockfiles are unprotected.
stale-plugin-check.js SessionStart When this session still runs a replaced develop version, warns with the loaded and installed versions and the restart step (exit, then claude --resume <session_id>), and tells the model not to run develop workflows on the stale copy until the user chooses, through AskUserQuestion, to restart or continue — once per session and version. Silent when current; never blocks.
enforce-review-header.js PreToolUse (AskUserQuestion), PostToolUse (AskUserQuestion), Stop Blocks only the owning workflow follow-up until its report exists and the follow-up call's first question text is a short plain summary (report path, Title, Outcome/Verdict; at most 1,500 characters, no table). Diagnostic/recovery questions remain available; unreadable delivery evidence is not success. On Stop: keeps a turn going once per report when its final reply lacks the full header table.
report-header-table.js Shared local module Shared local module (source): matches workflow-specific questions and current report headers; at question time checks only the call's first question text, at Stop only the final reply after the turn's last tool call.
blueprint-allow.js Decision module of allow-dispatch.js Exact-matches a normalized Bash command against the committed blueprint-manifest.json, so verbatim bash shipped in this plugin's skills runs without a prompt.
sentinel-read-allow.js Decision module of allow-dispatch.js Auto-allows pre-canned TMPDIR sentinel-read and $(date +FMT) idioms inside read-only commands.
lib/audit-log.js Shared module Append-only record writer behind allow-dispatch.js and audit-close.js; never throws, so a logging failure cannot change a permission decision.

Hook decisions are logged: allow-dispatch.js and audit-close.js append one JSON line per Bash call to ~/.claude/logs/audit/ (see Auto-allow audit log).

Artifact directories

Skills write to these dirs at project root (all gitignored):

Directory Contents
.plans/active/ Plan files from /develop:plan, diagnosis files from /develop:debug
.developments/<timestamp>/ Checkpoint files for resumable feature/fix/refactor sessions; targeted-test records (test-targets.jsonl) and full run logs
.temp/review/<timestamp>/ Per-agent handover files (intermediate) from /develop:review
.reports/review/<timestamp>/ Consolidated final report from /develop:review

Completed runs cleaned after 30 days. Interrupted runs (no result.jsonl) kept for debugging.

🔍 Troubleshooting

"foundry plugin not installed — named-agent fallback"

Not installed → named-agent dispatch falls back to general-purpose; the develop-owned quality stack still runs. Install foundry when you want its specialist agents.

A question is blocked with "develop:review report gate"

Blocks only the owning workflow follow-up until its report and matching current-turn header table are verified. Diagnostic/recovery questions remain available; unreadable delivery evidence is not success. Finish the producer, print the required current output, then retry the workflow follow-up. Existing sentinel expiry remains unchanged; it is not a completion receipt.

Demo gate passes (exit 0) when it should fail

/develop:feature Step 2 confirms demo fails before implementation. Gate exits 0 → feature may already exist, or test tests wrong thing. Skill stops, asks revisit Step 1. Do not force past gate — means feature exists already or demo not testing intended contract.

Regression test gate passes when it should fail

Same pattern in /develop:fix Step 2. Regression test passes on unfixed code → test not capturing bug. Revisit Step 1 — symptom description not pointing at actual failure site, or test exercises different code path.

Characterization test fails on unmodified code

/develop:refactor Step 3: characterization tests must pass before refactoring begins. Characterization test fails → test wrong — must assert current behavior, not desired. Fix test to match what code actually does now.

A spawned agent shows ⏱ timed out

Skills never poll a background agent; they resume on its completion notification. Each spawn arms a deadline (agent_watch.py); an agent whose notification arrives without its expected output, or that a later wake-up finds past its deadline, is marked ⏱ timed_out at once and named in the report. Analysis and test-writing work is then done inline; a timed-out challenger asks you to retry it, proceed unchallenged, or abort — it is never counted as a clean pass.

Session interrupted mid-skill

feature, fix, refactor write checkpoint file to .developments/<timestamp>/checkpoint.md after each major step. Re-running same skill command offers resume from last completed step.

codemap-py query warnings appearing in output

codemap-py is optional; codemap-py not on PATH → all codemap-py steps silently skipped and the skill works fully without it.

  • The gate and context contracts are read live from the installed codemap-py plugin (bin/resolve_shared_path.py codemap-py claude-skills/_shared, install record first) — no local copy, so upgrading codemap-py upgrades the contract develop follows.
  • Plugin installed but index missing → Gate A follows the installed provider contract: current providers prepare automatically, while explicit LAZY_CODEMAP and SCAN_NO_AUTOBUILD=1 preferences remain controlling.
  • Index stale → Gate B follows the installed contract: codemap-py ≥ 0.39.0 rebuilds automatically, no prompt unless LAZY_CODEMAP is set; older installs ask first.
  • --no-codemap skips silently either way.
  • To enable Codemap context, install the codemap-py plugin; current providers prepare the index on ordinary structural lookup (requires codemap-py plugin).

🙏 Contributing / feedback

Plugin part of borda-ai-rig suite. Canonical source in plugins/cc_develop/ within repository.

Report bug or suggest improvement: open issue in repository. Include skill name, invocation used, actual vs expected behavior.

To update the plugin:

claude plugin install develop@borda-ai-rig

To uninstall:

claude plugin uninstall develop

Uninstall leaves rule links behind: Claude Code runs no cleanup hook on uninstall, so ~/.claude/rules/develop-*.md survives both claude plugin uninstall and make clear-all. Delete those symlinks by hand — once the plugin cache version is gone they dangle.

Skills, rules and hooks:

Skill Purpose
/develop:plan Scope a task: classification, complexity, risks
/develop:feature TDD-first feature development
/develop:fix Reproduce-first bug fixing
/develop:refactor Test-first refactoring with a safety net
/develop:debug Investigation-first root-cause diagnosis
/develop:review Local Python review across multiple dimensions
/develop:setup Deliver this plugin's rule symlinks
Rule Purpose
rules/quality-gates.md Complete quality gates; delivered as develop-quality-gates.md
rules/quality-gates-delta.md Develop-specific delta, linked instead when foundry delivers its copy
rules/_full/adversarial-loop.md Procedure for explicitly requested iterative review/fix loops

Hooks: see the Hooks table.

Plugin structure:

plugins/cc_develop/
├── .claude-plugin/    -- plugin.json manifest and permissions-*.json manifests
├── assets/images/     -- animated execution diagrams
├── bin/               -- deterministic helper scripts
├── hooks/             -- hook registrations and modules
├── rules/             -- quality-gates.md (delivered as ~/.claude/rules/develop-quality-gates.md)
└── skills/            -- plan, feature, fix, refactor, debug, review, setup (one SKILL.md each)

Permission manifests (merged into ~/.claude/settings.json by /develop:setup, Step 5):

  • .claude-plugin/permissions-allow.json lists the tool calls the skills expect to be pre-approved.
  • .claude-plugin/permissions-allow-retired.json lists allow rules earlier versions shipped; /develop:setup removes exactly those from settings.json through --drop-allow-file, keeping the rule text out of the command line. The setup summary counts removals from this complete retirement set.
  • .claude-plugin/permissions-deny.json is its counterpart — the operations that must stay denied no matter how broad the allow list becomes: destructive shell and git commands (rm -rf, sudo, ssh, chmod 777, force-push, claude --dangerously-skip-permissions). It holds no gh write or local branch/tag deletion entry.
  • The merge is otherwise additive and idempotent: setup removes the obsolete Bash(gh api repos/*:*) allow entry and the broad Bash(claude:*), Bash(find:*), Bash(node:*), Bash(sed:*) and Bash(eval:*) entries while preserving every other existing allow and deny entry. Deny entries are prefix matches, so they stop the documented command forms rather than every possible flag ordering.

Develop ships no git/gh guard; foundry supplies that guard (requires foundry plugin). Develop's allow list omits Bash(gh api repos/*), Bash(gh api graphql:*), Bash(git branch:*), and Bash(git tag:*). Without foundry or other matching user rules, these command families reach normal permission handling on new installs, including prompts for routine reads such as git branch --show-current.

Upgrades preserve these four allow entries in existing settings if an older setup merged them. /develop:setup does not remove them because foundry ships the same strings; without foundry, remove them manually from ~/.claude/settings.json to restore prompts. Stale gh deny entries from older versions are cleaned only by /foundry:setup (requires foundry plugin).

🧰 Bin helper inventory (main helpers)

The bin/ directory holds 40 deterministic helpers; this table lists only the main ones; the full inventory is in DEVELOPMENT.md.

  • They are installed workflow support, not additional slash-command skills.
  • The skills own the development workflow; the helpers handle bounded flag parsing, Codemap context, test execution, worktree setup, path resolution, and state extraction.
  • The subset below is what users most often meet in run output or settings; the rest parse flags, resolve Codemap and shared paths, fetch issues, and write compaction contracts.
Helper Purpose
dev_run_dir.py Create a timestamped .developments/ run directory and optional sentinel.
dev_test_targets.py Select the tests a change touches; --run runs them in one call.
dev_run_tests.py Run the project's test command from its session sentinel without a shell; child exit status is passed through, exit 64 when no test command ran.
dev_run_repro.py Reproduce a bug with the allow-listed pytest runner; only pytest exit 1 is reproduced, other non-zero is ! GATE ERROR.
plan_hash.py Record a --plan file's hash and flag edits made during the build.
resolve_review_target.py Resolve a review target and its changed Python files; --committed diffs HEAD~1..HEAD.
adversarial_loop.py Record and validate review → fix loop rounds, print the progress table, and stop a repeated finding at its third occurrence.
agent_watch.py Report each spawned agent's deliverable and deadline in one call.
extract_json_field.py Recover a JSON object from text and print a selected field.
sync_rules.py Install namespaced rule symlinks into ~/.claude/rules/.
merge_settings_permissions.py Merge the plugin's shipped allow and deny rules into ~/.claude/settings.json in one atomic write (/develop:setup).
verify_blueprint_audit.py Verify and prune the auto-allow audit log.

Auto-allow audit log

allow-dispatch.js and audit-close.js append one JSON line each per Bash call to ~/.claude/logs/audit/: one file per session (s-<key>.jsonl, the key being a hash of the session id) plus a shared _no-session.jsonl for calls that arrive without one.

  • A record names the deciding plugin and hook, the session and tool-call ids, the working directory, the effective decision with its lane and provenance, and both decision modules' own verdicts.
  • Command text is never written — only a digest, and for a provenance allow the manifest src it matched. task-log.js already writes the first 200 characters of every Bash command into timings.jsonl; that text is masked first (env assignments, credential-named values and flags, URL credentials, Bearer values, well-known token prefixes), and task-log.js tightens the log directory to 0700 and log files to 0600.
  • With several plugins installed each writes its own rows and nothing coordinates them, so one completed call yields one row per plugin at each end. That is corroboration, not duplication.
  • RIG_AUDIT=0 disables audit writing without changing any permission decision.
python "${CLAUDE_PLUGIN_ROOT}/bin/verify_blueprint_audit.py" verify
python "${CLAUDE_PLUGIN_ROOT}/bin/verify_blueprint_audit.py" prune --older-than 30 --dry-run
  • verify exits 1 only when a record's own hash fails to verify; torn framing from concurrent appends and every classification are warnings. record_hash detects a record that changed after it was written — it is not tamper-evidence, because the same user owns the log, the hooks and the checker.
  • A call with a decision row and no completion row is reported as completion-unobserved when the session later ended and in-flight-or-hard-kill when it did not; neither distinguishes a refusal at the prompt from a deny rule elsewhere or a closer that died. That a tool ran never establishes that a human approved it.
  • prune is the only component that deletes a log file, is never run by a hook, and never prunes _no-session.jsonl by age — a growing one means the host stopped sending a session id. Nothing schedules prune.

Modify any skill → update this README before finishing — unsynced change = incomplete change.

Evidence and real-case acceptance: shipped rules/quality-gates.md requires cited proof for factual, causal and completion claims, a representative real case alongside TDD, and unchanged user-authorized behavior. Mocks are supplementary polishing after real behavior is validated; unavailable real acceptance stays explicit.