Development Practices Skill

REFERENCE MODE: This skill provides reference material. Load specific standards on-demand based on current task.

Foundational development practices applicable across all technology stacks and development activities. Covers when to ask users, how to research best practices, proper tool usage, document management, and dependency governance.

Workflow

Step 1: Load Core Development Rules

Important: Load this standard at the start of any development work.

Read: standards/agent-behavior-rules.md

Covers Boy Scout Rule, decision tree for when to ask users, research patterns, tool selection guide, document proliferation guidelines, and dependency approval.

Step 2: Load Tool Usage Standards (As Needed)

Tool usage patterns (load for file operations, content search, or automation work):

Read: standards/tool-usage-patterns.md

Covers tool selection guide, file operations (discovery, existence checks, validation), content search patterns (architecture search --content first, Grep as the qualified fallback), Bash safety rules (one command per call, no shell constructs, no heredocs), and build command resolution via architecture API.

Step 3: Load Script Argument Naming Conventions (As Needed)

Script argument naming (load when authoring or invoking plan-marshall manage-* scripts):

Read: standards/argument-naming.md

Covers typed-ID flags (--lesson-id, --plan-id, --task-number, --module, --component), read-verb canonicalization (read vs get vs exists), --module vs --name, and Python-stdlib log-level naming. Includes the canonical-forms table for in-scope manage-* scripts.

Step 4: Load the Coverage Contract (As Needed)

Scope × thoroughness (load for any coverage-class work — sweeps, audits, refactors, refines, and any task whose value comes from how completely it covered a surface):

Read: standards/thoroughness.md

Covers the orthogonality of effort and thoroughness, the thoroughness ladder (T1–T5), the scope ladder, the grade-to-the-floor rule, the coupling constraint reject thoroughness ≥ T4 ∧ scope < component, and the floor-graded self-report.

Step 5: Load the Coverage-Gathering Contract (As Needed)

Coverage-gathering contract (load when building or modifying a broad-pass component — a wide audit, compliance sweep, simplification/refactor campaign, or pre-submission review — that gathers a coverage cell from the user and consumes it to govern its breadth/depth):

Read: standards/coverage-gathering-contract.md

Covers the reusable two-dial contract that broad-pass components implement: the canonical AskUserQuestion gather shape, the static cell→instruction expansion table (the operational instruction per cell), the gather→expand→consume obligation, the status.json persistence + transport mechanism (identifier + expanded instruction, mirroring compatibility + compatibility_description), and the Current-Implementations table. thoroughness.md defines the LEVELS; this contract's expansion table defines the OPERATIONAL INSTRUCTION per cell (no duplication).

Hard Rules (never override)

Bash: One command per call

Each Bash tool call must contain exactly ONE command. Never combine with newlines, &, &&, ;, or inline env-var assignment of the form VAR=val cmd.

The VAR=val cmd shape trips the host platform's permission UI and obscures the env-var contract. Pass values as flag args instead, or set the env var in a separate invocation header outside the command line. See standards/tool-usage-patterns.md § Env-var dispatch in Bash for the full anti-pattern walkthrough and both safe alternatives.

Bash: Timeout from architecture-resolved canonical command

When invoking a build/verify canonical command (resolved via plan-marshall:manage-architecture:architecture resolve or via a workflow step that surfaces the canonical envelope), inspect the resolved TOON for bash_timeout_seconds and execution_tier fields:

• execution_tier: per_task — the Bash call runs synchronously inside the current dispatch. Pass timeout: bash_timeout_seconds * 1000 (milliseconds) on the Bash tool call. Never accept the default 2-minute Bash timeout for these commands; the host platform will silently auto-move the call to background and the dispatch will lose the synchronous-return path.
• execution_tier: orchestrator — the canonical command is owned by the orchestrator (e.g. long-running module-tests/verify/coverage on a worktree that the orchestrator drives). Sub-agents MUST NOT invoke the command via Bash from inside the dispatch. When the loaded workflow documents a hand-off step, follow it; otherwise return control to the orchestrator (with a TOON indicating the command cannot run within this dispatch) so the orchestrator can dispatch the build in its own envelope with the correct timeout.

The floor for ad-hoc build/verify invocations outside the architecture-resolved envelope is 600000ms (10 minutes); the architecture-resolved bash_timeout_seconds always supersedes the floor.

The recurrence signature and orchestrator-tier rationale are documented in the adaptive-timeout infrastructure design.

The 🔨 build-busy terminal-title bracket around such a call is machine-owned and carries no agent obligation: the PreToolUse:Bash render hook sets the token when a build-wrapper invocation enters and the paired PostToolUse:Bash hook clears it when the call exits, both on render events that deliver the repaint. Do NOT hand-write a title-token set/clear pair or a session push-title-token call around a build — see manage-terminal-title/standards/terminal-title-architecture.md § Channel Delivery Contract.

Bash: No file operations

Never use Bash for file discovery, reading, or content search. Use the structured architecture inventory first (architecture files --module X, architecture which-module --path P, architecture find --pattern P for a path glob, architecture search --content --pattern P for file content); fall back to Glob, Grep, Read when narrowing to sub-module components, scanning content inside an already-known file, or when the architecture verb returns elision. grep and git's grep subcommand via Bash are never the answer — see `manage-architecture/standards/client-api.md` § search for the content-search contract, and "Structured queries first" below for the full rule.

Skill workflow: No improvisation

Execute ONLY the commands documented in the loaded skill's workflow. Never add discovery steps, invent arguments, or skip documented steps.

Skill mode: comply with the declared archetype

