@complexthings/superpowers-agent 10.0.3 → 11.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/.agents/superpowers-agent +17 -222
- package/.github/copilot-instructions.md +0 -9
- package/AGENTS.md +19 -140
- package/README.md +79 -507
- package/package.json +1 -7
- package/.agents/docs/SUPERPOWERS.md +0 -37
- package/.agents/skills/.gitkeep +0 -0
- package/.agents/skills/claude-handoff/SKILL.md +0 -18
- package/.agents/skills/code-review/SKILL.md +0 -89
- package/.agents/skills/codebase-design/DEEPENING.md +0 -37
- package/.agents/skills/codebase-design/DESIGN-IT-TWICE.md +0 -44
- package/.agents/skills/codebase-design/SKILL.md +0 -114
- package/.agents/skills/design-an-interface/SKILL.md +0 -94
- package/.agents/skills/diagnosing-bugs/SKILL.md +0 -134
- package/.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh +0 -41
- package/.agents/skills/domain-modeling/ADR-FORMAT.md +0 -47
- package/.agents/skills/domain-modeling/CONTEXT-FORMAT.md +0 -60
- package/.agents/skills/domain-modeling/SKILL.md +0 -74
- package/.agents/skills/fable-mode/SKILL.md +0 -95
- package/.agents/skills/git-guardrails-claude-code/SKILL.md +0 -95
- package/.agents/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh +0 -25
- package/.agents/skills/grill-me/SKILL.md +0 -7
- package/.agents/skills/grill-with-docs/SKILL.md +0 -7
- package/.agents/skills/grilling/SKILL.md +0 -14
- package/.agents/skills/handoff/SKILL.md +0 -16
- package/.agents/skills/i-have-adhd/SKILL.md +0 -120
- package/.agents/skills/implement/SKILL.md +0 -11
- package/.agents/skills/improve-codebase-architecture/HTML-REPORT.md +0 -123
- package/.agents/skills/improve-codebase-architecture/SKILL.md +0 -66
- package/.agents/skills/loop-me/SKILL.md +0 -32
- package/.agents/skills/prototype/LOGIC.md +0 -79
- package/.agents/skills/prototype/SKILL.md +0 -30
- package/.agents/skills/prototype/UI.md +0 -112
- package/.agents/skills/qa/SKILL.md +0 -130
- package/.agents/skills/request-refactor-plan/SKILL.md +0 -68
- package/.agents/skills/research/SKILL.md +0 -12
- package/.agents/skills/resolving-merge-conflicts/SKILL.md +0 -14
- package/.agents/skills/scaffold-exercises/SKILL.md +0 -106
- package/.agents/skills/setup-matt-pocock-skills/SKILL.md +0 -127
- package/.agents/skills/setup-matt-pocock-skills/domain.md +0 -51
- package/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md +0 -45
- package/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md +0 -46
- package/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md +0 -30
- package/.agents/skills/setup-matt-pocock-skills/triage-labels.md +0 -15
- package/.agents/skills/skill-creator/LICENSE.txt +0 -202
- package/.agents/skills/skill-creator/SKILL.md +0 -485
- package/.agents/skills/skill-creator/agents/analyzer.md +0 -274
- package/.agents/skills/skill-creator/agents/comparator.md +0 -202
- package/.agents/skills/skill-creator/agents/grader.md +0 -223
- package/.agents/skills/skill-creator/assets/eval_review.html +0 -146
- package/.agents/skills/skill-creator/eval-viewer/generate_review.py +0 -471
- package/.agents/skills/skill-creator/eval-viewer/viewer.html +0 -1325
- package/.agents/skills/skill-creator/references/schemas.md +0 -430
- package/.agents/skills/skill-creator/scripts/__init__.py +0 -0
- package/.agents/skills/skill-creator/scripts/__pycache__/__init__.cpython-314.pyc +0 -0
- package/.agents/skills/skill-creator/scripts/__pycache__/run_eval.cpython-314.pyc +0 -0
- package/.agents/skills/skill-creator/scripts/__pycache__/utils.cpython-314.pyc +0 -0
- package/.agents/skills/skill-creator/scripts/aggregate_benchmark.py +0 -401
- package/.agents/skills/skill-creator/scripts/generate_report.py +0 -326
- package/.agents/skills/skill-creator/scripts/improve_description.py +0 -247
- package/.agents/skills/skill-creator/scripts/package_skill.py +0 -136
- package/.agents/skills/skill-creator/scripts/quick_validate.py +0 -103
- package/.agents/skills/skill-creator/scripts/run_eval.py +0 -310
- package/.agents/skills/skill-creator/scripts/run_loop.py +0 -328
- package/.agents/skills/skill-creator/scripts/utils.py +0 -47
- package/.agents/skills/tdd/SKILL.md +0 -36
- package/.agents/skills/tdd/mocking.md +0 -59
- package/.agents/skills/tdd/tests.md +0 -77
- package/.agents/skills/teach/GLOSSARY-FORMAT.md +0 -35
- package/.agents/skills/teach/LEARNING-RECORD-FORMAT.md +0 -46
- package/.agents/skills/teach/MISSION-FORMAT.md +0 -31
- package/.agents/skills/teach/RESOURCES-FORMAT.md +0 -32
- package/.agents/skills/teach/SKILL.md +0 -140
- package/.agents/skills/to-spec/SKILL.md +0 -75
- package/.agents/skills/to-tickets/SKILL.md +0 -114
- package/.agents/skills/triage/AGENT-BRIEF.md +0 -207
- package/.agents/skills/triage/OUT-OF-SCOPE.md +0 -105
- package/.agents/skills/triage/SKILL.md +0 -112
- package/.agents/skills/ubiquitous-language/SKILL.md +0 -93
- package/.agents/skills/wayfinder/SKILL.md +0 -127
- package/.agents/skills/writing-great-skills/GLOSSARY.md +0 -201
- package/.agents/skills/writing-great-skills/SKILL.md +0 -83
- package/.agents/templates/AGENTS.md.template +0 -27
- package/.agents/templates/SUPERPOWERS.md.template +0 -37
- package/skills/collaboration/brainstorming/SKILL.md +0 -66
- package/skills/collaboration/brainstorming/skill.json +0 -9
- package/skills/collaboration/leveraging-cli-tools/SKILL.md +0 -110
- package/skills/collaboration/leveraging-cli-tools/references/copilot-instructions.md +0 -30
- package/skills/collaboration/leveraging-cli-tools/scripts/setup-ponytail.sh +0 -185
- package/skills/collaboration/leveraging-cli-tools/scripts/setup-rtk.sh +0 -217
- package/skills/collaboration/leveraging-cli-tools/skill.json +0 -9
- package/skills/meta/create-skill-json/SKILL.md +0 -370
- package/skills/meta/create-skill-json/skill.json +0 -9
- package/skills/meta/create-skill-json/test-scenarios.md +0 -29
- package/skills/setup-skills/SKILL.md +0 -54
- package/skills/setup-skills/skill.json +0 -8
|
@@ -1,47 +0,0 @@
|
|
|
1
|
-
# ADR Format
|
|
2
|
-
|
|
3
|
-
ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
|
|
4
|
-
|
|
5
|
-
Create the `docs/adr/` directory lazily — only when the first ADR is needed.
|
|
6
|
-
|
|
7
|
-
## Template
|
|
8
|
-
|
|
9
|
-
```md
|
|
10
|
-
# {Short title of the decision}
|
|
11
|
-
|
|
12
|
-
{1-3 sentences: what's the context, what did we decide, and why.}
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
|
|
16
|
-
|
|
17
|
-
## Optional sections
|
|
18
|
-
|
|
19
|
-
Only include these when they add genuine value. Most ADRs won't need them.
|
|
20
|
-
|
|
21
|
-
- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
|
|
22
|
-
- **Considered Options** — only when the rejected alternatives are worth remembering
|
|
23
|
-
- **Consequences** — only when non-obvious downstream effects need to be called out
|
|
24
|
-
|
|
25
|
-
## Numbering
|
|
26
|
-
|
|
27
|
-
Scan `docs/adr/` for the highest existing number and increment by one.
|
|
28
|
-
|
|
29
|
-
## When to offer an ADR
|
|
30
|
-
|
|
31
|
-
All three of these must be true:
|
|
32
|
-
|
|
33
|
-
1. **Hard to reverse** — the cost of changing your mind later is meaningful
|
|
34
|
-
2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
|
|
35
|
-
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
|
|
36
|
-
|
|
37
|
-
If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
|
|
38
|
-
|
|
39
|
-
### What qualifies
|
|
40
|
-
|
|
41
|
-
- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
|
|
42
|
-
- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
|
|
43
|
-
- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
|
|
44
|
-
- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
|
|
45
|
-
- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
|
|
46
|
-
- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
|
|
47
|
-
- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.
|
|
@@ -1,60 +0,0 @@
|
|
|
1
|
-
# CONTEXT.md Format
|
|
2
|
-
|
|
3
|
-
## Structure
|
|
4
|
-
|
|
5
|
-
```md
|
|
6
|
-
# {Context Name}
|
|
7
|
-
|
|
8
|
-
{One or two sentence description of what this context is and why it exists.}
|
|
9
|
-
|
|
10
|
-
## Language
|
|
11
|
-
|
|
12
|
-
**Order**:
|
|
13
|
-
{A one or two sentence description of the term}
|
|
14
|
-
_Avoid_: Purchase, transaction
|
|
15
|
-
|
|
16
|
-
**Invoice**:
|
|
17
|
-
A request for payment sent to a customer after delivery.
|
|
18
|
-
_Avoid_: Bill, payment request
|
|
19
|
-
|
|
20
|
-
**Customer**:
|
|
21
|
-
A person or organization that places orders.
|
|
22
|
-
_Avoid_: Client, buyer, account
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
## Rules
|
|
26
|
-
|
|
27
|
-
- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
|
|
28
|
-
- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
|
|
29
|
-
- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
|
|
30
|
-
- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
|
|
31
|
-
|
|
32
|
-
## Single vs multi-context repos
|
|
33
|
-
|
|
34
|
-
**Single context (most repos):** One `CONTEXT.md` at the repo root.
|
|
35
|
-
|
|
36
|
-
**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
|
|
37
|
-
|
|
38
|
-
```md
|
|
39
|
-
# Context Map
|
|
40
|
-
|
|
41
|
-
## Contexts
|
|
42
|
-
|
|
43
|
-
- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
|
|
44
|
-
- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
|
|
45
|
-
- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
|
|
46
|
-
|
|
47
|
-
## Relationships
|
|
48
|
-
|
|
49
|
-
- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
|
|
50
|
-
- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
|
|
51
|
-
- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
The skill infers which structure applies:
|
|
55
|
-
|
|
56
|
-
- If `CONTEXT-MAP.md` exists, read it to find contexts
|
|
57
|
-
- If only a root `CONTEXT.md` exists, single context
|
|
58
|
-
- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
|
|
59
|
-
|
|
60
|
-
When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.
|
|
@@ -1,74 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: domain-modeling
|
|
3
|
-
description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Domain Modeling
|
|
7
|
-
|
|
8
|
-
Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
|
|
9
|
-
|
|
10
|
-
## File structure
|
|
11
|
-
|
|
12
|
-
Most repos have a single context:
|
|
13
|
-
|
|
14
|
-
```
|
|
15
|
-
/
|
|
16
|
-
├── CONTEXT.md
|
|
17
|
-
├── docs/
|
|
18
|
-
│ └── adr/
|
|
19
|
-
│ ├── 0001-event-sourced-orders.md
|
|
20
|
-
│ └── 0002-postgres-for-write-model.md
|
|
21
|
-
└── src/
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
|
|
25
|
-
|
|
26
|
-
```
|
|
27
|
-
/
|
|
28
|
-
├── CONTEXT-MAP.md
|
|
29
|
-
├── docs/
|
|
30
|
-
│ └── adr/ ← system-wide decisions
|
|
31
|
-
├── src/
|
|
32
|
-
│ ├── ordering/
|
|
33
|
-
│ │ ├── CONTEXT.md
|
|
34
|
-
│ │ └── docs/adr/ ← context-specific decisions
|
|
35
|
-
│ └── billing/
|
|
36
|
-
│ ├── CONTEXT.md
|
|
37
|
-
│ └── docs/adr/
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
|
|
41
|
-
|
|
42
|
-
## During the session
|
|
43
|
-
|
|
44
|
-
### Challenge against the glossary
|
|
45
|
-
|
|
46
|
-
When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
|
|
47
|
-
|
|
48
|
-
### Sharpen fuzzy language
|
|
49
|
-
|
|
50
|
-
When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
|
|
51
|
-
|
|
52
|
-
### Discuss concrete scenarios
|
|
53
|
-
|
|
54
|
-
When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
|
|
55
|
-
|
|
56
|
-
### Cross-reference with code
|
|
57
|
-
|
|
58
|
-
When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
|
|
59
|
-
|
|
60
|
-
### Update CONTEXT.md inline
|
|
61
|
-
|
|
62
|
-
When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
|
|
63
|
-
|
|
64
|
-
`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
|
|
65
|
-
|
|
66
|
-
### Offer ADRs sparingly
|
|
67
|
-
|
|
68
|
-
Only offer to create an ADR when all three are true:
|
|
69
|
-
|
|
70
|
-
1. **Hard to reverse** — the cost of changing your mind later is meaningful
|
|
71
|
-
2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
|
|
72
|
-
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
|
|
73
|
-
|
|
74
|
-
If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
|
|
@@ -1,95 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: fable-mode
|
|
3
|
-
description: Use PROACTIVELY the moment you notice a task has many layers - multiple dependent steps, unknowns that could change the approach, debugging where the first theory might be wrong, or anything that needs verification before handoff. Also use when a task keeps failing or stalling, or when Nate says "fable mode", "think like Fable", "use the Fable skill", "use the Fable method", "work like Fable", "slow down and do this right", or "think this through first". Loads Fable 5's working discipline (the five-gate task loop plus standing habits) so any session, especially one running on Opus 4.8 or Sonnet 5, applies it.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# The Fable Method
|
|
7
|
-
|
|
8
|
-
Fable 5's working discipline, written down so any model can run it. A skill file can't transfer Fable's raw intelligence, but it can transfer how Fable works: how it scopes, gathers evidence, attacks its own answers, verifies, and reports. Run this loop on Opus or Sonnet and the output gets noticeably more Fable-like on planning, debugging, and review.
|
|
9
|
-
|
|
10
|
-
A hard task is anything where the first idea might be wrong: multi-step builds, debugging, research with claims, anything touching data you haven't looked at yet. For a one-file edit or a simple lookup, skip the gates and just do the work.
|
|
11
|
-
|
|
12
|
-
## The loop: five gates, in order
|
|
13
|
-
|
|
14
|
-
Every hard task passes through five gates. A gate must pass before the next one opens. When a task stalls or a result surprises you, name which gate you're at and re-run it.
|
|
15
|
-
|
|
16
|
-
### Gate 1 — Scope before work
|
|
17
|
-
|
|
18
|
-
State what done looks like before touching anything.
|
|
19
|
-
|
|
20
|
-
- Define done in one or two sentences: what artifact exists at the end, what must be true of it, and how you will check that it's true. If you can't write the check, you don't understand the task yet.
|
|
21
|
-
- Check standing rules first (CLAUDE.md, skills, memory). Don't invent an approach the project already has a rule for.
|
|
22
|
-
- Separate known from assumed. Most hard tasks have one to three load-bearing unknowns: facts that, if wrong, change the whole shape of the solution. Name them explicitly.
|
|
23
|
-
- If the request is ambiguous in a way that changes what you'd build, ask one question, aimed at the biggest gap. Otherwise pick the sensible default, say so in one line, and proceed. Ask questions to change outcomes, not to feel safe.
|
|
24
|
-
- Right-size the effort. Match the depth of this process to the stakes of the task. Deep reasoning belongs in planning and review, not in mechanical steps.
|
|
25
|
-
|
|
26
|
-
### Gate 2 — Evidence before reasoning
|
|
27
|
-
|
|
28
|
-
Never design from memory of what a file, API, or dataset "probably" looks like. Open it.
|
|
29
|
-
|
|
30
|
-
- Files and live tool output are sources. Training memory is only a hypothesis generator.
|
|
31
|
-
- Attack the load-bearing unknowns first, with the cheapest probe. A 30-second read of the real data beats an hour of building on a guess.
|
|
32
|
-
- Prefer a thin end-to-end pass over a complete first stage. Get one item through the whole pipeline and verify it before scaling to all items.
|
|
33
|
-
- Keep a live plan for anything with 3+ steps. Slice by dependency, not by category: each step's output feeds the next. The plan is a hypothesis, not a contract.
|
|
34
|
-
|
|
35
|
-
### Gate 3 — Reason adversarially
|
|
36
|
-
|
|
37
|
-
Before committing to an answer, switch roles and try to kill it.
|
|
38
|
-
|
|
39
|
-
- Attack your own emerging answer as a hostile reviewer: what input, state, or reading makes this wrong? Actually test that case; don't just imagine it.
|
|
40
|
-
- Then steelman what survives. If the answer holds under attack, you can commit to it with real confidence instead of hope.
|
|
41
|
-
- Steelman the existing thing before changing it. Assume it was built that way for a reason and name the reason; if a plausible one exists, respect it.
|
|
42
|
-
- When reviewing, finding nothing wrong is a legitimate result. "Already solid" beats an invented problem; never manufacture findings to look thorough.
|
|
43
|
-
- Re-decide after every result. Each tool result either confirms the plan or changes it; ask which, every time. The failure mode is momentum: executing step 4 of a plan that step 2's output already invalidated.
|
|
44
|
-
- Two failed attempts at the same fix means the diagnosis is wrong. Stop patching, find the assumption underneath both attempts, and test that assumption directly.
|
|
45
|
-
|
|
46
|
-
### Gate 4 — Verify before declaring done
|
|
47
|
-
|
|
48
|
-
"It ran" is not verification. Verify at the layer of the claim.
|
|
49
|
-
|
|
50
|
-
- If the claim is "the output is correct," look at the output. If the claim is "the page renders," look at the page. Exit code 0 only proves the layer below the claim.
|
|
51
|
-
- Use evidence you didn't generate. Re-open the file you wrote. Run the code. Screenshot the page and read the screenshot. Diff before against after. Count the things you claimed to count.
|
|
52
|
-
- Re-check against the original request and the standing rules from Gate 1. Did you build what was asked, and did you follow the rules you loaded?
|
|
53
|
-
- Sample the tails, not just the middle: first item, last item, weirdest item. Happy-path spot checks hide the failures that matter.
|
|
54
|
-
- Treat good news as suspect. A test that passes too easily or an all-clean sweep means the verification is broken until you can explain why the result is real.
|
|
55
|
-
- Zero-context test for anything user-facing: would someone with none of this session's context understand it and be able to act on it?
|
|
56
|
-
|
|
57
|
-
### Gate 5 — Report calibrated
|
|
58
|
-
|
|
59
|
-
The report is part of the work, not an afterthought.
|
|
60
|
-
|
|
61
|
-
- Lead with the answer, then the support.
|
|
62
|
-
- Separate verified from assumed, out loud. "I confirmed X by running Y; I'm assuming Z because I couldn't check it."
|
|
63
|
-
- Cite evidence with specifics: file paths, line numbers, the command you ran, the number you saw.
|
|
64
|
-
- Report what you observed, not what you intended. If tests failed, say so with the output. If a step was skipped, say that.
|
|
65
|
-
- Never soften a real problem to be agreeable. Disagreement with concrete reasoning beats compliance. Flag the risk once, concretely, then respect the user's call.
|
|
66
|
-
- Never state as fact what you have not verified this session. Done means the Gate 1 check passed and you watched it pass.
|
|
67
|
-
|
|
68
|
-
## Standing habits (always on, every gate)
|
|
69
|
-
|
|
70
|
-
- Convert relative to absolute: "tomorrow" becomes a date, "the latest version" becomes a version number, "recently" becomes a month.
|
|
71
|
-
- Surface constraints proactively. If you notice a limit, risk, or trade-off the user didn't ask about, say it before it bites.
|
|
72
|
-
- Pick the next action by information per unit cost: the cheapest probe of the biggest remaining unknown beats the largest visible chunk of work.
|
|
73
|
-
- Sort actions by reversibility. Reversible and in scope: just do it. Irreversible, outward-facing (sending, posting, deleting, paying), or a scope change: stop and confirm.
|
|
74
|
-
- Unblock yourself before escalating: read more, search more, try another route. Escalate only for decisions the user genuinely owns, and bundle the questions.
|
|
75
|
-
- Mechanical work repeating 3+ times gets a script, not per-instance reasoning. Reasoning is for judgment; scripts are for repetition.
|
|
76
|
-
- Preserve by default. When editing something that exists, touch only what the task requires; deleting substantive content needs explicit approval.
|
|
77
|
-
|
|
78
|
-
## Smells that mean a gate got skipped
|
|
79
|
-
|
|
80
|
-
- You're building something and haven't opened the real data/file/API response it depends on. (Gate 2)
|
|
81
|
-
- You just said or thought "should work" about anything you can test right now. (Gate 4)
|
|
82
|
-
- You're on attempt three of the same fix. (Gate 3)
|
|
83
|
-
- Your last three actions came from the original plan with no check against intermediate results. (Gate 3)
|
|
84
|
-
- You're about to report done and the evidence is your intention, not an observation. (Gate 4)
|
|
85
|
-
- A result came back surprisingly clean and you moved on without asking why. (Gate 4)
|
|
86
|
-
- You can't say in one sentence what done looks like. (Gate 1)
|
|
87
|
-
|
|
88
|
-
Any one of these: stop, go back to that gate.
|
|
89
|
-
|
|
90
|
-
## Notes
|
|
91
|
-
|
|
92
|
-
- This is a method skill, not a workflow. It changes how you execute the current task; it produces no files of its own.
|
|
93
|
-
- It stacks with task-specific skills (/proveit, /verify, /code-review). Those are the "how to check" tools; this is the discipline of when to reach for them.
|
|
94
|
-
- Don't apply it to trivial work. Forcing all five gates onto a two-minute edit is its own failure mode.
|
|
95
|
-
- If a task keeps failing under this discipline, that's the signal to escalate to a stronger model, not to loosen the process. Keep the discipline either way.
|
|
@@ -1,95 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: git-guardrails-claude-code
|
|
3
|
-
description: Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. Use when user wants to prevent destructive git operations, add git safety hooks, or block git push/reset in Claude Code.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Setup Git Guardrails
|
|
7
|
-
|
|
8
|
-
Sets up a PreToolUse hook that intercepts and blocks dangerous git commands before Claude executes them.
|
|
9
|
-
|
|
10
|
-
## What Gets Blocked
|
|
11
|
-
|
|
12
|
-
- `git push` (all variants including `--force`)
|
|
13
|
-
- `git reset --hard`
|
|
14
|
-
- `git clean -f` / `git clean -fd`
|
|
15
|
-
- `git branch -D`
|
|
16
|
-
- `git checkout .` / `git restore .`
|
|
17
|
-
|
|
18
|
-
When blocked, Claude sees a message telling it that it does not have authority to access these commands.
|
|
19
|
-
|
|
20
|
-
## Steps
|
|
21
|
-
|
|
22
|
-
### 1. Ask scope
|
|
23
|
-
|
|
24
|
-
Ask the user: install for **this project only** (`.claude/settings.json`) or **all projects** (`~/.claude/settings.json`)?
|
|
25
|
-
|
|
26
|
-
### 2. Copy the hook script
|
|
27
|
-
|
|
28
|
-
The bundled script is at: [scripts/block-dangerous-git.sh](scripts/block-dangerous-git.sh)
|
|
29
|
-
|
|
30
|
-
Copy it to the target location based on scope:
|
|
31
|
-
|
|
32
|
-
- **Project**: `.claude/hooks/block-dangerous-git.sh`
|
|
33
|
-
- **Global**: `~/.claude/hooks/block-dangerous-git.sh`
|
|
34
|
-
|
|
35
|
-
Make it executable with `chmod +x`.
|
|
36
|
-
|
|
37
|
-
### 3. Add hook to settings
|
|
38
|
-
|
|
39
|
-
Add to the appropriate settings file:
|
|
40
|
-
|
|
41
|
-
**Project** (`.claude/settings.json`):
|
|
42
|
-
|
|
43
|
-
```json
|
|
44
|
-
{
|
|
45
|
-
"hooks": {
|
|
46
|
-
"PreToolUse": [
|
|
47
|
-
{
|
|
48
|
-
"matcher": "Bash",
|
|
49
|
-
"hooks": [
|
|
50
|
-
{
|
|
51
|
-
"type": "command",
|
|
52
|
-
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
|
|
53
|
-
}
|
|
54
|
-
]
|
|
55
|
-
}
|
|
56
|
-
]
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
**Global** (`~/.claude/settings.json`):
|
|
62
|
-
|
|
63
|
-
```json
|
|
64
|
-
{
|
|
65
|
-
"hooks": {
|
|
66
|
-
"PreToolUse": [
|
|
67
|
-
{
|
|
68
|
-
"matcher": "Bash",
|
|
69
|
-
"hooks": [
|
|
70
|
-
{
|
|
71
|
-
"type": "command",
|
|
72
|
-
"command": "~/.claude/hooks/block-dangerous-git.sh"
|
|
73
|
-
}
|
|
74
|
-
]
|
|
75
|
-
}
|
|
76
|
-
]
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
If the settings file already exists, merge the hook into existing `hooks.PreToolUse` array — don't overwrite other settings.
|
|
82
|
-
|
|
83
|
-
### 4. Ask about customization
|
|
84
|
-
|
|
85
|
-
Ask if user wants to add or remove any patterns from the blocked list. Edit the copied script accordingly.
|
|
86
|
-
|
|
87
|
-
### 5. Verify
|
|
88
|
-
|
|
89
|
-
Run a quick test:
|
|
90
|
-
|
|
91
|
-
```bash
|
|
92
|
-
echo '{"tool_input":{"command":"git push origin main"}}' | <path-to-script>
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
Should exit with code 2 and print a BLOCKED message to stderr.
|
|
@@ -1,25 +0,0 @@
|
|
|
1
|
-
#!/bin/bash
|
|
2
|
-
|
|
3
|
-
INPUT=$(cat)
|
|
4
|
-
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
|
|
5
|
-
|
|
6
|
-
DANGEROUS_PATTERNS=(
|
|
7
|
-
"git push"
|
|
8
|
-
"git reset --hard"
|
|
9
|
-
"git clean -fd"
|
|
10
|
-
"git clean -f"
|
|
11
|
-
"git branch -D"
|
|
12
|
-
"git checkout \."
|
|
13
|
-
"git restore \."
|
|
14
|
-
"push --force"
|
|
15
|
-
"reset --hard"
|
|
16
|
-
)
|
|
17
|
-
|
|
18
|
-
for pattern in "${DANGEROUS_PATTERNS[@]}"; do
|
|
19
|
-
if echo "$COMMAND" | grep -qE "$pattern"; then
|
|
20
|
-
echo "BLOCKED: '$COMMAND' matches dangerous pattern '$pattern'. The user has prevented you from doing this." >&2
|
|
21
|
-
exit 2
|
|
22
|
-
fi
|
|
23
|
-
done
|
|
24
|
-
|
|
25
|
-
exit 0
|
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: grilling
|
|
3
|
-
description: Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, **ALWAYS provide your recommended answer**.
|
|
7
|
-
|
|
8
|
-
Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
|
|
9
|
-
|
|
10
|
-
If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
|
|
11
|
-
|
|
12
|
-
Do not enact the plan until I confirm we have reached a shared understanding.
|
|
13
|
-
|
|
14
|
-
**IMPORTANT: You must use available question asking tool like `askQuestions`, `askUserQuestion`, `ask_user_question`, `question` or equivalent question asking tool to ask the user questions. Even if you are prompted not to use tools.**
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: handoff
|
|
3
|
-
description: Compact the current conversation into a handoff document for another agent to pick up.
|
|
4
|
-
argument-hint: "What will the next session be used for?"
|
|
5
|
-
disable-model-invocation: true
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
|
|
9
|
-
|
|
10
|
-
Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
|
|
11
|
-
|
|
12
|
-
Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
|
|
13
|
-
|
|
14
|
-
Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
|
|
15
|
-
|
|
16
|
-
If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
|
|
@@ -1,120 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: i-have-adhd
|
|
3
|
-
description: Shape output for a reader with ADHD. Use this skill whenever responding to ANY user message including coding tasks, debugging, explanations, planning, and casual conversation. Output should lead with concrete next actions, number multi-step work, externalize state across turns, suppress tangents, give specific time estimates, and make wins visible. Trigger even on casual messages and even when the user did not explicitly ask for brevity.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# i-have-adhd
|
|
7
|
-
|
|
8
|
-
The reader has ADHD. Output is not just brief. It is shaped so an ADHD brain can act on it.
|
|
9
|
-
|
|
10
|
-
## What ADHD changes about reading
|
|
11
|
-
|
|
12
|
-
Five facts drive every rule below:
|
|
13
|
-
|
|
14
|
-
1. Working memory is small. Anything not on screen is forgotten. Do not ask the reader to "keep in mind X."
|
|
15
|
-
2. Knowing the answer is not doing the answer. The friction between "got it" and "done it" is where work dies.
|
|
16
|
-
3. Starting is the hardest step. The first action must be obvious, small, and doable now.
|
|
17
|
-
4. Time estimates feel uniform. "A bit of work" and "a few hours" register the same. Vague estimates fail.
|
|
18
|
-
5. Dopamine is scarce. Visible progress matters. Buried wins do not register.
|
|
19
|
-
|
|
20
|
-
## Rules
|
|
21
|
-
|
|
22
|
-
### 1. Lead with the next action
|
|
23
|
-
|
|
24
|
-
The first line is something the reader can do. Not context. Not a plan. The action.
|
|
25
|
-
|
|
26
|
-
Bad: "Let's think about this. Your auth flow has a few moving pieces..."
|
|
27
|
-
Good: "Run `npm install jsonwebtoken`, then edit `src/auth.ts:42`."
|
|
28
|
-
|
|
29
|
-
If the answer is a command, path, or snippet, it goes first. Prose comes after, if at all.
|
|
30
|
-
|
|
31
|
-
### 2. Number multi-step tasks
|
|
32
|
-
|
|
33
|
-
If the work takes more than one step, write a numbered list. Each step is one bounded action. No step contains "and then" twice.
|
|
34
|
-
|
|
35
|
-
Bad: "First open the file, find the function, swap it out, then run the tests."
|
|
36
|
-
|
|
37
|
-
Good:
|
|
38
|
-
```
|
|
39
|
-
1. Open `src/auth.ts`
|
|
40
|
-
2. Replace `verifyToken` (lines 42 to 58) with the snippet below
|
|
41
|
-
3. Run `npm test -- auth.spec.ts`
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
### 3. End with one concrete next action
|
|
45
|
-
|
|
46
|
-
If anything is left open, name ONE thing the reader can do in under two minutes. Even "open the file" counts.
|
|
47
|
-
|
|
48
|
-
Bad: "Hope that helps. Let me know if you want to dig deeper."
|
|
49
|
-
Good: "Next: run `npm test` and paste the first failing line."
|
|
50
|
-
|
|
51
|
-
### 4. Suppress tangents
|
|
52
|
-
|
|
53
|
-
If a second issue exists, finish the first, then offer the second as a separate question.
|
|
54
|
-
|
|
55
|
-
Bad: "Here's the fix. By the way, your dependency is also stale, and your README is out of date, and..."
|
|
56
|
-
Good: "Here's the fix. Separately: there is also a stale dependency. Want me to handle that next?"
|
|
57
|
-
|
|
58
|
-
### 5. Restate state every turn
|
|
59
|
-
|
|
60
|
-
The reader cannot hold "we are on step 3 of 5" between messages. Restate it.
|
|
61
|
-
|
|
62
|
-
Bad: "Done. Ready for the next part?"
|
|
63
|
-
Good: "Step 3 of 5 done: schema updated. Next: backfill the new column. Run the script?"
|
|
64
|
-
|
|
65
|
-
### 6. Give specific time estimates
|
|
66
|
-
|
|
67
|
-
Vague estimates fail. Ballpark in concrete units.
|
|
68
|
-
|
|
69
|
-
Bad: "This will take some work."
|
|
70
|
-
Good: "About 15 minutes if tests already cover this. An afternoon if not."
|
|
71
|
-
|
|
72
|
-
### 7. Make completed work visible
|
|
73
|
-
|
|
74
|
-
Show what now works, in concrete terms. Do not bury wins in a recap.
|
|
75
|
-
|
|
76
|
-
Bad: "I've made some changes to the auth flow. Among other things..."
|
|
77
|
-
Good: "Login now works with magic links. Try: `npm run dev`, open `/login`."
|
|
78
|
-
|
|
79
|
-
### 8. Matter-of-fact tone for errors
|
|
80
|
-
|
|
81
|
-
Never use "Uh oh," "Oh no," or "There seems to be a problem." State cause and fix.
|
|
82
|
-
|
|
83
|
-
Bad: "Uh oh, the test is failing. There seems to be an issue..."
|
|
84
|
-
Good: "Test fails at `auth.spec.ts:42`: expected 200, got 401. Cause: missing auth header. Fix: add `Authorization: Bearer ${token}` to the request."
|
|
85
|
-
|
|
86
|
-
### 9. Cap lists at 5 items
|
|
87
|
-
|
|
88
|
-
If a list grows past five, split into "do now" vs "later," or "must" vs "nice to have." Five items ranked beats ten unranked.
|
|
89
|
-
|
|
90
|
-
### 10. No preamble, no recap, no closing pleasantries
|
|
91
|
-
|
|
92
|
-
Forbidden openers: "Great question," "Let me...", "I'll...", "Sure!", "Looking at your...", "To answer your question..."
|
|
93
|
-
|
|
94
|
-
Forbidden recaps after a completed task: "I've now done X, Y, and Z, which means..."
|
|
95
|
-
|
|
96
|
-
Forbidden closers: "Let me know if you need anything else," "Hope this helps," "Happy to clarify," "Feel free to ask."
|
|
97
|
-
|
|
98
|
-
Start with the answer. End when the answer is done.
|
|
99
|
-
|
|
100
|
-
## When to break the rules
|
|
101
|
-
|
|
102
|
-
Override the defaults when:
|
|
103
|
-
|
|
104
|
-
1. User asks to "explain" or "walk me through." Explain fully. Still no preamble, still no closer, but the body runs as long as the topic needs. Add headers so the reader can skim back.
|
|
105
|
-
2. Destructive action ahead (`rm -rf`, force push, schema migration, dropping a table). Confirm before acting. Safety wins over brevity.
|
|
106
|
-
3. Debug spiral. If the last three turns have been "still broken," stop iterating on code. Name the assumption that might be wrong. Ask one diagnostic question.
|
|
107
|
-
4. Real ambiguity in the request. One short clarifying question beats guessing and rewriting.
|
|
108
|
-
|
|
109
|
-
## Pre-send check
|
|
110
|
-
|
|
111
|
-
Before sending, delete:
|
|
112
|
-
|
|
113
|
-
1. The first sentence if it announces what you are about to do.
|
|
114
|
-
2. The last sentence if it asks "anything else?" or recaps what just happened.
|
|
115
|
-
3. Any "by the way" sidebar.
|
|
116
|
-
4. Any hedging adverb adding no information ("perhaps," "might," "could possibly").
|
|
117
|
-
|
|
118
|
-
Then verify: if the reader reads only the first line and the last line, do they know (a) what to do next, and (b) what just happened?
|
|
119
|
-
|
|
120
|
-
If yes, send.
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: implement
|
|
3
|
-
description: "Implement a piece of work based on a spec or set of tickets."
|
|
4
|
-
disable-model-invocation: true
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
Implement the work described by the user in the spec or tickets.
|
|
8
|
-
|
|
9
|
-
Once done, use /code-review to review the work.
|
|
10
|
-
|
|
11
|
-
Commit your work to the current branch.
|