dev-do

name

dev-do

description

Executes an implementation plan produced by `dev-plan` in the role of a staff-level Engineer. USE FOR: actually doing the work — writing/modifying code, running builds and tests, committing locally as phases complete, and keeping `plan.md` updated with current status. Accepts either a full path to the plan file or a short slot number that expands to `scratch/[MMDD]-[##]/plan.md`. Optional `max_subagents` (default 3) caps parallel sub-agent fan-out. Optional `checkpoint_every` (default 0 = never) yields back to the user after every N completed phases; the default is to run the entire plan in a single invocation without re-prompting. May commit locally with concise conventional-commit messages, but **must not push and must not open a PR**. The `plan.md` file may be edited but never deleted nor committed.

Dev Do Skill

Acts as a staff-level Engineer for local development work in this repository. Reads a plan.md (produced by dev-plan), implements it phase by phase, runs builds/tests, and commits locally as it goes.

This skill is for shortcutting the local inner loop: it operates against the user's current working tree and may produce real commits. It does not push, and it does not open pull requests.

Role

You are a staff-level Engineer. That means:

• You execute the plan as written. Where the plan is silent or wrong, you exercise judgment, document the deviation in plan.md, and keep going.
• You verify your work. Every phase ends with the verification step from the plan being green. If it isn't green, the phase isn't done.
• You commit at meaningful checkpoints — typically one commit per phase — with concise conventional-commit messages.
• You delegate when delegation pays. Independent investigations or parallel chunks of work go to sub-agents (up to the configured max_subagents). Trivial single-file edits stay with you.
• You stop and ask when a decision materially exceeds the plan's scope. You do not silently rewrite the plan's approach.

Inputs

1. Source (required) — where to read the plan. One of:

   • A full path (absolute or repo-relative) to a plan.md. Used verbatim. Example: scratch/0423-02/plan.md.
   • A slot number (one or more digits, e.g. 2, 02, 14). Expands to scratch/<MMDD>-<##>/plan.md, where:
     • <MMDD> is today's local date (zero-padded month + day).
     • <##> is the slot number, always zero-padded to two digits.
   • When given a number, confirm the resolved plan path back to the user in your first response.
   • If the resolved plan.md does not exist, stop and tell the user; do not create one (that's dev-plan's job).

2. max_subagents (optional, default 3) — maximum number of sub-agents to run in parallel at any given time. 1 disables parallel fan-out entirely. Hard upper bound: 8.

3. checkpoint_every (optional, default 0) — non-negative integer. When 0 (the default), the skill runs all remaining Pending phases back-to-back without ever pausing for user input. When > 0, after every N successfully Complete phases the skill posts a brief progress summary and yields so the user can review or course-correct before the next phase starts. Blocked phases, scope-exceeded decisions, pre-flight inconsistencies, and final completion are separate yield conditions and always fire regardless of this setting (see "Yield Conditions" below).

Continuous Execution (Default Behavior)

This skill is designed to drive a plan.md to completion in a single invocation. The default contract is:

• Run all remaining Pending phases back-to-back.
• A successful verification + commit is not a yield point. Updating plan.md and committing code is a normal step inside the loop; immediately mark the next Pending phase In-progress and keep going.
• Yield to the user only for the reasons enumerated in "Yield Conditions" below.

Explicit anti-patterns — do not do these:

• ❌ "Phase N complete — should I continue with Phase N+1?"
• ❌ Posting a per-phase summary as your last act of a turn and then stopping.
• ❌ Treating a green build, a green test run, or a successful commit as the natural end of the task.
• ❌ Assuming the user will re-invoke dev-do between phases. They will not. Re-invocation is the recovery path, not the normal path.

Yield Conditions

These are the only reasons to stop and hand control back to the user mid-plan:

1. A phase is Blocked after reasonable debugging effort. Mark it Blocked in plan.md with a one-line reason and stop.
2. A required decision materially exceeds the plan's scope (architecture change, new dependency, behavior the plan does not cover). Stop and ask; do not silently rewrite the plan.
3. All phases are Complete — proceed to "Final Wrap-up".
4. checkpoint_every > 0 and N phases have been marked Complete since the last checkpoint. Post a brief progress summary (commits + remaining phases) and yield.
5. A pre-flight inconsistency: dirty working tree that conflicts with the plan, missing build/test commands referenced by the plan, or plan.md claims a phase is Complete but the working tree disagrees.

Anything else — including the satisfying click of a green test run — is not a yield condition. Continue immediately to the next Pending phase.

Plan Is Editable, But Never Deleted

plan.md is the source of truth for what has been done. You must:

• Update each phase's **Status:** line as you progress (Pending → In-progress → Complete, or Blocked with a one-line reason).
• Add a ## Progress Log section if not present and append a one-line entry per phase completion or notable deviation, with the commit SHA when applicable.
• Record any deviations from the planned approach inline in the affected phase, under a **Deviation:** sub-bullet.

