User guide organized by usage order: setup -> execute -> release.

Grabby: Complete Static Guide

Grabby is a CLI-first framework for AI-assisted software development. It converts plain-language requests into structured feature contracts, then runs them through validation, planning, backlog generation, prompt bundling, approval, execution, and post-run audit. This guide follows the main path: use your preferred LLM service and run Grabby locally for predictable, reviewable, repeatable delivery.

Grabby icon

Quick Start Navigation

Use this path for first-time onboarding.

1. SetupInstall Grabby and initialize your repo. 2. Claude ContractPrompt Claude to generate your contract draft. 3. Grabby GatesValidate, plan, approve, execute, audit. 4. ReleaseFollow development -> main release process.

Main Workflow: Prompt Claude First

Primary path for this repo: create the contract draft in Claude, then enforce delivery with Grabby.

1
Prompt Claude to draft the contract
You are helping me create a Grabby feature contract.

Request: <describe the feature request here>

Output requirements:
- Return a complete feature contract markdown.
- Include clear scope, non-goals, directories, files, dependencies, testing, and done-when criteria.
- Keep the contract implementation-ready and bounded.

Use filename: contracts/<request-slug>.fc.md
2
Save contract locally
# Save Claude output into:
# contracts/<request-slug>.fc.md
3
Run Grabby governance gates
grabby validate contracts/<request-slug>.fc.md
grabby plan contracts/<request-slug>.fc.md
grabby approve contracts/<request-slug>.fc.md
Good vs Bad Claude prompt

Good: clear scope, strict output format, explicit constraints.

Create a Grabby feature contract for this request:
"Add login regression tests for redirect edge cases."

Output only valid contract markdown for:
contracts/login-redirect-regression.fc.md

Requirements:
- Include objective, scope, non-goals, directories, files table, dependencies, testing, and done-when.
- Keep scope bounded to tests and related auth redirect logic.
- Do not propose broad refactors or unrelated enhancements.

Bad: vague request with no boundaries or expected structure.

Make a contract for login.

Setup (Highest Priority)

Supported LLM services: ChatGPT, Claude, Gemini, Copilot, or any equivalent provider. Grabby is provider-agnostic and runs locally in your repo.
1
Use your existing LLM service
# Keep using your preferred LLM client/service.
# Grabby runs locally in your repo to enforce workflow and governance.
2
Install Grabby CLI (standard user path)
npm install -g grabby
grabby --help
3
Initialize your repo
cd your-project
grabby init
grabby init-hooks
4
Run setup baseline if prompted
grabby setup --quick
# or manual baseline flow
# grabby validate SETUP-BASELINE.fc.md
# grabby plan SETUP-BASELINE.fc.md
# grabby approve SETUP-BASELINE.fc.md
# grabby complete-baseline SETUP-BASELINE
Contributor/developer install from source 
git clone https://github.com/Raccoon-King/ai-feature-contracts.git
cd ai-feature-contracts
npm install
npm link
grabby --help
Offline / airgapped install 
# connected machine
npm ci
npm pack

# airgapped machine
npm install -g ./grabby-2.0.0.tgz
grabby --help

First Day Plan (User-Focused)

A
Create first contract in Claude
# Use the Claude template above to generate:
# contracts/login-flow-regression.fc.md
B
Pass governance gates
grabby validate contracts/<ID>.fc.md
grabby plan contracts/<ID>.fc.md
grabby approve contracts/<ID>.fc.md
C
Execute + verify
grabby execute contracts/<ID>.fc.md
grabby session contracts/<ID>.fc.md --check
grabby audit contracts/<ID>.fc.md

Feature Validation Source

Guide coverage verified against local feature history artifacts:
.grabby/features.index.json, .grabby/history/history-001.yaml, .grabby/history/history-002.yaml.

Snapshot timestamp: 2026-03-08T18:27:14.976Z. Archived feature count: 126.

Coverage Areas

Core + Setup Task/Ticket/Orchestrate Agent Workflow Feature Lifecycle Validation + Audit Git Safety Git + Release Policy

Daily Workflow

Default path for most work requests.

A
Contract Draft via Claude
# Prompt Claude with the template above.
# Save output as contracts/<request-slug>.fc.md
B
Contract Gate
grabby validate contracts/<ID>.fc.md
grabby plan contracts/<ID>.fc.md
grabby approve contracts/<ID>.fc.md
C
Execute + Verify
grabby execute contracts/<ID>.fc.md
grabby session contracts/<ID>.fc.md --check
grabby audit contracts/<ID>.fc.md
D
Close Feature
grabby feature:close <id>
grabby features:refresh

Command Explorer (LLM-First Surfaces)

Agents + Persona Routing

Ari -> Archie -> Val -> Sage -> Dev -> Tess -> Iris, with Flash for quick bounded paths and Conductor for orchestration.

grabby agent list
grabby agent architect
grabby orchestrate "request"
grabby party
grabby workflow <name>

Governance and Safety Gates

Rule: do not bypass validate/plan/approve gates before execute.
grabby context:lint
grabby policy:check
grabby guard contracts/<ID>.fc.md
grabby session --check-all

Git + Release Process

Current repo policy: merge normal work to development; release through main.

1
Normal development
git checkout development
git pull origin development
# feature branch from development
# PR target: development
2
Release sync
git checkout main
git merge --ff-only development
$env:GRABBY_RELEASE="1"; git push origin main
3
Tag release (from main)
git tag -a vX.Y.Z -m "release"
git push origin vX.Y.Z
Release tag pre-push gate

Tag push is blocked if contracts/ contains active .fc.md files.

Troubleshooting

"Bootstrap gate active"

Complete setup baseline flow or run grabby setup --quick.

"Execution blocked"

Run validate -> plan -> approve for the target contract before execute.

Hooks not applying

Reinstall hooks: grabby init-hooks.

Coverage or generated files are noisy

Do not PR generated local noise unless intentional. Re-check with git status before committing.

Interactive Checklist

0 / 5 complete