Dev — Common Development Guidelines
Rules applied to every employee, 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.
Classification is provisional. Before broad investigation, decide who owns independent discovery, including read-only work. If authorized and a configured employee is available, dispatch a bounded read-only question with jaw dispatch --agent <employee> --task-file <brief> --read-only; otherwise record the gap and proceed within scope. Keep a narrow lookup local when its answer gates the next action. Revisit discovery ownership when scope grows.
| 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 jaw-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 | Use Interview behavior first; enter persisted I only for explicit or otherwise authorized orchestration (see jaw-dev-pabcd §1), 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, §5 safety rules
(imports/exports), §7.2 static analysis. UNIT-RESIDENCE-01: C0 creates no
numbered implementation record; C1 records change/reason/proof only inside an
existing owning unit. See
../jaw-dev-pabcd/references/implementation-units.mdfor the canonical rule. C4-risk changes leave this fast path. - 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
Rule authority follows purpose, not typography. Safety, correctness, permissions, and truthful verification are mandatory. Size, naming, layout, style, and aesthetic rules are normally DEFAULT or STYLE_SAMPLE, even if an older reference says MUST. A documented project or user contract may raise a constraint's authority; cite it. An unclassified rule is DEFAULT unless breach has a concrete safety or correctness effect.
- 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)
Overlays activate by Jaw task_tags, an explicit method, repository contract, or a
matching strict trigger. They are conditional; use the smallest relevant proof.
The task-tag table and product-slice route are in
references/methodology-overlays.md. Tags are not employee role values.
For PR creation, review, merge, or dependent delivery, read
references/stacked-prs.md (DEV-STACK-06/07/OPT-IN-01).
§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,
jaw-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:
A truncated SKILL.md read is incomplete even when the command exits zero.
Read missing portions as contiguous, non-overlapping ranges through EOF before
governed work. Load selected references only when that task needs their depth.
| Skill File | Injected When | Covers |
|---|---|---|
../jaw-dev-frontend/SKILL.md |
role=frontend |
UI implementation, responsive, anti-slop |
../jaw-dev-backend/SKILL.md |
role=backend |
API/architecture, data access, ops |
../jaw-dev-data/SKILL.md |
role=data |
Pipelines, data quality, analytics SQL |
../jaw-dev-security/SKILL.md |
Security-sensitive code, or security/threat_model task_tags |
OWASP, auth, secrets, supply chain |
../jaw-dev-testing/SKILL.md |
testing/tdd task_tags, or testing phase |
Test strategy, Playwright, contracts, CI |
../jaw-dev-debugging/SKILL.md |
Debugging phase (phase 4) | Root-cause method, instrumentation |
../jaw-dev-code-reviewer/SKILL.md |
Any agent, during code review | Review process, severity, antipatterns |
../jaw-dev-architecture/SKILL.md |
Module boundary work, dependency analysis | Cycles, coupling, barrels, validation placement |
../jaw-dev-uiux-design/SKILL.md |
Vague design direction, UX state patterns | Intent discovery, design vocabulary, UX states |
../jaw-dev-scaffolding/SKILL.md |
New project/feature setup, structural audit, docs generation | Lidge Standard, colocation, devlog |
../jaw-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 jaw-dev-* skill)
Role boundary (canonical — identical in
jaw-dev-frontendandjaw-dev-uiux-design):jaw-devowns universal process, evidence, and safety rules.jaw-dev-uiux-designowns design intent, direction, and concept judgment.jaw-dev-frontendowns concrete frontend implementation and rendered tell enforcement. Anti-slop has three layers:jaw-dev= output/process hygiene (FAMILY-SLOP-01),jaw-dev-uiux-design= concept/taste judgment (is this direction generic or domain-wrong?),jaw-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 (jaw-dev-frontend, jaw-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.
Session, account, tab ownership, and side-effect checks: references/browser-routing.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
Inspect existing source-of-truth, toolchain, owner, caller, and sibling conventions
before broad edits. Preview broad changes and follow the project record location.
Canonical guidance: references/development-practice.md.
1. Modular Development
Keep one responsibility per unit and one logical change per PR. Size thresholds are
review signals. See references/development-practice.md and jaw-dev-architecture.
1.5 Necessity Gate & Pre-Write Search Obligation
For C2+ work, consult references/development-practice.md for DEV-NECESSITY-01,
DEV-MAP-FIRST-01, and DEV-READ-FIRST-01 before creating or editing code.
2. Systematic Debugging
Use jaw-dev-debugging for root-cause work. DEV-FRICTION-01 and
DEV-EDIT-SHAPE-01 are owned by references/development-practice.md.
3. Verification Before Completion (STRICT)
Verify every completion claim with evidence. Run the relevant command fresh, read full output, and confirm the claim matches.
Verification gate (before any completion claim):
- Identify — What command proves this claim?
- Run — Execute fresh (not cached).
- Read — Full output. Check exit code. Count failures.
- Confirm — Does the output actually support the claim?
- Report — State the claim with evidence attached.
Per-class verification floor (DEV-VERIFY-FLOOR-01): C0 uses text consistency; C1 uses a focused checker/test or observed repro with stated limits where automation does not fit. C2 adds focused integration/contract checks; C3 runs affected suites and contract/docs checks; C4 runs full relevant gates, negative cases and durable evidence. This floor does not cap project-required checks.
| Claim | Requires | Not Sufficient |
|---|---|---|
| "Tests pass" | Expected tests actually ran; fresh output has 0 failures | Absent, skipped, cancelled, or previous tests |
| "Build succeeds" | Build command: exit 0 | "Linter passed" |
| "Bug fixed" | Original symptom verified resolved | "Code changed, assumed fixed" |
| "Feature complete" | Each requirement checked line-by-line | "Tests pass" |
| "Agent completed" | VCS diff shows actual changes | Agent report says "success" |
| "Regression test works" | Red-green cycle verified | Test passes once |
Employee delegation: When employees report success, verify independently: check VCS diff → verify changes exist → confirm behavior.
Long external waits (cli-jaw runtime): don't block the turn polling CI/deploys/
web-ai sessions — register cli-jaw bgtask add --cmd '[...]' --prompt "..." and end
the turn; the server re-invokes the boss on completion. Local tests/tsc/builds stay blocking.
For hosted CI, follow DEV-CI-EVIDENCE-01 in
references/hosted-ci-evidence.md: identify the required jobs, checked SHA,
workflow event, run and attempt before claiming a pass.
Red flags — unverified claims creeping in: "should"/"probably"/"seems to" · satisfaction before verification · partial/previous-run evidence · trusting agent success reports · "just this once".
4. Change Documentation
Devlog phase documents use decade-range numbering (00-09 research, 10-19 phase 1, ...; three-digit
prefixes such as 000_/010_ in new units); never bare PLAN.md/PHASES.md/RCA.md (LEXICO-SPLIT-01). Full
convention: ../jaw-dev-pabcd/references/implementation-units.md.
For C2+ work with a supplied worklog/changelog, record a factual entry per changed file:
### [filename] — [reason] with Changes (what/why), Impact (dependent modules),
and Verification (command + result). C0/C1 follow the canonical
UNIT-RESIDENCE-01 exception in §0.1; an explicit release-record contract still applies.
Reader deliverables (FAMILY-READER-01) — reports, phase summaries, devlog narrative — follow
references/reader-documents.md: the answer first, evidence in an appendix.
5. Safety Rules
- Preserve public contracts — trace external consumers before removing public exports and decide compatibility or migration. Internal unused exports may be removed within scope after consumer search.
- Verify imports exist before adding
importstatements. Confirm the target file and export are real. - Externalize configuration — use config files or environment variables. Place magic strings and numbers in named constants.
- Handle all async errors explicitly — surface failures at a clear boundary. In JS/TS backend code, the Result pattern (
neverthrow) may replace per-calltry/catchwhen failures are surfaced at a verified boundary (see../jaw-dev-backend/SKILL.md§3). In other cases, usetry/catchand log with context (console.error('[module]', error.message)). - Confirm before destructive operations (ESCALATE) — deleting files, dropping tables, resetting state, or clearing caches require explicit user approval.
- DEV-SHELL-TEXT-01 / DEV-PRIVACY-01 (STRICT) — write generated shell-bound
text safely and keep private data outside public trees. Follow
references/safe-public-text.mdfor the exact handling and public-boundary gates.
Git discipline
- Commit incrementally (DEV-GIT-COMMIT-01, DEFAULT) — each logically complete step (passing test, wired feature, fixed defect) gets its own commit, so progress is checkpointed on disk. This matters most in multi-cycle work, where the transcript is not durable: committed work survives a context flush, uncommitted work does not.
- Push requires explicit user approval (DEV-GIT-PUSH-01, ESCALATE) — committing locally is autonomous; pushing is an external state change the user must authorize. Holds even at completion, and covers force-push, remote branch creation, and tag push. Approval for a named scope ("push when done") is approval for that scope only.
- Stack dependent work when review and dependency justify it (DEV-STACK-01,
DEFAULT). Manual chains and registered native stacks have different CI and
merge behavior. Cascade changed lower layers before publication; merging remains
user-authorized. DEV-STACK-06/07/OPT-IN-01 and the merge procedures live in
references/stacked-prs.md.
6. Code Quality Signals (stub)
Anti-pattern detection (god class, long method, deep nesting, magic numbers, stringly
typed, missing boundary error handling, floating promises, copy-paste) is canonically
owned by ../jaw-dev-code-reviewer/SKILL.md §3 — read it when writing or reviewing code.
Size signals are in references/development-practice.md; boundary-error placement
follows jaw-dev-architecture §4.
7. Type Safety & Static Analysis
7.0 JS/TS Source File Default
New JS/TS source files prefer TypeScript (.ts/.tsx) when the repo supports it or
is greenfield; use .js only for clearly JS-only repos, build constraints, or explicit
user request. Never introduce TS tooling, convert existing JS, or change tsconfig
without approval. New TypeScript MUST be strict-compatible from the first patch:
no implicit any (explicit any needs justification), prefer unknown + narrowing,
type exported params/returns, handle null/undefined deliberately. Verify with the
project's typecheck (or tsc --noEmit); if strict compatibility can't be verified, say so.
7.1 Type Annotations
Add explicit types to all function signatures, return types, and non-trivial variables.
TypeScript: strict: true, no implicit any (explicit any needs a justification
comment). Python: hints on all params/returns. Enable the language's strict/pedantic
mode when one exists. Per-language rules table: references/static-analysis-gate.md.
7.2 Static Analysis Gate
After every code change, run the project's static analysis toolchain as part of the
verification gate (§3) — zero errors on changed files is the floor. Per-toolchain
commands and the anti-pattern ↔ lint-rule mapping live in
references/static-analysis-gate.md; check project config for the canonical rule set.
If no tool is configured, recommend one — but do not add tooling without approval.
7.3 Escape Hatches
When bypassing the type system is unavoidable: comment why, scope minimally (narrowest
cast point), prefer assertion functions over raw casts. TS as unknown as T needs a
linked issue/TODO; Python # type: ignore[code] must name the exact error code.
8. Token Budget Awareness
Tiered reference loading: (1) read the selected skills' SKILL.md routers;
(2) read references/ files only when the task touches that topic; (3) do not
preload all references (HEURISTIC) — e.g. a caching task reads caching.md only.
Employees: name only the relevant policy skills in a dispatch brief and
verify they can read them; naming is not automatic injection.
9. Employee Skill Guidance and Skill Discovery
Two DEFAULT rules live in references/skill-injection-and-discovery.md:
DEV-SKILL-INJECT-01— namejaw-devand every relevant surface skill in the dispatch brief, and verify it is resolvable. Jaw does not attach skills automatically from that text.DEV-SKILL-DISCOVERY-01— check the runtime's skill registry before improvising.jaw-devkeeps authority over a discovered skill, and the family wins name conflicts.