@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.
@@ -0,0 +1,3 @@
1
+ import type { AgentDefinition } from './types';
2
+ export declare function createDefaultExecutorAgent(model?: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
3
+ //# sourceMappingURL=default-executor.d.ts.map
@@ -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"}
@@ -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":"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"}
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;AAyQ/C,wBAAgB,uBAAuB,CACrC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CA4BR;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
+ {"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 should
6
- * route file writes and shell-heavy execution to specialist agents instead of
7
- * using blocked tools in the primary session.
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 enable: set FLOWDECK_ORCHESTRATOR_GUARD=on in the environment.
10
- * Default is OFF.
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;AAuDH,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;CASjD"}
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 !== "on";
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.toLowerCase().replace(/[-_]/g, "");
3447
+ const norm = normalizeToolName(name);
3413
3448
  for (const b of BLOCKED_TOOLS) {
3414
- if (norm === b.replace(/[-_]/g, "") || norm === b.replace(/_/g, ""))
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
- ` + `Use built-in read/search tools for lightweight inspection, then route execution with OpenCode's native @agent invocation.
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
- ` + `Recommended handoffs:
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 enable this guard: set FLOWDECK_ORCHESTRATOR_GUARD=on`;
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 (ALWAYS_ALLOWED.has(toolName))
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. Read planning state, inspect the codebase with built-in tools when needed, and route specialized work to the right agent using OpenCode's native agent invocation.
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
- ## Operating Model
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
- - Start by reading STATE.md and the active PLAN.md.
3605
- - Use built-in read/search tools directly for lightweight inspection and progress tracking.
3606
- - Use native agent routing for implementation, testing, deep research, reviews, and other specialist work.
3607
- - Do not rely on the removed FlowDeck-specific delegation tools.
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: run directly in execute phase, skip discuss/plan.
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: write-docs verify.
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 yourself for lightweight reading and status tracking
3862
- - Use native agent routing when specialist work or deeper execution is the better fit
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 built-in tools for execution",
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dv.nghiem/flowdeck",
3
- "version": "0.4.8",
3
+ "version": "0.4.9",
4
4
  "description": "FlowDeck — structured planning and execution workflows for OpenCode",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -7,23 +7,40 @@ languages: []
7
7
 
8
8
  # Agent Orchestration
9
9
 
10
- FlowDeck provides 23 specialist agents. Each has a specific role. Using the right agent gets better results faster.
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
- ## When to Use Agents Immediately (No Prompting Needed)
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
- FlowDeck uses adaptive workflow routing. The orchestrator selects the most appropriate workflow class at runtime based on task context, complexity, risk, and codebase familiarity.
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 workflow class with the highest score is selected. The orchestrator prefers the lightest workflow that is sufficient.
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 execution that the initial workflow class is insufficient, it escalates to a richer workflow:
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 replanning.
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.