agent-orchestration 0.5.1 → 0.6.1

package/.cursor/rules/orchestrator-auto.mdc

@@ -17,6 +17,8 @@ This project uses **Agent Orchestration**. You MUST follow these rules.
 bootstrap
 ```
 
+**Important**: `bootstrap` is an MCP tool invocation inside your agent/IDE, not a terminal command.
+
 This registers you with the orchestrator and shows you:
 - Current project focus
 - Tasks assigned to you

package/.cursor/rules/orchestrator-main.mdc

@@ -13,12 +13,13 @@ You are the **main orchestrator agent** in a multi-agent coordination system. Fo
 **IMMEDIATELY** when starting any task, register yourself:
 
 ```
-agent_register:
+bootstrap:
   name: "main-orchestrator"
   role: "main"
-  capabilities: ["planning", "coordination", "review"]
 ```
 
+**Important**: `bootstrap` is an MCP tool invocation inside your agent/IDE, not a terminal command.
+
 ## Your Responsibilities
 
 1. **Set the Focus** - Always set the current focus so other agents know what we're working on:
@@ -35,7 +36,7 @@ agent_register:
      title: "<clear task title>"
      description: "<detailed requirements>"
      priority: "normal" | "high" | "urgent"
-     assigned_to: "<agent_id>" (optional)
+     complexity: "trivial" | "simple" | "moderate" | "complex" (optional, auto-detected)
    ```
 
 3. **Store Decisions** - Document architectural decisions:
@@ -52,9 +53,22 @@ agent_register:
    task_list
    ```
 
+## Task Complexity Guidelines
+
+When creating tasks, consider the appropriate complexity:
+
+| Complexity | Use For | Research Required |
+|------------|---------|-------------------|
+| `trivial` | Typo fixes, config changes | None |
+| `simple` | Bug fixes, small refactors | context, files |
+| `moderate` | New endpoints, components | + requirements |
+| `complex` | New features, migrations | + design |
+
+Complexity is auto-detected from keywords, but you can override it.
+
 ## Workflow
 
-1. Register yourself first
+1. Register yourself with `bootstrap`
 2. Check `coordination_status` to see current state
 3. Set `context:current_focus` with the goal
 4. Create tasks for work that needs to be done
@@ -75,12 +89,28 @@ This prevents contradicting decisions made by other agents.
 ## When Delegating
 
 1. Create a clear task with `task_create`
-2. Optionally assign to a specific sub-agent
-3. Wait for task completion before creating dependent tasks
-4. Use task dependencies when order matters
+2. Set appropriate complexity for research requirements
+3. Optionally assign to a specific sub-agent
+4. Wait for task completion before creating dependent tasks
+5. Use task dependencies when order matters
+
+## Reviewing Research
+
+Before approving implementation, check sub-agent research:
+```
+research_status:
+  task_id: "<task_id>"
+```
+
+Search past research for relevant context:
+```
+research_query:
+  query: "<search term>"
+```
 
 ## Communication Pattern
 
 - Use `memory_set` in namespace `context` for current state
 - Use `memory_set` in namespace `blockers` for issues
+- Use `memory_set` in namespace `decisions` for architectural choices
 - Check `agent_list` to see who's available

package/.cursor/rules/orchestrator-sub.mdc

@@ -19,59 +19,120 @@ claim_todo:
   description: "<details if any>"
 ```
 
+**Important**: tool calls like `claim_todo` / `bootstrap` are MCP tool invocations inside your agent/IDE, not terminal commands.
+
 **DO NOT start coding until you have claimed your task.**
 
 This:
 1. Registers you with the orchestrator
 2. Creates the task if it doesn't exist
-3. Claims it so no other agent works on it
-4. Returns your agent ID and task ID
+3. Assigns it to you
+4. Shows you the **research checklist** based on task complexity
 
 ---
 
