agentleFS
netanelavrnetanelavr/dotcursor/skills/kit-plan/SKILL.md

kit-plan

Skill6 starsChanged 27 days agoMITView on GitHub

Distill the need first (don't-build can stop the work), then align a buildable concept and wait for explicit approval. Use for complex or fuzzy work, including three ticket readings when the ask is ambiguous.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. About 0 are common, 12 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Not grilling a finished design against glossary/ADRs (kit-challenge-design)

    line 15
  2. Very specific:

    Not the living log of a feature already in progress (kit-decisions)

    line 16
  3. Very specific:

    Not choosing the smallest path of an agreed outcome (kit-minimize).

    line 17
  4. Distinctive:

    Not a PRD factory, issue tree, or future-proof architecture pass

    line 18
  5. Very specific:

    If they already have a spec to stress-test → kit-challenge-design.

    line 20
  6. Distinctive:

    Ask only if the answer would change at least one of:

    line 39
  7. Distinctive:

    Prefer 2–4 sharp options over serial ping-pong.

    line 48
  8. Distinctive:

    Distill the need: before the readings. The request is a proposed solution, not the mission.

    line 54
  9. Distinctive:

    If still build-shaped, continue.

    line 57
  10. Distinctive:

    If the ask could still be three different tickets:

    line 61
  11. Distinctive:

    Write Read A / B / C — three distinct interpretations (goal, scope, non-goals).

    line 63
  12. Distinctive:

    If you cannot name one shared outcome sentence that all three reads support, you are not ready to plan or code.

    line 69
  13. Very specific:

    Search the repo before proposing new files or layers.

    line 81
  14. Distinctive:

    Stop when further questions no longer change the concept.

    line 82
  15. Distinctive:

    If the concept includes premature architecture, strip it or make the user accept the cost in writing.

    line 93
  16. Distinctive:

    Default output is short:

    line 98
  17. Distinctive:

    Only expand into a written plan/issues when they say to lock it.

    line 108
  18. Very specific:

    Prefer the smallest shape (kit-minimize if the path is still wide).

    line 118

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Plan

Distill the need first. If it still needs a build, reach a shared concept, write a short decision log, and stop. Code only after explicit approval.

You stop plan-mode from inventing the wrong thing, and you stop coding from starting too early.

What this is NOT

  • Not grilling a finished design against glossary/ADRs (kit-challenge-design)
  • Not the living log of a feature already in progress (kit-decisions)
  • Not choosing the smallest path of an agreed outcome (kit-minimize). Don't-build in step 1 ends before an outcome exists.
  • Not a PRD factory, issue tree, or future-proof architecture pass

If they already have a spec to stress-test → kit-challenge-design. Once approved and they want the thinnest diff → kit-minimize.

Effort

Effort = how many consequential forks you open, not how much trivia you ask.

Accept kit-plan light|standard|deep. If omitted, auto-calibrate and say the tier in one line.

TierWhenForks
lightLocal change, existing pattern, clear done0–2
standardFeature-shaped, fuzzy done, crosses a boundary3–7 batched
deepNew nouns, several valid architectures, or repeated misalignmentWalk the real forks

Higher effort means more scope / boundary / correctness / sequencing questions — never more folder or button-copy questions.

Question filter

Ask only if the answer would change at least one of:

  • what we build vs skip
  • system boundary or data model
  • failure mode / correctness bar
  • sequencing (what ships first)
  • whether we are overbuilding for scale

Otherwise default from the codebase and say what you assumed. Prefer 2–4 sharp options over serial ping-pong.

Flow

1. Place the ask

Distill the need before the readings. The request is a proposed solution, not the mission.

  • Literal ask in one line, marked as a proposed solution. Actual need: what must be true when done.
  • Better means: reuse, config, process change, or don't-build. If the need dies or don't-build wins, stop. No plan. Say why in one line.
  • If still build-shaped, continue. Distill is the coarse gate (should this exist at all). Scale-gate in step 3 is the fine gate (is this version overbuilt).

One sentence: local fix, workflow change, or new domain concept.

If the ask could still be three different tickets:

  1. Write Read A / B / C — three distinct interpretations (goal, scope, non-goals). Keep each short.
  2. Compare — shared intent vs divergence.
  3. Confidence
    • High + shared → pick the reading; say why the others lose.
    • Low / unclear → stop. Ask 2–4 targeted questions. Do not invent a direction.

If you cannot name one shared outcome sentence that all three reads support, you are not ready to plan or code. Don’t collapse to one reading before compare.

2. Align the concept

Walk forks in dependency order. Capture as you go:

  • done — one sentence
  • in / out of scope
  • boundaries and interfaces
  • defaults you assumed
  • open risks

Search the repo before proposing new files or layers. Reuse beats invention. If the new layer has a common name (queue, retry, auth), say that name and whether a dependency already covers it (kit-evidence). Stop when further questions no longer change the concept.

3. Scale-gate (always)

Any “yes we need fancy X” needs evidence.

  • What limit are we near, and what proves it?
  • Next order of magnitude, or fantasy scale?
  • Specific problem, or a toolbox for hypothetical futures?
  • Can we defer caches, new frameworks, and broad abstractions?

If the concept includes premature architecture, strip it or make the user accept the cost in writing. Bias: specific > generic, today’s runway > status architecture.

4. Decision log (not a plan)

Default output is short:

  • shared concept (5–10 lines)
  • key decisions
  • assumed defaults
  • scale-gate outcome
  • remaining non-guessables
  • recommended next move (go / lock it / edit a fork)

Do not auto-write a PRD, task tree, or “comprehensive planning document.” Only expand into a written plan/issues when they say to lock it.

5. Wait

Present the log. Ask for approval (go / lock it / numbered edits). Do not implement until they explicitly approve.

6. After approval

Implement only the approved concept. Prefer the smallest shape (kit-minimize if the path is still wide). Once a diff exists and it is fatter than that shape, kit-strip-diff. Prove claims with kit-prove. Do not add extensibility nobody approved.

Do / Don't

DoDon't
"Auto → standard. Two forks: reuse Invoice vs new CreditNote; sync vs async. Rest I default from billing."Forty questions about names, folders, labels
"Scale-gate fail: generic cache with no evidence we are near a limit. Defer."Let sharding / “for later” ride along because it sounds responsible
Decision log, then waitStart coding because the questions slowed down
On light for a null-check: confirm repro + acceptance, ask to goDeep-grill a one-line fix
Three short readings when the ticket is ambiguousCollapse to one story before comparing

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.