Shai-Hulud is an opinionated, structured vibe-coding starter kit for Claude Code and GitHub Copilot. It replaces blind prompting with a layered context architecture, specialist AI agents, reusable commands, and a battle-tested development workflow — so your AI pair-programmer actually understands what you're building.

Why Shai-Hulud?

Most vibe-coding sessions start with a blank prompt and end with spaghetti. Shai-Hulud gives your AI assistant memory, structure, and purpose from the first keystroke:

• Shared Context Layer — Your PRD, architecture, security rules, and dependencies live in one place. Both Claude and Copilot read them automatically.
• Specialist Agents — The Bene Gesserit handles documents, planning, and project setup. The Mentat analyzes architecture, reviews backlogs, and identifies tech debt. Each has sub-specialists for precise routing.
• Session Commands — Start with /gogogo, end with /wrapup. Every session is structured, trackable, and resumable.
• Prompt Engineering Built In — Craft prompts using the R.G.C.O.A. framework. Research prompts, improve prompts, build new ones — all via slash commands.
• Local-First Issue Tracking — Uses beads (bd) for CLI-based issue tracking that works offline and integrates with both tools.

Stop prompting into the void. Start vibe-coding with structure.

The Architecture of Arrakis

Both tools read the same shared context. Each has its own native command format that references the knowledge below.

Quick Start

Prerequisites

• Node.js ≥ 18
• beads installed: npm install -g @beads/bd
• A git repository initialized

Install

npx shai-hulud

For Claude Code

1. Copy this kit into your project root
2. Open in Claude Code
3. Run /bootstrap
4. Follow the setup wizard — the Bene Gesserit will guide you

For GitHub Copilot

1. Copy this kit into your project root
2. Open in VS Code with Copilot
3. Use the bootstrap prompt in Copilot Chat
4. Follow the setup wizard

Project Structure

shai-hulud/
├── CLAUDE.md                    # Claude Code master hub
├── AGENTS.md                    # Copilot/OpenAI agents hub
├── context/                     # ── The Desert Floor ──
│   ├── prd.md                   #   Product requirements
│   ├── workflow.md              #   Development workflow (beads)
│   ├── infra.md                 #   Infrastructure & coding standards
│   ├── security.md              #   Security blueprint
│   ├── sbom.md                  #   Approved dependencies
│   ├── tests.md                 #   Testing strategy
│   └── changelog.md             #   Version history
├── agents/                      # ── The Orders ──
│   ├── bene-gesserit/           #   Planning, docs, project setup
│   └── mentat/                  #   Architecture & backlog analysis
├── .claude/commands/            #   Slash commands (Claude Code)
├── .github/prompts/             #   Reusable prompts (Copilot)
├── setup/                       #   Bootstrap & conversion prompts
├── docs/                        #   Guides & references
└── examples/                    #   Starter templates (CLI, web app)

Commands & Prompts

Every command works in both tools. Claude Code uses slash commands; Copilot uses prompt files.

Command	Claude	Copilot	What It Does
Session start	/gogogo	gogogo	Load context, check git, surface available work
Session end	/wrapup	wrapup	Commit, update issues, create handoff notes
Add features	/story	story	Add user stories to the PRD
New project	/bootstrap	bootstrap	Initialize the full starter kit
Existing project	/convert	convert	Add the kit to an existing codebase
Build prompt	/create-prompt	create-prompt	Craft prompts via R.G.C.O.A. framework
Research prompt	/create-research-prompt	create-research-prompt	Build deep-research prompts
Improve prompt	/improve-prompt	improve-prompt	Refine and strengthen existing prompts
Bene Gesserit	/bene-gesserit	bene-gesserit	Document creation & planning agent
Mentat	/mentat	mentat	Architecture & backlog review agent
Status line	/setup-statusline	Claude only	Terminal token/context usage display

The Agent Orders

Two specialist agent systems give your AI deeper capabilities beyond basic chat.

Workflow — Riding the Maker

This project uses beads (bd) for local-first issue tracking:

bd create "Feature title" --type feature    # Plant a thumper
bd list --status open                       # Survey the desert
bd ready                                    # See what's unblocked
bd update <id> --status in_progress         # Mount the worm
bd close <id>                               # Harvest the spice

See docs/workflow-guide.md for the full workflow.

What's in the Box?

Document	Description
Setup — Claude Code	Claude Code installation & configuration
Setup — GitHub Copilot	GitHub Copilot installation & configuration
Workflow Guide	Development workflow with beads
Agent Guide	Bene Gesserit & Mentat systems in depth
Command Reference	Complete command & prompt reference
Statusline Guide	Context status line setup (Claude)

Who Is This For?

• Solo devs who want their AI to actually understand the project, not just autocomplete
• Teams adopting vibe coding and need shared structure across Claude & Copilot
• Anyone tired of re-explaining context every session and getting inconsistent output
• Builders who want opinionated defaults they can customize, not a blank canvas

Design Philosophy

1. Context is king — AI without context is just a fancy autocomplete. The context/ layer gives your assistant persistent, shared project memory.
2. Opinionated by default, flexible by design — Strong defaults (Conventional Commits, beads, conflict resolution matrix) that you can override.
3. Dual-tool native — CLAUDE.md and AGENTS.md each serve their tool idiomatically. No awkward adapter layers.
4. Agents over prompts — The Bene Gesserit and Mentat systems route complex work to specialists, not generic chat.
5. Local-first — beads tracks issues in your repo. No external services required.

License

MIT