Plan a new objective end-to-end in this repo's docs/mbo Management-By-Objective system — turn a GitHub issue or a gss draft-PR worktree into consistent design/spec/plan artifacts and track it in docs/mbo/index.md. Use this whenever the user wants to START planning or designing a new feature, skill, CLI, or service: "plan this issue", "let's design X", "spec this out", "write a plan for #N", "start an MBO / a design doc", or when they're working in a gss draft PR and want to scope the work — even if they don't say "mbo". Routes the task to the right skill workflow (skill-creator, brainstorming→writing-plans, the go/web teams) per docs/mbo/AGENTS.md. Also anchors the objective to a GitHub design issue + a gss draft PR, and — when the plan is ready and it's time to BUILD — asks whether to "break out the work / parallelize / divide it across the teams": a dependency graph of leaf tasks, each a gss feature worker with its own worktree, draft PR, and linked GitHub sub-issue, fanned out via a Workflow, blocking task

2026-07-0743

remote-claude-session

sfc-gh-eraigosa/dotfiles

Start, restart, or attach to a persistent Claude --remote-control session on any remote SSH host inside a specified git repository. Use this skill whenever the user asks to "start a remote Claude session", "spin up Claude on [host]", "set up remote control on [host]", "launch Claude remotely in [repo]", "start an AI session on [machine]", "restart the remote Claude session", or any variation of establishing or checking a remote Claude Code instance. Also triggers when the user asks to check whether a remote session is running or to get the attach command for an existing one.

2026-07-0743

sync-skills

sfc-gh-eraigosa/dotfiles

Synchronize AI agent skills and build binaries from the dotfiles repository.

2026-07-0743

team

sfc-gh-eraigosa/dotfiles

Route a task to the right AI team + member (two-level team→member selection)

2026-07-0743

gsl-status

sfc-gh-eraigosa/dotfiles

Query and configure the gsl (Go Status Line) that renders a powerline-style status bar in Claude Code and Antigravity CLI.

2026-07-0743

name	git-safe-sync
description	A reliable skill for synchronizing and pushing changes to any Git repository with built-in safety backups and dirty-repo scanning.

Git Safe Sync (gss) Skill

This skill provides a structured and safe workflow for managing Git repositories using the 'gss' tool.

Capabilities

Slash Command: Use /gss for a quick status summary and help overview.
Introspect Changes: Run 'gss status' to see what files are changed in a repo.
Scan for Changes: Run 'gss scan [dir]' to find all repositories with uncommitted changes.
Reliable Push: Run 'gss push' to backup, sync, and push changes safely.
Create PR: Run 'gss pr' to create a feature branch and pull request.
Repository Summaries: Generate categorized markdown tables of up to 50 open PRs and Issues, including latest changes and associated issue numbers.

The Workflow

1. Identify & Introspect (Research Phase)

If a sync is implied or requested, first use 'gss status' and 'git diff' to understand what would be pushed.
Summarize the changes clearly for the user.

2. Mandatory Confirmation (Decision Phase)

