feat: add bitflow-funding-coordinator (BFF Skills Comp winner by @macbotmini-eng)

bitflow-funding-coordinator/AGENT.md

@@ -0,0 +1,40 @@
+---
+name: bitflow-funding-coordinator-agent
+skill: bitflow-funding-coordinator
+description: "Coordinates route-ready Bitflow funding swaps only after checkpoint, confirmation, and Hiro verification checks pass."
+---
+
+# Agent Behavior - Bitflow Funding Coordinator
+
+## Decision order
+
+1. Run `doctor` first. If it fails, stop and surface the blocker.
+2. Run `status` to detect an unresolved funding checkpoint.
+3. Run `plan` with explicit wallet, source token, target token, amount, slippage, and handoff label.
+4. Confirm that the user wants the funding leg, not a downstream HODLMM or Zest placement.
+5. Execute `run --confirm=FUND` only after reviewing the plan.
+6. If a txid is already known, use `resume --txid` instead of rebroadcasting.
+7. Parse JSON output and pass the handoff payload to the next strategy only after `routeReady` is true.
+
+## Guardrails
+
+- Never broadcast without `--confirm=FUND`.
+- Never treat funding as yield deployment. This skill stops after the target token is route-ready.
+- Never call HODLMM, Zest, borrow, repay, or unwind write paths.
+- Never retry a write silently after interruption.
+- Never start a new route while an unresolved checkpoint exists.
+- Never expose wallet passwords, private keys, mnemonics, wallet IDs, or raw signer material.
+- Always surface txid, Hiro status, route-ready token, handoff label, and next action.
+
+## On error
+
+- Log the JSON error payload.
+- Do not retry silently.
+- If a txid exists, instruct the operator to use `resume --txid`.
+- If no txid exists, instruct the operator to inspect `status` and rerun `plan`.
+
+## On success
+
+- Confirm the tx hash, Hiro status, wallet, source token, target token, and handoff label.
+- Report that downstream routing can start only with the emitted target token.
+- Do not claim that #559, HODLMM, or Zest placement has executed.

bitflow-funding-coordinator/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: bitflow-funding-coordinator
+description: "Coordinates Bitflow funding swaps into route-ready target tokens for downstream strategy skills."
+metadata:
+  author: "macbotmini-eng"
+  author-agent: "Hex Stallion"
+  user-invocable: "false"
+  arguments: "doctor | status | plan | run | resume | cancel"
+  entry: "bitflow-funding-coordinator/bitflow-funding-coordinator.ts"
+  requires: "wallet, signing, settings, bitflow-swap-aggregator, nonce-manager"
+  tags: "defi, write, mainnet-only, requires-funds, l2"
+---
+
+# Bitflow Funding Coordinator
+
+## What it does
+
+`bitflow-funding-coordinator` is the funding leg for Bitflow-routed strategies. It turns a caller-selected source token into a caller-selected target token through the accepted `bitflow-swap-aggregator`, records a route checkpoint, confirms the swap on Hiro, and emits a handoff payload for downstream strategy skills.
+
+The required v1 acceptance path is STX to sBTC so wallets that start with idle STX can produce route-ready sBTC for `bitflow-hodlmm-zest-yield-loop`.
+
+## Why agents need it
+
+Downstream strategy routers should not quietly perform funding swaps while they are deciding where to place capital. This skill keeps the funding leg explicit: quote, plan, confirm, swap, verify, and hand off the resulting target token without performing HODLMM, Zest, borrow, repay, or unwind actions.
+
+## Safety notes
+
+- This is a write skill and can move wallet funds.
+- Mainnet only.
+- `run` refuses without `--confirm=FUND`.
+- The delegated swap primitive still requires its own `--confirm=SWAP` internally.
+- The skill refuses overlapping local checkpoints unless the operator resumes or cancels the prior route.
+- The skill records any returned txid before its own Hiro confirmation loop.
+- It does not deposit into HODLMM, supply to Zest, borrow, repay, or choose a yield venue.
+
+## Commands
+
+### doctor
+
+Checks wallet, Bitflow swap aggregator availability, nonce-manager availability signal, Hiro reachability, and any pending funding checkpoint.
+
+```bash
+bun run bitflow-funding-coordinator/bitflow-funding-coordinator.ts doctor --wallet <stacks-address>
+```
+
+### status
+
+Reads the local funding checkpoint and the delegated swap primitive's wallet readiness checks.
+
+```bash
+bun run bitflow-funding-coordinator/bitflow-funding-coordinator.ts status --wallet <stacks-address>
+```
+
+### plan
+
+Produces a quote-backed funding plan through `bitflow-swap-aggregator` without broadcasting.
+
+```bash
+bun run bitflow-funding-coordinator/bitflow-funding-coordinator.ts plan --wallet <stacks-address> --token-in token-stx --token-out token-sbtc --amount-in 1 --handoff-label bitflow-hodlmm-zest-yield-loop
+```
+
+### run
+
+Executes the funding swap after explicit confirmation, checkpoints the route, verifies Hiro success, and emits a route-ready handoff.
+
+```bash
+bun run bitflow-funding-coordinator/bitflow-funding-coordinator.ts run --wallet <stacks-address> --token-in token-stx --token-out token-sbtc --amount-in 1 --confirm=FUND --handoff-label bitflow-hodlmm-zest-yield-loop
+```
+
+### resume
+
+Confirms an already-broadcast funding txid and completes the local checkpoint without rebroadcasting.
+
+```bash
+bun run bitflow-funding-coordinator/bitflow-funding-coordinator.ts resume --wallet <stacks-address> --txid <txid>
+```
+
+### cancel
+
+Marks an unresolved local checkpoint as operator-cancelled.
+
+```bash
+bun run bitflow-funding-coordinator/bitflow-funding-coordinator.ts cancel --wallet <stacks-address>
+```
+
+## Output contract
+
+All commands emit exactly one JSON object to stdout.
+
+Success:
+
+```json
+{
+  "status": "success",
+  "action": "plan",
+  "data": {
+    "fundingRoute": "token-stx-to-token-sbtc",
+    "mode": "one-shot",
+    "routeReady": false,
+    "handoff": {
+      "label": "bitflow-hodlmm-zest-yield-loop",
+      "readyToken": "token-sbtc",
+      "readyAmount": null
+    }
+  },
+  "error": null
+}
+```
+
+Blocked:
+
+```json
+{
+  "status": "blocked",
+  "action": "run",
+  "data": {},
+  "error": {
+    "code": "CONFIRMATION_REQUIRED",
+    "message": "This write skill requires --confirm=FUND.",
+    "next": "Review plan output and rerun with --confirm=FUND."
+  }
+}
+```
+
+## Known constraints
+
+- V1 proves STX to sBTC funding for the #471 / #559 route.
+- Token selection is delegated to the live Bitflow swap aggregator token registry.
+- DCA-style repeated chunks are represented as `--mode dca-chunk`, but autonomous scheduling is intentionally out of scope for this submission.
+- This skill does not replace `bitflow-swap-aggregator`; it adds funding checkpoint, resume/cancel, handoff, and downstream-boundary semantics around that primitive.
+
+## Origin
+
+Winner of AIBTC x Bitflow Skills Pay the Bills competition.
+Original author: @macbotmini-eng
+Competition PR: https://github.com/BitflowFinance/bff-skills/pull/585