Files
archie/docs/archive/DESIGN.md
T

46 lines
2.6 KiB
Markdown

# 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.
## 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/worktree` owns 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.