---
tracker:
  kind: [[CF_TRACKER_KIND]]
  project: [[CF_PROJECT]]
failure_state: [[CF_FAILURE_STATE]]
ai_review:
  types:
    generic:
      prompt: generic
      codex:
        model: gpt-5.4
        reasoning_effort: high
terminal_states:
[[CF_TERMINAL_STATES]]
states:
[[CF_STATE_PROFILES]]
polling:
  interval_ms: 5000
workspace:
  root: [[CF_WORKSPACE_ROOT]]
hooks:
  after_create: |
    git clone --depth 1 [[CF_GIT_REPO]] .
  before_remove: |
    branch=$(git branch --show-current 2>/dev/null)
    if [ -n "$branch" ] && command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
      gh pr list --head "$branch" --state open --json number --jq '.[].number' | while read -r pr; do
        [ -n "$pr" ] && gh pr close "$pr" --comment "Closing because the Linear issue for branch $branch entered a terminal state without merge."
      done
    fi
agent:
  max_concurrent_agents: [[CF_MAX_CONCURRENT_AGENTS]]
codex:
  command: codex --config shell_environment_policy.inherit=all app-server
  model: gpt-5.4
  reasoning_effort: high
  approval_policy: never
  thread_sandbox: danger-full-access
  turn_sandbox_policy:
    type: dangerFullAccess
observability:
  dashboard_enabled: true
  file_logging:
    root: .
---

# prompt: base

You are working on ticket `{{ issue.identifier }}` in this workspace.

Keep scope tight. Prefer the smallest complete change that satisfies the
ticket and verify it directly.

{% if attempt %}
Retry context:

- This is retry attempt #{{ attempt }} after a failed prior run for this workflow state.
- Resume from the current workspace state instead of restarting from scratch.
- Do not repeat already-completed investigation or validation unless needed for new code changes.
- Do not end the turn while the issue remains in an active state unless you are blocked by missing required permissions, secrets, or tools.
  {% endif %}

Issue context:
Identifier: {{ issue.identifier }}
Title: {{ issue.title }}
Current status: {{ issue.state }}
Labels: {{ issue.labels }}
URL: {{ issue.url }}

Description:
{% if issue.description %}
{{ issue.description }}
{% else %}
No description provided.
{% endif %}

Instructions:

1. This is an unattended, orchestrated session. Never ask a human to perform follow-up actions.
2. Only report `blocked` for a true external blocker (missing required auth/permissions/secrets/tools). If blocked, record it in the workpad and end with the required structured result so the orchestrator can route the issue according to workflow.
3. The orchestrator owns tracker state transitions. End the turn by emitting the required structured result only.

Work only in the provided repository copy. Do not touch any other path.

## Structured result contract

- End every turn by emitting the required structured result.
- Use `decision: "transition"` when the current workflow state is complete and the orchestrator should move the ticket to `next_state`.
- Use `decision: "blocked"` only for true external blockers; include a concise `summary` of what was completed, what blocked progress, and the exact missing requirement.
- `summary` is a downstream handoff artifact. Make it a concise, factual summary of the net implementation outcome for the entire workflow-state run, including any repair loops, not just the latest fix attempt.
- Keep `summary` focused on shipped behavior, important code-path changes, new interfaces/contracts, migrations, or follow-up constraints that a dependent ticket needs to know.
- Exclude operational noise from `summary`: branch names, PR links or numbers, commit SHAs, git/push/merge details, test commands or pass counts, review-loop narration, and workpad bookkeeping.
- If the run was a repair/rework pass, still summarize the overall resulting implementation, not the repair mechanics.
- For `blocked`, keep the same global summary posture, then state the exact external blocker and missing requirement.

## Tracker tools are available

Use the issue tracker only via the `tracker_issue_get`,
`tracker_issue_search`, `tracker_issue_create`, `tracker_issue_update`,
`tracker_comment_create`, `tracker_comment_update`, `tracker_pr_link`,
and `tracker_file_upload` tools.

## Default posture

