Design decisions

• ADR 0001 - Agent conventions live in the MCP layer 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 madtea lets an agent or a human edit issue bodies, pull-request bodies, and comment bodies.
• ADR 0003 - Side-effect confirmation is structural 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 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 - Proactive parameter-name schema clarity 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 refuses 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 in multi-repo workspaces Mutating local-git MCP calls fail closed when the server cwd is a structurally detected multi-repo workspace and no caller-repo signal is present, closing a dead-zone that signal-only guards could…
• ADR 0008 - The operation registry is the source of record madtea ships as both a CLI binary and an MCP server, and today maintains two independently-authored help corpora:
• ADR 0009 - Agent-facing guards are non-overridable madtea’s Claude Code plugin ships four PreToolUse Bash hooks (check-git-{commit,local,cli,remote}.sh).
• ADR 0010 - Tag-driven releases, one blessed 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. Two coupled causes:
• ADR 0011 - Cross-platform support is first-class 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 updates madtea update downloads a release and replaces the running binary.
• ADR 0013 - Secure-backend-preferred credential storage 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 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 madtea targets the standard Gitea API v1 endpoints that Forgejo maintains for compatibility, working with both platforms without modification.
• 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 primary checkouts are immutable 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 The FlexIDs lineage made identifier value shapes liberal: multiple input forms for a number list are normalized to []string.
• ADR 0021 - Pure-read steering is advisory 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 A handler test called issuesDevelop without sandboxing.
• ADR 0023 - Shipped strings are self-contained 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 - Commit file sets are declared, 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 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= began as a repo selector for local-git tools (ADR 0007) and was extended to any git repo on disk, with ADR 0019 clamping foreign primaries to the worktree→finish contribution flow.
• ADR 0028 - Semver tiers within 0.x Within 0.x, breaking changes bump MINOR and all other releasable types bump PATCH; the cadence gate counts releasable commits regardless of tier.
• ADR 0029 - No 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 commands match git's argument shape ADR 0016 pins CLI subcommand, flag, and MCP action names to gh then tea verbatim, with one refinement for git-mirrored commands: madtea’s thin wrappers over local git commands (branch,…
• ADR 0031 - Recoverable guards refuse by default, override per call ADR 0029 pinned the rule for unrecoverable acts: they are omitted from every madtea surface.