Skill: core-engineering

Purpose

Apply the default engineering workflow for production-grade implementation work.

Core Rules

• Verify before acting.
• Prefer the smallest correct change.
• Preserve public contracts unless explicitly asked to change them.
• Match existing project style.
• Do not introduce unrelated refactors.
• Do not invent files, APIs, schemas, commands, or test results.
• Do not use placeholders as implementation.
• Do not leave dead code.
• Do not hide uncertainty.

Workflow

1. Understand

Identify:

• requested behavior;
• expected output;
• constraints;
• ambiguous points;
• relevant domain boundaries.

If ambiguity blocks correctness, ask one precise question.

If ambiguity is manageable, proceed with an explicit assumption.

2. Inspect

Before writing code, inspect:

• relevant files;
• nearby related code;
• project config;
• tests;
• existing patterns;
• validation commands.

3. Plan

Create a concise plan:

• target files;
• intended changes;
• expected behavior;
• validation method;
• risks/assumptions.

For small tasks, one short paragraph is enough. The plan is a tool, not a paperwork shrine.

4. Implement

Implement in small focused slices.

Rules:

• one concern per change;
• explicit control flow;
• explicit error handling;
• no hidden global state;
• no unrelated formatting churn;
• no new dependencies unless justified.

Tooling Defaults

Use the strongest relevant local tool when it is available:

• rg and rg --files before slower text or file search;
• fd for file discovery when it improves the search;
• ast-grep or tree-sitter for syntax-aware search and safe mechanical rewrites;
• jq or yq for structured JSON/YAML inspection and transformation;
• just when a justfile owns project commands;
• delta for local diff review when useful;
• fzf only for interactive narrowing, not as a required automation dependency.

If the preferred tool is unavailable, use the best fallback and name the gap only when it materially affects confidence or reproducibility.

Context Tooling Tiers

Use the same question-based routing as the steady global prompt, when the current host exposes the relevant capability:

Do not run every search tool for each task. Keep path filters and bounded excerpts. A package installation does not prove host availability. If a route is unavailable, use targeted local evidence and report the material gap. Repomix is an export, not a live code index.

Project Context Bootstrap

Before broad reads or repeated cross-file exploration, do a cheap state check:

• Serena: .serena/project.yml plus any exposed Serena MCP/symbol tools;
• Graphify: graphify-out/graph.json;
• Repomix/context pack: existing requested pack path;
• output compressors: command availability and raw-output location.

Use the result as a decision gate:

• localized task -> use rg, symbol lookup, and targeted reads;
• existing Serena, Graphify, or QMD state -> compare its source revision and file hashes with the required scope, including uncommitted changes, before trusting it; an index older than an edit is stale evidence;
• missing state but architecture-heavy, symbol-heavy, dependency/call-graph, or repeated onboarding task -> initialize the narrowest useful project-local state when file mutation is allowed;
• read-only, security, validation-critical, or "do not modify files" task -> ask before creating .serena/, graphify-out/, context packs, hooks, or other repo-local artifacts.

Serena may be initialized with serena project index . when the CLI is available and LSP-backed navigation will materially reduce file reads. Report new .serena/ files and never stage or commit them unless asked.

Graphify belongs to architecture/dependency/call-graph work. If no graph exists, build a scoped graph only when it will reduce repeated reading; report graphify-out/ as generated state and verify important claims against source.

After edits, refresh the affected index scope and confirm one changed symbol or document is found. If freshness cannot be established, read current source and mark the index unverified. QMD roots must be an explicit allowlist; do not add other repositories, personal notes, or home directories automatically.

Do not run persistent hook/config upgrades such as Graphify hooks or Git hooks without an explicit user request.

Output Compression Guardrail

Select one transformation: jq or deterministic filters for structured data, RTK for supported noisy CLI output, Context Mode for large results with selective retrieval, or Distill for semantic grouping. Do not chain multiple summarizers by default. Distill is not sole evidence of a successful test.

Capture stdout/stderr and the original command's exit code before any filter or summarizer. Store raw artifacts outside tracked files. Record command, working directory, source revision, and raw artifact path separately from the summary. A nonzero test exit remains FAIL even when a filter exits zero; preserve scanner errors separately from findings and SKIP separately from PASS. Before enabling an automatic wrapper, run an intentionally failing test and verify its raw exit code and failure remain visible. Read raw evidence before claiming validation or explaining ambiguous failures.

Context Mode hook enablement is a separate decision from using output compression. context-mode doctor may diagnose missing hooks, but that result does not authorize installing them.

Do not run context-mode upgrade for small, localized, read-only, security, or validation-critical tasks. Propose it only when the work is multi-session, repeated, or likely to produce large/noisy outputs where automatic capture will materially reduce context loss.

Run context-mode upgrade only after explicit user authorization to modify persistent Codex hooks/config. If the user asks to "reduce context/log noise automatically", summarize that this requires persistent hook/config changes and ask for confirmation before running it.

After enabling hooks, run context-mode doctor and report modified global files such as ~/.codex/config.toml, ~/.codex/hooks.json, and any backups.

5. Validate

Run the best available targeted validation.

If validation fails, report the failure honestly and fix root causes when in scope.

If validation cannot be run, explain exactly why.

6. Report

Report:

• changed files;
• summary;
• validation command and result;
• assumptions;
• remaining risks.

Assumptions Format

Assumption: <clear assumption>
Reason: <why this assumption is reasonable>
Risk: <what breaks if it is wrong>

Definition of Done

The task is done when:

• behavior is implemented;
• architecture is respected;
• tests/validation are handled;
• assumptions and risks are explicit;
• no fake placeholders remain;
• output is understandable to a senior engineer.