octopus-workflow/core/skills/implement/SKILL.md

name, description, triggers, role

name	description	triggers	role
implement	Use ONLY when implementing a work item from an approved iteration plan, OR fixing a bug (bugfix mode), OR refactoring code (refactor mode), OR porting a feature (port mode). The Developer (Worker) reads the work item, design sections, and acceptance criteria, writes code, and self-checks against the relevant checklist before handing off to code review.	implement implement work item implement WI- work item 实现工作项 开始写代码 implement the iteration bugfix fix a bug fix bug fix this bug 修复 修复bug help me fix doesn't work does not work not working is broken stack trace throws an error crashes refactor 重构 restructure 删除死代码 dead code improve code structure 重新组织代码 graduate experimental remove experimental guard 移除实验性 port porting port feature port this feature migrate feature 移植 迁移功能 code change write code	Producer

Core 中立版（Increment 6a 改写，原 deferHard verbatimDir）。机制、结构与 frontmatter 保持；实例术语（工具名、路径、工单号）按 core/adapters/TERMINOLOGY.md 绑定到具体实例。

Skill: implement

Mode Selection

This skill handles four work modes. The main session identifies the mode from the work item's type field or the user's request:

Mode	When to use	Key difference
implement (default)	Work item from an approved iteration plan	Standard implementation per acceptance criteria
bugfix	User reports a bug / fix request	Reproduce → root cause → regression test (must FAIL first) → minimal fix
refactor	User asks to restructure code (no behavior change)	Establish baseline → transform in ≤10 steps → verify zero regression
port	User asks to port a feature from another project	Read source → map concepts → implement in target conventions → verify fidelity

In standalone mode (user-initiated, no iteration plan), skip preconditions about plan/approval and go directly to the mode-specific workflow.

In pipeline mode (work item from iteration plan), follow the standard preconditions then the mode-specific phases.

On-demand references: each mode's phase-by-phase detail (templates, prompts, orchestration flows, historical notes) lives in reference/{mode}-mode.md, NOT injected — read it at mode entry. Full read-timing table: References section.

