A structured workflow framework for Claude Code. Brings opinionated, repeatable workflows to AI-assisted software development — with plans, phases, multi-agent reviews, session persistence, and automated quality gates.

• Prerequisites
• Installation
• Project Setup
• Workflow Guide
• Skill Reference
• Hook Reference
• Agent Reference
• Configuration
• Troubleshooting

Tip: Use project-scope MCP configuration where possible to avoid loading unused MCPs globally.

git clone https://github.com/janark147/zebracode ~/zebracode
cd ~/zebracode
./install.sh

Copy framework files to your Claude Code config directory:

# Skills
cp -r skills/ ~/.claude/skills/

# Agents
cp -r agents/ ~/.claude/agents/

# Hooks
cp -r hooks/ ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# Templates
cp -r templates/ ~/.claude/templates/

# Status line
cp statusline.sh ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

# Global instructions (review before overwriting — may contain your own customizations)
# cp CLAUDE.md ~/.claude/CLAUDE.md
# cp RULES.md ~/.claude/RULES.md

Then merge the hooks configuration from settings.json.example into your ~/.claude/settings.json. See Configuration for the full hooks config.

After installing ZebraCode globally, initialize it for each project:

cd /path/to/your/project
/z-project-init

This runs an interactive questionnaire that:

1. Auto-detects your stack (language, framework, test runner, formatter)
2. Asks about issue tracker, git conventions, and tooling preferences
3. Creates .claude/z-project-config.yml with your answers
4. Creates .claude/.gitignore (ignores .local/ ephemeral state)

The config file is committed to git so all team members share the same ZebraCode configuration.

Key principle: Run /clear between each skill invocation. Context is preserved via plan files, session files, and git history — not the conversation window.

All hooks are shell scripts in ~/.claude/hooks/. They're wired via ~/.claude/settings.json.

• Hooks receive context via JSON on stdin (not command-line arguments)
• Parse with jq: e.g., jq -r '.tool_input.file_path' or jq -r '.tool_input.command'
• Exit code 2 = block the action (PreToolUse, Stop only)
• Exit code 0 = allow / success
• Stdout from hooks is injected into the conversation context

ZebraCode includes 10 custom agent definitions for multi-agent workflows.

All agents use read-only tools (Read, Grep, Glob) — they cannot modify files. Only the main Claude Code session makes changes.

Created by /z-project-init in your project's .claude/ directory. Key sections:

project:
  name: "my-project"

git:
  target_branch: "main"
  branch_prefix: "feature/"

issue_tracker:
  type: "github"          # github | jira | linear | none

stack:
  language: "typescript"
  framework: "nextjs"
  frontend: "react"
  test_runner_backend: "jest"
  formatter: "prettier"

commands:
  test_backend: "npm test"
  lint: "npm run lint"
  format: "npx prettier --write"
  typecheck: "npx tsc --noEmit"

protected_files:           # Blocked by file protection hook
  - ".env*"
  - "package-lock.json"

dangerous_commands:        # Blocked by destructive command hook
  # seed_fresh: "artisan db:seed --force"

• ~/.claude/CLAUDE.md: Framework behavior rules (plan usage, verification, debugging)
• ~/.claude/RULES.md: Actionable operational rules (task management, file safety, agent access)

The settings.json.example file contains the complete hooks configuration. Key settings:

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: Enables multi-agent workflows
• includeCoAuthoredBy: false: Prevents AI co-author attribution in commits
• alwaysThinkingEnabled: true: Extended thinking for complex reasoning

~/.claude/
├── CLAUDE.md              # Global instructions
├── RULES.md               # Operational rules
├── settings.json          # Hooks + settings
├── skills/                # 20 skill directories (SKILL.md + references/)
├── agents/                # 10 agent definitions
├── hooks/                 # 8 hook scripts
├── templates/             # Config templates
└── statusline.sh          # Status bar script

{project}/.claude/
├── z-project-config.yml   # Stack + tool config (committed)
├── project-patterns.md    # Accumulated patterns (committed)
├── plans/                 # Plan files — like ADRs (committed)
├── .gitignore             # Contains: .local/
└── .local/                # Ephemeral state (gitignored)
    ├── {branch}-session.md
    ├── {branch}-debug.md
    └── {branch}-compact-state.md

• Verify skill files exist: ls ~/.claude/skills/*/SKILL.md
• Each skill must be in its own directory: skills/{name}/SKILL.md
• Front-matter must be valid YAML between --- delimiters

• Check ~/.claude/settings.json has the hooks section (compare with settings.json.example)
• Verify scripts are executable: chmod +x ~/.claude/hooks/*.sh
• Test hooks manually: echo '{"tool_input":{"file_path":".env"}}' | ~/.claude/hooks/block-protected-files.sh
• Check jq is installed: which jq

• Ensure stack.formatter is set in z-project-config.yml
• Ensure commands.format is set (e.g., npx prettier --write)
• The formatter must be installed in the project (npm install)

• Skills like /z-pause require you to be on a feature branch, not main/master
• Run /z-start first to create/checkout the feature branch

• Check protected_files patterns in z-project-config.yml
• Patterns use glob matching (e.g., .env* matches .env, .env.local, .env.production)
• To edit a protected file intentionally, temporarily remove it from the config

• This is expected — context is preserved via files, not conversation history
• Plan files in .claude/plans/ track all progress
• Run /z-resume if you previously ran /z-pause
• The SessionStart hook shows current workflow state automatically

• /z-review spawns up to 6 agents — this takes time
• Ensure CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set to "1" in settings.json env
• If agents fail to spawn, check Claude Code version supports agent teams

Apache 2.0