Mo Dev

Compatibility: designed for Codex CLI and compatible agents on supported MatrixOne development platforms. Use the Go version in go.mod. CGo work also requires the repository-supported compiler and matching native artifacts.

Outcome and core workflow

Produce the smallest general change that restores or introduces an explicit contract, then prove every affected boundary with the cheapest valid evidence. Rigor is coverage of contracts and unhappy paths, not diff size, command count, or repeated full-suite runs.

1. Resolve scope once. Record base, head, merge-base, committed plus local changes, and untracked/delivery artifacts. Build the change map and per-closure R0-R3 classification from validation-evidence.md.
2. Classify design work. Apply the feature/major-refactor gate before implementation. Ordinary focused bug fixes are exempt from a design document, but never from invariant, ownership, cost, or validation reasoning.
3. State the contract. Write the problem evidence, invariant and negation, first owner, affected consumers, state transitions, unhappy paths, and performance/resource budget before choosing the patch.
4. Load only applicable domain references. Use the resource map below; do not load or restate every specialized workflow.
5. Implement the narrowest complete closure. Change the common ownership or protocol boundary, not one observed trace. Update consumers/reverse arcs and tests in the same functional unit.
6. Validate by information value. Reuse semantically valid evidence, run the cheapest discriminating checks first, and escalate only along mapped risk dimensions. Do not rerun equivalent author/CI work.
7. Review and deliver. Run mo-self-review on the final scope, resolve every blocker, inspect the delivery diff, and report the compact evidence record.

For tests and diagnostic probes, acquire each resource only after its preceding step succeeds and schedule its cleanup immediately in the same lexical scope. When a loop performs repeated queries or opens rows/statements, use a small helper or per-iteration closure so defer releases the resource before the next iteration; a cleanup call at the bottom of a test is not equivalent on an early assertion failure.

For diagnosis-only requests, stop after proving and explaining the cause; do not turn diagnosis into an implementation without authorization.

Resource map

Read a reference when its trigger applies:

Enforcement gates

First-principles change rules

1. Start from the violated/missing invariant and the first owner of state or resources, not the proposed patch, issue spelling, or last stack frame.
2. Close success, error, cancellation, timeout, retry, partial initialization, reset/reuse, restart, and cleanup only where the mapped contract can reach them. Prove unreachable dimensions instead of testing them ritualistically.
3. Prefer deleting duplicated state/transitions/cleanup. Every new stateful component needs one effective owner, an explicit bound, admission/publication point, all terminal paths, and a generation/restart rule.
4. Keep mechanisms proportional. A local fix does not justify a framework, cache, worker, retry layer, global, extension point, or generic abstraction. Require multiple independent recurring needs, a stable contract, and lower total runtime/operational/testing/maintenance complexity.
5. Treat per-row/batch/message/transaction/query paths as hot until bounded. Account for allocations, copies, scans, synchronization, goroutines, I/O, logs, and metric cardinality; benchmark/profile only when cost can be material.
6. Avoid incident overfit. Do not encode issue IDs, one plan layout, exact data shape, or timing coincidence in production logic. Test the invariant, nearest control, and counterexample with minimum data and deterministic control.
7. Preserve user scope and permissions. Read-only review/diagnosis does not authorize production changes, GitHub review submission, or other external mutations.

Efficient validation and completion

Use validation-evidence.md as the source of truth. In particular:

• prove exact package/test/case selection is non-empty;
• run focused evidence before broader owning-package/group evidence;
• validate a real consumer when an ownership/API boundary changes;
• add BVT/topology/restart/upgrade/race/GPU/performance only when the mapped contract requires that dimension;
• reuse exact-head CI or local evidence whose relevant semantic inputs and mode are unchanged; unrelated docs or PR metadata do not invalidate it;
• retain real terminal status and diagnose silence by polling the existing process, not by launching duplicates.

Incremental static checks (default)

Do not run a repository-wide SCA for every edit. Resolve the merge base once, include committed and local tracked/untracked Go files, inspect the resulting package list, and run the configured checks only on that list:

set -euo pipefail
base_ref=${REVIEW_BASE:-origin/main}
merge_base=$(git merge-base HEAD "$base_ref")
tracked_go=$(git diff --name-only "$merge_base" -- '*.go')
untracked_go=$(git ls-files --others --exclude-standard -- '*.go')
changed_go=$(printf '%s\n%s\n' "$tracked_go" "$untracked_go" |
  sort -u | sed '/^$/d')
existing_go=$(printf '%s\n' "$changed_go" | while IFS= read -r file; do
  if [ -n "$file" ] && [ -f "$file" ]; then printf '%s\n' "$file"; fi
done)

if [ -n "$existing_go" ]; then
  format_files=$(printf '%s\n' "$existing_go" | xargs -r gofmt -l)
  if [ -n "$format_files" ]; then
    printf 'gofmt required for:\n%s\n' "$format_files" >&2
    exit 1
  fi
