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.
- package/.gitmessage +5 -0
- package/.releaserc.json +17 -0
- package/CHANGELOG.md +61 -0
- package/CLAUDE.md +61 -0
- package/CONVENTIONS.md +140 -0
- package/GEMINI.md +53 -0
- package/LICENSE +21 -0
- package/README.md +116 -0
- package/RELEASE.md +108 -0
- package/SKILL-INDEX.md +146 -0
- package/assess-impact/SKILL.md +76 -0
- package/audit-code/HEURISTICS.md +43 -0
- package/audit-code/SKILL.md +81 -0
- package/bin/bigpowers.js +27 -0
- package/change-request/REFERENCE.md +60 -0
- package/change-request/SKILL.md +42 -0
- package/commit-message/REFERENCE.md +81 -0
- package/commit-message/SKILL.md +39 -0
- package/countable-story-format.md +293 -0
- package/craft-skill/REFERENCE.md +88 -0
- package/craft-skill/SKILL.md +55 -0
- package/deepen-architecture/DEEPENING.md +37 -0
- package/deepen-architecture/INTERFACE-DESIGN.md +44 -0
- package/deepen-architecture/LANGUAGE.md +53 -0
- package/deepen-architecture/SKILL.md +76 -0
- package/define-language/SKILL.md +75 -0
- package/define-success/SKILL.md +60 -0
- package/delegate-task/SKILL.md +70 -0
- package/design-interface/SKILL.md +94 -0
- package/develop-tdd/SKILL.md +160 -0
- package/develop-tdd/deep-modules.md +33 -0
- package/develop-tdd/interface-design.md +31 -0
- package/develop-tdd/mocking.md +59 -0
- package/develop-tdd/refactoring.md +10 -0
- package/develop-tdd/tests.md +71 -0
- package/dispatch-agents/SKILL.md +72 -0
- package/edit-document/SKILL.md +14 -0
- package/elaborate-spec/SKILL.md +79 -0
- package/enforce-first/SKILL.md +75 -0
- package/execute-plan/SKILL.md +84 -0
- package/grill-me/REFERENCE.md +63 -0
- package/grill-me/SKILL.md +25 -0
- package/guard-git/REFERENCE.md +136 -0
- package/guard-git/SKILL.md +39 -0
- package/guard-git/scripts/block-dangerous-git.sh +41 -0
- package/guard-git/scripts/lib/git-guardrails-core.sh +29 -0
- package/hook-commits/SKILL.md +91 -0
- package/hooks/pre-tool-use.sh +130 -0
- package/index.js +6 -0
- package/inspect-quality/SKILL.md +101 -0
- package/investigate-bug/SKILL.md +111 -0
- package/kickoff-branch/SKILL.md +87 -0
- package/map-codebase/SKILL.md +66 -0
- package/migrate-spec/REFERENCE-GSD.md +137 -0
- package/migrate-spec/REFERENCE.md +186 -0
- package/migrate-spec/SKILL.md +150 -0
- package/model-domain/ADR-FORMAT.md +47 -0
- package/model-domain/CONTEXT-FORMAT.md +77 -0
- package/model-domain/SKILL.md +82 -0
- package/opencode.json +4 -0
- package/orchestrate-project/REFERENCE.md +89 -0
- package/orchestrate-project/SKILL.md +59 -0
- package/organize-workspace/REFERENCE.md +80 -0
- package/organize-workspace/SKILL.md +74 -0
- package/package.json +45 -0
- package/plan-refactor/SKILL.md +75 -0
- package/plan-release/SKILL.md +75 -0
- package/plan-work/SKILL.md +124 -0
- package/playwright.config.ts +56 -0
- package/release-branch/SKILL.md +116 -0
- package/request-review/SKILL.md +70 -0
- package/respond-review/SKILL.md +68 -0
- package/scripts/audit-compliance.sh +256 -0
- package/scripts/cleanup-worktrees.sh +44 -0
- package/scripts/install-cursor-skills-local.sh +13 -0
- package/scripts/install-cursor-skills.sh +34 -0
- package/scripts/install.sh +240 -0
- package/scripts/project-survey.sh +54 -0
- package/scripts/sync-skills.sh +110 -0
- package/seed-conventions/SKILL.md +185 -0
- package/session-state/SKILL.md +69 -0
- package/skills-lock.json +157 -0
- package/spike-prototype/SKILL.md +92 -0
- package/survey-context/SKILL.md +93 -0
- package/terse-mode/SKILL.md +35 -0
- package/trace-requirement/SKILL.md +68 -0
- package/using-bigpowers/SKILL.md +65 -0
- package/validate-fix/SKILL.md +93 -0
- package/visual-dashboard/SKILL.md +49 -0
- package/visual-dashboard/scripts/frame-template.html +189 -0
- package/visual-dashboard/scripts/helper.js +83 -0
- package/visual-dashboard/scripts/server.cjs +345 -0
- package/visual-dashboard/scripts/start-server.sh +121 -0
- package/visual-dashboard/scripts/stop-server.sh +46 -0
- package/wire-observability/SKILL.md +90 -0
- 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
|
+
}
|