3.1 KiB
archied — design notes
Archie is a resident daemon that keeps personal projects moving: it polls GitHub for issues labelled
archie, works each one in an isolated fresh-clone worktree through a routed workflow, and opens a
pull request for human review. Sam reviews and merges; the machine grinds in between.
Guiding principle: environmental constraints over prompt instructions. Agents don't get asked nicely
to write good code — the quality gate (vet/build/test/lint, configurable per repo and per workflow stage)
refuses to let a run succeed until it passes. The gate mechanics live in ai-sdk/agentloop; this repo
owns orchestration only.
Workflows, not a pipeline
internal/workflow is the engine: a Workflow is an ordered list of stages over a shared TaskContext;
stages are deterministic steps (worktree, gate, diff cap, PR, comments — the shared step library in
steps.go) or agent stages (agentloop.Run with a stage-specific mission/toolset/gate). Routing is
label-driven (bug → tdd, feature → feasibility, default → implement), refinable by an LLM triage
stage. Adding a workflow must never require touching the engine or reimplementing steps.
Planned workflows:
- bootstrap (registered): deterministic marker-file PR proving invites/clone/push/PR plumbing.
- implement: planner (read-only agentloop, plan posted to the issue) → builder (full toolset, repo gate) → diff cap → PR.
- tdd (bugfixes): analyse → problem surface → write failing repro tests (gate stage with
ExpectFailure) → fix (gate: suite passes) → PR. - feasibility (features): read-only analysis → roadmap fit → won't-do close with reasons, or
plan + PRD → email Sam →
waiting_human→ LLM-judged reply → hand off to implement.
Task lifecycle
queued → running(workflow:stage) → waiting_human | pr_open → merged | parked | rejected | closed_wont_do
SQLite (internal/store), WAL, one row per issue with a transitions audit table. Crash recovery:
running tasks re-queue on startup with attempt++. Parks are never silent — every park comments on the
issue with the reason and gate output.
Rejected alternative: building on tau's peer-agent runtime
tau has a working headless child (internal/app/child.go RunChild(), stdio-JSONL, shared SQLite): the
wrong substrate here. Its model is ephemeral child processes under an explicit "no resident process"
principle, and it drags tau's store/coordinator/session machinery into a batch worker. archied instead
shares code with tau at the module level: ai-sdk/toolkit (the promoted tool set) and ai-sdk/agentloop
(gate/budgets/loop-breaker, patterns harvested from tau's coordinator).
Security posture
- Fine-grained PAT on the bot account only (Contents RW, PRs RW, Issues RW, Metadata R), via
ARCHIE_GITHUB_TOKEN; git auth through an askpass helper so the token stays out of argv and.git/config. - The model never runs git:
internal/worktreeowns all repo operations deterministically. - Agent tools are jailed to the task worktree (toolkit path jail); intended deployment is a dedicated Incus container so the blast radius is environmental, not prompt-negotiated.