fi

changed_dirs=$(printf '%s\n' "$changed_go" | while IFS= read -r file; do
  if [ -n "$file" ]; then dirname -- "$file"; fi
done | sort -u)
changed_pkgs=$(printf '%s\n' "$changed_dirs" | while IFS= read -r dir; do
  if [ -z "$dir" ]; then continue; fi
  if [ ! -d "$dir" ]; then
    printf 'changed Go directory was removed; select affected consumers explicitly: %s\n' "$dir" >&2
    exit 1
  fi
  if ! find "$dir" -maxdepth 1 -type f -name '*.go' -print -quit | grep -q .; then
    printf 'changed Go directory has no current Go files; select affected consumers explicitly: %s\n' "$dir" >&2
    exit 1
  fi
  GOWORK=off go list -mod=readonly "./${dir#./}" || exit 1
done | sort -u)
if [ -n "$changed_go" ] && [ -z "$changed_pkgs" ]; then
  printf 'changed Go files exist, but no package was discovered\n' >&2
  exit 1
fi

if [ -n "$changed_pkgs" ]; then
  GOWORK=off go vet -mod=readonly $changed_pkgs
  GOWORK=off golangci-lint run -c .golangci.yml --new-from-rev "$merge_base" $changed_pkgs
fi

Use the CGo setup and wrapper from cgo-build-test.md when the selected closure is CGo-direct/transitive. Add directly affected consumers when an exported/API, protocol, generated-code, or shared lifecycle contract changed; the package list must not be a guessed single leaf. A deleted-only package directory must stop this helper and be handled by explicitly selecting its existing consumers; do not replace that decision with ./.... If no Go file changed, run the smallest checker for the changed artifact.

make static-check-analysis, make static-check, golangci-lint run ./..., and equivalent whole-repository commands are the CI/full-scan path, not the default edit loop. Escalate to one only when SCA configuration/toolchain or workflow files changed, the affected consumer closure cannot be bounded, a release/pre-push gate explicitly requires it, or a CI failure must be reproduced. Record incremental and full results separately; a focused pass is not evidence that full CI SCA is green. Never suppress a finding or delete cleanup merely to make a static check pass.

CI and environment diagnosis

When a CI check is red or silent, do not infer the cause from the check name or partial output. Inspect the failing step and terminal log at the exact checked SHA, then classify it before editing:

• Code/static/test: reproduce the smallest affected package/test locally with the same mode (race, coverage, tags, CGo, platform where possible), and fix the violated contract. Run static checks before an expensive cluster or end-to-end test.
• Infrastructure: network/API fetch failures, rate limits, unavailable caches, runner/toolchain setup, disk exhaustion, or a cancelled/evicted job do not by themselves prove a product failure. Preserve the log and classify the cancellation/eviction reason; rerun only a clearly transient job when authorized, and do not add sleeps, retries, skips, or product workarounds to hide it.
• Ambiguous/hung: keep the existing run as the source of truth; poll for a terminal result, inspect the process/stack and resource state, and avoid launching a duplicate service or test that can contend for ports, native artifacts, or global state. A timeout is evidence of a liveness failure until the wait-for path is explained.

For local native/integration work, preflight the selected toolchain, disk and temporary directory, active test-owned processes/ports, and CGo artifact provenance. Use the repository wrapper and an explicit temporary directory; clean only artifacts owned by the test. Report environment failures separately from code evidence, and never claim CI green from a pending, skipped, cancelled, or unrelated check.

Ordinary pure-Go examples:

GOWORK=off go test -mod=readonly -list 'TestXxx' ./pkg/target
GOWORK=off go test -mod=readonly -v -count=1 -timeout 120s -run '^TestXxx$' ./pkg/target
GOWORK=off go test -mod=readonly -v -count=1 -timeout 120s ./pkg/target/...
GOWORK=off go vet -mod=readonly ./pkg/target/...

For CGo-direct/transitive packages, replace go test with:

.agents/skills/mo-dev/scripts/mo-cgo-test -count=1 -timeout=120s ./pkg/target/...

Before delivery, the record must show:

□ resolved range/worktree scope and complete per-closure change map
□ design-gate decision and approved revision when triggered
□ invariant/root cause/owner/consumer and relevant unhappy paths closed
□ UT/BVT and specialized-domain decisions recorded
□ every required proof is validly reused or passed; gaps/pending work are explicit
□ generated/delivery artifacts, diff stat, and unintended files checked
□ `mo-self-review` has zero unresolved blockers

Never weaken assertions, add sleeps/retries/skips, broaden fixtures, or run an unrelated package merely to make a checkbox green. Never claim “systematic” from breadth alone: demonstrate one general contract closed across its relevant state space with less total complexity than the credible alternatives.