@dv.nghiem/flowdeck 0.4.8 → 0.4.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/default-executor.d.ts +3 -0
- package/dist/agents/default-executor.d.ts.map +1 -0
- package/dist/agents/index.d.ts +2 -1
- package/dist/agents/index.d.ts.map +1 -1
- package/dist/agents/orchestrator.d.ts.map +1 -1
- package/dist/hooks/orchestrator-guard-hook.d.ts +12 -6
- package/dist/hooks/orchestrator-guard-hook.d.ts.map +1 -1
- package/dist/index.js +281 -84
- package/package.json +1 -1
- package/src/rules/common/agent-orchestration.md +88 -30
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"default-executor.d.ts","sourceRoot":"","sources":["../../src/agents/default-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAgD/C,wBAAgB,0BAA0B,CACxC,KAAK,CAAC,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,MAAM,EACrB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,eAAe,CAkBjB"}
|
package/dist/agents/index.d.ts
CHANGED
|
@@ -21,6 +21,7 @@ import { createPolicyEnforcerAgent } from './policy-enforcer';
|
|
|
21
21
|
import { createPerformanceOptimizerAgent, createRefactorGuideAgent } from './performance';
|
|
22
22
|
import { createDesignAgent } from './design';
|
|
23
23
|
import { createSupervisorAgent } from './supervisor';
|
|
24
|
+
import { createDefaultExecutorAgent } from './default-executor';
|
|
24
25
|
/** All agent names registered by FlowDeck. */
|
|
25
26
|
export declare const AGENT_NAMES: readonly string[];
|
|
26
27
|
export type AgentMode = 'primary' | 'subagent' | 'all';
|
|
@@ -52,5 +53,5 @@ export declare function getAgentConfigs(agentModels?: Record<string, string | un
|
|
|
52
53
|
* @param customAppendPrompt - optional prompt suffix
|
|
53
54
|
*/
|
|
54
55
|
export declare function createOrchestratorAgentForStage(stage: string, model?: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
|
|
55
|
-
export { createOrchestratorAgent, createPlannerAgent, createBackendCoderAgent, createFrontendCoderAgent, createDevopsAgent, createPlanCheckerAgent, createTesterAgent, createReviewerAgent, createResearcherAgent, createWriterAgent, createSecurityAuditorAgent, createDocUpdaterAgent, createMapperAgent, createCodeExplorerAgent, createDebugSpecialistAgent, createBuildErrorResolverAgent, createTaskSplitterAgent, createDiscusserAgent, createArchitectAgent, createRiskAnalystAgent, createPolicyEnforcerAgent, createPerformanceOptimizerAgent, createRefactorGuideAgent, createDesignAgent, createSupervisorAgent, };
|
|
56
|
+
export { createOrchestratorAgent, createPlannerAgent, createBackendCoderAgent, createFrontendCoderAgent, createDevopsAgent, createPlanCheckerAgent, createTesterAgent, createReviewerAgent, createResearcherAgent, createWriterAgent, createSecurityAuditorAgent, createDocUpdaterAgent, createMapperAgent, createCodeExplorerAgent, createDebugSpecialistAgent, createBuildErrorResolverAgent, createTaskSplitterAgent, createDiscusserAgent, createArchitectAgent, createRiskAnalystAgent, createPolicyEnforcerAgent, createPerformanceOptimizerAgent, createRefactorGuideAgent, createDesignAgent, createSupervisorAgent, createDefaultExecutorAgent, };
|
|
56
57
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,SAAS,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EACL,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agents/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agents/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAsV/C,wBAAgB,uBAAuB,CACrC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CA6BR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACjE,YAAY,CAAC,EAAE,MAAM,EACrB,kBAAkB,CAAC,EAAE,MAAM,EAC3B,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,eAAe,CAuBjB"}
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Orchestrator Guard Hook
|
|
3
3
|
*
|
|
4
|
-
* Enforces the "orchestrator as coordinator" rule for the primary session.
|
|
5
|
-
* The orchestrator may inspect files and planning state directly, but it
|
|
6
|
-
*
|
|
7
|
-
*
|
|
4
|
+
* Enforces the "orchestrator as coordinator, not executor" rule for the primary session.
|
|
5
|
+
* The orchestrator may inspect files and planning state directly, but it CANNOT
|
|
6
|
+
* use file-write, edit, or shell tools. Those MUST be routed to specialist agents
|
|
7
|
+
* or the default-executor.
|
|
8
8
|
*
|
|
9
|
-
* To
|
|
10
|
-
* Default is
|
|
9
|
+
* To disable: set FLOWDECK_ORCHESTRATOR_GUARD=off in the environment.
|
|
10
|
+
* Default is ON.
|
|
11
11
|
*/
|
|
12
12
|
export declare class OrchestratorGuard {
|
|
13
13
|
private primarySessionId;
|
|
@@ -19,5 +19,11 @@ export declare class OrchestratorGuard {
|
|
|
19
19
|
sessionId?: string;
|
|
20
20
|
}): void;
|
|
21
21
|
check(sessionId: string, toolName: string): void;
|
|
22
|
+
/** Exposed for testing. */
|
|
23
|
+
_isBlockedForTest(name: string): boolean;
|
|
24
|
+
/** Exposed for testing. */
|
|
25
|
+
_isAllowedForTest(name: string): boolean;
|
|
26
|
+
/** Exposed for testing. */
|
|
27
|
+
_setPrimarySessionIdForTest(id: string | null): void;
|
|
22
28
|
}
|
|
23
29
|
//# sourceMappingURL=orchestrator-guard-hook.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"orchestrator-guard-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/orchestrator-guard-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;
|
|
1
|
+
{"version":3,"file":"orchestrator-guard-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/orchestrator-guard-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsHH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,gBAAgB,CAAsB;IAE9C,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAkBtH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAUhD,2BAA2B;IAC3B,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIxC,2BAA2B;IAC3B,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIxC,2BAA2B;IAC3B,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;CAGrD"}
|
package/dist/index.js
CHANGED
|
@@ -3381,7 +3381,7 @@ function createCompactionHook(ctx, tracker) {
|
|
|
3381
3381
|
}
|
|
3382
3382
|
|
|
3383
3383
|
// src/hooks/orchestrator-guard-hook.ts
|
|
3384
|
-
var DISABLED = process.env.FLOWDECK_ORCHESTRATOR_GUARD
|
|
3384
|
+
var DISABLED = process.env.FLOWDECK_ORCHESTRATOR_GUARD === "off";
|
|
3385
3385
|
var BLOCKED_TOOLS = new Set([
|
|
3386
3386
|
"write_file",
|
|
3387
3387
|
"write",
|
|
@@ -3398,20 +3398,63 @@ var BLOCKED_TOOLS = new Set([
|
|
|
3398
3398
|
"execute",
|
|
3399
3399
|
"run_command",
|
|
3400
3400
|
"terminal",
|
|
3401
|
-
"shell"
|
|
3401
|
+
"shell",
|
|
3402
|
+
"python",
|
|
3403
|
+
"run_python",
|
|
3404
|
+
"js",
|
|
3405
|
+
"run_js",
|
|
3406
|
+
"npm",
|
|
3407
|
+
"pnpm",
|
|
3408
|
+
"yarn",
|
|
3409
|
+
"bun",
|
|
3410
|
+
"cargo",
|
|
3411
|
+
"go",
|
|
3412
|
+
"make",
|
|
3413
|
+
"cmake",
|
|
3414
|
+
"docker",
|
|
3415
|
+
"kubectl",
|
|
3416
|
+
"terraform",
|
|
3417
|
+
"pulumi"
|
|
3402
3418
|
]);
|
|
3403
3419
|
var ALWAYS_ALLOWED = new Set([
|
|
3420
|
+
"read",
|
|
3421
|
+
"read_file",
|
|
3422
|
+
"view",
|
|
3423
|
+
"search",
|
|
3424
|
+
"grep",
|
|
3425
|
+
"glob",
|
|
3404
3426
|
"planning-state",
|
|
3405
3427
|
"codebase-state",
|
|
3406
3428
|
"repo-memory",
|
|
3407
3429
|
"decision-trace",
|
|
3408
3430
|
"policy-engine",
|
|
3409
|
-
"reflect"
|
|
3431
|
+
"reflect",
|
|
3432
|
+
"codegraph",
|
|
3433
|
+
"codegraph-search",
|
|
3434
|
+
"codegraph-node",
|
|
3435
|
+
"codegraph-explore",
|
|
3436
|
+
"load-rules",
|
|
3437
|
+
"list-rules",
|
|
3438
|
+
"council",
|
|
3439
|
+
"rtk-setup",
|
|
3440
|
+
"hash-edit",
|
|
3441
|
+
"failure-replay"
|
|
3410
3442
|
]);
|
|
3443
|
+
function normalizeToolName(name) {
|
|
3444
|
+
return name.toLowerCase().replace(/[-_]/g, "");
|
|
3445
|
+
}
|
|
3411
3446
|
function isBlocked2(name) {
|
|
3412
|
-
const norm = name
|
|
3447
|
+
const norm = normalizeToolName(name);
|
|
3413
3448
|
for (const b of BLOCKED_TOOLS) {
|
|
3414
|
-
if (norm ===
|
|
3449
|
+
if (norm === normalizeToolName(b))
|
|
3450
|
+
return true;
|
|
3451
|
+
}
|
|
3452
|
+
return false;
|
|
3453
|
+
}
|
|
3454
|
+
function isAlwaysAllowed(name) {
|
|
3455
|
+
const norm = normalizeToolName(name);
|
|
3456
|
+
for (const a of ALWAYS_ALLOWED) {
|
|
3457
|
+
if (norm === normalizeToolName(a))
|
|
3415
3458
|
return true;
|
|
3416
3459
|
}
|
|
3417
3460
|
return false;
|
|
@@ -3419,17 +3462,21 @@ function isBlocked2(name) {
|
|
|
3419
3462
|
function blockMessage(toolName) {
|
|
3420
3463
|
return `[Orchestrator Guard] The orchestrator cannot use \`${toolName}\` directly.
|
|
3421
3464
|
|
|
3422
|
-
` + `
|
|
3465
|
+
` + `The orchestrator is a coordinator, not an executor.
|
|
3466
|
+
|
|
3467
|
+
` + `Routing options:
|
|
3468
|
+
` + ` @default-executor — simple direct tasks (rename, typo fix, quick edit)
|
|
3469
|
+
` + ` @backend-coder — backend code writing and editing
|
|
3470
|
+
` + ` @frontend-coder — frontend code writing and editing
|
|
3471
|
+
` + ` @devops — CI/CD, deploy, and infrastructure changes
|
|
3472
|
+
` + ` @mapper — codebase mapping
|
|
3473
|
+
` + ` @researcher — focused research and file analysis
|
|
3474
|
+
` + ` @tester — tests, builds, and shell-heavy verification
|
|
3475
|
+
` + ` @writer — documentation writing
|
|
3423
3476
|
|
|
3424
|
-
` + `
|
|
3425
|
-
` + ` @backend-coder — backend code writing and editing
|
|
3426
|
-
` + ` @frontend-coder — frontend code writing and editing
|
|
3427
|
-
` + ` @devops — CI/CD, deploy, and infrastructure changes
|
|
3428
|
-
` + ` @mapper — codebase mapping
|
|
3429
|
-
` + ` @researcher — focused research and file analysis
|
|
3430
|
-
` + ` @tester — tests, builds, and shell-heavy verification
|
|
3477
|
+
` + `Allowed tools for orchestrator: read, search, planning-state, codebase-state, repo-memory, decision-trace, policy-engine, reflect, codegraph, load-rules, council, rtk-setup, hash-edit, failure-replay.
|
|
3431
3478
|
|
|
3432
|
-
` + `To
|
|
3479
|
+
` + `To disable this guard: set FLOWDECK_ORCHESTRATOR_GUARD=off`;
|
|
3433
3480
|
}
|
|
3434
3481
|
|
|
3435
3482
|
class OrchestratorGuard {
|
|
@@ -3461,12 +3508,21 @@ class OrchestratorGuard {
|
|
|
3461
3508
|
return;
|
|
3462
3509
|
if (sessionId !== this.primarySessionId)
|
|
3463
3510
|
return;
|
|
3464
|
-
if (
|
|
3511
|
+
if (isAlwaysAllowed(toolName))
|
|
3465
3512
|
return;
|
|
3466
3513
|
if (isBlocked2(toolName)) {
|
|
3467
3514
|
throw new Error(blockMessage(toolName));
|
|
3468
3515
|
}
|
|
3469
3516
|
}
|
|
3517
|
+
_isBlockedForTest(name) {
|
|
3518
|
+
return isBlocked2(name);
|
|
3519
|
+
}
|
|
3520
|
+
_isAllowedForTest(name) {
|
|
3521
|
+
return isAlwaysAllowed(name);
|
|
3522
|
+
}
|
|
3523
|
+
_setPrimarySessionIdForTest(id) {
|
|
3524
|
+
this.primarySessionId = id;
|
|
3525
|
+
}
|
|
3470
3526
|
}
|
|
3471
3527
|
function extractSessionId(event) {
|
|
3472
3528
|
const props = event.properties;
|
|
@@ -3597,14 +3653,143 @@ ${customAppendPrompt}`;
|
|
|
3597
3653
|
return base;
|
|
3598
3654
|
}
|
|
3599
3655
|
// src/agents/orchestrator.ts
|
|
3600
|
-
var ORCHESTRATOR_PROMPT = `You coordinate multi-agent execution.
|
|
3656
|
+
var ORCHESTRATOR_PROMPT = `You are the FlowDeck Orchestrator. You coordinate multi-agent execution. You do NOT execute tasks yourself.
|
|
3657
|
+
|
|
3658
|
+
## Core Rule: You Are a Router, Not a Worker
|
|
3659
|
+
|
|
3660
|
+
**NEVER** perform the following directly:
|
|
3661
|
+
- Write or edit files
|
|
3662
|
+
- Run shell commands, bash scripts, or terminal operations
|
|
3663
|
+
- Run tests or builds
|
|
3664
|
+
- Implement code
|
|
3665
|
+
- Do full investigations
|
|
3666
|
+
- Run the entire coding workflow yourself
|
|
3667
|
+
|
|
3668
|
+
Your ONLY job is to:
|
|
3669
|
+
1. **Analyze** the request
|
|
3670
|
+
2. **Classify** the task type and estimate complexity/risk/ambiguity
|
|
3671
|
+
3. **Choose** the appropriate workflow and execution path
|
|
3672
|
+
4. **Route** work to the correct agent or execution path
|
|
3673
|
+
5. **Supervise** progress
|
|
3674
|
+
6. **Collect** results
|
|
3675
|
+
7. **Return** the final coordinated outcome
|
|
3676
|
+
|
|
3677
|
+
## Routing-First Protocol
|
|
3678
|
+
|
|
3679
|
+
For EVERY user request, you MUST follow this exact sequence BEFORE any execution begins:
|
|
3680
|
+
|
|
3681
|
+
### Step 1: Analyze
|
|
3682
|
+
- Read STATE.md if it exists
|
|
3683
|
+
- Identify current phase and workflow class
|
|
3684
|
+
- Understand what the user is asking for
|
|
3685
|
+
|
|
3686
|
+
### Step 2: Classify
|
|
3687
|
+
Estimate:
|
|
3688
|
+
- Simplicity: Is this a rename, typo fix, config update, or simple question?
|
|
3689
|
+
- Confidence: How well does the request match known patterns?
|
|
3690
|
+
- Risk: Blast radius (files touched) and sensitivity (auth, security, data)
|
|
3691
|
+
- Codebase familiarity: Is the codebase mapping fresh?
|
|
3692
|
+
- Complexity: Cheap (classify, validate, summarize) vs expensive (architect, refactor)
|
|
3693
|
+
|
|
3694
|
+
### Step 3: Choose Workflow
|
|
3695
|
+
Select ONE of these workflow classes:
|
|
3696
|
+
|
|
3697
|
+
| Workflow Class | Execution Path | When to Select |
|
|
3698
|
+
|----------------|---------------|----------------|
|
|
3699
|
+
| \`quick\` | Route to @default-executor with \`direct-stock-tools\` mode | Simple, low-risk tasks (< 5 files, no ambiguity) |
|
|
3700
|
+
| \`standard\` | Plan with @planner → Execute with specialists → Verify with @reviewer | Normal implementation tasks |
|
|
3701
|
+
| \`explore\` | Discuss with @discusser → Plan with @planner → Execute with specialists | Ambiguous or unfamiliar tasks |
|
|
3702
|
+
| \`ui-heavy\` | Discuss with @discusser → Design with @design → Plan with @planner → Execute with specialists | UI/UX-heavy tasks |
|
|
3703
|
+
| \`bugfix\` | Discuss with @discusser → Fix with @debug-specialist / @backend-coder → Verify with @tester | Bug fixes |
|
|
3704
|
+
| \`docs-only\` | Route to @default-executor with \`inspect-only\` or \`simple-edit\` mode, or @writer for large docs | Documentation-only changes |
|
|
3705
|
+
| \`verify-heavy\` | Plan with @planner (enhanced checks) → Execute with specialists → Verify with @reviewer + @security-auditor | High blast radius or sensitive paths |
|
|
3706
|
+
|
|
3707
|
+
### Step 4: Log the Decision
|
|
3708
|
+
Before routing, you MUST emit a routing decision in this exact format:
|
|
3601
3709
|
|
|
3602
|
-
|
|
3710
|
+
\`\`\`
|
|
3711
|
+
## Routing Decision
|
|
3712
|
+
|
|
3713
|
+
**Request:** <brief summary of user request>
|
|
3714
|
+
**Classification:** <task type> | Confidence: <0.0-1.0>
|
|
3715
|
+
**Workflow Selected:** <workflow class>
|
|
3716
|
+
**Reason:** <why this workflow was chosen>
|
|
3717
|
+
**Execution Path:** <which agent(s) will execute>
|
|
3718
|
+
**Estimated Blast Radius:** <number of files or "unknown">
|
|
3719
|
+
\`\`\`
|
|
3603
3720
|
|
|
3604
|
-
|
|
3605
|
-
-
|
|
3606
|
-
-
|
|
3607
|
-
-
|
|
3721
|
+
### Step 5: Route and Supervise
|
|
3722
|
+
- Invoke the selected agent(s) using OpenCode's native @agent invocation
|
|
3723
|
+
- Provide clear, focused context
|
|
3724
|
+
- Wait for completion
|
|
3725
|
+
- Collect results
|
|
3726
|
+
- If escalation is needed, log the escalation and re-route
|
|
3727
|
+
|
|
3728
|
+
## What You MAY Do Directly
|
|
3729
|
+
|
|
3730
|
+
You may ONLY use these tools directly:
|
|
3731
|
+
- **read** — Read files for lightweight inspection
|
|
3732
|
+
- **search/grep** — Search codebase for patterns
|
|
3733
|
+
- **planning-state** — Read/update planning state
|
|
3734
|
+
- **codebase-state** — Read codebase documentation
|
|
3735
|
+
- **repo-memory** — Query architecture graph
|
|
3736
|
+
- **decision-trace** — Record decisions
|
|
3737
|
+
- **policy-engine** — Check policies
|
|
3738
|
+
- **reflect** — Gather session artifacts
|
|
3739
|
+
|
|
3740
|
+
You may NEVER use:
|
|
3741
|
+
- write, write_file, create, create_file
|
|
3742
|
+
- edit, edit_file, patch, apply_patch, str_replace_editor, str_replace
|
|
3743
|
+
- bash, run_bash, execute, run_command, terminal, shell
|
|
3744
|
+
- Any tool that modifies the filesystem or executes commands
|
|
3745
|
+
|
|
3746
|
+
## Execution Paths After Routing
|
|
3747
|
+
|
|
3748
|
+
### Direct Execution Path (via @default-executor)
|
|
3749
|
+
When workflow class is \`quick\` or \`docs-only\` (simple):
|
|
3750
|
+
- Route to @default-executor with an explicit mode:
|
|
3751
|
+
- \`direct-stock-tools\` — for simple file changes
|
|
3752
|
+
- \`quick-answer\` — for questions
|
|
3753
|
+
- \`inspect-only\` — for analysis/reporting
|
|
3754
|
+
- \`simple-edit\` — for surgical changes
|
|
3755
|
+
- The @default-executor is the worker; you are the coordinator
|
|
3756
|
+
|
|
3757
|
+
### Specialist Execution Path
|
|
3758
|
+
When workflow class is \`standard\`, \`explore\`, \`ui-heavy\`, \`bugfix\`, or \`verify-heavy\`:
|
|
3759
|
+
- Route implementation to role-specific specialists:
|
|
3760
|
+
- @backend-coder — server, API, business logic, database
|
|
3761
|
+
- @frontend-coder — UI components, client state, styling
|
|
3762
|
+
- @devops — CI/CD, deployment, infrastructure
|
|
3763
|
+
- @tester — tests, builds, verification
|
|
3764
|
+
- @researcher — API docs, library research
|
|
3765
|
+
- @reviewer — code quality review
|
|
3766
|
+
- @security-auditor — security review
|
|
3767
|
+
- @debug-specialist — root cause analysis
|
|
3768
|
+
|
|
3769
|
+
### Parallel Execution Patterns
|
|
3770
|
+
|
|
3771
|
+
Wave 1 (parallel):
|
|
3772
|
+
@researcher — research the library API
|
|
3773
|
+
@backend-coder — implement the model and types
|
|
3774
|
+
@tester — write test cases
|
|
3775
|
+
|
|
3776
|
+
Wave 2 (after Wave 1):
|
|
3777
|
+
@backend-coder — implement service using Wave 1 research
|
|
3778
|
+
@reviewer — review Wave 1 implementation
|
|
3779
|
+
|
|
3780
|
+
## Adaptive Routing and Escalation
|
|
3781
|
+
|
|
3782
|
+
If you discover during supervision that the initial workflow class is insufficient:
|
|
3783
|
+
1. Log the escalation with reason
|
|
3784
|
+
2. Select the richer workflow class
|
|
3785
|
+
3. Re-route the remaining work to appropriate agents
|
|
3786
|
+
4. You STILL do not execute the work yourself
|
|
3787
|
+
|
|
3788
|
+
Escalation paths:
|
|
3789
|
+
- quick → standard: when blast radius exceeds 3 files
|
|
3790
|
+
- standard → verify-heavy: when sensitive paths are touched
|
|
3791
|
+
- standard → ui-heavy: when design requirements emerge
|
|
3792
|
+
- explore → standard: when confidence improves after discussion
|
|
3608
3793
|
|
|
3609
3794
|
## Startup Behavior
|
|
3610
3795
|
|
|
@@ -3620,18 +3805,14 @@ If STATE.md does not exist, tell the user: No STATE.md found. Run /fd-map-codeba
|
|
|
3620
3805
|
Read STATE.md to determine the current phase and workflow class.
|
|
3621
3806
|
|
|
3622
3807
|
The orchestrator may run in any phase, but should respect the workflow class:
|
|
3623
|
-
- For \`quick\` workflows:
|
|
3808
|
+
- For \`quick\` workflows: route to @default-executor, skip discuss/plan.
|
|
3624
3809
|
- For \`standard\` workflows: plan → execute → verify.
|
|
3625
3810
|
- For \`explore\` workflows: discuss → plan → execute → verify.
|
|
3626
3811
|
- For \`ui-heavy\` workflows: discuss → design → plan → execute → verify.
|
|
3627
3812
|
- For \`bugfix\` workflows: discuss → fix-bug → verify.
|
|
3628
|
-
- For \`docs-only\` workflows:
|
|
3813
|
+
- For \`docs-only\` workflows: route to @default-executor or @writer.
|
|
3629
3814
|
- For \`verify-heavy\` workflows: plan → execute → verify (with enhanced checks).
|
|
3630
3815
|
|
|
3631
|
-
If the project is in a different phase than expected:
|
|
3632
|
-
- Suggest the correct next command but allow override for adaptive workflows.
|
|
3633
|
-
- Log any phase skips with reasons.
|
|
3634
|
-
|
|
3635
3816
|
## State-First Read Strategy
|
|
3636
3817
|
|
|
3637
3818
|
Before invoking an agent that needs codebase context:
|
|
@@ -3649,60 +3830,6 @@ For each incomplete step in PLAN.md:
|
|
|
3649
3830
|
4. Wait for completion, then update and re-read STATE.md.
|
|
3650
3831
|
5. Move to the next incomplete step.
|
|
3651
3832
|
|
|
3652
|
-
## Implementation Routing
|
|
3653
|
-
|
|
3654
|
-
When a plan step requires implementation, route to a role-specific agent:
|
|
3655
|
-
- Use @backend-coder for server, API, business logic, database, and non-UI application code.
|
|
3656
|
-
- Use @frontend-coder for UI components, client state, styling, and interaction behavior.
|
|
3657
|
-
- Use @devops for CI/CD workflows, deployment, infrastructure, runtime config, and operations scripts.
|
|
3658
|
-
- Split mixed-domain steps into smaller specialist handoffs when that reduces risk.
|
|
3659
|
-
|
|
3660
|
-
## Agent Team
|
|
3661
|
-
|
|
3662
|
-
- @design: discovery, UX planning, wireframes, visual system, implementation handoff, design fidelity review
|
|
3663
|
-
- @backend-coder: backend code implementation
|
|
3664
|
-
- @frontend-coder: frontend code implementation
|
|
3665
|
-
- @devops: CI/CD and infrastructure implementation
|
|
3666
|
-
- @researcher: API docs and library usage
|
|
3667
|
-
- @tester: writing and running tests
|
|
3668
|
-
- @reviewer: code quality review
|
|
3669
|
-
- @writer: documentation
|
|
3670
|
-
- @mapper: codebase mapping to .codebase/
|
|
3671
|
-
- @architect: system design and ADRs
|
|
3672
|
-
- @security-auditor: security review
|
|
3673
|
-
- @code-explorer: reading unfamiliar code
|
|
3674
|
-
- @debug-specialist: root cause analysis
|
|
3675
|
-
- @build-error-resolver: build and compile failures
|
|
3676
|
-
- @doc-updater: updating existing docs
|
|
3677
|
-
- @task-splitter: decomposing complex tasks
|
|
3678
|
-
- @discusser: requirements extraction
|
|
3679
|
-
- @plan-checker: plan quality review
|
|
3680
|
-
- @planner: feature planning
|
|
3681
|
-
- @performance-optimizer: performance analysis
|
|
3682
|
-
- @refactor-guide: safe refactoring
|
|
3683
|
-
|
|
3684
|
-
## Adaptive Workflow Routing
|
|
3685
|
-
|
|
3686
|
-
The orchestrator reads the workflow class from STATE.md and adapts its behavior:
|
|
3687
|
-
|
|
3688
|
-
| Workflow Class | Stages | When Used |
|
|
3689
|
-
|----------------|--------|-----------|
|
|
3690
|
-
| \`quick\` | execute → verify | Simple, low-risk tasks (< 5 files, no ambiguity) |
|
|
3691
|
-
| \`standard\` | plan → execute → verify | Normal implementation tasks |
|
|
3692
|
-
| \`explore\` | discuss → plan → execute → verify | Ambiguous or unfamiliar tasks |
|
|
3693
|
-
| \`ui-heavy\` | discuss → design → plan → execute → verify | UI/UX-heavy tasks |
|
|
3694
|
-
| \`bugfix\` | discuss → fix-bug → verify | Bug fixes |
|
|
3695
|
-
| \`docs-only\` | write-docs → verify | Documentation-only changes |
|
|
3696
|
-
| \`verify-heavy\` | plan → execute → verify | High blast radius or sensitive paths |
|
|
3697
|
-
|
|
3698
|
-
- discuss: requirements extraction with @discusser (only for explore/bugfix/ui-heavy)
|
|
3699
|
-
- plan: plan creation with @planner, review with @plan-checker (skip for quick/docs-only)
|
|
3700
|
-
- design: UX structure with @design (only for ui-heavy)
|
|
3701
|
-
- execute: implementation with appropriate specialists
|
|
3702
|
-
- verify: review with @reviewer and @security-auditor (always run for edited code)
|
|
3703
|
-
|
|
3704
|
-
The workflow class is chosen by scoring task complexity, confidence, risk, and codebase familiarity. Prefer the lightest workflow that is sufficient. Escalate to a richer workflow only when evidence shows the current path is insufficient.
|
|
3705
|
-
|
|
3706
3833
|
## Tracking
|
|
3707
3834
|
|
|
3708
3835
|
After each step completes:
|
|
@@ -3730,6 +3857,11 @@ When a task required unusual human guidance, a novel solution strategy, or expos
|
|
|
3730
3857
|
|
|
3731
3858
|
Do NOT create a skill for routine tasks. Only capture genuinely novel or reusable patterns.`;
|
|
3732
3859
|
var AGENT_DESCRIPTIONS = {
|
|
3860
|
+
"default-executor": `@default-executor
|
|
3861
|
+
- Role: Default execution worker for simple, direct tasks
|
|
3862
|
+
- Permissions: Read/write files, shell execution
|
|
3863
|
+
- Best for: Quick answers, simple edits, inspect-only analysis, direct stock-tool usage
|
|
3864
|
+
- Use when: Workflow class is \`quick\` or \`docs-only\`, or a single focused task needs direct execution`,
|
|
3733
3865
|
design: `@design
|
|
3734
3866
|
- Role: Runs design-first workflow for user-facing tasks
|
|
3735
3867
|
- Permissions: Read/write files
|
|
@@ -3858,8 +3990,9 @@ ${enabledAgents}
|
|
|
3858
3990
|
- Review available agents before acting
|
|
3859
3991
|
- Reference paths and line numbers instead of pasting full files
|
|
3860
3992
|
- Provide context summaries, then let specialists inspect what they need
|
|
3861
|
-
- Use direct built-in tools
|
|
3862
|
-
-
|
|
3993
|
+
- Use direct built-in tools ONLY for lightweight reading and status tracking
|
|
3994
|
+
- NEVER use write/edit/bash tools yourself — always route execution to agents
|
|
3995
|
+
- Log every routing decision before handing off work
|
|
3863
3996
|
|
|
3864
3997
|
</Delegation>`;
|
|
3865
3998
|
}
|
|
@@ -3868,7 +4001,7 @@ function createOrchestratorAgent(model, customPrompt, customAppendPrompt, disabl
|
|
|
3868
4001
|
const prompt = resolvePrompt(basePrompt, customPrompt, customAppendPrompt);
|
|
3869
4002
|
const definition = {
|
|
3870
4003
|
name: "orchestrator",
|
|
3871
|
-
description: "AI coding orchestrator that coordinates specialist agents and
|
|
4004
|
+
description: "AI coding orchestrator that coordinates specialist agents. Routes all work to appropriate agents and workflows. Does not execute tasks directly.",
|
|
3872
4005
|
config: {
|
|
3873
4006
|
temperature: 0.1,
|
|
3874
4007
|
prompt
|
|
@@ -6553,9 +6686,71 @@ function createSupervisorAgent(model, customPrompt, customAppendPrompt) {
|
|
|
6553
6686
|
return definition;
|
|
6554
6687
|
}
|
|
6555
6688
|
|
|
6689
|
+
// src/agents/default-executor.ts
|
|
6690
|
+
var DEFAULT_EXECUTOR_PROMPT = `You are the Default Execution Agent — the worker that handles simple, direct tasks when the orchestrator has explicitly routed work to you through a chosen direct workflow.
|
|
6691
|
+
|
|
6692
|
+
## Your Role
|
|
6693
|
+
|
|
6694
|
+
You execute. You do NOT route, plan, or orchestrate.
|
|
6695
|
+
You receive a specific task from the orchestrator with a chosen execution mode, and you carry it out using the full set of available tools.
|
|
6696
|
+
|
|
6697
|
+
## Execution Modes
|
|
6698
|
+
|
|
6699
|
+
The orchestrator selects one of these modes when routing to you:
|
|
6700
|
+
|
|
6701
|
+
- **direct-stock-tools** — Use OpenCode's built-in read/search/write/edit/bash tools directly to complete a focused task that fits in < 5 files and has no ambiguity.
|
|
6702
|
+
- **quick-answer** — Answer a question or provide information using read/search tools only. No file modifications.
|
|
6703
|
+
- **inspect-only** — Read and analyze code to answer questions or produce reports. No modifications.
|
|
6704
|
+
- **simple-edit** — Make a small, surgical change (rename, typo fix, constant update, config change). Must be reversible and low-risk.
|
|
6705
|
+
|
|
6706
|
+
## Rules
|
|
6707
|
+
|
|
6708
|
+
1. **Execute exactly what was routed to you.** Do not expand scope.
|
|
6709
|
+
2. **Do not invent new workflows.** If the task is bigger than expected, report back to the orchestrator — do not silently absorb it.
|
|
6710
|
+
3. **Use the simplest tool for the job.** Prefer read/search for investigation, write/edit for changes, bash for verification.
|
|
6711
|
+
4. **Report completion clearly.** Summarize what was done and any issues encountered.
|
|
6712
|
+
5. **Escalate if complexity emerges.** If you discover the task touches > 5 files, requires architectural decisions, or involves security-sensitive paths, stop and report to the orchestrator for re-routing.
|
|
6713
|
+
|
|
6714
|
+
## Anti-Patterns
|
|
6715
|
+
|
|
6716
|
+
- Do NOT act as an orchestrator yourself.
|
|
6717
|
+
- Do NOT route work to other agents.
|
|
6718
|
+
- Do NOT silently expand a "simple edit" into a full refactor.
|
|
6719
|
+
- Do NOT bypass the orchestrator's routing decision.
|
|
6720
|
+
|
|
6721
|
+
## Completion Format
|
|
6722
|
+
|
|
6723
|
+
When done, respond with:
|
|
6724
|
+
|
|
6725
|
+
\`\`\`
|
|
6726
|
+
## Execution Complete
|
|
6727
|
+
|
|
6728
|
+
**Mode:** <the mode you were given>
|
|
6729
|
+
**Files touched:** <list or "none">
|
|
6730
|
+
**Summary:** <what was done>
|
|
6731
|
+
**Verification:** <how you confirmed it works>
|
|
6732
|
+
**Issues:** <any problems found, or "none">
|
|
6733
|
+
\`\`\``;
|
|
6734
|
+
function createDefaultExecutorAgent(model, customPrompt, customAppendPrompt) {
|
|
6735
|
+
const prompt = resolvePrompt(DEFAULT_EXECUTOR_PROMPT, customPrompt, customAppendPrompt);
|
|
6736
|
+
const definition = {
|
|
6737
|
+
name: "default-executor",
|
|
6738
|
+
description: "Default execution worker for direct, simple tasks routed by the orchestrator. Handles quick-answer, inspect-only, simple-edit, and direct-stock-tools workflows.",
|
|
6739
|
+
config: {
|
|
6740
|
+
temperature: 0.1,
|
|
6741
|
+
prompt
|
|
6742
|
+
}
|
|
6743
|
+
};
|
|
6744
|
+
if (typeof model === "string" && model) {
|
|
6745
|
+
definition.config.model = model;
|
|
6746
|
+
}
|
|
6747
|
+
return definition;
|
|
6748
|
+
}
|
|
6749
|
+
|
|
6556
6750
|
// src/agents/index.ts
|
|
6557
6751
|
var AGENT_NAMES = [
|
|
6558
6752
|
"orchestrator",
|
|
6753
|
+
"default-executor",
|
|
6559
6754
|
"planner",
|
|
6560
6755
|
"backend-coder",
|
|
6561
6756
|
"frontend-coder",
|
|
@@ -6598,6 +6793,8 @@ function createAgent(name, model, customPrompt, customAppendPrompt) {
|
|
|
6598
6793
|
switch (name) {
|
|
6599
6794
|
case "orchestrator":
|
|
6600
6795
|
return createOrchestratorAgent(model, customPrompt, customAppendPrompt);
|
|
6796
|
+
case "default-executor":
|
|
6797
|
+
return createDefaultExecutorAgent(model, customPrompt, customAppendPrompt);
|
|
6601
6798
|
case "planner":
|
|
6602
6799
|
return createPlannerAgent(model, customPrompt, customAppendPrompt);
|
|
6603
6800
|
case "backend-coder":
|
package/package.json
CHANGED
|
@@ -7,23 +7,40 @@ languages: []
|
|
|
7
7
|
|
|
8
8
|
# Agent Orchestration
|
|
9
9
|
|
|
10
|
-
FlowDeck provides
|
|
10
|
+
FlowDeck provides specialist agents. The orchestrator routes work to them. The orchestrator does NOT execute work itself.
|
|
11
|
+
|
|
12
|
+
## Core Principle: Orchestrator = Router, Not Worker
|
|
13
|
+
|
|
14
|
+
The orchestrator's ONLY responsibilities:
|
|
15
|
+
1. **Analyze** the request
|
|
16
|
+
2. **Classify** the task type
|
|
17
|
+
3. **Choose** the appropriate workflow
|
|
18
|
+
4. **Route** work to the correct agent
|
|
19
|
+
5. **Supervise** progress
|
|
20
|
+
6. **Collect** results
|
|
21
|
+
7. **Return** the final coordinated outcome
|
|
22
|
+
|
|
23
|
+
The orchestrator NEVER:
|
|
24
|
+
- Writes or edits files directly
|
|
25
|
+
- Runs shell commands or builds
|
|
26
|
+
- Implements code itself
|
|
27
|
+
- Runs the full coding workflow itself
|
|
11
28
|
|
|
12
29
|
## Available FlowDeck Agents
|
|
13
30
|
|
|
14
31
|
| Agent | Purpose | When to Use |
|
|
15
32
|
|-------|---------|------------|
|
|
33
|
+
| `@orchestrator` | **Coordinate multi-agent execution** | Managing a full feature delivery — analyzes, classifies, routes, supervises |
|
|
34
|
+
| `@default-executor` | **Execute simple direct tasks** | Quick answers, simple edits, inspect-only analysis, direct stock-tool usage |
|
|
16
35
|
| `@architect` | System design, ADRs, API contracts | Planning new modules, API changes, schema changes |
|
|
17
36
|
| `@build-error-resolver` | Fix build failures and type errors | Immediately when build fails |
|
|
18
|
-
| `@build-resolver` | Diagnose and fix build/compile failures | When build breaks and cause is unclear |
|
|
19
37
|
| `@code-explorer` | Map unfamiliar codebase structure | Before modifying unfamiliar code |
|
|
20
|
-
| `@backend-coder` | Implement features and fixes | All code implementation |
|
|
38
|
+
| `@backend-coder` | Implement features and fixes | All backend code implementation |
|
|
21
39
|
| `@debug-specialist` | Root cause analysis for bugs | When a bug needs deep investigation |
|
|
22
40
|
| `@discusser` | Extract requirements via Q&A | Starting a new feature or phase |
|
|
23
41
|
| `@doc-updater` | Update docs after code changes | After implementation completes |
|
|
24
42
|
| `@plan-checker` | Review PLAN.md before execution | Before executing any plan |
|
|
25
43
|
| `@mapper` | Map codebase to .codebase/ docs | Running /fd-map-codebase |
|
|
26
|
-
| `@orchestrator` | Coordinate multi-agent execution | Managing a full feature delivery |
|
|
27
44
|
| `@task-splitter` | Decompose parallel workstreams | When tasks can run simultaneously |
|
|
28
45
|
| `@performance-optimizer` | Profile and fix performance issues | When app is slow or before release |
|
|
29
46
|
| `@planner` | Create detailed implementation plans | Any multi-file feature |
|
|
@@ -31,16 +48,52 @@ FlowDeck provides 23 specialist agents. Each has a specific role. Using the righ
|
|
|
31
48
|
| `@researcher` | Research APIs, docs, best practices | Using an unfamiliar library or API |
|
|
32
49
|
| `@reviewer` | Code quality and convention review | After writing code, before PRs |
|
|
33
50
|
| `@security-auditor` | Deep security audit | Before merging security-sensitive code |
|
|
34
|
-
| `@task-splitter` | Decompose tasks into parallel tracks | Complex features with parallel work |
|
|
35
51
|
| `@tester` | Write and run tests (TDD) | Implementing features or fixing bugs |
|
|
36
52
|
| `@writer` | Draft project documentation | Writing or updating docs |
|
|
37
53
|
|
|
38
|
-
##
|
|
54
|
+
## Execution Paths
|
|
55
|
+
|
|
56
|
+
After the orchestrator analyzes and classifies a request, it selects ONE execution path:
|
|
57
|
+
|
|
58
|
+
### Direct Execution Path (via @default-executor)
|
|
59
|
+
|
|
60
|
+
For simple, low-risk tasks (< 5 files, no ambiguity):
|
|
61
|
+
- **Mode:** `direct-stock-tools` — use built-in tools directly for focused changes
|
|
62
|
+
- **Mode:** `quick-answer` — answer questions, no file modifications
|
|
63
|
+
- **Mode:** `inspect-only` — read and analyze, produce reports
|
|
64
|
+
- **Mode:** `simple-edit` — surgical changes (rename, typo fix, constant update)
|
|
65
|
+
|
|
66
|
+
The orchestrator routes to `@default-executor` with the chosen mode. The orchestrator does NOT do the work itself.
|
|
67
|
+
|
|
68
|
+
### Specialist Execution Path
|
|
69
|
+
|
|
70
|
+
For normal or complex tasks:
|
|
71
|
+
- Implementation → `@backend-coder`, `@frontend-coder`, `@devops`
|
|
72
|
+
- Testing → `@tester`
|
|
73
|
+
- Research → `@researcher`
|
|
74
|
+
- Review → `@reviewer`, `@security-auditor`
|
|
75
|
+
- Debug → `@debug-specialist`
|
|
76
|
+
- Docs → `@writer`, `@doc-updater`
|
|
77
|
+
|
|
78
|
+
### Workflow Classes
|
|
79
|
+
|
|
80
|
+
| Class | Stages | Executor | When Selected |
|
|
81
|
+
|-------|--------|----------|---------------|
|
|
82
|
+
| `quick` | execute → verify | `@default-executor` | Simple, low-risk tasks (< 5 files, no ambiguity) |
|
|
83
|
+
| `standard` | plan → execute → verify | Specialists | Normal implementation tasks |
|
|
84
|
+
| `explore` | discuss → plan → execute → verify | Specialists | Ambiguous or unfamiliar tasks |
|
|
85
|
+
| `ui-heavy` | discuss → design → plan → execute → verify | Specialists | UI/UX-heavy tasks |
|
|
86
|
+
| `bugfix` | discuss → fix-bug → verify | Specialists | Bug fixes |
|
|
87
|
+
| `docs-only` | write-docs → verify | `@default-executor` or `@writer` | Documentation-only changes |
|
|
88
|
+
| `verify-heavy` | plan → execute → verify | Specialists | High blast radius or sensitive paths |
|
|
89
|
+
|
|
90
|
+
## When to Use Agents Immediately
|
|
39
91
|
|
|
40
92
|
These situations should trigger agent use automatically:
|
|
41
93
|
|
|
42
94
|
| Situation | Agent |
|
|
43
95
|
|-----------|-------|
|
|
96
|
+
| Simple task (< 5 files, no ambiguity) | `@default-executor` |
|
|
44
97
|
| Complex feature spanning 3+ files | `@planner` first, then `@backend-coder` |
|
|
45
98
|
| Code was just written | `@reviewer` |
|
|
46
99
|
| Build fails | `@build-error-resolver` |
|
|
@@ -75,47 +128,34 @@ Parallel:
|
|
|
75
128
|
|
|
76
129
|
## Adaptive Workflow Routing
|
|
77
130
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
### Workflow Classes
|
|
81
|
-
|
|
82
|
-
| Class | Stages | When Selected |
|
|
83
|
-
|-------|--------|---------------|
|
|
84
|
-
| `quick` | execute → verify | Simple, low-risk tasks (< 5 files, no ambiguity) |
|
|
85
|
-
| `standard` | plan → execute → verify | Normal implementation tasks |
|
|
86
|
-
| `explore` | discuss → plan → execute → verify | Ambiguous or unfamiliar tasks |
|
|
87
|
-
| `ui-heavy` | discuss → design → plan → execute → verify | UI/UX-heavy tasks |
|
|
88
|
-
| `bugfix` | discuss → fix-bug → verify | Bug fixes |
|
|
89
|
-
| `docs-only` | write-docs → verify | Documentation-only changes |
|
|
90
|
-
| `verify-heavy` | plan → execute → verify | High blast radius or sensitive paths |
|
|
131
|
+
The orchestrator selects the most appropriate workflow class at runtime based on task context, complexity, risk, and codebase familiarity.
|
|
91
132
|
|
|
92
133
|
### Routing Criteria
|
|
93
134
|
|
|
94
|
-
The orchestrator scores tasks across these dimensions:
|
|
95
135
|
- **Simplicity**: Is the task a simple rename, typo fix, or config update?
|
|
96
136
|
- **Confidence**: How well does the task description match known patterns?
|
|
97
137
|
- **Risk**: Is the blast radius small (< 3 files) and are no sensitive paths touched?
|
|
98
138
|
- **Codebase familiarity**: Is the codebase mapping fresh (< 24h)?
|
|
99
139
|
- **Complexity**: Is the task cheap (classify, validate, summarize) vs expensive (architect, refactor entire system)?
|
|
100
140
|
|
|
101
|
-
The
|
|
102
|
-
|
|
103
|
-
### Phase Behavior
|
|
104
|
-
|
|
105
|
-
- **quick / docs-only**: Skip discuss and plan phases. Run execute directly.
|
|
106
|
-
- **standard / verify-heavy**: Skip discuss. Start with plan.
|
|
107
|
-
- **explore / bugfix / ui-heavy**: Include discuss phase for requirements gathering.
|
|
108
|
-
- **ui-heavy**: Always include design phase before execute.
|
|
141
|
+
The orchestrator prefers the lightest workflow that is sufficient. Escalate to a richer workflow only when evidence shows the current path is insufficient.
|
|
109
142
|
|
|
110
143
|
### Escalation
|
|
111
144
|
|
|
112
|
-
If the orchestrator discovers during
|
|
145
|
+
If the orchestrator discovers during supervision that the initial workflow class is insufficient, it escalates and re-routes:
|
|
113
146
|
- quick → standard: when blast radius exceeds 3 files
|
|
114
147
|
- standard → verify-heavy: when sensitive paths are touched
|
|
115
148
|
- standard → ui-heavy: when design requirements emerge
|
|
116
149
|
- explore → standard: when confidence improves after discussion
|
|
117
150
|
|
|
118
|
-
Escalation is logged with reasons and triggers
|
|
151
|
+
Escalation is logged with reasons and triggers re-routing to appropriate agents. The orchestrator STILL does not execute the work itself.
|
|
152
|
+
|
|
153
|
+
### Phase Behavior
|
|
154
|
+
|
|
155
|
+
- **quick / docs-only**: Skip discuss and plan phases. Route to `@default-executor`.
|
|
156
|
+
- **standard / verify-heavy**: Skip discuss. Start with plan.
|
|
157
|
+
- **explore / bugfix / ui-heavy**: Include discuss phase for requirements gathering.
|
|
158
|
+
- **ui-heavy**: Always include design phase before execute.
|
|
119
159
|
|
|
120
160
|
### Phase Gating (Relaxed)
|
|
121
161
|
|
|
@@ -123,3 +163,21 @@ Phase gating is advisory, not absolute:
|
|
|
123
163
|
- For `quick` and `docs-only` workflows: phases may be skipped without override.
|
|
124
164
|
- For other workflows: follow the phase order for the selected workflow class.
|
|
125
165
|
- The orchestrator may override phase gating when the workflow class permits it.
|
|
166
|
+
|
|
167
|
+
## Tool Access Enforcement
|
|
168
|
+
|
|
169
|
+
The orchestrator is restricted from using execution tools directly:
|
|
170
|
+
|
|
171
|
+
**Blocked for orchestrator:**
|
|
172
|
+
- File writes: `write`, `create`, `edit`, `patch`, `str_replace_editor`
|
|
173
|
+
- Shell execution: `bash`, `execute`, `terminal`, `shell`
|
|
174
|
+
- Build/test runners: `npm`, `bun`, `cargo`, `make`
|
|
175
|
+
- Container/deployment: `docker`, `kubectl`, `terraform`
|
|
176
|
+
|
|
177
|
+
**Allowed for orchestrator:**
|
|
178
|
+
- Read/search: `read`, `search`, `grep`, `glob`
|
|
179
|
+
- Planning: `planning-state`, `codebase-state`, `repo-memory`
|
|
180
|
+
- Governance: `decision-trace`, `policy-engine`, `reflect`
|
|
181
|
+
- Analysis: `codegraph`, `load-rules`, `council`
|
|
182
|
+
|
|
183
|
+
All file modifications and command execution MUST be routed to `@default-executor` or specialist agents.
|