bigpowers 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/.gitmessage +5 -0
  2. package/.releaserc.json +17 -0
  3. package/CHANGELOG.md +61 -0
  4. package/CLAUDE.md +61 -0
  5. package/CONVENTIONS.md +140 -0
  6. package/GEMINI.md +53 -0
  7. package/LICENSE +21 -0
  8. package/README.md +116 -0
  9. package/RELEASE.md +108 -0
  10. package/SKILL-INDEX.md +146 -0
  11. package/assess-impact/SKILL.md +76 -0
  12. package/audit-code/HEURISTICS.md +43 -0
  13. package/audit-code/SKILL.md +81 -0
  14. package/bin/bigpowers.js +27 -0
  15. package/change-request/REFERENCE.md +60 -0
  16. package/change-request/SKILL.md +42 -0
  17. package/commit-message/REFERENCE.md +81 -0
  18. package/commit-message/SKILL.md +39 -0
  19. package/countable-story-format.md +293 -0
  20. package/craft-skill/REFERENCE.md +88 -0
  21. package/craft-skill/SKILL.md +55 -0
  22. package/deepen-architecture/DEEPENING.md +37 -0
  23. package/deepen-architecture/INTERFACE-DESIGN.md +44 -0
  24. package/deepen-architecture/LANGUAGE.md +53 -0
  25. package/deepen-architecture/SKILL.md +76 -0
  26. package/define-language/SKILL.md +75 -0
  27. package/define-success/SKILL.md +60 -0
  28. package/delegate-task/SKILL.md +70 -0
  29. package/design-interface/SKILL.md +94 -0
  30. package/develop-tdd/SKILL.md +160 -0
  31. package/develop-tdd/deep-modules.md +33 -0
  32. package/develop-tdd/interface-design.md +31 -0
  33. package/develop-tdd/mocking.md +59 -0
  34. package/develop-tdd/refactoring.md +10 -0
  35. package/develop-tdd/tests.md +71 -0
  36. package/dispatch-agents/SKILL.md +72 -0
  37. package/edit-document/SKILL.md +14 -0
  38. package/elaborate-spec/SKILL.md +79 -0
  39. package/enforce-first/SKILL.md +75 -0
  40. package/execute-plan/SKILL.md +84 -0
  41. package/grill-me/REFERENCE.md +63 -0
  42. package/grill-me/SKILL.md +25 -0
  43. package/guard-git/REFERENCE.md +136 -0
  44. package/guard-git/SKILL.md +39 -0
  45. package/guard-git/scripts/block-dangerous-git.sh +41 -0
  46. package/guard-git/scripts/lib/git-guardrails-core.sh +29 -0
  47. package/hook-commits/SKILL.md +91 -0
  48. package/hooks/pre-tool-use.sh +130 -0
  49. package/index.js +6 -0
  50. package/inspect-quality/SKILL.md +101 -0
  51. package/investigate-bug/SKILL.md +111 -0
  52. package/kickoff-branch/SKILL.md +87 -0
  53. package/map-codebase/SKILL.md +66 -0
  54. package/migrate-spec/REFERENCE-GSD.md +137 -0
  55. package/migrate-spec/REFERENCE.md +186 -0
  56. package/migrate-spec/SKILL.md +150 -0
  57. package/model-domain/ADR-FORMAT.md +47 -0
  58. package/model-domain/CONTEXT-FORMAT.md +77 -0
  59. package/model-domain/SKILL.md +82 -0
  60. package/opencode.json +4 -0
  61. package/orchestrate-project/REFERENCE.md +89 -0
  62. package/orchestrate-project/SKILL.md +59 -0
  63. package/organize-workspace/REFERENCE.md +80 -0
  64. package/organize-workspace/SKILL.md +74 -0
  65. package/package.json +45 -0
  66. package/plan-refactor/SKILL.md +75 -0
  67. package/plan-release/SKILL.md +75 -0
  68. package/plan-work/SKILL.md +124 -0
  69. package/playwright.config.ts +56 -0
  70. package/release-branch/SKILL.md +116 -0
  71. package/request-review/SKILL.md +70 -0
  72. package/respond-review/SKILL.md +68 -0
  73. package/scripts/audit-compliance.sh +256 -0
  74. package/scripts/cleanup-worktrees.sh +44 -0
  75. package/scripts/install-cursor-skills-local.sh +13 -0
  76. package/scripts/install-cursor-skills.sh +34 -0
  77. package/scripts/install.sh +240 -0
  78. package/scripts/project-survey.sh +54 -0
  79. package/scripts/sync-skills.sh +110 -0
  80. package/seed-conventions/SKILL.md +185 -0
  81. package/session-state/SKILL.md +69 -0
  82. package/skills-lock.json +157 -0
  83. package/spike-prototype/SKILL.md +92 -0
  84. package/survey-context/SKILL.md +93 -0
  85. package/terse-mode/SKILL.md +35 -0
  86. package/trace-requirement/SKILL.md +68 -0
  87. package/using-bigpowers/SKILL.md +65 -0
  88. package/validate-fix/SKILL.md +93 -0
  89. package/visual-dashboard/SKILL.md +49 -0
  90. package/visual-dashboard/scripts/frame-template.html +189 -0
  91. package/visual-dashboard/scripts/helper.js +83 -0
  92. package/visual-dashboard/scripts/server.cjs +345 -0
  93. package/visual-dashboard/scripts/start-server.sh +121 -0
  94. package/visual-dashboard/scripts/stop-server.sh +46 -0
  95. package/wire-observability/SKILL.md +90 -0
  96. package/write-document/SKILL.md +63 -0
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: dispatch-agents
3
+ description: Dispatch multiple subagents in parallel on independent tasks. No waiting between them — all run concurrently. Use when tasks are truly decoupled and speed matters. Distinct from delegate-task (concurrent here, no inter-task review gate).
4
+ ---
5
+
6
+ # Dispatch Agents
7
+
8
+ Run multiple subagents in parallel on independent tasks. Use when tasks are genuinely decoupled — no agent needs the output of another to start.
9
+
10
+ **Distinct from `delegate-task`:** This skill maximizes throughput via concurrency. There is no sequential review gate between tasks. Use `delegate-task` instead when a single task needs careful two-stage oversight before proceeding.
11
+
12
+ ## When to use
13
+
14
+ - Tasks that can run simultaneously without shared state
15
+ - Large plans that can be broken into parallel workstreams
16
+ - Exploration: gather information from multiple parts of the codebase at once
17
+
18
+ ## When NOT to use
19
+
20
+ - Task B depends on Task A's output
21
+ - You need to review Task A before Task B can start safely
22
+ - The tasks share a file and concurrent edits would conflict
23
+
24
+ ## Process
25
+
26
+ ### 1. Confirm independence
27
+
28
+ Before dispatching, verify each task pair is truly independent:
29
+ - No shared files being written
30
+ - No shared state (DB migrations, config files)
31
+ - No ordering dependency between outcomes
32
+
33
+ If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead.
34
+
35
+ ### 2. Write task briefs
36
+
37
+ Before writing briefs, read `specs/STATE.md` if it exists — each agent gets only the decisions relevant to its task, nothing else.
38
+
39
+ For each task, use this minimal template (each agent starts cold — brief size directly controls token cost and hallucination risk):
40
+
41
+ ```
42
+ Goal: [one sentence — what success looks like]
43
+ In scope: [explicit file or module list]
44
+ Out of bounds: [what NOT to touch]
45
+ Verify: [runnable command]
46
+ Prior decisions: [relevant entries from specs/STATE.md — omit section if none apply]
47
+ ```
48
+
49
+ Do not include the full conversation, full file contents, or decisions unrelated to this agent's task.
50
+
51
+ ### 3. Dispatch in parallel
52
+
53
+ Spawn all agents in a single message using multiple Agent tool calls. Each agent gets its own complete brief.
54
+
55
+ ```
56
+ Agent 1: brief for task A
57
+ Agent 2: brief for task B
58
+ Agent 3: brief for task C
59
+ ```
60
+
61
+ ### 4. Collect and review results
62
+
63
+ When all agents return:
64
+ - Review each result independently
65
+ - Run all verify commands
66
+ - Check diffs for scope violations or CONVENTIONS.md breaches
67
+
68
+ ### 5. Integrate
69
+
70
+ Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict.
71
+
72
+ Report a summary: which tasks succeeded, which need revision, and overall verify status.
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: edit-document
3
+ description: Edit and improve documents by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, restructure, or improve any document — including specs/ files, articles, READMEs, or technical writing.
4
+ ---
5
+
6
+ 1. First, divide the document into sections based on its headings. Think about the main points made in each section.
7
+
8
+ Consider that information is a directed acyclic graph, and that pieces of information can depend on other pieces of information. Make sure that the order of the sections and their contents respects these dependencies.
9
+
10
+ Confirm the sections with the user.
11
+
12
+ 2. For each section:
13
+
14
+ 2a. Rewrite the section to improve clarity, coherence, and flow. Use maximum 240 characters per paragraph.
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: elaborate-spec
3
+ description: Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn "I want X" into a concrete spec.
4
+ ---
5
+
6
+ # Elaborate Spec
7
+
8
+ Turn a rough idea into a clear specification through focused dialogue. No code is written during this skill — the output is shared understanding and a refined problem statement.
9
+
10
+ ## Process
11
+
12
+ ### 1. Listen first
13
+
14
+ Let the user describe their idea in their own words. Do not interrupt or redirect. Take notes on:
15
+ - The core problem they're trying to solve
16
+ - Who is affected (actors)
17
+ - What success looks like to them
18
+ - Any constraints they've already identified
19
+
20
+ ### 2. Ask clarifying questions
21
+
22
+ Ask one question at a time. Work through these areas:
23
+
24
+ **Problem clarity**
25
+ - What is the current behavior (or lack of behavior) that prompted this?
26
+ - Who experiences this problem? How often?
27
+ - What's the cost of not solving it?
28
+
29
+ **Solution boundaries**
30
+ - What is explicitly IN scope?
31
+ - What is explicitly OUT of scope?
32
+ - Are there existing solutions (internal or external) this replaces or integrates with?
33
+
34
+ **Success criteria**
35
+ - How will you know this is done?
36
+ - What does the happy path look like end-to-end?
37
+ - What are the key failure modes to handle?
38
+
39
+ **Constraints**
40
+ - Any performance requirements?
41
+ - Any compatibility constraints (existing APIs, data formats)?
42
+ - Any non-negotiable implementation decisions already made?
43
+
44
+ ### 2.5. Multiple Interpretations (HARD GATE)
45
+
46
+ > **HARD GATE** — If the request admits ≥2 valid interpretations, do NOT guess. You must list them and ask the user to choose before proceeding. Proceeding with unresolved ambiguity is a failure of integrity.
47
+
48
+ Present the options clearly:
49
+ > "I see two ways to read this:
50
+ > 1. [Interpretation A] — my recommendation because [reason]
51
+ > 2. [Interpretation B]
52
+ > Which is closer to what you mean?"
53
+
54
+ ### 3. Surface hidden assumptions
55
+
56
+ Once the user has answered the main questions, probe for assumptions:
57
+ - "You mentioned X — does that mean Y is also true?"
58
+ - "What happens when Z fails?"
59
+ - "Is this for internal users, external users, or both?"
60
+
61
+ ### 4. Synthesize and confirm
62
+
63
+ Summarize your understanding in 3–5 bullet points:
64
+ - The problem
65
+ - The solution
66
+ - The key constraints
67
+ - The success criteria
68
+ - What's out of scope
69
+
70
+ Ask: "Is this an accurate summary? Anything missing or wrong?"
71
+
72
+ ### 5. Suggest next skill
73
+
74
+ Once the spec is clear, recommend the next step:
75
+ - If domain model needs work → `model-domain`
76
+ - If ready to plan → `plan-release` then `plan-work` per story
77
+ - If a spike is needed first → `spike-prototype`
78
+ - If architecture decisions are needed → `deepen-architecture` or `grill-me`
79
+ - If the plan depends on a specific library or API → `grill-me` in docs mode
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: enforce-first
3
+ description: Apply the F.I.R.S.T test quality rubric (Fast, Independent, Repeatable, Self-Validating, Timely) to a test suite or individual tests. Use when develop-tdd is writing tests, when test quality needs to be checked, or when user mentions F.I.R.S.T or "test quality".
4
+ ---
5
+
6
+ # Enforce FIRST
7
+
8
+ Apply the F.I.R.S.T rubric (Uncle Bob, Clean Code Chapter 9) to evaluate and improve tests.
9
+
10
+ This skill is typically invoked internally by `develop-tdd` during the test-writing phase. It can also be run standalone on an existing test suite.
11
+
12
+ ## The F.I.R.S.T Rubric
13
+
14
+ ### F — Fast
15
+
16
+ Tests must run quickly. Slow tests don't get run. They don't get trusted.
17
+
18
+ - [ ] No real network calls (use fakes/stubs for external I/O)
19
+ - [ ] No real database (use in-memory or transaction-rollback strategies)
20
+ - [ ] No `sleep` or arbitrary timeouts in test code
21
+ - [ ] The full suite runs in under 30 seconds (target; adjust to project size)
22
+
23
+ **Fix:** Replace slow I/O with named fake classes. Never inline anonymous stubs.
24
+
25
+ ### I — Independent
26
+
27
+ Tests must not depend on each other. Running in any order must produce the same result.
28
+
29
+ - [ ] No shared mutable state between tests
30
+ - [ ] Each test sets up its own data and tears it down
31
+ - [ ] No test assumes another test ran first
32
+ - [ ] Tests can be run individually (e.g. `npm test -- mytest.test.ts`) and pass
33
+
34
+ **Fix:** Move setup into `beforeEach`. Use factory functions to build test data.
35
+
36
+ ### R — Repeatable
37
+
38
+ Tests must pass consistently in any environment.
39
+
40
+ - [ ] No dependency on machine-specific paths, ports, or environment variables (unless explicitly injected)
41
+ - [ ] No dependency on current time without mocking the clock
42
+ - [ ] No flakiness — a test that sometimes fails is worse than no test
43
+ - [ ] Tests pass on CI the same way they pass locally
44
+
45
+ **Fix:** Inject time, randomness, and environment as parameters. Pin seeds for anything random.
46
+
47
+ ### S — Self-Validating
48
+
49
+ Tests must report pass or fail automatically. No human inspection required.
50
+
51
+ - [ ] Tests use assertions (`expect`, `assert`, etc.) — not just `console.log`
52
+ - [ ] Failure messages are descriptive enough to diagnose without reading the test body
53
+ - [ ] No tests that "pass" by default when the feature is broken
54
+
55
+ **Fix:** Add assertion messages. Use matchers that describe the expected behavior.
56
+
57
+ ### T — Timely
58
+
59
+ Tests must be written at the right time — before or immediately with the code they test.
60
+
61
+ - [ ] Tests are written in the same commit as the code (or the commit before, if TDD)
62
+ - [ ] No "I'll add tests later" patterns
63
+ - [ ] Bug fixes include a regression test that would have caught the bug
64
+
65
+ **Fix:** Run `develop-tdd` — it enforces the timely principle by design.
66
+
67
+ ## Applying the rubric
68
+
69
+ For each failing criterion:
70
+ 1. Identify which tests violate it
71
+ 2. Describe the fix
72
+ 3. Apply the fix
73
+ 4. Re-run the suite to confirm it still passes
74
+
75
+ Report: "F.I.R.S.T audit complete. X criteria passed, Y fixed."
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: execute-plan
3
+ description: Batch-execute tasks from specs/RELEASE-PLAN.md sequentially, with a human checkpoint after each step. Use when user has an approved plan and wants to execute it step-by-step with oversight, or mentions "execute the plan" or "run the plan".
4
+ ---
5
+
6
+ # Execute Plan
7
+
8
+ Execute the tasks in `specs/RELEASE-PLAN.md` one at a time, showing evidence after each step before proceeding.
9
+
10
+ > **HARD GATE** — Do NOT proceed if on `main` or `master`. Run `kickoff-branch` first to create a feature branch or worktree.
11
+ >
12
+ > **HARD GATE** — Do NOT execute a plan if `specs/RELEASE-PLAN.md` does not exist or if its tasks lack runnable `verify:` commands. If the plan is missing or weak, run `plan-release` then `plan-work` first.
13
+
14
+ ## Process
15
+
16
+ ### 1. Read the plan
17
+
18
+ Read `specs/RELEASE-PLAN.md` in full. Confirm with the user:
19
+ - How many steps are there?
20
+ - Any steps to skip or reorder?
21
+ - Should you stop after a specific step?
22
+
23
+ ### 2. Execute step by step
24
+
25
+ For each step in the plan:
26
+
27
+ **a. Announce the step**
28
+ ```
29
+ ─── Step N of M ─────────────────────────
30
+ Task: [step description]
31
+ verify: [verify command]
32
+ ```
33
+
34
+ **b. Execute the work**
35
+ Implement the step using the appropriate approach:
36
+ - Write/edit code directly for small focused changes
37
+ - Spawn a subagent via `delegate-task` for complex isolated work
38
+
39
+ > **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
40
+
41
+ **c. Run the verify command**
42
+ Every task in `specs/RELEASE-PLAN.md` must have a `verify: <cmd>`. Run it and show the output.
43
+
44
+ **d. Log the decision**
45
+ After verify passes, append to `specs/STATE.md` under `## Active Decisions`:
46
+ ```
47
+ **Step N — [short name]**: [what approach was chosen and why — one sentence]
48
+ ```
49
+ Only log if a non-obvious decision was made (approach chosen, constraint discovered, blocker resolved). Skip if the step was mechanical.
50
+
51
+ **e. Checkpoint**
52
+ Report the result and ask: "Step N complete. Proceed to step N+1?" (or proceed automatically if the user asked for fully autonomous execution)
53
+
54
+ **f. Story Verification (UAT)**
55
+ After the last step of a Story is completed:
56
+ 1. Present the **Verification Script** from `specs/RELEASE-PLAN.md` for this story.
57
+ 2. Ask the user to perform the manual verification steps.
58
+ 3. Wait for the user to confirm "pass" or describe issues.
59
+ 4. If issues are reported, log them and stop execution for diagnosis.
60
+
61
+ If verify fails:
62
+ - Do NOT move to the next step — never advance on a red verify
63
+ - Diagnose the failure
64
+ - Fix it and re-run verify
65
+ - Loop on this step until the verify command is green
66
+ - Only then proceed to the next step
67
+
68
+ If verify passes but behavioral correctness is in doubt, do not advance — a mechanical green is not enough; confirm behavior is correct first.
69
+
70
+ ### 3. Handle blockers
71
+
72
+ If a step cannot be completed as written:
73
+ - Report the blocker clearly
74
+ - Ask the user whether to skip, adapt, or stop
75
+ - Update `specs/RELEASE-PLAN.md` if the plan needs revision
76
+
77
+ ### 4. Final report
78
+
79
+ After all steps complete:
80
+ ```
81
+ ✓ Plan complete: N/N steps executed
82
+ All verify commands passed.
83
+ Suggested next: audit-code → commit-message → release-branch
84
+ ```
@@ -0,0 +1,63 @@
1
+ # Docs Mode — Full Process
2
+
3
+ Triggered by "grill me with docs" or when a plan depends on a specific library or external API.
4
+
5
+ **Why this matters:** AI agents hallucinate API methods, argument orders, and behaviors. Every assumption about an external dependency must be validated against the actual docs before code is written.
6
+
7
+ ## Step 1 — Identify the dependencies
8
+
9
+ From the plan or conversation, list:
10
+ - Every external library being used
11
+ - Every third-party API being called
12
+ - Every framework behavior being relied upon
13
+
14
+ Ask: "Which of these are you most confident about? Which are you less sure of?"
15
+
16
+ ## Step 2 — Fetch the relevant docs
17
+
18
+ For each dependency, fetch the actual documentation:
19
+
20
+ ```
21
+ WebFetch the official docs for [library/API]
22
+ ```
23
+
24
+ Prioritize:
25
+ - The API reference for the specific method being used
26
+ - The changelog for the version in use (breaking changes)
27
+ - Migration guides if upgrading from a previous version
28
+ - Known gotchas / FAQ sections
29
+
30
+ ## Step 3 — Challenge each assumption
31
+
32
+ For every assumption in the plan, find the corresponding doc section and ask:
33
+
34
+ - "Does the real API actually work this way? Show me the doc."
35
+ - "Is this method available in the version you're using?"
36
+ - "Does this argument order match the actual signature?"
37
+ - "Are there rate limits, quotas, or timeout behaviors that affect this design?"
38
+ - "Is this marked as deprecated in the current version?"
39
+
40
+ Ask one question at a time. For each challenge, cite the specific URL and section.
41
+
42
+ ## Step 4 — Surface hallucinations
43
+
44
+ When an assumption doesn't match the docs:
45
+
46
+ > "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime."
47
+
48
+ Document each discrepancy clearly.
49
+
50
+ ## Step 5 — Update the plan
51
+
52
+ For each confirmed discrepancy, recommend a concrete fix:
53
+ - Correct method signature
54
+ - Correct argument order
55
+ - Alternative approach that matches what the library actually supports
56
+ - Whether a spike (`spike-prototype`) is needed to validate a remaining uncertainty
57
+
58
+ ## Step 6 — Sign off
59
+
60
+ When all major assumptions have been validated against docs, report:
61
+ - Which assumptions were confirmed ✓
62
+ - Which were corrected ✗ + what the correct approach is
63
+ - Which remain uncertain → recommend `spike-prototype`
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: grill-me
3
+ description: Stress-test a plan or design through relentless questioning until every decision is resolved. Two modes: Design (default Q&A on decisions) and Docs (grounds every challenge in real library or API documentation). Use when user wants to challenge a plan, validate API assumptions, or mentions "grill me" or "grill me with docs".
4
+ ---
5
+
6
+ # Grill Me
7
+
8
+ Two modes. Default is **Design**. Switch to **Docs** by saying "grill me with docs" or when the plan relies on a specific library or external API.
9
+
10
+ ## Design mode (default)
11
+
12
+ Interview relentlessly about every aspect of this plan until reaching shared understanding. Walk each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. Ask one question at a time.
13
+
14
+ If a question can be answered by exploring the codebase, explore it instead.
15
+
16
+ ## Docs mode
17
+
18
+ Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See [REFERENCE.md](REFERENCE.md) for the full process.
19
+
20
+ Short form:
21
+ 1. List every external library, third-party API, and framework behavior relied upon.
22
+ 2. Fetch the actual docs for each (`WebFetch` the official API reference).
23
+ 3. Challenge each plan assumption against the real docs: correct method signature? right version? deprecated?
24
+ 4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → `spike-prototype`.
25
+ 5. Update the plan for each confirmed discrepancy.
@@ -0,0 +1,136 @@
1
+ # Git guardrails — reference
2
+
3
+ ## Copy layout
4
+
5
+ The main script is `pre-tool-use.sh`.
6
+
7
+ ```text
8
+ <hooks-dir>/pre-tool-use.sh
9
+ ```
10
+
11
+ Example project locations:
12
+
13
+ - Claude: `.claude/hooks/`
14
+ - Cursor: `.cursor/hooks/`
15
+ - Gemini: `.gemini/hooks/`
16
+
17
+ Use the same layout for user-level hooks (`~/.claude/hooks`, `~/.cursor/hooks`, `~/.gemini/hooks`).
18
+
19
+ ---
20
+
21
+ ## Claude Code
22
+
23
+ Hook command does **not** need `GIT_GUARDRAILS_MODE` (defaults to `claude`).
24
+
25
+ **Project** (`.claude/settings.json`):
26
+
27
+ ```json
28
+ {
29
+ "hooks": {
30
+ "PreToolUse": [
31
+ {
32
+ "matcher": "Bash",
33
+ "hooks": [
34
+ {
35
+ "type": "command",
36
+ "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-tool-use.sh"
37
+ }
38
+ ]
39
+ }
40
+ ]
41
+ }
42
+ }
43
+ ```
44
+
45
+ ---
46
+
47
+ ## Cursor and Cursor CLI
48
+
49
+ Use `beforeShellExecution`. Set `GIT_GUARDRAILS_MODE=cursor`.
50
+
51
+ **Project** (`.cursor/hooks.json`):
52
+
53
+ ```json
54
+ {
55
+ "version": 1,
56
+ "hooks": {
57
+ "beforeShellExecution": [
58
+ {
59
+ "command": "GIT_GUARDRAILS_MODE=cursor .cursor/hooks/pre-tool-use.sh",
60
+ "matcher": "git"
61
+ }
62
+ ]
63
+ }
64
+ }
65
+ ```
66
+
67
+ ---
68
+
69
+ ## Gemini CLI
70
+
71
+ Use `BeforeTool` with matcher `run_shell_command`. Set **`GIT_GUARDRAILS_MODE=gemini`**.
72
+
73
+ **Project** (`.gemini/settings.json`):
74
+
75
+ ```json
76
+ {
77
+ "hooks": {
78
+ "BeforeTool": [
79
+ {
80
+ "matcher": "run_shell_command",
81
+ "hooks": [
82
+ {
83
+ "name": "git-guardrails",
84
+ "type": "command",
85
+ "command": "GIT_GUARDRAILS_MODE=gemini \"$GEMINI_PROJECT_DIR\"/.gemini/hooks/pre-tool-use.sh",
86
+ "timeout": 5000
87
+ }
88
+ ]
89
+ }
90
+ ]
91
+ }
92
+ }
93
+ ```
94
+
95
+ ---
96
+
97
+ ## Google Antigravity
98
+
99
+ Add **Deny list** entries in **Antigravity → Settings → Terminal**:
100
+
101
+ - `git push`
102
+ - `git push --force`
103
+ - `git reset --hard`
104
+ - `git clean`
105
+ - `git branch -D`
106
+ - `git checkout .`
107
+ - `git restore .`
108
+
109
+ ---
110
+
111
+ ## Verify (local tests)
112
+
113
+ **1. Dangerous Pattern (Claude mode):**
114
+ ```bash
115
+ echo '{"tool_input":{"command":"git push origin main"}}' | ./pre-tool-use.sh
116
+ # Expected: exit 2, stderr message
117
+ ```
118
+
119
+ **2. Conventional Commits (Gemini mode):**
120
+ ```bash
121
+ echo '{"tool_input":{"command":"git commit -m \"bad message\""}}' | GIT_GUARDRAILS_MODE=gemini ./pre-tool-use.sh
122
+ # Expected: exit 0, {"decision":"deny", "reason":"..."}
123
+ ```
124
+
125
+ **3. Protected Branch (Cursor mode):**
126
+ ```bash
127
+ # Run on 'main' branch
128
+ echo '{"command":"git commit -m \"feat: valid message\""}' | GIT_GUARDRAILS_MODE=cursor ./pre-tool-use.sh
129
+ # Expected: exit 2, "Direct commits to protected branch 'main' are forbidden"
130
+ ```
131
+
132
+ **4. Allow (Gemini mode):**
133
+ ```bash
134
+ echo '{"tool_input":{"command":"git status"}}' | GIT_GUARDRAILS_MODE=gemini ./pre-tool-use.sh
135
+ # Expected: exit 0, {"decision":"allow"}
136
+ ```
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: guard-git
3
+ description: Block dangerous git commands (push, force push, reset --hard, clean, branch -D, checkout/restore .) and enforce Conventional Commits & Branch Protection before an AI agent runs them. Installs hook scripts for Claude Code, Cursor, Cursor CLI, and Gemini CLI; documents Google Antigravity Terminal deny lists. Use when the user wants git safety hooks, to block git push or destructive git in agents, or to mirror the same policy across AI coding tools.
4
+ ---
5
+
6
+ # Guard Git
7
+
8
+ Installs a shared hook that blocks destructive git operations and enforces workflow discipline. **Requires `jq` on the agent's PATH** when the hook runs.
9
+
10
+ ## What gets blocked/enforced
11
+
12
+ - **Safety**: `git push` (including `--force`), `git reset --hard`, `git clean -f`, `git branch -D`, `git checkout .`, `git restore .`.
13
+ - **Discipline**: Blocks direct commits or pushes to protected branches (`main`, `master`).
14
+ - **Standardization**: Enforces [Conventional Commits](https://www.conventionalcommits.org/) for all `git commit` commands.
15
+
16
+ ## Quick start
17
+
18
+ 1. **Scope**: ask project-only vs global (paths differ per product).
19
+ 2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory.
20
+ 3. **Run `chmod +x`** on `pre-tool-use.sh`.
21
+ 4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys.
22
+ 5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md).
23
+
24
+ | Client | Mechanism | Config |
25
+ |--------|-----------|--------|
26
+ | Claude Code | `PreToolUse` (Bash) | `.claude/settings.json` or `~/.claude/settings.json` |
27
+ | Cursor / Cursor CLI | `beforeShellExecution` | `.cursor/hooks.json` or `~/.cursor/hooks.json` |
28
+ | Gemini CLI | `BeforeTool` + `run_shell_command` | `.gemini/settings.json` or `~/.gemini/settings.json` |
29
+ | Google Antigravity | Built-in Terminal **Deny list** | Settings UI (no shell hook) |
30
+
31
+ **Modes (env on the hook command):** `GIT_GUARDRAILS_MODE` is `claude` (default) or `cursor` → stderr + exit `2` on block. Set `gemini` for Gemini CLI → JSON `decision` on stdout.
32
+
33
+ ## Customization
34
+
35
+ To add or remove patterns or protected branches, edit `pre-tool-use.sh`.
36
+
37
+ ## Advanced
38
+
39
+ Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: [REFERENCE.md](REFERENCE.md).
@@ -0,0 +1,41 @@
1
+ #!/usr/bin/env bash
2
+ # Blocks dangerous git commands for Claude Code, Cursor, and Gemini CLI hooks.
3
+ # Requires jq on PATH.
4
+ # GIT_GUARDRAILS_MODE: claude (default) | cursor | gemini
5
+ # claude/cursor: stderr message, exit 2 on block, exit 0 on allow
6
+ # gemini: JSON with decision on stdout, exit 0 always (allow or deny)
7
+
8
+ set -euo pipefail
9
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
10
+ # shellcheck source=lib/git-guardrails-core.sh
11
+ . "$SCRIPT_DIR/lib/git-guardrails-core.sh"
12
+
13
+ INPUT=$(cat)
14
+ COMMAND=$(echo "$INPUT" | jq -r '.command // .tool_input.command // empty')
15
+ MODE="${GIT_GUARDRAILS_MODE:-claude}"
16
+
17
+ if [ -z "$COMMAND" ]; then
18
+ if [ "$MODE" = "gemini" ]; then
19
+ echo '{"decision":"allow"}'
20
+ fi
21
+ exit 0
22
+ fi
23
+
24
+ if PATTERN=$(git_guardrails_first_match "$COMMAND"); then
25
+ REASON="BLOCKED: '$COMMAND' matches dangerous pattern '$PATTERN'. The user has prevented you from doing this."
26
+ case "$MODE" in
27
+ gemini)
28
+ jq -nc --arg reason "$REASON" '{decision: "deny", reason: $reason}'
29
+ exit 0
30
+ ;;
31
+ claude|cursor|*)
32
+ echo "$REASON" >&2
33
+ exit 2
34
+ ;;
35
+ esac
36
+ else
37
+ if [ "$MODE" = "gemini" ]; then
38
+ echo '{"decision":"allow"}'
39
+ fi
40
+ exit 0
41
+ fi
@@ -0,0 +1,29 @@
1
+ # Shared pattern list and matcher for git hook guardrails.
2
+ # Source from block-dangerous-git.sh only.
3
+
4
+ GIT_GUARDRAILS_PATTERNS=(
5
+ "git push"
6
+ "git reset --hard"
7
+ "git clean -fd"
8
+ "git clean -f"
9
+ "git branch -D"
10
+ "git checkout \\."
11
+ "git restore \\."
12
+ "push --force"
13
+ "reset --hard"
14
+ )
15
+
16
+ # Print first matching pattern to stdout; exit 0 if dangerous, 1 if safe.
17
+ # Usage: if git_guardrails_first_match "$command"; then read pattern; fi
18
+ # Actually: pattern=$(git_guardrails_first_match "$c") && ...
19
+ git_guardrails_first_match() {
20
+ local cmd="$1"
21
+ local p
22
+ for p in "${GIT_GUARDRAILS_PATTERNS[@]}"; do
23
+ if echo "$cmd" | grep -qE "$p"; then
24
+ printf '%s' "$p"
25
+ return 0
26
+ fi
27
+ done
28
+ return 1
29
+ }