Skip to content Table of Contents
Install
Guides Safety Reference Design decisions Appendices Docs Design decisions Design decisions
ADR 0001 — The MCP layer is the universal source of truth for agent conventions madtea ships as both a CLI binary and a Model Context Protocol (MCP) server, and as a Claude Code plugin that bundles skills and PreToolUse hooks around that same binary. ADR 0002 — Safe inline body updates: anchored capture-then-update with optimistic-lock write-back madtea lets an agent or a human edit issue bodies, pull-request bodies, and comment bodies. ADR 0003 — Side-effect confirmation is a structural, enforced convention A command that performs a side-effect must tell the caller what it did — otherwise the caller re-runs work that already happened. ADR 0004 — A positive terminal-closure signal on completed results A side-effecting command already confirms what it did (ADR-0003): finish names its merge and pull, a close says “Closed issue #42”. ADR 0005 — Parameter-name ergonomics: proactive schema clarity, not reactive matching Agents reach for a “natural” argument name that is not the tool’s canonical parameter, the JSON unmarshaler silently drops it, and a wasted round-trip follows. Recurring, real instances: ADR 0006 — `finish` always refuses to run from the default branch madtea finish completes a feature branch: it commits, pushes, opens a PR, merges it, and returns to the default branch. ADR 0007 — Structural fail-closed for mutating local-git tools in a multi-repo workspace The legacy tracker 1313 wrong-repo guard (internal/mcp/repoguard.go, commit 352df60) fails closed only when it has a caller-repo signal that differs from the repo the server resolved from its launch-fixed cwd. ADR 0008 — The OperationSpec registry is the single source of record for all operation help and metadata madtea ships as both a CLI binary and an MCP server, and today maintains ADR 0009 — Agent-facing guards are non-overridable; no agent-reachable opt-out madtea’s Claude Code plugin ships four PreToolUse Bash hooks (check-git-{commit,local,cli,remote}.sh). ADR 0010 — A release is a git tag; one blessed cross-platform install Every release left a trail on the default branch: a docs(changelog): backfill [Unreleased] PR, a chore: prepare release PR, and their merge commits (legacy tracker 1711). Two coupled causes: ADR 0011 — linux/macOS/windows are first-class; OS behavior behind build-tag splits madtea ships binaries for linux, macOS, and windows (GoReleaser builds linux_{amd64,arm64}, darwin_{amd64,arm64}, windows_amd64). ADR 0012 — Release signing and trust-on-first-use update verification madtea update downloads a release and replaces the running binary. ADR 0013 — Credential storage: secure-backend-preferred, scope-consistent, never on argv madtea authenticates to a forge with a token; where and how it is stored sets the blast radius of a leak. ADR 0014 — CLI and MCP are thin surfaces over one service layer madtea ships two distinct user-facing surfaces: the Cobra CLI (internal/cmd) and the MCP server (internal/mcp). ADR 0015 — One MCP tool per resource noun, action-dispatched madtea’s MCP server must expose the full Forgejo/Gitea API surface to an agent. ADR 0016 — Names match gh/tea verbatim; no invented vocabulary madtea exposes two surfaces — the Cobra CLI (madtea …) and the MCP server (madt_<noun> tools) — and every operation appears on both. ADR 0017 — Target the standard Gitea API v1; surface Forgejo gaps transparently madtea is described in the project CLAUDE.md as follows: “Forgejo compatibility: Uses standard API v1 endpoints that Forgejo maintains for Gitea compatibility. ADR 0018 — internal/diag is the sole diagnostics emitter madtea ships as both a CLI binary and an MCP server (ADR 0014). The two surfaces have different output channels: ADR 0019 — Foreign-repo primary checkouts are immutable to madtea ADR 0007 (structural fail-closed, multi-repo) introduced dir= targeting: a madtea agent can name any other on-disk git repository as the target of a mutating local-git tool (madt_branch_create, madt_commit, madt_push, …). ADR 0020 — Identifier arity is a hard boundary: a singular parameter never becomes a batch The FlexIDs lineage made identifier value shapes liberal: numbers accepts 441, "441", [441], ["441"], and "441, 442", all normalized to []string. ADR 0021 — Pure-read local-git steering is non-blocking advisory, not a hard deny madtea’s Claude Code plugin ships a local-git steering hook (hooks/scripts/check-git-local.sh) that intercepts the agent’s Bash tool and redirects raw git forms to the madt_* MCP tool that does the same job. ADR 0022 — Hermetic test guard: `go test` cannot resolve real credentials or mutate the real checkout A handler test called issuesDevelop without sandboxing. ADR 0023 — Shipped strings are self-contained: no internal references in steering, error, or refusal text madtea ships strings to users in three compiled-in forms: hook steering text (the plugin’s PreToolUse scripts), error/refusal returns from the CLI and the madt_* tools, and MCP tool/parameter descriptions. ADR 0024 — Declared-files staging: a commit's file set must be named, never swept madt_commit and madt_finish (and madt_add) once offered a blanket-staging mode — all=true on the MCP surface, -A/--all on the CLI — that ran the equivalent of git add -A before… ADR 0025 — Origin-first forge resolution and host-keyed credentials madtea resolves a repository’s path (owner/name) from its origin remote, but resolves the API server from the single madtea.url config value. ADR 0026 — Guard texts are terminal or forwarding: no guard cycles, no dead ends madtea steers agents away from raw, credential-unsafe or shared-state-unsafe git through two families of guards: the Claude Code plugin’s PreToolUse hooks (they deny/advise on the Bash tool) and the… ADR 0027 — Launch scope is the credential boundary; `dir=` is never a token selector dir= began as a repo selector for local-git tools (ADR 0007) and was extended to any git repo on disk (legacy tracker 1862), with ADR 0019 clamping foreign primaries to the worktree→finish contribution flow. ADR 0028 — Semver tiers within 0.x; no launch-gated version freeze Two changes to the original decision: ADR 0029 - Strict omission: no madtea surface carries a work-destroying override madtea’s destructive-operation surfaces grew case by case, and by mid-2026 three different safety models coexisted with no ADR pinning any of them: ADR 0030 — git-mirrored CLI commands anchor their argument shape to git's signature ADR 0016 pins CLI subcommand, flag, and MCP action names to gh then tea verbatim, and docs/contributing/naming-conventions.md records the one refinement it already needs: madtea’s thin… ADR 0031 - Recoverable-guard tier: refuse wrong-workflow acts by default, override per call ADR 0029 pinned the rule for unrecoverable acts: they are omitted from every madtea surface. 