Refacil:autopilot

refacil:autopilot — Autonomous Implementation Pipeline

This skill is an orchestrator wrapper that runs the post-proposal SDD cycle without human intervention. It assumes the human has already executed /refacil:propose and approved the generated artifacts (proposal, design, specs, tasks). It chains the existing skills in order, respects the methodology contract and review gate, and notifies the outcome via WhatsApp through Kapso at the end.

Prerequisites:

• sdd profile from refacil-prereqs/SKILL.md + rules from METHODOLOGY-CONTRACT.md.
• Artifacts of the target change already generated and human-approved (i.e. /refacil:propose already ran).
• Credentials file ~/.refacil-sdd-ai/kapso.env exists with:
• KAPSO_API_KEY
• KAPSO_PHONE_NUMBER_ID
• NOTIFY_PHONE (E.164 format, e.g. +5731XXXXXXXX)

When to invoke

Activate when:

• The user explicitly invokes /refacil:autopilot [changeName].
• The user says variants like: "autopilot", "modo autónomo", "termina solo el flujo", "ejecuta el resto sin preguntarme", "me voy del PC, completa el SDD".

Do NOT activate when:

• The user has not yet run /refacil:propose for the target change.
• The user says "review the proposal" or asks anything still in the design phase.

Improvement passes — global rule

Each implementation phase below (apply, test, review) runs in up to 2 passes:

• Pass 1: execute the phase normally. After the underlying skill completes, ask the corresponding sub-agent to list acceptable improvements it identified but did not implement during pass 1 (refactors, missing edge-case tests, doc gaps, small quality wins). "Acceptable" means: within scope of the change, non-breaking, no new dependencies, no scope creep beyond the proposal.
• Pass 2: if pass 1 returned improvements, apply them all in a single pass.
• Hard cap: never run a 3rd pass on the same phase. If issues remain after pass 2, they are recorded as warnings in the notification payload and autopilot continues. If they are blocking (e.g., review still rejects, verify rounds exhausted), autopilot aborts and notifies failure.

verify is exempt from this loop — it already has 2 built-in autofix rounds (see METHODOLOGY-CONTRACT.md §3.1). Autopilot does NOT add a 3rd round on top.

After pass 2 of any phase, re-run sdd status --json to ensure the state is still consistent (tasks pending count, artifacts intact) before moving to the next phase.

Flow

Step 0: Preflight validation (blocking)

Run refacil-sdd-ai sdd list --json to get active changes.

• If there are no active changes → stop and instruct the user to run /refacil:propose first. Do NOT notify Kapso (this is a usage error, not an autopilot run).
• If $ARGUMENTS provided a change name → use it.
• If there is a single active change and no $ARGUMENTS → use it.
• If there are multiple active changes and no $ARGUMENTS → stop and ask the user to specify which change. Autopilot requires unambiguous scope.

With the resolved changeName, run refacil-sdd-ai sdd status --json and validate:

• artifacts.proposal AND artifacts.design AND artifacts.tasks AND artifacts.specs must all be true.
• ready.forApply must be true.
• Treat ready.forApply as the contract source of truth. It is true only with proposal.md, design.md, tasks.md, and valid non-empty specs from specs.md and/or recursive specs/**/*.md; empty specs/ folders do not count. This is the same spec source set used by sdd status, sync-spec, test/verify criteria extraction, and archive.
• If validation fails, build missingArtifacts from every false value in artifacts and report the full list.

If any of the above fails → stop and instruct the user to complete /refacil:propose for `, including Missing artifacts: `. Do NOT notify Kapso.

Step 0.5: Verify Kapso credentials (optional — guided)

(a) Attempt to read ~/.refacil-sdd-ai/kapso.env. Parse all lines of the form KEY=VALUE.

(b) Check that KAPSO_API_KEY, KAPSO_PHONE_NUMBER_ID, and NOTIFY_PHONE are all present and non-empty. If all three are present → set kapsoEnabled = true and continue to Step 0.6.

(c) If the file is absent or any of the three keys is missing or empty → kapsoEnabled = false. Ask the user (in the session language):

> Kapso credentials not found or incomplete in ~/.refacil-sdd-ai/kapso.env. Do you want to configure it now to receive a WhatsApp notification when the pipeline finishes? > > - Run refacil-sdd-ai kapso setup in another terminal and reply done when finished. > - Reply no to continue without notification.

Wait for the user's reply:

• If the user replies done / listo / ok / yes (case-insensitive) → re-read ~/.refacil-sdd-ai/kapso.env and re-check. If now complete → kapsoEnabled = true. If still incomplete → inform the user and set kapsoEnabled = false, continue.
• If the user replies no (or any other input) → set kapsoEnabled = false and continue.

(d) Continue the pipeline regardless of kapsoEnabled. Kapso is optional — a missing or misconfigured credential must never block the SDD pipeline.

