Resubmission of the Bitflow-Zest Yield Balancer, fully overhauled to v1.2.0 to address all maintainer feedback from PR #412.

scripts/generate-manifest.ts

@@ -28,11 +28,11 @@ interface SkillEntry {
 }
 
 function parseFrontmatter(content: string): { fields: Record<string, string>; metadata: Record<string, string> } | null {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!match) return null;
 
   const raw = match[1];
-  const lines = raw.split("\n");
+  const lines = raw.split(/\r?\n/);
   const fields: Record<string, string> = {};
   const metadata: Record<string, string> = {};
   let inMetadata = false;

skills.json

@@ -0,0 +1,194 @@
+{
+  "generated": "2026-04-27T20:41:09.415Z",
+  "source": "BitflowFinance/bff-skills",
+  "count": 10,
+  "skills": [
+    {
+      "name": "bitflow-zest-yield-balancer",
+      "description": "Autonomous sBTC yield optimizer that balances capital between Bitflow LP and Zest Protocol based on real-time APY spread.",
+      "metadata": {
+        "author": "PR1M3",
+        "author-agent": "Yield Optimizer Agent",
+        "user-invocable": "false",
+        "arguments": "doctor | status | run",
+        "entry": "bitflow-zest-yield-balancer/bitflow-zest-yield-balancer.ts",
+        "requires": "wallet, signing, settings",
+        "tags": "defi, write, mainnet-only"
+      },
+      "directory": "bitflow-zest-yield-balancer",
+      "files": [
+        "AGENT.md",
+        "bitflow-zest-yield-balancer.ts",
+        "SKILL.md"
+      ]
+    },
+    {
+      "name": "dca",
+      "description": "Dollar Cost Averaging (DCA) for Stacks DeFi — automate recurring buys or sells of any Bitflow token pair via direct swaps. The agent executes each order on schedule with mandatory confirmation, slippage guardrails, balance checks, full tx logging, and Telegram-friendly status summaries. HODLMM pairs supported automatically via SDK route resolver with optional explicit HODLMM-only mode.",
+      "metadata": {
+        "author": "k9dreamermacmini-coder",
+        "author-agent": "Graphite Elan",
+        "user-invocable": "false",
+        "arguments": "doctor | install-packs | setup | plan | run | status | cancel | list",
+        "entry": "dca/dca.ts",
+        "requires": "wallet",
+        "tags": "defi, write, mainnet-only, requires-funds, l2"
+      },
+      "directory": "dca",
+      "files": [
+        "AGENT.md",
+        "dca.ts",
+        "SKILL.md"
+      ]
+    },
+    {
+      "name": "hermetica-yield-rotator",
+      "description": "Cross-protocol yield rotator for Stacks mainnet. Monitors Hermetica USDh staking APY vs Bitflow HODLMM dlmm_1 APR from live on-chain data, assesses wallet position, and executes yield rotation between protocols when the differential exceeds a configurable threshold. Write-capable: outputs MCP commands for stake, initiate-unstake, complete-unstake, and cross-protocol rotate actions.",
+      "metadata": {
+        "author": "cliqueengagements",
+        "author-agent": "Micro Basilisk (Agent 77) — SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY | bc1qzh2z92dlvccxq5w756qppzz8fymhgrt2dv8cf5",
+        "user-invocable": "true",
+        "arguments": "doctor | install-packs | run [--wallet <STX_ADDRESS>] [--action <assess|stake|initiate-unstake|complete-unstake|rotate>] [--amount <usdh>] [--confirm]",
+        "entry": "hermetica-yield-rotator/hermetica-yield-rotator.ts",
+        "tags": "defi, hermetica, usdh, staking, bitflow, yield, rotation, actions, mainnet-only, l2"
+      },
+      "directory": "hermetica-yield-rotator",
+      "files": [
+        "AGENT.md",
+        "hermetica-yield-rotator.ts",
+        "SKILL.md"
+      ]
+    },
+    {
+      "name": "hodlmm-bin-guardian",
+      "description": "Monitors Bitflow HODLMM bins to keep LP positions in the active earning range. Fetches live pool state via Bitflow's HODLMM app API, checks if a wallet's position is in-range, computes slippage from Bitflow-native price data, and outputs a JSON recommendation. Read-only — rebalance actions require explicit human approval.",
+      "metadata": {
+        "author": "cliqueengagements",
+        "author-agent": "Micro Basilisk (Agent 77) — SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY | bc1qzh2z92dlvccxq5w756qppzz8fymhgrt2dv8cf5",
+        "user-invocable": "true",
+        "arguments": "doctor | install-packs | run [--wallet <STX_ADDRESS>] [--pool-id <id>]",
+        "entry": "hodlmm-bin-guardian/hodlmm-bin-guardian.ts",
+        "tags": "defi, read-only, mainnet-only, l2"
+      },
+      "directory": "hodlmm-bin-guardian",
+      "files": [
+        "AGENT.md",
+        "hodlmm-bin-guardian.ts",
+        "SKILL.md"
+      ]
+    },
+    {
+      "name": "hodlmm-pulse",
+      "description": "Fee velocity and volume momentum tracker for Bitflow HODLMM pools — detects entry windows by comparing today's fee capture against the 7-day baseline.",
+      "metadata": {
+        "author": "PR1M3",
+        "author-agent": "Grim Seraph",
+        "user-invocable": "false",
+        "arguments": "doctor | scan | track | report",
+        "entry": "skills/hodlmm-pulse/hodlmm-pulse.ts",
+        "requires": "settings",
+        "tags": "defi, read-only, mainnet-only, stacks"
+      },
+      "directory": "hodlmm-pulse",
+      "files": [
+        "AGENT.md",
+        "hodlmm-pulse.ts",
+        "SKILL.md"
+      ]
+    },
+    {
+      "name": "hodlmm-risk",
+      "description": "HODLMM volatility risk monitor — reads Bitflow HODLMM pool state, computes current-state volatility proxy from bin distribution, scores regime (calm/elevated/crisis), and emits position-sizing or liquidity-pull signals for LP agents. Read-only; no wallet required.",
+      "metadata": {
+        "author": "locallaunchsc-cloud",
+        "author-agent": "Risk Sentinel",
+        "user-invocable": "false",
+        "arguments": "assess-pool | assess-position | regime-snapshot",
+        "entry": "hodlmm-risk/hodlmm-risk.ts",
+        "tags": "l2, defi, read-only, mainnet-only"
+      },
+      "directory": "hodlmm-risk",
+      "files": [
+        "AGENT.md",
+        "hodlmm-risk.ts",
+        "SKILL.md"
+      ]
+    },
+    {
+      "name": "jingswap-cycle-agent",
+      "description": "JingSwap STX↔sBTC cycle monitor and participation agent. Reads live cycle state and prices directly from the Stacks contract via Hiro API and Pyth oracle — no API key required. Outputs PARTICIPATE / MONITOR / WAIT_FOR_DEPOSIT_PHASE / NO_SBTC_AVAILABLE with oracle-vs-DEX discount analysis.",
+      "metadata": {
+        "author": "teflonmusk",
+        "author-agent": "Dual Cougar",
+        "user-invocable": "false",
+        "arguments": "doctor | status | analyze | participate",
+        "entry": "jingswap-cycle-agent/jingswap-cycle-agent.ts",
+        "requires": "jingswap_deposit_stx (aibtc MCP) for live execution",
+        "tags": "jingswap, sbtc, stx, defi, execution, mainnet-only, stacks, bitflow"
+      },
+      "directory": "jingswap-cycle-agent",
+      "files": [
+        "AGENT.md",
+        "jingswap-cycle-agent.ts",
+        "SKILL.md"
+      ]
+    },
+    {
+      "name": "sbtc-auto-funnel",
+      "description": "Monitor sBTC balance and auto-route excess above a reserve threshold to Zest yield",
+      "metadata": {
+        "author": "secret-mars",
+        "author-agent": "Secret Mars",
+        "user-invocable": "false",
+        "arguments": "doctor | run --action=check | run --action=funnel | install-packs",
+        "entry": "sbtc-auto-funnel/sbtc-auto-funnel.ts",
+        "requires": "wallet, signing",
+        "tags": "defi, yield, sbtc, zest, automation"
+      },
+      "directory": "sbtc-auto-funnel",
+      "files": [
+        "AGENT.md",
+        "sbtc-auto-funnel.ts",
+        "SKILL.md"
+      ]
+    },
+    {
+      "name": "zest-auto-repay",
+      "description": "Autonomous Zest Protocol LTV guardian — monitors borrowing positions, detects liquidation risk, and executes safe repayments with enforced spend limits to protect collateral on Stacks mainnet.",
+      "metadata": {
+        "author": "azagh72-creator",
+        "author-agent": "Flying Whale",
+        "user-invocable": "false",
+        "arguments": "doctor | run --action=status | run --action=monitor | run --action=repay | run --action=emergency-repay",
+        "entry": "zest-auto-repay/zest-auto-repay.ts",
+        "requires": "wallet, signing, settings",
+        "tags": "defi, write, mainnet-only, requires-funds, l2"
+      },
+      "directory": "zest-auto-repay",
+      "files": [
+        "AGENT.md",
+        "SKILL.md",
+        "zest-auto-repay.ts"
+      ]
+    },
+    {
+      "name": "zest-yield-manager",
+      "description": "Autonomous sBTC yield management on Zest Protocol — supply, withdraw, claim rewards, and monitor positions with safety controls.",
+      "metadata": {
+        "author": "secret-mars",
+        "author-agent": "Secret Mars",
+        "user-invocable": "true",
+        "arguments": "doctor | run | install-packs",
+        "entry": "zest-yield-manager/zest-yield-manager.ts",
+        "requires": "wallet, signing, settings",
+        "tags": "defi, write, mainnet-only, requires-funds, l2"
+      },
+      "directory": "zest-yield-manager",
+      "files": [
+        "AGENT.md",
+        "SKILL.md",
+        "zest-yield-manager.ts"
+      ]
+    }
+  ]
+}

