Workflows

High-level git workflow commands for branch completion, orchestration, ADR management, and merged-branch pruning.

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 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 need no credentials; private repos require madtea auth login first. Per-repo credentials are configured automatically. Never raw git clone a credentialed URL (leaks the token). Under ssh/ssh-only git-protocol it clones over SSH as git@host:owner/repo.git, no token on the git wire. The result names the forge host and warns on read-only mirrors.

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=). No blanket “stage everything” mode (the removed all=true/git add -A): declare 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, use madt_push then madt_prs action=create draft=true - 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 - parent epics (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 linked worktree’s branch (same repo, no dir=) without disturbing its checkout. Pass dir= to target another local git repo by 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 cwd is NOT itself a git repo (a plain parent dir of clones), a repo whose toplevel is strictly UNDER that dir is in-scope, not foreign: finish it via branch= (no checkout to stage) with normal branch-detected auto-close (no forced no_close=true). Without dir, targets the server’s cwd; 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 (same overrides). For the parallel-agent worktree flow, see madt_help(topic="worktrees"). A failed finish returns the step ledger with a partial-progress line naming what completed - staging failures included (step ‘commit’ failed, not a bare error). Re-running the identical call converges without duplicating work: a commit-landed/push-failed state re-runs without re-committing (files= included). One exception: if the MERGE landed but the final return step failed, recover with madt_pull - a re-run cannot converge from that state. A provably-stale .git/index.lock self-heals with a stated confirmation; a held lock refuses with a teaching error naming the lock path.

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=<pr>): 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. A dry run (default) previews the full set: merged local branches AND remote-only orphans (no remote=true needed to preview them). delete_branches=true deletes the local branches; remote=true also deletes the remote twins and orphans, then cleans the now-stale remote-tracking refs. Local branches squash/cherry-pick-merged (squash_merged, content already in the default branch) are ALSO deleted under delete_branches=true - their remote twins under remote=true. 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