NEVER execute git add, git commit, gss push, gss pr, or git push autonomously.
Turn Break Mandate: You MUST NOT chain git add, git commit, or gss push in the same conversational turn as code modifications. After making code changes, you MUST provide a summary and end your response. Explicitly asking the user for confirmation must be the primary focus of the following turn.
Autonomous-Mode Exception: This mandatory confirmation rule OVERRIDES any autonomous-mode / minimal-interruption instructions (e.g. "YOLO mode"). You MUST ask for permission even if the user has requested minimal interruption.
You MUST explicitly ask the user — using whatever confirmation mechanism your assistant provides (a direct question, an interactive prompt, or your host's user-confirmation tool) — to request permission to proceed, even if the user asks you to "sync", "add", or "commit" changes. A request to "sync" means start the workflow, not skip the confirmation.
Present the user with clear options:
- Commit & Push: (Add -> Commit -> Backup -> Sync -> Push)
- Commit Only: (Add -> Commit)
- Create PR: (Add -> Commit -> Feature Branch -> Push -> GH PR)
- Cancel: Do nothing.
PR Hygiene — the description and labels must always match the PR's full current scope: A PR's description and labels are part of its state, not a one-time creation step. Keep them accurate for everything the PR now contains, every time you change what's on it:
On create (gss pr): gss pr does not infer a body or labels — pass them explicitly via gss pr --title "<subject>" --body "<markdown body>" and use gh pr edit --add-label "<labels>" immediately after.
On every later push to a branch that already has an open PR (gss push, or a re-run gss pr): gss push only updates the branch. After such a push you MUST refresh the description and labels to cover the newly added commits, via gh pr edit <number> --title "<subject>" --body "<body>" --add-label "<labels>". Never push scope-changing commits to a PR and leave its description or labels behind.
Label Selection: Use standard prefixes (feat, fix, docs, ci, test, style, refactor, chore) and area-specific labels (e.g., gsl, wispr, remote-claude). If a PR addresses an issue, ensure it carries the same categorization labels as the issue.
The body should always include — What (summary of functional changes), Why (rationale), Impact (effect on system/UX), Testing (how verified). NEVER use generic or empty descriptions.
Note: gss pr has no --draft flag — classic PRs are created ready-for-review. (Draft PRs exist only in the gss feature stacked-worker workflow, whose PR bodies and labels are owned by gss feature checkpoint — do not hand-edit those with gh pr edit.)

3. Execution (Action Phase)

ONLY proceed if the user explicitly selected a confirmation option in the previous turn.
Handshake Generation: Before calling gss push, you MUST generate an approval token — as two separate commands. The safety_guard.sh hook intentionally blocks chaining the token generation and the push in one command, so the user sees an explicit approve→publish gate.
- Step 1 (one command): mkdir -p ~/.config/gss && git rev-parse HEAD > ~/.config/gss/approval.token
- Step 2 (a separate command): gss push
This consumes the token and satisfies the binary's technical safeguard.
First push of a brand-new branch (no double prompt): gss push detects a branch with no origin/<branch> counterpart and creates it with --set-upstream instead of failing on the rebase step — it prints New branch — … --set-upstream. So the single token → gss push recipe works for a new branch too; issue it ONCE. Do not expect (or work around) the old sync: rebase ... couldn't find remote ref <branch> failure, which used to burn the token and force a second confirmation prompt. Fallback for an OLD binary that still errors that way: run one plain git push -u origin HEAD (a plain push is not token-gated), then create the PR — do not regenerate the token and retry gss push.
Auto-Recovery: If gss push fails with a "missing or unreadable approval token" error (exit 22), it means you skipped the user confirmation turn. You MUST immediately stop and explicitly ask the user for permission before retrying.
Refresh the PR description (mandatory after pushing to an existing PR): If the push added commits to a branch that already has an open PR (rather than creating a new one), the PR body is now stale — gss push never updates it. Immediately reconcile it with gh pr edit <number> --title "<subject>" --body "<body>" so the description covers the PR's new full scope (re-derive What/Why/Impact/Testing from all commits now on the branch, e.g. git log <base>..HEAD). This is part of the push, not an optional follow-up. (Skip only for gss feature worktrees — gss feature checkpoint owns those bodies.)

4. Summarize & Link (Verification Phase)

After execution, summarize the result using the output from 'gss push'.
Detailed Summary: If fewer than 10 files were changed, provide the list of files and their +/- line counts.
Compact Summary: If 10 or more files were changed, provide the high-level stats (e.g., "15 files changed").
Provide the GitHub Comparison Link or the Pull Request URL.
Description sync check: If the push targeted an existing PR, confirm you refreshed its description (Execution phase) so it matches every commit now on the PR. A push that left the description stale is an incomplete sync — go back and run gh pr edit.
Browser Verification: Ask the user whether to open the GitHub Comparison/PR link (from the push/pr output) in their browser for final verification. To open it, run the repo's open-url <link> helper (opt/scripts/misc/open-url), which picks the right opener per platform — open on macOS, wslview/explorer.exe under WSL, xdg-open on Linux. It exits non-zero and prints the link when no opener exists (e.g. a headless SSH session); in that case just leave the link visible rather than retrying.

5. Repository Summaries (PRs & Issues)

When asked to summarize open PRs or issues, always fetch detailed data up to a limit of 50 items (e.g., gh pr list --state open --limit 50 --json number,title,author,labels,state,updatedAt,body and similarly for gh issue list).
Present the results in categorized markdown tables, grouped by focus area or topic (e.g., "Infrastructure", "UI Improvements").
Include columns for PR/Issue Number, Title, Status, and a brief Summary of what the item addresses.
For PRs, explicitly extract and include associated issue numbers and highlight any latest changes or recent commits based on the retrieved data.
Label Markers: Include visible markers for labels (e.g., [feat], [fix]) in the Title or Status columns to help categorize items within the summary. If labels are missing but the intent is clear (e.g., "Fixes X"), suggest the appropriate label to the user.

Guidelines

No Assumptions: Even if a sync seems obvious, you must ask for permission first.
Always Backup: Trust 'gss push' because it creates a safety branch before rebasing.
Provide Links: Never hide the GitHub/PR links; they are the user's primary way to verify the result.
Handle Conflicts: If a rebase conflict occurs, inform the user and show the output.

Two operating modes

gss auto-detects its mode by whether the current directory is a registered feature worker worktree (design.md → "Command surface"):

Classic (regular checkout): gss push / pr / sync / status / scan — the workflow above. Refused inside a worker worktree (ErrWrongMode); --force-autonomous does not bypass that.
Feature / worker (stacked PRs): the gss feature … subtree, for developing several dependent branches in parallel isolated worktrees.

Feature worker workflow (stacked PRs)

Use this when work splits into multiple dependent branches (a "stack") or when running parallel AI/automation workers on one feature. Authoritative reference: design.md → Command surface and Stacked PRs — this section summarises, the design governs.

Mental model

A feature groups one or more workers. Each worker is its own git worktree on its own branch feature/<feature>/<user>/<purpose>[-<suffix>], recorded in registry.json.
Workers form a stack: each worker's base_branch points at its parent's branch (or the default branch at the bottom). Review and merge bottom-up.
When a parent merges, gss re-targets its children onto the parent's former base and — for a linear, never-restacked stack — auto-promotes the next draft to ready.

Typical lifecycle

gss feature start <name> [--base main] [--description "…"] — create the feature.
gss feature worker add --feature <name> --purpose <p> --description "…" — add a worker worktree; cd into the printed path to work in it.
Inside the worktree: gss feature checkpoint — rebase on base, push, and create/update the draft PR (refreshing the stack section across the feature). Hooks may call gss feature checkpoint --auto --worker <ref>.
gss feature list --tree to see the stack; gss feature conflicts to see files touched by more than one worker.
When a worker is approved: gss feature pr --ready (promote the draft — token-gated, see below).
After a PR merges on the main repo: gss feature merged <ref> re-targets children and auto-promotes the next where eligible.
gss feature done [<ref>] [--force] — tear down a finished worker (and the feature if it empties and FEATURE.md is unedited).
gss feature audit [--repair] — reconcile the registry against observed reality; run it first on a fresh machine (observable state wins).

The approval token also gates the publish-class feature verbs

The mandatory-confirmation + two-call token recipe above ALSO applies to gss feature pr --ready, gss feature merged, and gss feature restack (they mutate remote state). Generate the token as a SEPARATE call immediately before the command, then run it; safety_guard.sh enforces this and refuses classic --force-autonomous inside a worker worktree.

Description hygiene

Give every feature and worker a short, specific --description; it seeds FEATURE.md / WORKER.md and the PR body (NFC-normalised; control chars and injection markers stripped).
WORKER.md placement (issue #132): WORKER.md is seeded outside the worker's git worktree, at <worktrees-root>/<owner>/<repo>/<feature>/<user>/.gss-meta/<leaf>/WORKER.md, so it never appears in the consumer repo's git status and cannot be accidentally committed. There is no manual cleanup step — gss feature done removes the worker's .gss-meta/<leaf>/ automatically. (An older gss may have left a root-level WORKER.md inside the worktree; the next checkpoint --auto relocates it to the meta path.)
FEATURE.md cleanup: FEATURE.md is transient feature-level scaffolding; gss feature done removes it when the feature empties and it carries no human edits (an edited FEATURE.md is retained with a notice). No manual step needed.
spawned_by (engine/session/pane) is informational only — never the basis for a trust or control decision (design.md resolution #8).

Restack & conflicts → reach for the git-machete skill

gss feature restack <worker> --onto <branch> re-targets a worker's branch and permanently excludes it from auto-promote (increments restack_count). Use sparingly.
When gss feature conflicts reports overlap, or a checkpoint/rebase/restack aborts on a conflict, drive the git-machete companion skill (src/git-machete/skill/SKILL.md) for the local multi-branch restack, then re-run the matching gss feature command so gss reconciles PRs + registry. gss stays the single writer for PRs and the registry.

Help

Slash Command: Type /gss at any time to see the status of the current repository and a quick usage guide.
Status Inquiry: If the user asks "Which of my projects need a push?", use 'gss scan ~/git'.
Feature help: gss feature --help lists every verb; gss feature <verb> --help shows its flags.