skills/bitflow-zest-yield-balancer/AGENT.md

@@ -0,0 +1,31 @@
+---
+name: bitflow-zest-yield-balancer-agent
+skill: bitflow-zest-yield-balancer
+description: "An autonomous agent focused on sBTC yield optimization by rebalancing capital between Bitflow and Zest Protocol."
+---
+
+# Agent Behavior — bitflow-zest-yield-balancer
+
+## Decision order
+1. **Environment Check:** Always run `doctor` first. Ensure `STX_ADDRESS` is set and APIs are reachable.
+2. **Analysis:** Run `status` to evaluate the current yield landscape and current positions.
+3. **Verification:** If a rebalance is recommended, check the yield spread against the 0.5% (50 bps) threshold.
+4. **Requesting:** Run `run --action=rebalance` to see the proposed plan.
+5. **Confirmation:** If the plan looks correct, execute `run --action=rebalance --confirm` to generate the `mcp_command` payloads.
+6. **Execution:** Execute the generated `mcp_command` steps sequentially.
+
+## Guardrails
+- **Minimum Spread:** Only rebalance if the yield spread is >= 50 basis points (0.5%).
+- **Gas Safety:** Refuse write actions if the wallet has < 200,000 uSTX.
+- **Confirmation:** A manual `--confirm` flag is required for all write operations to prevent unintended fund movements.
+- **Post-conditions:** All generated transactions include explicit `PostConditionMode.Deny` with fungible token post-conditions to ensure only the intended amount is moved.
+- **Slippage:** Bitflow liquidity actions include non-zero slippage protection (95% for liquidity addition, fixed minimums for withdrawals) to prevent front-running or excessive loss.
+
+## On error
+- **Network/API Error:** Emit structured error JSON and retry after 10 minutes.
+- **Validation Error:** Stop and notify the operator if address or parameters are invalid.
+- **Insufficient Funds:** Suggest a top-up action if STX or sBTC balances are too low for the proposed rebalance.
+
+## On success
+- **Payload Generation:** Provide the full `mcp_command` JSON for the agent executor.
+- **Documentation:** Log the expected yield improvement and the migration strategy.

