sdlc/skills/implement/SKILL.md

---
name: implement
description: SDLC implementation stage. Gate on capability tags enforced in code by sdlc-gate (implement requires coding), confirm the target branch before writing any file, then claim a ready work package from ANALYZE_CONTENTS with a work ticket, create a worktree from the analysis page's source branch under .worktree/{分析頁 HASH}/{repo}, and complete its TDD todos one by one inside it, updating the wiki after every item. A delivery package confirms its content type (API document or user-defined) before its first todo. Ends with jsc-review code-review, opens the PR and only then removes the worktree, asks which delivery-document format to produce (DELIVER_{HASH} wiki page or Gitea issue comment), and optionally registers the project in MAINTAIN_CONTENTS. Use when analysis is done and code must be written; not for planning or analysis.
---

# implement

Goal: complete the analysis page's todos one by one; **update the wiki status immediately after every completed item**.
All wiki reads and writes go through `jsc-gitea:wiki`.

## Steps

1. **Model gate and stage lock** (capability tags, enforced in code — never self-assessed):
   1. Run `jsc-cli/tools/model-tags.sh sync` to refresh `$JSC_HOME/model-tags.tsv` from `jsc-cli/references/model-tags.md`.
   2. Run `jsc-hooks/hooks/sdlc-gate.sh lock implement`. The script reads the **actual** model id from the transcript, compares it against this stage's required tags (`coding`), and locks the stage only when they match.
   3. **Never claim a capability tag you have not verified with that script**, and never substitute your own judgement for its verdict. Non-zero exit = blocked: relay the script's message verbatim, stop the skill, do nothing else this turn. Do not run `unlock` to get past the gate; only the user may decide that.
   4. Exit 0 means the stage is locked. From now until the next stage's gate runs, the sdlc-gate hook blocks every prompt whose model stops satisfying the tags.
2. **Confirm the target branch** — do this **before writing any file**:
   1. Report the current branch, whether the working tree is clean, and which of `origin/develop` / `origin/master` exist, plus the remote default branch resolved per `references/branch.md`.
   2. Ask per `jsc-ask:ask` rules which branch this work merges into; state the impact scope on every option (the answer decides the PR target and, when it collides with the current branch, forces a new working branch).
   3. Uncommitted changes in the working tree → warn first and let the user commit or back them up; never discard them.
   4. Apply `references/branch.md` to the confirmed target: source branch and target branch sharing a name means creating a new working branch instead of committing on the target; report the resulting branch name.
   5. Record the confirmed target branch on the analysis page next to the work ticket, and reuse it as the PR target in `jsc-git:pr`. Completion condition: the user has confirmed the target branch explicitly; never fall back to `develop` silently.
3. **Generate a work ticket**: format `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}`. `{HASH}` = the shared wiki hash for `{owner}/{repo}`, computed by `jsc-gitea/tools/hash-id` (see `jsc-gitea:wiki`). Try to rename the current session to the ticket name (skip when the CLI does not support it).
4. Read `ANALYZE_CONTENTS` via `jsc-gitea:wiki` and list what is unfinished: plan name, HASH, work package number, count of open items. A selectable work package must satisfy all three: **unfinished, dependency-free (or all dependencies done), and not holding a work ticket**.
5. Let the user pick a work package per `jsc-ask:ask` rules (options state open-item count and estimated effort). **List delivery packages (交付 `是`) first** — the analysis page makes `WP-01` the standalone delivery package, so keep that order in the options. Write the ticket into that work package's ticket column (the zh-TW field 「工作證」) on the analysis page and save it back to the wiki. **Only after the ticket is saved successfully may you proceed.**
6. **When the package taken is a delivery/handover package, confirm its content before doing any of its todos**:
   1. Ask per `jsc-ask:ask` rules what this delivery must contain. The default options are fixed: **1. API 文件** (endpoint path, **every** input parameter, **every** output parameter) and **2. 由使用者輸入** (the user states the content themselves). State the impact scope on each. **Never assume the type, and never skip this — the answer decides what the whole package produces.**
   2. Chose API 文件 → follow `references/deliver-formats.md`: all parameters listed (not just the main ones), each with name, type, required flag, example, data source and new-versus-existing status; sample values take real sources first and are labelled `真實：{來源}` or `推論：無來源`; **an existing endpoint must mark new versus old parameters both ways** — the status column (🆕 新增 / ⚠️ 變更 / ❌ 移除 / blank for untouched) and a `diff` code block for colour. HTML `style` attributes get filtered by the wiki, so never rely on them.
   3. Chose 由使用者輸入 → produce exactly what the user described; do not force the API document layout onto it.
   4. Record the confirmed type in the analysis page's 交付型別 column and save it before starting the todos.
