agentleFS
RidhuanDEVRidhuanDEV/claude-skills/shadow-git/SKILL.md

shadow-git

Skill1 starsChanged yesterdayMITView on GitHub

Safe Team Git & Worktree Collaboration. Use when syncing team branches, running git merge-tree dry-run conflict checks, managing parallel multi-agent worktrees, integrating independent feature branches, or resolving merge conflicts safely.

  • Reads credentials
  • Installs packages
  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 3 are distinctive, and 15 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 15

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this skill whenever the Monarch asks to manage branches, create/inspect/clean Git worktrees, run parallel agents across isolated …

    line 8
  2. Distinctive:

    Conditional Activation & Read-Only Default: Do not execute Git synchronization or branch mutations automatically merely because a session …

    line 10
  3. Very specific:

    Never assume every project uses Git Flow.

    line 33
  4. Very specific:

    When multiple agents work in parallel (e.g., Tejas/main, Tejas/feature-rag, Tejas/feature-sitaba, Tejas/feature-export):

    line 37
  5. Very specific:

    Create an isolated worktree per agent via worktree-create (automatically blocks if the branch is already checked out elsewhere or if the …

    line 38
  6. Very specific:

    Run check-parallel-scope to detect if two parallel worktrees are modifying the same shared file or violating their allowed path scope.

    line 40
  7. Very specific:

    When pausing an agent's worktree, save state via /handoff (shadow_handoff MCP).

    line 41
  8. Very specific:

    When Branch C (feature-export) is completed while Branch A (feature-rag) and Branch B (feature-sitaba) are still in progress:

    line 44
  9. Very specific:

    Run integrate-feature --branch feature-export --target main (Read-Only Preview) to verify:

    line 45
  10. Very specific:

    Run /shadow-test and /shadow-sec inside Branch C's worktree.

    line 49
  11. Distinctive:

    After Branch C merges into main, bring updated main into unfinished branches A and B:

    line 53
  12. Very specific:

    Default to --strategy merge (git merge --no-ff main) for shared, published, or long-lived branches.

    line 54
  13. Very specific:

    Not checked out in another active worktree (BRANCH_CHECKED_OUT_IN_WORKTREE).

    line 72
  14. Very specific:

    No active agent ownership lock unless --release-agent-lock is confirmed (ACTIVE_AGENT_OWNERSHIP), and zero ongoing MERGE/REBASE/CHERRY_PICK …

    line 73
  15. Distinctive:

    Create an explicit named backup stash (including untracked files) only when authorized:

    line 94
  16. Very specific:

    Verify resolution: git diff --check + run project typecheck, linter, and unit tests (/shadow-test).

    line 108
  17. Very specific:

    Deterministic Post-Merge Reconciliation: After integrating worktrees sequentially into an integration branch, run cross-boundary checks …

    line 124
  18. Very specific:

    Execution Approval Boundary (L0 vs L4): Read-only status/diff/merge-tree diagnostics are L0_READ_ONLY, whereas --approve branch …

    line 125

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Shadow Git v2.0 (/shadow-git) — Branching, Worktree & Parallel Multi-Agent Orchestrator

Use this skill whenever the Monarch asks to manage branches, create/inspect/clean Git worktrees, run parallel agents across isolated features, integrate completed branches independently into main, sync unfinished branches with main, pull safely, or predict/resolve merge conflicts.

  • Conditional Activation & Read-Only Default: Do not execute Git synchronization or branch mutations automatically merely because a session starts. Always run read-only inspection/previews first (health, predict-conflicts, or commands without --approve) and require explicit Monarch authorization before merge, rebase, force-push, branch deletion, or worktree removal.
  • Detailed Architectural Reference: Load references/WORKTREE-AND-PARALLEL-AGENTS.md for the branching strategy matrix, worktree ownership manifest, conflict taxonomy, and recovery playbooks.

1. Natural-Language Intent to Command Routing (scripts/git_orchestrator.py)

Monarch Natural-Language IntentOrchestrator Command (python ".../shadow-git/scripts/git_orchestrator.py" ...)
"Cek strategi branch repo ini"detect-strategy --repo <path>
"Cek semua worktree dan branch aktif" / "Health report"health --repo <path> --stale-days 14
"Buat worktree baru untuk fitur RAG"worktree-create --repo <path> --branch feature-rag --path ../feature-rag --base main --agent Agent-RAG --task TASK-01 --allowed-paths rag/
"Kerjakan fitur A dan B secara paralel"worktree-create for each branch + check-parallel-scope --repo <path> --base main
"Prediksi conflict sebelum merge"predict-conflicts --repo <path> --source <feature-branch> --target main
"Branch C sudah selesai, cek apakah aman merge ke main"integrate-feature --repo <path> --branch <branch-C> --target main (add --approve only after Monarch confirmation)
"Sync branch A dan B dengan main terbaru"sync-from-main --repo <path> --branch <branch-A> --main main --strategy merge (add --approve to execute)
"Bersihkan worktree yang sudah selesai"safe-cleanup --repo <path> --branch <branch-C> --target main --release-agent-lock (add --approve to execute)

2. Core Workflows (FR-01 .. FR-08)

A. Branching Strategy Detection (FR-01)

Never assume every project uses Git Flow. Run detect-strategy first to identify:

  • Trunk-Based (main only), Short-Lived Feature Branches (GitHub Flow), Long-Lived Feature/Research Branches, Release/Hotfix Branches, or Git Flow (main + develop).

B. Git Worktree Lifecycle & Parallel Multi-Agent Isolation (FR-02, FR-03)

When multiple agents work in parallel (e.g., Tejas/main, Tejas/feature-rag, Tejas/feature-sitaba, Tejas/feature-export):

  1. Create an isolated worktree per agent via worktree-create (automatically blocks if the branch is already checked out elsewhere or if the target directory is non-empty).
  2. Each worktree registers an ownership & scope manifest (.git/shadow-worktrees/agents_registry.json) with agent_id, task_id, allowed_paths, and depends_on_branches.
  3. Run check-parallel-scope to detect if two parallel worktrees are modifying the same shared file or violating their allowed path scope.
  4. When pausing an agent's worktree, save state via /handoff (shadow_handoff MCP).

C. Independent Feature Integration (FR-04)

When Branch C (feature-export) is completed while Branch A (feature-rag) and Branch B (feature-sitaba) are still in progress:

  1. Run integrate-feature --branch feature-export --target main (Read-Only Preview) to verify:
    • Worktrees are clean (0 uncommitted/untracked files).
    • Required depends_on_branches are already merged.
    • Zero Git conflicts (git merge-tree --write-tree) and semantic risks are listed.
  2. Run /shadow-test and /shadow-sec inside Branch C's worktree.
  3. Upon explicit Monarch approval, execute integrate-feature --branch feature-export --target main --approve (or open a PR per repository policy without bypassing protected branch rules).

D. Forward Integration / Sync From Main (FR-05)

After Branch C merges into main, bring updated main into unfinished branches A and B:

  1. Default to --strategy merge (git merge --no-ff main) for shared, published, or long-lived branches.
  2. Shared-Branch Rebase Guard: sync-from-main automatically blocks --strategy rebase if the branch tracks a remote upstream or is marked shared (SHARED_BRANCH_REBASE_BLOCKED). Never force-push without explicit approval and risk disclosure.
  3. Predicts conflicts and blocks if the target worktree has uncommitted/untracked changes (DIRTY_WORKTREE_PROTECTED).

E. Enhanced Conflict Prediction: Git Conflicts vs Semantic Risks (FR-06)

predict-conflicts distinguishes:

  • Hard Git Conflicts: Content conflicts, rename/delete conflicts, file mode changes, and divergent histories.
  • Semantic Integration Risks (flagged even when Git merge is clean):
    • PARALLEL_SCHEMA_MIGRATIONS: Both branches added DB migration files (/shadow-data).
    • API_CONTRACT_MODIFICATION: Changes to openapi.yaml, routes, controllers, .proto, .graphql (/shadow-api).
    • SHARED_CONFIGURATION_CHANGE: Edits to .env*, package.json, tsconfig.json, docker-compose.yml.
    • LOCKFILE_DIVERGENCE: Concurrent lockfile updates.

F. 6-Point Safe Cleanup Gate (FR-08)

safe-cleanup refuses to remove a worktree or delete a branch unless all 6 checks pass:

  1. Zero staged or unstaged changes (UNCOMMITTED_CHANGES).
  2. Zero untracked files (UNTRACKED_FILES_PRESENT).
  3. Zero unmerged commits relative to target branch (UNMERGED_COMMITS).
  4. Not checked out in another active worktree (BRANCH_CHECKED_OUT_IN_WORKTREE).
  5. No active agent ownership lock unless --release-agent-lock is confirmed (ACTIVE_AGENT_OWNERSHIP), and zero ongoing MERGE/REBASE/CHERRY_PICK operations.
  6. Explicit --approve flag provided after Monarch confirmation.

3. Preserved v1.0 Team Branch Sync & Conflict Resolution Protocol

Phase 1: Safe Pre-Pull Reconnaissance (Zero Working-Tree Mutation)

git status -sb
git branch -vv
git fetch --all --prune
git log HEAD..origin/<target-branch> --oneline --stat
git merge-tree --write-tree HEAD origin/<target-branch>

Phase 2: Safe Pull Execution Protocol

  • Clean working tree & 0 conflicts:
    • 0 ahead commits: git pull --ff-only origin <target-branch>
    • Diverged (>0 ahead, 0 conflicts): git pull --no-rebase origin <target-branch>
  • Uncommitted local changes exist:
    • Create an explicit named backup stash (including untracked files) only when authorized:
      git stash push -u -m "shadow-pre-pull-backup-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
    • Pull safely, then restore with git stash pop (never run implicit stash drop).

Phase 3: Intelligent Collaborative Conflict Resolution

  1. List conflicted files: git diff --name-only --diff-filter=U
  2. Inspect both sides' commit intent:
    • git log -p -n 3 HEAD -- <file>
    • git log -p -n 3 origin/<target-branch> -- <file>
  3. Never Blindly Apply --ours or --theirs on Source Code:
    • Combine both contracts cleanly (0 any, 0 as Type casting, zero dead code).
    • Regenerate lockfiles via the package manager (npm install --package-lock-only) after merging manifests.
  4. Verify resolution: git diff --check + run project typecheck, linter, and unit tests (/shadow-test).

4. Ecosystem Integration Boundaries (FR-09)

  • /shadow-monarch: Enforces approval gates, strict typing during conflict resolution, and read-only default behavior.
  • /shadow-plan: Maps TASK-* IDs and depends_on_branches to isolated worktrees.
  • /shadow-test: Runs module & integration regression tests inside each worktree before integrate-feature and after sync-from-main.
  • /shadow-sec: Runs secret scanning and ASVS access-control checks before merging into main.
  • /shadow-release: Verifies release tags, migration backward compatibility, and rollback SHAs after main integration.
  • /handoff: Persists worktree path, branch name, and active task state across AI agent sessions (shadow_handoff MCP).

5. Parallel Worktree Path-Ownership & Reconciliation Protocol

  • Explicit Path-Ownership Invariant: Before spawning parallel worktrees or swarm workers, partition modified file paths so each worktree owns a disjoint set of directories/files. Shared contracts (openapi.yaml, schema.prisma, package.json, shared types/router indexes) MUST NOT be edited concurrently by multiple feature branches; assign shared contracts to a serialized coordinator gate or prerequisite base branch first.
  • Deterministic Post-Merge Reconciliation: After integrating worktrees sequentially into an integration branch, run cross-boundary checks (typecheck, openapi validation, integration tests, and /shadow-quality drift checks) on the combined tree before cleanup. Conflict resolution MUST merge both worktrees' semantic invariants rather than taking --ours/--theirs blindly.
  • Execution Approval Boundary (L0 vs L4): Read-only status/diff/merge-tree diagnostics are L0_READ_ONLY, whereas --approve branch integration, rebase, force cleanup, or git push are L4: HIGH_IMPACT requiring explicit Monarch authorization (shadow-monarch/scripts/execution_approval_gate.py).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.