agent-orchestration 0.5.0 → 0.6.0

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
 
@@ -41,28 +42,10 @@ Works with any AI coding agent that supports MCP or [AGENTS.md](https://agents.m
 - **Devin**
 - And many more!
 
-## Installation
-
-### Prerequisites
-
-- Node.js 18 or higher
-- npm
-
-### Install
-
-```bash
-# Clone or navigate to the project
-cd agent-orchestration
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-```
-
 ## Quick Start
 
+No installation required! Just use `npx`:
+
 ### For Any IDE/CLI (AGENTS.md)
 
 ```bash
@@ -93,12 +76,19 @@ 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
 ```
 
-## Manual Setup
-
-### 1. Configure Your IDE
+## MCP Server Setup
 
 Add to your MCP configuration (e.g., `~/.cursor/mcp.json` for Cursor):
 
@@ -118,7 +108,7 @@ Add to your MCP configuration (e.g., `~/.cursor/mcp.json` for Cursor):
 
 The server automatically uses the current working directory as the project root.
 
-### 2. Start Your Session
+### Start Your Session
 
 Use the `bootstrap` tool to start:
 
@@ -126,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
@@ -160,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 |
@@ -176,35 +177,166 @@ 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 |
 
-## Architecture
+### 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
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                     IDE / CLI Tool                           │
-├─────────────┬─────────────┬─────────────┬─────────────┬─────┤
-│ Main Agent  │ Sub-Agent 1 │ Sub-Agent 2 │ Sub-Agent 3 │ ... │
-└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴─────┘
-       │             │             │             │
-       └─────────────┴──────┬──────┴─────────────┘
-                            │
-                    ┌───────▼───────┐
-                    │  MCP Server   │
-                    │  (TypeScript) │
-                    └───────┬───────┘
-                            │
-              ┌─────────────┼─────────────┐
-              │             │             │
-      ┌───────▼───┐ ┌───────▼───┐ ┌───────▼───┐
-      │  Agents   │ │   Tasks   │ │  Memory   │
-      │  Registry │ │   Queue   │ │   Store   │
-      └───────────┘ └───────────┘ └───────────┘
-              │             │             │
-              └─────────────┼─────────────┘
-                            │
-                    ┌───────▼───────┐
-                    │    SQLite     │
-                    │  (per-project)│
-                    └───────────────┘
+
+### 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
@@ -214,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
 ```
@@ -222,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
@@ -252,11 +401,62 @@ 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
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     IDE / CLI Tool                           │
+├─────────────┬─────────────┬─────────────┬─────────────┬─────┤
+│ Main Agent  │ Sub-Agent 1 │ Sub-Agent 2 │ Sub-Agent 3 │ ... │
+└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴─────┘
+       │             │             │             │
+       └─────────────┴──────┬──────┴─────────────┘
+                            │
+                    ┌───────▼───────┐
+                    │  MCP Server   │
+                    │  (TypeScript) │
+                    └───────┬───────┘
+                            │
+              ┌─────────────┼─────────────┐
+              │             │             │
+      ┌───────▼───┐ ┌───────▼───┐ ┌───────▼───┐
+      │  Agents   │ │   Tasks   │ │  Memory   │
+      │  Registry │ │   Queue   │ │   Store   │
+      └───────────┘ └───────────┘ └───────────┘
+              │             │             │
+              └─────────────┼─────────────┘
+                            │
+                    ┌───────▼───────┐
+                    │    SQLite     │
+                    │  (per-project)│
+                    └───────────────┘
+```
+
 ## AGENTS.md
 
 This project follows the [AGENTS.md](https://agents.md/) format - a simple, open format for guiding AI coding agents used by over 60k open-source projects.
 
-When you run `agent-orchestration init`, it creates an `AGENTS.md` file that works with:
+When you run `npx agent-orchestration init`, it creates an `AGENTS.md` file that works with:
 - OpenAI Codex
 - Google Jules
 - Cursor
@@ -270,8 +470,7 @@ When you run `agent-orchestration init`, it creates an `AGENTS.md` file that wor
 ### Server won't start
 
 1. Make sure Node.js 18+ is installed: `node --version`
-2. Rebuild the project: `npm run build`
-3. Check the path in your MCP config is correct
+2. Check the path in your MCP config is correct
 
 ### Database errors
 
@@ -291,11 +490,24 @@ It will be recreated on next server start.
 
 ## Development
 
+For contributors and local development:
+
+### Prerequisites
+
+- Node.js 18 or higher
+- npm
+
+### Setup
+
 ```bash
+# Clone the repository
+git clone https://github.com/madebyaris/agent-orchestration.git
+cd agent-orchestration
+
 # Install dependencies
 npm install
 
-# Build
+# Build the project
 npm run build
 
 # Watch mode (rebuild on changes)
@@ -309,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"}