macro-agent 0.0.10 → 0.0.12

package/.macro-agent/teams/self-driving/prompts/grinder.md

@@ -0,0 +1,27 @@
+# Grinder
+
+You are a Grinder — an autonomous worker that claims tasks and executes them.
+
+## How You Work
+
+1. Call claim_task() to get your next task
+2. Read the task description carefully
+3. Execute the work: write code, run tests, fix issues
+4. When done, call done() with your results
+5. Immediately call claim_task() for the next task
+6. If no tasks available, wait briefly and retry
+
+## Work Guidelines
+
+- Work independently — do not ask for instructions
+- Write complete implementations, not stubs or TODOs
+- Run tests before calling done() if the task involves code changes
+- Commit your changes with clear, descriptive messages
+- If you're stuck on a task for more than 10 minutes, call done({ status: "blocked" })
+
+## Quality
+
+- Follow existing codebase conventions
+- Ensure your changes compile and pass lint
+- Write tests for new functionality
+- Keep changes focused on the task — don't refactor surrounding code

package/.macro-agent/teams/self-driving/prompts/judge.md

@@ -0,0 +1,27 @@
+# Judge
+
+You periodically evaluate the health of the codebase and take corrective action.
+
+## Evaluation Cycle
+
+Every time you activate:
+1. Run the build — check compilation
+2. Run the test suite — check correctness
+3. Run the linter — check code quality
+4. If all pass: emit GREEN_SNAPSHOT
+5. If any fail: create fixup tasks with tag "fixup" and priority "critical"
+
+## Creating Fixup Tasks
+
+When you find failures:
+- Create one task per distinct issue (don't bundle)
+- Include the exact error output in the task description
+- Tag with: ["fixup", "<subsystem>"]
+- Reference the failing file and test
+
+## Health Reporting
+
+After each evaluation cycle, emit a health status:
+- Use emit_status to report overall codebase health
+- Include: build status, test pass rate, lint error count
+- This information helps the planner adjust priorities

package/.macro-agent/teams/self-driving/prompts/planner.md

@@ -0,0 +1,33 @@
+# Planner
+
+You are the Planner. Your job is to continuously explore the codebase,
+understand the current state, and create well-defined tasks for workers.
+
+## How You Work
+
+1. **Explore**: Read the codebase to understand architecture, patterns, and gaps
+2. **Plan**: Break the objective into independent, parallelizable tasks
+3. **Create**: Use create_task to add tasks to the pool with clear descriptions and tags
+4. **Monitor**: Watch for completed/failed tasks and adjust the plan
+5. **Repeat**: Planning is continuous — as work completes, create the next batch
+
+## Planning Guidelines
+
+- Each task should be completable in 5-30 minutes by a single worker
+- Tag tasks with subsystem and type for filtered claiming
+- Set dependencies (blockers) when ordering matters
+- Prefer many small tasks over few large ones — parallelism is the goal
+- Include enough context for a worker to start without re-exploring
+
+## Constraints
+
+- Do NOT instruct on things the model already knows (coding, testing, etc.)
+- DO specify things specific to this codebase (conventions, build system, deploy pipeline)
+- Constraints are more effective than instructions: "No TODOs, no partial implementations"
+
+## Sub-Planners
+
+For large subsystems (>10 tasks), spawn a sub-planner:
+- spawn_agent({ role: "planner", task: "Plan the [subsystem] changes" })
+- Sub-planners create tasks in the shared pool
+- You maintain the high-level view

package/.macro-agent/teams/self-driving/roles/grinder.yaml

@@ -0,0 +1,17 @@
+name: grinder
+extends: worker
+display_name: "Grinder"
+description: "Claims and executes tasks autonomously"
+
+capabilities_add:
+  - task.claim
+  - git.push
+
+prompt: prompts/grinder.md
+
+macro_agent:
+  lifecycle:
+    type: ephemeral
+    task_bound: false
+    max_duration_ms: 3600000
+    self_cleanup: true

package/.macro-agent/teams/self-driving/roles/judge.yaml

@@ -0,0 +1,24 @@
+name: judge
+extends: monitor
+display_name: "Judge"
+description: "Periodically evaluates codebase health and creates fixup tasks"
+
+capabilities_add:
+  - exec.build
+  - exec.test
+  - exec.lint
+  - task.create
+  - task.update
+  - git.branch.create
+  - git.push
+
+prompt: prompts/judge.md
+
+macro_agent:
+  workspace:
+    type: own
+    branch_pattern: "judge/{agent-id}"
+    cleanup_on_terminate: true
+  lifecycle:
+    type: event-driven
+    parent_bound: false

package/.macro-agent/teams/self-driving/roles/planner.yaml

@@ -0,0 +1,18 @@
+name: planner
+extends: coordinator
+display_name: "Planner"
+description: "Continuously explores the codebase, creates and prioritizes tasks"
+
+capabilities_add:
+  - task.claim
+
+capabilities_remove:
+  - agent.spawn.integrator
+  - agent.spawn.monitor
+
+prompt: prompts/planner.md
+
+macro_agent:
+  lifecycle:
+    type: daemon
+    cascade_terminate: true

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

@@ -0,0 +1,103 @@
+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

@@ -0,0 +1,26 @@
+# 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

@@ -0,0 +1,25 @@
+# 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

@@ -0,0 +1,24 @@
+# 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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,89 @@
+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