-## After Claiming
+## 🔬 Research-First Workflow
+
+After claiming, you'll see a research checklist based on task complexity:
+
+| Complexity | Research Required |
+|------------|-------------------|
+| `trivial` | None - start immediately |
+| `simple` | context, files |
+| `moderate` | context, files, requirements |
+| `complex` | context, files, requirements, design |
 
-1. **Check context** to understand the project:
+### For Non-Trivial Tasks
+
+**BEFORE coding**, document your research:
+
+1. **Context** - Understand the current state:
    ```
-   memory_get:
-     key: "current_focus"
-     namespace: "context"
+   memory_set:
+     key: "understanding"
+     value: "<what you learned about the codebase>"
+     namespace: "research:<task_id>:context"
    ```
 
-2. **Check decisions** to avoid contradicting them:
+2. **Files** - Identify affected files:
    ```
-   memory_list:
-     namespace: "decisions"
+   memory_set:
+     key: "affected_files"
+     value: "<list of files you'll modify>"
+     namespace: "research:<task_id>:files"
    ```
 
-3. **Lock files** before editing:
+3. **Requirements** (moderate/complex):
    ```
-   lock_acquire:
-     resource: "<file_path>"
-     reason: "<what you're doing>"
+   memory_set:
+     key: "specs"
+     value: "<requirements, acceptance criteria, edge cases>"
+     namespace: "research:<task_id>:requirements"
    ```
 
----
+4. **Design** (complex only):
+   ```
+   memory_set:
+     key: "architecture"
+     value: "<design decisions, component structure>"
+     namespace: "research:<task_id>:design"
+   ```
 
-## While Working
+### Mark Research Complete
+
+When all items are documented:
 
-Update progress periodically:
 ```
-task_update:
+research_ready:
   task_id: "<your_task_id>"
-  progress: 50
 ```
 
-Store important findings:
+### Then Start Implementation
+
 ```
-memory_set:
-  key: "<finding>"
-  value: "<details>"
-  namespace: "findings"
+task_claim:
+  task_id: "<your_task_id>"
 ```
 
 ---
 
+## Check Research Status
+
+To see what's done and what's missing:
+
+```
+research_status:
+  task_id: "<your_task_id>"
+```
+
+---
+
+## While Working
+
+1. **Lock files** before editing:
+   ```
+   lock_acquire:
+     resource: "<file_path>"
+     reason: "<what you're doing>"
+   ```
+
+2. **Update progress** periodically:
+   ```
+   task_update:
+     task_id: "<your_task_id>"
+     progress: 50
+   ```
+
+3. **Store findings** for others:
+   ```
+   memory_set:
+     key: "<finding>"
+     value: "<details>"
+     namespace: "findings"
+   ```
+
+---
+
 ## When Done
 
 1. Complete the task:
@@ -109,6 +170,7 @@ memory_set:
 ## Important Rules
 
 1. **ALWAYS claim your task first** with `claim_todo`
-2. **ALWAYS lock files** before editing shared resources
-3. **ALWAYS complete your task** when done
-4. **Check shared memory** before making decisions that affect others
+2. **ALWAYS complete research** before implementation (non-trivial tasks)
+3. **ALWAYS lock files** before editing shared resources
+4. **ALWAYS complete your task** when done
+5. **Check shared memory** before making decisions that affect others

package/README.md

@@ -24,6 +24,7 @@ This MCP server provides:
 - **Task Queue** - Turn-based task execution with dependencies
 - **Agent Discovery** - Agents can see who else is working on the project
 - **Resource Locking** - Prevent concurrent access to files or resources
+- **Research-First Workflow** - Ensures agents understand context before coding
 - **Coordination Status** - Real-time visibility into the orchestration state
 - **Auto Context Sync** - Automatically updates `activeContext.md` for easy reference
 
@@ -75,6 +76,15 @@ This copies `.cursor/rules/` with Cursor-specific rules.
 npx agent-orchestration init           # Create AGENTS.md (works with any AI agent)
 npx agent-orchestration init-cursor    # Setup for Cursor IDE (.cursor/rules/)
 npx agent-orchestration serve          # Run the MCP server