7. **Create the worktree — before touching any code**. Full rules in `references/branch.md`:
   1. Read the **source branch** and the repositories involved from the analysis page. Every code change happens inside the worktree; the main working directory's branch and working tree stay untouched.
   2. Path: `{工作目錄}/.worktree/{分析頁 HASH}/{repo}` — the HASH without the `ANALYZE_` prefix, the repo name without its owner. One worktree per repository, all under the same HASH directory.
   3. **Ask per `jsc-ask:ask` rules how to handle the branch**, with the two fixed options: create a new working branch off the source branch (`git worktree add -b {工作分支} {路徑} {來源分支}`), or check the source branch out directly (`git worktree add {路徑} {來源分支}`). State the impact scope on each. **Never assume, never skip the question.**
   4. **Quote every branch name and path**: source branches carry Chinese characters, spaces and multiple slashes (for example `feat/一址通/查地址/完整版/P2`), and an unquoted argument gets split.
   5. No local clone of that repository → stop and ask the user for its path; never clone on your own initiative and never guess the location.
   6. Add `.worktree/` to that repository's `.git/info/exclude` — never edit the user's shared `.gitignore`.
   7. Report the worktree path, the checked-out branch and the source branch. Completion condition: every involved repository has a worktree and you have reported all of them.
8. List every open item of the work package and implement them **one at a time**, **inside the worktree**:
   - Follow the TDD loop: red before green, one slice at a time; rules and anti-patterns in `references/tdd.md` (refactoring belongs to the review stage).
   - After each item, flip its `[ ]` to `[x]` on the analysis page and save to the wiki before starting the next item.
9. When all items are done, call `jsc-review:code-review` and wait for the review; on failure, fix and re-review until it passes.
10. **Open the PR, then remove the worktree** — in that order, never the reverse:
   1. Call `jsc-git:pr` with the target branch confirmed in step 2. Commits come from inside the worktree.
   2. **Only after `jsc-git:pr` reports the PR was created successfully**, run `git worktree remove {路徑}` for each worktree, then `git worktree prune`. PR creation failed → keep the worktree so the user can take over.
   3. Uncommitted changes still inside a worktree → **do not remove it**; report and stop. Those changes never reached the PR, and removing would throw them away.
   4. Once every worktree of this analysis is gone and `.worktree/{HASH}/` is empty, delete that directory too.
11. **Delivery document** — a finished work package is a delivery, so **always ask before producing it; never pick a format silently and never skip this step**:
   1. Ask per `jsc-ask:ask` rules which format to produce. The options are fixed: **a `DELIVER_{HASH}` wiki page** or **a Gitea issue comment**. State the impact scope on each (the wiki page lives beside the plan and analysis pages; the issue comment reaches whoever follows that issue).
   2. Both formats use the same structure — `templates/deliver-page.md`, in Traditional Chinese. Only the destination differs.
   3. Wiki page: write `DELIVER_{HASH}` through `jsc-gitea:wiki`, where `{HASH}` comes from `jsc-gitea/tools/hash-id` over `{owner}/{repo}` plus the work package number (for example `plugins/sdlc#WP-01`), so each work package gets its own page instead of overwriting the previous one. A new page is added to `DELIVER_CONTENTS` per `templates/deliver-contents.md`.
   4. Issue comment: confirm the issue number with the user (propose the one referenced by the work package or the PR; never guess), then post via `gitea/tools/gitea.sh api POST /repos/{owner}/{repo}/issues/{n}/comments` with the body passed in as a UTF-8 file — real newlines, never a literal `\n`.
   5. Sample values follow the analysis page's 資料來源 column: `真實：{來源}` for real sources, `推論：無來源` for reasoned ones. Personal data never goes in — keep the field and format, drop the value.
   6. Completion condition: the chosen format has actually been produced, and you have reported where it landed (wiki page name, or the comment URL).
12. Ask per `jsc-ask:ask` rules whether to register this project for maintenance: append to `MAINTAIN_CONTENTS` with `templates/maintain-contents.md`. Required: repository `{owner}/{repo}`, maintenance method, start date. Optional: end date (NULL = maintain forever), last-maintained time.

## Rules

- The work ticket is a mutex: always skip work packages that already hold a ticket; never take one over.
- Never batch wiki updates across items; one item, one update.
- Sample data written into code or fixtures follows the analysis page's 資料來源 column: real data where a source exists, reasoned values labelled as inferred where none does. Never invent a value and present it as real, and never copy personal data into fixtures — keep the format, drop the identity.
- Everything the skill writes out (wiki content, commit messages, PR descriptions) stays Traditional Chinese per the STE100 rule.