dx-new
Skill8 starsChanged 4 months agoMITView on GitHub
Start a new piece of work — creates a change or an effort and points you at the next step.
In this repository21 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- dx-archiveSkill
- dx-brainstormSkill
- dx-diagnoseSkill
- dx-distillSkill
- dx-domain-discoverSkill
- dx-domainSkill
- dx-frameSkill
- dx-implementSkill
- dx-initSkill
- dx-lessonSkill
- dx-planSkill
- dx-refactor-discoverSkill
- dx-referencesSkill
- dx-researchSkill
- dx-reviewSkill
- dx-review-triageSkill
- dx-roadmapSkill
- dx-standards-discoverSkill
- dx-standards-updateSkill
- dx-tddSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Every piece of work starts here.
- Very specific: line 11
Guard: If context/ isn't scaffolded (no changes/ or efforts/), stop and tell the user to run /dx-init.
- Distinctive: line 36
Never nest a change inside a change.
- Very specific: line 57
Stop. Do not chain into another skill.
≈ “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.
Files
dx-new — the entry point and router
Every piece of work starts here. Your one job is to pick the container level, create its identity file, and print the next command. You do not research, frame, or plan — you route.
Guard. If context/ isn't scaffolded (no changes/ or efforts/), stop and tell the user to run /dx-init. Never auto-create the parent tree.
Briefs named in the argument — optional, loose, plural
A brief under context/foundation/briefs/ may be named anywhere in the argument, in any form — a bare slug, a filename, a full path, several of them — with no flag and no fixed position. Those names are settled upstream context, not part of the idea: strip them before deriving a slug. A name that doesn't resolve is never guessed at — list context/foundation/briefs/ and ask which was meant. No brief named is the ordinary case and changes nothing below.
Record the resolved ones as a single prose line in the new container's ## Notes, naming their paths (Briefs: context/foundation/briefs/<slug>.md, …). Nothing is copied and no frontmatter field changes — that line is the pointer dx-frame and dx-plan follow.
Slice of an existing effort — read the id, don't invent one
If invoked as dx-new <effort-id> <slice-n>, this is a child change — a different path from everything below. Read context/efforts/<effort-id>/roadmap.md and find ### Slice <slice-n>: its - change: <slug> line is the id dx-roadmap already assigned, and the slice name is the title. Use them as-is — do not derive a new slug from scratch, that would orphan the roadmap's link. Missing effort or slice → tell the user to run /dx-roadmap <effort-id> first.
Create context/changes/<slug>/change.md with effort: <effort-id>, slice: <slice-n>, status: new. Default type: feature unless effort.md's ## Notes carries the marker line Refactor effort — findings promoted from /dx-refactor-discover. (written once at effort creation — see Promoted entries), then type: refactor; or the marker Candidate effort — default slice type: <type>; promoted from /dx-review <policy-id>. (see Promoted entries), then that <type>. Fill every other frontmatter field the schema defines — invoke dx-references with topic change-md for the exact shape. The child inherits the effort's research/ and frame.md in place (nothing is copied) — its problem framing is already settled, so skip straight to /dx-plan <slug>. Optionally run /dx-frame <slug> first instead: in slice mode it adds only this slice's own ## User cases to a small frame.md of its own, without reopening the inherited framing.
Name it (change or effort, not a slice)
Derive a kebab-case slug from the idea (Add Google sign-in → oauth-login). If foundation/glossary.md exists, read it first and prefer its terms so the id matches the project's language. Reject a slug that collides with an existing change/effort/archive folder — ask for another.
Pick the level
Infer from size and clarity; when it's a coin-flip, ask one question and stop.
- A change is the default. A single shippable unit. Create
context/changes/<id>/change.md. Settype(feature | defect | refactor | migration — default feature),effort: null,slice: null,status: new, plus every other field the schema defines. Invokedx-referenceswith topicchange-mdfor the exact shape. - An effort only when the slices can each ship alone, or run in parallel. "Large" by itself is not a reason; serial work that hardens or extends earlier work is phases of one plan, not slices. An effort produces changes. Create
context/efforts/<id>/effort.mdwith a one-paragraph## Goal,status: new, plus every other field the schema defines. Invokedx-referenceswith topiceffort-mdfor the exact shape.
Never nest a change inside a change. Large work is an effort that spawns flat child changes.
Promoted entries
dx-diagnose, dx-refactor-discover, and dx-brainstorm are separate discovery skills that hand a candidate here. When invoked with a pre-seeded diagnosis.md (bug) or refactor candidate, drop it into the new change's folder as its seed research and set type accordingly (defect / refactor). Don't re-derive what the discovery skill already found. dx-brainstorm creates its own container, so when a brainstorm already ran the bundling test the change-vs-effort level is handed over, not re-derived — you won't be routing that work at all.
Multi-candidate effort seed. An argument opening with the heading ## Refactor opportunities (from /dx-refactor-discover) is dx-refactor-discover's promote-many output — an effort's worth of candidates, not a short idea to slugify. Derive the effort slug via Name it, fed a short descriptor built from the seed's closing Start with: line (e.g. refactor: <top-pick module> + N other modules), not the whole blob. Write context/efforts/<id>/effort.md (topic effort-md) with a one-sentence ## Goal citing that Start with: line, plus the ## Notes marker Refactor effort — findings promoted from /dx-refactor-discover. — written once; this is the fact the slice-creation check above reads. Then write one context/efforts/<id>/research/<topic>.md per numbered candidate: provenance frontmatter (topic, kind: codebase, source — the file(s) from that candidate's "What & where", gathered — today, git_commit — git rev-parse HEAD) and that candidate's entry (title, What & where, Why, Shape, Proposed, Dependency category) verbatim as the body, minus its list numeral — a standalone file has nothing to be numbered against — with its Standard: and Sketch: lines kept verbatim only when the candidate carries them. Slug each topic from the candidate's module/file name, not its deepening verb, collision-checked the same way Name it checks any slug. Any other argument — including a long one — still falls through to Name it / Pick the level unchanged.
Policy candidates seed. An argument opening with a heading of the form ## <Policy> candidates (from /dx-review <policy-id>) is dx-review's Explore-run promote-many output. Handle it like the refactor seed above: effort slug via Name it from the closing Start with: line, a one-sentence ## Goal citing it, the ## Notes marker Candidate effort — default slice type: <type>; promoted from /dx-review <policy-id>. (<type> from the seed's Type: <type> line; written once, slice creation reads it), and one research/<topic>.md per numbered entry with the same provenance frontmatter (kind: codebase, source the entry's file(s), gathered, git_commit) and the entry verbatim minus its list numeral, topic slugged from the entry's module/file name.
Done when
The identity file exists with every frontmatter field filled (plus any seeded candidate, plus the ## Notes line for any brief named). Print the exact next command and stop — never run it:
Change: Next: /dx-research <id> <topic> → /dx-frame <id> → /dx-plan <id>
(both optional — small/clear work can go straight to /dx-plan <id>)
Effort: Next: /dx-research <id> <topic> → /dx-frame <id> → /dx-roadmap <id>
Child change: Next: /dx-frame <slug> → /dx-plan <slug> (frame optional — adds this slice's own user cases)Stop. Do not chain into another skill. (The next command can run in this same session — no /clear needed.)
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
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.

