Skip to content

Add Mermaid architecture diagram to README #61

Description

@mrjf

Add a Mermaid diagram to the README showing the autoloop flow. Something like:

flowchart TD
    subgraph "Pre-step"
        S[autoloop_scheduler.py] -->|reads| PD[".autoloop/programs/{name}/program.md"]
        S -->|reads| SF[("memory/autoloop branch<br/>{name}.md state file")]
        S -->|writes| AJ["/tmp/gh-aw/autoloop.json"]
    end

    subgraph "Agent Step"
        AJ -->|selected program| A1["Step 1-2: Read program,<br/>state file, target files,<br/>issue comments"]
        A1 --> A3["Step 3: Checkout autoloop/{name}<br/>fast-forward to main"]
        A3 --> A4["Step 4: Propose change,<br/>run evaluation command"]
        A4 -->|metric improved| A5a["Step 5a: Commit → push<br/>via create_pull_request /<br/>push_to_pull_request_branch"]
        A4 -->|no improvement| REJ["Reject: update state,<br/>no push"]
        A5a -->|CI green| A5c["Step 5c: Accept<br/>update state, post to issue"]
        A5a -->|CI red| A5b["Step 5b: Fix loop<br/>(up to 5 attempts)"]
        A5b -->|fixed| A5a
        A5b -->|exhausted| PAUSE["Pause program"]
    end

    subgraph "Safe Outputs Step"
        A5a -->|patch artifact| SO["Apply patch to remote branch<br/>Create/update PR<br/>Post comments to issue"]
    end

    subgraph "Persistence"
        A5c -->|writes| SF
        REJ -->|writes| SF
        SO -->|pushes| BR["autoloop/{name} branch"]
        SO -->|creates/updates| PR["Draft PR"]
        SO -->|comments on| ISS["Program issue<br/>[Autoloop: {name}]"]
    end

    subgraph "Supporting"
        EV["Evergreen (every 5m)"] -->|fixes CI / merges main| PR
        CI["CI workflow"] -->|runs on push| BR
    end
Loading

The diagram should cover:

  • The three phases: scheduler pre-step → agent step → safe-outputs step
  • What gets read (program def, state file, issue comments, target files)
  • The accept/reject decision tree
  • The CI fix loop
  • How state persists (repo-memory branch, program issue, PR branch)
  • How Evergreen and CI interact with the autoloop PRs

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions