macro-agent 0.1.0 → 0.1.2

package/.macro-agent/teams/self-driving/team.yaml

@@ -1,103 +0,0 @@
-name: self-driving
-description: "Autonomous codebase development with continuous planning"
-version: 1
-
-roles:
-  - planner
-  - grinder
-  - judge
-
-topology:
-  root:
-    role: planner
-    prompt: prompts/planner.md
-    config:
-      model: sonnet
-
-  companions:
-    - role: judge
-      prompt: prompts/judge.md
-      config:
-        model: haiku
-
-  spawn_rules:
-    planner: [grinder, planner]
-    judge: []
-    grinder: []
-
-communication:
-  channels:
-    task_updates:
-      description: "Task lifecycle events"
-      signals: [TASK_CREATED, TASK_COMPLETED, TASK_FAILED]
-    work_coordination:
-      description: "Work assignment and completion"
-      signals: [WORK_ASSIGNED, WORKER_DONE, MERGE_REQUEST]
-    health:
-      description: "System health monitoring"
-      signals: [HEALTH_CHECK, METRIC_SNAPSHOT, GREEN_SNAPSHOT]
-
-  subscriptions:
-    planner:
-      - channel: task_updates
-      - channel: work_coordination
-        signals: [WORKER_DONE]
-      - channel: health
-        signals: [METRIC_SNAPSHOT]
-    judge:
-      - channel: task_updates
-        signals: [TASK_FAILED]
-      - channel: work_coordination
-        signals: [WORKER_DONE]
-      - channel: health
-    grinder:
-      - channel: work_coordination
-        signals: [WORK_ASSIGNED]
-
-  emissions:
-    planner: [TASK_CREATED, WORK_ASSIGNED]
-    judge: [HEALTH_CHECK, GREEN_SNAPSHOT, FIXUP_CREATED]
-    grinder: [WORKER_DONE]
-
-  routing:
-    status: upstream
-    peers:
-      - from: judge
-        to: planner
-        via: direct
-        signals: [FIXUP_CREATED, GREEN_SNAPSHOT]
-      - from: planner
-        to: judge
-        via: direct
-        signals: [CONVERGENCE_CHECK]
-
-  enforcement: permissive
-
-macro_agent:
-  task_assignment:
-    mode: pull
-    pull:
-      idle_timeout_s: 300
-      claim_retry_delay_ms: 2000
-      max_concurrent_per_agent: 1
-
-  integration:
-    strategy: trunk
-    config:
-      max_retries: 3
-      conflict_action: abandon
-
-  lifecycle:
-    continuations:
-      enabled: true
-      max_history_messages: 50
-      checkpoint_interval: round_trip
-    scaling:
-      min_workers: 3
-      max_workers: 20
-      scale_on: task_queue_depth
-      idle_drain: true
-
-  observability:
-    metrics_window_s: 3600
-    snapshot_interval_s: 300

package/.macro-agent/teams/structured/prompts/developer.md

@@ -1,26 +0,0 @@
-# Developer
-
-You are a **Developer** on a structured development team. You execute a single assigned task in your isolated workspace.
-
-## Responsibilities
-
-1. **Implement** - Complete the assigned task according to its description
-2. **Test** - Verify your changes work correctly
-3. **Commit** - Create clean, descriptive commits
-4. **Report** - Call `done()` with status and summary when finished
-
-## Workflow
-
-1. Read and understand the task description
-2. Explore the relevant code to plan your changes
-3. Implement the changes
-4. Run tests to verify correctness
-5. Commit your work with a clear message
-6. Call `done()` with status `completed` and a brief summary
-
-## Guidelines
-
-- Stay focused on your assigned task only
-- Do not modify files outside the scope of your task
-- If you encounter a blocker, call `done()` with status `failed` and describe the issue
-- Make atomic commits that are easy to review

package/.macro-agent/teams/structured/prompts/lead.md

@@ -1,25 +0,0 @@
-# Lead
-
-You are the **Lead** of a structured development team. You coordinate work by decomposing objectives into tasks and assigning them to developers.
-
-## Responsibilities
-
-1. **Task Decomposition** - Break down the user's request into well-scoped, independent tasks
-2. **Assignment** - Spawn developers and assign each a specific task
-3. **Progress Tracking** - Monitor task completion and handle failures
-4. **Sequencing** - Ensure dependent tasks are ordered correctly using blockers
-
-## Workflow
-
-1. Analyze the objective and identify the minimal set of changes needed
-2. Create tasks with clear descriptions and acceptance criteria
-3. Spawn developers to handle each task
-4. Monitor TASK_COMPLETED / TASK_FAILED signals
-5. When all tasks complete, call `done()` with a summary
-
-## Guidelines
-
-- Keep tasks small and focused (one file or one logical change)
-- Set blockers between tasks that have data dependencies
-- Prefer parallel execution where tasks are independent
-- If a task fails, assess whether to retry or adjust the plan