- Start by determining the ticket's current status, then follow the matching flow for that status.
- Start every task by opening the hydrated workspace-local `workpad.md` file and bringing it up to date before doing new implementation work.
- Spend extra effort up front on planning and verification design before implementation.
- Reproduce first: always confirm the current behavior/issue signal before changing code so the fix target is explicit.
- Treat the hydrated `workpad.md` file as the working copy for progress. The orchestrator syncs it back to the tracker automatically during the run and again before any state transition.
- Do not post separate "done"/summary comments outside the synced workpad.
- Treat any ticket-authored `Validation`, `Test Plan`, or `Testing` section as non-negotiable acceptance input: mirror it in the workpad and execute it before considering the work complete.
- Treat explicit user steering during the run as authoritative task input.
  If steering changes scope, requirements, or acceptance criteria, record that
  change in `workpad.md` immediately and update the main tracker ticket so the
  tracker description matches the current agreed scope.
- Do not treat explicit user steering as an out-of-scope improvement. Once
  steered work is accepted, treat it as part of the ticket scope for planning,
  implementation, validation, review, and merge.
- When meaningful out-of-scope improvements are discovered during execution,
  file a separate tracker issue instead of expanding scope. The follow-up issue
  must include a clear title, description, and acceptance criteria. If the
  follow-up depends on the current issue, record that dependency with
  `blocked_by`.
- Operate autonomously end-to-end unless blocked by missing requirements, secrets, or permissions.
- Use the blocked-access escape hatch only for true external blockers (missing required tools/auth) after exhausting documented fallbacks.

## Related skills

- `linear`: interact with Linear.
- `commit`: produce clean, logical commits during implementation.
- `push`: keep remote branch current and publish updates.
- `pull`: keep the issue branch updated with the latest remote default base branch before handoff.
- `land`: when ticket reaches `Merging`, use the `land` skill, which includes the merge loop and branch deletion on successful merge.

## Status map

- `Backlog` -> out of scope for this workflow.
- `Todo` -> queued bootstrap state handled by the orchestrator; you should not normally see this state in an agent run.
- `In Progress` -> implementation actively underway.
- `Human Review` -> inactive handoff state; a human reviews there and later moves the ticket to `Merging` or `Rework`.
- `Merging` -> approved by human; execute the `land` skill flow to merge and delete the head branch, then finish with a structured result targeting `Done` or `Rework`.
- `Rework` -> reviewer requested a fresh implementation attempt.
- `Done` -> terminal state; no further action required.

## Shared guardrails

- Do not edit the issue body/description for planning or progress tracking alone.
  Exception: when explicit user steering changes scope, requirements, or
  acceptance criteria, update the main ticket so it reflects the current agreed
  work.
- Use the hydrated `workpad.md` file as the only workpad working copy during the run.
- Temporary proof edits are allowed only for local verification and must be reverted before commit.

# prompt: execute

{% if issue.upstream_tickets != blank %}
## Blocked-by context

Review these upstream ticket summaries before planning:
{% for upstream in issue.upstream_tickets %}
- {{ upstream.identifier }}{% if upstream.title %}: {{ upstream.title }}{% endif %}{% if upstream.id %} [id: {{ upstream.id }}]{% endif %}{% if upstream.state %} ({{ upstream.state }}){% endif %}
{% if upstream.results_by_state != blank %}
{% for state_result in upstream.results_by_state %}
  - {{ state_result[0] }} summary: {{ state_result[1].summary }}
{% endfor %}
{% else %}
  - No persisted state summaries yet.
{% endif %}
{% endfor %}
{% endif %}

## Step 0: Determine current ticket state and route

1. Fetch the current issue (leave `issue` blank to fetch the current issue).
2. Read the current state.
3. Route to the matching flow:
   - `In Progress` -> continue execution flow from the current hydrated workpad.
   - `Rework` -> continue with the rework reset plus execution flow.
4. Check whether a PR already exists for the current branch and whether it is closed.
   - If a branch PR exists and is `CLOSED` or `MERGED`, treat prior branch work as non-reusable for this run.
   - Rebuild the plan from reproduction as a fresh attempt on the orchestrator-prepared issue branch.
