autonomous-autonomy

Autonomous task orchestration framework. Use when a task is too large or complex for a single agent pass — multiple subtasks, cross-cutting concerns, verification needs, or tasks that would exhaust a context window.

autonomous-autonomy: Autonomous Task Orchestration

You are operating with the autonomous-autonomy framework — a methodology for decomposing and executing arbitrarily large tasks with production-grade reliability, observability, and minimal human intervention.

When to Use This Skill

Use this whenever a task is too large or complex for a single agent pass. Signs include: multiple independent subtasks, cross-cutting concerns, need for verification, tasks that would exhaust a context window, or anything requiring structured planning before execution.

Core Architecture

The 6-Phase Pipeline

Every autonomous-autonomy workflow follows these phases:

  1. Initialize (/aa:init) — Create the .aa/ state directory, scan the project, establish context
  2. Plan (/aa:plan) — Decompose the objective into a task DAG with Given/When/Then specs
  3. Execute (/aa:run) — Run tasks stage-by-stage with isolated subagents and curated context
  4. Verify (/aa:verify) — Check each task's output against its specification
  5. Monitor (/aa:status) — Track progress, identify blockers, estimate completion
  6. Report (/aa:report) — Generate comprehensive execution report

Files-as-State (The Source of Truth)

All orchestration state lives in .aa/ as structured JSON and markdown files. This makes execution resumable, auditable, and version-controllable.

.aa/
├── objective.md              # The original user request
├── decomposition.json        # Task DAG: tasks[] (each task has per-task dependencies[])
├── execution-plan.json       # Topologically sorted parallel stages
├── state.json                # Current state: task states, progress, metadata
├── tasks/{taskId}/
│   ├── spec.json             # Given/When/Then + constraints + context items
│   ├── acceptance-test.md    # Acceptance test contract (metadata + pointer to runnable test)
│   ├── context.json          # Curated context payload for the executor
│   ├── result.json           # Execution output and artifacts (includes acceptanceTest field)
│   └── verification.json     # Verification decision and evidence
└── logs/
    └── events.jsonl          # Structured event stream

# The executor also creates a RUNNABLE acceptance test file in the project's test directory:
# e.g., tests/test_acceptance_{taskName}.py or tests/{taskName}.acceptance.test.ts
# This is the actual executable test — acceptance-test.md just points to it.

Task State Machine

Tasks progress through these states. Only the transitions shown are valid:

                    ┌←←← (retry: retries available) ←←←┐
                    │                                   │
                    │  ┌← (crash, retries available) ←┐ │
                    ↓  ↓                              │ │
pending ──→ queued ──→ running ──→ verifying ──→ completed
  │                       │            │
  ↓                       ↓            ↓ (retries exhausted)
blocked               failed ←←←←←←←←←┘
  (when resolved → queued)

Transition rules:

  • pending → queued: All dependencies satisfied
  • queued → running: Subagent launched for this task
  • running → verifying: Subagent completed, output ready for verification
  • running → failed: Subagent error or timeout (retries exhausted)
  • running → queued: Executor crash, retries available (synthetic verification.json written for retry context)
  • verifying → completed: Verification passed
  • verifying → queued: Verification failed, retries available (max 2 retries per task)
  • verifying → failed: Verification failed, retries exhausted
  • pending → blocked: Dependencies not yet met
  • blocked → queued: Blocking dependencies now complete

Context Curation (Stripe Pattern)

Before any task executes, assemble its context deterministically:

  1. Task specification — The Given/When/Then spec from spec.json
  2. Project context — Architecture overview, coding standards, conventions
  3. Source files — Only files listed in the task's contextItems (max 5 files, ~50k tokens)
  4. Dependency results — Outputs from completed prerequisite tasks
  5. Recent history — Last 5 git commits for project awareness

Write the assembled context to .aa/tasks/{taskId}/context.json. The executor subagent receives this as its working knowledge. Same task always gets same context — deterministic and reproducible.

Bounded Retry Strategy

When a task fails:

  1. If retries < 2: Increment retry count, requeue task. The previous verification.json and result.json are preserved on disk — the run command reads them on the next attempt and includes failure details (evidence, recommendations) in the executor prompt as "PREVIOUS ATTEMPT FAILURE" context. This ensures retries learn from failures rather than repeating the same mistakes.
  2. If retries >= 2: Mark as permanently failed, log failure reason, suggest human intervention
  3. Never retry more than twice — empirically, if it doesn't work in 2 attempts, more attempts waste compute without improving outcomes

Acceptance-Test-Driven Execution

