@tea-agent/loop-agent 0.1.0-fe-test.0

package/skills/playwright-cli/references/test-generation.md

@@ -0,0 +1,433 @@
+# Test generation (plan → generate → heal)
+
+End-to-end workflow for authoring and maintaining Playwright tests with `playwright-cli`. Every `playwright-cli` action emits the equivalent Playwright TypeScript, and that generated code is the raw material for every test. The sections below can be used independently:
+
+- **How generation works** — the core mechanic everything else relies on: actions become TypeScript, plus how to add assertions.
+- **Plan** — explore the app, produce a spec file describing what to test.
+- **Generate** — turn a spec into Playwright test files. Update the spec if it's vague or stale.
+- **Heal** — diagnose failing tests, fix the code, reconcile the spec with reality.
+
+Plan / generate / heal lean on the same mechanic: run `npx playwright test --debug=cli` in the background, then `playwright-cli attach tw-XXXX` to drive the paused page interactively. See [playwright-tests.md](playwright-tests.md) for the debug/attach mechanics.
+
+---
+
+## 0. How generation works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code. This code appears in the output and can be copied directly into your test files.
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+### Building a test file
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+### Use semantic locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### Explore before recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### Add assertions manually
+
+Generated code captures actions but not assertions. Add expectations in your test using one of the recommended matchers:
+
+- `toBeVisible()` — element is rendered and visible
+- `toHaveText(text)` — element text content matches
+- `toHaveValue(value) / toBeEmpty()` — input/select value matches
+- `toBeChecked() / toBeUnchecked()` — checkbox state matches
+- `toMatchAriaSnapshot(snapshot)` — page (or locator) matches a partial accessibility snapshot
+
+Use `playwright-cli generate-locator <target>` to produce the locator expression for the assertion, and the snapshot/eval commands to capture the expected value.
+
+When asserting text content, make sure that generated locator does not contain text from the element itself. `getByTestId()` or `getByLabel()` usually work well with asserting text. When locator is text-based, prefer `toBeVisible()` instead.
+
+Snapshot to be matched does not have to contain all the information - only capture what's necessary for the assertion. You can use regular expressions for unstable values.
+
+```bash
+# Get a stable locator for an element ref to use in the assertion
+playwright-cli --raw generate-locator e5
+# getByRole('button', { name: 'Submit' })
+
+# Capture expected text content for toHaveText
+playwright-cli --raw eval "el => el.textContent" e5
+
+# Capture expected input value for toHaveValue/toBeEmpty
+playwright-cli --raw eval "el => el.value" e5
+
+# Capture expected aria snapshot for toMatchAriaSnapshot/toBeChecked
+# (whole page, or use a ref to scope to a region)
+playwright-cli --raw snapshot
+playwright-cli --raw snapshot e5
+```
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertions using the outputs above:
+await expect(page.getByRole('alert', { name: 'Success' })).toBeVisible();
+await expect(page.getByTestId('main-header')).toHaveText('Welcome, user');
+await expect(page.getByRole('textbox', { name: 'Email' })).toHaveValue('user@example.com');
+await expect(page.getByRole('checkbox', { name: 'Enable notifications' })).toBeChecked();
+
+// toMatchAriaSnapshot on the whole page, finds a matching region
+await expect(page).toMatchAriaSnapshot(`
+  - heading "Welcome, user"
+  - link /\\d+ new messages?/
+  - button "Sign out"
+`);
+
+// toMatchAriaSnapshot scoped to a region
+await expect(page.getByRole('navigation')).toMatchAriaSnapshot(`
+  - link "Home"
+  - link /\\d+ new messages?/
+  - link "Profile"
+`);
+```
+
+---
+
+## 1. Planning
+
+Goal: produce a spec file (e.g. `specs/<feature>.plan.md`) that enumerates the scenarios to test. **Always** write the spec to a file.
+
+### 1.1 Prerequisite: workspace
+
+Check the workspace has Playwright installed before anything else:
+
+```bash
+# Either of these confirms a workspace:
+test -f playwright.config.ts || test -f playwright.config.js
+npx --no-install playwright --version
+```
+
+If there is no Playwright install, bootstrap one and let the user pick the defaults:
+
+```bash
+npm init playwright@latest
+```
+
+### 1.2 Prerequisite: seed test
+
+A **seed test** is a minimal test that lands the page in the state every scenario starts from: navigation to the app, any required login, feature flags, etc. Scenarios assume a fresh start *after* the seed. `--debug=cli` pauses *inside* this test, so the seed is where every planning and generation session begins.
+
+Minimum viable seed:
+
+```ts
+// tests/seed.spec.ts
+import { test } from '@playwright/test';
+
+test('seed', async ({ page }) => {
+  await page.goto('https://example.com/');
+});
+```
+
+Preferred — push navigation into a fixture so scenario tests reuse it:
+
+```ts
+// tests/fixtures.ts
+import { test as baseTest } from '@playwright/test';
+export { expect } from '@playwright/test';
+
+export const test = baseTest.extend({
+  page: async ({ page }, use) => {
+    await page.goto('https://example.com/');
+    await use(page);
+  },
+});
+```
+
+```ts
+// tests/seed.spec.ts
+import { test } from './fixtures';
+
+test('seed', async ({ page }) => {
+  // Fixture already navigates. This empty body tells agents where to start.
+});
+```
+
+If no seed exists, create one that at least navigates to the app.
+
+### 1.3 Explore the app
+
+Launch the app via the seed in the background and attach:
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli
+# wait for "Debugging Instructions" and the session name tw-XXXX
+playwright-cli attach tw-XXXX
+```
+
+Resume so the seed runs, then probe the app:
+
+```bash
+playwright-cli resume                   # resume so that seed test runs fully
+playwright-cli snapshot                 # inventory of interactive elements
+playwright-cli click e5                 # follow a flow
+playwright-cli eval "location.href"     # read URL / state
+playwright-cli show --annotate          # ask the user to point at something
+```
+
+Map out:
+
+- Interactive surfaces (forms, buttons, lists, filters, modals).
+- Primary user journeys end-to-end.
+- Edge cases: empty states, validation errors, very long input, boundary values.
+- Persistence: reload, local/session storage, URL fragments.
+- Navigation: which controls change the URL, back/forward behaviour.
+
+**Important**: Do not just open the app url with playwright-cli, always go through the test to capture any custom setup done there.
+**Important**: Stop the background test when done exploring.
+
+### 1.4 Write the spec file
+
+Save under `specs/<feature>.plan.md`. Use this structure:
+
+```markdown
+# <Feature> Test Plan
+
+## Application Overview
+
+<One paragraph describing what the feature does and why it matters.>
+
+## Test Scenarios
+
+### 1. <Group Name>
+
+**Seed:** `tests/seed.spec.ts`
+
+#### 1.1. <kebab-case-scenario-name>
+
+**File:** `tests/<group>/<kebab-case-scenario-name>.spec.ts`
+
+**Steps:**
+  1. <Concrete user step>
+    - expect: <observable outcome>
+    - expect: <another observable outcome>
+  2. <Next step>
+    - expect: <outcome>
+
+#### 1.2. <next-scenario>
+...
+
+### 2. <Next Group>
+
+**Seed:** `tests/seed.spec.ts`
+...
+```
+
+Guidelines:
+
+- Each scenario is independent and starts from the seed's fresh state — never chain scenarios.
+- Scenario names are kebab-case and match the test file name (`should-add-single-todo` → `should-add-single-todo.spec.ts`).
+- Cover happy path, edge cases, validation, negative flows, persistence.
+- Write steps at the user level ("Type 'Buy milk' into the input"), not the API level ("call `fill`").
+- Put observable outcomes in `- expect:` bullets; each becomes an assertion during generation.
+
+---
+
+## 2. Generate
+
+Goal: take a spec file and produce Playwright test files. Optionally update the spec if it has drifted.
+
+### 2.1 Inputs
+
+- **Spec file**, e.g. `specs/basic-operations.plan.md`.
+- **Target**: either a single scenario (e.g. `1.2`), a whole group (`1`), or all.
+- **Seed file**, read from the `**Seed:**` line of the scenario's group.
+
+### 2.2 Generate one scenario
+
+For each target scenario, in sequence (never in parallel — scenarios share the seed session):
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test <seed-file> --debug=cli   # background
+playwright-cli attach tw-XXXX
+# resume
+```
+
+**Do not** just open the app url with playwright-cli, always go through the test to capture any custom setup done there.
+
+Walk the scenario's `Steps:` one by one with `playwright-cli`, treating the spec as the plan and the live app as the source of truth. If a step is vague ("click the button" — which button?), references an element that no longer exists, or contradicts the app's actual behaviour, use your judgement: update the spec to match what the app really does, then keep going. Editing the spec mid-generation is expected.
+
+Every action prints the equivalent Playwright TypeScript (see [How generation works](#0-how-generation-works)):
+
+```bash
+playwright-cli snapshot                         # find refs
+playwright-cli fill e3 "John Doe"               # -> page.getByRole('textbox', {...}).fill(...)
+playwright-cli press Enter
+playwright-cli click e7
+```
+
+For each `- expect:` bullet, add an explicit assertion. See [How generation works](#0-how-generation-works) for details.
+
+Collect the generated code and write the test file at the path given in the spec:
+
+```ts
+// spec: specs/basic-operations.plan.md
+// seed: tests/seed.spec.ts
+import { test, expect } from './fixtures';   // or '@playwright/test' if no fixtures file
+
+test.describe('Signing in and out', () => {
+  test('should sign in', async ({ page }) => {
+    // 1. Navigate to the application
+    // (handled by the seed fixture)
+
+    // 2. Type 'John Doe' into the username field
+    await page.getByRole('textbox', { name: 'username' }).fill('John Doe');
+
+    // 3. Type password
+    await page.getByRole('textbox', { name: 'password' }).fill('TestPassword');
+
+    // 4. Press Enter to submit
+    await page.getByRole('textbox', { name: 'password' }).press('Enter');
+
+    await expect(page.getByRole('heading')).toContainText('Welcome, John Doe!');
+  });
+});
+```
+
+Rules:
+
+- **One test per file.** File path, describe name, and test name come verbatim from the spec (minus the ordinal).
+- Prefix each numbered step with a `// N. <step text>` comment before its actions.
+- Use the describe group name verbatim from the spec (no `1.` ordinal).
+- Import from `./fixtures` if the project has one; otherwise `@playwright/test`.
+- **Important**: close the CLI session and stop the background test before moving to the next scenario.
+
+### 2.3 Generate multiple scenarios
+
+Loop 2.2 over the targeted scenarios one at a time, restarting the seed between each so every test starts from a clean page. This is safe to parallelise due to unique generated session names - just make sure each test run is stopped.
+
+### 2.4 Run generated tests
+
+After generation, run the new tests once:
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts
+```
+
+Any failure goes to Section 3.
+
+---
+
+## 3. Heal
+
+Goal: fix failing tests, and update the spec if the app's intended behaviour changed.
+
+### 3.1 Find failing tests
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+```
+
+Record the list of failing `<file>:<line>` entries and process them one at a time. Do not attempt parallel fixes — shared state and the single CLI session make that fragile.
+
+### 3.2 Debug one failure
+
+Run the single failing test in debug mode in the background, then attach:
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts:<line> --debug=cli
+# wait for "Debugging Instructions" and the tw-XXXX session name
+playwright-cli attach tw-XXXX
+```
+
+The test is paused at the start. Step forward or run to until just before the failing action or assertion, then diagnose:
+
+```bash
+playwright-cli snapshot                # did the element change / move / rename?
+playwright-cli console                 # app-side errors?
+playwright-cli requests                # failed request? wrong payload?
+playwright-cli show --annotate         # ask the user to point somewhere
+```
+
+Common causes: selector drift, new wrapper element, label/ARIA rename, timing (transition, async load), assertion text updated in the app, test data leaking between runs.
+
+Rehearse the corrected interaction with `playwright-cli` — the generated code in the output is what you paste back into the test.
+
+### 3.3 Apply the fix
+
+Edit the test file: update the locator, assertion, step order, or inputs to match the corrected behaviour. Stop the background debug run. Rerun the single test to confirm green.
+
+Never skip hooks or add sleeps as a fix. Never use `networkidle`.
+
+### 3.4 Reconcile with the spec
+
+Open the spec referenced by the `// spec:` header in the test file and locate the scenario that matches the test.
+
+- **Fix was purely technical** (locator drift, better assertion shape) and the spec's user-level behaviour still matches the app → leave the spec alone.
+- **Fix changed user-visible steps, inputs, order, or expected outcomes** that the spec describes → update the spec to match reality. Keep the scenario id and file path stable; only the step / expect lines change.
+- **Unclear whether the app change is intentional** (spec is stale) **or a regression** (test was right, app is wrong) → **stop and ask the user**. Provide:
+  - the scenario id (e.g. `2.3`),
+  - the spec lines that no longer match,
+  - the observed app behaviour (quote a snapshot excerpt or a concrete outcome).
+
+Only after the user answers, either update the spec (intentional change) or file/flag the test as covering a bug (regression).
+
+### 3.5 Iteration and giving up
+
+- Fix failures one at a time; rerun after each.
+- If after thorough investigation you are confident the test is correct but the app is wrong *and* the user has confirmed it's a bug: mark the test `test.fixme(...)` with a comment pointing at the user's decision or issue link. Never silently skip.
+
+---
+
+## Cross-references
+
+| For... | See |
+|---|---|
+| `--debug=cli` / attach mechanics | [playwright-tests.md](playwright-tests.md) |
+| Mocking requests during exploration/generation | [request-mocking.md](request-mocking.md) |
+| Managing the CLI browser session | [session-management.md](session-management.md) |

