# gf-workflow — Reference
Operations reference for the `gf-workflow` orchestrator. Main execution flow: see `SKILL.md`.
## Contract Operations API
### Create Contract
```bash
gf workflow create --title "<issue_title>" --mode <full|fast>
# 输出分配的 ID 与合同路径,例如:
# ✅ Workflow 已创建: wf-2026-08-08-002
# 合同: .cache/workflows/active/wf-2026-08-08-002.json
```
ID 由 CLI 自动分配(Issue #142):扫描 `active/` 与 `archive/` 全部月份目录取当日
最大序号的下一个空位,并用 O_EXCL 原子写入——归档后序号不复用,并发创建不产生
同名合同。**不要手写 `WORKFLOW_ID` 或按 active 数量计数**(旧逻辑已废弃)。
### Update Contract (on Phase completion)
```bash
COMPLETED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
jq --arg phase "$PHASE_NUM" \
--arg status "complete" \
--arg completed_at "$COMPLETED_AT" \
--argjson evidence "$EVIDENCE_JSON" \
'.phases[$phase].status = $status | .phases[$phase].completed_at = $completed_at | .phases[$phase].evidence = $evidence | .updated_at = $completed_at' \
".cache/workflows/active/${WORKFLOW_ID}.json" > "${WORKFLOW_ID}.tmp" \
&& mv "${WORKFLOW_ID}.tmp" ".cache/workflows/active/${WORKFLOW_ID}.json"
```
### Advance to Next Phase (after gate passes)
```bash
jq --arg next "$((PHASE_NUM + 1))" \
--arg started_at "$COMPLETED_AT" \
'.current_phase = ($next | tonumber) | .phases[$next].status = "in_progress" | .phases[$next].started_at = $started_at | .updated_at = $started_at' \
".cache/workflows/active/${WORKFLOW_ID}.json" > "${WORKFLOW_ID}.tmp" \
&& mv "${WORKFLOW_ID}.tmp" ".cache/workflows/active/${WORKFLOW_ID}.json"
```
### Read Contract
```bash
jq '.current_phase, .phases | to_entries[] | select(.value.status == "in_progress") | .key' \
".cache/workflows/active/${WORKFLOW_ID}.json"
```
## Cross-Session Recovery
Workflows may be interrupted at any Phase. New sessions recover via contract + plan doc.
```
New Session Starts
↓
1. List .cache/workflows/active/*.json → find workflow with status != "complete"
2. Read current_phase and evidence
3. Load context based on mode and current_phase:
• Phase 1: No doc needed (start fresh)
• Phase 2: Read design_doc_path; check mode for Phase 1 exemptions
• Phase 3: Read spec_path (plan document); check mode for fast skip; also reload `change_surface`/`security_check`/`regression_check` evidence (Issue #344) and `diff_review_status`/`diff_review_path` (Issue #397) alongside `branch`/`worktree_path` — do not re-ask an answered change-surface question; rerun the cheap diff render if resuming before delivery, since HEAD may have changed
• Phase 4: Read pr_url + review reports and any generated local `diff_review_path`; use get_phase4_steps(mode) to determine remaining steps
4. Resume from current_phase, follow auto-trigger rules
```
**Key principles:** Contract = state machine. Plan doc = execution manual. Design doc = requirement source. All state in contract and documents, no external dependencies.
## Multi-Workflow Concurrency
```
.cache/workflows/
├── active/
│ ├── wf-2026-07-09-001.json ← feat: TOON
│ └── wf-2026-07-09-002.json ← fix: pr merge
└── archive/
└── 2026-07/
└── wf-2026-07-08-001.json
```
Each workflow uses its own worktree, branch, and contract file — no interference.
### Worktree Path Convention
All worktrees are created at a fixed location within the project: `.worktree/<branch-name>`
- **Path pattern:** `.worktree/feat/<issue-number>-<short-description>`
- **Branch naming:** `feat/<issue-number>-<short-description>` (e.g., `feat/146-worktree-path`)
- **Gitignore:** `.worktree/` is included in `.gitignore`
- **Benefits:**
- Worktrees remain within the project directory for easy discovery and cleanup
- Predictable paths for Phase 4 Branch Finish automation
- No orphaned worktrees in parent directories
**Example:**
```bash
# Phase 3 Step 1: preflight, then create worktree
git status --porcelain # classify before forking (see below)
git worktree add .worktree/feat/146-worktree-path -b feat/146-worktree-path main
# Carry this workflow's Phase 1/2 documents INTO the worktree, then commit on the
# feature branch (structure-preserving and portable — macOS has no `cp --parents`)
WORKTREE_PATH=".worktree/feat/146-worktree-path"
for f in docs/superpowers/specs/146-x-design.md docs/superpowers/plans/146-x.md; do
mkdir -p "$WORKTREE_PATH/$(dirname "$f")"
cp "$f" "$WORKTREE_PATH/$f"
done
# Backstop: assert every contract-referenced document really landed in the worktree
for f in docs/superpowers/specs/146-x-design.md docs/superpowers/plans/146-x.md; do
test -f "$WORKTREE_PATH/$f" || { echo "ABORT: $f missing in worktree"; exit 1; }
done
# Symlink shared directories (workflow contracts + Claude config).
# Depth is computed, not hardcoded: worktree_path can be multi-segment
# (branch names follow feat/<issue-number>-<short-description>, so
# .worktree/<branch-name> is routinely 2+ segments deep). See "Why the
# Symlink Depth Is Computed, Not Hardcoded" below for the formula and
# the empirical proof.
segs=$(awk -F/ '{print NF}' <<< "$WORKTREE_PATH")
ups_cache=$((segs + 1)) # .cache/workflows 软链文件位于 .cache/ 下,多一级
ups_claude=$segs # .claude 软链文件直接位于 $WORKTREE_PATH 下
rel_cache=$(printf '../%.0s' $(seq 1 "$ups_cache"))
rel_claude=$(printf '../%.0s' $(seq 1 "$ups_claude"))
mkdir -p "$WORKTREE_PATH/.cache"
ln -s "${rel_cache}.cache/workflows" "$WORKTREE_PATH/.cache/workflows"
ln -s "${rel_claude}.claude" "$WORKTREE_PATH/.claude"
# Existence self-check — a dangling symlink still passes `test -e`, so verify
# the *resolved target* is a real directory. A failure here means the depth
# formula or worktree_path itself is wrong, not that the contract is missing.
test -d "$WORKTREE_PATH/.cache/workflows" || {
echo "ABORT: .cache/workflows symlink depth miscalculated — worktree_path=$WORKTREE_PATH segs=$segs ups_cache=$ups_cache"
echo "Expected to resolve to repo-root .cache/workflows but did not."
exit 1
}
test -d "$WORKTREE_PATH/.claude" || {
echo "ABORT: .claude symlink depth miscalculated — worktree_path=$WORKTREE_PATH segs=$segs ups_claude=$ups_claude"
echo "Expected to resolve to repo-root .claude but did not."
exit 1
}
# Exclude them from git tracking — writes to the COMMON git dir's info/exclude
# (verified: worktrees do NOT have a per-worktree info/exclude; this file is shared
# by the main tree + all worktrees of this local clone), so it protects every
# worktree, not just this one, without touching the project's own .gitignore.
EXCLUDE_FILE="$(cd "$WORKTREE_PATH" && git rev-parse --git-common-dir)/info/exclude"
grep -qxF '.cache/workflows' "$EXCLUDE_FILE" || echo '.cache/workflows' >> "$EXCLUDE_FILE"
grep -qxF '.claude' "$EXCLUDE_FILE" || echo '.claude' >> "$EXCLUDE_FILE"
cd "$WORKTREE_PATH"
git add docs && git commit -m "docs(workflow): wf-2026-08-30-001 Phase 1-2 artifacts"
cd -
# Only now remove the main-tree copies, so the eventual merge cannot be blocked
rm docs/superpowers/specs/146-x-design.md docs/superpowers/plans/146-x.md
# Phase 4 Branch Finish: Remove worktree
git worktree remove "$WORKTREE_PATH"
```
### Worktree Preflight (Phase 3 Step 1)
`git worktree add` checks out a **committed** state. Anything uncommitted in the main
working tree stays behind — including this workflow's own Phase 1/2 documents, which the
contract references by path. The contract itself survives (it is symlinked), so without a
preflight the executor is handed a `spec_path` that does not exist in its working directory
and plans against a document it cannot read.
Run this before `git worktree add`. `git status --porcelain` empty ⇒ record
`worktree_preflight = "clean"` and proceed.
| Bucket | Match | Action |
|---|---|---|
| **A — workflow artifacts** | paths equal to contract `design_doc_path`, `spec_path`, `ticket_refs[]` | ✋ PAUSE and ask before committing (see below) |
| **B — unrelated dirty files** | everything else reported by `git status` | ✋ PAUSE and ask |
| **C — ignored** | covered by `.gitignore` (`.cache/`, `.worktree/`, `target/`) | Nothing to do (`git status` already omits them) |
**Bucket A requires explicit commit permission too** — per project policy, nothing is
committed without the user's go-ahead, and Phase 1/2 design docs are no exception just
because the workflow itself produced them. `git worktree add` only forks a **committed**
state, so these docs must be committed for the executor to see them — but the commit
itself still needs a yes. Before committing, show the paths and ask:
```
即将把以下设计文档提交到 feature 分支 <branch>,worktree 才能读取到它们:
<bucket A paths>
是否提交?
1) 提交 2) 中止(不创建 worktree,回 Phase 2 处理)
```
Choice 2 ⇒ do not run `git worktree add`; leave the contract in Phase 3 for resume.
Choice 1 ⇒ commit to the feature branch, never to `base_branch`: entering Phase 3 must
not leave commits on a shared branch as a side effect.
**Why the main-tree copies must be removed after committing.** Verified behaviour: if the
untracked originals stay, the later merge fails with
`untracked working tree files would be overwritten by merge … Aborting`. Removing them
after the worktree commit is safe because the content is preserved in git and comes back on
merge. Remove only after asserting the commit succeeded.
**Bucket B is never auto-committed and never deleted** — it is somebody else's work. Offer
exactly these four options, and record the choice in `worktree_preflight`:
```
主工作区有与本工作流无关的改动:
<paths from git status --porcelain>
它们不会进入 worktree。请选择:
1) 单独提交 2) git stash 3) 留在主工作区继续 4) 中止
```
Choice 3 ⇒ `worktree_preflight = "user_left_dirty"` and list the paths in
`unresolved_dirty_paths`, so Phase 4 and any later reader knows what was deliberately
abandoned in the main tree. Choice 2 ⇒ `"user_stashed"`. Choice 4 ⇒ `"aborted"`, keep
the contract in Phase 3 for resume.
A non-empty bucket A that the user approved and that was committed ⇒ `"artifacts_carried"`.
A non-empty bucket A that the user declined to commit ⇒ `"aborted"`, same as Bucket B
choice 4 — the contract stays in Phase 3 for resume.
**Every execution mode must run this preflight.** Modes ① and ② let the *executor* create
the worktree, so the orchestrator cannot rely on having checked the tree itself — the
handoff text must carry these steps verbatim. See `Phase 3 Execution Modes` below.
### Change-Surface Detection (Phase 3 Step 3, Issue #344)
Phase 3 Step 3 决定是否阻断式运行 `gf-security-check` / `gf-regression`,判定依据是 Step 1 已经记录的 `base_branch`——**不重新猜测 base ref**,直接复用:
```bash
diff_files="$(git diff --name-only "$base_branch"...HEAD)"
```
(`gf-quality` 的 Gate 3 曾经因为用 `${BASE_REF:-origin/main}` 猜测 base ref,在 GitLab/GitCode 默认分支不是 `main` 时解析失败;这里直接吃 Phase 3 Step 1 的既有产出,不重蹈覆辙。)
两条独立规则,各自判定,互不影响:
| 检查 | 触发路径模式 |
|---|---|
| `gf-security-check` | `Cargo.toml`、`Cargo.lock`、`**/Cargo.toml`(workspace 内任意 crate)、`deny.toml` |
| `gf-regression` | `apps/cli/src/**`、`crates/core/src/**`、`crates/github/src/**`、`crates/gitlab/src/**`、`crates/gitcode/src/**` |
都不命中(例如纯文档/spec/skill 文本改动)→ `change_surface = "docs_only"`,两项检查都记 `not_triggered`,不实际调用任何一个 skill。
**为什么必须在 Step 3(旧 Step 3 交付选择之前)而不是 Phase 4:** local_merge 路径下,旧的 Step 3(现 Step 4)会立刻把分支合并进 `base_branch`。如果检查放在 Phase 4(交付之后),发现问题时代码已经进了 `base_branch`,"阻断式"就名不副实了——所以必须卡在合并动作发生之前。
### Conditional Diff Review (Phase 3 Step 4, Issue #397)
`skills/gf-workflow/SKILL.md` → Phase 3 Step 4 defines the trigger and the
scan/render commands. It runs before the delivery choice so both PR and local
merge paths use the same `base_branch...HEAD` diff. The generated JSON/HTML
live in the main worktree's ignored `.cache/diff-review/<workflow_id>.*`, which
survives removal of the feature worktree. Record `diff_review_status` even when
not triggered or when rendering fails; record `diff_review_path` only on
success. This local file path belongs in the workflow summary, not in a remote
Issue/PR comment.
### Why the Symlink Depth Is Computed, Not Hardcoded
A relative symlink resolves starting from the directory that *contains* the
symlink file, not from `worktree_path` itself. `$WORKTREE_PATH/.cache/workflows`
lives inside `$WORKTREE_PATH/.cache/`, **one segment deeper** than
`$WORKTREE_PATH` — but `$WORKTREE_PATH/.claude` lives directly at
`$WORKTREE_PATH`, with no extra segment. The two symlinks therefore need two
different `../` counts:
```
ups_cache = (number of "/"-separated segments in worktree_path) + 1
ups_claude = (number of "/"-separated segments in worktree_path)
```
An earlier version of this formula used `ups_cache`'s value for both
symlinks, which left `.claude` dangling (it resolved one level above the
repo root) — see Issue #353.
**Verified empirically** (not inferred from documentation) with real
`mkdir` + `ln -s`:
| `worktree_path` | segments | `ups_cache` | `ups_claude` |
|---|---|---|---|
| `.worktree/foo` (single-segment) | 2 | 3 | 2 |
| `.worktree/feat/89-desc` (branch name contains `/`, per the `feat/<issue-number>-<short-description>` convention) | 3 | 4 | 3 |
The old hardcoded `../../` (2 levels) was wrong even for the single-segment
case it was presumably written for — it only reaches `.worktree/`, one level
short of the repo root, in every case. A branch name containing `/` (the
routine case, not an edge case — see the naming convention above) simply
made the shortfall larger and easier to hit. The `ups_cache`/`ups_claude`
split is correct for both symlinks, and the post-creation
`test -d "$WORKTREE_PATH/.cache/workflows"` / `test -d "$WORKTREE_PATH/.claude"`
checks catch any future regression of either formula by refusing to proceed
silently — a dangling symlink otherwise looks identical to a missing
contract to every downstream reader (see Issue #322's real-world report:
this exact ambiguity cost significant debugging time downstream).
### Why These Symlinks Must Never Reach the Main Branch
`.cache/workflows` and `.claude` inside a worktree are relative symlinks
(e.g. `../../../.cache/workflows`, `../../.claude` for a two-segment
`worktree_path` — see `ups_cache`/`ups_claude` above). If either is ever committed, `git ls-files -s`
shows a `120000` (symlink) mode entry for that path. A clone made from a commit carrying
that entry re-creates the symlink pointing at `../../<name>` **relative to that clone's own
location** — which, outside the original working tree that produced it, resolves to a
directory that does not exist or belongs to something else entirely.
**Verified real-world impact (Issue #318):** in the downstream project
`iproost/proxy/api-src`, `.cache/workflows` and `.claude/.claude` had been committed as
symlinks (commit `e7f4254`, swept in by an unrelated broad `git add`). Resolved from that
repo's root, `.cache/workflows -> ../../.cache/workflows` landed **outside the repository**,
in a directory shared by other checkouts. Every subsequent gf-workflow contract read/write in
that project actually happened against that external shared path — including a case where a
background research fork and the main session concurrently touched the same contract file and
cross-wrote each other's Phase 3/4 progress.
**Why `info/exclude` fixes this at the source, not just in this repo.** A linked worktree has
no `info/exclude` of its own: `git rev-parse --git-common-dir` from inside any worktree
resolves to the *main* repository's `.git`, and `info/exclude` always lives there — confirmed
by writing to it from a worktree and observing `git status` change in a sibling worktree and
the main tree alike. So the one write performed right after `ln -s` (see the example above)
protects the main tree and every worktree this clone will ever create, permanently, without
depending on that project's own `.gitignore` ever mentioning `.cache/` or `.claude/` — which is
exactly the gap that let `e7f4254` happen upstream.
**Belt and suspenders.** `info/exclude` only stops *new* accidental adds; it does nothing for
a symlink that is already staged in a commit about to leave `branch` (rebase, cherry-pick,
`git commit -a` racing the exclude write, etc.). That is why Phase 3 Step 4 in `SKILL.md` also
scans the diff immediately before delivery:
```bash
git diff --summary "$BASE_BRANCH"...HEAD | grep 'create mode 120000'
```
A hit means some commit on `branch` added a symlink that `base_branch` doesn't have. Treat it
as a hard stop: show the path(s), and let the user choose to drop the offending commit/entry
or explicitly confirm it is an intentional, unrelated symlink before delivery proceeds.
## Lifecycle Management
| Status | Location | Retention | Cleanup |
|--------|----------|-----------|---------|
| active | `.cache/workflows/active/` | In progress | Move to archive on completion |
| archive | `.cache/workflows/archive/YYYY-MM/` | 90 days | `gitflow workflow cleanup --older-than 90` |
## CLI Integration
```bash
gitflow workflow create --title "<issue_title>" --mode <full|fast> # 创建合同(自动分配当日不重复 ID)
gitflow workflow list # List active workflows
gitflow workflow status <workflow_id> # View contract details
gitflow workflow archive <workflow_id> # Archive completed workflow(目标已存在时拒绝覆盖)
gitflow workflow cleanup --older-than 90 # Clean up expired archives
```
## Branch Finish Operations
Phase 4 Step 4 commands. All operations are local-only (no push).
### Detect PR Merge Status
```bash
gf pr view # parse "merged" field from output
```
### Execute Branch Cleanup (after user confirmation)
```bash
# Return to main working tree
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
# Switch to base branch and update
git checkout "$BASE_BRANCH"
git pull origin "$BASE_BRANCH"
# Delete feature branch (safe: refuses if unmerged)
git branch -d "$FEATURE_BRANCH"
# Remove worktree
git worktree remove "$WORKTREE_PATH"
git worktree prune
# Clean stale remote tracking refs
git fetch --prune origin
```
### Skip Conditions
| Condition | Action |
|-----------|--------|
| `base_branch` empty/missing | Skip entire Branch Finish |
| `worktree_path` empty | Skip worktree removal, still attempt branch delete |
| PR not merged | Skip all cleanup, set `branch_cleaned = false` |
| `git branch -d` fails | Warn, preserve branch, continue to archive |
| User declines confirmation | Set `branch_cleaned = false`, continue to archive |
## Dual-Source Skill Resolution (Issue #141)
gf-workflow runs on ONE external skill source: `superpowers` or `mattpocock/skills`.
SKILL.md phase steps use role aliases; actual names resolve from the tables below.
**This section is the single point of maintenance** — upstream renames are fixed here only.
### Sentinels (shared authoritative definition)
Mirrored by the Rust constants in `apps/cli/src/commands/skills.rs`
(`SUPERPOWERS_PLUGIN_PREFIX` / `MATTPOCOCK_PLUGIN_PREFIX` /
`SUPERPOWERS_BARE_SENTINELS` / `MATTPOCOCK_BARE_SENTINELS`) used by install-time
Step 0. Change both sides together.
| Source | Model-invoked sentinel | User-invoked sentinel |
|---|---|---|
| superpowers | `superpowers:brainstorming`, or bare `brainstorming` + `writing-plans` | — |
| mattpocock | `mattpocock-skills:grilling`, or bare `grilling` | `to-spec` |
Model-invoked sentinels must appear in the session available-skills list. User-invoked
sentinels normally do not appear there because their frontmatter sets
`disable-model-invocation: true`; locate them only under skill roots declared by the
environment and verify both the frontmatter `name` and that flag. They also count if the
session explicitly exposes them. A partial hit counts as absent; report each missing
sentinel.
### Detection & Recording
- Mechanism: at Bootstrap, BEFORE the contract exists, introspect the session
available-skills list for model-invoked sentinels. For explicit user-invoked sentinels,
inspect only the environment-declared skill roots; this scoped lookup is authoritative
because those skills are intentionally hidden from model invocation. All other
filesystem probing remains diagnostics-only.
- Both present → ask the user which source this workflow uses (no default priority).
- Neither present → ask: continue inline (`skill_source: "inline"`) or abort (no contract).
- Record after contract creation:
```bash
jq --arg src "<superpowers|mattpocock|inline>" \
'.skill_source = $src | .updated_at = (now | todate)' \
".cache/workflows/active/${WORKFLOW_ID}.json" > tmp && mv tmp ".cache/workflows/active/${WORKFLOW_ID}.json"
```
- Resume: reuse `skill_source` from the contract; re-verify sentinels are still present;
if vanished, re-run the neither-present prompt.
### Dual-Source Mapping Table
| Role alias | superpowers | mattpocock | Invocation form |
|---|---|---|---|
| Clarification | `brainstorming` | `grilling` | model-invoked / model-invoked |
| Spec | (merged into brainstorming design doc) | ✋ `/to-spec` (local-only) | — / user-invoked |
| Issue resolution | Reuse a verified open Issue; otherwise `gf-issue-create` | Same; `/to-spec` stays local-only | gf CLI |
| Issue review | `gf-issue-review` | `gf-issue-review` (unchanged) | gf CLI |
| Planning | `writing-plans` | ✋ `/to-tickets` | model-invoked / user-invoked |
| Quality gate | `gf-quality` | `gf-quality` (unchanged) | gf CLI |
| Execution engine | `subagent-driven-development` (same-session) / `executing-plans` (new window) — per GO gate | ✋ `/implement` per ticket (internal `/tdd` mandatory) | per mode / user-invoked |
| Execution review | SDD built-in two-stage review | `code-review` (driven inside `/implement`) | — |
| Delivery review | `gf-review` | `gf-review` (unchanged; no extra code-review pass) | gf skill |
| Triage (full mode) | `gf-issue-triage` | `gf-issue-triage` (unchanged; mattpocock `triage` NOT adopted) | gf skill |
| Pipeline analysis | `gf-pipeline-analyzer` — optional, asked at Phase 4 entry, default yes (all modes) | (unchanged) | gf skill |
### Source Branch Semantics
**Invariants (both sources):** four-phase state machine, three gates, contract evidence
semantics, all `gf-*` steps, mandatory TDD + code review, mode matrix (full/standard/fast).
**mattpocock path:**
- **Prerequisite:** `docs/agents/issue-tracker.md` exists (`setup-mat-pocock-skills`
output). Missing → ask the user: run `setup-mat-pocock-skills` now (one-time) or abort.
- **Phase 1:** `grilling` (auto) → ✋ PAUSE prompting:
> 请运行 `/to-spec`:综合当前对话撰写 spec,写入本地文件
> `docs/specs/<workflow-id>-spec.md`。**只写本地,不发布 tracker、不打标签。**
Verify the local spec exists afterwards. **Fallback** (constraint failed / skill refused):
the orchestrator writes the design doc itself from the grilling record, bypassing `to-spec`.
Then reuse the verified open Issue if one covers the task; otherwise
`gf-issue-create` creates one. `/to-spec` never publishes to the tracker.
`gf-issue-review` reviews the resolved Issue. Evidence: `issue_url`,
`comment_id`, `design_doc_path`.
- **Phase 2:** ✋ PAUSE prompting `/to-tickets` with the Phase 1 spec reference.
`to-tickets` publishes tickets per the configured tracker (local `.scratch/<feature>/issues/`
files or real tracker issues) and includes its own breakdown quiz. Its rule "do NOT close
or modify any parent issue" is compatible with gf-workflow. Orchestrator records
`ticket_refs` (paths/URLs) and sets `spec_path` = the Phase 1 spec file. Gate 2→3
presents the ticket list + blocking edges.
- **Phase 3:** worktree per chosen execution mode; per ticket in dependency order
(frontier): ✋ PAUSE → user runs `/implement` (internal `/tdd` + `/code-review` + commit);
suggest `/clear` between tickets (context recovery via contract + ticket files).
`gf-pr-create` with `Closes #<issue>`, then `make test`.
- **Phase 4:** identical to superpowers ([pipeline ∥ triage[full] ∥ gf-review] →
dogfooding[full] → Branch Finish → archive). `code-review` already ran inside `/implement`.
- **Evidence mapping:** `design_doc_path` ← local spec file; `spec_path` ← same spec file
(what `to-tickets` consumed); `ticket_refs` ← ticket paths/URLs.
**inline source (both absent, user chose to continue):** orchestrator performs each phase
inline — self-interview, self-written design doc/plan, TDD loop with a review subagent.
Evidence fields follow the superpowers shape. Degraded but explicit.
### Phase 3 Execution Modes (GO gate)
Gate 2→3 = plan approval + execution-mode choice. Same-session execution left the default
menu (SDD objection: approving a plan ≠ authorizing hours of autonomous subagent fan-out;
same-session SDD hijacks the conversation once started).
| Mode | Description | Availability |
|---|---|---|
| ① Manual new window ⭐default | Print opening guidance: worktree path (or creation command) + contract recovery command (`gf workflow status <id>` + plan doc path) + **Worktree Preflight steps verbatim**; new window creates branch/worktree itself and runs `executing-plans` (superpowers) or per-ticket `/implement` (mattpocock); user reports back, orchestrator verifies evidence | both sources |
| ② Same-session | Current behavior: orchestrator creates worktree and drives the engine inline | explicit request only |
**Why no background-executor mode:** an earlier mode dispatching a harness-isolated,
non-interactive executor (`isolation: worktree` + `run_in_background`) was removed after
Issue #325 confirmed two structural defects that cannot be fixed by documentation alone:
(1) such an isolated executor's git operations are hard-restricted to its own
harness-managed worktree — it cannot target `.worktree/<branch-name>`; (2) that
harness-managed worktree forks from `origin/<default-branch>`, not from the orchestrator's
`base_branch`, so any resulting branch would silently miss `base_branch`-only commits.
See `specs/gf-workflow-mode1-removal-design.md` for the investigation.
Quality compensation: `executing-plans` (light path) lacks per-task review → gates
compensate (`make test` before PR + Phase 4 `gf-review`). SDD carries per-task review built in.
### Phase 3 Execution Error Classification (Issue #336)
`skills/gf-workflow/SKILL.md`'s top-level Error Handling table covers orchestrator-level
failures (missing contract, gate check failed). It does not cover failures that occur
**during Phase 3 execution** (the implementation engine actually running build/test/lint
commands, merging, or queuing a merge). This table fills that gap.
**Two categories were adapted, not ported verbatim, from `smallnest/goal-workflow`'s
`loop-it` skill** — this repo's semantics differ:
- `merge_conflict`: Phase 3 Step 4's local-merge path already aborts and hands back to the
user on conflict (`git merge --abort`, branch/worktree untouched). The table below keeps
that behavior — zero automatic retries — rather than inventing a new auto-resolve loop.
- `ci`: Phase 3 Step 6 queues the merge (`gf pr merge --auto`) against a specific SHA that
has already passed checks. Pushing a new commit to that branch after queuing does **not**
get carried into the queued check (verified empirically) — so `ci` failures can never be
"fixed" by pushing more commits onto the queued branch. A fix requires a fresh commit and
a fresh queue entry, which restarts at Step 2, not a retry of Step 6.
| Category | Trigger | Recovery | Retry Cap |
|---|---|---|---|
| `build` | Compile/build failure | Fix code, rebuild | 3 |
| `test` | Test failure | Fix code or test, rerun | 3 |
| `lint` | `cargo clippy` / `cargo fmt` (or per-language equivalent) failure | Fix, rerun `make lint` | 3 |
| `merge_conflict` | `git merge` conflict (Phase 3 Step 4, local-merge path) | `git merge --abort`; leave `branch`/worktree untouched; escalate to user immediately — no automatic retry. User resolves manually, then Step 4 is re-run as a fresh attempt (not counted against this cap) | 0 |
| `ci` | Required check fails after the merge queue (Phase 3 Step 6, PR path) | Never push a new commit to the already-queued branch. `gf` has no re-run command for an existing pipeline run — ✋ PAUSE and ask the user to rule out flakiness via the platform's own re-run action (e.g. GitHub Actions "Re-run failed jobs", or that platform's native CLI); if it still fails, a real fix requires a new commit + a fresh queue entry — that restarts at Step 2, it is not a retry of Step 6 | 1 (one user-triggered same-SHA re-run only) |
| `auth` | `gf auth status` failure / API 401/403 | No retry — escalate to user immediately (`auth login` is a human action) | 0 |
| `rate_limit` | API 429 / platform throttling | No retry — escalate to user immediately (waiting or rotating credentials is a human decision) | 0 |
| `network` | Transient network error (timeout, connection reset) | Retry with backoff | 3 |
| `issue_unclear` | Execution engine hits a requirement ambiguity it cannot resolve | Not a retryable error — pause and ask the user for clarification; never guess. Each clarification round is a fresh attempt, not counted against a retry cap | 0 |
| `unknown` | Uncategorized error | Capture the full error, retry once conservatively; escalate if it recurs | 1 |
**Escalation contract.** When a category's retry cap is reached (or immediately, for the
four 0-cap categories — `merge_conflict`, `auth`, `rate_limit`, `issue_unclear`): stop
retrying automatically, show the user the error category, every recovery attempt tried so
far with its outcome, and the retry count, then wait for the user's decision (continue /
change strategy / abort the task). Never silently give up and never silently switch
delivery mode (e.g. falling back from local-merge to PR) as a substitute for asking.
### Worktree Location Convention (Issue #146)
All gf-workflow worktrees are created at a **fixed path**: `.worktree/<branch-name>`.
- Branch name format: `feat/<issue-number>-<short-description>`
- Full path example: `.worktree/feat/141-dual-skill-sources`
- `.worktree/` is in `.gitignore` → worktrees are automatically excluded from version control
- Phase 4 Branch Finish cleanup uses this predictable path for `git worktree remove`
- New-window executors create worktrees at this same location
## Workflow Recommendation (Issue #383)
At Bootstrap, make a short, reviewed JSON input with `title`, `summary` (at most 512 bytes), `labels`, and optional `userMode`; store it under ignored `.cache/workflows/`. Include only the task description and allowed issue labels. Do not include logs, environment variables, credentials, private URLs, or full repository content. Run `gf workflow recommend --input <path>` for deterministic advice. If the user explicitly opts into Jev and `GF_DECISION_PROVIDER=jev` is configured, add `--live`; otherwise no provider call occurs. A saved typed `DecisionResponse` can be replayed with `--response <path>` without a provider. The command emits `ruleMode`, optional `suggestedMode`, `effectiveMode`, `status`, `riskFlags`, and `candidatePhases`. See `docs/workflow-recommendation.md` for the schema and examples.
The command does not create a contract or change a gate. Use `effectiveMode` only as the rule or explicit user choice when creating the contract. Display model conflicts and low confidence for review; do not treat `suggestedMode`, `riskFlags`, or `suggestedSkills` as permission to run or skip steps. If the command is unavailable in an older `gf` binary, apply the deterministic Mode Auto-Detection table in `SKILL.md`.