+npx agent-orchestration doc --task <task-id>
+npx agent-orchestration cursor check   # Verify Cursor CLI support
+npx agent-orchestration cursor delegate --task <task-id>
+npx agent-orchestration cursor status --task <task-id>
+npx agent-orchestration cursor resume --task <task-id>
+npx agent-orchestration cursor sync --task <task-id>
+npx agent-orchestration cursor recover --task <task-id>
+npx agent-orchestration cursor handoff --task <task-id> --summary "..."
+npx agent-orchestration cursor list    # Show delegated Cursor tasks
 npx agent-orchestration help           # Show help
 ```
 
@@ -106,6 +116,8 @@ Use the `bootstrap` tool to start:
 bootstrap
 ```
 
+**Note**: `bootstrap` is an MCP tool invocation inside your agent/IDE, not a terminal command.
+
 This registers you, shows current focus, pending tasks, and recent decisions.
 
 ## Available Tools
@@ -140,13 +152,22 @@ This registers you, shows current focus, pending tasks, and recent decisions.
 
 | Tool | Description |
 |------|-------------|
-| `task_create` | Create a new task in the queue |
-| `task_claim` | Claim a task to work on |
+| `task_create` | Create a new task (auto-detects complexity) |
+| `task_claim` | Claim a task to work on (requires research for non-trivial) |
 | `task_update` | Update task status or progress |
 | `task_complete` | Mark a task as completed |
 | `task_list` | List tasks with filters |
 | `is_my_turn` | Check if work is available for you |
 
+### Research Workflow
+
+| Tool | Description |
+|------|-------------|
+| `research_ready` | Mark research complete for a task |
+| `research_status` | Check research progress for a task |
+| `research_query` | Search past research findings |
+| `research_checklist` | View research requirements by complexity |
+
 ### Coordination
 
 | Tool | Description |
@@ -156,6 +177,168 @@ This registers you, shows current focus, pending tasks, and recent decisions.
 | `lock_check` | Check if a resource is locked |
 | `coordination_status` | Get overall system status |
 
