Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (headchef) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

headchef

Scaffold AI IDE configs, agents, and skills for 10 code editors in one command.

npx headchef create my-project

Supported IDEs

IDE	Key	Config
Claude Code	`claude`	`CLAUDE.md`, `.claude/agents/`, `.claude/commands/`
OpenAI Codex	`codex`	`.codex/config.toml`
Cursor	`cursor`	`.cursor/rules/`
Windsurf	`windsurf`	`.windsurf/rules/`
Google Antigravity	`antigravity`	`GEMINI.md`, `.agent/skills/`
GitHub Copilot	`copilot`	`.github/copilot-instructions.md`
Cline / Roo Code	`cline`	`.clinerules`, `.roo/rules/`
JetBrains AI	`jetbrains`	`.aiassistant/rules/`
Augment Code	`augment`	`.augment/rules/`
AGENTS.md	`agentsmd`	`AGENTS.md`

Install

# Run directly (no install)
npx headchef create my-project

# Or install globally
npm install -g headchef

Commands

`headchef create [name]`

Create a new project directory with AI IDE configs, agents, and project scaffolding.

headchef create my-app
headchef create my-app --framework flutter
headchef create my-app --only claude cursor
headchef create --no-brain              # skip brain integration

Interactive mode prompts for project name, IDE selection, framework, agent categories, and Obsidian brain path.

`headchef init`

Add AI IDE configs to an existing project.

headchef init
headchef init --framework nextjs
headchef init --only claude cursor windsurf
headchef init --target ./other-project

`headchef list`

Show all available IDEs, frameworks, and agent categories with counts.

Options

Flag	Description
`--only <ides...>`	Generate only for specified IDEs
`--exclude <ides...>`	Skip specified IDEs
`--framework <name>`	Apply framework-specific rules
`--force`	Overwrite existing files
`--dry-run`	Preview without writing
`--no-interactive`	Skip prompts, use all IDEs
`--no-brain`	Skip Obsidian brain integration
`--target <dir>`	Target directory (`init` only)

Frameworks

Framework	Key	Highlights
General	`general`	SOLID, clean code, naming, testing, security
Flutter	`flutter`	Dart, BLoC, Freezed, GetIt, Firebase
Next.js	`nextjs`	RSC, App Router, Shadcn UI, Zod
React	`react`	Hooks, functional components, Testing Library
Python	`python`	PEP 8, type hints, pytest, FastAPI

Agents

headchef ships 55+ agents across 10 categories. Select which categories to include during setup.

Category	Agents	Examples
Core	6	Orchestrator, Code Reviewer, Test Writer, Bug Debugger, Architecture Planner, Docs Keeper
Engineering	7	Frontend Developer, Backend Architect, AI Engineer, DevOps Automator, Mobile App Builder
Design	7	UI Designer, UX Researcher, Brand Guardian, Visual Storyteller
Marketing	8	Growth Hacker, Content Creator, TikTok Strategist, App Store Optimizer
Product	3	Sprint Prioritizer, Trend Researcher, Feedback Synthesizer
Project Management	5	Studio Producer, Project Shepherd, Senior Project Manager
Testing	7	Evidence Collector, Reality Checker, Performance Benchmarker, API Tester
Support	6	Support Responder, Analytics Reporter, Legal Compliance Checker
Spatial Computing	6	XR Developer, Vision Pro Specialist, WebXR Engineer
Specialized	6	Data Analytics Reporter, LSP Engineer, Agents Orchestrator

Core agents are always included. Other categories are opt-in via interactive prompt.

IDEs that support discrete agent files (Claude Code, Antigravity) get one file per agent. Other IDEs get a condensed agent summary in their rules file.

Skills

15 built-in skills are generated as slash commands for Claude Code (.claude/commands/):

code-review, commit-message, unit-test, regex-generator, security-audit, accessibility-audit, architecture-design, code-converter, prompt-enhancer, diagram-generator, tech-review, sql-terminal, logic-builder, data-visualizer, domain-name-generator

Brain Integration

headchef optionally integrates with an Obsidian vault for project documentation:

Creates a project directory in {brainPath}/Projects/Active/{project}/
Generates an Overview.md in the brain
Symlinks docs/ from the project to the brain directory
Creates docs/plans/ for architecture plans
Generates CHECKLIST.md and CHANGELOG.md

Brain path is saved to ~/.headchefrc after first entry. Use --no-brain to skip.

Generated File Structure

A typical project created with headchef create my-app (Claude + core agents):

my-app/
  CLAUDE.md              # Rules + coding standards + available agents
  CHECKLIST.md           # Task tracking
  CHANGELOG.md           # Change history
  docs/ -> brain/        # Symlink to Obsidian vault (if configured)
    plans/               # Architecture plans
  .claude/
    agents/              # One .md per agent
      headchef-orchestrator.md
      code-reviewer.md
      test-writer.md
      bug-debugger.md
      architecture-planner.md
      docs-keeper.md
    commands/            # One .md per skill
      code-review.md
      commit-message.md
      ...

Collision Handling

By default, existing files are skipped. In interactive mode, a checkbox prompt lets you pick which files to overwrite. Use --force to overwrite everything.

Preferences

headchef saves your selections to ~/.headchefrc so the next run pre-selects your previous choices.

{
  "ides": ["claude", "cursor", "windsurf"],
  "framework": "flutter",
  "agentCategories": ["core", "engineering", "testing"],
  "brainPath": "/path/to/obsidian-vault"
}

Delete ~/.headchefrc to reset. --no-interactive ignores it.

Development

git clone https://github.com/EventuallySolutions/headchef.git
cd headchef
npm install
npm run dev       # watch mode
npm test          # 207 tests
npm run build     # production build

License

MIT