cuioss/dev-general-practices

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/general-development-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 (Grep modes, filtering), 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.

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 (e.g., MY_VAR=value python3 some_command.py ...) is forbidden for two reasons: it combines the assignment and the command into a single shell argument, which trips the host platform's permission UI and produces a security prompt; and it obscures the env-var contract by hiding the variable inside the command line rather than declaring it explicitly.

Anti-pattern: MY_VAR=value python3 some_command.py ...

Safe alternative (option A) — Pass the value as a flag arg:

python3 some_command.py ... --my-var value

Safe alternative (option B) — Set the env var in the command's invocation header (e.g., a separate env MY_VAR=… line, NOT inline) before launching the bash command, or define the value as a Python module-level constant lookup inside the script itself.

Bash: No file operations

Never use Bash for file discovery or reading. Use the structured architecture inventory first (architecture files --module X, architecture which-module --path P, architecture find --pattern P); 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. See "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.

Structured queries first

Before reaching for Glob or Grep for codebase navigation (file discovery, module identification, path resolution), consult the structured architecture inventory via architecture files --module X, architecture which-module --path P, or architecture find --pattern P. 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 general-development-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.

Why: Lesson 2026-04-29-23-002 documents three recurrences in ~3 days (lesson-2026-04-29-08-003, phase-a-arch-split, phase-c1-diff-modules) where skill workflows and orchestrators referenced renamed/removed CLI shapes. Each recurrence produced multiple wrong_parameters argparse rejections that the calling workflow swallowed silently. The same failure mode hit phase skills, the retrospective orchestrator, and the execute-task fix-and-retry path — confirming the failure is structural, not specific to any one skill.

How to apply: When in doubt, invoke the script with --help first (python3 .plan/execute-script.py {notation} --help and python3 .plan/execute-script.py {notation} {subcmd} --help), or grep .plan/execute-script.py's embedded SCRIPTS = { ... } mapping. The ARGUMENT_NAMING_* plugin-doctor rule cluster (unconditionally active per lesson 2026-04-29-23-002) catches drift at edit time as the structural guard against this class of failure.

Git: always use git -C {path}, never cd {path} && git ...

Every repo-targeted git command MUST use the git -C {path} <subcommand> form. The compound form cd {path} && git <subcommand> is 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. The -C form does not trip the heuristic.
2. One-command-per-call: cd {path} && git ... is two commands joined by &&, which already violates the Bash: One command per call rule above. Using git -C {path} ... is one command and satisfies both rules at once.

When a plan runs in an isolated worktree, the canonical {path} is the worktree absolute path surfaced by plan-marshall:phase-5-execute in its [STATUS] Active worktree: ... work-log line. When operating against the main checkout, use git -C . — never cd && git.

Related

• dev-general-code-quality — Complementary quality standards (SRP, CQS, complexity)
• dev-general-module-testing — Testing methodology standards (AAA pattern, coverage)

Standards Reference

| Standard | Purpose | |----------|---------| | general-development-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 |

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.