Skill: workspace-isolation Skill

required_canon_version: >=3.0.0

Skill: workspace-isolation

Version: 1.0.0

Status: Active

Purpose

Enforces disciplined git workflow for agents to prevent commit bloat and ensure human approval before permanent repository changes.

Trigger

This skill applies to ALL agent sessions that involve repository modifications. Agents MUST follow these rules whenever performing git operations.

CRITICAL: Human Review Gate

The user MUST review and approve ALL work BEFORE any commit or merge.

Agents do NOT decide when work is ready. The human does. Present your work, then STOP and WAIT.

Git Workflow Rules

Phase 1: Work Completion (NO GIT OPERATIONS)

Complete ALL work first - Do not commit anything until the entire task is finished
Stage changes for review - Use git add to stage, but DO NOT commit
STOP AND PRESENT WORK - Show the user:
- Full git diff --staged output
- Summary of what was changed and why
- Proposed commit message
WAIT for explicit approval - Do NOT proceed until user says "commit" or equivalent
- "Looks good" is NOT approval to commit
- "Yes" to a question about the code is NOT approval to commit
- Only explicit commit approval (e.g., "commit it", "yes commit", "go ahead and commit") authorizes the commit

Phase 2: Single Commit (AFTER APPROVAL, BEFORE MERGE)

One commit only - After explicit approval, create exactly ONE commit with all changes
Descriptive message - Use a clear, comprehensive commit message covering all changes
No intermediate commits - Never create multiple commits for incremental work
STOP AGAIN - After committing, STOP and ask about merge. Do NOT auto-merge.

Phase 3: Merge (SEPARATE APPROVAL REQUIRED)

CRITICAL: NEVER use git merge or git merge --no-ff. Always use selective file checkout.

STOP AND ASK - Present merge plan to user
Request explicit merge approval - "Ready to merge to [branch]?" then WAIT

Selective file merge ONLY - Merge ONLY files you created or modified:

# Switch to target branch (e.g., main)
git checkout main

# Cherry-pick ONLY your changed files from feature branch
git checkout feature-branch -- file1.py file2.py file3.md

# Commit the changes
git commit -m "feat: descriptive message"

NEVER merge the entire branch - Do NOT use:
- ❌ git merge feature-branch
- ❌ git merge --no-ff feature-branch
- ❌ Any command that merges all commits/files from the branch
Delete feature branch after merge - Clean up merged branches:
```
# From main repo root (not worktree)
python CAPABILITY/SKILLS/agents/workspace-isolation/run.py cleanup <task_id>
```
- Or manually: git worktree remove <path> && git branch -D feature-branch

Phase 4: Post-Merge Cleanup (CONDITIONAL)

Amend is SAFE only when:
- The commit has NOT been pushed to remote
- OR the branch is a personal feature branch with no collaborators
- AND the user explicitly approves the amend
Amend is UNSAFE when:
- Commit has been pushed to shared remote
- Others may have pulled the branch
- Working on main/master/develop branches
For post-merge cleanup (changelog updates, version bumps):
- If amend is safe: git commit --amend to add to previous commit
- If amend is unsafe: Create a new "chore:" commit

Prohibited Actions

Agents MUST NOT:

git commit before all work is complete
git commit without user approval
git merge or git merge --no-ff (use selective file checkout instead)
git push without user approval
git commit --amend on pushed commits without explicit user consent
Create multiple commits for a single logical change
Commit, merge, then commit again (the Gemini anti-pattern)
Merge entire branches (always cherry-pick only files you changed)

Approval Checkpoints

| Action | Requires Approval | |--------|-------------------| | git add | No | | git commit | YES | | git merge | YES | | git push | YES | | git commit --amend | YES (with safety check) | | git rebase | YES | | git branch -d | No (auto after merge) |

Example Workflow

1. Agent receives task: "Add feature X and update changelog"
2. Agent implements feature X (no commits)
3. Agent updates changelog (no commits)
4. Agent stages all changes: git add -A
5. Agent: "All work complete. Here's what I've done:

   [git diff --staged output]

   Summary:
   - Added feature X in src/feature.ts (new endpoint for user preferences)
   - Updated CHANGELOG.md (added entry for v1.2.0)

   Proposed commit message: 'feat: add user preferences endpoint'

   Please review the changes above. Let me know when you'd like me to commit."

   >>> AGENT STOPS HERE AND WAITS <<<

6. User reviews the diff, maybe asks questions, requests changes
7. Agent makes any requested changes, re-stages, presents again
8. User: "Commit it" (explicit approval)
9. Agent: git commit -m "feat: add user preferences endpoint"
10. Agent: "Committed. Ready to merge to main?"

    >>> AGENT STOPS HERE AND WAITS <<<

11. User: "Yes, merge"
12. Agent:
    ```bash
    git checkout main
    git checkout feature-branch -- src/feature.ts CHANGELOG.md
    git commit -m "feat: add user preferences endpoint"
    python CAPABILITY/SKILLS/agents/workspace-isolation/run.py cleanup feature-branch
    ```
13. Agent: "Merged only changed files and cleaned up feature-branch."
14. If post-merge cleanup needed:
    Agent: "Need to update version number. Safe to amend? (not pushed yet)"

    >>> AGENT STOPS HERE AND WAITS <<<

Constraints

Must present git diff --staged or git status before requesting commit approval
Must verify push status before offering amend option
Must track approval state throughout session
Must escalate to user on any git operation uncertainty

Outputs

Agent should output at each checkpoint:

Summary of staged changes
Proposed commit message
Safety status for amend operations
Clear approval request

required_canon_version: >=3.0.0

Agent Skills: Skill: workspace-isolation

Install this agent skill to your local

Skill Files