Step 0.6: Pre-flight user input (single interaction — gather all before starting)

Resume detection: before anything else, try to read refacil-sdd/.autopilot-active. If the file exists and its changeName matches the resolved changeName from Step 0, the pre-flight was already completed in a prior session — skip this entire step (Steps 0.6 Case A and B) and go directly to Step 0.7. The marker already contains taskReference, createPR, baseBranch, and includeUpCode (fallback to true if the field is missing from an older marker).

All user input needed for the full pipeline must be collected here, in one message and one reply. This step only collects configuration — the pipeline does not start until the user sends an explicit affirmative after the ready message.

Run in parallel:

• git branch --show-current → currentBranch
• git status --porcelain → detect uncommitted changes
• refacil-sdd-ai sdd config --json → baseBranch, protectedBranches

IDE detection: Before presenting the pre-flight message, determine which IDE is running this session from the available context (system prompt, environment variables, CLI invocation style). Apply the following mapping:

| Signal | detectedIDE | |---|---| | System prompt contains "Claude Code" / claude CLI context | claude-code | | Cursor-specific context / agent header | cursor | | Codex CLI context | codex | | OpenCode CLI context | opencode | | Cannot determine | unknown |

Also detect the OS from session context:

• Windows (PowerShell / cmd environment) → detectedOS = "windows"
• macOS / Linux / WSL → detectedOS = "unix"
• Unknown → detectedOS = "unknown"

On Windows: just open a new terminal and run the command directly — no wrapper needed. Leave that terminal open while the pipeline runs. On Unix: wrap with nohup ... >> log 2>&1 & so the process survives after closing the terminal.

Map detectedIDE + detectedOS → idePermissionInstruction (shown literally in the pre-flight message).

Generate idePermissionInstruction in the session language using the template below (command lines stay literal). The instruction always opens the IDE interactively with the auto-permissions flag — the user sees output in real time and types /refacil:autopilot to start. No -p / non-interactive mode.

claude-code: Tell the user that avoiding permission prompts requires a new session. Instruct them to: close this session → open a new terminal → cd to the project → run claude --dangerously-skip-permissions → once Claude opens, type /refacil:autopilot.

cursor: Set idePermissionInstruction = "" (empty — Cursor runs autopilot in the current session; no need to open another session). Do NOT include any instruction to open a new session. Case A and Case B proceed normally.

codex: Tell the user that skipping permission prompts requires a new session. Instruct them to: close this session → open a new terminal → cd to the project → run codex --dangerously-bypass-approvals-and-sandbox → once Codex opens, type /refacil:autopilot.

opencode: Tell the user that skipping permission prompts requires a new session. Instruct them to: close this session → open a new terminal → cd to the project → run opencode --dangerously-skip-permissions → once open, type /refacil:autopilot.

unknown: Tell the user their IDE could not be detected. Show the open command for each IDE and instruct them to type /refacil:autopilot once it opens:

• Claude Code: claude --dangerously-skip-permissions
• Cursor: open Cursor in this repo, confirm in chat, then /refacil:autopilot (no headless launcher)
• Codex: codex --dangerously-bypass-approvals-and-sandbox
• OpenCode: opencode --dangerously-skip-permissions

Kapso pre-flight (kapsoEnabled = true only) — run once per session to surface the 24h window notice. Before presenting the ready message, check whether kapsoPreflightShown has already been set in this session:

• If kapsoPreflightShown is not yet set → run refacil-sdd-ai kapso preflight (exits 0, prints JSON). Parse preflightMessage from the output and include it in the ready message below. Then set kapsoPreflightShown = true so the block is not repeated if autopilot is re-invoked later in the same session.
• If kapsoPreflightShown is already set → omit the pre-flight block from the ready message (the user already saw it).
• Do NOT block or wait for confirmation of the WhatsApp notice — informational only.
• If kapsoEnabled = false, skip this sub-step entirely and omit the block.

Case A — currentBranch is in protectedBranches:

Present ONE data-collection message in the session language covering these three points (no permissions question here). This message only collects configuration; answering it does not start the pipeline.

