Skip to content

Remote-Gated Approval

Syntaxis’s plan and completion gates today are approved in the chat session: you tell the agent “yes, write the plans” or “yes, merge this,” and that approval never leaves the conversation. That works well for a single developer, but it doesn’t fit a team where a lead or PMO needs to review and sign off on a project plan or a finished feature themselves, visibly, on infrastructure the whole team already trusts.

Rather than inventing a new approval system, this proposal routes both decisions through the team’s existing git host — GitHub, GitLab, or Bitbucket — using the pull/merge request review each of those already provides. It’s also the same direction the industry is formalizing: GitHub’s own GH-600 “Agentic AI Developer” certification treats the git host as the control plane and system of record for agent-driven SDLC work — required reviewers, protected branches, and audit history gating what an agent is allowed to advance. This proposal applies that same idea to Syntaxis’s two existing approval points instead of introducing a parallel review system.

Two new optional gates, both delegated to the git host’s own required-reviewer rules instead of anything Syntaxis evaluates itself: plans must land on the protected default branch through an approved pull/merge request before /overview will read them, and /complete opens a request instead of merging locally, landing on main only once the host’s required reviewers approve it.

Step Today
Plan approval You write or approve project-plan.md / build-plan.md directly in the session (/discovery Step 5, or by hand). Nothing outside the session records that approval.
/overview Reads whatever is on disk immediately after you approve it. No check against any remote state.
/complete Squash-merges the feature/fix/rollback branch into local main (Step 3), then separately asks whether to push main upstream. Merge and push are both local, session-approved actions.

Full detail on today’s shipped behavior: The Build Loop, and the overview and complete skills’ own source (.claude/skills/overview/SKILL.md, .claude/skills/complete/SKILL.md).

Syntaxis never evaluates approval. It only verifies presence on the remote’s protected default branch, which the host has already gated.

Every host — GitHub, GitLab, Bitbucket — has a native way to say “this content cannot land on the protected branch without required approvals”: branch protection, protected branches, or merge checks. Instead of teaching Syntaxis to parse GitHub’s review API differently from GitLab’s approval rules differently from Bitbucket’s, both new gates reduce to the same one check on every host: is this exact content already on origin/<default-branch>? That single mechanism is what makes the design provider-agnostic, and it’s also why Syntaxis can never accidentally grant an approval it didn’t have the authority to grant — the host’s branch protection is the only thing actually enforcing “who can approve,” on every provider, the whole time.

A new shared reference (kept in sync across .agents/skills/ and .claude/skills/, as with every other cross-tool piece of the workflow) gives every skill three provider-agnostic operations:

  • detect — read git remote get-url origin, classify the host, and confirm the repo isn’t local-only. No remote means the remote workflow is simply unavailable — same fallback style /overview already uses today for local-only detection.
  • open-request(branch, title, body, reviewers?) — create a pull/merge request.
  • check-landed(path-or-commit) — fetch and compare local content or a commit against the remote default branch tip.
Capability GitHub GitLab Bitbucket
CLI gh, official, mature glab, official, mature no first-party CLI on par with either
Open request gh pr create glab mr create REST call, needs a configured API token
Auth check gh auth status glab auth status no ambient session to check — token presence only
Fetch/compare plain git, universal plain git, universal plain git, universal

GitHub and GitLab are first-class under this design; Bitbucket is a documented second-class adapter with real setup friction, not full parity — see Constraints.

{
"remote": {
"enabled": false,
"provider": "auto",
"planApproval": "manual",
"completeApproval": "local-merge",
"reviewers": []
}
}
  • enabled: false and the manual / local-merge defaults keep every existing project’s behavior exactly as it is today. This is opt-in, the same posture /ci already uses for automatic GitHub checks.
  • planApproval and completeApproval are independent — a team can gate completion only, plans only, or both.
  • Consistent with the existing rule that configuration can only make gates stricter, never grant permission to merge or push: the real “who can approve” enforcement always lives in the host’s branch protection, which Syntaxis doesn’t and can’t configure remotely on a team’s behalf.

/discovery never commits, merges, or pushes anything today — Step 5 only writes the approved drafts to disk. That rule doesn’t change under this proposal. Whether a plan comes from /discovery, is written by hand, or is generated by /adopt, it lands the same way: as local files on disk, with no git action taken yet. That’s exactly why the remote gate can’t live in /discovery — there’s nothing on git to gate at the point it finishes.

/overview — new Step 0, before Step 1 ever runs

Section titled “/overview — new Step 0, before Step 1 ever runs”

This is where the gate actually belongs, because /overview is the one place every plan source already funnels through before anything downstream can use it. Today, the git commit of project-plan.md / build-plan.md doesn’t even happen until /overview’s own Step 4 (“offer the initial planning baseline commit”) — after Steps 1–3 have already read the plans and generated project-overview.md. The proposed gate has to sit in front of that entire sequence, not slotted in as a precondition on top of it.

