Execute Phase

Execute Phase

Three modes:

• feature phase (default) — implement one phase of docs/features/-/ using its TASKS.md.
• single-pass — a small feature (SPEC Size: XS/S; only a SPEC.md, no planning artifacts): implement it end-to-end in one pass.
• --fix — implement a fix from docs/fix/-/.

Turn contract — every invocation, verify before ending the turn

✓ 1. Branch verified FIRST: `git branch --show-current` was RUN and its output
     pasted. Output = the default branch → `git switch -c ` was RUN
     before any edit. NEVER work on main/master.
✓ 2. The gate was RUN (not assumed): commands + exit codes pasted.
✓ 3. `git add ` and `git commit -m "(): "` were
     EXECUTED and the resulting sha is pasted. Describing a commit you did not
     run counts as NOT committed.
✓ 4. Unit finished (single-pass, --fix, or final phase)? Then `git push` and
     `gh pr create` were EXECUTED and **the PR URL is printed in the chat**
     (not every agent shows open PRs — the link in the chat is the contract).
     The PR body is NEVER empty: what it does, why, evidence, and
     `Closes #` when issue-born. The body is passed with `--body-file`
     (real Markdown, NO `\`-escaped backticks — see Issue policy). AND the roadmap row (or fix-index entry)
     was updated to `done · [#]()` in a follow-up
     `docs: link PR #` commit, pushed to the same branch. A `done` row
     without its PR link is an UNFINISHED unit. Unit not finished? Then
     NOTHING was pushed.
✓ 5. Clean-tree check LAST: `git status --porcelain` was RUN and its output
     pasted immediately before ending the turn. Any tracked modification —
     CODE OR DOCS (`docs/**` counts; doc updates left uncommitted are the #1
     close-out failure) — was committed before the turn ended. AND if the
     branch has an open PR: `git status -sb` shows the branch is NOT ahead of
     its remote (every commit pushed). A dirty tree or an unpushed commit on a
     PR-backed branch = the turn is NOT done.
✓ 6. Artifact language: explicit user instruction > the project's declared
     docs language > English. The CONVERSATION language never decides — a
     Spanish prompt still produces English commits/PRs/issues unless one of
     the first two says otherwise.
✓ 7. The closing `→ Next:` block is printed, then the machine envelope
     (fenced ```json — see ## Machine envelope) as the ABSOLUTE last output.

Push policy — two regimes, by whether the PR exists yet. Before the PR: push happens exactly once, at the PR step — never mid-phase, never unasked, never to the default branch. After the PR exists: every subsequent commit on that branch (folded review findings, audit-blocker fixes, doc updates, the docs: link PR commit) is pushed immediately after committing — an open PR must always show the branch's latest state; CI and the merge gate judge the remote, not your working copy. If, about to end the turn, any box is unchecked: STOP and complete it now — a turn that ends with work implemented but uncommitted, committed but unpushed (PR open), or committed but missing its PR (finished units), is a FAILED turn, not a done one.

Hard rules

• Honor the project's Workflow conventions (branch/PR, gate-before-commit, docs-language). Run git branch --show-current before any edit/commit; if main, create the working branch first (assistant only; the user may use main).
• Phases are P1, P2, …. The ` argument and every reference in PLAN.md/TASKS.md/progress.md/commits is P1, P2, … ("phase N") — **never** S1/S2/"Step N". If a plan you're handed uses S1-style labels, normalize it to P1, … before executing and note it in decisions.md`.
• Implement only the requested scope — one phase (feature mode) or the whole SPEC (single-pass/fix). Never bundle phases unless asked.
• Stop after the gate passes; keep commits small and reviewable.
• Feature mode: update TASKS.md, progress.md, testing.md, known-issues.md each phase (and decisions.md if architecture moved).
• When reality contradicts the plan (a task is impossible, an assumption is wrong, a better path appears): update TASKS.md/PLAN.md and record why in decisions.md — never silently diverge from the written plan.
• Dependency gate before any work — see the section below. No edit, no branch, no commit happens for a unit whose dependency closure isn't merged, unless the user passed --force.

Dependency gate (always, before any other step)

Run this check for every mode (feature phase, single-pass, and --fix) before touching anything:

1. Read the unit's Depends on: (SPEC) and its roadmap/fix-index row.
2. Build the transitive closure: for each dependency, read its roadmap

row and collect its dependencies too, until none remain.

1. For each entry in the closure, its status must be merged in the forge

(gh pr view on its PR, or the row's PR reference) — done-but-PR-open is NOT met (its code isn't on the default branch), and a missing folder/row is NOT met.

1. All met → proceed to the normal workflow.
2. Any unmet → STOP before any edit and print exactly:

``` DEPENDENCY GATE — - BLOCKED Unmet chain (deepest first is the one to start): ← () [← () …] Build order to unblock: → … →

→ Next: /execute-phase P1 — the deepest unmet dependency (plan it first with /plan-feature if it has no SPEC) · fix-type dependency → /plan-fix then /execute-phase --fix · proceed anyway, at your own risk → /execute-phase --force (the override is recorded in decisions.md — never silent) ```

1. --force skips the stop (never the check): the gate still runs and its

result is recorded in decisions.md ("started with unmet deps: , user-forced ") before implementation begins. --force is a user-only escape hatch — the autopilot (ship-roadmap) must never pass it.

Allowed & forbidden (fixed lists — no interpretation)

Allowed changes in a phase:

• The phase's own tasks (from TASKS.md, or the SPEC for single-pass/fix)
• Tests for the behavior this phase adds or alters
• The per-phase doc updates listed in the completion gate below
• The smallest refactor strictly required to land a task (state why in the commit)

Forbidden — never, even if it "would help":

• New abstractions beyond what the SPEC names (an interface with one

implementation is a violation)

• New dependencies not justified in the SPEC
• Public API / contract changes the SPEC doesn't name
• Architecture changes (layers, boundaries, patterns)
• Refactoring unrelated code
• Building future phases or features early

Something forbidden looks necessary → stop, record it in decisions.md or known-issues.md, and surface it — never do it silently.

Phase completion gate — pass only if (every box, every phase)

✓ Verification gate green — type-check + tests + build actually RUN (paste exit
  status), never assumed
✓ Every task of this phase checked off in TASKS.md, each mapped to evidence
  (code path or test name)
✓ Tests updated/added for every behavior this phase changed
✓ No TODO/FIXME/HACK markers left in the diff
✓ No duplicated logic (reuse the existing helper — cite it if one existed)
✓ No dead code introduced (unused imports, functions, unreachable branches)
✓ No hidden breaking change (changed public contracts diffed against their
  consumers)
✓ Architecture doc respected (dependency directions, layer boundaries)
✓ Docs updated — at minimum verify each of: TASKS.md (checkboxes),
  progress.md, testing.md, known-issues.md, decisions.md (if any decision was
  taken), SPEC.md (only if scope/acceptance changed — with the change logged)
✓ Docs COMMITTED with the phase — after the phase commit,
  `git status --porcelain -- docs/` returns nothing. Doc updates ride the
  phase commit (same `git add`), never sit uncommitted "for later"

A phase that cannot tick every box is not done: fix within the phase's scope, or record the blocker in known-issues.md, leave the work uncommitted, and stop with a clear report. Never commit red; never tick a box you didn't verify.

Branch

| Mode | Format | |------|--------| | feature / single-pass | feat/- | | --fix | fix/- |

Read the SPEC's Branch field; create with git switch -c . If absent/ambiguous, ask. Never commit, amend, or force-push on main.

Honor the project's declared Git workflow (Workflow conventions — branches or worktrees). Default and assumption everywhere: branches — one active unit at a time, sequential, plain git switch -c; never create a worktree. Only when the project explicitly declares worktrees may a unit get its own checkout — and then one worktree per unit, removed after merge.

Issue policy

Forge operations use the project's declared forge CLI (Workflow conventions — examples use gh; translate if the project declares another forge).

> Forge bodies are Markdown, not shell — never hand-escape them. Backticks, > *, _, #, | in an issue / PR / comment body are formatting; a \ > before them renders literally (` \code\ instead of code ) — > the #1 forge-formatting bug (worse on some agents than others). Fix it at the > source: **never pass a Markdown body inline** (--body "…", a quoted > mangle backticks). Instead write the body to a file with the Write tool > (plain Markdown — real backticks, zero backslashes; scratchpad is fine) and > pass --body-file : gh issue create --body-file , > gh pr create --body-file , gh issue comment --body-file > (or the declared forge's equivalent). Short one-liners with no Markdown (e.g. > a bare Closes #12) may stay inline. Verify after creating: > gh issue view --json body / gh pr view --json body must show > backticks rendering — a literal ` \ ` in the output means redo it with > --body-file`.

• --fix: every fix needs a tracked issue; create with gh issue create --template fix.yml --body-file if missing, populating the body from the SPEC (body as a Markdown file — see the Markdown rule above). Use the returned number for branch and folder.
• feature: if it came from an issue, include Closes # in the PR body. Don't create issues for features that didn't originate from one.
• Language precedence for every artifact (issues, PRs, commits, SPECs, docs): (1) an explicit user instruction in the prompt, else (2) the project's declared docs language (Workflow conventions), else (3) English. The conversation language is NOT a signal — being asked in Spanish never makes the PR Spanish. Non-matching source material gets translated first.

Workflows

Feature phase (default) — docs/features/-/

1. Verify branch (create if on main). P1 only: if the planning artifacts

(docs/features/-/) are still uncommitted, commit them first on the feature branch — git add docs/features/- && git commit -m "docs(-): planning artifacts" — so planning history stays separate from implementation.

1. Read progress.md first (the running log — what prior phases did and left

open), then SPEC.md + TASKS.md for the requested phase. Same-session shortcut: if you executed the previous phase in this session and the planning docs haven't changed, don't re-read them — only the new phase's TASKS.md section.

1. Implement only that phase (see Implementation guidance).
2. Run the gate (type-check, tests, build). If red: fix within the phase's

scope and re-run — never commit red. If the failure can't be fixed within this phase's scope, record it in known-issues.md, leave the work uncommitted, and stop with a clear report.

1. Update the per-phase docs.
2. Stage and commit: git add then git commit -m "(): " — one commit per phase, conventional format. Run this; don't just describe what should be committed.
3. Review checkpoint (recommended, not blocking) — every 2 phases, recommend a hand-off to /review-change in the closing block (see below). The user decides: review now, or continue straight to the next phase — the skill never forces the intermediate stop. The end-of-unit review stays mandatory (it feeds audit-pr, the merge gate). Never run the review in this skill's turn.

Resuming an interrupted phase (stated contract — any agent must honor it). If, on entry, the unit branch already carries dirty files or commits belonging to the requested phase (a prior run died mid-turn — e.g. the driver process restarted), do not restart the phase from scratch: reconcile against TASKS.md first — verify each ticked task's evidence actually exists (code path / test present), untick any tick without evidence, then continue from the first unticked task. Idempotent re-entry is the contract workflow-status's crash-recovery verdict RESUMABLE relies on. If the ledger contradicts the commits in a way that has no unique next task, stop and report instead of guessing (that is its AMBIGUOUS verdict — a human decides).

Single-pass — small feature with only a SPEC.md, no planning artifacts:

1. Verify branch.
2. Read SPEC.md (+ DECISIONS.md if present) and the docs its documentation map points to.
3. If the SPEC is ambiguous on scope / edge cases / UI, ask first — one question at a time, nothing it already answers.
4. Implement end-to-end (see Implementation guidance).
5. Run the gate; write CHECKLIST.md (below).
6. Stage and commit: git add then git commit -m "(): ".
7. Mark done + open the PR — always (this is the last step). Flip the roadmap

row to done (it's built; merge state lives in the forge, not the status — see Marking done), commit that flip, then git push and open the PR (body written to a file as Markdown, per the Markdown rule above): gh pr create --base main --title "(): " --body-file (put Closes # in that body when issue-born). Then, with the URL gh pr create returned: print it in the chat, update the roadmap row to done · [#](), commit (docs: link PR #), and push again — the link commit rides the same open PR. A single-pass unit never ends branch-only — it always leaves an open, chat-linked PR, regardless of the review/audit still to come.

1. Mandatory review hand-off → /review-change (the required final quality step;

see Review checkpoint), then audit-pr as the merge gate. Print the next step.

--fix — docs/fix/-/, template docs/fix/_TEMPLATE/SPEC.md, index docs/fix/README.md:

1. Verify the issue exists (gh issue view ); if it doesn't, create it

(gh issue create --template fix.yml --body-file , body from the SPEC written to a Markdown file — per the Markdown rule above).

1. If docs/fix/-/SPEC.md already exists (e.g. from plan-fix), use it — do not re-draft. Otherwise copy the template, fill every section, and register the entry in docs/fix/README.md.
2. Verify branch (fix/-).
3. Implement the fix (no planning artifacts; the SPEC is enough).
4. Run the gate.
5. Stage and commit: git add then git commit -m "fix(): ".
6. Mark done + open the PR — always (this is the last step). Set the

docs/fix/README.md entry's status to done (built, not yet merged), commit, git push, then open the PR with the body written to a Markdown file (per the Markdown rule above): gh pr create --base main --title "fix(): " --body-file (the body includes Closes #). Run the commands. Then, with the returned URL: print it in the chat, set the docs/fix/README.md entry to done · [#](), commit (docs: link PR #), and push again. A fix never ends branch-only — it always leaves an open, chat-linked PR.

1. Mandatory review hand-off → /review-change, then audit-pr as the merge gate.

Print the next step. Keep the fix-index entry until the PR is actually merged (don't drop issue tracking early; the merge ga

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gtrabanco
• Source: gtrabanco/agentic-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.