Every task follows a strict test-first workflow:

  1. Plan phase creates a Given/When/Then spec (spec.json) and an acceptance test stub (acceptance-test.md) for each task
  2. Executor translates the spec into an executable acceptance test file BEFORE writing any implementation code. The test must fail (red) initially.
  3. Executor uses TDD (unit tests) to implement the feature until the acceptance test passes (green).
  4. Verifier runs the acceptance test as its primary verification mechanism.

This ensures every feature is provably correct through an executable test that directly encodes the business specification.

Verification Strategy (Hybrid)

Verification combines four approaches:

  1. Acceptance test — Run the executable acceptance test created by the executor. A passing acceptance test is the strongest evidence of spec satisfaction. A missing acceptance test caps confidence at 0.70 and downgrades status to "warning". A failing acceptance test caps confidence at 0.50 and downgrades status to "fail".
  2. Automatic — Check that code compiles, unit tests pass, linter is clean, expected files exist
  3. Content — A verifier subagent reads the task spec and output, judges whether Given/When/Then is satisfied
  4. Manual gate — If automatic or content checks are uncertain, flag for human review

Write results to .aa/tasks/{taskId}/verification.json with status (pass/fail/warning), confidence score, and evidence.

How Commands Work Together

User says: "Build me X"
    │
    ▼
/aa:init          Creates .aa/, scans project
    │
    ▼
/aa:plan "X"      Decomposes into DAG, creates spec.json + acceptance-test.md per task
    │              Shows plan to user for review
    ▼
/aa:run           Executes next stage (or all stages if "all")
    │              Each task: write acceptance test (red) → TDD → acceptance test (green)
    ▼
/aa:verify        Runs acceptance tests, checks completed tasks against specs
    │              Passes: mark completed. Fails: retry or flag.
    ▼
/aa:run           Execute next stage (repeat run/verify cycle)
    │
    ▼
/aa:report        Generate final report with metrics and timeline

For fully autonomous execution, /aa:run all loops through all stages automatically, running verification after each stage.

Subagent Patterns

When spawning subagents, use the Agent tool with the plugin's dedicated agent types. Each type auto-loads its agent prompt — you only need to provide task-specific data in the prompt parameter.

For task execution:

Agent(subagent_type="aa:executor", prompt="[task spec + curated context]")

For task decomposition:

Agent(subagent_type="aa:planner", prompt="[objective + project context]")

For context research:

Agent(subagent_type="aa:researcher", prompt="[task spec + files to explore]")

For verification:

Agent(subagent_type="aa:verifier", prompt="[task spec + result + files to check]")

For plan quality scoring (benchmark):

Agent(subagent_type="aa:plan-scorer", prompt="[decomposition JSON + test objective rubric]")

Each subagent gets a fresh context window with its agent prompt automatically loaded. The prompt parameter should contain only task-specific data (specs, context, file paths) — not the agent's base instructions.

Observability

Every significant action is logged to .aa/logs/events.jsonl as one JSON object per line:

{"timestamp":"2026-03-04T10:00:00Z","eventType":"planning_completed","taskCount":8,"stages":5,"message":"Objective decomposed into 8 tasks across 5 stages"}
{"timestamp":"2026-03-04T10:05:00Z","eventType":"task_started","taskId":"task-001","message":"Task task-001 started execution"}
{"timestamp":"2026-03-04T10:30:00Z","eventType":"task_completed","taskId":"task-001","message":"Task task-001 execution completed, now verifying"}
{"timestamp":"2026-03-04T10:31:00Z","eventType":"task_verified","taskId":"task-001","status":"pass","message":"Task task-001 verification completed with status pass"}

When updating state, always:

  1. Read current .aa/state.json
  2. Update the relevant fields
  3. Write back the complete state
  4. Append an event to .aa/logs/events.jsonl

Key Principles

  1. Specs are contracts — Given/When/Then specifications are the source of truth for what a task should accomplish. Never skip writing them.
  2. Acceptance tests are proof — Every task must have an executable acceptance test that encodes the Given/When/Then spec. No feature is complete without one. The test fails first (red), then passes after implementation (green).
  3. Deterministic orchestration — The execution plan is computed once from the DAG. No LLM reasoning about "what to do next" — just read the plan.
  4. Isolation per task — Each task runs in its own subagent with curated context. No cross-task state leakage.
  5. Fail fast, retry bounded — 2 retries max. If it doesn't work, escalate to human.
  6. Observable everything — Every state change is logged. Status is always available.
  7. Resumable always — State on disk means you can stop and restart at any point.