Weaver

Use raw git only for supporting inspection, such as checking branch names, showing logs, or verifying repository state around a Weaver command.

Preferred Workflows

Inspect or declare a stack

• Use weaver stack <branch> --on <parent> to declare dependencies.
• Use weaver unstack <branch> to remove a declaration.
• Use weaver deps [branch] to inspect chains or the full tree.
• Use weaver status when stack-parent health labels matter. This view is local-only and compares each branch to its declared parent or base, not to its Git upstream.
• Use weaver status --upstream when the user wants upstream drift instead. This mode fetches remote refs and compares each tracked branch to its configured upstream without fast-forwarding local branches.
• Use weaver doctor when the user wants a read-only diagnostic pass.

Rebase a stack

• Use weaver update ... when the user wants to fetch remotes and fast-forward local branches to their upstream refs before any stack rebase.
• Use weaver update --integration <name> when the branch set should follow a saved shared integration strategy.
• Start with weaver status if the user wants to understand risk first.
• Use weaver sync [branch] for the actual ordered rebase.
• Use weaver sync [branch] --merge when the stack branches already have open PRs or reviewed history that should not be rewritten; this preserves history, fast-forwards when possible, and otherwise creates the normal merge commit.
• If a rebase pauses on conflicts, use weaver continue after resolution or weaver abort to restore the original branch.

Compose branches

• Prefer weaver compose ... --dry-run when the user wants preview or safety first.
• Use one selection mode only: explicit branches, --group, --integration, or --all.
• Compose is ephemeral by default and should restore the original branch after completion.
• If the user wants a reproducible shared integration recipe, save it first with weaver integration save <name> --base <branch> <branch...>.
• Use weaver integration doctor <name> when the user wants to know whether a saved integration is coherent before composing it.
• Use weaver compose --integration <name> ... when the base and branch set should come from the saved strategy instead of being repeated manually.
• Use weaver compose ... --skip <branch> when one branch should be left out temporarily for manual follow-up.
• If the user did not provide --skip, expect weaver compose to prompt for skip or abort when a branch conflicts.
• Treat repeated compose conflicts as a common workflow, not an exceptional one: if one branch keeps failing or is already known to be the noisy outlier, skip it outright or accept the skip prompt, let the compose finish, and then merge that branch manually onto the integration branch produced by --create or --update.
• When using this pattern, prefer naming the skipped branch explicitly in the command if you already know it is the problem branch. That keeps the compose reproducible and avoids re-running the same failing merge.
• If one branch is far more divergent than the rest and keeps breaking a large compose, prefer removing it from the compose or saved integration, repairing it first, and then merging it manually onto the branch created or updated by Weaver before adding it back.
• If the user needs a fresh integration branch created from the composed result, use weaver compose ... --base <branch> --create <integration-branch>.
• If the user needs an existing integration branch rebuilt from a clean base, use weaver compose ... --base <branch> --update <integration-branch>.
• Weaver tracks branches targeted by both --create and --update, so use weaver integration branch list to inspect them and weaver integration branch delete <name> to clean them up later.
• weaver integration branch list distinguishes: composed branches included during compose, branches merged later after being skipped, and skipped branches still pending manual follow-up.

Manage integration strategies

• Use weaver integration save <name> --base <branch> <branch...> to create or update a reusable integration strategy.
• Use weaver integration show <name> or weaver integration list to inspect saved strategies.
• Use weaver integration doctor <name> when the strategy may have foreign ancestry, drift, or suspicious merge history.
• Use weaver integration export <name> --json to share one strategy directly.
• Use weaver integration import <file> to restore one shared strategy in another clone.

Handoff state

• Use weaver export to serialize dependencies, groups, saved integrations, and tracked integration branches.
• Use weaver import <file> to restore them in another clone.

Guardrails

• Do not mix weaver stack operations with hand-edited .git/weaver/* files unless the user explicitly asks for manual repair.
• Do not force-push as part of a Weaver workflow unless the user explicitly requests it.
• If the user asks what Weaver will do without wanting changes yet, prefer read-only commands or --dry-run.
• If --integration is selected, do not also invent a manual branch list or --group selection in the same command.
• When a compose fails repeatedly because one branch is badly out of shape, do not keep retrying the full stack blindly; default to skipping that branch, finishing the compose, and merging it manually onto the branch produced by --create or --update afterward. Only fall back to removing it from the compose or integration entirely when the branch is so unstable that even skip-and-manual-merge is not a good short-term workflow.
• If a command fails because the repo lacks Weaver metadata, initialize with weaver init only when that matches the user’s intent.

Reference

Read references/commands.md when you need exact command syntax or example invocations.