zf-cr

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# ZaoFu Codebase Review

## Objective

Perform a read-only, architecture-level codebase review that builds accurate
development context before implementation. Focus on ZaoFu's harness
engineering invariants: deterministic kernel, runtime state, event log,
orchestration boundaries, integrations, Web/API projections, tests, and docs.

This skill is the **baseline checklist** for ZaoFu review. It does not claim
"everything is covered" by itself. A complete review must produce evidence:
coverage matrix, file/line references, explicit uncovered areas, and a
follow-up prompt or supplement plan for gaps.

Default to Chinese for repository-facing prose unless the user asks otherwise.

## Modes

- If the user asks to review the repository, execute the review workflow
  below.
- If the user asks for refactor planning, run the adaptive full-review loop:
  bootstrap -> dynamic Review Prompt V2 -> deep review -> coverage audit ->
  synthesis.
- If the user asks for a reusable command, generate a Codex command using
  `codex exec --ephemeral --ignore-user-config -s read-only -a never`.
- If the user explicitly asks for parallel or multi-agent review, split
  the review into independent read-only areas. Otherwise perform the
  review locally.

## Safety Rules

- Read `AGENTS.md` first and follow its repository rules.
- Do not modify files, create files, emit ZaoFu events, or update runtime
  state during review.
- Do not run commands that mutate the repo, configured state dirs,
  `.zf/`, caches, lockfiles, progress files, kanban files, or session
  files.
- Treat `.zf/` and configured state dirs as runtime state, not source
  code.
- Do not hard-code `.zf`; verify behavior against `zf.yaml` and
  `project.state_dir`.
- Prefer `rg`, `rg --files`, `git status --short`, `git diff --stat`, and
  targeted file reads for inspection.

## Review Workflow

### Step 0 — Bootstrap Strategy

Use this skill first to build the review map, not as the final review answer.
The first pass should output:

- repository map: important directories, runtime state location, major
  subsystems
- invariant map: state ownership, event ownership, task contract, Web/API
  mutation boundary, skill/workdir boundary
- hot spots: recent git changes, oversized modules, TODO/defer debt, failing
  or risky areas
- initial coverage matrix: subsystem -> files inspected -> evidence refs ->
  uncovered refs
- dynamic Review Prompt V2: a precise prompt for the second-pass deep review

If the user asks for "full review", "refactor scan", or "plan generation",
do not stop after bootstrap unless explicitly asked.

### Step 1 — Anchor Reading

Read these **4 anchor sources before anything else**. They save most of the
time the reviewer would otherwise spend rediscovering structure:

1. `AGENTS.md` — repository rules at top level
2. `docs/design/00-index.md` — canonical doc map, lists design docs with
   one-line summaries + status
3. `docs/design/142-layered-runtime-authority-and-orchestration-modes.md` —
   canonical authority, storage, orchestration-mode, and residual-gap boundary;
   doc 44 is only a historical scoring snapshot
4. `.claude/rules/code.md`, `.claude/rules/backlogs.md`,
   `.claude/rules/docs.md` — path-scoped rules and backlog/doc discipline

Then absorb the layout:

- `zf.yaml` (the only control plane)
- `src/zf/cli/`, `src/zf/core/`, `src/zf/runtime/`,
  `src/zf/integrations/`, `src/zf/autoresearch/`, `src/zf/web/`
- `tests/`, `web/`
- `docs/design/` (especially recent docs)
- `skills/` (ZaoFu's deliverable runtime skills)
- `.codex/skills/` and `.claude/skills/` (provider-local skills)

### Step 1.5 — Full Git History Map

Reviewing without the full project history misses architectural drift. Build a
full-history map first, then use recent commits only as hotspot signals.
Always run:

```bash
git log --all --oneline --decorate
git log --reverse --oneline | head -40
git log --all --name-only --pretty=format: | sort | uniq -c | sort -nr | head -80
git shortlog -sn --all
git log --all --since="2 weeks ago" --oneline | head -50
git diff --stat HEAD~30 2>/dev/null | tail -10
```

Use the complete `git log --all` to identify eras, feature families, subsystem
ownership, reversions, and long-running refactor debt. Use the recent scan to
rank likely regression hotspots. Sprint families to recognise: `feat: TR-* /
EVAL-* / PWF-* / ZF-LH-* / ZF-PWF-* / omega-* / alpha-* / beta-*`.

The review output should include a short Git History Map:

- major eras and feature families
- high-churn files/directories
- recent drift hotspots
- stale docs/backlogs that conflict with current code
- commits or commit families that deserve targeted follow-up

### Step 1.6 — Global Architecture Inventory

Before deep review, build a whole-system inventory so the second-pass prompt is

From uisee-ai/zaofu, Apache-2.0.

More from uisee-ai/zaofu