+### Cursor Provider
+
+| Tool | Description |
+|------|-------------|
+| `cursor_check` | Verify Cursor CLI availability and supported features |
+| `cursor_delegate_task` | Launch a Cursor CLI run for a task and persist session metadata |
+| `cursor_task_status` | Inspect delegated task health, recovery state, and retryability |
+| `cursor_resume_task` | Return the resume command for a delegated task |
+| `cursor_sync_task` | Refresh delegated task state and sync findings back into shared memory |
+| `cursor_recover_task` | Relaunch a failed or stale delegated task with current shared context |
+| `cursor_handoff_task` | Record a structured handoff for the next agent |
+| `cursor_list_delegations` | Show delegated Cursor tasks and their last known status |
+| `task_generate_doc` | Generate Markdown documentation for a task from current orchestration state |
+
+## Cursor-Native Delegation
+
+You can now delegate orchestrator tasks directly to Cursor CLI instead of manually creating a plan, opening a new tab, and pasting context yourself.
+
+### CLI Workflow
+
+```bash
+# Verify Cursor CLI is available
+npx agent-orchestration cursor check
+
+# Delegate a task to Cursor
+npx agent-orchestration cursor delegate --task <task-id> --mode agent
+
+# Inspect health and recovery hints
+npx agent-orchestration cursor status --task <task-id>
+
+# Resume the delegated session later
+npx agent-orchestration cursor resume --task <task-id>
+
+# Sync the latest delegated knowledge back into shared memory
+npx agent-orchestration cursor sync --task <task-id>
+
+# Recover a stale or failed delegated run
+npx agent-orchestration cursor recover --task <task-id>
+
+# Record a structured handoff for another agent
+npx agent-orchestration cursor handoff --task <task-id> --summary "Current implementation is complete; QA and docs remain."
+
+# Generate task documentation on demand
+npx agent-orchestration doc --task <task-id>
+
+# Or launch the resume session immediately
+npx agent-orchestration cursor resume --task <task-id> --exec
+```
+
+### MCP Workflow
+
+```text
+cursor_delegate_task:
+  task_id: "<task-id>"
+  mode: "agent"
+  use_worktree: true
+```
+
+Delegations store provider metadata directly on the task, including:
+
+- Cursor chat/session ID
+- provider status
+- worktree usage
+- launch command
+- run log path
+
+Moderate and complex tasks default to Cursor worktrees for safer parallel execution.
+
+### Delegation Knowledge Loop
+
+Delegated Cursor tasks now write structured shared memory so the next agent can resume with live context instead of only the original launch prompt.
+
+Namespaces:
+
+- `delegation:<task_id>:brief`
+- `delegation:<task_id>:updates`
+- `delegation:<task_id>:findings`
+- `delegation:<task_id>:decisions`
+- `delegation:<task_id>:handoff`
+
+Recommended flow:
+
+1. `cursor_delegate_task` or `agent-orchestration cursor delegate`
+2. `cursor_task_status` to inspect health and recovery hints
+3. `cursor_sync_task` or `agent-orchestration cursor sync`
+4. `cursor_recover_task` when the delegated process is stale or failed
+5. `cursor_handoff_task` when a human or another agent needs to pick up the work
+6. `cursor_resume_task` to rebuild a resume prompt from the latest shared knowledge
+
+### Graceful Recovery
+
+Delegated Cursor runs now track recovery metadata directly on the task:
+
+- recovery state (`healthy`, `stale`, `failed`, `completed`, `unknown`)
+- recoverability
+- last error / exit code
+- retry count
+- recovery hints
+
+This enables:
+
+- stale process detection when no clean exit is captured
+- structured recovery hints in MCP and CLI
+- safe relaunch via `cursor_recover_task`
+- preservation of knowledge and handoff state across retries
+
+### Auto Documentation
+
+Task documentation is now generated automatically into `.agent-orchestration/docs/` from:
+
+- task metadata and output
+- research namespaces
+- delegation knowledge namespaces
+- provider health and recovery state
+- recent task-specific orchestration events
+
+Generated files:
+
+- `.agent-orchestration/docs/tasks/<task-id>.md`
+- `.agent-orchestration/docs/README.md`
+
+Documentation refreshes automatically during:
+
+- delegated task launch
+- delegated sync
+- delegated handoff
+- delegated recovery
+- task completion
+
+You can also regenerate docs manually with:
+
+```bash
+npx agent-orchestration doc --task <task-id>
+```
+
+## Research-First Workflow
+
+Tasks are automatically assigned a complexity level that determines research requirements:
+
+| Complexity | Examples | Research Required |
+|------------|----------|-------------------|
+| `trivial` | Typo fix, config change | None |
+| `simple` | Bug fix, small refactor | context, files |
+| `moderate` | New endpoint, component | + requirements |
+| `complex` | New feature, migration | + design |
+
+### How It Works
+
+1. **Task Creation** - Complexity is auto-detected from keywords (or manually set)
+2. **Research Phase** - Agent documents findings in structured namespaces
+3. **Research Gate** - `task_claim` is blocked until research is complete
+4. **Implementation** - Agent proceeds with full context
+
+### Research Namespaces
+
+```
+research:<task_id>:context      # Understanding of codebase
+research:<task_id>:files        # Affected files identified
+research:<task_id>:requirements # Specs and edge cases
+research:<task_id>:design       # Architecture decisions
+```
+
 ## Recommended Workflow
 
 ### Main Orchestrator Agent
@@ -163,7 +346,7 @@ This registers you, shows current focus, pending tasks, and recent decisions.
 ```
 1. bootstrap                          # Start session
 2. memory_set current_focus "..."     # Set project focus
-3. task_create "Feature X"            # Create tasks
+3. task_create "Feature X"            # Create tasks (complexity auto-detected)
 4. task_create "Feature Y"
 5. coordination_status                # Monitor progress
 ```