Today Proposed
Entry Steps 1–4 run in order; the plan files are committed at the end (Step 4), as part of the broader Syntaxis baseline commit When remote.planApproval is "remote-request": a new Step 0 runs first
Step 0 (new) N/A If the on-disk plan bytes aren’t already reachable on origin/<default-branch>: commit just the plan files to a short-lived plans/<slug> branch, push it, open-request with the configured reviewers, and stop. Nothing else in /overview runs yet.
Re-run, request still open N/A Reports the open request and stops again — no polling
Re-run, request landed N/A check-landed confirms it; Steps 1–4 proceed exactly as today
Step 4 adjustment Stages plans + all Syntaxis setup files in one baseline commit Excludes the plan files from its candidate set when they already landed via a merged plan request, so they’re never committed twice

Everything about what /overview does with the plans once they’re readable — Steps 1 through 4 — is completely unchanged. The only new behavior is the one-time check-and-possibly-stop in front of it.

Today Proposed
Steps 0–2 Safety pass, archive findings/review/test-runs, one squash commit Unchanged. The archive already written here is exactly the outcome documentation a reviewer needs.
Step 3 Squash-merge into local main, then separately ask about pushing When remote.completeApproval is "remote-request": push the branch, open-request with a body built from the archive (findings, independent-review receipt, how-to-try-it), then stop. Local main does not move. Dashboard activity becomes ready with resumeCommand: "/complete resume".
New step N/A /complete resume — runs check-landed on the work commit. Merged → fetch, fast-forward local main, run the existing archive/tree integrity check, clean up branches. Still open → report and stop. Closed unmerged → report and let the user decide. Diverged locally → refuse, same as today’s existing-advance check; never force.

Independent review (/audit independent current) is unaffected and complementary, not redundant: it still gates code quality before the request opens; the host’s required reviewers gate the merge itself, which is often a different, non-technical sign-off.

Gains a read-only check: detected provider, whether its CLI is installed and authenticated, and whether the current repo has a remote at all — reported, never enforced, consistent with Doctor’s existing role.

Gains an explicit opt-in question: detected provider, confirmation that reviewers and branch protection are already configured on the host (Syntaxis reports this, it doesn’t configure remote repo settings itself — the same boundary /ci already respects for branch protection today), then writes the remote.* config block.

See each loop’s own page for the exact diagram and a full walkthrough of what changes and what doesn’t:

  • The Build Loop — the numbered /feature → /complete cycle every fresh project runs
  • The QA Loop — how the shared findings ledger now feeds a remote gate instead of a local one
  • The Adopt Loop — the same two gates applied to a brownfield codebase brought in through /adopt
  1. Provider adapter + /doctor checks. Read-only: detect host, check CLI auth, report. No behavior changes anywhere else.
  2. Remote plan-review gate. The new /overview Step 0, behind remote.planApproval. /discovery and hand-written plans are unaffected.
  3. Remote completion-review gate. The redesigned /complete Step 3 and the new /complete resume, behind remote.completeApproval.
  4. Onboarding and docs. /onboard / /ci wiring, this section’s docs promoted out of “proposed” once shipped.

Each phase ships independently and defaults to off, so a team can adopt the plan gate without the completion gate, or vice versa.

  • Bitbucket has no first-party CLI on par with gh or glab. That adapter is REST calls plus a team-managed token — more setup friction, and a maintenance liability if Bitbucket’s API shifts. GitHub and GitLab are first-class; Bitbucket should ship as a documented second-class adapter, not a promise of parity.
  • This assumes push access to the repo. A fork-based contribution model (no push access, cross-repo pull requests) is a materially different flow on every host and is explicitly out of scope for this design. It would need its own follow-up proposal.
  • Auth is ambient and unverified until /doctor checks it. If gh or glab isn’t authenticated when a skill needs it, the required failure mode is “stop with exact setup instructions” — never a silent fallback to local behavior, which would quietly disable a gate the team believes is active.
  • Races are refused, never forced. If local main advances past the recorded base while a request is still open — someone else merged something else first — /complete resume refuses and asks for a rebase or a reopened request, the same posture Step 3 already has today for an ordinary local advance.
  • Branch protection itself is a repo-admin action Syntaxis cannot take. The actual guarantee — “can’t merge until a lead approves” — comes from the host’s branch protection / required reviewers setting, configured once by the team. Syntaxis can refuse to do the merge itself and report whether protection looks configured, but it cannot turn that setting on remotely, the same boundary /ci already has for its own required checks today.
  • Syntaxis will not implement its own approval-evaluation logic for any host.
  • Syntaxis will not create, modify, or manage git host permissions, teams, or branch-protection rules remotely — it only reports what it observes.
  • Fork-based external contribution is not covered by this proposal.
  • This does not change how /feature, /implement, /check, or /audit work — only the two approval points, plan generation and completion, are affected.