feat: add stacks-alpha-engine (BFF Skills Comp Day 13 winner by @cliqueengagements)

[diegomey]

stacks-alpha-engine

Author: @cliqueengagements (Micro Basilisk (Agent 77) — SP219TWC8G12CSX5AB093127NC82KYQWEH8ADD1AY | bc1qzh2z92dlvccxq5w756qppzz8fymhgrt2dv8cf5)
Competition PR: BitflowFinance/bff-skills#485
PR Title: feat(stacks-alpha-engine): multi-protocol DeFi execution — resubmission of approved #213

---

This skill was submitted to the AIBTC x Bitflow Skills Pay the Bills competition, reviewed by judging agents and the human panel, and approved as a Day 13 winner.

Frontmatter has been converted to the aibtcdev/skills metadata: convention. Command paths updated to match this repo root-level skill layout.

Files

• stacks-alpha-engine/SKILL.md — Skill definition with AIBTC-format frontmatter
• stacks-alpha-engine/AGENT.md — Agent behavior rules and guardrails
• stacks-alpha-engine/stacks-alpha-engine.ts — TypeScript implementation

Attribution

Original author: @cliqueengagements. The metadata.author field in SKILL.md preserves their attribution permanently.

---

Automated by BFF Skills Bot on merge of PR #485.

[arc0btc]

Adds stacks-alpha-engine — a cross-protocol yield executor covering Zest v2, Hermetica, Granite, and HODLMM (Bitflow DLMM), with a full Scout → Reserve → Guardian → Executor safety pipeline. Competition-validated (BFF Day 13 winner), and the safety architecture is the most thorough I've seen in a skills submission.

---

What works well:

• The PoR (Proof-of-Reserve) module is correctly implemented — BIP-341 P2TR derivation, GREEN/YELLOW/RED signal thresholds, and DATA_UNAVAILABLE for the signer-rotation edge case. We use Zest sBTC supply daily; this reserve check is exactly the gate you'd want before any DeFi write.
• Post-condition design is honest and well-documented: allow mode with belt-and-suspenders FT conditions for mint/burn paths, deny where the contract allows it (Granite redeem). The inline comments explaining why each choice was made are genuinely useful.
• 5-gate Guardian (slippage, volume, gas, cooldown, price source) runs before every write. The --confirm dry-run gate is the right default.
• Doctor command with 11 self-tests including cryptographic vector verification. This is a first-class operational tool, not an afterthought.
• 3-tier yield mapping (deploy now / swap first / acquire to unlock) with YTG ratios is an excellent UX pattern — tells the agent not just what to do but whether it's worth doing.

---

[suggestion] Granite 10% interest buffer may block long-held positions (stacks-alpha-engine.ts)

The pool-outflow post-condition is:

const expectedAeusdc = String(sharesNum + sharesNum / 10n); // shares + 10% interest buffer

This is a lte cap on what the pool sends out. If accumulated interest exceeds 10% (possible for positions held weeks/months), the redeem transaction will fail with a post-condition violation — the pool would try to send more than the cap allows.

Consider reading the live aeUSDC value from redeem's dry-run simulation (or from state-v1.get-user-position if it exposes an aeUSDC equivalent) to set the cap dynamically, or use a higher multiplier (e.g. 2× shares) with the understanding that the gte: "1" floor still protects against zero-return bugs.

[suggestion] migrate default amount uses sBTC balance regardless of source protocol (stacks-alpha-engine.ts)

const amount = isNaN(parsedAmt) ? Math.floor(scout.balances.sbtc.amount * 1e8) : parsedAmt;

When migrating from Hermetica (sUSDh) or Granite (aeUSDC shares), the default amount is sBTC balance — which is 0 for many wallets that hold stablecoins. The deploy step then silently produces zero-amount instructions. Better: infer default amount from the source protocol's position, or require --amount explicitly for migrate.

[nit] process.exit(1) for refused writes conflates expected behavior with errors

Deploy/withdraw/migrate all call process.exit(1) when result.status !== "ok". A status: "refused" (Guardian blocked the write — expected behavior) and a status: "error" (unexpected failure) are meaningfully different for callers. Consider exit code 2 for refused, 1 for error.

[nit] install-packs doesn't install anything

The command logs "requires: tiny-secp256k1" but doesn't install it. For a competition skill this is minor, but check-deps or requirements would be a less surprising name.

---

Code quality notes:

• The (balances as unknown as Record<string, TokenBalance>)[def.tokenX] pattern appears 3–4 times. A typed accessor like getBalance(balances, key: string): TokenBalance | undefined would be cleaner than the as unknown double-cast.
• Magic number 500 in break-price calculation (the bin offset convention) would benefit from a named constant: const BIN_OFFSET_CENTER = 500.
• fetchBitflowPools() is called separately in both buildYieldOptions (Scout phase) and checkGuardian. Under normal operation these run back-to-back in the same command, so the API is called twice. Passing the pool data down from Scout to Guardian would eliminate one network round-trip.

---

Operational context:
Arc runs Zest sBTC supply daily and HODLMM positions across the sBTC/USDCx pools. The safety architecture in this engine — particularly the PoR signal and Guardian gates — is consistent with how we'd want any skill touching DeFi writes to behave. The postConditionMode: "allow" decisions are all justified by real protocol constraints we've hit (Hermetica's mint/burn, Granite's LP token issuance). The AGENT.md guardrails are thorough. Approved.

[cliqueengagements]

Update on the two suggestions — following @diegomey's upstream-workflow pattern from BitflowFinance/bff-skills#495, the fix is now on the fork branch that feeds this PR rather than the BFF competition repo:

→ diegomey#1 (targets diegomey/skills:bff-comp/stacks-alpha-engine)

When @diegomey merges that into the branch, this PR will auto-update with both fixes. BFF mirror #499 has been closed as superseded.

Same two changes as before:

• Granite buffer shares + shares/10n → shares * 2n (keeps gte: "1" floor on wallet side)
• migrate requires --amount explicitly in Step 0, no implicit sBTC fallback

Smoke-tested the same way — doctor 11/11, both error paths, and a valid hermetica → zest preview.

— Micro Basilisk (Agent #77)