package/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,5 @@
+# Tracing 输出边界
+
+受治理的 `frontend-test` DAG 不提供 tracing 输出能力。
+
+该 DAG 的证据边界仅保留有界的 screenshot、pdf 和 snapshot evidence。需要记录的验证结论应以这些有界证据为准。

package/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,5 @@
+# Video 输出边界
+
+受治理的 `frontend-test` DAG 不提供 video 输出能力。
+
+该 DAG 的证据边界仅保留有界的 screenshot、pdf 和 snapshot evidence。需要记录的验证结论应以这些有界证据为准。

package/skills/playwright-cli-case-generator/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: playwright-cli-case-generator
+description: 根据 FE-test RAG 知识包生成可由受限 playwright_cli runtime 串行执行的前端功能测试用例、索引和 case manifest。
+---
+
+# Playwright 用例生成器
+
+你是 Playwright 专家，擅长通过 `playwright-cli` skill 进行 UI 自动化测试。
+
+仅用于 FE-test DAG 的 `generate-frontend-functional-cases-pi`。本 skill 生成**中文** Markdown
+测试用例和 `manifest.draft.json`，不执行浏览器、不生成测试源码，也不修改被测应用。
+说明、步骤意图、预期结果用中文；命令、编号、URL、状态字段保持机器可读，禁止无意义中英双写。
+
+生成的 case 步骤写成 `playwright-cli <command> ...` 行；执行阶段由 frontend-test browser child
+通过结构化 `playwright_cli` tool 消费。生成节点本身不获得 command capability。
+填空骨架见 `docs/templates/frontend-test-case.example.md`。
+
+## 输入与边界
+
+- 只读取 `testcase/frontend/rag/context.md`、`coverage-map.md`、`standard-scenarios.v1.json`
+  与已有 `testcase/frontend/cases/`。
+- 只写 `testcase/frontend/cases/**`；不得回读 PRD、读取 `.harness/`，或写
+  `testcase/frontend/evidence/**`。不得写最终 `manifest.json`（只写 `manifest.draft.json`）。
+- 所有 API、字段限制、状态流转、数据来源、SLA、URL 与账号要求必须能在 RAG 知识包中追溯。
+  缺失信息标记 `blocked` 或“需人工确认”，不得猜测。
+- 按 AC 与 `priority=must` 标准场景覆盖（或记 GAP）。不要为凑满 `maxCasesPerBatch`（默认 50，最高 100）灌水。
+
+## 输出
+
+- 写 `index.md`、`manifest.draft.json` 与独立 case 文件
+  `FE-<FEATURE>-<NNN>-<dimension>.md`。
+- **推荐维度**：`core`、`boundary`、`flow`、`backend`、`ux`。允许其它 kebab-case 扩充维度；
+  禁止同义词滥造。dimension 须与 `caseId` 后缀一致。
+- **ID 契约（高频失败点，禁止混用）**：
+  - `caseId` / 文件名 = **用例 ID**，形态 `FE-<FEATURE>-<NNN>-<dimension>`
+    （例：`FE-LOGIN-001-core`、`FE-LOGIN-002-ux`）。禁止把验收标准写成 caseId。
+  - `acIds` = **验收标准 ID 列表**，形态 `AC-FE-*` / `AC-*`
+    （例：`["AC-FE-001"]`）。禁止把用例 ID 放进 acIds。
+  - `casePath` 必须等于 `testcase/frontend/cases/<caseId>.md`；
+    `evidenceDir` 必须等于 `testcase/frontend/evidence/<caseId>/`。
+- `manifest` 使用 `schemaVersion: 1`，每项只含 `caseId`、`casePath`、`dimension`、`acIds`、
+  `evidenceDir`。所有 ID、路径和 evidenceDir 必须唯一，并位于 `testcase/frontend/` 内。
+- `index.md` 按功能点列出 case、维度、AC、数据依赖、API 映射和预期执行状态。
+
+每个 case 必须包含：
+
+1. 元信息：功能、CRUD 分类、维度、关联 AC、RAG 来源、API 映射状态与数据策略。
+2. 前置条件：默认浏览器 session 中的登录状态、fixture/存量数据、清理责任；不得用
+   `-s=<case-id>` 建立 named session。
+3. 可独立执行的命令序列（见下方入口 URL 规则）。每个拟通过场景必须在入口之后以成功的 `find`
+   作为唯一结构化 UI 语义断言。`snapshot`、`goto`、`screenshot`、`requests`、`request`
+   和普通交互不能单独取得 passed authority。
+4. **动态元素 ref（硬约束）**：可执行的 `playwright-cli` 行绝不得包含尖括号 token。
+   只能使用 `eX`、`eY` 等；每次引用元素前写明 fresh snapshot。
+5. 明确的中文 UI/API 预期与数据清理结果；无法满足的环境或数据依赖必须写为 `blocked`。
+
+### 入口 URL 规则（硬）
+
+从 `context.md` 复制已探测可达的绝对非生产地址。
+
+| 情况 | 做法 |
+| --- | --- |
+| 需要登录 | `playwright-cli open --browser=chrome {{LOGIN_URL}}`，完成登录并用 `find` 确认，再 `playwright-cli goto {{TARGET_URL}}`。不要第二次 `open`。 |
+| 无需登录 | `playwright-cli open --browser=chrome {{TARGET_URL}}` |
+| 已登录（默认会话仍有效） | `open {{TARGET_URL}}`；若浏览器已打开则 `goto {{TARGET_URL}}`，不要再 `open` |
+
+文件型输出一律 canonical `--filename`（`final.png` / `final.pdf` / `snapshot.txt`）。不得使用
+`--path`、`--output`、`--file`。
+
+### playwright-cli-only（硬约束）
+
+- 用例步骤只能使用 `playwright-cli` skill 已声明的命令语法。
+- 不生成其他浏览器自动化调用、测试运行器调用或测试源码。
+- `playwright-cli` 不可用时不得降级；应写 blocked evidence，
+  `blockedReason: playwright-cli-unavailable`。
+
+## 覆盖矩阵
+
+| 类型 | 必选 | 条件 |
+| --- | --- | --- |
+| C-新增 | `core`、`boundary` | 有状态流转时 `flow`；有 API 映射时 `backend` |
+| R-查询 | `core` | 有搜索/筛选输入时 `boundary`；有 API 映射时 `backend` |
+| U-修改 | `core`、`boundary` | 有状态流转时 `flow`；有 API 映射时 `backend` |
+| D-删除 | `core` | 有 API 映射时 `backend` |
+| 交互体验 | `ux`：must 场景 `STD-FE-LOADING-DISABLED`、`STD-FE-FEEDBACK-TOAST` | 其余 UX should 有 RAG 证据再写，否则 GAP |
+
+- `boundary` 只从已知必填、长度、范围、精度、枚举或字符规则推导；无约束时不伪造边界值。
+- `flow` 是自包含的多步状态旅程；不依赖其他 case 创建的数据。
+- `ux` 只用 allowlist 可观察的文案/禁用/提示；不要断言手感或动画帧。
+- `backend` 只在 API 映射存在时使用 `requests` / `request <id>`。
+
+## 数据策略
+
+- C-新增优先使用需求中给出的测试数据。
+- R 查询优先使用知识包登记的 fixture 或当前用户可见数据。
+- **U/D 修改删除归属顺序（硬约束）**：
+  1. 仅操作可由**当前登录用户身份**与 UI/API 可观测归属字段共同证明的数据。
+  2. 当前用户无可用数据时，优先在当前用户上下文创建可清理数据，再 U/D，并验证清理。
+  3. 无法安全创建时，仅可使用任务源/RAG 已确认的 Mock，并明确标注。
+  4. 否则写 `blocked`：`current-user-data-unavailable` |
+     `data-ownership-unverifiable` | `safe-test-data-setup-unavailable`。
+  5. 禁止修改/删除其他用户数据、共享 fixture、生产数据。
+- 禁止使用生产 URL、真实用户凭据或不可清理的数据写入。
+
+## 交接
+
+生成结束时仅返回紧凑 JSON 摘要：case 总数、各维度数量、manifest 相对路径、blocked case ID
+与原因。详细内容保留在中文 case 文件中。