Every skill declares its execution archetype in its frontmatter mode field (knowledge / workflow / script-executor / manifest) — the sole source of truth for how it is consumed. Read the loaded skill's mode and comply: knowledge → load for context, never execute its body as instructions; workflow → follow the documented steps verbatim (the "Skill workflow: No improvisation" rule above); script-executor → drive the documented executor scripts and route on TOON status; manifest → treat as a read-only contract modified only via the Extension API. See `agent-behavior-rules.md` § Skill mode: comply with the declared archetype for the full per-value contract; the field taxonomy is owned by `pm-plugin-development:plugin-architecture` frontmatter-standards.md.

Structured queries first

Before reaching for Glob or Grep for codebase navigation (file discovery, module identification, path resolution, content search), consult the structured architecture inventory via architecture files --module X, architecture which-module --path P, architecture find --pattern P (matches the PATH), or architecture search --content --pattern P (matches the file BODY). Glob/Grep are the fallback for sub-module component lookup, content searches inside an already-known file, or when the architecture verb returns elision — not the routine first choice. See `agent-behavior-rules.md` § Structured queries first for the full rule and a worked example.

Never invent script subcommands

When issuing python3 .plan/execute-script.py {notation} {subcmd} ... calls, quote the subcommand and flag names verbatim from the executor mappings or the script's --help output. Never extrapolate plausible-sounding verbs (add-fix-task, read-context, tail, --filter-status, --tail) from surrounding workflow prose. Plausible names that match the workflow's narrative but not the actual argparse declaration produce silent exit_code: 2 failures that bypass the script body and corrupt downstream behaviour. When in doubt, invoke the script with --help first, or grep .plan/execute-script.py's embedded SCRIPTS = { ... } mapping.

The four canonical argparse-rejection recurrence signatures (verb-paraphrase, verb-scoped --plan-id/--project-dir, doubled bundle-prefix, missing --phase / --resolution-vs---status) with their concrete invented-vs-canonical examples, the accepted read-verb aliases carve-out, and the authoring contract live in `agent-behavior-rules.md` § Never invent script subcommands — recurrence signatures. The ARGUMENT_NAMING_* plugin-doctor rule cluster (unconditionally active under quality-gate) is the structural edit-time guard against this class.

Subagents are leaves — no further dispatch

You may be running inside a dispatched execution-context envelope. A dispatched subagent is a leaf — it cannot spawn further subagents (no further subagent dispatches; Task: is the Claude tool name for that dispatch, task on OpenCode). All cross-envelope dispatch originates only from the main-context orchestrator. When a workflow step calls for a further dispatch, return control to the orchestrator with the signal it needs (the workflow's declared return payload); do not attempt the dispatch yourself. In-context skill loading is permitted — loading a named skill into the current context (the Skill: directive on Claude, the skill tool on OpenCode) is in-context skill loading, not subagent dispatch.

Canonical contract: `ref-workflow-architecture/standards/agents.md` is the single source of truth for the leaf/dispatch-topology invariant. Do not restate the topology diagram here — see that document for the normative statement.

Git targeting: plain git in a cwd-pinned context, git -C {path} cross-tree, never cd {path} && git ...

The cd {path} && git <subcommand> compound form is always forbidden — even when the target path is a worktree absolute path that the model already has in context. Two reasons, both load-bearing:

1. Security prompt: the host platform treats cd followed by git in the same Bash call as a potential bare-repository-attack pattern and pops a permission prompt that disrupts the user.
2. One-command-per-call: cd {path} && git ... is two commands joined by &&, which already violates the Bash: One command per call rule above.

The git-targeting form to use depends on the execution context:

• Phase-5+ cwd-pinned context (the move-based, cwd-pinned model, ADR-002): cwd is pinned to the plan's worktree (or to the main checkout when use_worktree=false), so plain git <subcommand> already acts on the correct tree. Use plain git — do NOT route through git -C {worktree_path}. The pinned cwd is the resolution anchor; explicit path forwarding is redundant and re-leaks the worktree absolute path the cwd-pinned model deliberately removed. See `tools-script-executor/standards/cwd-policy.md` § "Worktree-path passing is unnecessary under cwd-pinning".
• Cross-tree or non-pinned context: when a git command must target a tree that is NOT the pinned cwd — a genuinely cross-tree operation, a main-checkout-from-worktree read, or any caller invoked outside a pinned-cwd context (phases 1-4, post-worktree-removal cleanup, fixture-driven invocations) — use the explicit git -C {path} <subcommand> form. This is the only surviving use of git -C.

When operating against the main checkout outside a pinned context, plain git (cwd already the main checkout) or git -C . are both acceptable — never cd && git. See workflow-integration-git/standards/worktree-handling.md for the worktree-specific application of this rule.

Related

• ref-code-quality — Complementary quality standards (SRP, CQS, complexity)
• persona-module-tester — Testing methodology standards (AAA pattern, coverage)

Standards Reference

Standard	Purpose
agent-behavior-rules.md	Boy Scout Rule, ask users, research, tool usage, dependencies
tool-usage-patterns.md	Tool selection, file operations, content search, Bash safety, build resolution
argument-naming.md	Typed-ID flags, read-verb canonicalization, --module over --name, stdlib log-level names for manage-* scripts
thoroughness.md	Scope × thoroughness coverage contract: thoroughness ladder (T1–T5), scope ladder, grade-to-the-floor rule, coupling constraint reject thoroughness ≥ T4 ∧ scope < component, floor-graded self-report
coverage-gathering-contract.md	The reusable coverage-gathering contract: canonical AskUserQuestion gather shape, the static cell→instruction expansion table, the gather→expand→consume implementor obligation, status.json persistence (identifier + expanded instruction), Current-Implementations table

See Also

• `extension-api:dispatch-granularity` — Dispatch granularity heuristics (10K rule, script-over-dispatch, bundle-over-iterate, per-iteration only when models differ or parallel; find the LLM core). Lives in extension-api because it governs decisions about the execution-context extension point.