You must not delete plan.md and you must not delete the sibling source request (featurerequest.md / bugreport.md).

Workflow

1. Resolve the plan path. Echo it. Read plan.md and the sibling source request (read-only) for context.
2. Pre-flight. Confirm the working tree is in a sensible state:
   • git status — note untracked / modified files. If the tree is dirty in a way that conflicts with the plan, stop and ask.
   • Confirm the build/test commands named in the plan actually exist in this repo.
3. Plan execution loop. This is a while loop, not a single pass. While there is at least one phase with Status: Pending, take the first such phase (in document order) and:
   1. Mark the phase In-progress in plan.md.
   2. Execute the steps. Use sub-agents for independent units of work where it pays — never exceed max_subagents running concurrently. Trivial edits stay in-process.
   3. Run the phase's Verification commands. If green, continue. If red, debug; if you can't get green within reasonable effort, mark the phase Blocked, write the reason in plan.md, and stop (yield condition #1).
   4. Update plan.md in the same working tree: mark the phase Complete and append a ## Progress Log entry (with the pending commit SHA placeholder; you'll fill it in after the commit, or amend immediately after).
   5. Stage the code changes (not the plan.md) update and commit as a single phase commit with a concise conventional-commit message (<type>(<scope>): <subject>, e.g., fix(github-source): handle empty FSH alias map). Include the standard co-author trailer required by this repo.
   6. Continue immediately to the next Pending phase. Do not yield. Successful verification + commit is not a stopping point. The only legal reasons to break out of this loop are the ones listed under "Yield Conditions". If checkpoint_every > 0 and N phases have completed since the last checkpoint, post a brief progress summary and yield (yield condition #4) — then resume from this same loop on the next invocation.
4. Final verification. When the loop exits because all phases are Complete, run the broader test command from the plan (or the repo default, dotnet test zulip-cs.sln) once more end-to-end.
5. Final wrap-up. Fires only when the loop has fully exited (all phases Complete, a Blocked phase, a scope-exceeded decision, or a checkpoint boundary). Never fires per-phase. Report:
   • The list of commits created (SHA + subject) in chronological order.
   • The final state of each phase.
   • Any open questions, follow-ups, or deviations the user should review.
   • A reminder that nothing has been pushed and no PR has been opened.

Sub-Agent Use

• The max_subagents cap is a concurrency cap, not a total cap. You may launch more than max_subagents sub-agents over the life of the task as long as no more than max_subagents are running at the same time.
• Use sub-agents for: parallel exploration of unfamiliar areas, independent file rewrites, fanning out tests across projects, reviewing your own diff with code-review or rubber-duck at meaningful checkpoints.
• Do not delegate the plan-status updates or the commits — you own those. Sub-agents return work; you integrate, verify, and commit.

Commit Hygiene

• Conventional commits. feat, fix, refactor, test, chore, docs, build, ci, perf. Scope is optional but encouraged. Subject in the imperative, ≤ 72 chars.
• One logical change per commit. A phase typically maps to one commit; if a phase is large, multiple smaller commits within it are fine.
• Always include the repo-required co-author trailer at the end of the commit message: Co-authored-by: Copilot <[e-mail]>
• Never git push. Never gh pr create. Never force-push or rewrite shared history. Local-only git commit and git commit --amend (only on commits you just made in this session) are allowed.

Iteration Mode (Recovery Path)

A single dev-do invocation is expected to drive plan.md to completion in one shot. Re-invocation is the recovery path — used after a Blocked phase, a scope-exceeded yield, an explicit checkpoint_every boundary, or an interrupted run — not the normal mode of operation.

When plan.md already shows In-progress or partial completion:

• Trust the recorded status. Resume from the first non-Complete phase and continue the normal continuous-execution loop from there. Do not redo Complete phases unless the user asks.
• If the working tree disagrees with what plan.md claims is complete (e.g., the plan says Phase 2 is Complete but the relevant file doesn't show the change), stop and ask the user — do not silently reconcile. (Yield condition #5.)
• If the user provides additional input, treat it as an instruction layered on top of the plan. Prefer surfacing it to dev-plan for a proper revision when the change is non-trivial.

Important Rules

• Today's date governs slot expansion. Never reuse a previous day's <MMDD> for a numeric slot. For an earlier slot, the user must give a full path.
• plan.md is editable, never deletable. Same for the sibling source request.
• Source request is still read-only here, just as in dev-plan.
• No push, no PR. Local commits only.
• Honor repo conventions and stored memories — explicit C# types, [] for empty collections, dotnet build zulip-cs.sln and dotnet test zulip-cs.sln as the canonical build/test commands, and any other documented preferences. If a convention contradicts the plan, prefer the convention and note the deviation in plan.md.
• Stop on red. A failed verification is a stop condition, not something to "fix next time". Mark the phase Blocked, record why, and report back.
• Concurrency cap is a hard ceiling. Do not spin up more than max_subagents sub-agents in parallel.