Remote-Gated Approval
Why this is being proposed
Section titled “Why this is being proposed”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.
What changes, in one sentence
Section titled “What changes, in one sentence”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.
Current state, shipped today
Section titled “Current state, shipped today”| 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).
Core design principle
Section titled “Core design principle”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.
Provider abstraction
Section titled “Provider abstraction”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/overviewalready 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.
Proposed configuration
Section titled “Proposed configuration”{ "remote": { "enabled": false, "provider": "auto", "planApproval": "manual", "completeApproval": "local-merge", "reviewers": [] }}enabled: falseand themanual/local-mergedefaults keep every existing project’s behavior exactly as it is today. This is opt-in, the same posture/cialready uses for automatic GitHub checks.planApprovalandcompleteApprovalare 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.
Skill-by-skill changes
Section titled “Skill-by-skill changes”/discovery — unchanged
Section titled “/discovery — unchanged”/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.
/complete — Step 3, “merge”
Section titled “/complete — Step 3, “merge””| 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.
/doctor
Section titled “/doctor”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.
/onboard / /ci
Section titled “/onboard / /ci”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.
The three loops
Section titled “The three loops”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 → /completecycle 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
Proposed rollout
Section titled “Proposed rollout”- Provider adapter +
/doctorchecks. Read-only: detect host, check CLI auth, report. No behavior changes anywhere else. - Remote plan-review gate. The new
/overviewStep 0, behindremote.planApproval./discoveryand hand-written plans are unaffected. - Remote completion-review gate. The redesigned
/completeStep 3 and the new/complete resume, behindremote.completeApproval. - Onboarding and docs.
/onboard//ciwiring, 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.
Constraints and open questions
Section titled “Constraints and open questions”- Bitbucket has no first-party CLI on par with
ghorglab. 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
/doctorchecks it. Ifghorglabisn’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
mainadvances past the recorded base while a request is still open — someone else merged something else first —/complete resumerefuses 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
/cialready has for its own required checks today.
Non-goals
Section titled “Non-goals”- 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/auditwork — only the two approval points, plan generation and completion, are affected.