Dev — Common Development Guidelines

Core rules applied to every coding task, regardless of surface.

User instructions and the actual host's safety/tool contracts take precedence over skill guidance. A diagnosis or review authorizes investigation, not fixes, installs, publishing, or account changes; a change request authorizes only its scoped implementation.

§0.0 Work Classifier (C0-C5)

Classify every task before choosing process depth (DEV-CLASS-01). The class selects how much planning, reading, and verification the task deserves — never apply maximum process by default.

Classification is provisional. Before broad investigation, decide discovery ownership using Discovery delegation, including for read-only work. Revisit that decision when the scope grows; an initial small-task label does not justify retaining independent source areas in main.

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
C3	Cross-Domain Feature/Refactor	Multiple modules, public API, shared types, broad behavior	Compact or full PABCD depending on persistence/risk; add subagent audit when scope or risk warrants
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-first via the pabcd skill, then reclassify

C5 is temporary — it cannot enter implementation until Interview resolves ambiguity and the task is reclassified C0-C4.

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).

§0.1 Patch Fast-Path (C0/C1)

For C0/C1 work (bounded by "one file, no new abstractions, local behavior" — a ≤5-line in-place 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 type/static checks when applicable. C0 changes with zero behavior impact are exempt from numbered implementation-unit records. C1 patches leave a short change/reason/proof record only when an owning unit already exists; do not create a unit just for C0/C1. Security, data-loss, or new-abstraction changes are not this fast path. This exception applies (UNIT-RESIDENCE-01, pabcd Implementation-Unit Documents).
• 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 the behavior of an auth/payment/deletion or other DEV-ESCALATE-01 path — not merely because the file lives in such an area. A zero-behavior edit (comment, typo, log string) inside an auth file stays C0; any edit touching the executed logic of such a path is not C0/C1 — reclassify and read the relevant reference.

§0.2 Rule Classes

Rule authority is based on purpose, not typography. Safety, correctness, permission boundaries, and truthful verification are mandatory. File-size thresholds, naming, module layout, implementation style, and aesthetic choices are DEFAULT or STYLE_SAMPLE, even when an older reference calls them MUST/NEVER or assigns HIGH severity. A documented project/user contract may make a particular constraint mandatory; cite that contract. Explicitly requested workflows retain their phase/evidence requirements. An unclassified rule is DEFAULT unless violating it has a concrete safety or correctness consequence.

• 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

For PR creation/review/merge or dependent work-phase delivery, read stacked PRs (DEV-STACK-06/07), even without a DevOps trigger. Default to ordinary PRs/manual chains. Do not suggest or create GitHub native stacks unless the user clearly and strongly requests that feature for this task (DEV-STACK-OPT-IN-01). Inspect existing membership and CI separately for safety; a body map or parent base is not native opt-in. Generic CSS/runtime stacks are unrelated.

Methodologies are conditional, not universal. For an explicit method, repo requirement, or a matching strict trigger, read Methodology overlays. The surface table below remains mandatory before writing in that surface. C2 conventional product slices also select CRUD product development. Read selected references only; do not preload every overlay's owners.

§0.4 Workflow Modes

The same rules flex by execution mode — know which one you are in: ordinary chat (direct work, C0-C2 typical) · PABCD mode (pabcd skill) · goal mode (create_goal, evidence-backed checkpoints) · subagent (scoped writes when explicitly delegated) · read-only review (no mutation, findings only) · docs-only work (no code gates, docs consistency checks instead).

PABCD, goal, divergence, and repeated work-phase mechanics are canonical in pabcd and cxc-loop. Load those skills when the selected process requires them; classify each work-phase independently. Multi-cycle loops (2+ work-phases) enter docs-first: the first work-phase is a docs-only PABCD that locks the diff-level roadmap before any implementation cycle (LOOP-DOCS-FIRST-01, cxc-loop).

Production surface (shared definition): a surface is production when it is deployed for real users beyond the author; prototypes, spikes, and internal demos are not. Skills that scope rules to production-surface concerns (for example dev-backend observability or dev-frontend production checklists) condition on this definition.

Companion Skills

This skill covers universal guidelines. STRICT (DEV-ROUTE-01): you MUST read the matching dev-* router SKILL.md before writing code in that surface. Routing is not optional discovery — for any change whose surface appears below, reading that router's SKILL.md (its routing table; references only when the change needs that depth) is a precondition for writing code there. Skipping it is a STRICT violation (dev §0.2), the same severity as a broken build. When a change spans multiple surfaces, read each matching router first.

For required full-file reads, keep batches within the active tool's output limits. A truncated result is incomplete: read the missing portions before the governed action. A successful command exit does not prove that all instructions reached the model. Keep the C0/C1 scope exceptions; this is not a request to load every linked reference.

If a selected file's output is truncated, re-read that file separately. Do not guess missing ranges from an elision marker. If it cannot fit one result, use numbered, contiguous, non-overlapping chunks through EOF and verify no gaps.

Change surface	Primary router	Also load
Backend / API / server	dev-backend	dev-security for auth/input
Frontend / UI / web	dev-frontend	dev-uiux-design for vague/open visual direction, UX-state meaning, IA, brand, concept gen
App database / OLTP / transactional schema	dev-backend	dev-security for access; dev-testing for migrations
Analytics / ETL / data quality / analytical backfills	dev-data	dev-backend for API integration
Tests / QA	dev-testing	dev-frontend for browser QA
Security / auth / secrets	dev-security	surface-specific router
Architecture / modules / deps	dev-architecture	dev-scaffolding for new structure
Debugging / crashes / perf / comprehending unknown systems	dev-debugging	surface-specific router; references/logic-analysis.md when no defect
DevOps / deploy / infra	dev-devops	dev-security for credentials
Scaffolding / docs / setup	dev-scaffolding	dev-architecture for boundaries
Code review	dev-code-reviewer	dev-security + dev-testing
Diagrams / charts / visual documents / reports / PDF composition	dev-visualizer	Available document-format owner for PDF/DOCX/Slides mechanics; dev-frontend and dev-uiux-design retain implementation/design ownership

Subagent Skill Injection (DEV-SKILL-INJECT-01)

Attach cxc-dev and every relevant surface skill explicitly to governed subagents. Prefer resolvable skill links; use plugin-native mentions or v1 items when needed. Hooks may normalize recognized plaintext mentions but never infer omitted skills. Attach cxc-search for search tasks; the same search policy binds delegated agents.

Surface-to-owner mappings live in references/skill-ownership.md; router trigger metadata remains canonical in each skill's agents/openai.yaml.

Discovery delegation

For authorized investigation, decide who owns discovery before loading a broad set of source files or logs. Read-only feature assessment, debugging and source comparison can use explorer without implementation or a full PABCD cycle.

Begin with the smallest orientation needed to name a concrete question and its read scope. When that question is independently answerable and main can progress on another part, delegate it to explorer before reading its full source locally. State the child's question and main's separate work. Use the configured role and supported dispatch protocol; no-delegation and host restrictions take priority.

Discovery is subagent work: an explorer is a leaf in this session's own working directory, and read-only lanes cannot collide because they write nothing. That is not a template for parallel write work. Anything needing its own branch, checkout or merge/CI lane is a separate Codex task, one per lane — see Dispatch surfaces.

Keep a narrow lookup local when its result immediately determines the next step, or when the work cannot be separated without duplicating the investigation. Before retaining substantial discovery locally, state that concrete reason. Read-only scope, file count alone, or parallel shell calls are not sufficient reasons. Do not seek approval for already authorized routine delegation.

Revisit the split when the investigation reaches another independent subsystem, requires broad rereading, or produces truncated output. Reclassify when scope changes. If delegation is unavailable, record the observed limitation and continue with bounded local reads.

Use a bounded discovery packet with findings, source anchors and uncertainties, not full file dumps. Main checks only the spans needed to settle a cited claim, not every returned file by default. If a broader read is necessary, name the evidence gap and reassign that question before expanding; do not repeat a delegated investigation as routine verification. Discovery does not replace implementation delegation or independent review. Confirm actual model routing from runtime evidence when reporting identity or cost. When comparing cost, use main plus child served-model input/cache/output prices and applicable tiers; token totals alone cannot compare differently priced models.

Capability Routing Hub

Independent peers: keep work local and use selective read-only evidence when needed. Outbound messages are default-off: contact an existing task only on an explicit user request or for necessary coordination of a confirmed blocking CI/merge collision, subject to host permissions and wake checks in peer collaboration. No routine discovery, unsolicited progress notifications or follow-ups. Authorized subagent work uses its own scoped delegation tools. Use dev plus repo tools for local facts; load search, pabcd, loop, recall, cxc-qa, or the matching dev-* owner for their named domains. skill-hub is deprecated.

Native execution

For tool composition, response projection, or in-context JS computation, prefer exposed native Code Mode and read native execution before nontrivial use. Simple direct calls and explicit tool restrictions take precedence; do not enable features or invent a runtime when the capability is absent.

Browse / QA Tool Routing

Canonical selection policy: Portable browser routing. Use it for public proof, authenticated research, parallel extraction, and local UI QA. Aside is preferred when suitable and available; agbrowse is recommended, not required. No optional browser, CLI, account, or native plugin is assumed installed on every host. Do not install a new driver/runner merely because a request says Playwright; use the available capability. Explicit project-owned E2E work remains dev-testing's domain.

Skill Ownership Map

Canonical rule ownership and stub locations live in references/skill-ownership.md. Update the canonical owner first and keep stubs as pointers; multi-domain tasks load every relevant owner skill before work begins.

---

Family Invariants (apply to every cxc-* 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).

These hold for every dev-family skill and every response they govern. dev is the canonical owner; other routers reference this section rather than restating it. They are agent-followed wording (no Codex hook enforces skill text — structure/00_philosophy.md §1), not runtime gates.

• Anti-slop output (FAMILY-SLOP-01). No filler, no performative narration, no decorative rationale. Ship no placeholders, TODO-only deliverables, fake fallbacks, speculative wrapper layers, or broad defensive clutter without a named boundary reason. Code-smell catalog lives in §6 + dev-code-reviewer §3; this rule is about not emitting slop in the first place. Prose and document deliverables have their own reflexes (DEFAULT): em dashes and connector openers in Korean text, bold-label bullets and rule-of-three lists where a sentence would do, and stat cards, tinted callouts and box-and-arrow figures in a printed page. kwrite owns the Korean sentence tells; dev-visualizer REPORT-DESIGN-01 owns the page-design tells.
• Reader deliverables (FAMILY-READER-01). A report, explainer, visual document or summary written for a person follows Reader documents: answer first, evidence separated and anchored, fresh-reader check for delivered reports. Audit artifacts (receipts, logs, ledgers) keep their raw form and are linked, not narrated.
• file:line evidence (FAMILY-CITE-01). When reporting code findings, plans, reviews, or contradictions, cite path:line. Plans list exact paths + the verification command; review and audit findings carry path:line; verification claims carry the command + its output or artifact path. This mirrors the structure doctrine (structure/00_philosophy.md:135-141).
• Completion proof (FAMILY-PROOF-01). No completion claim without fresh proof — see the §3 verification gate for the long form. Every other router inherits that gate; it is not re-stated per skill.

---

External Evidence and Recall Routing

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 cxc-search and follow its evidence rules
HTTP-first URL proof	agbrowse fetch <url> --json; full ladder: cxc-search Tier 2

Recall Lookup Scope (DEV-RECALL-01, MUST)

Trigger	Route
Prior term/file/decision is unfamiliar or context was lost	cxc chat search "<terms>" --days 0 and cxc memory search "<topic>"
Both searches miss	Ask the user and report what was searched; full flags: cxc-recall

---

0. Intent Clarification

Clarify only material uncertainty; skip questions already answered by context. During work, when request_user_input_async is exposed and allowed, leave useful questions without expecting a reply or stopping progress. Continue with evidence and authorized assumptions; incorporate answers if they arrive, and leave distinct new questions as needed. Read Async user questions for schema, pending-answer handling and fallback. Interview keeps its existing flow.

---

0.5 Repository Convention Discovery

C2+ implementation first reads Development practice: repository conventions, modular limits, necessity and owner search, read-before-edit, and friction rules. The C0/C1 fast-path in §0.1 applies. Read the source and direct callers before proposing a change; do not invent new structure without the required approval.

1. Modular Development

Canonical details remain in Development practice.

1.5 Necessity Gate & Pre-Write Search Obligation

Before any new abstraction, apply DEV-NECESSITY-01 and owner search in Development practice.

2. Systematic Debugging

For non-obvious defects or repeated failed repairs load cxc-dev-debugging. For comprehension without a defect — how an unknown app, API, AI tool, or codebase works (로직 파악, 뜯어보기) — load cxc-dev-debugging's references/logic-analysis.md: "I can't analyze this" is a skipped observation loop, not a limit. DEV-FRICTION-01 and DEV-EDIT-SHAPE-01 remain in Development practice.

---

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):