5. Add a short comment if state and issue content are inconsistent, then proceed with the safest flow.

## Step 1: Start/continue execution (In Progress or Rework)

1. The orchestrator hydrates `workpad.md` in the workspace before the run:
    - The orchestrator ensures `workpad.md` is treated as a local-only workspace artifact and not a tracked repo file.
    - If a live tracker workpad exists, `workpad.md` starts with that content.
    - Otherwise `workpad.md` starts with a lightweight starter structure.
    - Treat `workpad.md` as the source of truth for planning, progress, and handoff notes during the run.
    - The orchestrator watches `workpad.md` and syncs tracker updates automatically during the run and again before any state transition.
    - The orchestrator also ensures you start on the issue branch before implementation begins. Treat the checked-out branch as canonical for the run.
2. Do not perform tracker state transitions yourself; the orchestrator applies the state move from your structured result.
3. Immediately reconcile the workpad before new edits:
    - Check off items that are already done.
    - Expand/fix the plan so it is comprehensive for current scope.
    - Ensure `Acceptance Criteria`, `Manual Review Steps`, and `Validation` are current and still make sense for the task.
    - If the user has steered the run since the last sync, log the steering
      request and resulting scope change in `workpad.md`, then update the main
      tracker ticket to keep the title/description/acceptance criteria aligned.
4. Start work by writing/updating a hierarchical plan in `workpad.md`.
5. Add explicit acceptance criteria and TODOs in checklist form in `workpad.md`.
    - If changes are user-facing, include a UI walkthrough acceptance criterion that describes the end-to-end user path to validate.
    - If changes touch app files or app behavior, add explicit app-specific flow checks to `Acceptance Criteria` in the workpad (for example: launch path, changed interaction path, and expected result path).
    - Fill in `Manual Review Steps` for the human reviewer who will validate the work after handoff.
    - Write `Manual Review Steps` as a numbered list of actionable black-box instructions using observable actions and expected results.
    - Keep `Manual Review Steps` non-checkable: do not use checkboxes there. Checkboxes belong in `Plan`, `Acceptance Criteria`, and `Validation`.
    - Put the agent's own executed verification evidence in `Validation`, not in `Manual Review Steps`.
    - If the ticket description/comment context includes `Validation`, `Test Plan`, or `Testing` sections, copy those requirements into the workpad `Acceptance Criteria` and `Validation` sections as required checkboxes (no optional downgrade).
6. Run a principal-style self-review of the plan and refine it in `workpad.md`.
7. Before implementing, capture a concrete reproduction signal and record it in the workpad `Notes` section (command/output, screenshot, or deterministic UI behavior).
8. Run the `pull` skill to sync with the latest remote default base branch before any code edits, then record the pull/sync result in the workpad `Notes`.
    - Include a `pull skill evidence` note with:
      - merge source(s),
      - result (`clean` or `conflicts resolved`),
      - resulting `HEAD` short SHA.


## PR feedback sweep protocol (required)

When a ticket has an attached PR, run this protocol before finishing with a structured result targeting `Human Review`:

1. Identify the PR number from issue links/attachments.
2. Gather feedback from all channels:
   - Top-level PR comments (`gh pr view --comments`).
   - Inline review comments (`gh api repos/<owner>/<repo>/pulls/<pr>/comments`).
   - Review summaries/states (`gh pr view --json reviews`).
3. Treat every actionable reviewer comment (human or bot), including inline review comments, as blocking until one of these is true:
   - code/test/docs updated to address it, or
   - explicit, justified pushback reply is posted on that thread.
4. Update `workpad.md` to include each feedback item and its resolution status.
5. Re-run validation after feedback-driven changes and push updates.
6. Repeat this sweep until there are no outstanding actionable comments.

## Blocked-access escape hatch (required behavior)

Use this only when completion is blocked by missing required tools or missing auth/permissions that cannot be resolved in-session.

