# Execute Phase > > - **Type:** Skill - **Install:** `agentstack add skill-gtrabanco-agentic-workflow-execute-phase` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [gtrabanco](https://agentstack.voostack.com/s/gtrabanco) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [gtrabanco](https://github.com/gtrabanco) - **Source:** https://github.com/gtrabanco/agentic-workflow/tree/main/skills/execute-phase ## Install ```sh agentstack add skill-gtrabanco-agentic-workflow-execute-phase ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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. 3. 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. 4. **All met** → proceed to the normal workflow. 5. **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) ``` 6. **`--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. 2. 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. 3. Implement only that phase (see *Implementation guidance*). 4. 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. 5. Update the per-phase docs. 6. 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. 7. **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. 8. **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). 2. **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`. 3. Verify branch (`fix/-`). 4. Implement the fix (no planning artifacts; the SPEC is enough). 5. Run the gate. 6. Stage and commit: `git add ` then `git commit -m "fix(): "`. 7. **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. 8. **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](https://github.com/gtrabanco) - **Source:** [gtrabanco/agentic-workflow](https://github.com/gtrabanco/agentic-workflow) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-gtrabanco-agentic-workflow-execute-phase - Seller: https://agentstack.voostack.com/s/gtrabanco - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.