From c729937349fec68cac37fd19152a07b06d75e975 Mon Sep 17 00:00:00 2001 From: tg-agent <268907238+tg-agent@users.noreply.github.com> Date: Wed, 1 Apr 2026 07:24:07 -0600 Subject: [PATCH 1/2] docs: add igit refocus design and superpowers git conventions report MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spec for restructuring igit around four quadrants: process skills, action skills, policy hooks, and checks hooks. Includes v0.12–v1.0 release sequencing and superpowers conventions audit findings. Co-Authored-By: Trevor Gullstad Co-Authored-By: Claude --- docs/plans/2026-04-01-igit-refocus-design.md | 249 ++++++++++++++++++ ...4-01-superpowers-git-conventions-report.md | 102 +++++++ 2 files changed, 351 insertions(+) create mode 100644 docs/plans/2026-04-01-igit-refocus-design.md create mode 100644 docs/research/2026-04-01-superpowers-git-conventions-report.md diff --git a/docs/plans/2026-04-01-igit-refocus-design.md b/docs/plans/2026-04-01-igit-refocus-design.md new file mode 100644 index 0000000..f1ad106 --- /dev/null +++ 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 *` | 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/research/2026-04-01-superpowers-git-conventions-report.md b/docs/research/2026-04-01-superpowers-git-conventions-report.md new file mode 100644 index 0000000..9ba39b2 --- /dev/null +++ b/docs/research/2026-04-01-superpowers-git-conventions-report.md @@ -0,0 +1,102 @@ +--- +created: 2026-04-01 +topic: superpowers skill git conventions audit +--- + +# Superpowers ↔ igit Research Report + +Audit of all 14 superpowers skills for git-related content: commands, conventions, +workflow assumptions, and overlap with igit. + +## Skills with Significant Git Involvement + +| Skill | Git-related | Summary | +|---|---|---| +| `using-git-worktrees` | Deep | Core git workflow skill | +| `finishing-a-development-branch` | Deep | merge, push, PR, cleanup | +| `subagent-driven-development` | Deep | worktree required, commits, SHAs | +| `executing-plans` | Deep | worktree required, no main/master | +| `requesting-code-review` | Moderate | git diff, SHAs, "before merge to main" | +| `writing-plans` | Moderate | worktree context, frequent commits | +| `brainstorming` | Light | commits spec doc, .gitignore for .superpowers/ | +| `using-superpowers` | Light | git state detection (Codex), worktree detection | +| `receiving-code-review` | Marginal | gh API pattern for inline replies only | +| `systematic-debugging` | Marginal | git diff for root cause, git init examples | +| `writing-skills` | Marginal | `git add -A` anti-pattern, deploy checklist commit | +| `dispatching-parallel-agents` | No | — | +| `test-driven-development` | No | — | +| `verification-before-completion` | No | — | + +--- + +## Convention Gaps (things igit should assert) + +### 1. Python setup — confirmed gap + +`using-git-worktrees` uses `pip install -r requirements.txt` and `poetry install` for +Python. No knowledge of `uv`. igit's process skill should assert: for Python projects, +use `uv sync`. + +### 2. Branch naming — no conventions upstream + +No superpowers skill specifies prefix conventions. The only example shown is +`feature/auth`. igit owns this: `feature/`, `fix/`, `refactor/`, `docs/` conventions +should be asserted in `skills/process/`. + +### 3. Worktree directory — needs CLAUDE.md declaration + +`using-git-worktrees` reads CLAUDE.md for directory preference. igit should declare +`.worktrees/` explicitly in CLAUDE.md so the skill picks it up without asking. + +### 4. `git add -A` anti-pattern + +`writing-skills` graphviz conventions note `NEVER use git add -A`. This aligns with +igit's commit skill — worth cross-referencing in `igit:commit`. + +--- + +## Workflow Overlaps / Conflicts + +### 1. Worktree cleanup ownership — ambiguous + +- `finishing-a-development-branch` handles worktree removal (pairs with `using-git-worktrees`) +- `igit:merge` Stage 3 also handles worktree removal +- Both can fire on the same merge event. igit should either defer worktree cleanup to + `finishing-a-development-branch` or make `igit:merge` the single owner and document + the override. + +### 2. "Before merge to main" — convention conflict + +`requesting-code-review` says review is mandatory "Before merge to main," implying +direct merges are possible. igit enforces all changes go through PRs. igit's +`skills/process/git-workflow` should note that direct merges to main are prohibited +regardless of what other skills suggest. + +### 3. `git branch -D` (force delete) + +`finishing-a-development-branch` uses `-D` for the discard option (Option 4). igit's +policy hook has an open backlog item (`2026-03-27-git-policy-hook-force-delete-ask.md`) +to add `ask` for force-delete. These should be consistent — the hook should ask, the +skill should expect the ask. + +### 4. `receiving-code-review` + `igit:review` scope + +The superpowers skill focuses on the intellectual process (pushback, verification, +ordering). It surfaces one GitHub API pattern: +`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies` for inline thread +replies. `igit:review` owns the fetch-triage-respond execution layer and should +reference this API pattern explicitly. + +--- + +## Action Items for igit Roadmap + +| Item | Where | Type | +|---|---|---| +| Assert `uv sync` for Python worktree setup | `skills/process/` | Convention | +| Assert branch naming prefixes | `skills/process/` | Convention | +| Declare `.worktrees/` in CLAUDE.md | CLAUDE.md | Convention | +| Declare `igit:merge` owns worktree cleanup | `skills/process/` + `igit:merge` docs | Convention | +| Assert PR-only path to main (no direct merges) | `skills/process/git-workflow` | Convention | +| Implement force-delete `ask` hook | `hooks/policies/git_policy_hook.py` | Policy | +| Reference inline reply API in `igit:review` | `skills/actions/review/` | Action skill | From 947223710bb4bea26a9931194361240b9d6b1c0c Mon Sep 17 00:00:00 2001 From: tg-agent <268907238+tg-agent@users.noreply.github.com> Date: Wed, 1 Apr 2026 07:26:34 -0600 Subject: [PATCH 2/2] docs: add igit product roadmap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit High-level roadmap covering v0.12–v1.0: refocus (structural + security), actions (branch/pr/secure), review + conventions, and multi-platform hook expansion. Co-Authored-By: Trevor Gullstad Co-Authored-By: Claude --- docs/product/2026-04-01-igit-roadmap.md | 117 ++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/product/2026-04-01-igit-roadmap.md diff --git a/docs/product/2026-04-01-igit-roadmap.md b/docs/product/2026-04-01-igit-roadmap.md new file mode 100644 index 0000000..5eca052 --- /dev/null +++ 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`