vibe-implement

Task Implementation

Implement work specified by the user in a spec or ticket. /vibe-implement execute <plan> is a supervisory entrypoint that delegates an agreed execution plan to a separate executor and reviews the result.

Invocation Boundary

Identify the input and caller role before applying other sections.

• For execute <plan> or a request to execute a plan with Kind: execution-plan / Kind: design-spike, read all of EXECUTE.md and follow supervision. Plan-only input must not become ordinary direct invocation even when the word execute is absent.
• A dispatched atomic executor given the full plan and a workspace assignment by the supervisor must not become a supervisor or redelegate execution. Reuse the same implementation core (TDD, verification, read-only review), subject to the authority, status, and return contract in EXECUTE.md.
• Ordinary spec/ticket invocations and existing vibe-goal workspace assignments retain the contract below. Do not convert existing specs, tickets, or decision maps into execution plans arbitrarily. Return insufficient execute input to /vibe-plan instead of falling back to ordinary direct invocation.

The small-change/non-Git in-place exceptions, ordinary completion disposition, tracker updates, publishing, and cleanup below do not apply to supervision or its executor. Supervisors never implement directly and may record only execution status and evidence in the plan/index. Executors do not update the plan/index either. vibe-plan's EXECUTION-PLAN.md owns execution-plan authoring, review, reconcile, and --issues.

Planning Boundary

This skill never performs planning-family activities. It does not perform triage, exploration, spec drafting/editing, decomposition, ticket creation/splitting, ticket publishing, or plan modification. Implementation begins only from an already-agreed spec/ticket or an execution plan validated by supervision. Supervisory execution-status recording is distinct from changing plan content.

If input requires planning, or if the plan is incorrect or the spec is insufficient, stop implementation and return work to the caller or /vibe-plan//vibe-deep-plan. Do not fix or alter plans inside this skill.

Completion Ownership