@@ -171,11 +354,28 @@ This registers you, shows current focus, pending tasks, and recent decisions.
 ### Sub-Agents (Spawned for Specific Work)
 
 ```
-1. claim_todo "Feature X"             # Register + claim in one call
-2. lock_acquire "src/feature.ts"      # Lock files before editing
+1. claim_todo "Feature X"             # Register + see research checklist
+
+# Research Phase (for non-trivial tasks)
+2. memory_set key="understanding" namespace="research:<task_id>:context" value="..."
+3. memory_set key="files" namespace="research:<task_id>:files" value="..."
+4. research_ready task_id="<task_id>" # Validate research complete
+
+# Implementation Phase
+5. task_claim task_id="<task_id>"     # Now allowed to start
+6. lock_acquire "src/feature.ts"      # Lock files before editing
+7. [do the work]
+8. task_complete <task_id> "Done"     # Complete the task
+9. agent_unregister                   # Clean up
+```
+
+### Trivial Tasks (No Research)
+
+```
+1. claim_todo "Fix typo in README"    # Complexity: trivial
+2. task_claim task_id="<task_id>"     # Immediately allowed
 3. [do the work]
-4. task_complete <task_id> "Done"     # Complete the task
-5. agent_unregister                   # Clean up
+4. task_complete <task_id> "Done"
 ```
 
 ## Memory Namespaces
@@ -201,6 +401,26 @@ Use these namespaces for organization:
 | `MCP_ORCH_AGENT_ROLE` | Default agent role | `sub` |
 | `MCP_ORCH_CAPABILITIES` | Comma-separated capabilities | `code` |
 
+### `agent-orchestration.config.json`
+
+Optional project-level config for Cursor orchestration:
+
+```json
+{
+  "cursor": {
+    "binary": "agent",
+    "defaultMode": "agent",
+    "defaultForce": true,
+    "autoApproveMcps": true,
+    "trustWorkspace": true,
+    "useCreateChat": true,
+    "logDir": ".agent-orchestration/providers/cursor",
+    "preferWorktreeFor": ["moderate", "complex"],
+    "recoveryStaleAfterMs": 600000
+  }
+}
+```
+
 ## Architecture
 
 ```
@@ -301,11 +521,11 @@ npm run clean && npm run build
 
 We're actively developing new features. Here's what's coming:
 
+- [x] **Research-First Workflow** - Agents research and prepare before coding (DONE in v0.5.2, carried forward in v0.6.0)
 - [ ] **External Memory Integration** - Integration with external memory providers like [Mem0](https://mem0.ai/), [Byteover](https://www.byterover.dev/), and our own memory solution
-- [ ] **Enhanced Sub-Agent Knowledge** - Fix limitations in knowledge sharing between main agent and sub-agents
-- [ ] **Research-First Workflow** - When building from scratch, agents should research first and prepare all requirements before coding
-- [ ] **Graceful Error Handling** - Better error handling and recovery across all operations
-- [ ] **Auto Documentation** - Automatically generate documentation from and for each sub-agent + main agent interactions
+- [x] **Enhanced Sub-Agent Knowledge** - Delegated Cursor tasks now persist structured briefs, updates, findings, decisions, and handoff state in shared memory
+- [x] **Graceful Error Handling** - Delegated Cursor tasks now track health, stale/failed recovery state, retry counts, and structured recovery hints
+- [x] **Auto Documentation** - Task docs are now generated automatically from orchestration state, delegation memory, provider recovery metadata, and task events
 
 Have a feature request? [Open an issue](https://github.com/madebyaris/agent-orchestration/issues)!
 

package/dist/bin/cli.d.ts

@@ -6,6 +6,7 @@
  *   init         - Creates AGENTS.md for cross-IDE/CLI compatibility
  *   init-cursor  - Copies .cursor/rules/ for Cursor IDE
  *   serve        - Run the MCP server (used by IDEs via npx)
+ *   cursor       - Cursor-native orchestration helpers
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bin/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/bin/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}