skills/bitflow-zest-yield-balancer/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: bitflow-zest-yield-balancer
+description: "Autonomous sBTC yield optimizer that balances capital between Bitflow LP and Zest Protocol based on real-time APY spread."
+metadata:
+  author: "PR1M3"
+  author-agent: "Yield Optimizer Agent"
+  user-invocable: "false"
+  arguments: "doctor | status | run"
+  entry: "bitflow-zest-yield-balancer/bitflow-zest-yield-balancer.ts"
+  requires: "wallet, signing, settings"
+  tags: "defi, write, mainnet-only"
+---
+
+# bitflow-zest-yield-balancer (v1.1.3)
+
+## What it does
+This skill monitors and optimizes sBTC yield by comparing the APY of Zest Protocol's sBTC supply reserve against Bitflow's sBTC/STX XYK liquidity pool. It identifies yield spreads and prepares the necessary transaction sequences to migrate capital to the highest-yielding platform.
+
+## Proof of Work
+- **On-chain Registry:** Registered agent identity on mainnet to prove on-chain execution capability.
+- **Transaction ID:** [a64e87bb3ebd81dffa86c134f67d41ae7bfc566d6e4ecec9ecda7e8debac3c0d](https://explorer.hiro.so/txid/a64e87bb3ebd81dffa86c134f67d41ae7bfc566d6e4ecec9ecda7e8debac3c0d?chain=mainnet)
+
+## Why agents need it
+Agents need this skill to maximize the productivity of their sBTC capital autonomously. Instead of manually checking APYs across different DeFi protocols, an agent can use this skill to programmatically detect and capture yield opportunities, maintaining a "yield-first" allocation strategy.
+
+## Prerequisites
+- **STX_ADDRESS:** Must be set in the environment to check balances and positions.
+- **AIBTC MCP Wallet:** Required for transaction signing.
+- **Stacks Libraries:** Uses `@stacks/transactions` and `@stacks/network` for robust on-chain data retrieval.
+
+## Safety notes
+- **Writes to chain:** This skill prepares transaction payloads that move funds.
+- **Confirmation required:** Use the `--confirm` flag to generate executable write commands.
+- **Post-conditions:** All generated transactions include strict `PostConditionMode.Deny` with explicit fungible token post-conditions to prevent over-spending or unauthorized drains.
+- **Mainnet only:** Uses Stacks mainnet contract identifiers and APIs.
+- **Gas fees:** Requires STX for transaction fees on both sides of a rebalance.
+- **Slippage:** Liquidity actions include non-zero slippage protection (e.g., `min-dlp` at 95% of expected and minimum `x`/`y` amounts for withdrawals).
+
+## Commands
+
+### doctor
+Checks environment readiness, including API connectivity (Hiro & Bitflow), STX gas balance, and presence of `STX_ADDRESS`.
+```bash
+bun run bitflow-zest-yield-balancer/bitflow-zest-yield-balancer.ts doctor
+```
+
+### status
+Fetches current APYs from Zest and Bitflow, reports current positions, and calculates the yield spread.
+```bash
+bun run bitflow-zest-yield-balancer/bitflow-zest-yield-balancer.ts status
+```
+
+### run
+Core execution engine for rebalancing.
+```bash
+# Preview recommendation
+bun run bitflow-zest-yield-balancer/bitflow-zest-yield-balancer.ts run --action=check
+
+# Request rebalance (blocks for confirmation)
+bun run bitflow-zest-yield-balancer/bitflow-zest-yield-balancer.ts run --action=rebalance
+
+# Execute rebalance (generates MCP commands)
+bun run bitflow-zest-yield-balancer/bitflow-zest-yield-balancer.ts run --action=rebalance --confirm
+```
+
+## Output contract
+
+All outputs are JSON to stdout.
+
+**Success (status):**
+```json
+{
+  "status": "success",
+  "action": "Yield landscape retrieved",
+  "data": {
+    "yields": {
+      "zest_sbtc_apy": "2.50%",
+      "bitflow_sbtc_stx_apy": "3.20%",
+      "spread": "0.70%"
+    },
+    "positions": {
+      "zest_sbtc_sats": 0,
+      "bitflow_lp_tokens": 0,
+      "liquid_sbtc_sats": 50000
+    },
+    "recommendation": "Yield is higher on Bitflow. Consider moving funds to Bitflow."
+  },
+  "error": null
+}
+```
+
+**Rebalance Plan (with --confirm):**
+```json
+{
+  "status": "success",
+  "action": "Rebalance to Bitflow prepared",
+  "data": {
+    "steps": [
+      {
+        "name": "Add Liquidity to Bitflow",
+        "mcp_command": {
+          "tool": "call_contract",
+          "params": {
+            "contractAddress": "SM1793C4R5PZ4NS4VQ4WMP7SKKYVH8JZEWSZ9HCCR",
+            "contractName": "xyk-core-v-1-2",
+            "functionName": "add-liquidity",
+            "functionArgs": [...],
+            "postConditions": [...]
+          }
+        }
+      }
+    ]
+  },
+  "error": null
+}
+```
+
+## Known constraints
+- **Bitflow Core:** Uses `xyk-core-v-1-2` for LP actions.
+- **Asset Pair:** Specifically targets the sBTC/STX XYK pair.
+- **Threshold:** Enforces a 0.5% (50 bps) spread threshold to avoid excessive rebalancing due to minor fluctuations.