brain-spec-skills

Brain Spec Skills for Claude Code

Spec-driven development inside Claude Code. No server, no dependencies -- just 4 slash commands.

What is Brain Spec?

Brain Spec turns Claude Code into a structured development environment. It adds four slash commands that let you plan features through guided interviews, break them into tracked tasks, and maintain a persistent project knowledge base -- all stored as readable JSON and markdown in a .brain-spec/ directory.

Unlike an MCP server, Brain Spec Skills are plain markdown files that Claude Code loads on demand. Zero startup cost, zero dependencies, zero configuration.

The skills use current Claude Code conventions: runtime version detection via ${CLAUDE_SKILL_DIR}, skill-scoped lifecycle hooks, comma-separated allowed-tools allowlists, and a plugin manifest for marketplace installation. Every skill file is checksummed and covered by a CI-run test suite (see the badge above).

How It Works

/brain-init          /brain-spec create      /brain-task create     /brain-status
+-----------+        +----------------+      +----------------+     +-----------+
| Create    |------->| Interview or   |----->| Break into     |---->| View      |
| workspace |        | blank spec     |      | tracked tasks  |     | dashboard |
+-----------+        +----------------+      +----------------+     +-----------+
      |                     |                       |                     |
      v                     v                       v                     v
 .brain-spec/         specs/*.md              tasks/*/tasks.json    Aggregated
 config.json          specs/*.meta.json       tasks/*/logs/*.md     statistics
 steering/*.md

Installation

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/peopleforrester/Brain_spec_skills_claude/main/install.sh | bash

This clones the repo to a temp directory, copies the 4 skill folders into your project's .claude/skills/, and cleans up.

Manual

git clone --depth 1 https://github.com/peopleforrester/Brain_spec_skills_claude.git /tmp/brain-spec-skills
mkdir -p .claude/skills
cp -r /tmp/brain-spec-skills/.claude/skills/brain-* .claude/skills/
rm -rf /tmp/brain-spec-skills

Global install (all projects)

curl -fsSL https://raw.githubusercontent.com/peopleforrester/Brain_spec_skills_claude/main/install.sh | bash -s -- --global

Installs to ~/.claude/skills/ so skills are available in every Claude Code project.

As a Claude Code plugin

Brain Spec ships a plugin manifest, so you can install it through Claude Code's plugin marketplace instead of the install script:

/plugin marketplace add peopleforrester/Brain_spec_skills_claude
/plugin install brain-spec-skills@brain-spec

The first command registers this repo as a marketplace; the second installs the four skills. Updates come through /plugin rather than re-running the install script.

Requires a Claude Code version with plugin marketplace support. The install-script methods above work on every version and need no marketplace.

Verify

ls .claude/skills/brain-*/SKILL.md
# Should list 4 files

Verify Checksums

For security-conscious installs, verify file integrity against published checksums:

curl -fsSL https://raw.githubusercontent.com/peopleforrester/Brain_spec_skills_claude/main/checksums.txt -o /tmp/brain-spec-checksums.txt
sha256sum -c /tmp/brain-spec-checksums.txt --ignore-missing

Quick Start

Open Claude Code in your project
Type /brain-init -- creates the .brain-spec/ workspace, steering docs, and optionally a CLAUDE.md
Type /brain-spec create User Authentication -- starts a guided interview that builds a structured spec
Type /brain-task create user-authentication "Implement login form" -- adds a tracked task
Type /brain-status -- see your dashboard with specs, tasks, and progress bars

Skills

Skill	Command	Purpose
brain-init	`/brain-init`	Initialize workspace, create steering docs, generate CLAUDE.md
brain-spec	`/brain-spec <sub>`	Spec lifecycle: `create`, `interview`, `list`, `get`, `update`, `delete`, `archive`
brain-task	`/brain-task <sub>`	Task management: `create`, `update`, `list`, `log`, `progress`
brain-status	`/brain-status`	Dashboard overview of all specs and tasks

See Skills Reference for full subcommand documentation.

Version

Check your installed version: