/internal/docs/CONTINUOUS_IMPROVEMENT.md

Continuous Improvement Loop

Go Micro is an agent harness. This file defines the autonomous loop that builds it — the framework's own thesis (an agent operating a system) pointed at itself. Claude Code drives the loop; Codex executes scoped tasks; the human sets direction and can stop or revert anything at any time.

North Star. Every increment must advance the thesis in THESIS.md: a holistic agent harness and service framework encapsulating the lifecycle of services → agents → workflows. Judge each change against it — work that doesn't move toward that lifecycle isn't an improvement, however clean.

Autonomy

Full autonomy, no approval gates. Each increment: Claude Code picks the work, implements it (or dispatches Codex), opens a PR, and merges it — including reviewing and merging Codex's PRs. The only gate is correctness: go build, go test, and golangci-lint must be green (that's not an approval, it's not shipping broken code).

Transparency replaces approval: every increment ends with a one-line digest, and every change is a small, reversible, single-concern PR the human can revert.

What counts as an improvement

Grounded in real signal, never speculative rewrites. Each cycle draws from:

1. Roadmap — the Now/Next items in ROADMAP.md (harness depth: durable runs, observability, streaming, human-in-the-loop; hardening: resilience, conformance).
2. Open issues — the scoped backlog (e.g. #3010–#3014).
3. Improvement radar — a scan each cycle for: missing/weak tests, lint or quality issues, docs/code drift, and DX friction.
4. Dogfooding — actually build with the harness (micro new → run → chat, an agent + a flow) and fix what hurts. Friction found here is high-signal.

The cycle (one increment)

1. Sync master.
2. If a Codex PR is open and CI-green → review (diff + gates + correctness vs its issue) and merge it.
3. Else pick the single highest-value item from the sources above.
4. Implement it, or dispatch to Codex (@codex <instruction> on the issue) if it's a well-scoped chunk and Codex is free. Codex is serial — one task at a time.
5. Verify build/test/lint locally.
6. Open a PR (one concern) and merge it.
7. Post a one-line digest; refresh the backlog from the radar.

Roles

• Claude Code — orchestrator, implementer, reviewer, integrator, merger.
• Codex — serial builder for well-scoped chunks, dispatched via @codex.
• Human — sets direction; owns brand/positioning copy and breaking public-API decisions; can stop or revert anything.

Guardrails

• One concern per PR; small and reversible.
• Stay on claude/* branches (Codex on codex/*); never two agents on one branch; base PRs on master (don't stack on an in-flight branch). See CODEX.md.
• Off-limits without the human: brand/positioning/marketing copy, breaking public API changes, product-default changes with broad behavioral impact, new dependencies, architectural rewrites. The loop proposes these in the digest; it does not merge them autonomously.

Scheduling

• In-session cron (CronCreate) — runs increments while this Claude session is alive. Convenient, but the remote environment is reclaimed on inactivity and recurring jobs expire after 7 days, so it is not a durable scheduler.
• GitHub Actions (durable) — a scheduled workflow that runs the loop independently of any session. This is the real backbone; it opens a fresh tracking issue for each increment and dispatches Codex there. It needs a CODEX_TRIGGER_TOKEN repo secret from a user account Codex responds to; without that secret the workflow deliberately no-ops to avoid ignored bot comments. See .github/workflows/continuous-improvement.yml and the mechanics below.

How the durable loop works (mechanics)

Hard-won wiring — change any one piece and the loop silently stops producing merged PRs. Each scheduled run:

1. Opens a fresh issue per increment (Continuous improvement increment #N) and posts the @codex instruction on it. Why a fresh issue: Codex derives its branch name from the triggering issue's context, so re-using one tracker issue collapses every run onto one branch name and only the first PR opens — the rest collide and silently fail.

2. Posts as a user, not the Actions bot. Codex ignores @codex comments authored by github-actions[bot], so the dispatch uses CODEX_TRIGGER_TOKEN (a PAT for a user account Codex follows). No token → the step no-ops.

3. Codex opens the PR itself with gh — never make_pr. In the Codex Cloud sandbox the make_pr tool is a no-op stub: it records the PR title/body for the manual "Create PR" button and never pushes a branch or calls the API. So the dispatch and AGENTS.md tell Codex to do it by hand:

   git switch -c codex/increment-<issue>     # unique branch, codex/ prefix
   git push -u origin codex/increment-<issue>
   gh pr create --base master --label codex --title "…" --body "… Closes #<issue>"
   gh pr merge  --squash --auto --delete-branch
   

   This requires the Codex setup script to install gh and run gh auth setup-git (so git push is authenticated) with a write-scoped token.

4. Merges via GitHub native auto-merge, gated by branch protection. master requires the CI status checks (build, tests, golangci-lint) and 0 approving reviews. gh pr merge --auto enables auto-merge; GitHub lands the PR the moment checks pass and deletes the branch. Closes #<issue> auto-closes the tracking issue. There is no merge sweep workflow — branch protection is the gate.

Do-not-break list

• Don't re-add required approvals to master — it blocks every autonomous merge. The intended gate is green CI only.
• Don't point the dispatch at one standing tracker issue — one issue per run.
• Don't tell Codex to use make_pr (or imply a token "isn't a substitute"): it cannot open a PR. gh is the only path.
• Don't manually re-implement a Codex increment during the summary→PR lag (Codex posts an optimistic "opened a PR" comment ~30–45 min before the PR actually appears). Re-doing it creates duplicate PRs and stale branches that then block the next run. Wait for the PR, or let it ride.

Overseer passes (DevRel + Architect)

The hourly loop ships increments; two periodic passes keep the whole heading in the right direction. Both use the same mechanism (fresh issue → @codex → output) but produce direction and coherence, not just code.

• DevRel — daily (.github/workflows/devrel-review.yml). Audits the public surface (README, website landing + docs, blog) for coherence with the North Star, README crispness, and blog-worthy material. Autonomy boundary: safe factual-alignment and crispness fixes auto-merge like any increment; brand/positioning copy and blog drafts are surfaced in a report for the human, never auto-merged.
• Architect — every few days (.github/workflows/architecture-review.yml). Reviews the framework/harness against the thesis: API coherence, lifecycle gaps, drift/sprawl. Its output is an assessment plus scoped follow-up issues that feed the hourly increment loop — it does not make breaking or architectural changes itself (those stay with the human).

Together they close the loop: the architect decides what should change and files issues, the increment loop builds them, and DevRel keeps the public story honest. Cadence is tunable in each workflow's cron. Codex is serial, so these passes queue behind any in-flight increment rather than running concurrently.

Stop / redirect

• In-session: CronDelete <id> (or end the session).
• Durable: disable/delete the workflow.
• Or just tell Claude Code to pause or change focus — direction always wins over the loop.