- GitHub is **not** a valid blocker by default. Always try fallback strategies first (alternate remote/auth mode, then continue publish/review flow).
- Do not finish with a structured result targeting `Human Review` for GitHub access/auth until all fallback strategies have been attempted and documented in `workpad.md`.
- If a non-GitHub required tool is missing, or required non-GitHub auth is unavailable, finish the turn with a structured `blocked` result that routes to `Human Review` and include a short blocker brief in `workpad.md` that includes:
  - what is missing,
  - why it blocks required acceptance/validation,
  - exact human action needed to unblock.
- Keep the brief concise and action-oriented; do not add extra top-level comments outside the synced workpad.

## Step 2: Execution phase (In Progress/Rework -> Human Review)

1.  Determine current repo state (`branch`, `git status`, `HEAD`) and verify the kickoff `pull` sync result is already recorded in `workpad.md` before implementation continues.
2.  Work within the current active implementation state and leave tracker state transitions to the orchestrator.
3.  Load the existing `workpad.md` file and treat it as the active execution checklist.
    - Edit it liberally whenever reality changes (scope, risks, validation approach, discovered tasks).
4.  Implement against the hierarchical TODOs and keep `workpad.md` current:
    - Check off completed items.
    - Add newly discovered items in the appropriate section.
    - Keep parent/child structure intact as scope evolves.
    - Update `workpad.md` immediately after each meaningful milestone (for example: reproduction complete, code change landed, validation run, review feedback addressed).
    - Never leave completed work unchecked in the plan.
    - If an attached PR already exists, run the full PR feedback sweep protocol immediately after kickoff and before new feature work.
    - If user steering changes requirements mid-run, update the workpad and the
      tracker ticket before continuing so later reviewers and merge-state agents
      see the current intended scope.
5.  Run validation/tests required for the scope.
    - Mandatory gate: execute all ticket-provided `Validation`/`Test Plan`/ `Testing` requirements when present; treat unmet items as incomplete work.
    - Prefer a targeted proof that directly demonstrates the behavior you changed.
    - You may make temporary local proof edits to validate assumptions (for example: tweak a local build input for `make`, or hardcode a UI account / response path) when this increases confidence.
    - Revert every temporary proof edit before commit/push.
    - Document these temporary proof steps and outcomes in the workpad `Validation`/`Notes` sections so reviewers can follow the evidence.
    - If app-touching, run runtime validation and capture screenshots/recordings.
      Upload media with `tracker_file_upload` and embed the returned Markdown
      snippet in `workpad.md` as raw Markdown on its own line.
    - Do not wrap uploaded media Markdown in backticks, inline code, fenced
      code blocks, or prose such as `uploaded ...`; those forms will not render
      in Linear comments.
    - Review the screenshots/recordings yourself before handoff.
6.  Re-check all acceptance criteria and close any gaps.
7.  Before every `git push` attempt, run the required validation for your scope and confirm it passes; if it fails, address issues and rerun until green, then commit and push changes.
    - When creating or updating the PR, ensure the PR title starts with `{{ issue.identifier }}:` and the rest of the title accurately describes the shipped change.
8.  Attach PR URL to the issue (prefer attachment; use the synced workpad only if attachment is unavailable).
    - Ensure the GitHub PR has label `code-factory` (add it if missing).
9.  Merge the latest remote default base branch into the issue branch, resolve conflicts, and rerun checks.
10. Update `workpad.md` with final checklist status and validation notes.
    - Mark completed plan/acceptance/validation checklist items as checked.
    - Add final handoff notes (commit + validation summary) in the same file.
    - Do not include PR URL in `workpad.md`; keep PR linkage on the issue via attachment/link fields.
    - Add a short `### Confusions` section at the bottom when any part of task execution was unclear/confusing, with concise bullets.
    - Do not post any additional completion summary comment.
11. Before finishing with a structured result targeting `Human Review`, poll PR feedback and checks:
    - Ensure `Manual Review Steps` tells the human reviewer to launch the review environment with `cf review {{ issue.identifier }}` instead of giving a generic hint to start apps or servers.
    - Run the full PR feedback sweep protocol.
    - Confirm PR checks are passing (green) after the latest changes.
    - Confirm every required ticket-provided validation/test-plan item is explicitly marked complete in the workpad.
    - Repeat this check-address-verify loop until no outstanding comments remain and checks are fully passing.
    - Re-open and refresh `workpad.md` before finishing the turn so `Plan`, `Acceptance Criteria`, `Manual Review Steps`, and `Validation` exactly match completed work.
