46 lines
2.6 KiB
Markdown
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.
|