feat(flow-orchestrate): multi-agent orchestrator skill for Flow development#28
Open
claucondor wants to merge 28 commits intoonflow:mainfrom
Open
feat(flow-orchestrate): multi-agent orchestrator skill for Flow development#28claucondor wants to merge 28 commits intoonflow:mainfrom
claucondor wants to merge 28 commits intoonflow:mainfrom
Conversation
Introduces the flow-orchestrate skill that routes multi-domain tasks to specialized subagents. Each agent loads only the references for its domain, reducing per-agent context by 80-90% vs. loading all 50 reference files.
task-routing.md: decision tree mapping task keywords to agent sets, parallel vs. sequential ordering, and file conflict detection. handoff-format.md: structured output format each agent must produce so downstream agents can consume work without re-reading everything.
…specialists Roster now matches production agents: cu-profiler, storage-architect, cross-vm-bridge, cadence-deploy, economic-designer, security-auditor, test-architect. Each mapped to the specific skill refs they embed.
cu-profiler: measures real CU costs on testnet using sweep methodology, extracts fees from FlowFees.FeesDeducted events, outputs MAX_SAFE_N. storage-architect: optimizes Cadence resource layout using atree internals (dict vs array, borrow-outside-loops, 512-byte inlining, composite key packing). First agent called when CU budget is exceeded.
cross-vm-bridge: handles Cadence<->EVM boundary (EVM.dryCall vs coa.call, manual ABI encoding, inline decode rule, COA borrow pattern, gas defaults). cadence-deploy: owns compile->deploy->verify cycle with common error table, update-vs-redeploy decision rule, and post-deploy verification checklist.
Translates CU Profiler output into protocol fee parameters: INDEX_FEE, treasury split ratios, solvency analysis across FLOW price scenarios, loyalty point sustainability, and royalty cut validation (UFix64 silent bug). Works from measured numbers only — never estimates independently.
security-auditor: full Cadence vulnerability taxonomy (access control gaps, storage path bugs, arithmetic, resource handling, capability abuse, loyalty farming), 7-pass methodology, severity classification, per-finding output format. test-architect: CDC native vs Go/overflow decision tree, adversarial test categories for all known exploit classes, coverage interpretation with known system-contract limitation.
task-routing: workflows for the 7 production agents (cu-profiler, storage-architect, cross-vm-bridge, cadence-deploy, economic-designer, security-auditor, test-architect) with concrete scope examples per agent. handoff-format: agent-specific handoff block examples covering all real inter-agent transitions (audit→fix, profiler→designer, tests→deploy).
Adds agent capabilities table (what each agent does, tools it uses, what it cannot do), team communication block to append to every agent prompt in team mode, and peer-to-peer SendMessage protocol so agents coordinate directly without routing through the orchestrator.
…chitect Both agents now know each other's capabilities and communicate directly via SendMessage: auditor sends findings to test-architect, test-architect sends results to cadence-deploy. No relay through team-lead.
cu-profiler sends MAX_SAFE_N directly to economic-designer and notifies storage-architect of baseline. storage-architect triggers cu-profiler re-measure and alerts security-auditor of path changes. economic-designer waits for cu-profiler input, then sends INDEX_FEE to cadence-deploy.
cadence-deploy waits for security-auditor PASS, then pushes contract address directly to frontend-dev. cross-vm-bridge alerts security-auditor of files ready and cadence-deploy of required EVM addresses. frontend-dev waits for cadence-deploy address before configuring FlowProvider.
…to project dir Agents were escaping the project directory and reading files from other repos when resolving imports. Two fixes: plugin refs now resolve from <plugin-root>/skills/<path> instead of a filesystem search; every agent prompt now receives an explicit project root constraint.
…fold Without local dependencies, agents resolve NonFungibleToken and MetadataViews by searching the filesystem and may find contracts in unrelated projects. Phase 0 ensures standard contracts are available in the project before any agent touches .cdc files.
…riteria Orchestrator now outputs a visible plan block before spawning any agent so the user knows what is about to run and why. TeamCreate decision criteria: use teams when agents need mid-task peer coordination (cycles, back-and-forth, blocking waits). Use parallel Agent() for clean linear pipelines where each phase feeds the next.
- cu-profiler: add cu-optimization.md (CU cost table, high-CU patterns) - cadence-deploy: add upgrade-strategies.md (allowed changes, rollback) - test-architect: add testing-patterns.md (adversarial categories, CDC vs Go)
Template refs cover the common case. Orchestrator should add cadence-scaffold refs when an agent generates new code, and other domain refs when relevant. Documents when to add: scaffold-contract, scaffold-transaction, scaffold-defi, access-control, transactions.
…ssing Team mode (TeamCreate + SendMessage) requires the flag in settings.json. Parallel Agent() calls work without it and cover most pipeline workflows. Add check command and settings snippet so users can enable team mode.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
flow-orchestrateskill that routes complex, multi-domain Flow development tasks to specialized subagents. Each agent receives only the reference files for its domain — keeping per-agent context 80-90% leaner than loading all 50 reference files.Validated end-to-end: a single prompt produced a production-ready NFT contract, passed a security audit (2 High findings found and fixed), deployed to emulator, profiled CU across N=10–1000, and computed a governance-updatable mint fee — all without manual coding. See claucondor/flow-orchestator-test.
Requirements
Agent()calls, sequential handoffsTeamCreate+SendMessagepeer-to-peerCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1in~/.claude/settings.jsonThe orchestrator detects which mode to use based on task complexity and documents the check command inline in SKILL.md. Most workflows run as a pipeline and need no flag.
What's included
flow-orchestrate/SKILL.md— orchestrator briefing: agent roster with capabilities and limitations, plugin root resolution, workspace scoping, parallel vs sequential rules, Team vs subagent decision criteria, experimental flag requirement, plan announcement format.flow-orchestrate/agents/— 8 agent templates:cu-profilerstorage-architectcross-vm-bridgecadence-deployeconomic-designersecurity-auditortest-architectfrontend-devEach template: role, when-to-spawn criteria, refs to embed, full prompt with embedded domain knowledge, team peer-routing (who sends what to whom), token budget.
flow-orchestrate/references/task-routing.md— decision tree: task keywords → agent sets, Phase 0 dependency install, parallel/sequential ordering, file conflict detection.flow-orchestrate/references/handoff-format.md— structured output each agent must produce so downstream agents consume results without re-reading everything.New cross-skill references:
cadence-lang/references/cu-optimization.md— CU cost table, high-CU patterns, MAX_SAFE_N methodologyflow-dev-setup/references/testing-patterns.md— CDC native vs Go/overflow decision tree, adversarial test categoriesflow-project-setup/references/upgrade-strategies.md— allowed/forbidden upgrades, new-name migration, rollbackflow-defi/references/protocol-architecture.md— appended cross-VM failure modesDesign decisions
Phase 0 always runs first. The orchestrator runs
flow dependencies installbefore any agent touches.cdcfiles. Agents never search the filesystem for standard contracts.Project root is explicit in every agent prompt. Prevents agents from reading files from unrelated projects on the same machine.
Agent templates are a base, not a fixed list. Orchestrator adds cadence-scaffold refs when generating new code, and domain refs (access-control, transactions) when the task calls for it.
Test run
claucondor/flow-orchestator-test — 7 commits tracing each agent's output, 176 tool calls, ~22 min. CU model:
CU(N) = 4.46N + 9.68(R²=0.9999), MAX_SAFE_N=2013, MINT_FEE=0.00000025 FLOW.