Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add Mermaid architecture diagram to README

Open
#61 0 comments 1 reaction 2 assignees View on GitHub

@mrjf is already working on this.

Since May 6, 2026.

  • #62 by @copilot-swe-agent — open

Assessment

This issue has not been assessed yet.

Description

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

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
Dominant language
Python
Stars
72
Forks
6
PR merge metrics
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from githubnext/autoloop

All issues in githubnext/autoloop

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.