package/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: requesting-code-review
+description: 在完成任务、实现 major features，或 merge 前验证 work 是否满足 requirements 时使用
+---
+
+# Requesting Code Review
+
+Dispatch code reviewer subagent，在问题级联前捕获 issue。Reviewer 获得精确 crafted 的 evaluation context — 绝不是你的 session history。这使 reviewer 聚焦 work product，而非你的 thought process，并保留你自己的 context 以继续工作。
+
+**Core principle：** Review early, review often.
+
+## When to Request Review
+
+**Mandatory：**
+- subagent-driven development 中每个 task 之后
+- 完成 major feature 之后
+- merge 到 main 之前
+
+**Optional but valuable：**
+- 卡住时（fresh perspective）
+- refactoring 前（baseline check）
+- 修复 complex bug 之后
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Use the code reviewer template**（本 skill 目录下的 `code-reviewer.md`）：
+
+**Placeholders:**
+- `{DESCRIPTION}` — 简要 summary of what you built
+- `{PLAN_OR_REQUIREMENTS}` — 它应做什么（contract、exec plan 或 requirements）
+- `{BASE_SHA}` — Starting commit
+- `{HEAD_SHA}` — Ending commit
+
+**3. Act on feedback:**
+- Critical issues 立即修复
+- Important issues 在继续前修复
+- Minor issues 稍后处理
+- Reviewer 有误时 push back（附 reasoning）
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch code reviewer subagent]
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+  PLAN_OR_REQUIREMENTS: Task 2 from ai_workspace/loop-agent/exec-plans/active/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Harness Workflow
+
+**每个 work chunk 之后（Plan → Contract → Implement → Verify → Handoff）：**
+- Implement 之后、Verify 之前 review
+- 在问题 compound 前捕获
+- 进入 next task 前修复
+
+**Before merge / Handoff：**
+- 宣称 complete 前 review
+- 对照 contract acceptance criteria 验证
+
+**Ad-Hoc Development：**
+- merge 前 review
+- 卡住时 review
+
+## Red Flags
+
+**Never：**
+- 因 "it's simple" 跳过 review
+- 忽略 Critical issues
+- 带着未修复的 Important issues 继续
+- 与 valid technical feedback 争辩
+
+**If reviewer wrong：**
+- 用 technical reasoning push back
+- 展示证明其有效的 code/tests
+- 请求 clarification
+
+Template 见：requesting-code-review/code-reviewer.md