octopus-workflow/core/skills/implement/reference/implement-mode.md

Extracted from implement/SKILL.md (Mode: implement) — moved verbatim 2026-08-25, ticket [org-internal #3381].

Mode: implement (default)

The standard implementation workflow for work items from an approved iteration plan. Implement a single work item, guided by the approved design, and self-verify before passing to code review.

Pre-flight

The pre-flight self-check prompt format ([org-internal #2599]), prepended to the Developer sub-agent's task prompt when routes.{Kind}.preflight is non-empty:

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. ...

Process Overview

Every diamond below is a gate agents rationalize skipping. None are optional.

digraph implement {
    rankdir=TB;
    node [shape=box, fontname="Helvetica"];

    pre      [shape=diamond, label="Preconditions\n(artifacts + reviews\nconverged)?"];
    abort    [label="ABORT: list every\nmissing item"];
    p1       [label="Phase 1: Parse Context"];
    p2       [label="Phase 2: Plan\n(≤3 files per WI)"];
    scope    [shape=diamond, label="Scope ≤3 files\nAND maps to a\ndesign component?"];
    gap      [label="Flag design gap,\nDO NOT invent decisions"];
    p3       [label="Phase 3: Implement\n(design-exact, tests cover AC)"];
    p4       [label="Phase 4: Self-Check\n(typecheck + lint +\ntest:changed + review checklist)"];
    clean    [shape=diamond, label="0 BLOCKERs\nand 0 MAJORs?"];
    p5       [label="Phase 5: Report\n(AC → test traceability)"];
    p6       [shape=doublecircle, label="Phase 6: Handoff\nto review-code"];

    pre   -> abort [label="no"];
    pre   -> p1    [label="yes"];
    p1    -> p2;
    p2    -> scope;
    scope -> gap   [label="no"];
    scope -> p3    [label="yes"];
    p3    -> p4;
    p4    -> clean;
    clean -> p4    [label="no: fix + re-run"];
    clean -> p5    [label="yes"];
    p5    -> p6;
}

Tester focus for implement

The Tester role in implement writes boundary + contract tests:

• Contract tests — for every public API signature in impl-notes.md, verify the documented inputs/outputs, error paths, and side effects. Each acceptance criterion (node acceptance_criteria in {epic-slug}/dag; historically 04-plan-05-acceptance-criteria) MUST map to at least one test.
• Boundary tests — empty values, malformed input, permission boundaries, concurrency edges, and the edge cases the node spec's decision tables / state machines imply.
• Failure-path tests — every error scenario the node's cross-session edge contracts (historically the interface design, 03-design-04-interface-design) specify.

The Developer's Phase 4 self-check (bun run test:changed to green) covers the happy path and existing tests; the Tester's job is the cases the Developer is structurally biased to miss.

Preconditions

Publish target (tiered targeting retired, [org-internal #3072] phase 3): the Size/*-tiered publish rule (rules/workflow-routing.md §"Publish target by Size/* tier — RETIRED") was retired with the legacy producer skills. Artifacts publish where the live mode puts them: DAG task mode → node spec in the frozen {epic-slug}/dag copy (see the DAG-mode input path below); standalone bugfix → {slug}/bugfix-report + issue body per bugfix Phase 5. Legacy tiered locations ({slug}/02-03-req-design, {slug}/04-plan-*, …) stay readable for historical runs via _shared/gitea-read-patterns.md.

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

DAG-route read map (applies to Phase 1 read inputs and the Phase 3/4 artifact references below — mirror verify/SKILL.md's DAG branch): when DAG-routed, resolve each legacy tiered artifact reference (any mention below of {slug}/04-plan-* / {slug}/03-design-* pages) from the frozen DAG copy instead:

• Work item — {slug}/04-plan-04-iteration-assignment / issue body → the node spec in {epic-slug}/dag + the node ticket's issue body.
• Acceptance criteria — {slug}/04-plan-05-acceptance-criteria / issue body → the node acceptance_criteria in {epic-slug}/dag (+ {epic-slug}/dag-nodes/{node-id} subpages when AC detail is sunk) + the node ticket's issue body.
• test_id (測試用例 ID) declared in 04-plan-05-acceptance-criteria → the test_id declared on the node AC in {epic-slug}/dag.
• Design sections — {slug}/03-design-** / {slug}/02-03-req-design → the node spec + cross-session edge contracts in the frozen DAG copy (design detail is folded into node AC + contracts; there is no {slug}/03-design-* page).
• Interface design — 03-design-04-interface-design → the node's cross-session edge contracts in {epic-slug}/dag.
• Component mapping — {slug}/03-design-08-traceability → the node req_refs + component field in {epic-slug}/dag.

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

Before starting implementation, confirm:

Legacy pipeline preconditions retired ([org-internal #3072] phase 3, 2026-08-21): the tier-dependent requirements/design/plan artifact-existence checks and the design-space / iteration-plan review-convergence checks that used to head this list belonged to the archived legacy pipeline (<instance-root>/archive/). Live input modes: DAG task mode (node spec from the frozen {epic-slug}/dag copy — see the DAG-mode input path above; convergence precondition = octopus review status --stage review-dag shows success) and standalone modes (bugfix / refactor / port — the request itself is the spec). Historical req/design/plan pages stay readable via _shared/gitea-read-patterns.md.

• 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 is accessible and its DAG 路由变体 section has been confirmed item by item. Specifically: the frozen DAG copy exists and the single gate has converged; the node's cross-session upstream dependencies are at terminal state (ready). If any dependency is not complete → abort, listing the blocked nodes.

If any precondition is unmet, abort and inform the user. Refer to core/checklists/pipeline-gate.md for the complete gate checklist. List every missing artifact, every un-converged review, and every blocked dependency explicitly so the user knows exactly what upstream work remains before implementation can begin. Refer to the Recovery Protocol in core/checklists/pipeline-gate.md to determine the recovery action for each missing item.

Work-item selection

When the user requests implementation without specifying a work item, resolve the work-item list from the frozen DAG copy: the ready/pending task nodes in {epic-slug}/dag (via wiki 读写 API（见 TERMINOLOGY）), cross-checked against the node tickets on the Epic's ## DAG 状态 table. (Legacy tier-based resolution via {slug}/04-plan-04-iteration-assignment was archived 2026-08-21, [org-internal #3072] phase 3.) Present the current ready nodes for selection:

Current iteration: Iteration {N}: {Goal}
Available work items:
| Work Item | Description | Complexity | Status |
|-----------|-------------|------------|--------|
| WI-001 | ... | 3 | PENDING |
| WI-002 | ... | 2 | PENDING |

→ Which work item should be implemented?

---

Phase 1 — Parse Context

Pipeline stage: if the source issue exists, move it to the implement column on the Pipeline Stages board per _shared/gitea-write-patterns.md Pattern 7.5. Skip if no source issue exists.

Read the upstream artifacts to build a complete implementation context. Resolve inputs per the DAG-route read map (Preconditions above); standalone modes read the request/bug report instead:

1. Work item — the node spec in {epic-slug}/dag (+ the {epic-slug}/dag-nodes/{node-id} subpage when detail is sunk) and the node ticket's issue body:

   • Node id, title, complexity (size_attrs).
   • Requirements covered (req_refs).
   • Component(s) involved (node component field).

2. Acceptance criteria — the node acceptance_criteria in {epic-slug}/dag (+ sunk subpages) and the node ticket's issue body:

   • Every falsifiable AC (AC-{n}) and NFR: entry.
   • The declared 测试用例 ID (test_id) for each criterion — these drive the Red → Green test-first order in Phase 3 and are the handshake with verify (DOD-1.6).

3. Design context — the node spec + the node's cross-session edge contracts in the frozen DAG copy (design detail is folded into node AC + contracts; there is no separate design page). Historical {slug}/03-design-* pages from legacy runs stay readable.

4. Existing codebase — use glob and grep to locate:

   • Existing files in the component's directory.
   • Existing tests.
   • Existing type definitions, schemas, configuration files the work item touches.

Output: internal only. The Developer MUST have read every referenced design file before writing a single line of code.

---

Phase 2 — Plan Implementation

Before writing code, produce a brief implementation plan:

## Implementation Plan: {WI-ID}

**Work item**: {description}
**Files to create**:

- `path/to/new/file.ts` — {purpose}

**Files to modify**:

- `path/to/existing/file.ts` — {what changes, why}

**Design compliance**:

- Component: {COMP-XXX} from {design-file}
- Interface: {iface-name} from {design-file}
- Data entity: {entity-name} from {design-file}

**Acceptance criteria to satisfy**:

- [ ] {criterion 1}
- [ ] {criterion 2}

Rules:

• If the implementation plan reveals that the work item touches > 3 files, pause and ask: "This work item spans {N} files. Is the scope correct, or should it be split?" The Builder (or user) MUST split it into smaller work items each touching ≤ 3 files before proceeding.
• If the work item requires a file that doesn't map to any design component, flag a design gap and abort. Do NOT invent design decisions.

Present the plan to the user:

Implementation plan for {WI-ID}:
- {N} files to create, {M} files to modify
- {K} acceptance criteria

→ Proceed? (yes / no / revise)

---

Phase 3 — Implement

Write code following these rules:

Design Discipline

• Component interfaces, method signatures, and return types MUST match the design document exactly.
• Data model fields, types, and relationships MUST match the data design.
• API endpoints, request/response schemas, and status codes MUST match the interface design.
• If a design decision proves impossible in practice, stop and report the gap to the Builder. Do NOT silently deviate.

Code Quality

• Follow existing project conventions (read neighbor files first to understand patterns).
• Use existing libraries and utilities already in the codebase — do not introduce new dependencies without explicit justification.
• Keep functions small and single-purpose — but per rules/style-guide, do NOT preemptively extract single-use helpers; inline at the call site unless the helper is reused, hides a genuinely complex boundary, or has a clear independent name that improves the caller.
• Handle errors at the appropriate layer (matching the design's error handling strategy).
• Write self-documenting code; add comments only for genuinely non-obvious logic.
• Document all new/modified public APIs inline (JSDoc/TSDoc/pydoc/etc.) with parameter descriptions, return types, and thrown errors.
• If the project has an API documentation file (e.g. OpenAPI spec, API.md), update it to reflect the new endpoints, schemas, or behavior changes.

Test Discipline

• Test-first (Red → Green) for declared test_ids. For every acceptance criterion (node AC in {epic-slug}/dag, whose test_id mapping is declared inline; historically the 04-plan-05-acceptance-criteria table) that declares a test_id, write that test FIRST and confirm it fails for the intended reason (Red) before writing the implementation that satisfies it (Green). The test's file-path :: test-name MUST match the declared test_id exactly — this is the implement-side handshake with verify (DOD-1.6). A test_id marked MANUAL or BENCH:<script> is implemented per its method and is exempt from the Red step. If a test already passes against existing code (the behavior is already present), note it in the Phase 5 report rather than forcing an artificial failure.
• Write tests that verify the acceptance criteria.
• Tests must be independent (no shared mutable state).
• Test edge cases identified in the acceptance criteria.
• Test failure paths that the design specifies.

Incremental Commitments

• Implement in dependency order within the work item: shared types first, then data access, then business logic, then API handlers.
• After each coherent unit, run typecheck to catch errors early.

---

Common Rationalizations

Implementation fails far more often from pressure than from ignorance — the Developer knows the rules and rationalizes skipping them under context or time pressure. These are the excuses that precede every review blocker and silent defect. If you catch yourself thinking any row's "Excuse", stop: the "Reality" column is the exact rule you are about to break, and breaking it is what turns a one-pass implementation into a multi-round review.

Excuse	Reality (the rule being broken)
"Design says X, but Y is simpler/better"	Silent deviation is a hidden design gap. Phase 3 Design Discipline: stop and report to the Builder — never silently deviate.
"Small change, a test is overkill"	A one-line edit can break a contract. Every acceptance criterion maps to ≥1 test (Phase 4 Brownfield check). 30 seconds now vs. a review blocker later.
"I'll write tests after it works"	Tests-after verify what you built, not what was required — you test your own bias, not the spec.
"Typecheck passed, lint is cosmetic"	Lint is a Phase 4 gate, not optional polish. Failing lint is an automatic review blocker.
"Self-check passed, I'll trust it"	Rubber-stamping misses the MAJORs the formal review will catch. Rule: if YOU can find a MAJOR, fix it now — the first review should never discover what you could have.
"This neighbor looks buggy, I'll fix it too"	Scope creep. Log it as an observation in the report; do not fix unrelated code (Greenfield/Brownfield rule).
"Spans 5 files but it's one logical change"	The ≤3-files rule is structural, not aesthetic. Split the work item via the Builder (Phase 2 rule).
"Design is ambiguous here, I'll pick the obvious option"	Inventing a design decision is a Phase 2 abort condition. Flag the gap; do not guess.
"Already manually verified it works"	Manual ≠ systematic — no record, can't re-run, can't bisect. bun run test:changed is the evidence the report demands.
"Report is busywork, the diff speaks for itself"	No report → review-code cannot trace AC→test. Phase 5 is the handoff contract; skip it and the review stalls.
"X× improvement — assumed, no measurement"	Quick-measure before it becomes an AC. Unverified assumptions in ACs waste framing cost ([org-internal #1932]: YAML token density assumed 2-3×, measured 0.95 — hypothesis rejected by data).

---

Phase 4 — Self-Check

After writing all code, run the project's verification commands:

1. Typecheck: bun typecheck (or project-equivalent). Fix all type errors.
2. Lint: bun oxlint --deny-warnings (repo root — the review-code mechanical gate's canonical lint invocation; bun lint is the package-script alias). Fix all lint errors.
3. Tests: bun run test:changed (or project-equivalent). All affected tests must pass.
4. Post-deletion cleanup (mandatory when any code was removed): If files or code blocks were deleted (dead code, test cleanup, refactored-out modules), re-run bun oxlint --deny-warnings specifically to catch orphaned imports and unused variables — these are the most common post-deletion regressions. Re-run bun typecheck to catch orphaned type references to deleted modules.

Then self-check against core/checklists/implementation.md:

• Verify every checklist item marked PRE (pre-implementation) was satisfied before coding.
• Verify every checklist item marked POST (post-implementation) is satisfied now.
• For any failed checklist item, fix the code before reporting.

Brownfield Self-Check (additional)

For brownfield work items, additionally:

1. Design spec cross-check: Re-read the node's cross-session edge contracts in the frozen DAG copy (historically the design's interface design section, 03-design-04-interface-design). Verify every interface promise — method signatures, return types, output formats, error messages, config field names, param descriptions — is satisfied exactly as specified. Schema annotations MUST match actual code behavior.
2. Test coverage: For each new function, method, or exported API added, confirm at least one test exercises it. If bun run test:changed reports zero new tests, add them before handoff.

Review Readiness Self-Check (mandatory before handoff)

Before submitting to code review, the Developer MUST self-attest against the code review checklist. This reduces round-trips by catching common defects before the first review submission. The self-check must achieve 0 BLOCKERs and 0 MAJORs before handoff — if the Developer can find a MAJOR issue during self-check, the formal reviewers will find it too.

1. Run the code review checklist: Read core/checklists/code-review.md and self-attest that the code likely passes, for each of its 10 dimensions (COR, DGN, SEC, PERF, TST, STY, DBT, A11Y, DOC, TRC — the authoritative dimension set lives in the checklist's section headers and review-code/reference/code-review-dimensions.md; do NOT hand-maintain a copy here).
2. Record the self-attestation in the Phase 5 report under "Review Readiness" as a pass/fail per dimension. Any FAIL dimension MUST be fixed before handoff.
3. Hard gate: self-check MUST find 0 BLOCKERs and 0 MAJORs. If the Developer finds even one MAJOR, fix it and re-run self-check before handoff. The first formal code review should never discover issues the Developer could have caught themselves.

---

Phase 4.5 — Iteration Completion Commit

After ALL work items in the current iteration have been implemented and passed Self-Check (Phase 4), create a git commit BEFORE proceeding to the next iteration. This preserves per-iteration traceability and enables git bisect per iteration.

Commit Rules

1. Commit after the last WI of the iteration is done and self-checked.
2. Commit message format: [{chunk-id}][{iteration}] {summary}.
   • Example: [chunk-resolution][iter-1] feat: add two-pass chain resolution engine
3. Commit body is REQUIRED for non-trivial commits (any commit touching > 1 file or > 20 LOC). The body MUST contain:
   • What: a 1-3 line summary of the changes (files + purpose), including the work item ID (WI-{NNN}) the commit delivers — code-review TRC 10.1 requires the commit/PR description to carry the work item ID.
   • Why: the design/requirement motivation (cite REQ-ID or ADR if applicable).
   • Evidence: test names or verification commands run (e.g. 90 compaction tests pass).
   • Subject-only commits are acceptable only for single-line fixes or doc tweaks.
4. Include all source + test files from the iteration.
5. After commit, proceed to Phase 4.6 (Issue Checklist Sync), then Phase 5 (Report) for the iteration, then start the next iteration's WIs.

Multi-Iteration Workflow

Iteration 1 WIs → Self-Check → Commit [iter-1] → Checklist Sync → Code Review →
Iteration 2 WIs → Self-Check → Commit [iter-2] → Checklist Sync → Code Review → Merge

---

Phase 4.6 — Issue Checklist Sync (progressive)

After committing the iteration, sync the source issue's checklist so stakeholders see progress in real time. This is mandated by the issue-checklist-sync L1 rule — follow its "How to sync (each point)" procedure (identify source issue → fetch body → map → update, preserving non-checklist content); this phase adds only the implement-specific annotation:

• Stage-specific row: for each - [ ] item the iteration's work satisfies, mark - [x] and append _(commit {sha}: file/component)_ or _(PR #NNN: file)_.
• Do NOT touch items outside this iteration's scope — they will be caught at a later sync point (next iteration, DAG-freeze aggregation sync, or verify Phase 5.6). Only check off what this iteration actually delivered.

This is a progressive sync: the checklist fills in incrementally as iterations complete, giving stakeholders a live view of progress without waiting for the final verify gate.

Phase 4.7 — PR-Creation Sync

The session pushes its branch and reports status=done branch=<ref> verify=… risk=…; the orchestrator admits the PR (serially, one open at a time) — workers never open PRs (TD-678/[org-internal #4425]; uncoordinated self-open only when the orchestrator is unreachable). Once that PR exists, update the source issue so stakeholders see the mergeable state without waiting for code review. Mandated by the issue-checklist-sync L1 rule; skip if no source issue exists.

PR shape per mode: default = one 1:1 PR per task (body carries the worker report); batch-mode epics ([org-internal #3731], per-epic opt-in) = the orchestrator composes ONE batch PR per iteration via the land-batch skill. This phase then runs per member issue as usual (N times), each pointing at its PR (batch: the single batch PR); the poller writes the PR/CI/review rows against every member issue (multi-close-ref fan-out).

1. Re-fetch the issue body via 工单 API（见 TERMINOLOGY）get.
2. Ensure the ## 当前状态 live-status section exists (create it if absent — MANDATORY for incident / standalone-bugfix flows; for quiet pipeline flows, create it only if it already exists, otherwise skip). The PR row itself is written by the status-sync poller (.gitea/scripts/status-sync-poll.ts), NOT this skill — do NOT manually 工单 API（见 TERMINOLOGY）update the PR / 代码评审 / CI rows (per issue-checklist-sync.md § Automated sync).
3. If this is an Epic task list, append the PR reference to the row that this iteration's work corresponds to.
4. Preserve all non-checklist content.
5. Never hand-sync main into the PR branch. Keeping the PR mergeable is the keep-mergeable workflow's job: once review converges the orchestrator labels the PR ready-to-merge and the server-side keep-mergeable cron (.gitea/scripts/keep-mergeable.ts, driven by script/keep-mergeable-cron.sh under a systemd timer) fetches the PR head, probes merge-tree --write-tree, and pushes a non-force commit-tree merge into the head branch (the retired POST /pulls/{n}/update-branch API path returned 405 on this instance — see AGENTS.md "PR keep-mergeable"). Hand-written chore: merge origin/main (keep PR mergeable) commits are retired — each one re-triggered the full CI surface for near-zero re-tested risk.

Kanban column lifecycle: automated (POST <gitea-base-url>/api/v1/repos/{owner}/{repo}/issues → Backlog, POST .../pulls → Review; no manual moves). Single shared reference: _shared/gitea-write-patterns.md Pattern 7.5; column semantics: wiki kanban-lifecycle.

---

Phase 5 — Report

Produce an implementation report:

## Implementation Report: {WI-ID}

**Work item**: {description}
**Iteration**: {iteration number}: {goal}

### Files Changed

| File               | Action   | Purpose        |
| ------------------ | -------- | -------------- |
| `path/to/file.ts`  | created  | {purpose}      |
| `path/to/other.ts` | modified | {what changed} |

### Acceptance Criteria

| Criterion     | Status | Evidence                           |
| ------------- | ------ | ---------------------------------- |
| {criterion 1} | ✅     | {test name or manual verification} |
| {criterion 2} | ✅     | {test name or manual verification} |

### Verification Results

- Typecheck: {pass / fail + error count}
- Lint: {pass / fail + warning count}
- Tests: {N} passed, {M} failed, {K} skipped

### Design Deviations

{list any intentional deviations from design with rationale, or "None"}

### Open Items

{anything incomplete with reason, or "None"}

---

**Handoff**: Ready for `core/skills/review-code/SKILL.md`

Persist before returning ([org-internal #2847]): the Developer MUST write the final report above to disk as its LAST action, BEFORE returning it — <runs-root>/{slug}/workers/{chunk-id}-worker-{seq}.md when the Tier 1 run workspace exists, else /tmp/octopus/{chunk-id}-worker-{seq}.md ({chunk-id}/{seq} come from the dispatch prompt — see ../_shared/worker-report-persistence.md). The persisted copy is the report of record; the task notification is a convenience copy. The same step applies to EVERY mode's report phase (bugfix Phase 5, refactor Phase 6, port report) — no worker return may exist only in the task notification.

---

Phase 6 — Handoff to Code Review

Present the report to the user and signal readiness for review:

Implementation of {WI-ID} complete.
- {N} files changed ({C} created, {M} modified)
- {T} tests passing
- All acceptance criteria satisfied
- Typecheck + lint clean

→ Run code review? (yes / no)

Do NOT mark the work item as complete until code review passes.

To notify workflow completion, call the signal_stage_done tool.

Legacy notes

Publish target (tiered targeting retired, [org-internal #3072] phase 3): the Size/*-tiered publish rule (rules/workflow-routing.md §"Publish target by Size/* tier — RETIRED") was retired with the legacy producer skills. Artifacts publish where the live mode puts them: DAG task mode → node spec in the frozen {epic-slug}/dag copy (see the DAG-mode input path above); standalone bugfix → {slug}/bugfix-report + issue body per bugfix Phase 5. Legacy tiered locations ({slug}/02-03-req-design, {slug}/04-plan-*, …) stay readable for historical runs via _shared/gitea-read-patterns.md.