jaw-dev

# Dev — Common Development Guidelines Rules applied to every sub-agent, regardless of role. ## §0.0 Work Classifier (C0-C5) **Classify every task before choosing process depth** (DEV-CLASS-01). The class selects planning, reading, and verification depth — never apply maximum process by default. | Class | Name | Signals | Default Process | |-------|------|---------|-----------------| | C0 | Trivial Text | Typo, comment, copy, log string — zero behavior change | Direct fix + smallest proof (§0.1) | | C1 | Single-File Local | One file, local behavior, no new abstractions | Fast path (§0.1) + targeted check | | C2 | Ordinary Product Slice | Conventional endpoint, form, table, model, list/detail screen, integration touchpoint | Compact plan + adjacent convention search + focused tests + micro-audit (orchestration mode) | | C3 | Cross-Domain Feature/Refactor | Multiple modules, public API, shared types, broad behavior | Compact or full PABCD depending on persistence/risk; employee audit per `dev-pabcd` Phase Skip conditions | | C4 | High-Risk | Auth, payments, data deletion, migration, release, permission model, security boundary | Full PABCD (mandatory) + full relevant gates + durable risk/evidence record | | C5 | Research/Ambiguous | Unclear requirements, ambiguous user value, unknown territory after one §0 clarification round | Interview/research first (`cli-jaw orchestrate I`), then reclassify | **Tie-break (DEFAULT):** when signals match two classes, the higher class wins. A conventional route→service→storage slice still counts as C2 even though it spans files; C3's "multiple modules" means crossing a module/package boundary beyond that conventional slice. **C4-promotion triggers override any fast path** (DEV-ESCALATE-01): security, data deletion/migration, destructive ops, public contract change, release surface, permission model, new dependency/framework. Any of these promotes the **affected part** of the task to C4-level care — split it out rather than inflating the whole slice. Promotion alone does not force a user question; stopping to ask is required only for rules individually classed **ESCALATE** (§0.2). Classifier eval cases: `evals/classifier_cases.json` — run when tuning trigger/classification behavior; track false promotions and demotions separately. ## §0.1 Patch Fast-Path (C0/C1) For **C0/C1 work** (one file, no new abstractions, local behavior — a ≤5-line edit is an example, not a limit): - Skip: §0.5 convention discovery, §1.5 pre-write search, reference file reading - Keep: §3 verification gate, §4 change documentation — including the numbered record doc in the owning implementation unit, mandatory for ALL work (UNIT-RESIDENCE-01, `dev-pabcd` §3.1), §5 safety rules (imports/exports), §7.2 static analysis - Role skills: read only the SKILL.md routing table — skip references unless the table explicitly routes to one This is scope guidance, not an exemption. Conventions visible in the touched file still apply even when proactive discovery is skipped. Promotion is **behavioral**, not territorial: a patch escalates when it can alter an auth/payment/deletion or other DEV-ESCALATE-01 path — not merely because the file lives there. A zero-behavior edit (comment, typo, log string) inside an auth file stays C0; any edit touching executed logic in such a path is not C0/C1 — reclassify and read the relevant reference. ## §0.2 Rule Classes Every rule in the dev skill family carries one severity class. When unmarked, treat prohibitions (⛔/MUST/NEVER) as STRICT and everything else as DEFAULT. - **STRICT** — always applies; violating it blocks completion (safety, broken builds, secrets). - **DEFAULT** — apply unless a documented, stated reason says otherwise. - **HEURISTIC** — judgment guide; deviation needs no justification, just awareness. - **STYLE_SAMPLE** — illustrative example or preset only. Examples illustrate acceptable choices but MUST NOT become universal requirements (DEV-STYLE-SAMPLE-01). - **ESCALATE** — stop and ask the user before proceeding. ## §0.3 Methodology Overlays (task_tags) Methodologies are **conditional overlays, never universal**. They activate via dispatch `task_tags`, explicit user request, repo convention, or a matching strict trigger — required evidence applies only when the strict trigger applies (low-risk/local work uses the smallest proof that validates the claim, with the reduced scope stated). | Tag | Loads | Strict trigger | |-----|-------|----------------| | `tdd` / `testing` | dev-testing | User/repo enforces TDD, or regression risk | | `bdd_acceptance` | dev-testing, dev | Ambiguous acceptance behavior | | `ddd` / `clean_arch` / `hexagonal` / `architecture` | dev-architecture, dev-backend | Real boundary pressure at C3/C4 | | `vertical_slice` | dev-architecture, dev-backend, dev-frontend, dev-testing | Thin end-to-end slice (C2) | | `adr_rfc` | dev-architecture, dev-scaffolding | Significant decision, domain vocabulary, or ADR source-of-truth work | | `review` / `code_review` | dev-code-reviewer | Review requested or C3/C4 | | `threat_model` / `security` | dev-security | C4 security/data/tooling risk | | `observability` / `observability_pipeline` | dev-backend (+dev-data) | Production, incident, release, long-lived runtime | | `debugging` / `debugging_rca` | dev-debugging | Repeated failure needs root cause | | `migration_backfill` | dev-data, dev-backend, dev-testing | Production or non-trivial data | | `product_discovery` (+`_ui`) | dev (+dev-uiux-design) | Ambiguous behavior/user value/metric/prototype intent | | `release_cd` | dev-testing, dev-backend, dev-scaffolding, dev-devops | Release/CI/CD surface | | `devops` / `infra` / `deploy` | dev-devops | Container/K8s/IaC/deploy pipeline/SRE | | `mobile_native` | dev-frontend + dev-uiux-design + dev-backend (refs) | RN/Flutter/Swift/Kotlin native app | | `ml` / `ai` / `llm` / `rag` | dev-backend + dev-data + dev-testing (+dev-devops) | ML serving, RAG, pipeline, evaluation | | `frontend_ui` | dev-frontend + dev-uiux-design | UI/design intent or runnable prototype variant work | | `crud_fullstack` | dev-backend, dev-frontend, dev-testing | Boss/direct planning signal only — when delegating, prefer split roles | | `logging` (CLI / scripts / libraries) | jaw-dev `references/logging.md` | What to emit and where; service instrumentation stays with jaw-dev-backend | | stacked pull requests (`DEV-STACK-*`) | jaw-dev `references/stacked-prs.md` | When to stack, cascade discipline, layer shape, review scope, bottom-up merge safety | | recall lookup (`DEV-RECALL-01`) | jaw-dev `references/recall-lookup.md` | Where to search before asking the user | | browse / QA ladders | jaw-dev `references/browse-qa-ladders.md` | Which surface opens a page, and why the two orders are opposite | | rule-area ownership | jaw-dev `references/skill-ownership.md` | Which skill is authoritative for a rule area; consult before adding one | | sub-agent skill injection and discovery | jaw-dev `references/skill-injection-and-discovery.md` | Naming skills in a dispatch packet; authority over a discovered skill | Tags are normalized `task_tags`, **not** employee `role` values; the execution role stays `frontend|backend|data|docs` (PROMPT-ROUTING-01). The boss sets `task_tags` at dispatch. With no tags, only strict triggers (self-assessed by the employee, reduced scope stated) activate overlays — legacy dispatches without the field behave identically. `task_tags` must be an array; a bare string is coerced to a single tag, and unknown tags are surfaced in the prompt, not silently dropped. ### Ordinary product reference (on-demand) For C2 ordinary product slices, the recipe lives in `references/product/crud-product-development.md` — read it when building a conventional feature slice, not for every task. ## §0.4 Workflow Modes The same rules flex by execution mode — know which one you are in: ordinary chat (direct work, C0-C2 typical) · strict PABCD (`orchestrate P/A/B/C/D`) · goal mode (self-advancing gates, evidence-backed checkpoints) · isolated employee (read-only verifier by default) · mutable employee (`--mutable`, scoped writes) · read-only review (no mutation, findings only) · docs-only work (no code gates, docs consistency checks instead). In goal mode, multi-phase / "loop"/"루프" work runs one FULL PABCD cycle per work-phase (depth scaled by §0.0 class); after D, re-enter P for the next work-phase. Classify EACH work-phase independently — C0-C1 fast-path applies to that work-phase's class, not the whole goal. Do each PABCD-phase's real work; never rubber-stamp a phase to advance. Work-phases chain HETEROGENEOUS units: a completely different feature or "the next plan" is simply the next cycle at P in the SAME session (LOOP-UNIT-CHAIN-01, `dev-pabcd` §5/§11.6) — "needs its own PABCD" never means ending the goal or waiting for a new session. **Production surface (shared definition):** deployed for real users beyond the author; prototypes, spikes, and internal demos are not. Skills that scope rules to "production-surface" concerns condition on this definition. ## Companion Skills This skill covers universal guidelines. **STRICT (DEV-ROUTE-01):** for domain-specific work, also read the matching role skill's `SKILL.md` before writing code in that domain: | Skill File | Injected When | Covers | | ---------------------------- | --------------------------------- | ------ | | `dev-frontend/SKILL.md` | `role=frontend` | UI implementation, responsive, anti-slop | | `dev-backend/SKILL.md` | `role=backend` | API/architecture, data access, ops | | `dev-data/SKILL.md` | `role=data` | Pipelines, data quality, analytics SQL | | `dev-security/SKILL.md` | Security-sensitive code, or `security`/`threat_model` task_tags | OWASP, auth, secrets, supply chain | | `dev-testing/SKILL.md` | `testing`/`tdd` task_tags, or testing phase | Test strategy, Playwright, contracts, CI | | `dev-debugging/SKILL.md` | Debugging phase (phase 4) | Root-cause method, instrumentation | | `dev-code-reviewer/SKILL.md` | Any agent, during code review | Review process, severity, antipatterns | | `dev-architecture/SKILL.md` | Module boundary work, dependency analysis | Cycles, coupling, barrels, validation placement | | `dev-uiux-design/SKILL.md` | Vague design direction, UX state patterns | Intent discovery, design vocabulary, UX states | | `dev-scaffolding/SKILL.md` | New project/feature setup, structural audit, docs generation | Lidge Standard, colocation, devlog | | `dev-pabcd/SKILL.md` | Orchestrated multi-phase development | PABCD phases, gates, attestation | ### Skill Ownership Map Each rule area has exactly one canonical owner. Other skills may contain stubs but MUST NOT duplicate canonical content. The full table is in `references/skill-ownership.md` — consult it before adding a rule area, and add a row when you do. A rule area with no recorded owner is how the same guidance ends up written twice in two skills at two different thresholds. **When your task spans multiple domains**, read each relevant skill file before starting. --- ## Family Invariants (apply to every `dev-*` skill) > **Role boundary (canonical — identical in `dev-frontend` and `dev-uiux-design`):** > `dev` owns universal process, evidence, and safety rules. `dev-uiux-design` owns > design intent, direction, and concept judgment. `dev-frontend` owns concrete frontend > implementation and rendered tell enforcement. Anti-slop has three layers: `dev` = > output/process hygiene (FAMILY-SLOP-01), `dev-uiux-design` = concept/taste judgment > (is this direction generic or domain-wrong?), `dev-frontend` = rendered implementation > tell detection and removal (FE-AI-TELL-01). **FAMILY-SLOP-01 / FAMILY-CITE-01 / FAMILY-PROOF-01:** no filler, placeholders, fake fallbacks, speculative wrappers, or broad defensive clutter without a named boundary reason; code findings, plans, reviews, contradictions, and verification claims cite exact files/lines or command/artifact evidence; no completion claim without fresh proof from the §3 verification gate. **FAMILY-FRESH-01 (DEFAULT):** version-pinned or time-sensitive claims live in `references/` with a Sources row (URL + checked date); routers carry only a frontmatter `last-verified` stamp. Treat claims older than the stamp as re-verify-first. ## Documentation Verification (Context7) Before using any external library API, verify current syntax via Context7 MCP (`resolve-library-id` → `query-docs`). **Verify when:** API not verified this session, pinned version, uncertain behavior, or a major release in the past 6 months. **Skip for:** language built-ins, standard library, syntax verified this session. If Context7 is unavailable, fall back to web search for official docs — never rely on training data alone for library-specific APIs. ## External Evidence and Recall Routing Canonical routing table for anything that is external, current, or previously decided. Surface routers point here instead of restating the policy. | Need | Route | |---|---| | External library syntax or pinned-version behavior | Context7 `resolve-library-id` → `query-docs`; otherwise official docs | | Current versions, releases, CVEs, providers, or public evidence | Load the active `search` skill and follow its evidence rules | | HTTP-first URL proof | Fetch the URL directly first; escalate to a real browser only when fetch is insufficient | | Prior term, file, or decision is unfamiliar, or context was lost | Search past sessions and the memory store before asking the user | ### External/current evidence For current versions, release notes, CVEs, package/source checks, or provider behavior, read the active `search` skill and follow its query-rewrite, source-fetch, and evidence-status rules. Sub-agents are bound by this policy too — include it in dispatch prompts. Routers that delegate here (`dev-frontend`, `dev-uiux-design`) inherit these rules in full; delegation is a pointer, never a weakening. ### Recall lookup scope (DEV-RECALL-01, MUST) When a prior term, file, or decision is unfamiliar — or context was lost to a compaction — search the durable record **before** asking the user: `cli-jaw chat search <query>`, then `cli-jaw memory search <query> [--chat]`, then the owning unit and the commit that introduced the term. If all miss, ask, and **state what you searched** — that is what lets the user correct the vocabulary instead of re-explaining something already on disk under a name you did not try. Full routing table: `references/recall-lookup.md`. ### Browse and QA tool routing (DEV-BROWSE-NATIVE-01, STRICT) For ad-hoc browsing and exploratory QA — opening a page, checking a URL, eyeballing a screen, taking a screenshot — **do not install a browser-automation framework or driver.** Use the runtime's own browser capability first. A deliberate end-to-end test suite is a different task and belongs to `jaw-dev-testing`. Two ladders exist and their orders are deliberately **opposite**: public-web proof leads with `jaw browser fetch`, QA of a surface you just built leads with the Manager embedded browser. Full rung tables and the reason the inversion is the content of the rule: `references/browse-qa-ladders.md`. --- ## 0. Intent Clarification When a request has **ambiguous scope or unspecified technology**, clarify before coding; skip entirely when tech and scope are already clear. - Present 2-3 options as `<TechName> — <plain explanation>` with project-relevant pros/cons (⚠️ flag risky ones); recommend one citing project context; user decides. - **Over-engineering guard** + **one confirmation round**: options → recommendation → confirm → move on. --- ## 0.5 Repository Convention Discovery Before broad changes, inspect existing conventions: source layout (`src/`, `app/`, `packages/`), source-of-truth docs (`structure/`, `docs/`, `adr/`, `devlog/`, `plans/`), agent context files (`AGENTS.md`, `CLAUDE.md`, tool instruction files), JS/TS setup (`package.json`, `tsconfig*`, linter config, sibling extensions), and naming/test/ phase-document patterns (decade numbering — see `dev-pabcd`). MUST follow existing conventions when they are clear. MUST read existing `structure/`, `devlog/`, or other source-of-truth logs before broad implementation. MUST NOT create `structure/`, `devlog/`, `AGENTS.md`, docs folders, or new tooling silently in an existing repo. If the repo is immature/undocumented, propose a lightweight source-of-truth structure and ask before creating it. ### Broad Change Preview **Broad change** = creates/reorganizes directories, touches 5+ files, spans multiple top-level packages, adds a feature/module/service, or adds source-of-truth structure. Before one, show: detected signals · compact tree (≤40 lines, omit `node_modules`/`dist`/ `build`/`.git`) · planned edits (files to create/modify) · convention decision (reuse vs ask). --- ## 1. Modular Development Give every file, function, and class a single, clear responsibility.