flame-harness-resume

name	flame-harness-resume
description	Resume a paused flame-harness run based on pause_reason (rate_limit waits; manual_action confirms with user; error reports).
argument-hint
allowed-tools	["Read","Write","Edit","Bash","AskUserQuestion","Skill"]

flame-harness-resume

Resume handler for the flutter-flame-harness pipeline. Reads state.md, branches on pause_reason, and re-dispatches the next phase skill when ready to continue.

All file schemas (state.md, pipeline-log.md) and state transition rules (including the requirement that pause_reason is cleared to "" when status is restored to running) are defined in docs/harness-protocol.md — refer to §2 (state.md schema) and §7 (state transition rules) as the single source of truth. Do not redefine schemas here.

---

Input

Read docs/harness/state.md per the schema in docs/harness-protocol.md §2. If state.md does not exist, abort with:

flame-harness-resume: nothing to resume — docs/harness/state.md not found.
Run /flame-harness <idea> to start a new pipeline.

Extract:

• status — expected paused; if running or completed, print a note and exit (nothing to resume).
• pause_reason — rate_limit | manual_action | error
• next_role — role to dispatch after resuming
• resume_attempts — integer; will be incremented on successful resume
• current_phase, updated_at — for logging

If status is running:

flame-harness-resume: pipeline is already running (status: running, next_role: <next_role>).
No resume needed.

If status is completed:

flame-harness-resume: pipeline is already completed. Nothing to resume.

---

Branch on pause_reason

rate_limit

pause_reason: rate_limit means the pipeline hit an API rate limit and paused automatically.

Procedure:

1. Print:

   Pipeline paused due to rate limit (rate_limit).
   Checking whether the rate-limit window has passed...
   

2. Read updated_at from state.md. Calculate elapsed time since that timestamp using Bash (date command). If elapsed time is less than 60 seconds, print a warning:

   Warning: only <N> seconds have elapsed since the pause. The rate-limit window may not
   have passed yet. Proceeding anyway — if another rate limit is hit, the pipeline will
   pause again.
   

3. Proceed to Resume execution below.

manual_action

pause_reason: manual_action means the pipeline requires a manual step from the user before it can continue (e.g. playing/approving the built game at the post-QA review gate, completing App Store / Play Console submission steps, uploading a keystore, or configuring a device). The specific action is recorded in the pause event row of pipeline-log.md.

Procedure:

1. Read docs/harness/pipeline-log.md per docs/harness-protocol.md §6. Find the most recent pause event row to extract the details string describing what manual action was needed. If the log is unavailable, use a generic prompt.

2. Use AskUserQuestion to confirm the user has completed the required steps:

   The pipeline was paused for a manual action.
   Last recorded reason: <details from pipeline-log, or "see docs/harness/pipeline-log.md">
   
   Have you completed the required steps? (yes / no / describe what's pending)
   

3. If the user answers no or describes pending work:

   • Print a summary of what they said.
   • Abort: do NOT resume. Exit with:

     flame-harness-resume: manual action not yet complete. Run /flame-harness-resume again
     when ready.
     

4. If the user answers yes:

   • Proceed to Resume execution below.

error

pause_reason: error means the pipeline encountered an unrecoverable error in a phase skill.

Procedure:

1. Read docs/harness/pipeline-log.md per docs/harness-protocol.md §6. Find the most recent error event row to extract the error details.

2. Print a clear error report:

   Pipeline paused due to an error.
   Phase     : <current_phase>
   Next role : <next_role>
   Error     : <details from pipeline-log, or "see docs/harness/pipeline-log.md">
   
   You must investigate and fix the error before resuming.
   Common fixes:
     - If it is a Flutter/Dart compile error, fix the code and run `flutter analyze`.
     - If it is a missing file, create or restore it.
     - If it is a credential error, check docs/harness/config.md and the credentials_dir.
   

3. Use AskUserQuestion:

   Have you resolved the error and are ready to retry? (yes / no)
   

4. If the user answers no:

   • Abort: do NOT resume. Exit with:

     flame-harness-resume: error not yet resolved. Run /flame-harness-resume again when fixed.
     

5. If the user answers yes:

   • Proceed to Resume execution below.

Unknown pause_reason

If pause_reason is empty or an unrecognised value, print:

flame-harness-resume: unexpected pause_reason "<value>" in state.md.
Expected one of: rate_limit, manual_action, error.
Please inspect docs/harness/state.md manually and correct it before resuming.

Then abort without modifying any files.

---

Resume execution

Reached only after the appropriate branch above confirms it is safe to continue.

Per docs/harness-protocol.md §7 rule 4: when status is set back to running, resume_attempts must be incremented, and per §7 rule 8: pause_reason must be cleared to "" by this skill.

1. Update state.md

Use Edit to update docs/harness/state.md with the following field changes (leave all other keys unchanged):

status: running
pause_reason: ""
resume_attempts: <previous_value + 1>
updated_at: "<ISO-8601 UTC now>"

Both status: running and pause_reason: "" must be written in the same Edit call (atomic per docs/harness-protocol.md §7 rule 1).

2. Append to pipeline-log.md

Append one row to docs/harness/pipeline-log.md per the schema in docs/harness-protocol.md §6:

| <ISO-8601 UTC now> | resume | <current_phase> | resume_attempts=<new_value>; was paused for <pause_reason> |

3. Dispatch next_role

Read next_role from the (now-updated) state.md and dispatch:

Skill("flame-harness-<next_role>")

Valid next_role values are listed in the transition table in docs/harness-protocol.md §7. admob is a normal dispatchable role and is handled like any other next_role — dispatch Skill("flame-harness-admob") without any special boundary check.

If next_role is generator, the generator resumes safely on its own: it reads checkpoint from state.md (§2) and skips the sub-phases whose HARD GATE already passed, so resume needs no special handling here — just dispatch it.

If next_role is empty or unknown, abort with:

flame-harness-resume: cannot dispatch — next_role is "<value>".
Inspect docs/harness/state.md and set a valid next_role before retrying.

---

Error handling

• If state.md becomes unreadable mid-execution (e.g. concurrent write), abort immediately and do not write partial state changes.
• Never dispatch Skill(...) before state.md has been successfully updated to status: running with pause_reason: "". Dispatch is the last step.