vibe-implement has one atomic single-task implementation core, not copies per mode. The supervisory entrypoint is a boundary that delegates this core to a separate executor, not a second implementation mode. If the caller (e.g. vibe-goal) supplies an assignment record (task unit ID, original target/ref, fixed point, branch, worktree path, owner/status) via ledger/handoff, reuse that workspace; otherwise create a single workspace according to Workspace Isolation below. Implementation → review → finding fixes → resumption for the same logical task reuses that exact single workspace without adding a second one. Do not infer state from current worktree path (.agents/worktrees/*) or branch name (vibe/*) alone. This skill does not own a caller-supplied mode branch.

Before touching anything, locate existing workspace records for the same logical task. Implementation, review, review-fix, and resuming prior runs are all the same task. Workspace records bind the task unit ID to original target/ref, fixed point, branch, worktree path, and current owner/status. This resides in the externally supplied assignment record or the run's own prior return record. If exactly one matching record exists with no other active owner, reuse as-is. Continue all work in the existing worktree; if the worktree was removed, reattach to the preserved branch (do not create a newly numbered branch), preserve the original fixed point (do not recompute from current HEAD), and create no new branch or worktree. If records are missing, multiple candidates exist, other active owners exist, or unexpected head/unsafe dirty states occur, stop and report. Do not guess by branch name, number, slug, or latest vibe/*, and do not create new siblings. Only for new logical tasks with no matching record do you capture the current commit (git rev-parse HEAD) as the fixed point for review, create a single workspace according to Workspace Isolation below, and record it in return results.

Workspace Isolation

Before classifying change size, apply the record lookup from Completion Ownership first. If matched to an existing workspace record for the same logical task, continue all implementation, testing, review-fixes, and resumption in that exact workspace (existing worktree or reattached to preserved branch) regardless of change size (including one-line review fixes or resumptions) and skip to Linearity Rules below. Never send such continuations to the original checkout. If an externally supplied assignment record exists, use only the workspace identified by that record and never use integration branches. Never add a second workspace for retries of the same logical task. Missing or ambiguous externally supplied records are stop-and-report conditions, not permissions to create new workspaces. If no matching record exists for a new logical task, classify the requested change. Single-file changes or other trivial edits fall below the isolation threshold and proceed in-place without creating a dedicated worktree. For larger changes with no matching record, if the project uses git with at least one commit (git rev-parse HEAD succeeds), isolate work in a dedicated worktree instead of editing the original checkout:

1. Name the branch vibe/{number}-{function}. {number} is the next sequential integer among existing vibe/* branches (starting from 1), and {function} is a short kebab-case slug for the feature (e.g. vibe/3-user-auth).
2. Create: git worktree add .agents/worktrees/{number}-{function} -b vibe/{number}-{function} (branched at fixed point). Ensure .agents/worktrees/ is git-ignored.
3. Perform all implementation, testing, and review within that worktree.

Maintain the work branch as the implementation source without modifying the original branch. The same logical task (initial implementation, review-fixes, all resumptions) reuses the single workspace identified by records without creating a second branch or worktree. Continuing runs do not create new vibe/{next-number}-* branches for the same task. Execution creates at most one branch and at most one worktree, maintaining linear history on that branch. Never merge original branch, integration branch, or target into the work branch. If the base moves, rebase the work branch onto it when no externally supplied record exists; when an externally supplied record exists, report the moved base to the caller instead of merging or rebasing directly. Workspaces supplied externally run only on supplied work branches and worktrees. Do not create extra branches or worktrees, modify original target checkouts, publish or merge work branches, or clean, delete, or alter externally supplied worktrees after return. After reviewed work is committed, follow Completion Disposition below. Do not merge automatically. Record workspace details (task unit ID, original target/ref, fixed point, branch, worktree path, owner/status) in completion returns so subsequent review-fixes or resumptions for the same logical task reuse it precisely instead of creating new workspaces.

If the repository has no commits yet (or project is not a git repo), skip isolation and work in-place.

Implement test-first at pre-agreed boundaries. Follow TDD.md: red → green loops, boundary rules, anti-patterns to avoid.

Reference documents to read as needed:

• TDD.md — Red → green loop and rules
• tests.md — What good tests look like, with examples
• mocking.md — When to mock, what to mock instead
• MERGE-CONFLICTS.md — Resolving in-progress merge or rebase conflicts

Run type checks regularly, individual test files regularly, and full test suites once at the end.

Commit Signing

Because commits in this workflow are authored by an AI and not a human, they must not be signed as though made by a human. Never pass -S, --gpg-sign, or --signoff to git commit. If repository or global configuration enables signing by default (commit.gpgsign = true), override per commit with git -c commit.gpgsign=false commit ... so results are honestly unsigned. This applies to every commit created by this workflow, including checkbox flip edits bundled into implementation commits.

Completion Disposition

1. Follow Configuration Documents and Defaults: read docs/agents/issue-tracker.md when present; otherwise, absent another explicit choice, use the bundled local Markdown rules. Do not require initialization or create configuration files.
2. On the work branch, run /vibe-review against the fixed point recorded at startup, passing implemented spec or tickets so each enabled review axis has its required source. Follow /vibe-review's risk-request and high-risk-change rules for enabling Risk; this skill defines no separate condition. Do not ask the user for fixed points; they are already known. /vibe-review is read-only: it reports findings but never modifies issue bodies, checkboxes, comments, labels, or statuses. Passing reviews never authorize closing issues.
3. If read-only review has no unresolved findings, commit reviewed work to the work branch. Acceptance checkbox flips (Tracker Updates) are part of this disposition and finish before the human merges. Then follow whether an externally supplied record exists:

• Externally supplied record exists (e.g. assigned workspace supplied by `vibe-goal`). Commit directly to supplied work branch, keeping linear above supplied base. Do not create extra branches or worktrees. Do not publish work branches, treat them as durable artifacts, or clean them up directly. Do not merge or land into original target. Do not clean, delete, or alter supplied worktrees. Caller owns and disposes of them. On hosted trackers, tick acceptance checkboxes only per Tracker Updates; do not close issues or change close-status. Version-controlled local Markdown ticket files are branch content included in ticket commits per Tracker Updates. Return branch name, exact supplied ticket base SHA, exact reviewed head SHA, verification proof, read-only /vibe-review verdict and report, notes on whether supplied base moved, and a one-line resumption record (task unit ID, work branch, worktree path, current owner/status). This enables subsequent review-fixes or retries for the same ticket to reuse this exact workspace instead of creating new branches or worktrees. Nothing else. Caller owns integration and final landing.
• No externally supplied record (direct invocation). Finish with exactly one surviving branch and no leftover worktree: reviewed vibe/* branch, linear on fixed point. If target moved, rebase onto it without merge commits. Maintain that branch as implementation source instead of landing. For local Markdown trackers, confirm unmerged branch is preserved before removing worktree and report branch name. For GitHub, push work branch and create a pull request targeting the original branch. For GitLab, push and create a merge request targeting the original branch. On hosted trackers, tick acceptance checkboxes before publishing and include a closing reference or a non-closing reference in the PR/MR description per the native-close eligibility and eligible-close rules in Tracker Updates, then verify target branch and closing-issue list immediately after publishing. Do not close issues directly; do not merge automatically. For other hosted trackers supporting pull/merge requests, follow documented publishing workflows. Remove worktree only after preservation or publishing succeeds. Report preserved branch name (or request URL for hosted trackers) and a one-line resumption record (task unit ID, original target/ref, fixed point, preserved branch, empty worktree path once removed, current owner/status). This enables subsequent review-fixes or resumptions to reattach worktrees to that exact preserved branch instead of creating new vibe/* branches. Leave no other vibe/* branches or worktrees from the same run. Do not merge automatically. Original branch remains untouched.

If unrelated dirty states, conflict ambiguities, or other unsafe conditions prevent safe disposition, do not publish, merge, clean up, or delete. Preserve original and resulting branches and commits, leave user state untouched, and report blockers. Branch or worktree removal is permitted only after disposition is safe. For in-progress merge or rebase conflicts, follow MERGE-CONFLICTS.md.

PR/MR Evidence and Risk

Apply only when publishing a PR/MR under Completion Disposition. Preserve the repository's existing template and domain language while briefly adding:

• Before/after evidence. Pair already-collected before/after observations for each main behavioral claim. For visual changes, compare screenshots when the environment supports them; otherwise show actual failing-then-passing tests or execution results and reproduction commands. Briefly explain the key test steps rather than merely stating "tests pass." If before evidence is unavailable, state that limitation and why. Do not fabricate results or perform risky production reproductions just to fill the format. Redact secrets and personally identifiable information from logs and screenshots.
• Reversibility and impact. State whether a simple rollback suffices or data deletion, migrations, or external changes require separate recovery, and identify the callers, data, or screens actually affected. Mark unverified risks as uncertain.
• Preserve authority and references. This format grants no additional publishing, merge, or issue-closing authority. Follow Tracker Updates below for closing-reference eligibility and post-publish verification. Externally supplied workspaces create no PR/MR and return verification evidence to the caller under the existing return contract.

Tracker Updates

• Local Markdown, Version-Controlled. Ticket files are branch content, not external systems. Inside the work branch worktree, flip acceptance checkboxes to [X] and include that edit in the same commit as the implementation. No separate tracker commits, comments, or commits on original/target branches. Do not await landing proof or request tracker-change approval. User owns merge; merge carries code and checklist together or neither. Do not edit 상태: lines.
• Hosted Trackers (GitHub, GitLab, other hosted trackers). Acceptance checklists and issue close are separate. The human owns merge; the agent never merges. Publishing is not landing.
• Checklist. If read-only review has no unresolved findings, tick the ticket's acceptance checkboxes before publishing the PR/MR (direct invocation without external record) or returning to the caller (externally supplied record). Do not await landing proof or request checkbox-only approval. The agent does not close the issue itself — on eligible PR/MRs, provider-native auto-close performs the close when the human merges in the UI.
• Native close eligibility. Applies only when no externally supplied record exists, the PR/MR targets the provider's default branch, and merge completes acceptance of exactly one implementation ticket. A parent spec issue is never a closing target. An issue that folds spec and the sole ticket is itself the ticket and is eligible. Externally supplied workspaces never use a closing reference because they do not publish.
• Eligible close. Link that exact single ticket in the PR/MR description using the closing-reference syntax documented by the configured tracker reference's auto-close publishing rules. Immediately after publishing, run the reference's post-publish target verification commands exactly as written there to confirm that the target branch is the default branch and the closing targets are exactly that one ticket. That reference is the single source of truth for provider commands, their exact flags, and the fields to check — this document duplicates no provider commands and substitutes no commands built from memory or guesswork. If verification fails or unintended issues are attached, fix the description and re-verify before returning, or stop safely by preserving branch, commits, and PR/MR and reporting the blocker. Never return unverified. The human's UI Merge action is the close approval, so no separate close preview or approval is required after merge. The agent never merges and never closes the issue itself. A passing review alone never authorizes close.
• Ineligible fallback. If the target is not the default branch, an operational or deployment gate remains after merge, or the parent or multiple goals make the target ambiguous, use a non-closing reference without a closing keyword and do not use native close. Closing such a ticket is not the merge gate. Only after independently obtaining authoritative proof that the exact reviewed commit SHA is on the designated target branch (e.g. git merge-base --is-ancestor <commit> <target-branch> succeeds) may follow-up or resumption direct invocations show an exact preview of close, status, and comments. Await separate explicit approval immediately before writing. Implementation requests, completed reviews, declines, or non-responses do not constitute close approval. Never close issues without approval.

Never propose or modify parent spec issues on any tracker. On hosted trackers, an issue that is both spec and the sole ticket is the ticket — tick its acceptance checkboxes there.