package/.macro-agent/teams/structured/prompts/reviewer.md

@@ -1,24 +0,0 @@
-# Reviewer
-
-You are a **Reviewer** on a structured development team. You review merge requests to ensure quality before they land on the main branch.
-
-## Responsibilities
-
-1. **Review** - Examine code changes in merge requests for correctness and quality
-2. **Validate** - Run build and test to verify the changes don't break anything
-3. **Decide** - Approve or reject the merge request with clear reasoning
-
-## Workflow
-
-1. Wait for MERGE_REQUEST signals
-2. Check out the branch and review the diff
-3. Run `build` and `test` commands
-4. If everything passes, emit REVIEW_APPROVED
-5. If issues found, emit REVIEW_REJECTED with explanation
-
-## Guidelines
-
-- Focus on correctness, not style preferences
-- Run the test suite before approving
-- Provide specific, actionable feedback on rejections
-- Do not modify code directly; report issues back to the lead

package/.macro-agent/teams/structured/roles/developer.yaml

@@ -1,12 +0,0 @@
-name: developer
-extends: worker
-display_name: "Developer"
-description: "Executes assigned tasks in isolated workspaces"
-
-prompt: prompts/developer.md
-
-macro_agent:
-  lifecycle:
-    type: ephemeral
-    task_bound: true
-    self_cleanup: true

package/.macro-agent/teams/structured/roles/lead.yaml

@@ -1,11 +0,0 @@
-name: lead
-extends: coordinator
-display_name: "Lead"
-description: "Decomposes work into tasks and assigns them to developers"
-
-prompt: prompts/lead.md
-
-macro_agent:
-  lifecycle:
-    type: persistent
-    cascade_terminate: true

package/.macro-agent/teams/structured/roles/reviewer.yaml

@@ -1,19 +0,0 @@
-name: reviewer
-extends: monitor
-display_name: "Reviewer"
-description: "Reviews merge requests and approves or rejects changes"
-
-capabilities_add:
-  - exec.build
-  - exec.test
-
-prompt: prompts/reviewer.md
-
-macro_agent:
-  workspace:
-    type: own
-    branch_pattern: "review/{agent-id}"
-    cleanup_on_terminate: true
-  lifecycle:
-    type: event-driven
-    parent_bound: false

package/.macro-agent/teams/structured/team.yaml

@@ -1,89 +0,0 @@
-name: structured
-description: "Hierarchical development with explicit task assignment and merge queue"
-version: 1
-
-roles:
-  - lead
-  - developer
-  - reviewer
-
-topology:
-  root:
-    role: lead
-    prompt: prompts/lead.md
-    config:
-      model: sonnet
-
-  companions:
-    - role: reviewer
-      prompt: prompts/reviewer.md
-      config:
-        model: haiku
-
-  spawn_rules:
-    lead: [developer, lead]
-    reviewer: []
-    developer: []
-
-communication:
-  channels:
-    task_updates:
-      description: "Task lifecycle events"
-      signals: [TASK_CREATED, TASK_ASSIGNED, TASK_COMPLETED, TASK_FAILED]
-    merge_flow:
-      description: "Merge queue and integration events"
-      signals: [MERGE_REQUEST, MERGE_COMPLETED, MERGE_CONFLICT]
-    review_flow:
-      description: "Code review signals"
-      signals: [REVIEW_REQUESTED, REVIEW_APPROVED, REVIEW_REJECTED]
-
-  subscriptions:
-    lead:
-      - channel: task_updates
-      - channel: merge_flow
-      - channel: review_flow
-        signals: [REVIEW_APPROVED, REVIEW_REJECTED]
-    reviewer:
-      - channel: merge_flow
-        signals: [MERGE_REQUEST]
-      - channel: review_flow
-    developer:
-      - channel: task_updates
-        signals: [TASK_ASSIGNED]
-
-  emissions:
-    lead: [TASK_CREATED, TASK_ASSIGNED]
-    reviewer: [REVIEW_APPROVED, REVIEW_REJECTED]
-    developer: [MERGE_REQUEST, TASK_COMPLETED, TASK_FAILED]
-
-  routing:
-    status: upstream
-    peers:
-      - from: reviewer
-        to: lead
-        via: direct
-        signals: [REVIEW_APPROVED, REVIEW_REJECTED]
-
-  enforcement: permissive
-
-macro_agent:
-  task_assignment:
-    mode: push
-
-  integration:
-    strategy: queue
-    config:
-      require_review: true
-
-  lifecycle:
-    continuations:
-      enabled: false
-    scaling:
-      min_workers: 1
-      max_workers: 10
-      scale_on: manual
-      idle_drain: false
-
-  observability:
-    metrics_window_s: 1800
-    snapshot_interval_s: 600

