Workflows

Destruction model for prune (content-verified, never force-delete) and branch delete: ADR 0029.

CLI Commands

madtea adr check

Verify ADR numbering, index bijection, and links (exit 1 on drift)

madtea adr new

Create the next ADR record and index row (number from origin)

madtea finish

Commit, push, create PR, merge, and return to default branch

madtea init

Create a new repository and push initial commit

madtea orchestrate

Merge PRs in batch with verification and bisect failure isolation

madtea orchestrate reconcile

Merge a moved base branch into an open PR’s head (no force-push)

madtea prune

Clean up stale remote refs and merged branches

madtea secret-exec

Execute a command with the Forgejo/Gitea token injected as an environment variable

MCP Tools

madt_adr

Create and consistency-check architecture decision records (ADRs) in any repo that carries a docs/adr/ tree.

Output schema: declared

One tool, action-dispatched. Set action to one of:

action="check"

Verify the ADR tree — unique numbers, file/index bijection, and resolvable links — and report every inconsistency; a clean tree returns OK. Returns an error when drift is found so it wires straight into a gate.

action="new"

Create the next ADR record and index row; the number is resolved from the origin default branch, NOT the local tree, so a diverged branch cannot reissue a landed number. Fails if origin is unreachable — pass offline=true to number from the local tree instead.

Required: slug

Optional: title, tracking, offline

Example:

madt_adr(action="new", slug="origin-first-forge-resolution")

madt_clone

Clone a Forgejo/Gitea repository - public repos succeed without credentials; private repos require madtea auth login first. When credentials are configured, per-repo credentials are set up automatically. Use this instead of raw git clone with a credentialed URL (which would leak the token into git config/history). The result names the resolved forge host and warns when the repo is a read-only mirror.

Output schema: declared

madt_finish

Complete a feature branch: commit, push, create PR, merge, return to mainline. Must be run from a FEATURE branch (errors on the default branch). The commit step commits the staged changes — or stages files=[…] itself in THIS call (mirrors madt_add/madt_commit; mutually exclusive with no_commit/branch=), collapsing the separate madt_commit step. There is no blanket “stage everything” mode (the removed all=true/git add -A): declare the paths in files=[…], or stage via madt_add first (check with madt_status), or set no_commit=true if already committed; mixed staged/unstaged trees silently drop unstaged edits from the PR. Merges to the DEFAULT branch — ONLY for branch completion, NOT for intermediate work (use madt_commit for mid-branch checkpoints; push with madt_push). It ALWAYS merges: for a review-only PR without merging, use madt_push then madt_prs action=create draft=true instead — and do not call finish on a branch that already has an open PR. Branch-detected issues (e.g. ‘feat/issue-321-thing’) auto-close iff they have no open dependencies in Forgejo/Gitea — issues that look like parent epics (have open deps) are referenced instead. Override with closes/close_linked/no_close. Set branch= to finish a branch by name without checking it out: the branch must exist and be ahead of the default; use this for a branch in a linked worktree (same repo, no dir=) without disturbing its checkout. Pass dir= to target another local git repo by path (validated, any path); a same-repo dir changes nothing. A FOREIGN dir requires branch= (no checkout-mode finish cross-repo) and defaults no_close=true (override via closes=/close_linked=). When the server’s working directory is itself NOT a git repo (a session launched in a plain parent dir that merely contains clones), a repo whose toplevel is strictly UNDER that dir is in-scope, not foreign: it is finished via branch= (there is no checkout to stage in a non-git cwd) but keeps normal branch-detected auto-close (no forced no_close=true). Without dir, targets the server’s working directory; in a detected multi-repo workspace with no dir it fails closed regardless (set MADTEA_CALLER_REPO). Set owner_repo=owner/repo (no dir, no checkout) to complete a forge-only branch (e.g. one committed by madt_files new_branch=) via a pure API path: open the PR, merge (honoring default_merge_style), delete the remote branch. Requires branch=; mutually exclusive with dir=/files=/no_commit; defaults no_close=true (override via closes=/close_linked=). For the parallel-agent worktree flow (commit in a linked worktree with madt_commit dir=, then finish it by name with branch= from the mainline checkout), see madt_help(topic=“worktrees”).

Output schema: declared

madt_init

Bootstrap a new repository: create remote, init local, stage everything (git add -A), commit, push. Set org to create under an organization; omit org for a personal repo. Only for brand-new work: fails if the target directory already has commits — to publish an EXISTING local repo, create the remote with madt_repos action=create, then madt_remote_add, then push. Creates a README.md if the directory is empty.

Output schema: declared

madt_orchestrate

Merge PRs in batch with verification and bisect failure isolation, OR reconcile a conflicted PR whose base moved. BATCH-MERGE mode (prs + verify): merges all PRs first, runs verify once, then bisects to find and revert culprits on failure. Already-merged PRs are skipped (safe to re-run). Requires a local checkout that is ON the default branch with a CLEAN working tree — the run pulls the current branch after merging, checks out commits during bisection (fails on a dirty tree), and creates revert branches from HEAD. All listed PRs must be open and non-draft: a closed or draft PR aborts the entire run before any merge (only already-merged PRs are skipped). SECURITY: verify runs via sh -c with full local shell access (env vars, files, network) and may execute multiple times during bisection — only pass trusted commands, never untrusted or user-supplied strings. RECONCILE mode (reconcile=): the push-compatible, force-push-free recovery when madt_finish/merge fails because the base branch moved under an open PR — checks out the PR’s head and merges the latest base INTO it, so the follow-up push needs no force. A clean merge is pushed and steers you back to finish/merge; a conflict returns the conflicted-file work-list plus continue/abort rails: resolve, madt_add the files, then reconcile_continue=true or reconcile_abort=true. Reconcile also takes dir=/owner_repo= (see param docs) for foreign-repo PRs: reconciled in a linked worktree holding the head; a foreign PRIMARY checkout is refused.

Output schema: declared

madt_prune

Clean up stale remote refs and delete branches merged into the default branch. Default is dry run; set delete_branches=true to delete. Set remote=true to also delete merged remote twins and merged remote-only branches (orphans), then remove the now-stale remote-tracking refs. Local branches whose content already landed in the default branch via a squash/cherry-pick merge (squash_merged) are content-verified, so they too ARE deleted under delete_branches=true - including their remote twins under remote=true - and listed as would-delete on a dry run. Branches held by a linked worktree are skipped and reported, never attempted-and-errored. To delete one specific (possibly unmerged) remote branch, use madt_branches_remote action=delete instead.

Output schema: declared