1. Working branch — will create feature/ from ``. Ask if they have a ticket/ID (e.g. PROJ-123) to use as the branch suffix, or reply "ok" to use the change name.
2. Task reference — URL, ticket, or short name for the final archive record (e.g. https://tracker.co/PROJ-123). If same as ticket in point 1, no need to repeat.
3. Up-code and PR at the end? — three options (default: include up-code and create PR):

• Reply "sin up-code", "no up-code", "sin push", "no push", "skip up-code", or "omitir up-code" → includeUpCode = false, createPR = false (cycle ends after archive)
• Reply "sin PR", "no PR", "solo push", or "without pr" → includeUpCode = true, createPR = false (push but no PR)
• Any other reply / no signal → includeUpCode = true, createPR = true (default: push + PR)

If there are uncommitted changes, add a note that they will be stashed before branch creation and restored after.

Wait for the user's reply. Parse:

• URL (http:// or https://) found → taskReference = , branchSuffix = (unless a ticket was also given)
• Ticket/ID ([A-Za-z][A-Za-z0-9_-]*-\d+, e.g. PROJ-123) found → branchSuffix = , taskReference = (overridden by URL if both present)
• "sin up-code" / "no up-code" / "sin push" / "no push" / "skip up-code" / "omitir up-code" found (case-insensitive) → includeUpCode = false, createPR = false
• "sin PR" / "no PR" / "solo push" / "sin pr" / "without pr" found (case-insensitive, only when no up-code skip signal) → includeUpCode = true, createPR = false
• No signal → includeUpCode = true, createPR = true (default)
• "ok" or bare affirmative with no recognizable data → branchSuffix = , taskReference = refacil-sdd-autopilot/ (synthetic — annotated in the final notification)

Then create the branch (do NOT ask again):

1. If uncommitted changes → git stash push -m "auto-stash-refacil".
2. git checkout && git pull origin .
3. git checkout -b feature/.
4. If stash was pushed → git stash pop.

Write the autopilot marker so sub-skills can detect autonomous mode and skip their own confirmation prompts:

printf '{"changeName":"%s","taskReference":"%s","createPR":%s,"baseBranch":"%s","includeUpCode":%s}\n' \
  "" "" "" "" "" \
  > "refacil-sdd/.autopilot-active"

After writing the marker, generate and present the ready message using the CLI:

refacil-sdd-ai autopilot ready-message --change "" --ide "" --lang ""

Where ` is es (default) or en based on the session language. This command prints the localized ready message to stdout. Present its output to the user, prepending the Kapso pre-flight block if kapsoEnabled = true and kapsoPreflightShown is not yet set (see above). When detectedIDE = cursor, idePermissionInstruction is empty — do NOT append any instruction to open a new session or use cursor-agent; the pipeline runs in this Cursor session. For all other IDEs, append the idePermissionInstruction` after the CLI output. The ready message must not imply that the pipeline starts as soon as the user answers the pre-flight questions — it starts only after the user sends an explicit affirmative below. Replace any mention of "you can step away from your PC" / "puedes alejarte del PC" with neutral text indicating that the pipeline runs autonomously once started and the user can continue other activities.

EXPLICIT CONFIRMATION GATE — STOP AND WAIT: after displaying the ready message, do NOT continue automatically. Wait for the user to reply with an explicit affirmative:

• Affirmative ("go", "ok", "start", "yes", "sí", "dale", "arrancar", etc.) → continue to Step 0.7 in this session.
• No reply / session closed → the next session launched with the headless command will pick up via resume detection at the top of Step 0.6.
• Non-affirmative in-session reply (e.g. "no", "cancel", any other response) → do NOT start the pipeline; re-display the ready message and instruct the user to reply with an affirmative (go, ok, start, sí, dale, arrancar) when ready.

Case B — currentBranch is already a working branch (not protected):

Only ask for task reference and up-code/PR preference (branch creation is skipped). Present the message in the session language covering these two points. This message only collects configuration; answering it does not start the pipeline.

1. Task reference — URL, ticket, or short name for the final archive record.
2. Up-code and PR at the end? — three options (default: include up-code and create PR):

• Reply "sin up-code", "no up-code", "sin push", "no push", "skip up-code", or "omitir up-code" → includeUpCode = false, createPR = false (cycle ends after archive)
• Reply "sin PR", "no PR", "solo push", or "without pr" → includeUpCode = true, createPR = false (push but no PR)
• Any other reply / no signal → includeUpCode = true, createPR = true (default: push + PR)

Parse the reply — branch creation is skipped in Case B, so do NOT derive branchSuffix:

• URL (http:// or https://) found → taskReference =
• Ticket/ID ([A-Za-z][A-Za-z0-9_-]*-\d+, e.g. PROJ-123) found only if not embedded inside a URL → taskReference = ; if a ticket is embedded inside a URL, taskReference = (do not extract the ticket as a standalone value)
• "sin up-code" / "no up-code" / "sin push" / "no push" / "skip up-code" / "omitir up-code" found (case-insensitive) → includeUpCode = false, createPR = false
• "sin PR" / "no PR" / "solo push" / "sin pr" / "without pr" found (case-insensitive, only when no up-code skip signal) → includeUpCode = true, createPR = false
• No signal → includeUpCode = true, createPR = true (default)
• Unrecognizable → taskReference = refacil-sdd-autopilot/ (synthetic), includeUpCode = true, createPR = true

After writing the marker, generate and present the ready message using `

…

Source & license

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

• Author: Erikole21
• Source: Erikole21/refacil-sdd-ai
• License: MIT

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