Skip to content

AGENT.md

Latest commit

 

History

History
119 lines (100 loc) · 5.63 KB

AGENT.md

File metadata and controls

119 lines (100 loc) · 5.63 KB
Raw

Syncwheel For AI Agents

Use Syncwheel for deterministic Git maintenance in repositories with PR stacks, integration branches, pinned deployment channels, dedicated worktrees, forks, or more than one human/agent touching branches.

First Checks

Run these before branch, worktree, push, PR, recovery, or final handoff work:

syncwheel repo tracking status
syncwheel status --fetch
syncwheel validate
syncwheel reconcile

If syncwheel_tracking is missing, stop and ask whether the repo should be git-tracked or local-only. Persist the answer with syncwheel repo tracking set ... --apply before continuing.

For a version 2 or 3 manifest with coordination.mode: "active-active", run this read-only handoff check before planning a mutation or taking over from another device:

syncwheel handoff

Mutation Rules

For repository_mode: "journal", do not use stack or integration commands. Run journal status, then plan with journal snapshot or journal publish; add --apply only for an authorized commit or exact-lease push. To catch up with other writers, use journal pull (plan) and journal pull --apply, never a raw git merge or git pull; journal publish --apply pulls first. Resolve journal conflicts yourself: run journal pull --apply --park-conflicts, merge each parked conflict entry into the working tree keeping both sides' intent, then journal publish --apply. Ask a human only when the sides contradict. Scheduler install/remove is also plan-first and Linux-only.

When Agentwheel delegates Git revisioning to syncwheel revision-provider, it must persist its start receipt, call check on a clean integration checkout, perform the file mutation, then call preflight with exact before/after hashes before finalize. In active-active mode both gates require fresh, published, fully aligned handoff state; offline or stale coordination fails closed before a provider journal is prepared. The provider never publishes the resulting draft.

  • reconcile is read-only by default.
  • sync, publish, reconcile --apply, stack rebuilds, integration rebuilds, branch deletion, and pushes are mutations.
  • channel contract, channel list, channel show, channel diff, channel plan, channel operation list/show, and channel receipt show are read-only. channel operation reconcile is also read-only until --apply appends a receipt. Every channel mutation previews a channelPlan; run it only with the exact --plan-digest ... --apply. A stable optional --operation-id is excluded from the digest and binds started/prepared/receipt evidence.
  • Treat channel publish as an exact-lease operation; a published channel branch is not evidence of an environment deployment.
  • channel create claims only a new, unowned ref. It refuses existing local or remote refs and protected base, integration, stack, target, and coordination branches; v0.33 has no implicit adoption path.
  • After an uncertain local-ref or remote outcome, inspect the operation and run digest-bound channel operation reconcile. Reconciliation only observes and appends a terminal receipt; it never retries the mutation.
  • A channel pins its base as well as its stack revisions. Only channel refresh advances the base pin. Preserve exact depends_on closure/order. A channel-local resolution is bound to the raw pins; composition edits invalidate it and promotion copies it with the source pins. Shared channels refuse draft-stack publication; ephemeral channels may use drafts, and active-active channels must use the coordination remote.
  • Never mutate branches from a dirty checkout.
  • Rebuilds do not create a worktree. Start routine implementation, dependency installation, builds, and tests on integration. Use --replay-mode desk only to resolve a conflict or validate a non-empty materialized stack when integration cannot safely run it; put it under the declared Syncwheel worktree root.
  • A plumbing conflict stops and prints the --replay-mode desk retry command. Take it: stack absorb and stack resolve-integration need a checkout that plumbing never created.
  • For active-active repositories, never bypass publish, stack push, or int push with a raw git push; they provide the required atomic state and exact leases.
  • If publication reports a mergeable race, inspect handoff and use publish --accept-merge only after explicitly accepting the disjoint-stack merge. Do not retry a failed lease silently.
  • Use worktree lock <stack> before retaining a tombstoned worktree for local investigation. gc --apply never deletes remote branches.
  • After rebuilds, diff the result against the expected post-fix state so stale manifest projections do not silently revert work.

Install The Skill

When Agentwheel is available:

agentwheel doctor --adapter codex --local --skill syncwheel --source github:NestDevLab/syncwheel
agentwheel install github:NestDevLab/syncwheel --adapter codex --local --skill syncwheel

Handoff Shape

End with:

  • manifest tracking status
  • worktree cleanliness
  • validation/check results
  • commit/push state for git-tracked repos
  • active-active handoff state, pending merge decision, and cleanup candidates
  • any branch or remote action still needing a human decision

Key References

  • Install handoff: install.md
  • AI agents: docs/ai-agents.md
  • Agent procedure: docs/agent-procedure.md
  • Manifest tracking: docs/manifest-tracking.md
  • Active-active protocol: docs/design/active-active-coordination.md
  • Agentwheel revision provider: docs/revision-provider.md
  • Deployment channels: docs/deployment-channels.md
  • Core procedure: docs/core-procedure.md