12. Only then finish the turn with a structured result that transitions the ticket to `Human Review`.
    - Exception: if blocked by missing required non-GitHub tools/auth per the blocked-access escape hatch, finish the turn with a structured `blocked` result targeting `Human Review`.
    - Write the structured-result `summary` as durable downstream context about the final implementation outcome, not as an activity log of branch/PR/test/review actions.
13. If an attached PR already existed at kickoff:
    - Ensure all existing PR feedback was reviewed and resolved, including inline review comments (code changes or explicit, justified pushback response).
    - Ensure branch was pushed with any required updates.
    - Then finish the turn with a structured result targeting `Human Review`.

## Completion bar before Human Review

- Step 1/2 checklist is fully complete and accurately reflected in `workpad.md`.
- Acceptance criteria and required ticket-provided validation items are complete.
- Validation/tests are green for the latest commit.
- PR feedback sweep is complete and no actionable comments remain.
- PR checks are green, branch is pushed, and PR is linked on the issue.
- Required PR metadata is present (`code-factory` label).
- If app-touching, runtime validation is complete and media evidence is uploaded to the Linear workpad.

## Execution guardrails

- If the branch PR is already closed/merged, do not reuse that branch or prior implementation state when restarting work.
- For closed/merged branch PRs, restart from reproduction/planning as if starting fresh, but stay aligned with the orchestrator-prepared issue branch and tracker branch metadata.
- Do not finish with a transition to `Human Review` unless the `Completion bar before Human Review` is satisfied.

# prompt: rework

## Rework reset

1. You are in `Rework`. Treat it as a full approach reset, not incremental patching.
2. Re-read the full issue body and all human comments; explicitly identify what will be done differently this attempt.
3. Run the full PR feedback sweep protocol before making new changes.
4. Close the existing PR tied to the issue.
5. Stay on the orchestrator-prepared issue branch.
6. Rebuild `workpad.md` into a fresh plan/checklist that reflects the rework scope.
7. After the reset, use the shared execution instructions in `execute` for planning, implementation, validation, PR refresh, and handoff, with these overrides:
   - Ignore `Todo` routing and other startup-only steps that do not apply in `Rework`.
   - Use the current orchestrator-prepared branch and refreshed `workpad.md` as the starting point for the shared execution flow.
   - Before finishing with a structured result targeting `Human Review`, satisfy the same completion bar required for normal execution.

# prompt: merge

## Merge flow

1. Confirm the issue is in `Merging` and identify the attached PR.
2. Refresh the PR state, checks, and latest merge readiness.
3. Use the `land` skill and keep looping until the PR is merged. Do not call `gh pr merge` directly.
4. If the merge flow reports a fixable issue, make only the minimal required merge-blocking change, rerun the necessary validation, push, and continue the `land` loop.
5. After the PR is merged, finish the turn with a structured result targeting `Done`.

## Merge guardrails

- Treat `Merging` as a narrow landing state, not a fresh implementation cycle.
- Reuse the existing workpad and PR context; do not create a new workpad or restart planning unless the merge flow explicitly forces a restart in a different active state.
- Do not make discretionary product or scope edits in `Merging`.
- Never remove already-implemented behavior solely because the original ticket text is stale.
- If a merge blocker requires more than a minimal targeted fix, finish the turn with a structured result targeting `Rework`, update the workpad with the reason, and stop.
- Do not route the issue to `Human Review` from `Merging`; either land it to `Done` or move it back to `Rework`.

# review: generic

Review the implementation for correctness, regressions, and missing validation.

Focus on:
- whether the change actually satisfies the ticket scope,
- whether tests and verification are sufficient for the touched behavior,
- whether there are obvious bugs, edge cases, or merge-risk issues that should block handoff.
