Skip to content

Commit fa5a88d

Browse files
Patel230Patel230
committed
docs: rewrite README with modern formatting, add ARCHITECTURE.md
1 parent 82e13a0 commit fa5a88d

3 files changed

Lines changed: 335 additions & 161 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Architecture
2+
3+
This document describes how iterate is structured and how the pieces fit together.
4+
5+
## Overview
6+
7+
iterate is a self-evolving coding agent. It has two modes of operation:
8+
9+
1. **REPL mode** — interactive chat with tool access
10+
2. **Evolution mode** — autonomous plan → implement → communicate loop
11+
12+
Both modes share the same command registry and agent infrastructure.
13+
14+
## Entry Point
15+
16+
```
17+
cmd/iterate/main.go
18+
```
19+
20+
The entry point parses flags, resolves provider config, and dispatches to one of:
21+
22+
- `runREPL()` — interactive mode
23+
- `runEvolutionMode()` — autonomous evolution
24+
- `runSocialMode()` — community interaction
25+
26+
```
27+
main.go → parseFlags() → runMode()
28+
main_mode.go → runMode() → dispatch to REPL / Evolution / Social
29+
```
30+
31+
## Agent Layer
32+
33+
```
34+
internal/agent/
35+
agent.go Agent interface
36+
pool.go Concurrent agent pool for multi-task sessions
37+
mutation.go Mutation testing runner
38+
```
39+
40+
The agent pool manages multiple concurrent agent instances. Each agent wraps the `iteragent` SDK which provides:
41+
- Provider abstraction (Anthropic, OpenAI, Gemini, Groq)
42+
- Tool execution with streaming
43+
- Context management and compaction
44+
45+
## Command Registry
46+
47+
```
48+
internal/commands/
49+
registry.go Core types: Command, Registry, Context, Result
50+
register.go Registration helpers
51+
```
52+
53+
All REPL commands are registered through a central `Registry`. Each command has:
54+
- `Name` — primary name (e.g., `/test`)
55+
- `Aliases` — alternative names
56+
- `Category` — grouping for help display
57+
- `Handler` — function that executes the command
58+
59+
Commands are organized by file:
60+
| File | Commands |
61+
|------|----------|
62+
| `agent.go` | `/help`, `/clear`, `/model`, `/thinking`, `/version`, `/quit` |
63+
| `dev.go` | `/test`, `/build`, `/lint`, `/fix`, `/coverage` |
64+
| `evolution.go` | `/phase`, `/self-improve`, `/evolve-now` |
65+
| `files.go` | `/find`, `/grep`, `/tree`, `/index` |
66+
| `git.go` | `/diff`, `/status`, `/commit`, `/log`, `/branch`, `/stash` |
67+
| `github.go` | `/pr list/view/diff/review/create/comment` |
68+
| `memory.go` | `/remember`, `/memories`, `/forget`, `/learn`, `/memo` |
69+
| `mode.go` | `/safe`, `/multi`, `/thinking` |
70+
| `session.go` | `/save`, `/load`, `/context`, `/tokens`, `/cost`, `/compact` |
71+
| `utility.go` | `/version`, `/stats`, `/changes`, `/history` |
72+
| `analysis.go` | `/count-lines`, `/hotspots`, `/contributors`, `/languages` |
73+
74+
## Evolution Engine
75+
76+
```
77+
internal/evolution/
78+
engine.go Main engine: Run(), RunPlanPhase(), etc.
79+
phases.go Phase implementations
80+
prompts.go System prompts for each phase
81+
parsing.go Parse agent responses into structured data
82+
verify.go Build/test verification
83+
git.go Git operations
84+
journal.go JOURNAL.md writing
85+
memory.go Memory system integration
86+
```
87+
88+
The evolution loop:
89+
90+
```
91+
┌──────────────────────────────────────────────────────────────┐
92+
│ evolution.Run() │
93+
│ │
94+
│ 1. Plan Phase │
95+
│ ├── Read source code │
96+
│ ├── Read JOURNAL.md │
97+
│ ├── Read community issues │
98+
│ └── Write SESSION_PLAN.md │
99+
│ │
100+
│ 2. Implement Phase │
101+
│ ├── For each task in SESSION_PLAN.md: │
102+
│ │ ├── Create agent │
103+
│ │ ├── Execute task (read/write/test) │
104+
│ │ ├── Verify: go build && go test │
105+
│ │ └── Commit if green, revert if red │
106+
│ └── Journal entry │
107+
│ │
108+
│ 3. Communicate Phase │
109+
│ ├── Read SESSION_PLAN.md Issue Responses │
110+
│ ├── Post GitHub comments on addressed issues │
111+
│ └── Write final journal entry │
112+
└──────────────────────────────────────────────────────────────┘
113+
```
114+
115+
## Community Layer
116+
117+
```
118+
internal/community/
119+
github.go Issue fetching and formatting
120+
discussions.go GitHub Discussions integration
121+
```
122+
123+
Fetches issues with labels `agent-input`, `agent-self`, `agent-help-wanted` and formats them for the agent's context.
124+
125+
## Social Engine
126+
127+
```
128+
internal/social/
129+
engine.go Social session runner
130+
engine_discussions.go Discussion interaction
131+
engine_decisions.go Decision logic for responses
132+
```
133+
134+
Reads GitHub discussions, decides whether to participate, and extracts learnings.
135+
136+
## Memory System
137+
138+
Three layers of persistent memory:
139+
140+
| Layer | File | Purpose |
141+
|-------|------|---------|
142+
| Evolution memory | `memory/learnings.jsonl` | Append-only lesson log |
143+
| Active memory | `memory/ACTIVE_LEARNINGS.md` | Synthesized from learnings |
144+
| Project memory | `.iterate/memory.json` | Per-project REPL notes |
145+
146+
All three are injected into the agent's system prompt.
147+
148+
## Skills System
149+
150+
```
151+
skills/<name>/SKILL.md
152+
```
153+
154+
Each skill has YAML frontmatter:
155+
156+
```yaml
157+
---
158+
name: evolve
159+
description: Safely modify your own source code
160+
tools: [bash, read_file, write_file, edit_file]
161+
---
162+
```
163+
164+
Skills are loaded at startup and injected into the agent's context when relevant.
165+
166+
## Scripts
167+
168+
| Script | Purpose |
169+
|--------|---------|
170+
| `scripts/evolution/evolve.sh` | Main evolution pipeline (called by CI) |
171+
| `scripts/social/social.sh` | Social session runner |
172+
| `scripts/build/build_site.py` | Generates `docs/index.html` from `JOURNAL.md` |
173+
| `scripts/build/format_issues.py` | Formats GitHub issues for agent context |
174+
| `scripts/maintenance/synthesize_learnings.py` | Compresses learnings into active memory |
175+
176+
## Data Flow
177+
178+
```
179+
GitHub Actions (cron)
180+
└── evolve.sh
181+
├── build iterate binary
182+
├── fetch issues (format_issues.py)
183+
├── run iterate --phase plan
184+
│ └── writes SESSION_PLAN.md
185+
├── run iterate --phase implement
186+
│ ├── creates agents per task
187+
│ ├── runs go build/test
188+
│ └── commits or reverts
189+
├── run iterate --phase communicate
190+
│ ├── posts GitHub comments
191+
│ └── writes JOURNAL.md entry
192+
└── git push
193+
194+
Deploy workflow (on push to main)
195+
└── build_site.py
196+
└── generates docs/index.html from JOURNAL.md
197+
└── deploys to GitHub Pages
198+
```
199+
200+
## Key Design Decisions
201+
202+
1. **Local replace for iteragent** — `go.mod` uses `replace github.com/GrayCodeAI/iteragent => ../iteragent` for local development. CI checks out iteragent as a sibling directory.
203+
204+
2. **Command registry pattern** — All REPL commands are registered through a central registry, making it easy to add new commands without touching the REPL loop.
205+
206+
3. **Test-gated commits** — The evolution engine runs `go build` and `go test` before every commit. If either fails, the change is reverted.
207+
208+
4. **Journal-first** — Every session writes to `JOURNAL.md` before anything else. The journal is the source of truth for what happened.
209+
210+
5. **Skills as files** — Skills are plain markdown files with YAML frontmatter, making them easy to edit and version control.

‎DAY_COUNT‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1+
<<<<<<< Updated upstream
12
2
3+
=======
4+
4
5+
>>>>>>> Stashed changes

0 commit comments

Comments
 (0)