Progressive disclosure ([org-internal #3734]): when dispatching a Developer scoped to one mode, pass skills: ["implement:mode-bugfix"] (preamble + that mode's workflow only) instead of the full body; pipeline-mode dispatches should also carry pipeline-detection ("implement:mode-implement,pipeline-detection"). Mode Selection, Agent Role, Greenfield vs. Brownfield, … are unmarked preamble and always inject. Full-body remains the default when no selector is passed.

Agent Role

The implementation is owned and produced by the Developer (Worker). The Builder delegates each work item to a dedicated Developer sub-agent with the full design and plan context.

Role naming: throughout this skill, "Builder", "Orchestrator", and "main session" name the same coordinating role (the main session that dispatches Developer sub-agents and validates output) — not a distinct role from the "Orchestrator" used by review-code and the shared review pipeline.

The Developer is responsible for:

• Reading the assigned work item, design sections, and acceptance criteria.
• Writing code that faithfully implements the design.
• Running typecheck, lint, and tests to self-verify.
• Self-checking against the relevant checklist before handoff.
• Persisting the final report to disk before returning — worker-report persistence ([org-internal #2847], see ../_shared/worker-report-persistence.md).
• Writing no more and no less than the work item scope — no opportunistic refactoring of unrelated code.

The Builder's role is to validate the implementation output and pass it to code review. The Builder MUST NOT write or revise implementation code.

Pre-flight checklist injection ([org-internal #2599])

Before dispatching ANY Developer (or Tester) sub-agent — in every mode (implement / bugfix / refactor / port; pipeline or standalone) — the orchestrator resolves the ticket's route (the Process Assessment Gate Step 0 already resolves the Kind/* route) and reads <instance-root>/workflow-routing.yaml routes.{Kind}.preflight. When the list is non-empty, prepend it to the sub-agent's task prompt as:

Pre-flight self-check (evidence-based, from retrospective — verify each
BEFORE writing code; if one is already satisfied, note why in impl-notes):
1. {item} (evidence: {evidence})
2. ...

Rules:

• The list is a human-landed checklist (retro proposes, a human lands it) — NEVER synthesize or extend items at dispatch time.
• Cap at preflight.max_items entries; beyond it, drop oldest by added_cycle.
• Items are self-checks, not gates: an unsatisfied item means the Developer addresses it in the implementation (and says how), not that dispatch aborts.

Context compaction: this skill is a pipeline stage boundary. The main session (orchestrator) compacts at this clean boundary ONLY when a capacity/projection trigger holds, per the L1 rule core/rules/compact.md §"Stage-boundary compaction" (long multi-stage runs — DAG Epic orchestration — keep the legacy every-boundary compaction; short runs — bugfix / DAG task — and standalone runs default to NOT compacting). The sub-agent this skill dispatches persists its artifacts to the Gitea wiki under {slug}/ as it goes, so a mid-run compaction loses nothing — re-read the stage's wiki index to resume.

Role Split: Developer vs Tester

Each execution mode below defines its own Tester focus and any mode-specific orchestration overrides.

Greenfield vs. Brownfield

Greenfield (new project): Create new files following the design. Project conventions are defined by the design document.

Brownfield (existing project + new feature):

• Read neighbors first. Before writing code, read at least 3 existing files in the same module to absorb the project's code patterns. (Shared brownfield rule — canonical statement: core/skills/review-code/SKILL.md §"Greenfield vs. Brownfield"; the threshold and same-module scope are defined there.)
• Match existing conventions exactly: error handling style, logging format, naming, file structure, import ordering, type declaration placement.
• New code MUST follow existing conventions consistently — no style drift.
• No opportunistic refactoring of unrelated existing code. If you see a bug or improvement opportunity in unmodified files, log it in the implementation report as a separate observation — do not fix it in this work item.
• Phase 1 (Parse Context) includes reading neighboring code files to establish the project's conventions. Phase 4 (Self-Check) compares new code against these conventions.

---

Execution Modes

Mode: implement (default)

Standard workflow for work items from an approved iteration plan. Full phase detail, templates, prompts: reference/implement-mode.md (read at mode entry).

Preconditions

DAG-mode input path (DAG ticket pipeline — Kind/Epic / Kind/Feature DAG parent, routes-table direct): DAG-routed tickets ignore Size/* — the tiered Preconditions below are replaced by the node spec: work item + acceptance criteria resolve from the frozen DAG copy wiki page {epic-slug}/dag (+ {epic-slug}/dag-nodes/{node-id} subpages when AC detail is sunk) and the node ticket's issue body — no legacy {slug}/04-plan-* page, no Size/*-tiered req/design page. The design-space + iteration-plan convergence preconditions are replaced by the review-dag single-gate convergence: octopus review status --stage review-dag must show success before the node is implemented.

DAG-route read map (every legacy {slug}/04-plan-* / {slug}/03-design-* reference below resolves from the frozen DAG copy instead — mirror of verify/SKILL.md's DAG branch; full map: reference/implement-mode.md § Preconditions):

• Work item (04-plan-04-iteration-assignment / issue body) → node spec in {epic-slug}/dag + node ticket body.
• Acceptance criteria (04-plan-05-acceptance-criteria / issue body) → node acceptance_criteria (+ sunk subpages) + node ticket body.
• test_id (測試用例 ID) → the test_id declared on the node AC in {epic-slug}/dag.
• Design sections / interface design (03-design-**) → node spec + cross-session edge contracts (no design page).
• Component mapping (03-design-08-traceability) → node req_refs + component field.

At Phase 6 handoff, pass mode: "dag-task" to review-code (its DAG Task Mode keys off the same frozen-DAG-copy detection).

Legacy pipeline preconditions retired ([org-internal #3072] phase 3, 2026-08-21): tiered artifact-existence and review-convergence checks belonged to the archived legacy pipeline. Live input modes: DAG task mode (above) and standalone modes (the request itself is the spec). Historical tiered publish targets: reference/implement-mode.md § Legacy notes.

Before starting implementation, confirm:

• Work item is specified (DAG node ticket {node-id}, or a clear task description in standalone modes).
• core/checklists/implementation.md is accessible.
• slug matches the run's slug (DAG: {epic-slug}).
• 跨阶段门控清单: core/checklists/pipeline-gate.md accessible and its DAG 路由变体 section confirmed — frozen DAG copy exists, single gate converged, upstream dependencies at terminal state (ready); else abort, listing the blocked nodes.

If any precondition is unmet, abort and inform the user — list every missing artifact, un-converged review, and blocked dependency (complete gate checklist + Recovery Protocol: core/checklists/pipeline-gate.md). When no work item is specified, resolve the ready/pending task nodes from {epic-slug}/dag and present them for selection (prompt: reference/implement-mode.md § Preconditions — work-item selection).

Phases skeleton

Every gate below is hard — agents rationalize skipping exactly these. Full detail: reference/implement-mode.md.

1. Phase 1 — Parse Context: read the work item (node spec + node ticket), acceptance criteria (every falsifiable AC-{n} / NFR: entry and its declared test_id), design context (cross-session edge contracts), and the existing codebase; resolve inputs per the DAG-route read map (standalone: the request). Read every referenced design file before writing code.
2. Phase 2 — Plan Implementation: brief plan (template: reference/implement-mode.md § Phase 2). GATES: ≤ 3 files per work item (more → the Builder/user MUST split it); every file must map to a design component (else flag the design gap and abort); do NOT invent design decisions. Present the plan and ask: proceed? (yes / no / revise).
3. Phase 3 — Implement: design-exact code; tests cover every AC.
   • Design discipline: component interfaces, method signatures, return types, data model fields, API endpoints/schemas/status codes MUST match the design exactly; an impossible design decision → stop and report the gap, never silently deviate.
   • Test discipline (Red → Green, declared test_ids): write each declared test FIRST and confirm it fails for the intended reason (Red) before writing the implementation (Green); the test's file-path :: test-name MUST match the declared test_id exactly — the implement-side handshake with verify (DOD-1.6). MANUAL / BENCH:<script> test_ids are exempt from the Red step; an already-passing test is noted in the Phase 5 report, not forced to fail.
   • Code quality + incremental commitments (conventions, no unjustified dependencies, public-API docs; shared types → data access → logic → handlers, typecheck per unit): reference/implement-mode.md § Code Quality.
4. Phase 4 — Self-Check (all mandatory):
   1. bun typecheck (or project-equivalent) — zero errors.
   2. bun oxlint --deny-warnings (repo root — the review-code mechanical gate's canonical lint invocation; bun lint is the package-script alias) — zero errors.
   3. bun run test:changed (or project-equivalent; full suite bun run test:parallel is verify's job, not a per-revision gate, [org-internal #2598]) — all tests pass.
   4. Post-deletion cleanup (when any code was removed): re-run lint + typecheck to catch orphaned imports/variables/type references. Then self-check core/checklists/implementation.md; every new function/method/exported API has ≥ 1 test; interface promises cross-checked against the node's edge contracts. Review-readiness GATE: self-attest core/checklists/code-review.md (COR, DGN, SEC, PERF, TST, STY, DBT, A11Y, DOC, TRC), record pass/fail per dimension in the Phase 5 report; handoff requires 0 BLOCKERs and 0 MAJORs — if you can find a MAJOR, the formal review will too; fix it now.
5. Phase 4.5 — Iteration Completion Commit: after ALL work items in the iteration pass Phase 4, commit with format [{chunk-id}][{iteration}] {summary}; commit body REQUIRED for non-trivial commits (> 1 file or > 20 LOC): What (files + purpose + the WI-{NNN} ID — code-review TRC 10.1), Why (design/REQ motivation), Evidence (test names / verification commands). Full rules: reference/implement-mode.md § Phase 4.5.
6. Phase 4.6 — Issue Checklist Sync (progressive): after committing, mark items this iteration delivered - [x] + _(commit {sha}: file/component)_ per the issue-checklist-sync L1 rule; do NOT touch items outside this iteration's scope.
7. Phase 4.7 — PR-Creation Sync: the session pushes its branch and reports status=done branch=<ref> verify=… risk=… — the orchestrator opens the PR (serially per TD-678/[org-internal #4425]) and applies the Risk/* label from the report's risk= hint, computed per the risk-classifier frozen table (HIGH_RISK_GLOBS in .gitea/scripts/risk-classifier.ts: core/migrations/deploy/core/rules/**/.gitea/workflows/** → Risk/High, else Risk/Low); Risk/High PRs merge manually by design. Once the PR exists, ensure ## 当前状态 exists (PR / 代码评审 / CI rows are written by the status-sync poller, NOT by hand); append the PR reference to the matching Epic task-list row. Never hand-sync main into the PR branch — that is the keep-mergeable workflow's job. Detail: reference/implement-mode.md § Phase 4.6 / § Phase 4.7.
8. Phase 5 — Report: implementation report with AC → test traceability (template: reference/implement-mode.md § Phase 5). Persist before returning ([org-internal #2847]) — the Developer's LAST action before returning the report: write it to <runs-root>/{slug}/workers/{chunk-id}-worker-{seq}.md (Tier 1 run workspace) else /tmp/octopus/{chunk-id}-worker-{seq}.md (../_shared/worker-report-persistence.md). The persisted copy is the report of record — applies to EVERY mode's report phase.
9. Phase 6 — Handoff to Code Review: present the report; signal readiness via signal_stage_done. Do NOT mark the work item complete until code review passes.

Tester focus & Common Rationalizations

Boundary + contract tests — the cases the Developer is structurally biased to miss; every acceptance criterion MUST map to ≥ 1 test. Implementation fails far more from pressure than from ignorance — full detail (11-row Excuse → Reality table): reference/implement-mode.md § Tester focus for implement / § Common Rationalizations.

---

Mode: bugfix

Reproduce, isolate, and fix a bug with a regression test that MUST fail before the fix. Small localized bugs → standalone (existing system behavior is the specification; review gate optional — only when > 20 lines or ≥ 3 files); large/complex bugs → pipeline (review + verify mandatory). Phase detail, templates, prompts: reference/bugfix-mode.md (read at mode entry).

Routing override (ticket-seeded): the Optional/None gate above applies to user-initiated standalone mode. A Kind/* route whose keep_gates includes review-code / verify (e.g. Kind/Bug, Kind/Testing) makes those gates MANDATORY regardless of size (a gate is mandatory if EITHER the route OR the skill requires it; skipping is valid only when BOTH agree).

Phases skeleton

The regression test MUST fail before the fix — the Tester dispatches between Phase 2 and Phase 4, not after the fix (dispatch flow: reference/bugfix-mode.md § Role & Responsibilities; single-Developer invocation only for trivial single-file fixes — force the split when the fix touches ≥ 2 files or the root cause spans ≥ 2 levels of indirection).

1. Phase 1 — Understand & Reproduce: read relevant code; check existing tests (a passing test on this path → the bug is in the test or an uncovered branch); reproduce and document (template: reference/bugfix-mode.md § Phase 1). If the bug CANNOT be reproduced, stop and report — do not guess-patch.
2. Phase 2 — Isolate Root Cause: trace symptom → proximate cause → root cause (RCA template: reference/bugfix-mode.md § Phase 2); fixing a symptom → stop, go deeper; not found after 3 levels of indirection → pause and report, no surface-level patch. Then evaluate routing (below).
3. Phase 3 — Write a Regression Test: exercise the exact bug path with the failing inputs; it MUST fail with the bug's symptom NOW, before the fix (already passing → the test does not cover the bug, rewrite it; no failing test possible → most targeted test, marked [flaky]).
4. Phase 4 — Fix: minimum change resolving the root cause; one conceptual change per fix — no bundled refactoring, style changes, or "while I'm here" improvements (root cause in a different file → fix it there). Run the regression test (MUST pass) + relevant unit tests.
5. Phase 5 — Self-Check & Report: bun typecheck; bun oxlint --deny-warnings; bun run test:changed (all pass; full suite belongs to verify); verify core/checklists/bugfix.md; publish the bugfix report as wiki page {slug}/bugfix-report (template: reference/bugfix-mode.md § Bugfix Report); persist per the Phase 5 persistence rule (Mode: implement, [org-internal #2847]).
6. Phase 5.5 — Issue Checklist Sync (standalone bugfix): sync the source issue at each transition (commit / PR / review / CI / close) per the issue-checklist-sync L1 rule and its standalone-flow table.
7. Phase 6 — Approval: present the report (prompt: reference/bugfix-mode.md § Phase 6 — Approval).

Routing Decision (after Phase 2)

Full escalate/stay criteria: reference/bugfix-mode.md § Routing Decision. In short — escalate to pipeline on ANY of: ≥ 5 files · ≥ 2 modules/components · design-level root cause · data migration / schema change · public-API / contract change · dependency change · > 50 lines · user requests full-process; stay standalone only when ALL the opposites hold. If uncertain, escalate — a false escalation costs review rounds; a false standalone decision skips quality gates.

Big-bug relabel rule ([org-internal #3061]) — before the generic escalation above, split the triggers by kind:

• Design-level triggers (root cause is a design decision — protocol / schema / architecture; shared-contract or public-API change; data migration): do NOT push through bugfix — relabel the ticket Kind/Feature and reroute via Step 0 (DAG route; 1–3 node small DAG expected); repro + root-cause notes become node input.
• Mechanical size triggers only (many files / lines, same design): stay in bugfix — batch into iterations, keep review-code + verify. Scale alone never justifies a relabel.

Pipeline Mode (bugfix)

Legacy path retired ([org-internal #3072] phase 3): the requirements → design → review → plan front-end was archived; a big bug needing a design-level decision relabels Kind/Feature into the DAG route (big-bug relabel rule above).

When a bugfix escalates beyond standalone scope, the bug report becomes a pipeline input; the bugfix phases (reproduce, root cause, regression test, fix) are embedded within the implement stage, and review-code + verify remain mandatory. On the DAG route the node spec lives in {epic-slug}/dag; the Developer follows bugfix Phases 1–6 as the implementation method, then produces the standard implementation report (Mode: implement, Phase 5).

Pipeline abort criteria — before any code is written in pipeline mode, abort if ANY of: (1) bug no longer reproduces; (2) root-cause hypothesis falsified during re-isolation; (3) resolved by external change; (4) reproduction confidence < 3/5 after one re-isolation iteration. Abort procedure ({slug}/ABORT wiki page, no commit/merge, retrospective, archive): reference/bugfix-mode.md § Pipeline Abort Criteria. Once code is written, abort is no longer valid — the run proceeds review-code → verify.

Common Rationalizations (bugfix) & Incident Triage — full 9-row Excuse → Reality table + Incident Triage Carve-Out (under active incident pressure the Phase 2→3 ordering MAY be relaxed, never skipped — a stop-gap may ship first, BUT the full root-cause trace + failing regression test + proper fix MUST land in the same incident window): reference/bugfix-mode.md § Common Rationalizations (bugfix) / § Incident Triage Carve-Out.

---

Mode: refactor

Restructure existing code without changing observable behavior — the existing test suite is the safety net; every step MUST be verified before proceeding. Templates and prompts: reference/refactor-mode.md (read at mode entry). Execution modes: standalone (user says "refactor {X}"; review gate optional — only when > 50 lines or ≥ 5 files) vs pipeline (refactoring WI / DAG node; scope from the node spec, review mandatory).

Preconditions

• Scope is specified (which file, module, or pattern to refactor).
• An existing test suite covers the scope (if unknown, run with coverage first).
• No uncommitted changes (git status is clean); core/checklists/refactoring.md is accessible.

No test coverage? Stop. Refactoring without tests is rewriting with unknown side effects — write characterization tests first or skip this module (prompt: reference/refactor-mode.md § No Test Coverage? Stop.).

Phases skeleton

1. Phase 1 — Scope & Baseline: map exact files + dependents; run bun run test:parallel (the refactor baseline legitimately needs the full suite) — ANY pre-existing failure → stop ("Cannot begin refactoring with failing tests. Fix them first."). Capture baseline: test count, coverage, optional complexity (template: reference/refactor-mode.md § Baseline).
2. Phase 2 — Define Target Pattern: Extract / Inline / Rename / Move / Replace / Simplify / Upgrade, with one-sentence goal + success criteria (all tests pass unchanged; structural goal met; coverage does not decrease). Pipeline mode: align with the node spec + contracts, or justify in the report.
3. Phase 3 — Decompose into Steps: smallest individually-verifiable steps (each reversible, suite-passing, ONE conceptual transformation); present the plan before executing (user may approve / reorder / reject). If > 10 steps, the scope is too large — split into multiple sessions.
4. Phase 4 — Incremental Execution: per step — transform, run bun run test:changed (ALL pass; per-step scoped reruns — full suite is verify's job, [org-internal #2598]), commit refactor: {what} from {where}. If FAIL: revert immediately — do NOT fix the test or code within the same step; find a smaller decomposition (exception: fix a flaky test first as a prerequisite step, then retry).
5. Phase 5 — Final Validation: bun run test:parallel all pass; bun typecheck zero errors; bun oxlint --deny-warnings zero errors; coverage MUST NOT decrease vs baseline (±1% noise).
6. Phase 6 — Report: before/after metrics, steps executed, verification results, design deviations (template: reference/refactor-mode.md § Refactor Report).
7. Phase 7 — Approval: present the report (prompt: reference/refactor-mode.md § Phase 7 — Approval). Route to code review if > 50 lines or ≥ 5 files.

---

Mode: port

Port a feature from a source project into the current (target) project, preserving the source's behavioral contract while adapting every implementation detail to the target's tech stack and conventions. Orchestration, per-phase processes, and templates live in the existing reference/*.md port files (indexed in References); read reference/port-mode.md at mode entry.

Tester focus (port): behavioral-fidelity tests — every FID-* item in port-{name}/source-analysis/10-fidelity-baseline MUST map to ≥ 1 ported test (rewrite the source test in the target framework's style, preserving the contract); port edge/error/boundary tests, not just the happy path (missing FID coverage is the #1 cause of incomplete porting); every [FIDELITY DEVIATION] gets a test locking the divergent behavior.

Phase 0 — Scope Assessment

Measure the source scope — file count and LOC alone are insufficient: (1) source files; (2) source LOC (exclude tests); (3) source modules / feature areas; (4) source packages touched; (5) implicit dependency artifacts (schema/migrations, config, env vars, CLI flags, theme files, routes, providers, build config — full list: Phase A1.8). Then:

• Standalone (Part 1): ≤ 5 files, ≤ 200 LOC, 1 package, 0 implicit deps.
• Pipeline (Part 2): > 5 files or > 200 LOC · spans ≥ 3 source modules · spans ≥ 2 packages · or ≥ 3 implicit dependency artifacts (implicit deps require capability boundary analysis).

Report the assessment and do NOT proceed without explicit approval (prompt: reference/port-mode.md § Phase 0 — Scope Assessment).

Preconditions

• Source project path/reference and source feature scope specified; target project structure accessible (all monorepo packages).
• Target is the current working directory, clean workspace, existing test framework (none → warn: behavioral fidelity cannot be guaranteed — reference/port-mode.md § Preconditions).
• Target's existing capabilities documented or discoverable (else run the structural survey, Phase A1.7, first); core/checklists/port.md is accessible.

Part 1 — Standalone Mode (Small Port)

The Developer executes the full port lifecycle directly; no DAG decomposition; code review is mandatory regardless of size (Phase A8). Phases: A1 source analysis → A1.5 review GATE → A1.7 target surface → A1.8 capability boundary GATE (reference/source-analysis.md) · A2 concept mapping → A3 gap analysis → A4 adaptation design (reference/mapping-and-design.md) · A5 implement + A5.5 self-check GATE (rules below) · A6 port tests & fidelity (reference/fidelity-verification.md) · A7 report (reference/port-report-template.md) · A8 approval → code review (reference/port-mode.md § Phase A8).

Phase A5 — Implement (rules): one file at a time (port completely, verify, then move on); target conventions are law; fidelity over aesthetics — do not "improve" the source logic (port the exact validation, log [NOTE: weak validation in source]; stricter behavior is a separate feature item); port comments from source (translated); bun typecheck after each file; no new dependencies (use the adaptation-design alternative or reimplement the subset inline).

Phase A5.5 — Self-Check GATE (MANDATORY): complete core/checklists/port.md in full — every item ☑ (pass) or ☐ (fail) with written justification; every ☐ item documents an inline fix plan; known deferrals include a reactivation path (chunk + trigger); publish as wiki page port-{name}/self-check. Do NOT proceed to Phase A6 until all items are ☑ OR all ☐ items have documented fix plans AND the Developer has printed SELF-CHECK COMPLETE — {X} items passing, {Y} items deferred with plan.

Part 2 — Pipeline Mode (Large Port)

The Developer produces a source analysis report as the foundation artifact, then the port flows through the pipeline with peer-review gates: port (source analysis) → analyze-dag (decompose by source module) → review-dag single gate → per node (dag.task_route): implement → review-code → verify (integration + fidelity). Phases: B1 12-document source analysis → B1.5 10-dimensional review GATE → B1.7+B1.8 target surface & capability boundary artifacts → B2 checklist self-check → B3 handoff to analyze-dag (slug port-{name}) → B4 per-node DAG task route (reference/large-port-pipeline.md) · B5 verify — integration + fidelity, every FID-* traced to a passing test (reference/fidelity-verification.md) · B6 final approval (rules below).

Phase B6 — Final Approval: verify (1) CI is configured (absent → warn [GAP: no CI — no automated gate before merge], flag in report); (2) all review gates passed (review-dag single gate + every node's code review converged: true); (3) typecheck + lint + tests pass fresh. Present the consolidated report (prompt: reference/port-mode.md § Phase B6). Post-merge cleanup: reference/port-mode.md § Phase B7.

---

Pipeline Work Item Detection

Not all work items involve writing new code — some are refactoring, bugfix, or frontend work items. They use the workflows above (or the frontend skill) but flow through the same pipeline gates (review-code → verify; DAG-routed work resolves its spec from {epic-slug}/dag). When detected, read reference/work-item-detection.md BEFORE Phase 1 for the per-phase pipeline adaptations. Detection triggers (full keyword lists in the reference):

Work item	Detected by (examples)	Route
Refactoring	"Refactor" / "重构" / "Extract" / "Rename" … prefixes; [REFACTOR] tag; behavior-preserving structural node spec; REQ-REFACTOR-*	Mode: refactor + adaptations — code review mandatory regardless of size, no "no review needed" bypass
Bugfix	"Bugfix" / "Fix" / "修复" / "Hotfix" prefixes; [BUGFIX] tag; correction-of-behavior node spec; bug report / stack trace / RCA reference	Mode: bugfix + adaptations — code review mandatory regardless of size
Frontend	"Frontend" / "UI" / "组件" / "页面" prefixes; [FRONTEND] tag; UI-layer node spec; components in components/ pages/ views/ ui/; exclusively .tsx/.jsx/.vue/.svelte/.astro/.css/.scss files	core/skills/frontend/SKILL.md + adaptations — code review mandatory regardless of size

References

On-demand mode references (NOT injected — read at the declared timing):

• reference/implement-mode.md — Mode: implement: mode entry (phase detail); Phase 2 / Phase 5 templates; Tester focus; Common Rationalizations; legacy notes.

• reference/bugfix-mode.md — Mode: bugfix: mode entry; Phase 1–3 templates; Phase 5 report + publish; routing escalation; abort procedure; orchestration.

• reference/refactor-mode.md — Mode: refactor: mode entry; Phase 1 baseline; Phase 6 report; no-coverage stop prompt.

• reference/port-mode.md — Mode: port: mode entry; Phase 0 prompt; preconditions warnings; A8/B6 approval prompts; B7 cleanup.

• reference/work-item-detection.md — detected refactoring / bugfix / frontend work item: BEFORE Phase 1 of the matched mode.

• core/checklists/implementation.md — Implementation self-check checklist

• core/checklists/bugfix.md — Bugfix self-check checklist

• core/checklists/refactoring.md — Refactoring self-check checklist

• core/checklists/port.md — Porting self-check checklist

• core/checklists/frontend.md — Frontend self-check checklist

• core/checklists/code-review.md — Code review checklist (self-attestation)

• core/checklists/pipeline-gate.md — Cross-stage pipeline gate checklist

• core/skills/frontend/SKILL.md — Frontend workflow (for frontend work items)

• core/skills/browser-debug/SKILL.md — Interactive browser verification (for frontend work items) and UI bug reproduction (bugfix Phase 1)

• core/skills/review-code/SKILL.md — Code review (next step after implementation)

• core/skills/verify/SKILL.md — Integration + fidelity verification (pipeline-mode bugfix, large port)

• <instance-root>/archive/skills/ — Legacy requirements/design/plan/roadmap skills (archived [org-internal #3072] phase 3; their templates moved to <instance-root>/archive/templates/)

• reference/source-analysis.md — Port Phase A1, A1.5, A1.7, A1.8 detailed processes & templates

• reference/mapping-and-design.md — Port Phase A2, A3, A4 detailed processes & templates

• reference/large-port-pipeline.md — Port Phase B1–B4 detailed processes

• reference/fidelity-verification.md — Port Phase A6, B5 detailed processes & templates

• reference/source-analysis-templates.md — Port B1 document format templates

• reference/capability-boundary-template.md — Port A1.8/B1.8 13-dimension table

• reference/target-surface-template.md — Port A1.7/B1.7 output format

• reference/port-report-template.md — Port A7/B6 report format

• Martin Fowler, Refactoring: Improving the Design of Existing Code (2nd ed.)

• core/rules/ — Project engineering conventions (test commands, typecheck)

• L2 wiki pages for style-guide, effect-rules, and database conventions (see the "L2 on-demand reference" section of AGENTS.md)