EpiAwareAgents

The configuration, prompts, skills, guardrails, and job definitions for the agent fleet that runs routine maintenance across the EpiAware GitHub org — triaging issues, drafting designs, implementing small changes as human-reviewed PRs, unsticking stalled PRs, and reporting every morning on what actually needs a human.

Status: design phase. Nothing here runs yet. Start with:

• DESIGN.md — the full system design: identity (GitHub App), security model (container-per-job, byte-level push guard, token broker, native sandbox), the job pipeline, the private reports site served over Tailscale, budget/capacity plan, and a v1/v2/v3 implementation plan.
• PAIN-POINTS.md — the risk register: every known pain point with its mitigation, residual risk, and the decisions that need the org lead. Read the consolidated decision list at the bottom first.
• docs/reference/claude-code-recommendations.md — dated snapshot of the official Anthropic/Claude Code guidance the design is grounded in.

The one-paragraph version

A GitHub App identity (epiaware-agent[bot]) acts across the org with per-job, per-repo, 1-hour tokens. Jobs run on systemd timers on a dedicated desktop, one fresh container per work unit, with all behaviour defined in this repo (nothing from the host's own Claude setup). Code owners can delegate tasks by mentioning @epiaware-agent; authorization is checked deterministically against CODEOWNERS/an allowlist, never against message text. Nightly jobs triage issues, draft designs, implement a review-debt-gated trickle of easy PRs (draft until an internal review passes; the agent never merges), and unstick stalled PRs. A weekly retrospective feeds cross-package patterns back into shared org tooling. Every action becomes a structured event; each morning a private report — served tailnet-only via Tailscale, stored in a private repo — says what happened and what needs a human, and an off-host dead-man's switch emails if the system goes quiet.

Design principles

1. Assume every prompt injection succeeds; make the damage boring anyway (sandbox, scoped tokens, deterministic guards — never prompt secrecy).
2. GitHub is the database; the host holds only reconstructible state.
3. Scripts report, models narrate; silence is alarmed off-host.
4. The pipeline throttles to the human reviewer, not to a clock.
5. One busy academic must be able to ignore it for three weeks safely.