1. Identify — What command proves this claim?
2. Run — Execute fresh (not cached).
3. Read — Full output. Check exit code. Count failures.
4. Confirm — Does the output actually support the claim?
5. Report — State the claim with evidence attached.

Claim	Requires	Not Sufficient
"Tests pass"	Test command output: 0 failures	Previous run, "should pass"
"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"
"Subagent completed"	VCS diff shows actual changes	Subagent report says "success"
"Regression test works"	Red-green cycle verified	Test passes once

Per-class verification floor (DEV-VERIFY-FLOOR-01). The gate above is universal; the minimum scope scales with the work class (§0.0). This is the floor, not a cap:

Class	Minimum verification
C0/C1	Smallest relevant proof: text consistency for C0; focused test/checker for C1, or an observed repro with stated limits when automation does not fit
C2	Focused integration/contract test for the touched slice + targeted build/typecheck + UI smoke if UI changed (CRUD per-operation negatives: see dev-testing references/core/crud-test-matrix.md)
C3	Affected suites + docs/contract consistency when a public contract changed
C4	Full relevant gates + negative cases + durable evidence record

Subagent delegation: When subagents report success, verify independently: check VCS diff → verify changes exist → confirm behavior.

---

4. Change Documentation

For C2+ work with a supplied log, add a concise factual change/reason/verification entry. C0/C1 automatic record duties follow §0.1; merely finding a devlog or changelog does not reinstate them. An explicit user request or a documented release-record contract still governs its named log. Do not create an unrelated record to satisfy this section.

---

5. Safety Rules