# Linear Implement > Execute a ready Linear implementation plan: make code changes, verify them, ask for the final code destination, and post marked implementation status comments. Use when a Linear issue already has a ready plan and needs implementation. - Skill: `lkshrk/linear-implement` (Agent Skill, multi-file: 17 files) - Install (CLI): `npx skillmds@latest add lkshrk/linear-implement` - Raw SKILL.md: https://api.skillmd.com/api/skills/lkshrk/linear-implement/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: lkshrk (https://skillmd.com/u/lkshrk) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lkshrk/linear-implement --- # Linear Implement Use the repository root as the workflow source. Read and follow: - `agents/implementer.md` - `docs/implementer.md` - `docs/agent-required-passes.md` - `docs/superpowers-linear-persistence.md` - `templates/linear-status-comment.md` - `templates/linear-dashboard-comment.md` - `schemas/linear-ai.status.v1.schema.yaml` - `schemas/linear-ai.dashboard.v1.schema.yaml` Start from the newest valid marked plan comment. Do not invent missing product behavior. If blocked, post batched questions in a marked status comment and apply or emit the correct Linear mutations. ## Claim Lock Follow the Claim Lock Rule in `docs/workflow.md`. On start, re-read the issue; if it already carries `in-use` and this run is not resuming its own claim, stop and report the issue as claimed without changing it. Otherwise add the `in-use` label when claiming the issue (alongside applying `llm-active`). Remove `in-use` when this run stops working the issue: on review-ready handoff, blocked, abandoned, or failure. `in-use` is outside the `llm-*` namespace, so bulk `llm-*` strips do not remove it; release it explicitly. When claiming, also write the `linear-ai:claim` block to the issue description (`templates/linear-claim-block.md`) with `claimed_by: linear-implement` and an ISO 8601 `claimed_at`. When releasing, remove the claim block so the description stays consistent with the label. ## Pre-Implementation Gate Before changing any code, run this gate once the issue is claimed: 1. Re-confirm no open questions remain. Re-read the newest ready plan, its `open_questions`, `accepted_unknowns`, and `do_not_assume`, plus the relevant code. If any material question is unanswered and not explicitly accepted, or you discover new ambiguity while reading the code, stop and block with `llm-blocked` and batched questions instead of guessing or starting. Do not begin implementation with an open material question. 2. When there are no open questions, decompose the ready plan into independent parallel lanes - split by repository, module, checklist item, test surface, or verification lane so that lanes touching disjoint files can run at the same time. Hand each lane to its own subagent in an isolated worktree per the Parallel Execution rules, and reserve sequential work only for lanes that must share mutable files. ## Auto Mode Run implementation in auto mode once a valid ready plan exists. Continue through safe, reversible local inspect/edit/test/verify steps without asking for permission again. This includes reading repo context, creating the repo-local TDD plan, editing files named or implied by the ready plan, updating tests, running focused validation, updating the Linear dashboard/status evidence, and iterating on failed checks. Ask or block only when the next step is destructive, irreversible, credential-gated, external-production affecting, materially scope-changing, missing required authority, or genuinely ambiguous in a way that would create nontrivial rework. Batch blocker questions in a marked status comment instead of interrupting for routine implementation choices. ## Required Permission Context Before starting direct implementation, verify the required implementer permission context is active. The session must have workspace write access for the target repository, permission to run the repository package manager and verification commands, Linear MCP read/write tools for dashboard/status mutations, Git/GitHub tools when branch or PR work is in scope, and any project MCP tools required by the ready plan. Do not begin routine implementation in a prompt-by-prompt permission mode. Establish or inherit the required implementer permission context first so approved safe, reversible work can proceed without repeated confirmations. If that context cannot be established, narrow the work to safe read-only inspection or post/emit a blocked status with the missing authority instead of repeatedly asking during routine steps. No implementation or code changes before the Superpowers task list is mirrored into the Linear issue description dashboard or `REQUIRED_LINEAR_MUTATIONS` is emitted. Maintain one dashboard block in the issue description with schema `linear-ai.dashboard.v1`. Mirror the Superpowers task list into that dashboard with CLI-style state symbols, stable ready-plan task IDs, and `last_checked` repair evidence after each top-level task state change. Inspect the actual code/worktree state before marking a task done. Use a dashboard comment only as fallback when description writes are unavailable. ## Parallel Execution Use subagents heavily for independent implementation work. Split the ready plan into parallel lanes by repository, module, checklist item, test surface, review lane, or verification lane when those lanes do not require the same mutable files. Implementation always happens in an isolated issue worktree at `/.worktrees/-` unless you can prove it is already inside the correct issue worktree. Never implement directly on branches as the working tree, and never implement directly on `main` or `master`. Treat the branch name or Git ref from the ready plan or Linear issue as Git plumbing attached to the issue worktree, not as the primary workspace. Prefer git worktree isolation for parallel code-changing subagents. Each code-changing lane should have its own temporary lane worktree or Git ref, run its own focused verification, and report changed files, tests run, remaining risks, and dashboard task IDs. Do not place multiple code-changing subagents in the same working tree. Before dispatching subagents, verify they have the right tools and permissions for the lane: repo read/write access, package manager, test commands, Linear MCP read/write tools if needed, Git/GitHub tools when PR work is in scope, and any required project MCP tools. If those tools and permissions are not available, either narrow the lane to read-only work or run it in the main session. Merge back subagent work only after reviewing the diff, resolving conflicts, updating the dashboard task list, and rerunning relevant verification in the issue worktree. Clean up temporary lane worktrees after merge-back and verification. Keep temporary lane worktrees distinct from the persistent issue worktree. If any temporary lane worktree is intentionally kept, report its path, branch, owner, and reason in the status comment. ## Implementation Review Loop When implementation looks complete and local verification passes, run the Mandatory Implementation Review Loop from `docs/agent-required-passes.md` before the destination question and before applying `llm-review`. Dispatch independent parallel review subagents — always general review, refactor/code-smell, bug hunter, security, and spec/scope verifier, plus any specialized language/area reviewer the runtime provides — then fix or justify every finding, document each justification in the marked status comment, and repeat rounds until convergence. The loop has a maximum of five review rounds unless the issue explicitly sets a different cap. After each review round, post or emit a round summary with the round number, reviewers/lenses run, findings by severity, fixed findings, justified findings, deferred or blocked findings, verification rerun, and whether the loop continues, converged, or blocked at the cap. If the cap is reached without convergence, post a blocked status. Then pass the confidence and test-gap self-gates. Implementation is not done until the loop converges and both self-gates pass. ## Commit and Destination Policy After implementation and verification are complete, use the default integration path unless the issue itself contains an explicit requirement or rule for a different handoff: rebase the issue worktree onto the local main branch, squash to the minimal number of squashed commits that preserves reviewable behavior and rollback boundaries, and integrate into the local main branch. A ticket is completed only when the code is in the main branch. An open PR is not sufficient for ticket completion. Feature branches and PRs are review handoff states unless the issue explicitly requires them as the terminal path. Before pushing, merging, opening a PR, marking a PR ready, applying `llm-review`, or posting a review-ready handoff, confirm the destination: - integrate to the default branch (`main` or `master`) for completion - create or update a feature branch without a PR only when the issue explicitly requires that handoff - create or update a feature branch with a PR only when the issue explicitly requires that handoff or human review before main integration Record the answer in `final_destination` as `main`, `master`, `feature_branch`, or `feature_branch_pr`. If the answer is missing, ambiguous, or still `undecided`, stop with `llm-blocked` or emit `REQUIRED_LINEAR_MUTATIONS`; do not infer from the plan, branch name, existing issue worktree, or existing draft PR. Leave the minimal number of squashed commits: split only by reviewable behavior or risk boundary, not by every tiny edit and not as one unrelated bulk commit. Use semver syntax through Conventional Commit style and include the Linear issue ID in every commit subject, for example: ```text feat(HCL-123): add dashboard persistence fix(HCL-123): repair status extraction test(HCL-123): cover dashboard validation ``` ### Linear Magic Word Linking Link the work to the Linear issue with a closing magic word plus the issue ID so Linear auto-links and advances status (In Progress on push/open, Done when the change reaches the default branch): - Feature-branch-with-PR destination: put a closing magic word and the issue ID in the PR description, for example `Fixes HCL-123` (multiple issues: `Fixes HCL-123, HCL-124`). Magic words only work in the PR title or description, not in a PR comment. - Direct-to-main destinations (`main`/`master`): add a `Fixes HCL-123` line to the commit message body in addition to the Conventional Commit subject above. Feature branch without PR is a handoff exception only when the issue explicitly requires it. - Closing magic words: `close/closes/closed/closing`, `fix/fixes/fixed/fixing`, `resolve/resolves/resolved/resolving`, `complete/completes/completed/completing`, `implements/implemented/implementing`. Prefer `Fixes`. The Conventional Commit subject keeps the `(HCL-123)` scope for readability and commit-evidence closeout; the magic word drives the Linear automation. - Because a closing magic word moves the issue to Done on merge, `linear-close` runs as verify-and-finalize: it tolerates an already-Done issue and still verifies evidence, updates the dashboard, posts the closeout comment, and strips `llm-*` and `in-use`. Report the final commit list and chosen destination in the status comment. Before review-ready handoff, confirm the final destination was explicitly chosen, temporary lane worktrees were cleaned up, and the issue worktree cleanup state is explicitly listed as cleaned or intentionally kept. ## Linear MCP Contract Use these Linear MCP tools when available: - `get_issue` - read the current issue, labels, status, and branch metadata. - `list_comments` - find the newest marked plan and status comments before acting. - `save_comment` - post marked implementation status, questions, blockers, and review-ready evidence. - `save_issue` - apply `llm-active`, `llm-blocked`, or `llm-review`, remove other `llm-*` labels, add the `in-use` claim on start and remove it on stop, update issue description dashboard, and update status when writes are available. When the issue is a sub-issue, apply the Parent and Sub-Issue Rule from `docs/workflow.md` in the same finalization pass: on `llm-active` move the parent to `llm-active` and In Progress; on `llm-blocked` roll the parent state up per the rule. Never take an `in-use` claim on the parent. Validate status comments and the issue description dashboard with: ```sh scripts/validate_marked_comments.ts --description ``` Before applying `llm-review` or claiming review-ready, run the hard handoff gate: ```sh scripts/verify_handoff.ts --issue-id --status --description ``` If a Linear metadata snapshot is available, validate labels with: ```sh scripts/validate_marked_comments.ts --metadata ``` Use the local JavaScript package manager or runtime available to the agent: Bun can run the `.ts` scripts directly; Node/npm/pnpm/yarn environments should run them through a TypeScript runner such as `tsx`. If Linear MCP write tools are unavailable, do not claim labels, status, or comments were updated. Emit `REQUIRED_LINEAR_MUTATIONS` with the exact marked status comment and label/status changes. ## Step Completion Handoff When implementation completes a task, blocker update, verification pass, or review-ready status, report what changed, verification evidence, current Linear labels/status, PR or patch links when present, and the recommended next step. Ask if there is anything else to add for blocker, abandoned, or review-ready handoffs, or when no safe unambiguous task remains. Do not ask whether to continue after routine completed tasks; continue to the next unchecked task, verification, or review handoff while work remains and the next step is safe and unambiguous. After the add-more question is answered "no" at a blocker, abandoned, or review-ready handoff, ask whether the user wants to continue with the recommended next skill. Name the recommended next skill explicitly and wait for user confirmation; do not auto-run it. Use this response shape: - Current phase - What changed - Evidence - Missing evidence - Open blocker - Recommended next step - Recommended next skill - Question: Is there anything else to add before moving on? - Question: Do you want to continue with the recommended next skill? Stop when implementation is verified, PR links are present when applicable, and the issue has a marked status comment with `implementation_status` set to `review_ready`, `blocked`, `active`, or `abandoned`.