RFC: Decouple /workflow from Claude Code, cross-platform parallel workflow implementation based on native CAT architecture

[thiswind]

RFC: Decouple /workflow from Claude Code, cross-platform parallel workflow implementation based on native CAT architecture

Summary

The original design of /workflow in Issue #2 heavily relies on Claude Code exclusive run_in_background sub-agent API, restricting this large-scale parallel multi-agent capability to environments with Claude Code extension installed. Combined with the cross-platform parallel task verification data from Issue #3, this RFC delivers a complete technical design to implement full-featured /workflow without binding to any proprietary platform interface.

The core idea: Reuse all upper-layer native CAT modules including /discuss staff planning system, standardized PLAN-*.md task specification, unified workspace archiving mechanism. Only add a cross-platform agent scheduler abstraction layer at the bottom execution layer, take Cursor native Background Task / multitask as the core parallel execution carrier, and retain all original /workflow user experience, constraint rules and archive logic.

Related Issues:

1. Original /workflow capability RFC: [RFC] Peer executors under CAT: /crew vs Claude Code Dynamic Workflows (/workflow or /ultra) #2
2. Cross-platform parallel sub-agent capability test report: Capability Test: Parallel Background Sub-Agent Execution #3

1. Background & Existing Pain Points

1.1 Defect of the original tied design

The initial workflow scheme proposed in #2 uses Claude Code exclusive background sub-agent as the only underlying runtime:

• Only available when the user installs Claude Code extension;
• Pure stock Cursor IDE environment cannot activate /workflow, splitting CAT's functional experience;
• The whole feature is bound to a single LLM plugin, lacking long-term architecture scalability.

1.2 Sufficient verified alternative capabilities

Issue #3 finished comprehensive parallel execution tests on 3 carriers: Claude Code Agent, TRAE SOLO Task, Cursor IDE native Task. Key verified conclusions:

1. Cursor built-in multitask / Background Task can provide fully isolated sub-agent context, independent runtime, asynchronous result aggregation, same as Claude Code sub-agent;
2. Independent task read-only scanning, multi-branch Git audit, full directory traversal and other core workflow scenarios run stably under Cursor native task;
3. Sub-task logs can be separated and stored, only summary data is aggregated to the main session, avoiding main context bloat.

1.3 Core value to retain

All business logic of the original /workflow remains unchanged, including:

• Equal peer executor status with /crew;
• Driven entirely by standardized PLAN-*.md documents;
• Main agent supervision, autonomous block resolution within task scope;
• Offline unattended batch delivery support;
• Full traceable execution records stored under ai_workspace.

2. Overall Technical Architecture Adjustment

CAT three-layer core architecture remains untouched, only inject a cross-platform scheduling abstraction layer between PLAN parsing layer and underlying platform execution API.

2.1 Original CAT Hierarchy (Unchanged)

1. Planning Layer (Staff Department): /discuss command, generate standardized PLAN task file
2. Task Definition Layer: Parse Executor: crew / workflow tag from PLAN, split subtasks
3. New Added Cross-Platform Scheduler Abstraction Layer (core modification)
4. Platform Runtime Layer: Original Claude Code API / Cursor native Task / TRAE SOLO Task

2.2 New Abstraction Layer: AgentScheduler Unified Scheduling Module

Single unified entry for all parallel task requests, with automatic environment detection branch logic:

1. Environment detection logic
   • If Claude Code extension exists: Fallback to original run_in_background sub-agent logic (compatible with old usage)
   • If pure stock Cursor IDE: Switch to Cursor native multitask batch background task as parallel carrier
   • If TRAE SOLO runtime detected: Adopt TRAE independent Task runner
2. Unified external interface
   Expose identical calling parameters to upper PLAN parsing module, upper code zero modification, no user syntax change.
3. Unified constraint encapsulation
   Uniformly implement core workflow rules at scheduler layer, regardless of underlying platform:
   • All subtasks run with isolated context
   • Subtasks only output structured summary to main session, detailed logs isolated in independent subfolder
   • Subtask modification authority limited, heavy write operations still route to /crew serial executor
   • Automatic pause & human prompt when task blocked

3. Detailed Implementation Design

3.1 Zero modification for upper user layer

1. User command: /workflow (alias /ultra) keep consistent with original RFC [RFC] Peer executors under CAT: /crew vs Claude Code Dynamic Workflows (/workflow or /ultra) #2
2. PLAN marking syntax unchanged: Executor: workflow at global or single-stage level
3. Archive specification unchanged: All runtime records, task IDs, subtask logs uniformly stored in ai_workspace theme directory, full two-way traceability

3.2 Core capability equivalence implementation on pure Cursor

All original Claude sub-agent features replaced by Cursor native capability:

