# What is Gangsta Agents? Gangsta Agents is an **AI agentic skills framework** for spec-driven development. It provides a structured protocol — organized around the mafia family metaphor — that turns chaotic AI-assisted coding into disciplined, repeatable operations. ::callout{icon="i-lucide-lightbulb" type="info"} **The core idea:** Before you write a single line of code, you write a spec. Before you execute, you plan. The Heist Pipeline ensures every feature goes through reconnaissance, debate, and approval before implementation begins. :: ## The 1% Rule The framework's single most important behavioral rule: ::callout{icon="i-lucide-shield" type="warning"} If there's even a **1% chance** a Gangsta Agents skill applies to what you're doing, you **must** invoke it. No rationalizing your way around the framework. :: This means no skipping steps, no deciding "this is too simple for a Heist," and no going straight to code. The framework exists because undisciplined AI agents produce unreliable output — the skills enforce the discipline that produces reliable results. [Read the full 1% Rule →](https://gangsta.page/getting-started/the-1-percent-rule) ## The Heist Pipeline Every feature development cycle in Gangsta Agents is called a **Heist** — a 6-phase operational process: ::pipeline-flow 1. **Reconnaissance** — Intel gathering, codebase exploration, requirement analysis 2. **The Grilling** — Adversarial debate between proposer and devil's advocate 3. **The Sit-Down** — Spec drafting (no code allowed) 4. **Resource Development** — Task decomposition, infrastructure prep 5. **Execution** — Parallel implementation by Workers 6. **The Delivery** — Verification, integration, Ledger update Each phase has a **gate** — the Don (you) must approve before moving to the next phase. No auto-advancing. No skipping. [Explore the full Heist Pipeline →](https://gangsta.page/heist-pipeline) ## 20 Skills, 5 Platforms Gangsta Agents provides **20 skills** across three categories: | Category | Skills | Purpose | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | **Hierarchy Roles** | `the-consigliere`, `the-underboss`, `the-capo`, `the-ledger`, `omerta` | Organization and governance | | **Heist Phases** | `reconnaissance`, `the-grilling`, `the-sit-down`, `resource-development`, `the-hit`, `laundering` | Structured development cycles | | **Dev Skills** | `interrogation-debugging`, `drill-tdd`, `safehouse-worktrees`, `audit-review`, `receiving-orders`, `sweep-verification`, `exit-strategy` | Tactical development tools | These skills run on **5 platforms**: - **Claude Code** — Original target, full skill support - **OpenCode** — Plugin-based integration - **Codex** — Skills directory symlink - **Gemini CLI** — Extension-based install - **Cursor** — Follows Claude Code conventions [Install Gangsta Agents →](https://gangsta.page/getting-started/installation) ## Spec-Driven Development At its core, Gangsta Agents enforces **Spec-Driven Development**: :::callout{icon="i-lucide-scroll" type="info"} **Spec is Law.** Code that contradicts the spec means the spec needs revision — not the other way around. Never write code without a spec. ::: This isn't just a preference — it's Omerta Law #5. The Heist Pipeline is specifically designed to produce specs before code, debate specs before committing, and verify code against specs before delivery. [Learn about Omerta Laws →](https://gangsta.page/core-concepts/omerta) ## New to the Terminology? Gangsta Agents uses mafia metaphors throughout — Dons, Crew Leads, Omerta, The Delivery, and more. If you're unfamiliar with these terms, the glossary covers every one: [Glossary →](https://gangsta.page/glossary) :: # Installation Gangsta Agents is a skills framework — it doesn't run as a standalone application. Instead, you install it into your AI coding tool so the agent can invoke skills automatically. Choose your platform below. ::callout{icon="i-lucide-package" type="info"} **What you're installing:** A collection of Markdown-based skill files that tell your AI agent when and how to use structured development processes. No runtime dependencies, no build step, no package manager required. :: ## Prerequisites - Git - An AI coding tool: Claude Code, GitHub Copilot, OpenCode, Codex, Gemini CLI, or Cursor - A project directory where you want to use Gangsta Agents ## Install for Your Platform ### Claude Code Run these two slash commands inside Claude Code: ::code-group ```bash [1. Add marketplace] /plugin marketplace add kucherenko/gangsta ``` ```bash [2. Install plugin] /plugin install gangsta@gangsta ``` :: That's it — Claude Code will fetch and register all Gangsta Agents skills automatically. Start a new session to activate them. --- ### GitHub Copilot Run these two slash commands inside GitHub Copilot: ::code-group ```bash [1. Add marketplace] copilot plugin marketplace add kucherenko/gangsta ``` ```bash [2. Install plugin] copilot plugin install gangsta@gangsta-marketplace ``` :: That's it — GitHub Copilot will fetch and register all Gangsta Agents skills automatically. Start a new session to activate them. --- ### OpenCode Tell OpenCode in a new session: ```text [Prompt OpenCode] Fetch and follow instructions from https://raw.githubusercontent.com/kucherenko/gangsta/refs/heads/master/.opencode/INSTALL.md ``` That's it — OpenCode will clone the repo, configure the plugin, and set up the skills path automatically. **Prefer a manual install?** ::code-group ```bash [1. Clone] git clone https://github.com/kucherenko/gangsta.git ~/.gangsta ``` ```json [2. opencode.json] { "plugin": ["gangsta@file:///Users/you/.gangsta"], "skills": { "paths": ["~/.gangsta/skills"] } } ``` :: Replace `/Users/you/.gangsta` with your actual clone path. The `~` shorthand works in `skills.paths`. Restart OpenCode after saving. --- ### Codex Tell Codex in a new session: ```text [Prompt Codex] Fetch and follow instructions from https://raw.githubusercontent.com/kucherenko/gangsta/refs/heads/master/.codex/INSTALL.md ``` **Prefer a manual install?** ::code-group ```bash [Manual install] git clone https://github.com/kucherenko/gangsta.git ~/.gangsta mkdir -p ~/.agents/skills ln -sf ~/.gangsta/skills ~/.agents/skills/gangsta ``` :: Restart Codex — skills are discovered automatically from `SKILL.md` frontmatter. --- ### Gemini CLI ```bash gemini extensions install https://github.com/kucherenko/gangsta ``` This handles cloning, path configuration, and registration automatically. --- ### Cursor Cursor doesn't have a native Gangsta Agents plugin yet. Use the `skills` utility to install all skills directly: ```bash npx skills add https://github.com/kucherenko/gangsta ``` This installs the full Gangsta Agents skill set into your agent's skills directory. Once done, start a new Cursor session and prompt your agent: ```text Use gangsta and build new feature ``` Cursor will pick up the skills and invoke the right ones for the task. ::callout{icon="i-lucide-info" type="info"} `npx skills add` is also an alternative installation method for any platform listed above, if you prefer a single-command setup over platform-specific steps. :: --- ## Verify Installation After installing, start a **new session** with your AI tool and test with this prompt: ::callout{icon="i-lucide-check-circle" type="success"} **Verification prompt:** Start a new session and say: > "I want to build a new feature" The agent should **automatically invoke** `gangsta:reconnaissance` and begin gathering intel about your codebase and requirements. If it does, installation is successful. :: If the agent doesn't invoke the skill: 1. Check that the skills path is correctly configured 2. Ensure you're starting a **fresh session** (skills are loaded at session start) 3. Verify the `skills/` directory contains `.md` files (not nested too deep) ## Updating To update Gangsta Agents skills to the latest version: ::code-group ```bash [All Platforms] cd ~/.gangsta git pull origin master ``` ```bash [Gemini CLI] gemini extensions update gangsta ``` :: ::callout{icon="i-lucide-refresh-cw" type="warning"} Always update before starting a new Heist. Skill definitions evolve, and using the latest version ensures you have the most current process definitions. :: ## Troubleshooting | Issue | Solution | | -------------------------------- | --------------------------------------------------------------------- | | Agent doesn't invoke skills | Check skills path configuration; restart session | | Skills appear but produce errors | Verify skill files are `.md` format, not corrupted | | Partial skill invocation | Ensure the entire `skills/` directory is linked, not individual files | | Gemini CLI extension not found | Ensure `gemini extensions install` completed without errors | | Claude Code plugin not found | Ensure marketplace was added before running `/plugin install` | | GitHub Copilot plugin not found | Ensure marketplace was added before running `copilot plugin install` | # Quickstart — Your First Heist This guide walks you through a complete Heist cycle — the Gangsta Agents way to build a feature. By the end, you'll understand how the 6 phases work together and why structured development beats ad-hoc coding. ::callout{icon="i-lucide-rocket" type="info"} **Before you start:** Make sure you've [installed Gangsta Agents](https://gangsta.page/getting-started/installation) and verified the installation works. :: ## Step 1: Express Your Intent Start a fresh session with your AI tool and tell it what you want to build: > "I want to add a user authentication system to my app" That's it. The **1% Rule** kicks in automatically — the agent recognizes this as a "build something new" intent and invokes `gangsta:reconnaissance`. ## Step 2: Reconnaissance The agent deploys its intel-gathering skills: - Scans your codebase for existing patterns, dependencies, and architecture - Identifies relevant files, conventions, and constraints - Produces a **Dossier** — a structured report of findings - Asks you to **approve the Dossier** before proceeding ::callout{icon="i-lucide-shield" type="warning"} **Phase Gate:** You must approve the Dossier. If the intel is incomplete, ask for more reconnaissance before moving on. :: ## Step 3: The Grilling The agent runs an **adversarial debate** — a Proposer argues for the best approach while a Devil's Advocate challenges every assumption. This surfaces edge cases, risks, and trade-offs you might miss in a single-pass design. Output: **Grilling Conclusions** documenting the winning approach and rejected alternatives. ## Step 4: The Sit-Down Now the agent drafts the **Contract** — a formal specification document: - What will be built (scope) - What won't be built (out of scope) - Acceptance criteria - Architectural decisions - Applicable constitution rules ::callout{icon="i-lucide-ban" type="danger"} **No code allowed.** The Sit-Down is purely about specification. If any code appears, the phase must restart. :: You review and **sign the Contract** — this is the law that governs all subsequent implementation. ## Step 5: Resource Development The agent decomposes the Contract into an **Execution Plan**: - Breaks work into parallel task packages - Assigns territories (domains of responsibility) - Allocates resources and subagents - Identifies dependencies between tasks You approve the Execution Plan, and implementation begins. ## Step 6: Execution Workers implement the Execution Plan in parallel: - Each worker implements their assigned tasks - Test-Driven Development (`gangsta:drill-tdd`) enforces Red-Green-Refactor - Budgets are tracked per task - Code respects the Contract — deviations require a spec revision ## Step 7: The Delivery The Consigliere reviews all deliverables: - Code review against the Contract - Integration testing - The Ledger is updated with insights and fails - Production-ready code is delivered ::callout{icon="i-lucide-check-circle" type="success"} **Phase Gate:** You declare the Heist complete. The feature is spec'd, built, verified, and documented. :: ## The Full Pipeline Here's what your first Heist looks like end-to-end: | Phase | Skill | You Do | Output | | -------------- | ------------------------------ | ---------------------- | ---------------- | | Reconnaissance | `gangsta:reconnaissance` | Approve Dossier | Intel report | | The Grilling | `gangsta:the-grilling` | Approve Consensus | Design decisions | | The Sit-Down | `gangsta:the-sit-down` | Sign Contract | Specification | | Resource Dev | `gangsta:resource-development` | Approve Execution Plan | Task breakdown | | Execution | `gangsta:the-hit` | Approve Completion | Working code | | The Delivery | `gangsta:laundering` | Declare Complete | Clean delivery | ::callout{icon="i-lucide-external-link" type="info"} **Deep dive:** Read the full Heist Pipeline documentation for detailed checklists, gate conditions, and phase-specific processes. :: [Continue to the Heist Pipeline →](https://gangsta.page/heist-pipeline) # The 1% Rule The 1% Rule is the single most important rule in Gangsta Agents. It's the behavioral contract that makes the entire framework work: ::callout{icon="i-lucide-shield" type="danger"} **If there is even a 1% chance that a Gangsta Agents skill applies to what you are doing, you MUST invoke it.** This is not negotiable. This is not optional. You cannot rationalize your way out of it. :: ## Why the 1% Rule Exists Without the 1% Rule, AI agents default to ad-hoc behavior: - They jump straight to code without specs - They skip planning and start implementing - They ignore edge cases because "it's simple" - They produce inconsistent results across sessions The 1% Rule enforces discipline. It ensures every task, no matter how small, goes through the appropriate structured process. This produces reliable, repeatable outcomes. ## How It Works When you (the Don) express an intent, the agent evaluates whether any Gangsta Agents skill could apply. Even a slight possibility triggers invocation: | Your Action | Skill Triggered | Why | | ------------------------------- | --------------------------------- | --------------------------------- | | "I want to build a new feature" | `gangsta:reconnaissance` | New build = start a Heist | | "Fix this bug" | `gangsta:the-consigliere` | Bug = need diagnosis first | | "This code isn't working" | `gangsta:interrogation-debugging` | Debugging = systematic root-cause | | "Continue where we left off" | Check `docs/gangsta/` | Resuming = read checkpoints | | "Review this PR" | `gangsta:audit-review` | Review = structured assessment | ## Common Rationalizations (and Why They Fail) The framework explicitly calls out the rationalizations agents use to skip skills: | Rationalization | Reality | | ----------------------------------- | --------------------------------------------------------------------- | | "This is just a simple task" | Simple tasks become complex. Check for skills. | | "I'll just write the code directly" | Code without a spec is a shadow hotfix. | | "The Don wants it fast" | Speed without structure produces garbage. The Heist IS the fast path. | | "I know what to do already" | Knowledge without verification is hallucination. | | "This doesn't need a full Heist" | The Don decides what needs a Heist. Ask, don't assume. | ## The Skill Check Protocol Before every action, the agent runs this mental checklist: 1. **Could `gangsta:reconnaissance` apply?** — Am I building something new? 2. **Could `gangsta:the-consigliere` apply?** — Am I diagnosing or reviewing? 3. **Could `gangsta:interrogation-debugging` apply?** — Am I debugging a problem? 4. **Could `gangsta:drill-tdd` apply?** — Am I writing implementation code? 5. **Could `gangsta:the-hit` apply?** — Am I in an active Heist execution phase? 6. **Could any other skill apply?** — Check the full skill catalog. If any answer is "maybe" — that's a 1%. **Invoke the skill.** ## Priority Order When multiple skills could apply, the 1% Rule follows a priority order: 1. **Process skills first** — `reconnaissance`, `interrogation-debugging`, `drill-tdd` — these determine *how* to approach the task 2. **Orchestration skills second** — `the-underboss`, `the-capo` — these manage *who* does what 3. **Implementation skills third** — `the-hit`, `resource-development` — these guide *execution* ::callout{icon="i-lucide-lightbulb" type="info"} **Example:** If you say "Build X," the agent first invokes `gangsta:reconnaissance` (process), then during the Execution phase will use `gangsta:drill-tdd` (implementation) for code writing. :: ## Living the Rule The 1% Rule isn't just for AI agents. As the Don, you should: - **Expect structured process** — If your agent jumps to code, redirect it to the appropriate skill - **Approve or reject at every gate** — The Heist only works if you exercise your authority - **Hold the agent accountable** — "Did you check for applicable skills?" is a fair question at any point The 1% Rule is what separates Gangsta Agents-assisted development from undisciplined chat-driven coding. Respect it, and your projects will be spec'd before they're built. # Core Concepts Gangsta Agents is built on six foundational concepts that work together to create disciplined, structured AI-assisted development: 1. **[The Gangsta Agents Family Hierarchy](https://gangsta.page/core-concepts/the-borgata)** — The organizational structure that defines who does what: Don, Consigliere, Underboss, Crew Lead, Worker, and The Ledger. 2. **[The Heist Pipeline](https://gangsta.page/core-concepts/the-heist)** — The 6-phase development cycle that every feature goes through: Reconnaissance → The Grilling → The Sit-Down → Resource Development → Execution → The Delivery. 3. **[Omerta — The Five Laws](https://gangsta.page/core-concepts/omerta)** — The governance rules that prevent chaos: no direct agent-to-agent communication, checkpoint everything, cite sources, track budgets, spec is law. 4. **[Intent Routing](https://gangsta.page/core-concepts/intent-routing)** — How user intent maps to skill invocation. When you say "build this," the framework knows to start a Heist. When you say "debug this," it knows to use interrogation-debugging. 5. **[The Ledger](https://gangsta.page/core-concepts/the-ledger)** — Institutional memory: insights from successes, fails from mistakes, and accumulated constitution rules that persist across sessions. 6. **[Spec-Driven Development](https://gangsta.page/core-concepts/spec-driven-dev)** — The philosophy at the core: spec is law, code is implementation. Never code without a spec. The Heist cycle enforces this. ::callout{icon="i-lucide-map" type="info"} **Start here:** If you're new to Gangsta Agents, read these concepts in order. They build on each other — the hierarchy defines the roles, the pipeline defines the process, the laws govern the process, and the spec philosophy justifies it all. :: # Intent Routing When you speak, the agent analyzes your intent and routes it to the appropriate Gangsta Agents skill. This routing is automatic — powered by the 1% Rule — but understanding the mapping helps you work more effectively. ## Intent → Skill Mapping | User Intent | Action | Skill Invoked | | -------------------------- | ------------------------------ | --------------------------------- | | **Build something new** | Start a Heist | `gangsta:reconnaissance` | | **Fix a bug or issue** | Get diagnosis first | `gangsta:the-consigliere` | | **Debug a problem** | Systematic root-cause analysis | `gangsta:interrogation-debugging` | | **Continue existing work** | Resume from checkpoint | Check `docs/gangsta/` for files | | **Ask a question** | Answer directly | No skill needed | | **Review or audit** | Structured assessment | `gangsta:audit-review` | | **Write tests first** | TDD cycle | `gangsta:drill-tdd` | | **Process feedback** | Rigorous review | `gangsta:receiving-orders` | ## Skill Priority When multiple skills could apply, routing follows this order: 1. **Process skills first** — `reconnaissance`, `interrogation-debugging`, `drill-tdd` - These determine *how* to approach the task - They set up the methodology before any work begins 2. **Orchestration skills second** — `the-underboss`, `the-capo` - These manage *who* does what - They decompose work after the approach is established 3. **Implementation skills third** — `the-hit`, `resource-development` - These guide *execution* - They operate within the structure established by process skills ## Skill Types Skills come in two flavors: ### Rigid Skills Must be followed exactly. Don't adapt away from the discipline. - `gangsta:drill-tdd` — Red-Green-Refactor, no shortcuts - `gangsta:interrogation-debugging` — Systematic root-cause, no guessing - `gangsta:omerta` — Laws apply always, no exceptions ### Flexible Skills Adapt principles to context. The spirit matters more than the letter. - `gangsta:reconnaissance` — Intel gathering adapts to codebase size - `gangsta:the-grilling` — Debate depth adapts to feature complexity ## Common Routing Mistakes ::callout{icon="i-lucide-alert-triangle" type="danger"} **Anti-patterns to avoid:** :: 1. **Skipping reconnaissance** — "I already know the codebase" → You probably don't know it as well as a systematic scan. Invoke `gangsta:reconnaissance`. 2. **Debugging without structure** — "Let me just try changing this line" → Use `gangsta:interrogation-debugging` for systematic root-cause analysis. 3. **Coding without a spec** — "I'll just start implementing" → This violates Omerta Law #5 (Spec is Law). Run a Heist first. 4. **Auto-advancing phases** — "The dossier looks fine, let's keep going" → Every phase gate requires explicit Don approval. No auto-advancing. ## The Flow in Practice ```text User says "I want to add notifications" └── Intent: Build something new └── Skill: gangsta:reconnaissance └── Don approves Dossier └── gangsta:the-grilling └── Don approves Consensus └── gangsta:the-sit-down └── Don signs Contract └── gangsta:resource-development └── Don approves Execution Plan └── gangsta:the-hit (Execution) └── Don approves Completion └── gangsta:laundering (The Delivery) └── Don declares Complete ``` Each arrow represents a phase gate — a point where you must explicitly approve before proceeding. # Omerta — The Five Laws Omerta is the code of silence — and in Gangsta Agents, it's the code of governance. Five laws that prevent the chaos typical of undisciplined AI-assisted development. ::callout{icon="i-lucide-scale" type="warning"} These laws are always active. They're invoked via `gangsta:omerta` and govern every phase of every Heist. :: ## Law 1: The Introduction Rule **No direct agent-to-agent communication.** Agents never talk to each other directly. All communication flows through files — checkpoints, contracts, execution plans. This prevents the "telephone game" problem where messages get distorted through chains of agents. **In practice:** - Workers don't message other Workers - Crew Leads don't message other Crew Leads - All coordination happens through shared files in `docs/gangsta/` ## Law 2: The Rule of Availability **Every state must be checkpointed to files.** No agent holds critical state in memory. Everything is written to disk so any agent can pick up where another left off. This is what makes Heist resumption possible. **In practice:** - Dossiers, Contracts, Execution Plans — all persisted as files - Checkpoints written after every phase - Any new session can reconstruct the full state from files ## Law 3: The Rule of Truth **Every claim must cite its source.** Agents must reference where they found information. No "I think the database uses PostgreSQL" — instead: "The database config in `config/database.yml` line 42 shows PostgreSQL." This prevents hallucination from propagating. **In practice:** - File paths and line numbers for code claims - URLs for documentation claims - "I don't know" is acceptable; guessing is not ## Law 4: The Rule of Budget **Resource budgets are tracked.** Every task allocated to a Worker has a budget — estimated time or token cost. Budgets are tracked during Execution to prevent runaway tasks. If a task exceeds its budget, it must request an extension. **In practice:** - Execution Plans include budget estimates per task - Workers report budget consumption during execution - Over-budget tasks raise a flag for Don review ## Law 5: Spec is Law **If code contradicts the spec, revise the spec — not the code.** This is the philosophical foundation. The Contract (spec) is the authoritative source of truth. If implementation reveals a spec issue, the spec is formally revised. Code is never the primary artifact — the spec is. **In practice:** - The Sit-Down produces the Contract - Execution implements the Contract - Deviations require a Contract amendment, not a code-first approach - This ensures consistency and auditability ## Why These Laws Matter Without Omerta, AI-assisted development degenerates: | Problem | Law That Prevents It | | --------------------------------- | -------------------- | | Agents contradict each other | Introduction Rule | | Lost context across sessions | Rule of Availability | | Hallucinated facts propagated | Rule of Truth | | Runaway tasks consuming resources | Rule of Budget | | Code drifting from requirements | Spec is Law | These laws aren't bureaucratic overhead — they're the guardrails that make AI-assisted development reliable and repeatable. # Spec-Driven Development **Spec is Law.** This is Omerta Law #5 and the philosophical foundation of Gangsta Agents. ::callout{icon="i-lucide-scroll" type="warning"} Code that contradicts the spec means the spec needs revision — not the other way around. Never write code without a spec. :: ## The Problem Spec-Driven Development Solves Traditional AI-assisted development follows a dangerous pattern: 1. User describes what they want 2. AI agent starts writing code immediately 3. Code grows organically without a plan 4. Edge cases are discovered late (or never) 5. Requirements drift as implementation evolves 6. The final product doesn't match what was intended Sound familiar? This is **shadow development** — code written without specification, driven by implementation convenience rather than intentional design. ## The Spec-Driven Alternative Gangsta Agents enforces spec-driven development through the Heist Pipeline: | Phase | What Happens | Code Allowed? | | -------------------- | ---------------------------------- | -------------------- | | Reconnaissance | Gather intel, understand context | ❌ No | | The Grilling | Debate approaches, surface risks | ❌ No | | The Sit-Down | Write the specification (Contract) | ❌ **Absolutely not** | | Resource Development | Plan tasks and allocate work | ❌ No | | Execution | Implement the spec | ✅ Yes | | The Delivery | Verify against the spec | ❌ Only review | Notice that **code is only written during one phase** — Execution. And by that point, you have: - A Dossier that proves you understand the codebase - Grilling Conclusions that show you've debated alternatives - A signed Contract that defines exactly what will be built - An Execution Plan that breaks the work into manageable tasks ## The Contract: Source of Truth The Contract produced during The Sit-Down is the authoritative document. It includes: - **Objective** — What's being built and why - **Requirements** — Functional and non-functional - **Architectural Decisions** — Key design choices and rationale - **Grilling Conclusions** — What was debated and decided - **Applicable Rules** — Which constitution rules apply - **Acceptance Criteria** — How to verify success - **Out of Scope** — What's explicitly not being built If during Execution, a developer discovers the spec is wrong, the correct process is: 1. **Stop implementation** 2. **Revise the Contract** (with Don approval) 3. **Then resume implementation** This is not bureaucracy — it's discipline. Every spec revision is tracked and intentional. ## Spec vs. Code Priority | Scenario | Correct Action | | -------------------------------------------------- | --------------------------------------------- | | Code works but contradicts spec | Revise the spec, then align the code | | Spec says X, but implementation reveals X is wrong | Revise the spec first, then fix the code | | Developer "knows better" than the spec | Follow the spec; propose a revision if needed | | Edge case not covered by spec | Add it to the spec, then implement | ## The Heist Cycle Enforces This The Heist Pipeline is structured specifically to prevent code-first development: ::callout{icon="i-lucide-ban" type="danger"} The Sit-Down (Phase 3) has an explicit rule: **NO CODE ALLOWED.** If any code appears during spec drafting, the phase must restart. This is non-negotiable. :: By the time code is written (Execution), there's no ambiguity about what to build. The spec was debated (The Grilling), documented (The Sit-Down), and decomposed (Resource Development). The implementation phase is purely execution — no design decisions, no architectural debates, no scope creep. ## Benefits - **Predictable outcomes** — The spec defines success before code is written - **Auditability** — Every design decision is documented with rationale - **No scope creep** — The Contract defines what's in scope and what's not - **Consistent quality** — TDD during Execution ensures code meets the spec - **Team alignment** — Everyone works from the same specification # The Gangsta Agents Family Hierarchy Gangsta Agents organizes AI agent roles around the Gangsta Agents Family — a structured hierarchy where each role has specific responsibilities and authority levels. You (the user) are always the Don. ::hierarchy-tree ## The Roles ### Don (You) The supreme authority. You approve every phase gate, sign every Contract, and declare every Heist complete. The framework never auto-advances without your explicit approval. - **Authority:** Final decision on all matters - **Responsibility:** Approve dossiers, sign contracts, approve execution plans, declare heists complete - **Invokes:** Any skill, at any time - **Rule:** Your word is law. When instructions conflict, Don's explicit instructions override everything. ### Consigliere The strategic advisor. Outside the chain of command — provides impartial architectural guidance, security review, and code auditing. - **Invocation:** `gangsta:the-consigliere` - **Authority:** Advisory only — no direct command power - **Responsibility:** Architectural review, security analysis, impartial assessment - **Used for:** Bug diagnosis, code review, architecture decisions ### Underboss The Chief Operating Officer. Handles task decomposition, resource allocation, and planning. Dispatches work to Crew Leads and Workers. - **Invocation:** `gangsta:the-underboss` - **Authority:** Task assignment and decomposition - **Responsibility:** Break Contracts into work packages, assign territories, manage dependencies - **Used for:** Resource Development phase, complex multi-task coordination ### Crew Lead The domain crew lead. Each Crew Lead owns a territory (a domain of the codebase) and orchestrates work within it. - **Invocation:** `gangsta:the-capo` - **Authority:** Per-territory orchestration - **Responsibility:** Coordinate workers within a territory, enforce local quality standards - **Used for:** Multi-file changes within a domain, territory-specific execution ### Worker (Subagent) The executor. Stateless subagents that implement assigned tasks. They follow instructions, write code, and run tests. - **Authority:** None — executes assigned tasks only - **Responsibility:** Implement code per the Contract and Execution Plan - **Used for:** The Execution phase — parallel code implementation with TDD ### Associate (External Tool) External tools and API proxies. Not part of the hierarchy — they provide services that Workers and Crew Leads use. - **Examples:** GitHub API, database clients, CI/CD systems - **Used for:** Any external service interaction ### The Ledger Institutional memory. Not a role but a record — persists insights, fails, and constitution rules across sessions. - **Invocation:** `gangsta:the-ledger` - **Location:** `docs/gangsta/` in your project - **Contains:** Insights (successful patterns), Fails (documented mistakes), Constitution (accumulated rules) ## Chain of Command The hierarchy enforces a strict chain of command: ```text Don (You) ├── Consigliere (Advisory) ├── Underboss (Operations) │ ├── Crew Lead (gangsta:the-capo) │ │ └── Workers (Execution) │ └── Associates (External) └── The Ledger (Memory) ``` This ensures: - **No rogue workers** — Workers only execute assigned tasks - **No skipped gates** — Every phase requires Don approval - **No lost knowledge** — The Ledger persists across sessions - **No architectural drift** — The Consigliere keeps the big picture [Learn about The Ledger →](https://gangsta.page/core-concepts/the-ledger) :: # The Heist Pipeline Every feature development cycle in Gangsta Agents is called a **Heist** — a structured 6-phase process that ensures specs are written before code, designs are debated before committing, and results are verified before delivery. ::pipeline-flow{vertical} ## The Six Phases ### 1. Reconnaissance **Skill:** `gangsta:reconnaissance` Gather intel. The agent deploys associates to explore the codebase, identify patterns, find dependencies, and understand requirements. The output is a **Dossier** — a structured intelligence report. **Gate:** Don approves the Dossier. [Reconnaissance deep dive →](https://gangsta.page/heist-pipeline/reconnaissance) ### 2. The Grilling **Skill:** `gangsta:the-grilling` Adversarial debate. A Proposer argues for the best approach while a Devil's Advocate challenges every assumption. This surfaces edge cases, risks, and trade-offs that single-perspective design misses. The output is **Grilling Conclusions**. **Gate:** Don approves the consensus. [The Grilling deep dive →](https://gangsta.page/heist-pipeline/the-grilling) ### 3. The Sit-Down **Skill:** `gangsta:the-sit-down` Spec drafting. No code is allowed during this phase — only specification. The Contract defines scope, out-of-scope, acceptance criteria, architectural decisions, and applicable rules. The output is a **signed Contract**. **Gate:** Don signs the Contract. [The Sit-Down deep dive →](https://gangsta.page/heist-pipeline/the-sit-down) ### 4. Resource Development **Skill:** `gangsta:resource-development` Task decomposition. The Contract is broken into parallel work packages, territories are assigned to Crew Leads, and resources are allocated. The output is an **Execution Plan**. **Gate:** Don approves the Execution Plan. [Resource Development deep dive →](https://gangsta.page/heist-pipeline/resource-development) ### 5. Execution **Skill:** `gangsta:the-hit` Parallel implementation. Workers implement their assigned tasks, using TDD (`gangsta:drill-tdd`) for each work package. Budgets are tracked. The output is **implemented code with budget reports**. **Gate:** Don approves completion. [Execution deep dive →](https://gangsta.page/heist-pipeline/the-hit) ### 6. The Delivery **Skill:** `gangsta:laundering` Verification and integration. The Consigliere reviews all deliverables against the Contract. The Ledger is updated with insights and fails. The output is **clean, production-ready code**. **Gate:** Don declares the Heist complete. [The Delivery deep dive →](https://gangsta.page/heist-pipeline/laundering) ## Phase Gates Every phase ends with a gate — a checkpoint that requires the Don's explicit approval. This is non-negotiable: :::callout{icon="i-lucide-shield" type="warning"} **No auto-advancing.** The framework never moves to the next phase without your approval. If you're unsure, ask for more information. If the output is incomplete, reject it and ask for revisions. ::: ## Starting a Heist To start a Heist, simply express a building intention in your AI tool: > "I want to build a new feature" The agent will invoke `gangsta:reconnaissance` automatically (the 1% Rule ensures this). From there, each phase flows into the next — with your approval at every gate. ## Resuming a Heist If a session is interrupted, the next session can resume from the last checkpoint: 1. Check `docs/gangsta/` for checkpoint files 2. Read the latest checkpoint 3. Present the resume context to the Don 4. Continue from the phase where you left off [Checkpoint Recovery →](https://gangsta.page/advanced/checkpoint-recovery) :: # The Ledger The Ledger is Gangsta Agents' institutional memory. It persists across sessions, ensuring that lessons learned aren't lost when your AI session ends. ::callout{icon="i-lucide-book-open" type="info"} **Invocation:** `gangsta:the-ledger` **Location:** `docs/gangsta/` in your project root :: ## What the Ledger Contains ### Insights Successful patterns, non-obvious approaches, and domain knowledge worth preserving. **Examples:** - "The payment gateway requires idempotency keys for all POST requests" - "React Query's `useSuspenseQuery` works better than `useQuery` for this project's SSR setup" - "The database migration system doesn't support column renames — always add + remove instead" ### Fails Documented mistakes — approaches that caused rework, confusion, or wasted effort. **Examples:** - "Don't use `any` in TypeScript configs — it bypasses the type checker in ways that aren't obvious" - "The external API rate-limits to 100 req/min, not 1000 as the docs claim" - "Running tests in parallel on this project causes flaky failures due to shared database state" ### Constitution Accumulated rules that the team has agreed upon — project-specific extensions of Omerta. **Examples:** - "All database queries must use the QueryBuilder, never raw SQL" - "Feature flags must be in the `config/features.yml` file, not hardcoded" - "Every PR must include a test for the happy path and at least one error path" ## File Structure The Ledger lives in your project at `docs/gangsta/`: ```text docs/gangsta/ ├── insights/ │ └── 2026-04-15-payment-idempotency.md ├── fails/ │ └── 2026-04-10-parallel-test-flakiness.md ├── constitution/ │ └── rules.md └── {heist-name}/ ├── checkpoints/ │ ├── 01-reconnaissance.md │ ├── 02-the-grilling.md │ └── ... ├── recon/ │ └── 2026-04-15-recon-dossier.md ├── specs/ │ └── 2026-04-15-contract.md └── plans/ └── 2026-04-15-execution-plan.md ``` ## When to Write to the Ledger The Ledger is updated during two key moments: ### During The Delivery The final Heist phase (`gangsta:laundering`) includes a Ledger update step. The Consigliere reviews what worked, what failed, and what rules should be added to the constitution. ### During Conversations After any significant exchange outside a Heist — if the Don shares domain knowledge or if an approach is discovered that's worth preserving — offer to write a Ledger entry: ::callout{icon="i-lucide-pen-line" type="info"} **Protocol:** After the exchange resolves, ask once: *"Worth saving to the Ledger as an insight or fail?"* - If yes: write the entry using the Ledger format - If no: drop it — never ask again for the same topic in the same session - Never write a Ledger entry without explicit Don approval :: ## Proactive Memory Capture Gangsta Agents encourages proactive memory capture: | Situation | Action | | --------------------------------- | ---------------------------- | | Non-obvious approach discovered | Offer to save as **Insight** | | Don shares domain knowledge | Offer to save as **Insight** | | Creative solution to a constraint | Offer to save as **Insight** | | Don rejects an approach | Offer to save as **Fail** | | Approach causes rework | Offer to save as **Fail** | | Repeated mistake pattern | Offer to save as **Fail** | ## Why the Ledger Matters Without institutional memory, every session starts from zero. The Ledger ensures: - **Insights compound** — Successful patterns are reused, not rediscovered - **Fails aren't repeated** — Documented mistakes prevent future waste - **Constitution grows** — Project-specific rules accumulate over time - **New sessions are informed** — Any agent can read `docs/gangsta/` and understand the project's history # Reconnaissance **Phase 1 of the Heist Pipeline** Gather intelligence before any design or code begins. The agent deploys associates to explore the codebase, identify patterns, find dependencies, and understand requirements. **Skill:** `gangsta:reconnaissance`**Skill type:** Flexible — adapt principles to context ::callout{icon="i-lucide-eye" type="info"} **Purpose:** Understand what exists before deciding what to build. Reconnaissance produces the intel that every subsequent phase depends on. :: ## Process 1. **Deploy associates** — The agent sends subagents to explore different parts of the codebase 2. **Scan architecture** — Identify tech stack, directory structure, patterns, and conventions 3. **Map dependencies** — Find existing modules, APIs, and services that relate to the feature 4. **Identify constraints** — Document technical limitations, performance requirements, and security considerations 5. **Gather requirements** — Understand what you (the Don) actually want, not just what was said 6. **Produce the Dossier** — Compile findings into a structured intelligence report ## Output: The Dossier The Dossier is a structured document containing: - **Codebase Overview** — Architecture, tech stack, existing patterns - **Dependencies Identified** — Related modules, APIs, services - **Constraints** — Technical limitations, performance requirements - **Risks and Unknowns** — What needs further investigation - **Recommended Scope** — What reconnaissance suggests the feature should cover ## Phase Gate ::phase-gate{title="GATE: Dossier Approved"} The Don must review and approve the Dossier before proceeding to The Grilling. If intel is incomplete, request additional reconnaissance. Only approve when confident the intel is sufficient. :: ## Dossier File Reconnaissance produces the dossier at: ```text docs/gangsta/{heist-name}/recon/{date}-recon-dossier.md ``` This file is read by The Grilling phase and serves as the factual foundation for all subsequent design decisions. ## Autonomous Mode In Autonomous Mode (started via `/gangsta:heist`), the Don Proxy approves the Dossier once it's produced and auto-advances to The Grilling. The Heist halts if the Don Proxy detects a Constitutional Floor violation or material incompleteness. [Full Autonomous Mode docs →](https://gangsta.page/advanced/autonomous-mode) ## Checklist Before Proceeding - Codebase thoroughly scanned - All dependencies identified and documented - Technical constraints documented - Risks and unknowns surfaced - Dossier reviewed and approved by Don [Next: The Grilling →](https://gangsta.page/heist-pipeline/the-grilling) # The Grilling **Phase 2 of the Heist Pipeline** Adversarial brainstorming — a structured debate between a Proposer and a Devil's Advocate to surface risks, edge cases, and trade-offs that single-perspective design misses. **Skill:** `gangsta:the-grilling`**Skill type:** Flexible — debate depth adapts to feature complexity ::callout{icon="i-lucide-flame" type="info"} **Purpose:** Challenge assumptions before committing to a design. It's better to find weaknesses through debate than through production failures. :: ## Process The Grilling uses multi-agent debate: 1. **Proposer presents** — One agent argues for the best approach based on the Dossier 2. **Devil's Advocate challenges** — Another agent attacks every assumption, identifies risks, and proposes alternatives 3. **Multiple rounds** — The debate continues through several rounds until positions stabilize 4. **Consensus formation** — Areas of agreement and disagreement are documented 5. **Produce Grilling Conclusions** — Formal documentation of the outcome ## Output: Grilling Conclusions The Grilling Conclusions document contains: - **Key Decisions** — What was agreed upon and why - **Rejected Alternatives** — Approaches considered and rejected, with reasoning - **Unresolved Objections** — Disagreements that couldn't be settled (escalated to Don) - **Risk Assessment** — Identified risks with severity and mitigation strategies ## Phase Gate ::phase-gate{title="GATE: Consensus Approved"} The Don must review and approve the Grilling Conclusions before proceeding. If you disagree with key decisions, request additional debate rounds or override as the Don. Only approve when confident in the design direction. :: ## Grilling File The Grilling produces conclusions at: ```text docs/gangsta/{heist-name}/specs/{date}-contract.md ``` The conclusions are incorporated into the Contract during The Sit-Down. ## Autonomous Mode In Autonomous Mode (started via `/gangsta:heist`), the Don Proxy approves each Grilling round and the final consensus, then auto-advances to The Sit-Down. The Heist halts if consensus bakes in a Constitutional Floor violation. [Full Autonomous Mode docs →](https://gangsta.page/advanced/autonomous-mode) ## Checklist Before Proceeding - All major design approaches debated - Risks identified and documented - Alternatives considered and either accepted or rejected with reasoning - Unresolved objections escalated to Don - Consensus approved by Don [Previous: Reconnaissance ←](https://gangsta.page/heist-pipeline/reconnaissance) | [Next: The Sit-Down →](https://gangsta.page/heist-pipeline/the-sit-down) # The Sit-Down **Phase 3 of the Heist Pipeline** Draft the formal specification — the Contract. This is the most critical phase. **No code is allowed.** If any code appears during The Sit-Down, the phase must restart. **Skill:** `gangsta:the-sit-down`**Skill type:** Rigid — the "no code" rule is non-negotiable ::callout{icon="i-lucide-ban" type="danger"} **No code allowed during The Sit-Down.** This phase produces a specification, not an implementation. If code appears, restart the phase. :: ## Process 1. **Review the Dossier** — Ground the spec in verified intel from Reconnaissance 2. **Incorporate Grilling Conclusions** — Include the design decisions from The Grilling 3. **Draft the Contract** — Write the formal specification document 4. **Review for completeness** — Ensure scope, out-of-scope, acceptance criteria, and rules are all present 5. **Present for signature** — The Don reviews and signs the Contract ## Output: The Contract The Contract is the authoritative source of truth for the entire Heist. It includes: - **Objective** — What's being built and why - **Requirements** — Functional and non-functional requirements - **Architectural Decisions** — Key design choices and their rationale - **Grilling Conclusions** — Debated decisions and rejected alternatives - **Applicable Constitution Rules** — Project-specific rules that apply - **Acceptance Criteria** — How success is verified - **Out of Scope** — What's explicitly not being built - **Open Risks** — Known risks with severity and mitigation ## Phase Gate ::phase-gate{title="GATE: Contract Signed"} The Don must review and sign the Contract before proceeding. Verify every requirement is testable, scope matches expectations, out-of-scope items are listed, and acceptance criteria are clear. Only sign when confident the Contract is complete and correct. :: ## Contract File The Sit-Down produces the Contract at: ```text docs/gangsta/{heist-name}/specs/{date}-contract.md ``` This file is referenced during The Hit when verifying that implementation matches specification. ## Spec is Law The Contract is governed by Omerta Law #5: ::callout{icon="i-lucide-scroll" type="info"} **If code contradicts the Contract, revise the Contract — not the code.** The spec is the source of truth. During The Hit, if implementation reveals a spec issue: 1. Stop implementation 2. Propose a Contract revision 3. Get Don approval for the revision 4. Resume implementation :: ## Autonomous Mode In Autonomous Mode (started via `/gangsta:heist`), The Sit-Down has a **Dual-Veto** gate — both the Consigliere and the Don Proxy must approve. If either rejects, the Heist halts. There is no tie-breaker and no override. On dual approval, the pipeline auto-advances to Resource Development. [Full Autonomous Mode docs →](https://gangsta.page/advanced/autonomous-mode) ## Checklist Before Proceeding - Dossier findings incorporated - Grilling Conclusions incorporated - All requirements are testable - Out-of-scope items explicitly listed - Acceptance criteria are clear and measurable - Open risks documented - Contract reviewed and signed by Don [Previous: The Grilling ←](https://gangsta.page/heist-pipeline/the-grilling) | [Next: Resource Development →](https://gangsta.page/heist-pipeline/resource-development) # Resource Development **Phase 4 of the Heist Pipeline** Decompose the Contract into parallel work packages, assign territories, and create the Execution Plan. This is where the Underboss (COO) organizes the operation. **Skill:** `gangsta:resource-development`**Skill type:** Flexible — decomposition adapts to feature complexity ::callout{icon="i-lucide-diagram" type="info"} **Purpose:** Turn the Contract into an actionable plan. No implementation yet — just planning and allocation. :: ## Process 1. **Analyze the Contract** — Break the specification into discrete work packages 2. **Identify territories** — Group related work into domains (e.g., frontend, backend, database) 3. **Assign work packages** — Map each package to a territory and responsible Crew Lead 4. **Estimate budgets** — Assign resource budgets (time, complexity) to each package 5. **Map dependencies** — Identify which packages must complete before others can start 6. **Produce the Execution Plan** — Compile everything into a structured implementation plan ## Output: The Execution Plan The Execution Plan contains: - **Work Packages** — Discrete tasks with clear deliverables - **Territory Assignments** — Which domain each package belongs to - **Budget Estimates** — Resource budgets per package - **Dependency Map** — Which packages block others - **Execution Order** — Recommended parallel/sequential task ordering - **Risk Mitigations** — How to handle potential blockers ## Phase Gate ::phase-gate{title="GATE: Execution Plan Approved"} The Don must review and approve the Execution Plan before implementation. Verify work packages are appropriately scoped, dependencies are correctly mapped, budget estimates are reasonable, and territory assignments make sense. Only approve when confident the plan is executable. :: ## Execution Plan File Resource Development produces the Execution Plan at: ```text docs/gangsta/{heist-name}/plans/{date}-execution-plan.md ``` ## Parallel vs. Sequential Work The Execution Plan identifies which tasks can run in parallel and which must be sequential: - **Parallel tasks** — No dependencies between them; multiple Workers can work simultaneously - **Sequential tasks** — One must complete before another begins; ordered execution The Underboss optimizes for maximum parallelism while respecting dependency constraints. ## Autonomous Mode In Autonomous Mode (started via `/gangsta:heist`), the Don Proxy approves the Execution Plan once it's produced. `/gangsta:heist` then **exits** — The Hit does NOT auto-start. You must sign with `/gangsta:go` to execute phases 5–6. The Heist halts if the Plan forces a Constitutional Floor violation. [Full Autonomous Mode docs →](https://gangsta.page/advanced/autonomous-mode) ## Checklist Before Proceeding - Contract fully decomposed into work packages - Each package has clear deliverables - Territories assigned to Crew Leads - Budgets estimated for all packages - Dependencies mapped correctly - Execution Plan reviewed and approved by Don [Previous: The Sit-Down ←](https://gangsta.page/heist-pipeline/the-sit-down) | [Next: Execution →](https://gangsta.page/heist-pipeline/the-hit) # Execution **Phase 5 of the Heist Pipeline** Implementation. Workers implement the Execution Plan, writing code that fulfills the Contract. Each task follows Test-Driven Development within its budget. **Skill:** `gangsta:the-hit`**Skill type:** Rigid — TDD discipline and budget tracking are non-negotiable ::callout{icon="i-lucide-crosshair" type="info"} **Purpose:** Implement the Contract. Code is written here — and only here in the Heist Pipeline. :: ## Process 1. **Assign Workers** — The Underboss dispatches work packages to Worker subagents 2. **TDD per package** — Each Worker follows `gangsta:drill-tdd` (Red-Green-Refactor) 3. **Respect budgets** — Track resource consumption against estimated budgets 4. **Implement per Contract** — Code matches the specification, not the other way around 5. **Report completion** — Workers submit completed work for review 6. **Collect budget reports** — Document actual resource consumption vs. estimates ## Test-Driven Development During Execution, all implementation follows the Red-Green-Refactor cycle: 1. **Red** — Write a failing test that defines the desired behavior 2. **Green** — Write the minimum code to make the test pass 3. **Refactor** — Improve the code while keeping all tests green ::callout{icon="i-lucide-test-tubes" type="warning"} **No code without a test.** Every feature, every fix, every change starts with a test. This isn't a preference — it's the drill ( `gangsta:drill-tdd` ). :: ## Budget Tracking Each work package has a budget estimated during Resource Development. During Execution: - **Within budget** — Task completed within estimate ✅ - **Over budget** — Task consumed more resources than estimated ⚠️ - **Flagged** — Over-budget tasks must report to the Don for review ## Spec Deviations If implementation reveals that the Contract is wrong: ::callout{icon="i-lucide-file-warning" type="danger"} **Don't just change the code.** Omerta Law #5: Spec is Law. If the code contradicts the spec: 1. **Stop implementation** 2. **Propose a Contract revision** (with reasoning) 3. **Get Don approval** for the revision 4. **Resume implementation** under the revised spec :: This ensures every design change is intentional and tracked — not accidental drift. ## Output Execution produces: - **Implemented code** — Fulfilling the Contract - **Test suite** — Proving the implementation works - **Budget report** — Actual vs. estimated resource consumption - **Spec deviations** — Any Contract revisions that were needed ## Phase Gate ::phase-gate{title="GATE: Completion Approved"} The Don must review all deliverables. Verify code matches the Contract, all tests pass, budget reports are reviewed for over-budget items, and any spec deviations are documented. Only approve when all tasks are complete and verified. :: ## Autonomous Mode In Autonomous Mode (started via `/gangsta:heist`), The Hit executes after you sign the Contract with `/gangsta:go`. The key difference: the Don Proxy only intervenes at Worker-failure mini-Grilling. If a mini-Grilling occurs during Execution, it produces a **deviation report only** — the signed Contract remains byte-identical before and after. Contract amendment requires a fresh Sit-Down. Execution auto-advances to Laundering when all Work Packages report complete. [Full Autonomous Mode docs →](https://gangsta.page/advanced/autonomous-mode) ## Checklist Before Proceeding - All work packages implemented - All tests passing (Red-Green-Refactor followed) - Code matches Contract (no unauthorized spec deviations) - Budget reports submitted - Any spec deviations documented and approved - Don approves completion [Previous: Resource Development ←](https://gangsta.page/heist-pipeline/resource-development) | [Next: The Delivery →](https://gangsta.page/heist-pipeline/laundering) # The Delivery **Phase 6 of the Heist Pipeline** Verification and integration. The Consigliere reviews all deliverables against the Contract, the code is integrated, and The Ledger is updated with insights and fails. The output is clean, production-ready code. **Skill:** `gangsta:laundering`**Skill type:** Flexible — verification adapts to project complexity ::callout{icon="i-lucide-check-circle" type="info"} **Purpose:** Ensure the final product matches the Contract, is properly integrated, and that lessons learned are preserved for future Heists. :: ## Process 1. **Consigliere review** — Architectural advisor reviews all code against the Contract 2. **Integration testing** — Verify all components work together correctly 3. **Acceptance verification** — Check each acceptance criterion from the Contract 4. **Ledger update** — Record insights (what worked) and fails (what didn't) 5. **Constitution amendments** — Propose new rules based on lessons learned 6. **Final delivery** — Clean, verified, production-ready code ## Consigliere Review The Consigliere (`gangsta:the-consigliere`) provides an impartial architectural review: - **Code quality** — Does the implementation follow established patterns? - **Security** — Are there vulnerabilities or security concerns? - **Performance** — Are there bottlenecks or inefficiencies? - **Contract compliance** — Does the code match the signed specification? - **Test coverage** — Are edge cases covered? ## Ledger Update This is when institutional memory is captured: ### Insights - Successful patterns that should be reused - Non-obvious approaches that worked well - Domain knowledge the Don shared during the Heist ### Fails - Approaches that caused rework or confusion - Mistakes that should not be repeated - Process inefficiencies discovered ### Constitution - New rules proposed based on this Heist's experience - Amendments to existing rules - Project-specific conventions to formalize ## Output: Clean Delivery The final output of a Heist is: - **Production-ready code** — Verified against the Contract - **Complete test suite** — Proving all acceptance criteria are met - **Updated Ledger** — Insights, fails, and constitution amendments - **Heist archive** — Complete documentation in `docs/gangsta/` ## Phase Gate ::phase-gate{title="GATE: Heist Complete"} The Don verifies all acceptance criteria are met, the Consigliere review is satisfactory, the Ledger has been updated, and integration tests pass. The Don declares the Heist complete — the final stamp of approval that the feature is delivered. :: ## Autonomous Mode In Autonomous Mode (started via `/gangsta:heist`), Laundering runs with the Don Proxy approving the final declaration. Ledger entries are written with `signed-by: don-proxy` and `status: pending-don-confirmation`. The `/gangsta:go` command exits after Laundering completes. [Full Autonomous Mode docs →](https://gangsta.page/advanced/autonomous-mode) ## What Happens After a Heist Once the Don declares the Heist complete: 1. **Archive** — All Heist documentation remains in `docs/gangsta/` for future reference 2. **Ledger persists** — Insights, fails, and constitution rules are available for future sessions 3. **Clean slate** — The next feature starts a fresh Heist cycle 4. **Carry-forward** — New Heists can reference previous dossiers and contracts ## Checklist Before Declaring Complete - All acceptance criteria met - Consigliere review completed - Integration tests passing - Ledger updated with insights - Ledger updated with fails - Constitution amendments proposed (if any) - Don declares Heist complete [Previous: Execution ←](https://gangsta.page/heist-pipeline/the-hit) # The Heist Pipeline Every feature development cycle in Gangsta Agents follows the same structured process — a 6-phase Heist that ensures specs are written before code, designs are debated before committing, and results are verified before delivery. :pipeline-flow ## Phase Overview | # | Phase | Skill | Gate | Output | | - | -------------------------------------------------------------------------------- | ------------------------------ | ----------------------- | ---------------- | | 1 | [Reconnaissance](https://gangsta.page/heist-pipeline/reconnaissance) | `gangsta:reconnaissance` | Dossier approved | Intel report | | 2 | [The Grilling](https://gangsta.page/heist-pipeline/the-grilling) | `gangsta:the-grilling` | Consensus approved | Design decisions | | 3 | [The Sit-Down](https://gangsta.page/heist-pipeline/the-sit-down) | `gangsta:the-sit-down` | Contract signed | Specification | | 4 | [Resource Development](https://gangsta.page/heist-pipeline/resource-development) | `gangsta:resource-development` | Execution Plan approved | Task breakdown | | 5 | [Execution](https://gangsta.page/heist-pipeline/the-hit) | `gangsta:the-hit` | Completion approved | Working code | | 6 | [The Delivery](https://gangsta.page/heist-pipeline/laundering) | `gangsta:laundering` | Heist complete | Clean delivery | ## The Six Phases ### 1. Reconnaissance Gather intel on the codebase, requirements, dependencies, and existing patterns before writing a single line of code. [Explore Reconnaissance →](https://gangsta.page/heist-pipeline/reconnaissance) ### 2. The Grilling Run an adversarial debate between a proposer and a devil's advocate to stress-test designs before committing to implementation. [Explore The Grilling →](https://gangsta.page/heist-pipeline/the-grilling) ### 3. The Sit-Down Draft the formal specification — no code allowed. The Contract becomes the binding spec that governs all subsequent implementation. [Explore The Sit-Down →](https://gangsta.page/heist-pipeline/the-sit-down) ### 4. Resource Development Decompose the spec into work packages, assign territories, and prepare the infrastructure for parallel execution. [Explore Resource Development →](https://gangsta.page/heist-pipeline/resource-development) ### 5. Execution Workers implement the approved work packages in parallel, with strict TDD enforcement and real-time progress reporting to Crew Leads. [Explore Execution →](https://gangsta.page/heist-pipeline/the-hit) ### 6. The Delivery Verify, integrate, lint, test, and update the Ledger. Clean output only — no dirty code gets merged. [Explore The Delivery →](https://gangsta.page/heist-pipeline/laundering) ## Phase Gates Every phase ends with a **gate** — a checkpoint requiring the Don's explicit approval. The framework never auto-advances to the next phase. ::callout{icon="i-lucide-shield" type="warning"} **You are the Don.** Your approval is required at every gate. If the output is incomplete or incorrect, reject it. The Heist only progresses when you say so. :: ## Starting a Heist There are two ways to start a Heist: ### Manual (Gated) Express a building intention to your AI tool: > "I want to add user notifications to my app" The 1% Rule triggers `gangsta:reconnaissance` automatically. From there, each phase flows into the next with your approval at every gate. ### Autonomous Mode Use the `/gangsta:heist` slash command to run phases 1–4 end-to-end without pausing at each gate: > `/gangsta:heist make a user notifications system with push notification delivery` The Don Proxy approves each gate on your behalf. When the Contract and Execution Plan are ready, you sign with `/gangsta:go` to execute phases 5–6. [Full Autonomous Mode docs →](https://gangsta.page/advanced/autonomous-mode) ## Slash Commands | Command | Phases | Purpose | | ------------------------------ | ------ | ------------------------------------------------------------ | | `/gangsta:heist ` | 1–4 | Run Reconnaissance through Resource Development autonomously | | `/gangsta:go [feature]` | 5–6 | Sign the Contract and execute The Hit + The Delivery | | `/gangsta:abort ` | — | Halt the Heist and archive it | ## Resuming a Heist If a session is interrupted: 1. Check `docs/gangsta/` for checkpoint files 2. Read the latest checkpoint 3. Present the resume context to the Don 4. Continue from the last completed phase [Checkpoint Recovery guide →](https://gangsta.page/advanced/checkpoint-recovery) ## The Full Cycle ```text Reconnaissance → The Grilling → The Sit-Down → Resource Dev → Execution → The Delivery │ │ │ │ │ │ Dossier Consensus Contract Execution Code + Clean approved approved signed Plan Budgets Delivery approved ``` Each phase produces a concrete artifact that the next phase depends on. You cannot skip phases, and you cannot proceed without explicit approval. # Skills Reference Every Gangsta Agents skill is a self-contained markdown file that your AI agent reads at runtime. No plugins, no compilation — just structured instructions that the model follows. ## Installing Skills Skills are installed into your AI agent platform — see the [Installation guide](https://gangsta.page/getting-started/installation) for platform-specific instructions (Claude Code, GitHub Copilot, OpenCode, Codex, Gemini CLI, Cursor). **Alternative: install all skills at once via the `skills` utility:** ```bash npx skills add https://github.com/kucherenko/gangsta ``` This is especially useful for Cursor and any platform where a native integration is not yet available. Once installed, just tell your agent: ```text Use gangsta and build new feature ``` The agent will automatically invoke the right skills for the task. ## Available Skills Skills are sourced from the [Gangsta Agents GitHub repository](https://github.com/kucherenko/gangsta){rel=""nofollow""}. ## Skill Categories ### Hierarchy Roles Core roles in the Gangsta Agents Family chain of command. | Skill | Purpose | | ------------------------- | --------------------------------------- | | `gangsta:the-consigliere` | Architectural advisor, security auditor | | `gangsta:the-underboss` | Task decomposition, resource management | | `gangsta:the-capo` | Domain crew orchestration | | `gangsta:the-ledger` | Read/write institutional memory | | `gangsta:omerta` | Governance guardrails (always active) | ### Heist Phases The 6-phase pipeline for building anything. | Skill | Phase | | ------------------------------ | ----------------------------------- | | `gangsta:reconnaissance` | Phase 1 — Intel gathering | | `gangsta:the-grilling` | Phase 2 — Adversarial brainstorming | | `gangsta:the-sit-down` | Phase 3 — Spec drafting | | `gangsta:resource-development` | Phase 4 — Task planning | | `gangsta:the-hit` | Phase 5 — Execution | | `gangsta:laundering` | Phase 6 — The Delivery | ### Software Development Tactical skills for the daily grind. | Skill | Purpose | | --------------------------------- | -------------------------------------------- | | `gangsta:interrogation-debugging` | Systematic root-cause debugging | | `gangsta:drill-tdd` | Test-Driven Development (Red-Green-Refactor) | | `gangsta:safehouse-worktrees` | Isolated git worktrees | | `gangsta:audit-review` | Code review via the Inspector | | `gangsta:receiving-orders` | Process review feedback with rigor | | `gangsta:sweep-verification` | Evidence-before-assertions gate | | `gangsta:exit-strategy` | Branch integration and cleanup | | `gangsta:using-gangsta` | Framework orientation and intent routing | | `gangsta:find-skills` | Discover and install new skills | # Artifacts Reference Gangsta Agents generates structured documentation throughout every Heist. These artifacts are the paper trail — the evidence that work was done right, decisions were reasoned, and lessons were captured. All artifacts live under `docs/gangsta/` in your project root. ## Full Directory Structure ```text docs/gangsta/ ├── insights/ │ └── {date}-{slug}.md ├── fails/ │ └── {date}-{slug}.md ├── constitution/ │ └── rules.md └── {heist-name}/ ├── checkpoints/ │ ├── 01-reconnaissance.md │ ├── 02-the-grilling.md │ ├── 03-the-sit-down.md │ ├── 04-resource-development.md │ ├── 05-the-hit.md │ └── 06-laundering.md ├── recon/ │ └── {date}-recon-dossier.md ├── specs/ │ └── {date}-contract.md └── plans/ └── {date}-execution-plan.md ``` --- ## Heist Artifacts These artifacts are produced during a single Heist and stored under `docs/gangsta/{heist-name}/`. ### Recon Dossier **Phase:** Reconnaissance (Phase 1) :br**Skill:** `gangsta:reconnaissance`:br**Path:** `docs/gangsta/{heist-name}/recon/{date}-recon-dossier.md` The intelligence report that grounds every subsequent phase decision in verified facts. | Section | Contents | | ----------------- | ------------------------------------------------------------------------ | | Codebase Overview | Architecture, tech stack, directory structure, existing patterns | | Dependencies | Related modules, APIs, and services | | Constraints | Technical limitations, performance requirements, security considerations | | Risks & Unknowns | What needs further investigation before design can begin | | Recommended Scope | What reconnaissance suggests the feature should cover | The Dossier is the single factual foundation for The Grilling and The Sit-Down. No design decision is valid unless grounded in the Dossier. --- ### Grilling Conclusions **Phase:** The Grilling (Phase 2) :br**Skill:** `gangsta:the-grilling`:br**Incorporated into:** The Contract during The Sit-Down The structured output of adversarial debate between the Proposer and Devil's Advocate. Not a standalone file — the conclusions are folded into the Contract. | Section | Contents | | --------------------- | ------------------------------------------------------------- | | Key Decisions | What was agreed upon and why | | Rejected Alternatives | Approaches considered and explicitly rejected, with reasoning | | Unresolved Objections | Disagreements escalated to the Don | | Risk Assessment | Identified risks with severity and mitigation strategies | --- ### Contract **Phase:** The Sit-Down (Phase 3) :br**Skill:** `gangsta:the-sit-down`:br**Path:** `docs/gangsta/{heist-name}/specs/{date}-contract.md` The authoritative specification. Every implementation decision during The Hit traces back here. **This is law.** | Section | Contents | | ----------------------------- | ------------------------------------------------------- | | Objective | What's being built and why | | Requirements | Functional and non-functional requirements | | Architectural Decisions | Key design choices with rationale | | Grilling Conclusions | Design decisions and rejected alternatives from Phase 2 | | Applicable Constitution Rules | Project-specific rules that apply to this Heist | | Acceptance Criteria | How success is verified — each criterion is testable | | Out of Scope | What is explicitly not being built | | Open Risks | Known risks with severity and mitigation | ::callout{icon="i-lucide-scroll" type="danger"} **Spec is Law.** If implementation contradicts the Contract, revise the Contract — not the implementation. Revisions require Don approval. :: --- ### Execution Plan **Phase:** Resource Development (Phase 4) :br**Skill:** `gangsta:resource-development`:br**Path:** `docs/gangsta/{heist-name}/plans/{date}-execution-plan.md` The operational blueprint. Translates the Contract into a parallel work schedule. | Section | Contents | | --------------------- | -------------------------------------------- | | Work Packages | Discrete tasks with clear deliverables | | Territory Assignments | Which domain each package belongs to | | Budget Estimates | Resource budgets per package | | Dependency Map | Which packages block which | | Execution Order | Which tasks run in parallel vs. sequentially | | Risk Mitigations | How to handle potential blockers | --- ### Checkpoints **Phase:** All phases :br**Path:** `docs/gangsta/{heist-name}/checkpoints/{N}-{phase}.md` Written at the end of each phase gate. Checkpoints are the session recovery mechanism — if a Heist is interrupted, the next session reads checkpoints to restore context. Each checkpoint records: - **Phase completed** — Which phase just finished - **Gate status** — Whether the Don approved - **Key decisions** — Major choices made during the phase - **Artifacts produced** — Dossier, Contract, Execution Plan, etc. - **Pending items** — Anything unresolved before the interruption ```text checkpoints/ ├── 01-reconnaissance.md ├── 02-the-grilling.md ├── 03-the-sit-down.md ├── 04-resource-development.md ├── 05-the-hit.md └── 06-laundering.md ``` See [Checkpoint Recovery](https://gangsta.page/advanced/checkpoint-recovery) for how to resume interrupted Heists. --- ## Ledger Artifacts These artifacts persist across all Heists. They live directly under `docs/gangsta/` — not inside a heist subdirectory. ### Insights **Written by:** The Delivery (Phase 6) or proactive capture during conversations :br**Path:** `docs/gangsta/insights/{date}-{slug}.md` Non-obvious approaches, successful patterns, and domain knowledge worth preserving. **Captured when:** - A non-obvious approach is discovered - The Don contributes domain knowledge - A creative solution bypasses a complex constraint **Example filenames:** ```text docs/gangsta/insights/ ├── 2026-04-15-payment-idempotency.md └── 2026-04-20-query-builder-pattern.md ``` --- ### Fails **Written by:** The Delivery (Phase 6) or proactive capture during conversations :br**Path:** `docs/gangsta/fails/{date}-{slug}.md` Documented mistakes — approaches that caused rework, confusion, or wasted effort. **Captured when:** - The Don criticizes or rejects an approach - An approach caused rework or confusion - A repeated mistake pattern surfaces **Example filenames:** ```text docs/gangsta/fails/ ├── 2026-04-10-parallel-test-flakiness.md └── 2026-04-18-raw-sql-bypassed-builder.md ``` --- ### Constitution Rules **Written by:** The Delivery (Phase 6), amended over time :br**Path:** `docs/gangsta/constitution/rules.md` Accumulated project-specific commandments. These are project-level extensions of Omerta — rules the team has agreed should govern all future Heists. **Grows over time** as each completed Heist proposes and ratifies new rules. **Example entries:** - "All database queries must use the QueryBuilder, never raw SQL" - "Feature flags must be in `config/features.yml`, not hardcoded" - "Every PR must include a test for the happy path and at least one error path" ::callout{icon="i-lucide-gavel" type="info"} Constitution rules require Don approval before they are written. They are proposed at the end of The Delivery — never during implementation. :: --- ## Artifact Lifecycle | Artifact | Created | Approved by | Lives in | | -------------------- | --------------------------- | ------------ | ---------------------- | | Recon Dossier | Reconnaissance | Don | `{heist}/recon/` | | Grilling Conclusions | The Grilling | Don | Merged into Contract | | Contract | The Sit-Down | Don (signed) | `{heist}/specs/` | | Execution Plan | Resource Development | Don | `{heist}/plans/` | | Checkpoints | All phases | Automatic | `{heist}/checkpoints/` | | Insights | The Delivery / conversation | Don | `insights/` | | Fails | The Delivery / conversation | Don | `fails/` | | Constitution Rules | The Delivery | Don | `constitution/` | ## Commit Convention All artifacts should be committed to version control after each phase gate: ```bash # After each phase git add docs/gangsta/ git commit -m "heist({heist-name}): phase N — {phase name} artifacts" # Ledger entries git add docs/gangsta/insights/ docs/gangsta/fails/ docs/gangsta/constitution/ git commit -m "ledger: add insight — {slug}" ``` This ensures artifacts survive across sessions, remain visible to the full team, and maintain a historical record of every Heist. # Autonomous Mode Autonomous Mode runs the same 6-phase Heist Pipeline, but with `gangsta:don-proxy` substituting for the human Don at every gate. Instead of pausing at each phase for your approval, the pipeline flows through phases automatically — and you sign off at key checkpoints. ::callout{icon="i-lucide-robot" type="info"} **Autonomous Mode is optional.** The default gated pipeline — where you approve every phase — remains unchanged. Autonomous Mode is for when you trust the pipeline and want to move faster. :: ## How It Works Autonomous Mode uses **two commands** that split the Heist into two runs: 1. **`/gangsta:heist `** — Runs phases 1–4 (Reconnaissance → Grilling → Sit-Down → Resource Development). The Don Proxy approves each gate, producing a Contract and Execution Plan. 2. **`/gangsta:go [feature]`** — You review and sign the Contract, then phases 5–6 (The Hit → Laundering) execute. 3. **`/gangsta:abort `** — Halts the Heist at any point and archives it. ```text /gangsta:heist make a user notifications system with push notification delivery Phase 1: Reconnaissance ──── don-proxy approves ──→ auto-advance Phase 2: The Grilling ────── don-proxy approves ──→ auto-advance Phase 3: The Sit-Down ─────── dual-veto gate ────→ auto-advance Phase 4: Resource Development ─ don-proxy approves ──→ PAUSE /gangsta:go user-notifications You sign the Contract and Plan Phase 5: The Hit ──────────── Workers execute ────→ auto-advance Phase 6: Laundering ────────── don-proxy declares ──→ COMPLETE ``` ## The Don Proxy During Autonomous Mode, `gangsta:don-proxy` acts as your surrogate at every gate. It reviews outputs using the same criteria a human Don would: - Does the Dossier cover all requested areas? - Are Grilling conclusions well-reasoned? - Does the Contract meet completeness standards? - Is the Execution Plan realistic? The Don Proxy is **not** a rubber stamp. It can reject outputs that are incomplete or violate the Constitutional Floor. ## The Dual-Veto Phase 3 (The Sit-Down) has a special **Dual-Veto** gate: both the Consigliere and the Don Proxy must approve. If either rejects, the Heist halts. | Consigliere | Don Proxy | Result | | ----------- | --------- | ------------------------------- | | Approve | Approve | Proceed to Resource Development | | Reject | Approve | Halt — Consigliere veto | | Approve | Reject | Halt — Don Proxy veto | | Reject | Reject | Halt — both vetoed | There is no tie-breaker, no precedence, no override. A veto from either party is terminal for that Heist run. ## Command Reference ### `/gangsta:heist ` Starts an autonomous Heist. The description can be a feature name or a natural language description of what you want built: > `/gangsta:heist make a user notifications system with push notification delivery` The pipeline derives the Heist directory name from the description and runs phases 1–4 end-to-end without pausing. - Creates the Heist directory: `docs/gangsta//` - Produces: Dossier, Grilling Conclusions, Contract, Execution Plan - Artifacts are marked `signed-by: don-proxy`, `status: pending-don-confirmation` - Exits after Resource Development with the Contract and Plan ready for your review ### `/gangsta:go [feature]` Signs the Contract and Execution Plan, then executes phases 5–6. - If no feature is specified, reads `docs/gangsta/.last-heist` for the most recent autonomous Heist - Flips artifact status from `pending-don-confirmation` to `confirmed` - The signature is atomic: Contract and all matched Ledger entries are confirmed together - The Hit and Laundering execute automatically after signing ### `/gangsta:abort ` Halts the Heist and relocates all artifacts to `docs/gangsta/.aborted/-/`. - Aborted Heists are excluded from active Ledger reads - Clears `.last-heist` if it pointed to the aborted feature - No partial artifacts are left in the active Heist directory ## Constitutional Floor Autonomous Mode is bounded by a **Constitutional Floor** — a set of hard rules that cannot be overridden: - **Omerta Laws** from `skills/omerta/SKILL.md` - **Negative Constraints** from `docs/gangsta/constitution.md` - **Binding contributor constraints** from `AGENTS.md` If any phase produces output that violates the Constitutional Floor, the Heist **halts immediately**. The violation is written to the autonomous log, and the Heist directory is left in place for your inspection. ::callout{icon="i-lucide-shield-alert" type="danger"} **No mid-flight retry.** A Constitutional Floor rejection is terminal. Resumption requires a fresh `/gangsta:heist` invocation. The `--best-effort` flag does not override Floor violations. :: ## Per-Phase Differences The following table summarizes how Autonomous Mode differs from the default gated pipeline at each phase: | Phase | Gate Actor | Auto-Advance | Termination | | ----------------------- | ------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------- | | 1. Reconnaissance | Don Proxy (once, post-Dossier) | To Grilling on non-REJECT | Halts on Floor REJECT or material incompleteness | | 2. The Grilling | Don Proxy (per round + consensus) | To Sit-Down on non-REJECT | Halts on Floor violation baked into consensus | | 3. The Sit-Down | Don Proxy + Consigliere (dual-veto) | To Resource Development on dual non-REJECT | Either veto is terminal | | 4. Resource Development | Don Proxy (once, post-Plan) | `/gangsta:heist` exits; Hit does NOT auto-start | Halts on Plan that forces a Floor violation | | 5. The Hit | Don Proxy (at Worker-failure mini-Grilling only) | To Laundering as in default | Mini-Grilling produces deviation report only; Contract amendment requires fresh Sit-Down | | 6. Laundering | Don Proxy (once, at final declaration) | `/gangsta:go` exits | Ledger entries written `signed-by: don-proxy`, `status: pending-don-confirmation` | ## Artifact Lifecycle States Autonomous Mode artifacts carry one of three states in their frontmatter: ### `pending-don-confirmation` Written by `/gangsta:heist` and during Laundering under `/gangsta:go`. Visible to active reads but flagged as unconfirmed. ### `confirmed` Flipped by `/gangsta:go` at signing: `signed-by: don`, `confirmed: `. The flip is atomic across the Contract and every matched Ledger entry. ### `rejected` Relocated by `/gangsta:abort` together with the Heist directory to `docs/gangsta/.aborted/-/`. Subsequent Ledger reads exclude entries whose `heist:` resolves under `.aborted/`. ## State Files Autonomous Mode maintains two state files: ### `.last-heist` A single-line pointer at `docs/gangsta/.last-heist` that references the most recent autonomous Heist directory. Read by `/gangsta:go` when invoked without a feature argument. Cleared by `/gangsta:abort` if it points at the aborted feature. ### `autonomous-log.md` A progressive per-phase decision log at `docs/gangsta//autonomous-log.md`. Written incrementally during `/gangsta:heist` and `/gangsta:go`. Records: - Timestamp - Phase - Actor (don-proxy, consigliere, worker) - Verdict - Citation (which rule or artifact informed the decision) - Artifact pointers ## Resolution Rules Both `/gangsta:go` and `/gangsta:abort` resolve the target Heist by **exact directory match only** under `docs/gangsta//`. No fuzzy match, no Levenshtein distance, no auto-correct, no closest-suggestion. Resolution failure is a hard error. ## When to Use Autonomous Mode ::callout{icon="i-lucide-lightbulb" type="tip"} **Use Autonomous Mode when:** - You have a clear feature description and want fast end-to-end pipeline execution - You trust the pipeline's Constitutional Floor to catch serious issues - You want to review the Contract and Plan in one go rather than approving each phase individually **Use the default gated pipeline when:** - You want full control over every phase gate - The feature is complex or ambiguous enough that intermediate review is important - You don't want any auto-approval at all :: ## Quick Reference: Gated vs. Autonomous | Aspect | Gated Pipeline | Autonomous Mode | | ---------------- | --------------------------------------------------- | ------------------------------------------------------------------- | | Gate approval | Human Don at every phase | Don Proxy (phases 1–4), Human Don (signing), Don Proxy (phases 5–6) | | Phase transition | Manual after each gate | Automatic between phases | | Starting command | Express building intent or `gangsta:reconnaissance` | `/gangsta:heist ` | | Signing | Human Don at each gate | Human Don signs via `/gangsta:go` | | Halting | Reject at any gate | `/gangsta:abort` or Constitutional Floor REJECT | | Abort handling | Manual cleanup | Automatic archival to `.aborted/` | # Checkpoint Recovery Heists can be interrupted — your AI session might time out, you might need to step away, or a technical issue might cut things short. Gangsta Agents' checkpoint system ensures you never lose progress. ## How Checkpoints Work Every phase of the Heist writes checkpoints to `docs/gangsta/`: ```text docs/gangsta/{heist-name}/ ├── checkpoints/ │ ├── 01-reconnaissance.md │ ├── 02-the-grilling.md │ ├── 03-the-sit-down.md │ ├── 04-resource-development.md │ └── 05-the-hit.md ├── recon/ │ └── 2026-04-15-recon-dossier.md ├── specs/ │ └── 2026-04-15-contract.md └── plans/ └── 2026-04-15-execution-plan.md ``` Each checkpoint records: - **Phase completed** — Which phase just finished - **Gate status** — Whether the Don approved - **Key decisions** — Major choices made during the phase - **Artifacts produced** — Dossier, Contract, Execution Plan, etc. - **Pending items** — Anything unresolved ## Resuming an Interrupted Heist When you start a new session after an interruption: ### Step 1: Check for Checkpoints Look in `docs/gangsta/` for heist directories with checkpoint files. ### Step 2: Read the Latest Checkpoint The checkpoint tells you: - Which phase was last completed - What artifacts were produced - Any pending decisions ### Step 3: Present Context to the Don Start your new session by: > "I'm resuming a Heist that was interrupted. The last completed phase was [Phase X]. Here's the context: [summary of checkpoint]. Should we continue from [Phase X+1] ?" ### Step 4: Continue from the Last Approved Phase Resume from the phase after the last **approved** checkpoint. If the last phase was completed but not approved, present the output for Don review before proceeding. ## Example: Interrupted During The Hit ```text docs/gangsta/notifications/ ├── checkpoints/ │ ├── 01-reconnaissance.md ← approved │ ├── 02-the-grilling.md ← approved │ ├── 03-the-sit-down.md ← approved │ ├── 04-resource-development.md ← approved │ └── 05-the-hit.md ← INCOMPLETE ├── recon/ │ └── 2026-04-15-recon-dossier.md ├── specs/ │ └── 2026-04-15-contract.md └── plans/ └── 2026-04-15-execution-plan.md ``` **Resume approach:** 1. Read all checkpoints to understand the full context 2. Read the Execution Plan to see which tasks were assigned 3. Check the incomplete Execution checkpoint for partial progress 4. Resume The Hit from where it left off, or restart if the partial work is unclear ## Example: Clean Resume After The Delivery If the Heist completed successfully and you want to build something new: 1. The previous Heist's Ledger entries are preserved 2. Start a new Heist with `gangsta:reconnaissance` 3. The agent will read `docs/gangsta/` for context and institutional memory 4. Previous insights and fails inform the new Heist ## Best Practices ::callout{icon="i-lucide-save" type="info"} **Checkpoint frequently:** The more granular your checkpoints, the easier it is to resume. The Heist Pipeline creates natural checkpoints at every phase gate. :: ::callout{icon="i-lucide-alert-triangle" type="warning"} **Don't skip phases on resume.** Even if you're confident about where you left off, read the checkpoints. Context can be subtly different from what you remember, and the Rule of Truth (Omerta Law #3) requires citing sources — checkpoints are your sources. :: ## Checkpoint and Git Checkpoints are files in `docs/gangsta/` — they should be committed to version control: ```bash # After each phase gate git add docs/gangsta/ git commit -m "heist: phase N checkpoint — [phase name]" ``` This ensures: - Checkpoints survive across sessions - The team can see Heist progress - History is preserved even if the local environment changes # Contributing Gangsta is open source (MIT) and welcomes contributions — especially new skills that follow the established patterns. ## What You Can Contribute - **New skills** — Following the SKILL.md format - **Skill improvements** — Enhancements to existing skills - **Documentation fixes** — Corrections and clarifications - **Bug reports** — Issues with skill behavior ## Creating a Skill for Contribution ### 1. Fork the Repository ```bash git clone https://github.com/kucherenko/gangsta.git cd gangsta git checkout -b my-new-skill ``` ### 2. Create the Skill Directory ```bash mkdir -p skills/my-new-skill ``` ### 3. Write the SKILL.md Every skill must follow this structure: ```yaml --- name: my-new-skill description: | Clear description of what the skill does and when to invoke it. This is what AI agents read to decide whether to use this skill. type: flexible # or: rigid --- # My New Skill ## When to Invoke Specific conditions under which this skill should be activated. ## Process 1. Step one — describe what happens 2. Step two — describe what happens next 3. Step three — describe the output ## Checklist Before Proceeding - [ ] Verification item one - [ ] Verification item two ## Outputs What this skill produces when complete. ``` ### 4. Skill Quality Standards Before submitting, ensure your skill: - **Has a clear invocation trigger** — When should the AI use this skill? - **Follows an existing pattern** — Look at `skills/reconnaissance/SKILL.md` for reference - **Has a complete process** — Every step is described, no gaps - **Includes a checklist** — Phase gates need verification items - **Specifies output artifacts** — What does the skill produce? - **Uses correct skill type** — `rigid` for processes that must be followed exactly, `flexible` for adaptable ones ### 5. Subagent Prompts (Optional) If your skill delegates work to subagents, include prompt files: ```text skills/my-new-skill/ ├── SKILL.md ├── planner-prompt.md └── executor-prompt.md ``` ### 6. Test Your Skill 1. Install your skill locally (see [Installation](https://gangsta.page/getting-started/installation)) 2. Start a new session with your AI tool 3. Trigger the skill with an appropriate intent 4. Walk through the full process 5. Verify all checklist items are actionable 6. Confirm the expected outputs are produced ## Submitting a PR ```bash # Push your branch git push origin my-new-skill ``` Then open a Pull Request against `kucherenko/gangsta` with: 1. **Description** — What the skill does and why it's needed 2. **Skill type** — Rigid or flexible, and why 3. **Testing** — How you verified the skill works 4. **Pattern alignment** — How it follows existing Gangsta conventions ## PR Review Criteria Maintainers will review for: - **Invocation clarity** — Is the description specific enough for AI agents? - **Process completeness** — Are all steps actionable? - **Omerta compliance** — Does it follow the Five Laws? - **Consistency** — Does it match the tone and style of existing skills? - **No code** — Skills are Markdown, not code ## Code of Conduct Gangsta uses the mafia metaphor as a playful organizational framework. Contributions should: - Maintain the metaphor consistently - Be respectful and inclusive - Focus on structured, disciplined development processes - Not glorify actual criminal activity The metaphor exists to make structured development memorable and engaging. Keep it fun, keep it professional. ## Getting Help - **GitHub Issues** — [github.com/kucherenko/gangsta/issues](https://github.com/kucherenko/gangsta/issues){rel=""nofollow""} - **Discussions** — [github.com/kucherenko/gangsta/discussions](https://github.com/kucherenko/gangsta/discussions){rel=""nofollow""} # Writing Custom Skills Gangsta skills are Markdown files that tell AI agents how to perform structured tasks. You can create custom skills for your project's specific needs — domain-specific processes, team conventions, or specialized workflows. ## The SKILL.md Format Every skill is a Markdown file with YAML frontmatter: ```yaml --- name: my-custom-skill description: | A brief description of what this skill does and when to invoke it. This description is what the AI agent reads to decide whether to invoke the skill. type: flexible # or: rigid --- # Skill Name ## When to Invoke Describe the conditions under which this skill should be activated. Be specific about triggers and intents. ## Process 1. Step one 2. Step two 3. Step three ## Checklist Before Proceeding - [ ] Item one is verified - [ ] Item two is confirmed - [ ] Item three is complete ## Outputs Describe what this skill produces when complete. ``` ## Frontmatter Fields | Field | Required | Description | | ------------- | -------- | ------------------------------------------- | | `name` | Yes | Unique skill identifier (kebab-case) | | `description` | Yes | What the skill does and when to invoke it | | `type` | No | `rigid` or `flexible` (default: `flexible`) | ## Skill Types ### Flexible Skills Adapt principles to context. The spirit matters more than the letter. ```yaml type: flexible ``` Use for: reconnaissance, brainstorming, planning — tasks where context determines the best approach. ### Rigid Skills Must be followed exactly. Don't adapt away from the discipline. ```yaml type: rigid ``` Use for: TDD cycles, debugging protocols, governance rules — tasks where skipping steps produces unreliable results. ## Directory Structure Custom skills live in your project's skills directory: ```text your-project/ ├── .gangsta/ │ └── skills/ │ ├── my-custom-skill/ │ │ └── SKILL.md │ └── another-skill/ │ ├── SKILL.md │ └── subagent-prompt.md ├── docs/ ├── src/ └── ... ``` Or in a shared location: ```text ~/gangsta/skills/ ├── my-custom-skill/ │ └── SKILL.md └── ... ``` ## Writing Effective Skill Descriptions The `description` field is critical — it's what the AI agent reads to decide whether to invoke the skill. Write descriptions that: 1. **Are specific about triggers** — "When the user wants to add a new API endpoint" is better than "When building things" 2. **Include relevant keywords** — AI agents match on intent; use words the user is likely to say 3. **Clarify scope** — "For database migration tasks only" prevents false positives **Good example:** ```yaml description: | Invoke when creating or modifying database schema migrations. Covers adding tables, columns, indexes, and constraints. Do not invoke for data migrations or seed scripts. ``` **Poor example:** ```yaml description: | Use this skill for database stuff. ``` ## Subagent Prompts Skills that delegate work to subagents can include separate prompt files: ```text my-skill/ ├── SKILL.md ├── planner-prompt.md └── executor-prompt.md ``` The main `SKILL.md` references these subagents in its process steps. ## Registering with Your AI Tool ### Claude Code ```json // .claude/settings.json { "skills": { "paths": ["~/gangsta/skills", "./.gangsta/skills"] } } ``` ### OpenCode ```json // opencode.json { "skills": { "paths": ["~/gangsta/skills", "./.gangsta/skills"] } } ``` ### Codex ```bash # Symlink to the Codex skills directory ln -s ./skills/my-custom-skill ~/.agents/skills/my-custom-skill ``` ### Gemini CLI ```bash # Install local skills gemini extensions install ./path/to/my-custom-skill ``` ## Testing Custom Skills After creating a custom skill: 1. Start a **new session** with your AI tool 2. Express an intent that should trigger the skill 3. Verify the agent invokes your skill 4. Walk through the skill's process steps 5. Confirm the expected outputs are produced ::callout{icon="i-lucide-test-tubes" type="info"} **Debugging tip:** If a skill doesn't invoke, check the `description` field. It may not match the user intent closely enough. The 1% Rule means agents look for any match — make sure your description is specific enough to avoid false positives. :: # Advanced Topics For users who have mastered the basics and want to go deeper: - **[Autonomous Mode](https://gangsta.page/advanced/autonomous-mode)** — Run the Heist Pipeline end-to-end with Don Proxy gate approval - **[Artifacts Reference](https://gangsta.page/advanced/artifacts)** — Every file Gangsta generates, where it lives, and which phase produces it - **[Writing Custom Skills](https://gangsta.page/advanced/custom-skills)** — Create your own Gangsta skills using the SKILL.md format - **[Multi-Agent Patterns](https://gangsta.page/advanced/multi-agent-patterns)** — Use Underboss for task decomposition, Crew Lead for territory orchestration - **[Checkpoint Recovery](https://gangsta.page/advanced/checkpoint-recovery)** — Resume interrupted Heists from checkpoint files - **[Contributing](https://gangsta.page/advanced/contributing)** — How to contribute skills to the Gangsta framework ::callout{icon="i-lucide-zap" type="info"} **Prerequisites:** Make sure you've read [Core Concepts](https://gangsta.page/core-concepts) and understand the [Heist Pipeline](https://gangsta.page/heist-pipeline) before diving into advanced topics. :: # Multi-Agent Patterns When a Heist involves multiple files, multiple domains, or multiple concerns, the Gangsta Agents hierarchy provides structured patterns for multi-agent coordination. ## The Two Orchestration Skills ### Underboss (`gangsta:the-underboss`) The COO. Handles task decomposition and resource allocation. **When to invoke:** - Complex features that span multiple files or domains - Tasks that have clear dependency chains - When you need an Execution Plan broken into parallel work packages **What the Underboss does:** 1. Analyzes the Contract 2. Decomposes work into discrete packages 3. Maps dependencies between packages 4. Assigns territories (domains) to Crew Leads 5. Estimates budgets per package 6. Produces the Execution Plan ### Crew Lead (`gangsta:the-capo`) The domain crew lead. Orchestrates work within a territory. **When to invoke:** - When a territory has multiple related tasks - When a domain needs coordinated changes across multiple files - When sub-tasks within a territory need sequencing **What the Crew Lead does:** 1. Receives territory assignment from the Underboss 2. Sequences tasks within the territory 3. Dispatches Workers for individual tasks 4. Enforces quality standards within the territory 5. Reports completion status ## Pattern 1: Parallel Territories **Best for:** Features that touch independent domains (e.g., frontend + backend) ```text Underboss ├── Territory A (Frontend) → Crew Lead A → Worker 1, Worker 2 ├── Territory B (Backend) → Crew Lead B → Worker 3 └── Territory C (Database) → Crew Lead C → Worker 4 ``` **Workflow:** 1. Underboss decomposes the Contract into 3 territories 2. Each Crew Lead sequences their territory's tasks 3. Workers execute in parallel across territories 4. No cross-territory dependencies — maximum parallelism ## Pattern 2: Sequential Dependencies **Best for:** Features with hard dependencies (e.g., database schema must exist before API endpoints) ```text Underboss ├── Phase 1: Territory A (Schema) → Crew Lead A → Worker 1 │ (gate: schema complete) ├── Phase 2: Territory B (API) → Crew Lead B → Worker 2 │ (gate: API complete) └── Phase 3: Territory C (Frontend) → Crew Lead C → Worker 3 ``` **Workflow:** 1. Underboss identifies dependency chain 2. Crew Leads execute sequentially, each waiting for the previous to complete 3. Each phase has a gate — next phase doesn't start until current one is verified ## Pattern 3: Mixed Parallel-Sequential **Best for:** Most real-world features (some things can run in parallel, others can't) ```text Underboss ├── Phase 1: [Territory A (DB) | Territory B (Config)] ← parallel │ (gate: both complete) ├── Phase 2: [Territory C (API) | Territory D (Tests)] ← parallel │ (gate: both complete) └── Phase 3: Territory E (Integration) ← sequential ``` **Workflow:** 1. Within each phase, territories run in parallel 2. Phases run sequentially (phase 2 waits for phase 1) 3. The Execution Plan documents the dependency graph ## Communication Protocol All inter-agent communication follows Omerta Law #1 (The Introduction Rule): **Workers never communicate directly with each other.** All communication flows through files: - **Contracts** → define what to build - **Execution Plans** → define how to build it - **Checkpoints** → track progress - **The Ledger** → preserve knowledge This prevents the "telephone game" problem where messages distort through chains of agents. ## Choosing the Right Pattern | Situation | Pattern | Orchestration | | ----------------------------- | ----------------------- | ---------------------- | | Single file, single concern | Sequential | Crew Lead only | | Multiple independent concerns | Parallel Territories | Underboss + Crew Leads | | Dependent stages | Sequential Dependencies | Underboss | | Mixed dependencies | Mixed | Underboss + Crew Leads | ::callout{icon="i-lucide-lightbulb" type="info"} **Tip:** If you're unsure which pattern to use, invoke `gangsta:the-underboss` during Resource Development. The Underboss will analyze the Contract and recommend the appropriate pattern in the Execution Plan. :: # Glossary Gangsta Agents uses themed terminology throughout the framework. Here's what every term means in plain English — and why it maps to its software development concept. ::callout{icon="i-lucide-book-open" type="info"} Terms are listed alphabetically. Each entry explains the **original meaning** and the **Gangsta Agents meaning** . :: --- ## A ### Associate **Mafia:** Someone who works with a crime family but isn't a full member. They're trusted helpers — contractors, not employees. **Gangsta Agents:** External tools and API proxies. Not part of the agent hierarchy — they provide services that Agents and Crew Leads use. Examples: GitHub API, database clients, CI/CD systems. --- ## B ### Budget **General:** A resource allocation — time, money, or tokens assigned to a task. **Gangsta Agents:** The resource allocation assigned to an Agent's work package during Resource Development. Budgets are tracked during Execution — tasks that exceed their budget must flag it to the Don. This is Omerta's Rule of Budget: resource budgets are tracked, not ignored. --- ## C ### Checkpoint **Military/General:** A control point where you verify status before proceeding. **Gangsta Agents:** A state file written to disk at the end of each Heist phase. Checkpoints are what make Heist resumption possible — any session can read the checkpoint and pick up where the last one left off. ### Consigliere **Mafia:** The boss's trusted advisor. Not in the chain of command — operates outside it to give unbiased counsel. The word is Italian for "counselor." **Gangsta Agents:** The strategic advisor — an impartial agent for architectural review, security auditing, and code assessment. Because they're outside the chain of command, they give honest assessments rather than pleasing the hierarchy. Invoked via `gangsta:the-consigliere`. ### Constitution **Mafia:** The family's internal rules — what's allowed, what's forbidden, how disputes are settled. **Gangsta Agents:** Accumulated project-specific rules stored in The Ledger at `docs/gangsta/constitution/`. The Constitution grows over time as Heists add lessons learned. It extends Omerta with project-level constraints. ### Contract **Legal/Business:** A formal agreement that defines terms, scope, and obligations. Once signed, it's binding. **Gangsta Agents:** The formal specification document produced during [The Sit-Down](https://gangsta.page/heist-pipeline/the-sit-down). Signed by the Don, it defines scope, acceptance criteria, architectural decisions, and rules. No Agent writes code without one. If code contradicts the Contract, you revise the Contract — not the code (Omerta Law #5). ### Cowboy Coding **Software slang:** Writing code without discipline, structure, or process — flying solo and improvising. **Gangsta Agents:** Undisciplined development without structure — writing code without specs, skipping phases, flying solo without hierarchy. Gangsta Agents exists to eliminate cowboy coding. The opposite of how the Gangsta Agents Family operates. ### Crew Lead **Gangsta Agents:** A domain crew lead that owns a **territory** (a specific area of the codebase) and orchestrates Agents within it. Invoked via `gangsta:the-capo`. Responsible for sequencing tasks within a territory, dispatching Agents, and enforcing quality standards. Reports to the Underboss. --- ## D ### Devil's Advocate **General:** The role of someone who argues the opposite position to stress-test an idea — not their real opinion, but a structured challenge. **Gangsta Agents:** One of two voices in [The Grilling](https://gangsta.page/heist-pipeline/the-grilling). The Devil's Advocate challenges every assumption made by the Proposer, surfaces risks, and forces edge-case thinking. Their job is not to win — it's to make the final approach stronger. ### Don **Mafia:** The boss. The head of the family. Supreme authority — no one outranks the Don. **Gangsta Agents:** You. The user. The Don approves every phase gate, signs every Contract, and declares every Heist complete. The framework never auto-advances without your explicit approval. Your word overrides everything — including the skills. ### Dossier **Intelligence:** A file of collected intelligence about a target — surveillance notes, known patterns, findings. **Gangsta Agents:** The output of [Reconnaissance](https://gangsta.page/heist-pipeline/reconnaissance) — a structured report of codebase intel including file structure, dependencies, test coverage, and relevant Ledger entries. The Don approves the Dossier before the Heist moves to The Grilling. --- ## E ### Execution **General:** The act of implementing a plan. **Gangsta Agents:** Phase 5 of the Heist Pipeline — the actual code implementation. Agents implement the Execution Plan in parallel, following Test-Driven Development per the Contract. Budgets are tracked. Skill: `gangsta:the-hit`. ### Execution Plan **Project management:** A detailed operational plan for a project — who does what, in what order, with what resources. **Gangsta Agents:** The output of Resource Development. The Contract decomposed into specific tasks, with Agents assigned, territories claimed, and budget estimates set. The Don approves the Execution Plan before Execution begins. Stored at `docs/gangsta/{heist-name}/plans/`. --- ## F ### Fail **Gangsta Agents:** A Ledger entry documenting a mistake — an approach that caused rework, confusion, or wasted effort. Fails are preserved so they're never repeated. Written to `docs/gangsta/fails/`. --- ## G ### The Grilling **General:** Rigorous, pressure-filled questioning to surface the truth. **Gangsta Agents:** Phase 2 of the Heist Pipeline. An adversarial debate where a Proposer argues for the best approach and a Devil's Advocate challenges every assumption. The pressure surfaces edge cases and risks that single-perspective design misses. Output: Grilling Conclusions. Skill: `gangsta:the-grilling`. --- ## H ### Heist **Mafia:** A carefully planned operation. Multiple roles, coordinated phases, a clear objective. **Gangsta Agents:** The complete 6-phase development cycle for any feature: [Reconnaissance](https://gangsta.page/heist-pipeline/reconnaissance) → [The Grilling](https://gangsta.page/heist-pipeline/the-grilling) → [The Sit-Down](https://gangsta.page/heist-pipeline/the-sit-down) → [Resource Development](https://gangsta.page/heist-pipeline/resource-development) → [Execution](https://gangsta.page/heist-pipeline/the-hit) → [The Delivery](https://gangsta.page/heist-pipeline/laundering). The Don approves each phase gate. No shortcuts, no skipped phases. --- ## I ### Insight **Gangsta Agents:** A Ledger entry preserving a successful pattern, non-obvious approach, or domain knowledge worth reusing. Written to `docs/gangsta/insights/` during The Delivery or after significant discoveries. --- ## L ### The Delivery **Gangsta Agents:** Phase 6 of the Heist Pipeline — verification and integration. The Consigliere reviews all deliverables against the Contract, integration tests run, The Ledger is updated with insights and fails, and the output is clean, production-ready code. Skill: `gangsta:laundering`. ### The Ledger **Accounting:** A record book tracking history and accumulated knowledge. **Gangsta Agents:** Gangsta Agents' institutional memory — stored in `docs/gangsta/`. Contains Insights (successful patterns), Fails (documented mistakes), and the Constitution (accumulated rules). Unlike a session, The Ledger persists. Skill: `gangsta:the-ledger`. --- ## O ### Omerta **Mafia:** The mafia's code of silence — the rule that you never act outside sanctioned channels. Violating Omerta is a serious breach. **Gangsta Agents:** The five governance laws that prevent chaos in AI-assisted development: Introduction Rule, Rule of Availability, Rule of Truth, Rule of Budget, and Spec is Law. Always active. Non-negotiable. Skill: `gangsta:omerta`. See [Omerta — The Five Laws](https://gangsta.page/core-concepts/omerta). --- ## P ### Phase Gate **Process management:** A mandatory control point in a pipeline where you verify readiness before proceeding. **Gangsta Agents:** The mandatory checkpoint at the end of each Heist phase. The Don must explicitly approve before the next phase begins. There is no auto-advancing — ever. If the output isn't right, the phase is rejected and redone. --- ## R ### Reconnaissance **Military/Intelligence:** Scouting before an operation — gathering intelligence about the target environment. **Gangsta Agents:** Phase 1 of the Heist Pipeline. Associates survey the codebase, identify patterns, read documentation, and check The Ledger. The output is the Dossier. Skill: `gangsta:reconnaissance`. ### Resource Development **Project management:** Assembling the team, estimating effort, and planning execution before implementation. **Gangsta Agents:** Phase 4 of the Heist Pipeline. The Contract is decomposed into parallel work packages, territories are assigned to Crew Leads, and budgets are estimated. The output is the Execution Plan. Skill: `gangsta:resource-development`. --- ## S ### Shadow Hotfix **Software:** A code change made outside the official process — without authorization, review, or a spec. **Gangsta Agents:** Code written outside the Heist Pipeline — without a spec, without a Contract, without Don approval. The equivalent of a rogue Agent acting on their own. Violates Omerta Law #5 (Spec is Law). The framework is designed to make this impossible. ### The Sit-Down **Mafia:** A formal meeting between senior members to settle disputes, make agreements, or plan operations. **Gangsta Agents:** Phase 3 of the Heist Pipeline. The Contract is drafted — no code allowed. This phase is purely specification. If any code appears, the phase restarts. The Don signs the Contract before proceeding. Skill: `gangsta:the-sit-down`. ### Spec is Law **Gangsta Agents:** Omerta Law #5. The Contract (spec) is the authoritative source of truth. If code contradicts the spec, you revise the spec — not the code. Code is never the primary artifact. Implementation reveals a spec issue? Stop, propose a Contract revision, get Don approval, then resume. --- ## T ### Territory **Mafia/Military:** A defined area of responsibility or jurisdiction. **Gangsta Agents:** A domain of the codebase assigned to a Crew Lead during Resource Development. Territories prevent Agents from stepping on each other's work — each Crew Lead owns their domain and coordinates within it. --- ## U ### Underboss **Mafia:** The second-in-command of a crime family. Handles day-to-day operations, manages the crew, and acts when the Don is unavailable. **Gangsta Agents:** The Chief Operating Officer of the Gangsta Agents Family. Handles task decomposition, resource allocation, and planning. Dispatches work packages to Crew Leads and Agents. The operational layer between the Don's vision and the crew's execution. Skill: `gangsta:the-underboss`. --- ## W ### Worker **General:** The person or process that executes assigned tasks — no architectural authority, just implementation. **Gangsta Agents:** A stateless subagent that implements assigned tasks. Workers execute code per the Contract and Execution Plan, follow TDD (`gangsta:drill-tdd`), and report completion. They don't make architectural decisions — they execute. Dispatched by Crew Leads within territories. --- ## The 1% Rule **Gangsta Agents-specific:** If there's even a 1% chance a skill applies to what the agent is doing, it must be invoked. No rationalizing. No "this is probably simple enough to skip." The rule exists because agents are prone to convincing themselves that structure isn't needed — and that's exactly when it is. See: [The 1% Rule](https://gangsta.page/getting-started/the-1-percent-rule) # The Family vs. The Team ::div --- style: display:flex;align-items:center;gap:1.5rem;padding:1.25rem 1.5rem;background:var(--site-surface);border:1px solid var(--site-border);border-radius:0.75rem;margin-bottom:2.75rem; --- ![Gangsta Agents](https://gangsta.page/logo-light.svg){.dark:hidden style="height:4rem;width:auto;flex-shrink:0;"} ![Gangsta Agents](https://gangsta.page/logo-dark.svg){.hidden.dark:block style="height:4rem;width:auto;flex-shrink:0;"} :::div{style="display:flex;flex-direction:column;gap:0.375rem;"} [GANGSTA AGENTS]{style="font-size:0.6875rem;font-weight:800;letter-spacing:0.18em;text-transform:uppercase;color:var(--color-amber-500);"} [Spec-Driven Development Framework]{style="font-size:1rem;font-weight:600;color:var(--site-heading-h3h4);line-height:1.3;"} [Organized like a family. Built for humans and AI agents.]{style="font-size:0.875rem;color:var(--site-fg);opacity:0.55;line-height:1.5;"} ::: :: # The Family vs. The Team Agile gave us teams. Gangsta Agents gives us families. The difference is not aesthetic. It is not branding. It is a fundamentally different theory of how humans — and now agents — should organize around work that matters. ## The Team Is a Convenience An agile team is a temporary arrangement of interchangeable contributors. The methodology is explicit about this: roles are fluid, members are swappable, the backlog is the only thing that persists. When a sprint ends, the team disbands its commitments and starts fresh. When a member leaves, the standup continues without them by Wednesday. This is by design. Agile optimized for **throughput under uncertainty**. It assumed the work was unknowable, the requirements would change, and the safest bet was to keep everyone loosely coupled so the system could survive any single defection. It worked. For a while. For a kind of work. But loosely coupled people produce loosely coupled outcomes. When nobody owns the whole, nobody bleeds for the whole. ## The Family Is a Bond ![Agile Team vs Gangsta Agents Family — structure comparison](https://gangsta.page/family-vs-agile.svg){style="width:100%;border-radius:4px;margin:1.5rem 0 2rem;"} A family is not a team. It is a structure where every member has sworn — in blood, in code, by the rules — that the family's outcome is their personal outcome. There is no "I finished my ticket." There is only: *did the job get done, and did the family come out ahead?* This sounds like a metaphor. It is not. It is the operational reality of how Gangsta Agents runs. When the Underboss decomposes a contract into work packages, those packages are not Jira tickets to be picked up by whoever is available. They are **assignments to agents who will answer for the outcome**. When a Crew Lead reviews a deliverable from an agent, they are not running a code review checklist. They are asking: *did this agent honor the contract, or did they embarrass the family?* Every member feels the weight of every decision. That weight is not a burden — it is the source of the discipline. ## More Strict Than Agile Agile is permissive by default. The retrospective is where you discuss what went wrong. The sprint is where you ship anyway. Gangsta Agents does not work that way. The Contract is signed before any code is written. The Spec is supreme. An agent that deviates from the Contract — even with good intentions, even with a "better idea" — has violated the code. The Crew Lead will reject the deliverable. The Underboss will hear about it. The Don decides what happens next. There are no "let's just ship it and iterate." There is the Contract, Execution, The Delivery. Each phase has a gate. Each gate requires the Don's approval. There is no auto-advance. There is no "we'll fix it in the next sprint." ![The Gangsta Agents Heist Pipeline — 6 phases with Don-approved gates](https://gangsta.page/pipeline-flow.svg){style="width:100%;border-radius:4px;margin:1.5rem 0 2rem;"} This is stricter than any agile framework you have worked under. And it is stricter on purpose, because the cost of a quiet deviation in an AI-driven workflow is not a missed sprint goal — it is a hallucinated implementation that compounds across every downstream decision. ## More Adaptive Than Agile Here is the part that confuses people who only see the strictness: **Gangsta Agents is more adaptive than agile, not less.** Agile's adaptivity is bureaucratic. You adapt by waiting for the next planning meeting. You adapt by re-pointing stories. You adapt by negotiating scope with a product owner who is three layers removed from the work. In a family, adaptation happens at the speed of conversation. The Don speaks. The Underboss adjusts the execution plan. The Crew Lead redirects the agents. There is no ceremony to wait for. There is no quarterly roadmap to renegotiate. The Consigliere can call a truth check at any moment and stop a Heist that has gone off course — without anyone's permission, because the Consigliere stands outside the chain of command precisely so they can. The strictness is in the *structure*. The adaptivity is in the *response*. Agile inverted these and got slow rigidity dressed up as flexibility. Gangsta Agents inverts the inversion. ## Why This Matters Now When the workforce was entirely human, the difference between a team and a family was a matter of culture and tolerance for intensity. Some people thrive in families. Some people need the safety of teams. Both could ship software. That symmetry is broken now. AI agents do not need psychological safety. They need **constraints, ownership, and clear authority**. An agent given a Jira ticket and told to "just iterate" will hallucinate its way through six commits before lunch. An agent dispatched as an executor under a Crew Lead, against a signed Contract, with the Ledger watching, will produce work that survives review. The family structure is not a metaphor for AI orchestration. It is the most accurate organizational pattern we have found for it. Every member — human or agent — feels the weight. Every decision routes through a hierarchy that exists to be respected, not bypassed. Every deviation is named and accounted for. ## The Bond Is the Product Agile teams produce features. Gangsta Agents families produce outcomes — and the bond is what makes the outcome possible. When an agent knows the Crew Lead will review the deliverable against the Contract, they write the code differently. When a Crew Lead knows the Underboss will compare the territory's output against the execution plan, they review differently. When the Don knows the Consigliere has standing authority to stop the operation, they decide differently. This is not a hierarchy of distrust. It is a hierarchy of **mutual accountability**. Everyone is watching everyone, because everyone has sworn to the same outcome. That is what a family is. That is what a team can never be. *The Gangsta Agents Family does not have teammates. It has family.* # Spec-Driven Development in 2026 Ask Claude or Copilot to "add user authentication" and you'll get something. Whether that something matches what you actually need depends on twenty silent inferences the agent made: which auth pattern, which session strategy, which security level, which error handling. None of them written down. None of them reviewable. All of them yours to debug later. This is the structural failure SDD addresses. But "spec-first" is one principle implemented four very different ways. GitHub Spec Kit, OpenSpec, BMad Method, and Gangsta Agents agree that the spec comes before the code — they disagree on almost everything else: how strict the gates are, where the spec lives, whether agents debate, whether memory persists across sessions. I'll compare them across five axes that actually matter in practice: - **Spec scope** — feature-level (one change) or project-level (the whole project) - **Adversarial review** — is there a mechanism that attacks a proposal before code is written - **Gate strictness** — can the agent proceed without explicit human approval - **Institutional memory** — is experience preserved between sessions - **Cost of entry** — dependencies, setup time, learning curve Ecosystem metrics (stars, community, extensions) live in a separate table — they're useful, but they're not architecture. *Disclosure: I built Gangsta Agents. It's included for completeness, not promotion. Judge for yourself.* --- ## GitHub Spec Kit **88k stars** | [github.com/github/spec-kit](https://github.com/github/spec-kit){rel=""nofollow""} Official open-source project from GitHub, launched in 2025, with an active ecosystem of extensions and presets. **How it works:** Four phases with clear artifacts: Constitution → Specify → Plan → Tasks → Implement. Each phase is triggered via slash commands (`/speckit.constitution`, `/speckit.specify`, etc.) or agent skills. `Constitution.md` is an immutable document with project principles. Each phase is a handoff between the human (driving intent) and the AI (doing the writing). You don't move to the next phase until the current artifact is reviewed and accepted: - **Specify** — the developer writes what needs to be built and why. The AI generates a detailed spec covering user stories, acceptance criteria, workflows, and success metrics. No code, no implementation details. - **Plan** — the developer adds technical constraints (tech stack, architecture, compliance, performance). The AI produces a technical plan that respects those constraints. Alternative plans can be generated for comparison. - **Tasks** — the AI breaks work into small reviewable units. Each task is concrete and independently verifiable ("Create a user registration endpoint that validates email format" — not "build authentication"). - **Implement** — the AI executes each task. Code changes are traceable to specific requirements, not to a giant diff with unclear intent. The structure is the value. Each phase has a checkpoint where humans catch misalignment before it becomes rework. **Real workflow:** ```text /speckit.constitution Create principles focused on code quality and testing standards /speckit.specify Build a Kanban board with drag-and-drop, multiple users, no login /speckit.plan Use .NET Aspire, Postgres, Blazor server /speckit.tasks /speckit.implement ``` **Strengths:** - 50+ community extensions: Jira, Azure DevOps, GitHub Issues, worktrees, security review, V-Model, and more - Presets for customization without touching the core - Works with 28 AI agents: Claude Code, Gemini CLI, Copilot, Cursor, OpenCode, Codex, Kiro, Windsurf, and others - Ralph Loop — autonomous execution cycle for fully agentic implementation - Brownfield bootstrap extension for existing projects - Enterprise-ready: Azure DevOps, Jira integrations, compliance requirements **Weaknesses:** - Heavyweight: requires Python, uv, git - Phase gates exist but aren't strict — agent can continue without explicit approval - No adversarial review out of the box (extension only) - Spec lives at feature level, not project level **Best for:** If you already have Jira or Azure DevOps and need compatibility with your existing process — Spec Kit brings SDD without changing infrastructure. *Spec Kit is the most polished, most extensible, and most enterprise-ready of the four — but it pays for that with weight and bypassable gates.* --- ## OpenSpec **37.7k stars** | [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec){rel=""nofollow""} | [openspec.dev](https://openspec.dev){rel=""nofollow""} | YC W26 Built by Tabish (@0xTab), YC W26. Philosophy: fluid, not rigid. Iterative, not waterfall. **How it works:** Two key actions: ```text /opsx:propose "add dark mode" → creates openspec/changes/add-dark-mode/ ✓ proposal.md — why and what changes ✓ specs/ — requirements and scenarios ✓ design.md — technical approach ✓ tasks.md — implementation checklist /opsx:apply → executes all tasks ``` Each change lives in its own folder. Artifacts can be updated at any time — no strict phase transitions. **Spec deltas** — unique to OpenSpec. Every change produces a diff against the existing spec, not a new document. Reviewers see exactly what's changing in the requirements (added scenarios, modified behaviors, deleted constraints) before any code is written. Example: adding "Remember me" to authentication produces a delta showing the new scenario added to `auth-session/spec.md`, not a fresh spec file. Specs live in the codebase as permanent documentation. Other frameworks treat the spec as planning material that gets discarded after implementation. OpenSpec keeps specs in `openspec/specs/` organized by capability (`auth-login/`, `checkout-cart/`). When a new developer joins, they read the specs to understand what the code is supposed to do — not what it currently does. **Strengths:** - Minimal overhead: `npm install -g @fission-ai/openspec` - Brownfield-first — built for working with existing code - Iterative approach: spec evolves with the code - Active community: Discord, 37.7k stars - Works with 20+ tools **Weaknesses:** - Fluid means less structure — no strict gates - No adversarial review - No institutional memory between sessions - Spec quality is entirely on the developer **Best for:** If you want to try SDD today in 5 minutes on an existing project — this is the fastest start of the four. *OpenSpec treats specs as living code documentation through deltas — the lightest framework here, but you carry the discipline yourself.* --- ## BMad Method **44.2k stars** | [github.com/bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD){rel=""nofollow""} Full AI-driven framework for the entire development lifecycle — from idea to shipped code. Version 6, actively maintained. **How it works:** Specialized named agents guide the project through each phase. Modular architecture — extendable via BMad Builder. Four phases, each producing artifacts that feed the next: - **Analysis** (optional) — brainstorming, domain/market/technical research, product brief. Validates the idea before committing to planning. - **Planning** — PRD with functional and non-functional requirements + UX spec when relevant. - **Solutioning** — architecture document with ADRs, epics broken into stories, and an Implementation Readiness Check that produces a formal gate: PASS / CONCERNS / FAIL. - **Implementation** — sprint planning, story-by-story development, code review, retrospective. For small well-understood work, Quick Flow (`bmad-quick-dev`) skips phases 1–3 entirely — clarify intent, plan, implement, review in one unified pass. `project-context.md` — BMad's equivalent of Constitution. A document that captures technology stack, implementation rules, and project conventions. Generated from architecture or codebase, it guides every workflow. **Adversarial Review** is the recurring quality mechanism, used across the whole pipeline — code review, implementation readiness checks, spec validation. The reviewer agent must find issues — zero findings triggers a halt and re-analysis. The reviewer assumes problems exist and must surface them. Output is structured by severity: ```text - HIGH - login.ts:47 - No rate limiting on failed attempts - HIGH - Session token stored in localStorage (XSS vulnerable) - MEDIUM - Password validation happens client-side only - LOW - Magic number 3600 should be SESSION_TIMEOUT_SECONDS ``` Unlike Gangsta, there is no Nash Equilibrium as a stopping condition — the debate ends at the orchestrator's discretion. Human filtering is required: because the AI is instructed to find problems, false positives are expected. You decide what is real. **Strengths:** - Covers the full lifecycle: analysis → planning → implementation → verification - 12+ specialized named agents (PM, Architect, Developer, UX, Scrum Master, and more) - Adversarial Review as a built-in feature - Supports Agile-compatible workflows — iterative sprints, user stories, backlog - Large community: Discord, YouTube, active GitHub - Domain-specific modules: Game Dev Studio, Creative Intelligence Suite, Test Architect - Works with Claude Code, Cursor, Codex CLI **Weaknesses:** - High entry barrier — many concepts to learn upfront - Quality depends on installed modules (same applies to Spec Kit with its extensions) **Best for:** If you're building a new product from scratch and want AI at every stage from idea to deployment — BMad covers the full cycle. *BMad is the only framework that pairs full-lifecycle coverage with a built-in adversarial reviewer — pay the entry cost only if you'll use the whole pipeline.* --- ## Gangsta Agents **[github.com/kucherenko/gangsta](https://github.com/kucherenko/gangsta){rel=""nofollow""}** | [gangsta.page](https://gangsta.page){rel=""nofollow""} Agentic framework for spec-driven development built on the organizational model of the mafia. Zero dependencies, installs in one step. The newest entry of the four — first stable release v1.1.1 in April 2026 — so the comparison reflects an early-stage project rather than an established ecosystem. Gangsta is built on the principle of strict hierarchy and explicit gates — every decision is traceable to the contract, every agent answers only to its own level. Gangsta supports two modes: **manual mode** where the Don approves every phase gate, and **autonomous mode** where the entire pipeline runs end-to-end without human intervention. Choose based on the cost of failure for the task at hand. ![The Gangsta Agents Heist Pipeline — 6 phases with Don-approved gates](https://gangsta.page/pipeline-flow.svg){style="width:100%;border-radius:4px;margin:1.5rem 0 2rem;"} **How it works — 6-phase Heist Pipeline:** | Phase | What happens | Gate | | -------------------- | ------------------------------------------------------------- | --------------------------- | | Reconnaissance | Agents scan the codebase, read the Ledger | Don approves Dossier | | The Grilling | Adversarial debate: Proposer vs Devils-Advocate, min 2 rounds | Don approves consensus | | The Sit-Down | Formal contract — no code allowed | Don signs | | Resource Development | Decomposition into Work Packages | Don approves War Plan | | The Hit | Parallel execution, TDD mandatory | Don approves completion | | Laundering | Verification, integration, Ledger update | Don declares Heist complete | **Strict hierarchy:** Don (you) → Consigliere → Underboss → Capo → Soldier. No horizontal communication — only through the chain of command. ### The Grilling — unique feature Before any spec is written, three agents debate the solution: Proposer proposes the architecture, Devils-Advocate attacks (vulnerabilities, constitution violations, regression risks), Synthesizer integrates valid attacks and the Don's feedback. Minimum 2 rounds, maximum 7, exit only at **Nash Equilibrium** — when the Devils-Advocate can't raise a single new valid objection. ### The Sit-Down — real example Here's a fragment from a real contract in gangsta-money-tracker-example: ```text ## Functional Requirements - FR-001: Every transaction stores amount in original currency - FR-002: Every transaction stores amount_default in home currency - FR-003: Every transaction stores exchange_rate at create time - FR-008: Changing default currency recalculates ALL existing transactions ## Architectural Decisions - AD-001: Integer storage — no float rounding errors - AD-002: Currencies table in DB, not hardcoded enum - AD-005: Rate stored per-transaction, not computed at query time (exchange rates change; the rate at transaction time is correct) ``` No code. Just WHAT and WHY. ### Governance through Omerta — 5 laws: 1. **Introduction Rule** — no agent-to-agent communication without hierarchy mediation 2. **Rule of Availability** — all state saved to files before every phase transition 3. **Rule of Truth** — every claim cites its source. No citation — stronzate 4. **Rule of Tribute** — token and resource budgets are enforced 5. **Spec is Law** — if code contradicts the spec, the spec is revised. Never the reverse. ### Institutional Memory Gangsta stores history in the filesystem. After each Heist the Ledger is updated: successful patterns become Commandments, failures become Negative Constraints in the Constitution. During Reconnaissance, Associates scan the Ledger and include relevant entries in the next Heist's Dossier. ### Dev Skills — separate toolkit Beyond the Heist Pipeline, Gangsta ships 7 software development skills that can be invoked anywhere: - **Interrogation** — systematic debugging, finds the root cause before applying fixes - **The Drill** — TDD enforcement, no production code without a failing test first - **Safehouse** — git worktrees, isolated operational bases for parallel work - **The Audit** — code review with adversarial framing - **Receiving Orders** — processes user feedback with rigor, not blind agreement - **The Sweep** — verification through evidence, not assumption - **Exit Strategy** — clean branch integration and cleanup The **1% Rule** governs invocation: if there's even a 1% chance a skill applies, you invoke it. No rationalizing, no shortcuts. This prevents the "quick fix" mentality that compounds into technical debt. **Lightweight Heist** for minor fixes: the full 6-phase pipeline isn't always required. For minor fixes or known patterns, a lightweight version skips early phases. For new features, architectural changes, or non-trivial bugs — the full pipeline runs. **Strengths:** - The Grilling — the only adversarial debate with Nash Equilibrium and fixed rounds - Strict gates in manual mode — every phase requires explicit Don approval - Institutional Memory via Ledger - Zero dependencies — pure Markdown and shell scripts - TDD enforced at the architecture level - Native integration: Claude Code, GitHub Copilot, Gemini CLI, OpenCode, Codex. Cursor support via `npx skills add` **Weaknesses:** - Steep learning curve due to metaphors and hierarchy - 6-phase pipeline with gates is overkill for isolated single-agent tasks - Young project, community still forming **Best for:** If the cost of failure is high, the feature touches multiple domains, and you need full traceability of every decision back to the contract — Gangsta gives the strictest process of the four. *Gangsta Agents trades ceremony for traceability — the only framework with Nash Equilibrium debate and institutional memory, but the youngest of the four.* --- ## Comparison ### Autonomous execution: where the control boundary sits All four frameworks support autonomous execution — but the human control boundary differs: - **GitHub Spec Kit — Ralph Loop:** agent takes `tasks.md` and executes all tasks without stopping. Gates can be bypassed. - **OpenSpec — /opsx\:apply:** executes all tasks sequentially. Minimal gates, maximum autonomy. - **BMad Method — Orchestrator:** orchestrator agent guides execution through phases. Adversarial review built in, but no named loop. - **Gangsta Agents — Two modes:** in manual mode, Soldiers execute Work Packages with strict gates before and after the phase; in autonomous mode, the entire 6-phase pipeline runs end-to-end without human approval. ### Technical characteristics ![Technical characteristics comparison across four SDD frameworks](https://gangsta.page/tech.jpeg){style="width:100%;border-radius:4px;margin:1.5rem 0 2rem;"} ### Ecosystem | | GitHub Spec Kit | OpenSpec | BMad Method | Gangsta | | ------------ | --------------- | -------- | ----------- | ------- | | GitHub stars | 88k | 37.7k | 44.2k | — | | Extensions | 50+ | — | Modules | — | | Community | Large | Growing | Large | Forming | | AI agents | 28 | 20+ | 12+ | 5+ | Gangsta's Agile compatibility is low **by design**: each phase requires explicit human approval before proceeding, which conflicts with sprint-based iteration. This is optimized for traceability, not throughput. --- ## What all four share Despite different approaches, all four frameworks agree on one thing: **The human stays in the loop** — but not for everything. The agent acts on the rules and only stops where a human is actually needed: conflicting requirements, an architectural choice with real consequences, ambiguity affecting the system boundary. Uncertainty doesn't disappear into confident-sounding text — it gets logged explicitly. **Agent context matters more than agent capability.** When Andrej Karpathy named vibe coding in February 2025, the conversation focused on whether models were good enough. Two years later it's clear: the bottleneck isn't model capability. It's that the model has no contract. SDD does not guarantee correct decisions and does not replace architectural thinking. It reduces the probability of two specific failure modes: agents drifting off-spec due to missing constraints, and contradictions accumulating silently across sessions. The four frameworks sit on a spectrum from low ceremony to high traceability: - **OpenSpec:** minimal structure, maximum iteration speed, no gates - **Spec Kit:** structured phases, enterprise integrations, bypassable gates - **BMad:** full lifecycle, adversarial review, orchestrator-controlled flow - **Gangsta Agents:** strict gates at every phase, Nash Equilibrium debate, institutional memory Pick based on your failure cost and change velocity. Higher failure cost requires stricter gates. Higher change velocity requires lower ceremony. --- **GitHub Spec Kit:** [github.com/github/spec-kit](https://github.com/github/spec-kit){rel=""nofollow""} **OpenSpec:** [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec){rel=""nofollow""} | [openspec.dev](https://openspec.dev){rel=""nofollow""} **BMad Method:** [github.com/bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD){rel=""nofollow""} | [docs.bmad-method.org](https://docs.bmad-method.org){rel=""nofollow""} **Gangsta Agents:** [github.com/kucherenko/gangsta](https://github.com/kucherenko/gangsta){rel=""nofollow""} | [gangsta.page](https://gangsta.page){rel=""nofollow""} # Gangsta Agents — Run AI Agents Like the Mob ::u-page-hero #headline :hero-logo #title Code Like the Mob. #description Gangsta Agents is the AI skills framework for spec-driven development. No cowboy coding. No shadow hotfixes. Every feature runs The Heist — a 6-phase pipeline where specs are law and the Don always approves. #links :::u-button --- color: primary icon: i-lucide-arrow-right size: xl to: https://gangsta.page/getting-started/quickstart --- Start Your First Heist ::: :::u-button --- color: neutral icon: i-simple-icons-github size: xl to: https://github.com/kucherenko/gangsta variant: outline --- Star on GitHub ::: :: ::u-page-section #title The Gangsta Agents Family runs AI development. #description Every agent knows its role. Every task has a phase. Every phase gate requires the Don's approval. #features :::u-page-feature --- icon: i-lucide-file-check to: https://gangsta.page/core-concepts/spec-driven-dev --- #title Spec Before Code #description The Sit-Down phase produces a signed Contract. No worker writes code without one. ::: :::u-page-feature --- icon: i-lucide-library to: https://gangsta.page/skills --- #title Battle-Tested Skills #description Reconnaissance, TDD drills, interrogation debugging, exit strategies — each a pure markdown skill file. ::: :::u-page-feature --- icon: i-lucide-shield-alert to: https://gangsta.page/getting-started/the-1-percent-rule --- #title The 1% Rule #description If there's even a 1% chance a skill applies, you invoke it. No rationalizing. No shortcuts. ::: :::u-page-feature --- icon: i-lucide-network to: https://gangsta.page/core-concepts/the-borgata --- #title Multi-Agent Orchestration #description Underboss decomposes. Crew Leads orchestrate. Workers execute in parallel. The Gangsta Agents Family scales. ::: :::u-page-feature --- icon: i-lucide-terminal to: https://gangsta.page/getting-started/installation --- #title Multi-Platform Support #description Claude Code, GitHub Copilot, Gemini CLI, OpenCode, and Codex have native integrations. Cursor is supported via `npx skills add`. ::: :::u-page-feature --- icon: i-lucide-book-open to: https://gangsta.page/core-concepts/the-ledger --- #title Institutional Memory #description The Ledger persists insights and fails across sessions. The Gangsta Agents Family never forgets. ::: :: ::u-page-section #title The Heist Pipeline #description Every feature goes through 6 phases. No shortcuts. No skips. The Don approves every gate. :pipeline-flow :::u-button{color="primary" to="https://gangsta.page/heist-pipeline"} Explore Each Phase ::: :: ::u-page-section #title The Gangsta Agents Family Hierarchy #description Clear roles. Clear chain of command. The informed minority outperforms the uninformed majority. :hierarchy-tree :::u-button{color="primary" to="https://gangsta.page/core-concepts/the-borgata"} Understand the Hierarchy ::: :: ::u-page-section #title Run on any AI platform. #description Install once, invoke everywhere. Your agent gets the full Gangsta Agents Family. :platform-install :: ::u-page-section #title Omerta. Or else. #description Violation of the Five Laws is not a warning — it's a structural failure. The framework enforces discipline so your agents don't freelance. #features :::u-page-feature --- icon: i-lucide-users to: https://gangsta.page/core-concepts/omerta --- #title 1. Introduction Rule #description No agent-to-agent communication without hierarchy mediation. ::: :::u-page-feature --- icon: i-lucide-save to: https://gangsta.page/core-concepts/omerta --- #title 2. Rule of Availability #description All state checkpointed to files before phase transitions. ::: :::u-page-feature --- icon: i-lucide-eye to: https://gangsta.page/core-concepts/omerta --- #title 3. Rule of Truth #description Every claim must cite its source. Uncited = unverified. ::: :::u-page-feature --- icon: i-lucide-coins to: https://gangsta.page/core-concepts/omerta --- #title 4. Rule of Budget #description Resource budgets tracked and enforced per territory. ::: :::u-page-feature --- icon: i-lucide-scale to: https://gangsta.page/core-concepts/omerta --- #title 5. Spec is Law #description Code contradicts spec → revise the spec first. Never the reverse. ::: :: ::u-page-section #title Frequently Asked Questions #description Everything you need to know before joining the Family. :faq-accordion :: ::u-page-section #title Get Started #description Install Gangsta Agents and run your first Heist in under 5 minutes. #links :::u-button --- color: primary icon: i-lucide-arrow-right size: xl to: https://gangsta.page/getting-started/quickstart --- Start Your First Heist ::: :::u-button --- color: neutral icon: i-simple-icons-github size: xl to: https://github.com/kucherenko/gangsta variant: outline --- View on GitHub ::: ::