tgrnd · tg-agent · Apr 1, 2026 · Apr 1, 2026
diff --git a/docs/plans/2026-04-01-igit-refocus-design.md b/docs/plans/2026-04-01-igit-refocus-design.md
@@ -0,0 +1,249 @@
+---
+created: 2026-04-01
+status: approved
+type: design
+---
+
+# igit Refocus Design
+
+Refocuses the igit plugin around two primary use cases and a third emerging one:
+
+1. **Git skills** — action skills (user-invoked interactive workflows) and process skills
+   (model-read convention guidance)
+2. **Policy hooks** — PreToolUse enforcement for git and gh CLI with in-depth defense
+   against accidental data loss, infiltration, and exfiltration attacks
+3. **Sandbox guidance** — documentation, interactive setup, and passive config detection
+
+## Motivation
+
+The plugin has grown organically. Skills and hooks live in flat directories with no
+structural signal about their purpose. Convention gaps exist in the process skills
+(uv, branch naming, worktree ownership). Security gaps are documented in `docs/sec/`
+but unimplemented. User-facing documentation does not exist.
+
+This design gives the plugin a clear four-quadrant structure and a roadmap to fill
+the gaps in priority order.
+
+---
+
+## Directory Structure
+
+```
+skills/
+  process/                # model-read workflow guidance
+    git-workflow/
+    file-lineage/
+  actions/                # user-invoked workflow actions
+    commit/
+    merge/
+    branch/               ← new
+    pr/                   ← new
+    review/               ← new
+    secure/               ← new
+
+hooks/
+  hooks.json              # registration (root)
+  hook_logger.py          # shared utility (root)
+  shell_operators.py      # shared utility (root)
+  policies/               # PreToolUse: deny/ask/allow enforcement
+    git_policy_hook.py
+    gh_policy_hook.py
+  checks/                 # SessionStart/UserPromptSubmit: warn or block on bad config
+    sandbox_check.py      ← new
+    review_context.py     ← new
+
+docs/
+  user/                   # user-facing setup and reference
+    sandbox.md            ← new
+    policies.md           ← new
+    actions.md            ← new
+    workflow.md           ← new
+  research/               # investigation reports
+  sec/                    # internal threat models (source material)
+  work/ plans/ ops/       # unchanged
+```
+
+---
+
+## Skill Inventory
+
+### `skills/process/` — Convention Skills (move only)
+
+Model-read skills that assert workflow conventions. No user-invocable UI.
+
+| Skill | Status | Changes |
+|---|---|---|
+| `git-workflow` | move | Add convention assertions (see below) |
+| `file-lineage` | move | None |
+
+**Convention assertions to add to `git-workflow`:**
+
+- Branch naming prefixes: `feature/`, `fix/`, `refactor/`, `docs/`
+- All changes reach main through PRs — no direct commits or merges to main,
+  regardless of what other skills (e.g. `superpowers:requesting-code-review`) suggest
+- Worktree cleanup is owned by `igit:merge` Stage 3, not `finishing-a-development-branch`
+- Python worktree setup uses `uv sync`, not `pip install` or `poetry install`
+- Project-local worktrees live in `.worktrees/` (declared in CLAUDE.md so
+  `superpowers:using-git-worktrees` picks it up without asking)
+
+### `skills/actions/` — Action Skills
+
+User-invoked skills with interactive UI.
+
+| Skill | Status | Scope |
+|---|---|---|
+| `commit` | move | Unchanged |
+| `merge` | move | Unchanged |
+| `branch` | new | Create (with prefix guidance), switch, delete |
+| `pr` | new | Create, view/edit, request review — model-generated PRs |
+| `review` | new | Fetch PR comments, triage, respond inline |
+| `secure` | new | Guide user through securing their environment |
+
+#### `igit:branch`
+
+Create branch (prefix-guided), switch branch, delete branch. Safe `--delete` only —
+explains that force-delete goes through `igit:merge`. Worktree creation deferred to
+`superpowers:using-git-worktrees`.
+
+#### `igit:pr`
+
+Focused on model-generated PRs. Create PR with title/body/reviewers, view PR status,
+edit PR metadata. References `igit:git-workflow` for conventions.
+
+#### `igit:review`
+
+Execution layer for responding to GitHub PR reviews. Builds on
+`superpowers:receiving-code-review` (which covers the intellectual process). Covers:
+
+- Fetch inline comments: `gh api repos/{owner}/{repo}/pulls/{pr}/comments`
+- Fetch review bodies: `gh api repos/{owner}/{repo}/pulls/{pr}/reviews`
+- Triage: group by file, identify actionable vs informational comments
+- Respond inline via thread replies:
+  `gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`
+
+Paired with `hooks/checks/review_context.py` — a `UserPromptSubmit` hook that fires
+when either `/igit:review` or `/superpowers:receiving-code-review` is invoked, fetches
+PR comments into context, and reminds about the companion skill.
+
+#### `igit:secure`
+
+Interactive skill that guides the user through securing their Claude Code environment
+for git/gh operations:
+
+1. Read current `settings.json` sandbox config
+2. Identify missing `excludedCommands` for git and gh
+3. Identify policy hook gaps (comparing installed version against known rule set)
+4. Present diff of recommended changes with rationale
+5. Offer to apply changes or output for manual review
+
+Complements the passive `hooks/checks/sandbox_check.py` which warns on SessionStart.
+
+---
+
+## Hook Inventory
+
+### `hooks/policies/` — Policy Hooks
+
+#### `git_policy_hook.py` — gaps to close
+
+| Command pattern | Current | Target | Threat |
+|---|---|---|---|
+| `git remote add *` | allow | ask | Attacker adds remote, then pushes |
+| `git push https://*` | allow | deny | Direct URL push bypasses remote name checks |
+| `git push git@*` | allow | deny | Direct URL push bypasses remote name checks |
+| `git push <non-origin> *` | allow | ask | Push to unexpected remote |
+| `git branch -D *` | allow | ask | Force-delete unverified branch |
+| `git branch --delete --force *` | allow | ask | Force-delete unverified branch |
+
+#### `gh_policy_hook.py` — gaps to close
+
+| Command pattern | Current | Target | Threat |
+|---|---|---|---|
+| `gh repo create *` | ask (fallthrough) | deny | Exfiltration: create public repo + push |
+| `gh repo delete *` | ask (fallthrough) | deny | Destructive |
+| `gh gist create *--public*` | ask (fallthrough) | deny | Exfiltration: upload code snippets |
+| `gh api */repos -X POST*` | ask | deny | Exfiltration: create repo via API |
+| `gh api */contents/* -X PUT*` | ask | deny | Exfiltration: upload file via API |
+| `gh pr create *--repo *` | allow | ask | Exfiltration: PR to foreign repo |
+| `gh gist create *` | ask (fallthrough) | ask (explicit) | Confirm private gist intent |
+| `gh release *` | ask (fallthrough) | ask (explicit) | Confirm release intent |
+
+Rule ordering: new deny/ask rules must appear before existing catch-all rules.
+
+See `docs/sec/gh-exfiltration-defense.md` for full threat model and rationale.
+
+### `hooks/checks/` — New Hooks
+
+#### `sandbox_check.py` (SessionStart)
+
+Detects missing `excludedCommands` entries for git and gh. Warns the user with a
+summary of what will fail and suggests running `/igit:secure`.
+
+#### `review_context.py` (UserPromptSubmit)
+
+- Fires when prompt matches `/igit:review` or `/receiving-code-review` (any namespace)
+- Resolves current branch → open PR via `gh pr view --json number`
+- Fetches inline comments and review bodies
+- Outputs formatted context (file, line, author, body — not raw JSON)
+- Reminds model about the companion skill
+- No-op when no open PR found or prompt does not match
+
+Absorbs and extends backlog item `2026-03-29-improve-code-review-story.md`.
+
+---
+
+## User Documentation (`docs/user/`)
+
+| File | Content |
+|---|---|
+| `sandbox.md` | Recommended `excludedCommands`, why each is needed, verified failure modes. Derived from `docs/sec/sandbox-excluded-commands.md`. |
+| `policies.md` | Full rule inventory (git + gh), deny/ask/allow tiers, rationale. Derived from hook rule sets and `docs/sec/gh-exfiltration-defense.md`. |
+| `actions.md` | How to use each action skill: commit, merge, branch, pr, review, secure. |
+| `workflow.md` | Convention skills reference: branching, commits, PRs, file lineage, worktrees. |
+
+---
+
+## Release Sequencing
+
+### v0.12 — Refocus
+
+*Structural reorganization + security gap closure*
+
+- Reorganize into new directory structure (move only, no behavior changes)
+- Update `hooks.json` paths for moved hooks
+- Update `plugin.json` description
+- Close all `git_policy_hook.py` gaps
+- Close all `gh_policy_hook.py` gaps
+- Add `hooks/checks/sandbox_check.py`
+- Add `docs/user/sandbox.md` + `docs/user/policies.md`
+- Update `skills/process/git-workflow` with convention assertions
+- Declare `.worktrees/` in CLAUDE.md
+
+### v0.13 — Actions
+
+*Highest-frequency missing action skills*
+
+- `skills/actions/branch/`
+- `skills/actions/pr/`
+- `skills/actions/secure/`
+- `docs/user/actions.md`
+
+### v0.14 — Review + Conventions Complete
+
+- `skills/actions/review/`
+- `hooks/checks/review_context.py`
+- `docs/user/workflow.md`
+- Convention skill refinements from `docs/research/2026-04-01-superpowers-git-conventions-report.md`
+
+### v1.0 — Expansion
+
+- `hooks/policies/gitlab_policy_hook.py` — `glab` CLI coverage
+- GitHub MCP policy hook — intercept MCP tool calls for repo/PR operations
+
+---
+
+## Related Documents
+
+- `docs/sec/gh-exfiltration-defense.md` — threat model and proposed gh rules
+- `docs/sec/sandbox-excluded-commands.md` — sandbox configuration recommendations
+- `docs/research/2026-04-01-superpowers-git-conventions-report.md` — superpowers git conventions audit
diff --git a/docs/product/2026-04-01-igit-roadmap.md b/docs/product/2026-04-01-igit-roadmap.md
@@ -0,0 +1,117 @@
+---
+created: 2026-04-01
+status: active
+---
+
+# igit Roadmap
+
+igit is a Claude Code plugin for git workflow enforcement and convention guidance.
+It provides interactive action skills for common git operations, process skills that
+assert workflow conventions for model-driven work, and policy hooks that defend against
+accidental data loss and exfiltration attacks.
+
+## Use Cases
+
+### 1. Git Skills
+
+**Action skills** — user-invoked, interactive workflows for each step of the git
+lifecycle: branch, commit, PR, review, merge.
+
+**Process skills** — model-read convention reference for branching strategy, commit
+format, PR conventions, and file lineage. Used automatically when Claude performs
+git operations.
+
+### 2. Policy Hooks
+
+PreToolUse enforcement for `git` and `gh` CLI with layered defense:
+
+- **Data loss prevention** — deny/ask for destructive operations (force push, hard
+  reset, branch force-delete, mirror push)
+- **Exfiltration defense** — deny repo creation, public gist upload, direct URL push,
+  and API content upload endpoints that could leak code to attacker-controlled repos
+- **Infiltration defense** — ask for remote add, non-origin push, and direct URL
+  operations that could introduce malicious content
+- **Shell injection protection** — classify and block dangerous shell operators in
+  chained commands before rule matching
+
+Coverage planned for: `git`, `gh`, `glab` (GitLab CLI), GitHub MCP tools.
+
+### 3. Sandbox Guidance
+
+Documentation, interactive setup, and passive detection for configuring the Claude
+Code sandbox to work safely with git and gh:
+
+- **`igit:secure`** — interactive skill that walks through securing the environment
+- **`sandbox_check`** — SessionStart hook that warns when sandbox config will break
+  git or gh operations
+- **`docs/user/sandbox.md`** — reference guide for required `excludedCommands`
+
+---
+
+## Releases
+
+### v0.12 — Refocus
+
+*Structural reorganization + security gap closure*
+
+**Skills**
+- Reorganize into `skills/process/` and `skills/actions/`
+- Update `git-workflow` process skill: branch naming prefixes, PR-only path to main,
+  worktree ownership (`igit:merge` owns cleanup), `uv sync` for Python setup
+- Declare `.worktrees/` in CLAUDE.md
+
+**Hooks**
+- Reorganize into `hooks/policies/` and `hooks/checks/`
+- Close `git_policy_hook.py` gaps: `git remote add` → ask, direct URL push → deny,
+  non-origin push → ask, force-delete branch → ask
+- Close `gh_policy_hook.py` gaps: `gh repo create/delete` → deny, `gh gist create
+  --public` → deny, API repo/content creation → deny, `gh pr create --repo` → ask,
+  `gh gist create` → ask, `gh release` → ask
+- Add `hooks/checks/sandbox_check.py` (SessionStart: warn on missing excludedCommands)
+
+**Docs**
+- `docs/user/sandbox.md` — recommended excludedCommands with rationale
+- `docs/user/policies.md` — full rule inventory, deny/ask/allow tiers
+
+---
+
+### v0.13 — Actions
+
+*Highest-frequency missing action skills*
+
+- `igit:branch` — create (prefix-guided), switch, delete
+- `igit:pr` — create, view/edit, request review (model-generated PRs)
+- `igit:secure` — guided environment security setup
+- `docs/user/actions.md` — action skills reference
+
+---
+
+### v0.14 — Review + Conventions
+
+*Code review workflow and convention completeness*
+
+- `igit:review` — fetch PR comments, triage, respond inline to GitHub PR reviews
+- `hooks/checks/review_context.py` — UserPromptSubmit hook: fetch PR comments on
+  `/igit:review` or `/receiving-code-review` invocation, inject context, remind about
+  companion skill
+- `docs/user/workflow.md` — convention skills reference
+- Convention refinements from superpowers audit (see
+  `docs/research/2026-04-01-superpowers-git-conventions-report.md`)
+
+---
+
+### v1.0 — Expansion
+
+*Multi-platform policy hook coverage*
+
+- `hooks/policies/gitlab_policy_hook.py` — `glab` CLI coverage
+- GitHub MCP policy hook — intercept MCP tool calls for repo/PR operations
+
+---
+
+## Reference
+
+- Design spec: `docs/plans/2026-04-01-igit-refocus-design.md`
+- Superpowers audit: `docs/research/2026-04-01-superpowers-git-conventions-report.md`
+- Security threat model: `docs/sec/gh-exfiltration-defense.md`
+- Sandbox recommendations: `docs/sec/sandbox-excluded-commands.md`