Gangsta Agents
An AI agentic skills framework for spec-driven development, built on the organizational model of mafia.
Philosophy
Gangsta Agents replaces open-ended Agile iteration with a directive, vertical hierarchy. A small team of highly specialized agents — each operating with autonomy within their Position — outperforms a large pool of general-purpose agents.
The Spec is Law. Code is an implementation detail validated against the specification. No shadow hotfixes.
The Informed Minority. Clear roles, clear hierarchy, clear accountability.
How It Works
When you start a session, the framework bootstraps The Don — an orchestrator that analyzes your intent and routes to the appropriate skill. When you want to build something, it initiates a Heist: a 6-phase operational cycle.
The Heist Pipeline
| Phase | Skill | What Happens | Gate |
|---|---|---|---|
| 1. Reconnaissance | gangsta:reconnaissance | Intel gathering on codebase and requirements | Dossier |
| 2. The Grilling | gangsta:the-grilling | Adversarial brainstorming via Multi-Agent Debate (Proposer vs Devils-Advocate, with you weighing in each round) | Consensus |
| 3. The Sit-Down | gangsta:the-sit-down | Formal spec drafting. No code allowed. | Contract |
| 4. Resource Development | gangsta:resource-development | Task decomposition into Work Packages and Execution Plan | Execution Plan |
| 5. Execution | gangsta:the-hit | Parallel execution by Worker subagents with TDD enforcement | Completion |
| 6. The Delivery | gangsta:laundering | Verification, integration, and Ledger update | Ledger |
Every phase gate requires your approval. You are the Don.
→ Full Heist Pipeline documentation
Autonomous Mode
The default Heist pauses for Don approval at every phase gate. Autonomous Mode is an opt-in fast path that delegates per-phase gating to a don-proxy surrogate while preserving the Don's terminal authority.
| Aspect | Default Heist | Autonomous Mode |
|---|---|---|
| Per-phase approval | Don at each gate | gangsta:don-proxy |
| Sit-Down sign-off | Don signs Contract | don-proxy signs as pending-don-confirmation |
| Sit-Down review | Consigliere advisory | Dual-Veto — Consigliere AND don-proxy, either REJECT is terminal |
| Terminal authority | Don | Don, via /gangsta:go (sign), /gangsta:abort (reject), Consigliere veto |
| Constitutional Floor | N/A | Mandatory rejection of artifacts violating Omerta or Negative Constraints |
Slash commands:
| Command | Purpose |
|---|---|
/gangsta:heist <feature> | Run Phases 1–4 (Reconnaissance → Grilling → Sit-Down → Resource-Development) autonomously. Produces don-proxy-signed Contract and Plan in pending-don-confirmation state. |
/gangsta:go [feature] | Don signing event. Flips pending-don-confirmation → confirmed, then runs Phases 5–6 (the Hit + Laundering). Resolves the most recent Heist via docs/gangsta/.last-heist when feature is omitted. |
/gangsta:abort <feature> | Rejects a pending Heist. Relocates docs/gangsta/<feature>/ to docs/gangsta/.aborted/<feature>-<timestamp>/ with an abort marker. Excluded from future ledger reads. |
Flags on /gangsta:heist:
--retries <1-10>(default3) — per-phase retry budget before escalation--rounds <1-7>(default3) — Grilling rounds;--rounds=1is the minimum-cost fast path--best-effort <bool>(defaulttrue) — continue past non-terminal failures with deviation reports
Lifecycle states for autonomous artifacts: pending-don-confirmation → confirmed (via /gangsta:go) or rejected (via /gangsta:abort). Constitutional Floor REJECTs are terminal in any phase and cannot be retried regardless of --best-effort.
Note: Autonomous Mode is positioned as a structured fast path, not a token-cost reduction. Mandatory adversarial Grilling is preserved — there is no flag to bypass it.
The Gangsta Agents Family Hierarchy
| Role | Function |
|---|---|
| Don (You) | Supreme authority. Approves all phase gates. |
| Consigliere | Impartial advisor. Security and architecture auditor. |
| Don-Proxy | Surrogate Don for autonomous mode. Bounded by the Constitutional Floor. |
| Underboss | COO. Task decomposition, resource allocation. |
| Crew Lead | Domain crew lead. Manages Workers per territory. |
| Worker | Stateless code executor. TDD enforced. |
| Associate | External tool/API proxy. |
→ Full Hierarchy documentation
The Family Ledger
The Gangsta Agents Family maintains institutional memory across all Heists:
- Insights — Successful reasoning pathways and creative solutions
- Fails — Documented failures with cognitive diagnoses and negative constraints
- Constitution — Accumulated commandments and prohibitions
Software Development Skills
| Skill | Purpose |
|---|---|
| Interrogation | Systematic debugging — find the rat before applying fixes |
| The Drill | TDD enforcement — no code without a failing test |
| Safehouse | Git worktrees — isolated operational bases |
| The Audit | Code review — the-inspector checks the work |
| Receiving Orders | Process feedback with rigor, not blind agreement |
| The Sweep | Verification — evidence before completion claims |
| Exit Strategy | Branch integration and cleanup |
→ Full Dev Skills documentation
Omerta: Governance
Five non-negotiable laws govern all operations:
- Introduction Rule — No agent-to-agent communication without hierarchy mediation
- Rule of Availability — All state checkpointed to files
- Rule of Truth — Every claim cites its source. No invalid claims.
- Rule of Budget — Resource budgets tracked and enforced
- Spec is Law — Code contradicts spec → spec is revised first
Installation
Universal (any agent)
Install to all detected agents at once using the skills CLI:
npx skills add kucherenko/gangsta
Install globally (available across all projects):
npx skills add kucherenko/gangsta --global
Install to a specific agent only:
npx skills add kucherenko/gangsta -a cursor npx skills add kucherenko/gangsta -a claude-code npx skills add kucherenko/gangsta -a opencode
Cursor
npx skills add kucherenko/gangsta -a cursor --global
Skills are installed to ~/.cursor/skills/ (global) or .agents/skills/ (project).
Claude Code
/plugin marketplace add kucherenko/gangsta /plugin install gangsta@gangsta
GitHub Copilot
copilot plugin marketplace add kucherenko/gangsta copilot plugin install gangsta@gangsta-marketplace
OpenCode
Tell OpenCode:
Fetch and follow instructions from https://raw.githubusercontent.com/kucherenko/gangsta/refs/heads/master/.opencode/INSTALL.md
Codex
Tell Codex:
Fetch and follow instructions from https://raw.githubusercontent.com/kucherenko/gangsta/refs/heads/master/.codex/INSTALL.md
Gemini CLI
gemini extensions install https://github.com/kucherenko/gangsta
Verify Installation
Start a new session and say:
"I want to build a new feature"
The agent should invoke Gangsta Agents skills automatically, starting with Reconnaissance.
License
MIT