dotfile-brainstorm — Claude Code skill for spec-less pipeline design
Turns a vague project idea into a design doc with a Pipeline Configuration section. The doc then feeds dotfile-from-spec, which produces the pipeline DOT file.
npx skills add harperreed/dotfiles --skill dot-file-brainstorm -a claude-codeWhat dotfile-brainstorm does
The skill walks through brainstorming in stages. First it explores the repo context, asks clarifying questions one at a time, and proposes two or three approaches with trade-offs. Then come pipeline-specific questions: build phases, test frameworks, linters, retry counts, and points where work can run in parallel.
The output is a design doc saved to docs/plans/YYYY-MM-DD-<topic>-design.md. Its Pipeline Configuration section captures everything dotfile-from-spec needs. That section is the handoff artifact, not the DOT file itself.
A hard gate blocks DOT generation and any call to dotfile-from-spec until you approve the complete design. Human gates default to off, so the pipeline runs headless; wait.human nodes appear only if you ask for them. The skill insists on this even for simple projects, because a skipped brainstorm is where assumptions start costing time.
What it helps with
- break a loose idea into architecture and components
- fill the Pipeline Configuration block for dotfile-from-spec
- pick test frameworks, linters, and coverage targets
- decide whether the pipeline needs human approval gates
- commit a design doc before any DOT generation
Example prompts for the agent
- Brainstorm my project idea into a design doc for the pipeline
- I have a feature but no spec. Walk me through the dotfile-brainstorm steps
- Ask about build phases, testing, and quality tools, then show the design section by section
How to install dotfile-brainstorm
1Skills CLI (Vercel)
npx skills add harperreed/dotfiles --skill dot-file-brainstorm -a claude-code2Manually: put the files in place
~/.claude/skills/dot-file-brainstorm/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dot-file-brainstorm/
1Skills CLI (Vercel)
npx skills add harperreed/dotfiles --skill dot-file-brainstorm -a codex2Manually: put the files in place
.agents/skills/dot-file-brainstorm/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add harperreed/dotfiles --skill dot-file-brainstorm -a cursor2Manually: put the files in place
.cursor/skills/dot-file-brainstorm/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install harperreed/dotfiles dot-file-brainstorm2Manually: put the files in place
.github/skills/dot-file-brainstorm/SKILL.md1Skills CLI (Vercel)
npx skills add harperreed/dotfiles --skill dot-file-brainstorm -a gemini-cli2Platform CLI
gemini skills install https://github.com/harperreed/dotfiles --path .claude/skills-archive/dot-file-brainstormManually: put the files in place
.devin/skills/dot-file-brainstorm/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add harperreed/dotfiles --skill dot-file-brainstorm -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about dotfile-brainstorm
How do I install dotfile-brainstorm in Claude Code?
Run npx skills add harperreed/dotfiles --skill dot-file-brainstorm -a claude-code. The skill lands at ~/.claude/skills/dot-file-brainstorm/SKILL.md.
What does dotfile-brainstorm do?
It brainstorms a project idea into a design doc with a Pipeline Configuration section. That doc is then handed to dotfile-from-spec, which generates the actual DOT file.
How is this different from a CI/CD pipeline?
This pipeline is a chain of LLM tasks that build software from scratch: plan, scaffold, write tests, implement, verify, commit, review, ship. Nodes carry prompts, not build steps, and human gates are optional.
