theonepichael/agent-toolkit

A modular, multi-harness platform for AI agent workflows and paired development across:
- **Claude Code** (Anthropic)
- **GitHub Copilot CLI** (GitHub)
- **OpenCode** (Local / Multi-provider TUI)
- **Google Antigravity (AGY)** (Google DeepMind)
- **Pi** (Lightweight extensible terminal assistant)
- **Codex CLI** (OpenAI)
> **Status: independent.** Every file in this repository, including
> claude/CORE_INSTRUCTIONS.md, is authored directly here — zero external
> dependency. The GitHub remote is public (since 2026-09-08). See
> MIGRATION.md for the history of how this repo got here.
---
Features & Capabilities
- **Unified Core Workflows**: Standardized slash commands and skills across harnesses (/grill-me for design alignment, /second-opinion for architectural critique, /spec for structured specifications, /backlog-item for gated TDD lifecycle, /review-diff for a cross-model review of the staged diff, /land for the commit and merge gates, /to-tickets for splitting a plan into linked backlog items, /standup for daily progress synthesis, /dashboard and /recap for work tracking, /analyze-sessions for cost and transcript search, /refresh-guidance for doc staleness, /make-skill for authoring skills). INTERFACES.md lists which harnesses carry each one.
- **Contract-Gated Backlog**: dev_status.py items can carry acceptance criteria cited from a repo's own contract docs, frozen once work starts; done/approve refuse until a passed gate covers them, and an independent_verifier item can only be gate-passed by a session holding its private verifier token file.
- **Worker Delegation in herdr**: herdr_delegate.py launches backlog items into herdr tabs — pi or copilot queue runs (/swarm), or one item to a pi, copilot, agy or codex worker — and /foreman lets one interactive session schedule pi workers, review their work (watch, answer), and land it (--handoff, pi only).
- **Automated Guard Rails**: Pre-tool hooks and git pre-commit hooks that prevent committing directly to main and protect active task checkouts (see Git hooks). A repo can let gitignored provenance folders through that main-checkout protection by listing them in a .guard-rails.json file at its root ({"provenance_roots": ["reports/local"]}).
- **Seed Rewrite Guard**: A pre-commit check refuses a commit whose staged seed would lose SessionStart hook groups relative to HEAD — the lossy-rewrite race that once committed a seed without its matcher-* herdr group. Intentional drops use SEED_HOOK_ALLOW_DROP=1, never --no-verify.
- **Auto-Formatting on Tool Use**: Automatic Ruff formatting/lint fixing on Python edits.
- **Shell Completions & Environment Helpers**: Portable shell/agent-tools.zsh providing completions, PATH setup, and harness aliases.
- **Cross-Harness Code Generation**: Generators keep documentation (INTERFACES.md) and prompt templates (templates/*.tmpl) in sync across all 6 harnesses, compile one bash permission matrix (permission_matrix.py) into the Claude, opencode and Pi permission seeds (gen_permissions.py), and compile lifecycle hooks for Claude, Copilot and agy from one manifest (gen_hooks.py).
- **Architectural Overview & Progressive Disclosure**: System diagrams, component maps, and lifecycle flows are detailed in docs/architecture/overview.md, complemented by the progressive disclosure rubric.
---
Prerequisites: Install your chosen harness(es)
Install whichever CLI harness(es) you plan to use:
| Harness | Recommended Installation |
| :--- | :--- |
| **Claude Code** | npm install -g @anthropic-ai/claude-code |
| **GitHub Copilot CLI** | npm install -g @github/copilot |
| **OpenCode** | curl -fsSL https://opencode.ai/install \| bash |
| **Google Antigravity (AGY)** | Internal workstation installation |
| **Pi** | npm install -g @mariozechner/pi-cli |
| **Codex CLI** | npm install -g @openai/codex |
System tools:
- **Python 3.14** is the default runtime (dev venv, primary CI job). Hooks and githooks/ run bare python3, so make that resolve to 3.14 (e.g. uv python install 3.14 --default, with ~/.local/bin ahead of /usr/bin on PATH). 3.12 stays a supported, CI-tested floor until the work machine's Python is confirmed. ./install.sh prefers python3.14 when it is on PATH.