Engineering workflow gate for the naozhi repo. Enforces a hard "isolated worktree → independent review → PR" loop on every code-touching task: every feature or bug fix starts on a fresh git worktree (never main / never the current working branch), runs a code review before the PR opens, and ships through a PR — no direct push to the main branch. Also enforces design-doc requirements for features, classifies bug fixes by size and risk, blocks PRs that lack tests/regression evidence/rollback plans, and routes deployment through the `naozhi upgrade` release pipeline. TRIGGER when working in the naozhi repo and the user asks to implement a feature, refactor, fix a bug, or release a new version; or when about to write code that touches >20 lines, >3 files, or any item on the risk checklist. DO NOT TRIGGER for typo fixes, comment-only edits, or pure documentation changes.
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Engineering workflow gate for the naozhi repo. Enforces a hard "isolated worktree → independent review → PR" loop on every code-touching task: every feature or bug fix starts on a fresh git worktree (never main / never the current working branch), runs a code review before the PR opens, and ships through a PR — no direct push to the main branch. Also enforces design-doc requirements for features, classifies bug fixes by size and risk, blocks PRs that lack tests/regression evidence/rollback plans, and routes deployment through the `naozhi upgrade` release pipeline. TRIGGER when working in the naozhi repo and the user asks to implement a feature, refactor, fix a bug, or release a new version; or when about to write code that touches >20 lines, >3 files, or any item on the risk checklist. DO NOT TRIGGER for typo fixes, comment-only edits, or pure documentation changes.
naozhi Dev Workflow
Project-scoped gate for the naozhi repo. Decides whether a change can go straight to a PR or must first produce a design + independent review, and how a tagged release reaches each host. Apply at the start of any code-touching task, before writing the first line.
Mandatory loop (every code-touching task)
Every feature or bug fix — regardless of bucket (A, B, C, or E) — MUST run through this loop end-to-end. Trivial Bucket D changes (typos, comments, pure docs) are the only exception.
New worktree. Open an isolated git worktree before writing any code. Do not edit on master/main and do not reuse the current working branch. Use the EnterWorktree tool, or git worktree add .claude/worktrees/<topic> -b <branch> from the main branch tip. Each task gets its own worktree; do not bundle two unrelated tasks into one branch.
Implement + tests. Per Step 2 below.
Code review before PR. Run a review pass on the diff (not just the design). Prefer the ecc:code-review skill, or spawn parallel reviewer agents per the "Recommended agent team layouts" table below. Self-review is allowed only with written angle-by-angle notes. Address every blocking comment in the worktree before opening the PR; record agent verdicts and reconciled disagreements in the PR description.
PR. Open via ecc:prp-pr or ecc:git-workflow. Direct push to the main branch is forbidden — even for one-line fixes. Merge happens only after CI is green and the PR readiness gate (§Step 3) passes.
Never skip a step "because it's small". The loop is the rule; bucket classification only changes how heavy step 2 (design + tests) is, not whether the loop runs.
Step 0 — Classify the task
Pick exactly one bucket. If two apply, pick the stricter one.
Bucket
Definition
A. Feature / refactor
New behavior, new module, removing/changing existing behavior, or any work the user describes as a "feature"
B. Bug fix — small
Fix that is ALL of: ≤20 lines changed, ≤3 files touched, AND triggers no item on the Risk Checklist
C. Bug fix — large
Bug fix that violates ANY of: >20 lines, >3 files, or any Risk Checklist item
D. Trivial
Typo, comment, formatting, doc-only — skip this skill
E. Hotfix
Live incident or user-authorized emergency fix. Bypass design path to stop the bleeding. Required afterwards within 24h: write the design retroactively, add a regression test, and open a GitHub issue with priority:p0 + appropriate type: label for the postmortem trail. Commit message must use hotfix: prefix.
Risk Checklist (any one match → escalate to "needs design")
Performance hot path (per-request alloc, I/O in tight loops, per-event handlers)
Affects multiple subsystems or crosses a module boundary
Bucket A and C MUST follow the design path. Bucket B skips the design-doc path and may proceed directly to Step 2, but the Mandatory loop (worktree → implement+tests → code review → PR) still applies in full and a regression test is still required.
Step 1 — Design path (Bucket A and C)
1a. Feasibility spike (only if any apply)
New external dependency or new protocol
Performance ceiling unknown
Cross-subsystem change
Change estimated >300 lines or >10 files
A spike is a throwaway branch that proves the unknown. Time-box it. Record findings in the design doc, do not merge spike code.
1b. Design document
For Bucket A: write to docs/rfc/<topic>.md and add the entry to docs/rfc/README.md.
For Bucket C: design may live inline in the PR description instead of a standalone file, but must cover every required section in full — "shorter" means location, not content.
Use ecc:plan or ecc:prp-plan to draft the design.
Required sections (no skipping):
Background & problem — reproducible symptom, data, link to incident/ticket
Alternatives considered — at least 2 candidates + why the chosen one wins
Test strategy — unit / integration / manual / regression points; name the specific tests to add
Risk & rollback — what breaks if this is wrong, how to revert
Observability — logs, metrics, dashboards added or changed
Compatibility & migration — backward compat, on-disk format, config flags
Rollout plan — flag-gated, staged, full-cutover
If a section truly does not apply, write "N/A — ". Do not silently omit.
1c. Independent review
Run a dedicated review pass before coding starts. The reviewer can be:
Preferred — an agent team / specialized subagent. Spawn parallel reviewers per angle (e.g. ecc:code-reviewer, ecc:security-reviewer, ecc:performance-optimizer, ecc:database-reviewer, ecc:go-reviewer). Multi-angle parallel review surfaces blind spots a single pass misses and is the default for any non-trivial design.
A different session or a human collaborator.
The author themselves, IF they perform a deliberate angle-by-angle pass with fresh eyes (e.g. after a break or in a separate session) and write the review notes down explicitly. Self-review is acceptable but weaker than agent-team review — escalate to agents whenever the change is risky or cross-subsystem.
Reviewer(s) must check from these angles (one per heading in the review notes):
Architecture, naming, abstraction level
Test sufficiency: coverage, boundary cases, concurrency, failure paths
Observability: are failures debuggable from logs/metrics alone?
Backward compatibility & migration safety
Failure modes & graceful degradation
Documentation sync — produce docs/review/R{N}-raw.md and run the triage-findings skill, which routes findings to GitHub Issues / docs/cosmetic-backlog.md / discard. (docs/TODO.md was deleted 2026-05-26 after the migration; do NOT recreate it.)
Save review evidence to docs/reviews/<topic>-<date>.md if the repo uses that pattern; otherwise paste into the PR description. When using an agent team, capture each agent's verdict and note whether disagreements were resolved.
For convergence-style review (two independent reviewers must agree), use ecc:santa-loop. For a single-pass review, use ecc:code-review.
The design doc must be revised until the review is signed off (by the agent team's consensus, the human reviewer, or — for self-review — by the author's own written angle-by-angle notes). Do not start coding until then.
Step 2 — Implementation
Per the Mandatory loop step 1, work in a fresh worktree branched from the main branch tip. One worktree per task; two unrelated tasks → two worktrees → two PRs.
Keep refactor and bug fix in separate PRs. Do not bundle "while I was here" cleanup into a fix PR.
Add tests before or alongside the code change. For Go projects, use ecc:tdd-workflow and ecc:golang-testing to drive the test-first loop.
Regression test acceptance for Bucket B/C: at least one test must fail on the old code and pass on the new. A test that only asserts the post-fix behavior without reproducing the original bug does not qualify.
Scope re-classification. If during implementation the change breaks Bucket B's thresholds (>20 lines, >3 files) or hits any item on the Risk Checklist, STOP and re-classify to Bucket C. Keep already-written code as a spike and produce the design doc before continuing.
Do not break existing functionality:
Run the full test suite before pushing, not just the new tests.
For UI/runtime changes, exercise the feature end-to-end, not just type-check.
Step 3 — PR readiness gate
Use ecc:prp-pr or ecc:git-workflow to drive the PR creation flow. PRs must originate from a dedicated worktree branch, never directly from master/main. Direct push to the main branch is forbidden — every change ships through a PR, even one-line fixes.
A PR may be opened only when ALL of these hold:
Worktree branched from the main branch tip; no edits made on master/main or on an unrelated topic branch
Build passes: go build ./...
Full test suite passes: go test ./...
go vet ./... clean — no new warnings introduced
Coverage on changed files did not drop
Code review on the diff completed before push. Use ecc:code-review (or parallel reviewer agents per the table below). PR description must record reviewer verdicts and how blocking comments were addressed.
For Bucket A/C: design doc linked in PR description, design-stage reviewer sign-off recorded (agent team verdicts attached if used)
For Bucket B: regression test present, root cause stated in commit message
PR description contains: Summary, Why, Test plan, Risk, Rollback
No disabled tests without a tracking issue. --no-verify and skipped hooks are allowed only when the user has explicitly authorized them or hook failure is unrelated and tracked separately.
Recommended agent team layouts
Use these as starting points; spawn the relevant subagents in parallel via the Agent tool.
After all parallel reviews return, reconcile disagreements explicitly in the design doc — do not silently pick one verdict. If reviewers split, the author decides and records the rationale.
Anti-patterns (block on sight)
Editing on master/main directly, or reusing an unrelated topic branch instead of opening a fresh worktree
Pushing a fix straight to the main branch without a PR ("just one line, won't bother with a PR")
Opening a PR without running a code review on the diff first
PR with code but no background or motivation
Change >20 lines with zero tests added
"Drive-by" refactor mixed into a bug fix
Self-review with no written angle-by-angle notes — claiming review without doing one
Bug fix commit message that says "fix bug" without stating the root cause
Deleting failing tests instead of fixing them
Adding a feature flag without a removal plan
Required commit message shape (bug fixes)
<type>(<scope>): <one-line fix summary>
Root cause: <why it broke>
Fix: <what changed and why this addresses the root cause>
Regression test: <test name or path>
Decision flowchart
task arrives
│
├─ doc / typo only? ──► Bucket D — skip skill
│
└─ everything else
│
├─ open fresh worktree from main branch tip ◄── mandatory, every bucket
│
├─ live incident or user-authorized emergency?
│ └─► Bucket E — hotfix; backfill design + regression + postmortem within 24h
│
├─ bug fix?
│ ├─ ≤20 lines AND ≤3 files AND no risk-checklist hit?
│ │ └─► Bucket B — code + regression test
│ │ └─ scope grows mid-flight? → re-classify to C
│ └─► Bucket C — design path (design + design-stage review)
│
├─ feature / refactor / behavior change?
│ └─► Bucket A — design path
│ ├─ unknowns? → spike first
│ ├─ write design doc (8 required sections)
│ ├─ independent review across 8 angles (prefer agent team in parallel)
│ └─ implement with tests
│
├─ code review on the diff ◄── mandatory before PR
└─ PR readiness gate → open PR (never push directly to main)
Repo conventions
Project-scoped skills live under .claude/skills/ and are tracked in git (whitelisted in .gitignore). Edits to a skill follow the same worktree → review → PR loop as code.
Worktrees live under .claude/worktrees/<name>/ and are ignored. Use EnterWorktree (or git worktree add) — never branch by editing the existing checkout in place.
Large designs go in docs/rfc/, indexed in docs/rfc/README.md
Outstanding work tracked in GitHub Issues (label:priority:p0,priority:p1,priority:p2 is:open); docs/TODO.md was deleted 2026-05-26 after the migration — do NOT recreate it. The historical docs/TODO_*.md archives were removed 2026-05-30; old R-anchors are recoverable via git log -S against the repo history.
Cosmetic / godoc / naming suggestions go to docs/cosmetic-backlog.md, not issues
Local restart after a build during development: sudo systemctl restart naozhi (see docs/ops/naozhi-deploy-skill.md); never hand-kill the process
Prior review sweeps are referenced from the project memory MEMORY.md
Releasing & upgrading naozhi
Distributing a new version to any machine running naozhi MUST go through the release pipeline. sudo systemctl restart naozhi is for local development only — never use it to ship a build to another host.
Release flow:
Merge the PR to the main branch.
Tag the commit: git tag vX.Y.Z && git push origin vX.Y.Z. The tag must live on the main branch — release.yml verifies this.
CI cross-compiles the 6-platform binaries, runs the screenshot release gate (e2e-gate job: boots the binary in dashboard-only mode and asserts every dashboard view renders with zero console errors), and publishes a GitHub Release with checksums only if the gate passes. A gate failure blocks the Release — the tag exists but no assets ship, so naozhi upgrade cannot pull a dashboard-breaking build.
On each target host run naozhi upgrade. It checks the latest GitHub Release, downloads the matching binary, replaces the running one, and restarts the service.
Rules:
Never deploy by copying a locally built naozhi binary to a host (no scp, no git pull && go build on a target host). The only sanctioned path is naozhi upgrade pulling from a tagged release.
Tag versions follow semver: bug fixes bump patch, backwards-compatible features bump minor, breaking changes bump major.
For UI-touching changes, run make release-gate locally before tagging to catch a dashboard break pre-tag (the same gate CI enforces). make release-gate-live gates the running systemd instance after make deploy. See docs/ops/release-gate.md.
If the release pipeline fails, fix the pipeline — do not work around it with a manual binary copy.
A PR that requires deployment to verify must call out the version it targets (vX.Y.Z) in the PR description so the tag step is not forgotten.