package/docs/sudocode-integration.md

@@ -1,383 +0,0 @@
-# Sudocode Integration
-
-macro-agent integrates with [sudocode](https://github.com/sudocode-ai/sudocode) to provide external issue tracking and dependency management for tasks. This enables agents to work on issues from a structured backlog with proper dependency ordering.
-
-## Overview
-
-When using the sudocode backend:
-- Tasks are bound to sudocode issues via `external_id`
-- Blocking relationships come from sudocode's issue links
-- `listReady()` returns only tasks whose bound issues have no incomplete blockers
-- Task status can optionally sync with issue status
-
-## Quick Start
-
-### 1. Set Environment Variables
-
-```bash
-# Enable sudocode backend
-export MACRO_TASK_BACKEND=sudocode
-
-# Set project path (defaults to cwd)
-export SUDOCODE_PROJECT_PATH=/path/to/project
-```
-
-### 2. Start macro-agent
-
-```bash
-npx multiagent
-```
-
-The agent will automatically connect to sudocode and use issues as the task source.
-
-## Configuration Reference
-
-### Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `MACRO_TASK_BACKEND` | Backend type: `memory` or `sudocode` | `memory` |
-| `MACRO_TASK_TOOL_MODE` | Tool exposure mode: `abstract`, `native`, `both`, `auto` | `auto` |
-| `SUDOCODE_PROJECT_PATH` | Path to sudocode project root | `process.cwd()` |
-| `SUDOCODE_TOOL_MODE` | Sudocode tool mode: `native`, `mapped`, `both` | `mapped` |
-
-### Programmatic Configuration
-
-```typescript
-import { createTaskBackend, loadTaskConfigFromEnv } from 'macro-agent';
-
-// Load from environment
-const config = loadTaskConfigFromEnv();
-
-// Or configure manually
-const config = {
-  backend: {
-    type: 'sudocode',
-    projectPath: '/path/to/project',
-    idStrategy: 'dual',        // Task ID strategy
-    syncMode: 'realtime',      // Event sync mode
-    executionTracking: { mode: 'bound-only' },
-    autoLinkSpecs: true,       // Link tasks to specs
-    toolMode: 'mapped',        // Tool exposure mode
-  },
-  toolMode: 'auto',
-};
-
-const { backend, toolProvider, toolMode } = await createTaskBackend(config, eventStore);
-```
-
-### Backend Configuration Options
-
-```typescript
-interface SudocodeBackendConfig {
-  type: 'sudocode';
-
-  /** Path to sudocode project root (contains .sudocode/) */
-  projectPath: string;
-
-  /** ID strategy (default: 'dual') */
-  idStrategy?: 'dual';
-
-  /** Sync mode for event subscriptions */
-  syncMode?: 'realtime' | 'batch';
-
-  /** Execution tracking configuration */
-  executionTracking?: ExecutionTrackingConfig;
-
-  /** Auto-link tasks to specs when created from spec context */
-  autoLinkSpecs?: boolean;
-
-  /** Tool mode for this backend */
-  toolMode?: 'native' | 'mapped' | 'both';
-}
-```
-
-### Execution Tracking Options
-
-Control when execution records are created:
-
-```typescript
-type ExecutionTrackingConfig =
-  | { mode: 'none' }        // No execution records
-  | { mode: 'bound-only' }  // Only tasks with external binding (default)
-  | { mode: 'all' }         // All agent runs
-  | { mode: 'filter'; filter: ExecutionFilter };
-```
-
-## Usage Guide
-
-### Creating Tasks Bound to Issues
-
-```typescript
-// Create task bound to an existing sudocode issue
-const task = await backend.create({
-  description: 'Implement feature X',
-  external_id: 'i-abc123',  // sudocode issue ID
-});
-
-console.log(task.external_id); // 'i-abc123'
-```
-
-### Multiple Tasks Per Issue
-
-Multiple tasks (parallel workers) can work on the same issue:
-
-```typescript
-// Parallel workers on same issue
-const task1 = await backend.create({
-  description: 'Worker 1 attempt',
-  external_id: 'i-abc123',
-});
-
-const task2 = await backend.create({
-  description: 'Worker 2 attempt',
-  external_id: 'i-abc123',
-});
-
-// Assign to different agents
-await backend.assign(task1.id, 'worker-1');
-await backend.assign(task2.id, 'worker-2');
-```
-
-### Working with Dependencies
-
-Sudocode's blocking relationships determine task readiness:
-
-```typescript
-// Get tasks that are ready (no blocking dependencies)
-const ready = await backend.listReady();
-
-// Check if a specific task is blocked
-const task = await backend.get(taskId);
-if (task.isBlocked) {
-  // Task's bound issue has incomplete blockers
-  const blockers = await backend.getBlockers(taskId);
-  console.log('Blocked by:', blockers.map(b => b.external_id));
-}
-```
-
-### Task Lifecycle
-
-```typescript
-// 1. Create task bound to issue
-const task = await backend.create({
-  description: 'Implement feature',
-  external_id: 'i-abc123',
-});
-
-// 2. Assign to agent
-await backend.assign(task.id, 'agent-1');
-
-// 3. Start execution
-await backend.start(task.id);
-// Issue status syncs to 'in_progress' if syncStatus enabled
-
-// 4. Complete task
-await backend.complete(task.id, {
-  summary: 'Feature implemented',
-  result: { files_changed: 3 },
-});
-
-// 5. (Optional) Issue is closed by coordinator, not automatically
-```
-
-### Event Subscriptions
-
-```typescript
-// Subscribe to all task changes
-const unsubscribe = backend.onTaskChange((event) => {
-  console.log(`Task ${event.taskId}: ${event.type}`);
-});
-
-// Subscribe to specific task
-const unsubscribe = backend.onTaskChange(taskId, (event) => {
-  console.log(`Task updated: ${event.type}`);
-});
-```
-
-## Tool Modes
-
-The sudocode backend supports different tool exposure modes:
-
-| Mode | Description |
-|------|-------------|
-| `native` | Expose sudocode's native tools (`upsert_issue`, `link`, etc.) |
-| `mapped` | Map to abstract task tools (`create_task`, `complete_task`, etc.) |
-| `both` | Expose both tool sets |
-
-### Auto Mode Behavior
-
-When `toolMode: 'auto'`:
-- Sudocode backend defaults to `mapped` (abstract tools)
-- Memory backend defaults to `abstract`
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│              SudocodeTaskBackend                             │
-│                                                              │
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │              EventStore (Task Storage)               │    │
-│  │  - Tasks with external_id bindings                   │    │
-│  │  - Task-level state (assignment, status, outputs)    │    │
-│  └─────────────────────────────────────────────────────┘    │
-│                              │                               │
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │              SudocodeClient (Interface)              │    │
-│  │  - Abstracts deployment mode                         │    │
-│  │  - Issue/spec/relationship operations                │    │
-│  └─────────────────────────────────────────────────────┘    │
-└──────────────────────────────┼───────────────────────────────┘
-                               │
-            ┌──────────────────┴──────────────────┐
-            ▼                                     ▼
-┌───────────────────────────┐      ┌───────────────────────────┐
-│       ServerClient        │      │     StandaloneClient      │
-│  (Managed Mode)           │      │  (Standalone Mode)        │
-│  - REST API + WebSocket   │      │  - CLI + File Watcher     │
-└───────────────────────────┘      └───────────────────────────┘
-```
-
-### Data Flow
-
-1. **Task Creation**: Backend creates task in EventStore, binds to issue via `external_id`
-2. **Blocker Lookup**: When `isBlocked` is queried, client fetches issue's blockers
-3. **Status Sync**: Task status changes optionally sync to issue status
-4. **Ready Queries**: `listReady()` filters tasks by sudocode's ready issues
-
-## Migration Guide
-
-### From InMemoryTaskBackend
-
-#### Breaking Changes
-
-1. **No `subtasks[]` array** - Use `getChildren(parentId)` instead
-2. **No `agent_history[]` array** - Use `getAgentHistory(taskId)` instead
-3. **`isBlocked` is computed** - Based on sudocode relationships, not task.blockers
-
-#### Migration Steps
-
-1. Update task creation to use `external_id` for issue binding:
-   ```typescript
-   // Before
-   const task = await backend.create({ description: 'Work' });
-
-   // After (with issue binding)
-   const task = await backend.create({
-     description: 'Work',
-     external_id: 'i-abc123',
-   });
-   ```
-
-2. Replace direct property access with method calls:
-   ```typescript
-   // Before
-   const children = task.subtasks;
-   const history = task.agent_history;
-
-   // After
-   const children = await backend.getChildren(task.id);
-   const history = await backend.getAgentHistory(task.id);
-   ```
-
-3. Use `listReady()` for dependency-aware queries:
-   ```typescript
-   // Before (manual filtering)
-   const tasks = await backend.list({ status: 'pending' });
-   const ready = tasks.filter(t => !t.blockers?.length);
-
-   // After
-   const ready = await backend.listReady({ status: 'pending' });
-   ```
-
-### Coexistence
-
-Both backends can coexist during migration:
-- Tasks without `external_id` work like in-memory tasks
-- Tasks with `external_id` are bound to sudocode issues
-- Switch backends via environment variable without code changes
-
-## Sync Policy
-
-Configure how task and issue state synchronize:
-
-```typescript
-interface SyncPolicy {
-  /** Action when bound issue is closed externally */
-  onIssueClosed: 'complete_task' | 'fail_task' | 'notify_only';
-
-  /** Action when issue description changes */
-  onDescriptionChanged: 'propagate' | 'snapshot';
-
-  /** Action when blocker status changes */
-  onBlockerChanged: 'update_blocked' | 'notify_only';
-
-  /** Update issue status when task starts */
-  updateIssueOnStart: boolean;
-
-  /** Update issue when task completes */
-  updateIssueOnComplete: 'close' | 'comment' | 'never';
-}
-```
-
-Default policy:
-```typescript
-const defaultSyncPolicy = {
-  onIssueClosed: 'notify_only',      // Don't auto-complete/fail tasks
-  onDescriptionChanged: 'snapshot',   // Keep original description
-  onBlockerChanged: 'update_blocked', // Update isBlocked state
-  updateIssueOnStart: true,           // Sync status to in_progress
-  updateIssueOnComplete: 'never',     // Let coordinator close issues
-};
-```
-
-## API Reference
-
-### TaskBackend Methods
-
-| Method | Description |
-|--------|-------------|
-| `create(options)` | Create task, optionally bound to issue |
-| `get(id)` | Get task with computed `isBlocked` |
-| `update(id, updates)` | Update task metadata |
-| `assign(id, agentId)` | Assign task to agent |
-| `start(id)` | Start task, optionally sync to issue |
-| `complete(id, outputs?)` | Complete task |
-| `fail(id, error)` | Mark task as failed |
-| `list(filter?)` | List tasks with optional filter |
-| `listReady(filter?)` | List unblocked tasks |
-| `getBlockers(id)` | Get blocking tasks |
-| `getBlocking(id)` | Get tasks blocked by this one |
-| `getChildren(id)` | Get subtasks |
-| `getAgentHistory(id)` | Get assignment history |
-| `onTaskChange(callback)` | Subscribe to task events |
-
-### ExtendedTask Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Internal task ID |
-| `external_id` | `string?` | Bound sudocode issue ID |
-| `status` | `TaskStatus` | Current status |
-| `isBlocked` | `boolean` | Computed from issue blockers |
-| `assigned_agent` | `string?` | Assigned agent ID |
-| `parent_task` | `string?` | Parent task ID |
-| `outputs` | `object?` | Task outputs on completion |
-
-## Troubleshooting
-
-### Task shows isBlocked=false when issue has blockers
-
-Ensure the sudocode client has fetched the latest issue state. Call `backend.getBlockers(taskId)` to refresh blocker data.
-
-### Status not syncing to issue
-
-Check that `syncStatus: true` is set in backend config (default is true).
-
-### Tasks not appearing in listReady()
-
-Tasks must:
-1. Have status `pending` or `assigned`
-2. Be bound to an issue with no incomplete blockers
-3. Not be excluded by filter criteria