Original Claude Code exclusive feature	Equivalent Cursor native implementation
Isolated background sub-agent context	Cursor Background Task independent runtime
Batch parallel subtask execution	Single-round batch multitask task group scheduling
Asynchronous block notification to main session	Task pause callback alert mechanism
Offline unattended batch run	Cursor background persistent task process
Separate storage of subtask detailed logs	Independent subfolder under ai_workspace for each subtask

3.3 Automatic downgrade compatibility logic

For old low-version Cursor without Background Task capability:

• /workflow will not throw runtime error;
• Automatically downgrade to serial batch task execution;
• Add warning prompt in output: Parallel acceleration unavailable under current IDE version.

3.4 File & Code Modification Scope (Low workload)

1. New file: src/scheduler/agent_scheduler.py unified cross-platform scheduler
2. Minor modification: PLAN parser module, inject scheduler instead of direct platform API call
3. Minor modification: /workflow command entry, forward all requests to unified scheduler
4. No modification: /discuss planning module, /crew serial executor, full archive system, workspace storage logic

4. Scene Adaptation & Execution Split Rules

Consistent with the definition in Issue #2, two equal executors still exist after refactoring:

1. /crew serial executor
   Applicable: Multi-stage dependent modification tasks, release, paper revision, scenarios requiring strict process control
2. Cross-platform /workflow parallel executor
   Applicable: Full warehouse scan, multi-Git-branch comparison, batch document audit, mass independent read-only subtasks, offline batch delivery

Constraint supplement: All subtasks launched by /workflow are limited to read-only reconnaissance by default. Any file bulk write, code refactor, multi-stage dependent modification tasks are forced to switch to /crew to guarantee execution determinism.

5. Advantages After Decoupling Refactor

1. Platform neutrality: /workflow becomes native general CAT capability, no longer limited to users with Claude Code installed, expanding full user coverage
2. Architecture scalability: Adding new runtime platforms only requires adding a branch in AgentScheduler, zero changes to planning & archive upper layers
3. Zero user migration cost: PLAN syntax, command names, output format, archive structure fully consistent with original design
4. Retain all core innovations of CAT: Separation of staff planning layer and execution layer, standardized persistent PLAN file, traceable task records
5. Lower usage threshold: Cursor native multitask does not require handwritten JS workflow scripts; subtask splitting auto-generated from PLAN document

6. Undecided Discussion Items (To be confirmed in review)

1. Naming: Keep /workflow as official command, retain /ultra as optional alias
2. Auto conversion script: Whether to provide plan_to_workflow.py to convert PLAN stages into platform task batch definitions
3. Mandatory marking rule: Whether PLAN must explicitly write Executor: workflow to enable parallel mode
4. Offline delivery standard: Complete PLAN integrity requirements to allow user exit after submission
5. Log storage strategy: Unified separate subtask log directory under ai_workspace

7. Acceptance Standard for Merge

1. In pure Cursor environment without Claude Code: /workflow can launch multiple parallel isolated subtasks, complete audit & directory scan test cases from Issue Capability Test: Parallel Background Sub-Agent Execution #3
2. In environment with Claude Code installed: Original background sub-agent logic works normally, backward compatible
3. All PLAN syntax, command usage, archive file structure consistent with original RFC [RFC] Peer executors under CAT: /crew vs Claude Code Dynamic Workflows (/workflow or /ultra) #2
4. Low-version Cursor downgrade serial execution works without crash
5. All task execution logs can be traced back to corresponding PLAN document via task ID

[thiswind]

Progress: command layer shipped in v0.20.0 ✅

Delivered (commit f825c66, tag v0.20.0):

• /workflow command (alias /ultra) added to commands.yaml as the 6th role mask — plan-driven (Executor: workflow mark gate), read-only subtasks by default, write-heavy work routed to /crew
• Cross-platform scheduler guidance folded into command bodies exactly per this RFC: Claude Code run_in_background, Cursor native background tasks, TRAE task runner, plus serial downgrade for old IDEs — no proprietary API binding
• 22 build artifacts (18 + 4 new workflow artifacts), --check zero drift, 39 tests green
• workflow_assistant.mdc rules + _scripts/role_identity/workflow.py; all three platform installers ship the new command
• Behavior layer delegated to the new SUBAGENT-DISPATCH.md contract (issue Feature: Sub-agent dispatch best practice (SUBAGENT-DISPATCH.md) — orchestrator drives mid-tier sub-agents with CAT personas & harness #8)

Remaining: real-machine scheduler verification — run an actual /workflow session on each carrier (Cursor / Claude Code / TRAE), confirm parallel dispatch + result aggregation behaves per design, then report back. Tracked in the new reminder issue (see cross-reference above).

[thiswind]

Progress: v0.24.0 shipped (2026-09-08). Cross-platform command layer stable since v0.20.0; v0.24.0 adds the operational guardrail layer (write gateway, doctor, closing protocol) that orchestrators on each carrier can lean on. TRAE-carrier evidence posted in #9. Awaiting Cursor/Claude-Code carrier runs to close.