Bastard

Build from many, better than all.

SDLC-as-Code for AI coding agents. Quality gates, Constitution-driven rules, structured commits, 8 specialized skills, and workflow commands — for whatever AI agent you already use.

Zero API keys. One command.

# Install globally (recommended — bastard available everywhere)
npm install -g @denis_hamon/bastard-cli

# Then:
bastard init my-project
bastard validate
bastard scan
bastard list

Or one-time without install: npx bastard-cli init Or without Node.js: curl -fsSL https://raw.githubusercontent.com/bastard-framework/bastard/main/install.sh | bash

Your agent reads CLAUDE.md automatically. Ask it to build something — it validates before it commits.

Why Bastard?

AI-generated code has 1.7x more issues than human code. Code acceptance rates sit below 44%. Every other agent trusts the LLM. Bastard verifies.

• Constitution — Immutable project rules enforced programmatically. "NEVER use var" isn't a suggestion — it's a gate.
• Quality Gates — Compile, test, Constitution, semgrep. Independent validation on every change.
• Bypass with Audit Trail — Gates can be bypassed, but the justification is recorded in the commit. Forever.
• 8 Skills — Developer, Architect, Researcher, QA Tester, UX Reviewer, Journey Mapper, State Modeler, Handoff Spec.
• 5 Workflow Commands — Quick-flow, full SDLC process, multi-layer review, design, test suite.
• Pre-commit Hook — Automatic enforcement. You can't commit without passing gates.
• Agent Hooks (experimental) — hooks.json triggers validation on file writes and session end.

Quick Start

# Install once (global)
npm install -g @denis_hamon/bastard-cli

# New project
bastard init my-project

# Existing project
cd my-project
bastard init
bastard scan                      # auto-detect stack, generate Constitution
bastard hooks                     # enforce gates on every commit

From Cursor or Claude Code:

npx bastard-cli migrate           # convert .cursorrules/CLAUDE.md to Constitution

How It Works

You: "Add user authentication with OAuth"
  |
Agent reads CLAUDE.md         --> knows the Bastard process
Agent reads CONSTITUTION.md   --> knows the project rules
  |
Agent writes code
  |
bash .bastard/scripts/validate.sh
  --> compile:      PASS
  --> test:         PASS
  --> constitution: PASS
  --> semgrep:      PASS (advisory)
  |
bash .bastard/scripts/commit.sh "Add OAuth"
  --> [bastard] Add OAuth
  --> Gates: compile: PASS, test: PASS, constitution: PASS
  --> Bypasses: none

If a gate fails:

constitution: FAIL — use `var` — use `const` or `let`
  ./auth.js:12: var token = getToken();

FAIL — Fix issues or --bypass=gate:"reason"

The Constitution

CONSTITUTION.md is the project's immutable law. Rules are enforced by validate.sh via inline comments:

## Never List

- **NEVER** use `var` — use `const` or `let`
  <!-- bastard-rule: pattern="\bvar\b" glob="*.js,*.ts" severity="error" -->

- **NEVER** use `eval()`
  <!-- bastard-rule: pattern="\beval\(" glob="*.js,*.ts" severity="error" -->

- **NEVER** commit `.env` files
  <!-- bastard-rule: file-exists=".env" severity="error" -->

Auto-generate a Constitution from your codebase:

bash .bastard/scripts/scan.sh

Supports: JavaScript/TypeScript, Python, Go, Rust. Detects frameworks, databases, cloud providers, CI/CD.

Skills

| Skill | When to use | |-------|------------| | developer | Implement features, fix bugs, write code | | architect | Design systems, make tech decisions, write ADRs | | researcher | Investigate technologies, compare options | | qa-tester | Write tests, design test plans, review coverage | | ux-reviewer | Heuristic evaluation (Nielsen's 10) + accessibility (WCAG 2.2) | | journey-mapper | Map user experience across stages and touchpoints | | state-modeler | Model behavior as finite state machines | | handoff-spec | Developer handoff specifications from designs |

All skills follow agentskills.io standard. Create custom skills:

# .bastard/skills/my-skill.md
---
name: my-skill
description: What it does and when to use it.
---
Instructions here.

Commands

| Command | Workflow | |---------|---------| | quick-flow | Plan → code → validate → commit | | full-process | Research → architecture → implement → test → validate → commit | | review | UX + quality gates + Constitution (multi-layer) | | design | Journey map → state model → handoff spec | | test-suite | Analyze → plan → write tests → validate |

Enforcement

Git pre-commit hook (recommended):

bash .bastard/scripts/install-hooks.sh

Gates run automatically on every git commit. Failures block the commit.

Agent hooks (hooks.json):

• PreToolUse on Write/Edit — Constitution check before file writes
• Stop — Full validation when agent session ends

Bypass

When a gate fails and you have a valid reason:

bash .bastard/scripts/validate.sh --bypass='constitution:"Legacy code requires var"'

The bypass and justification are recorded in the commit metadata. No silent failures.

What Gets Installed

CLAUDE.md                              Agent instructions + skill table
PROJECT.md                             Project metadata
STATE.md                               Current state
CONSTITUTION.md                        (via scan.sh) Immutable rules
hooks.json                             Agent-native enforcement hooks
.bastard/
  scripts/
    validate.sh                        4 quality gates
    check-constitution.sh              Rule parser + grep enforcement
    check-constitution-live.sh         Pre-write Constitution check
    commit.sh                          Structured commits
    scan.sh                            Auto-detect stack → Constitution
    migrate.sh                         Convert .cursorrules/CLAUDE.md
    install-hooks.sh                   Git pre-commit hook installer
  commands/
    quick-flow.md                      Plan → code → validate → commit
    full-process.md                    Full SDLC workflow
    review.md                          Multi-layer review
    design.md                          UX design workflow
    test-suite.md                      Test coverage workflow
  skills/
    developer.md                       Code implementation
    architect.md                       System design + ADRs
    researcher.md                      Technical research
    qa-tester.md                       Testing + coverage
    ux-reviewer.md                     Usability + accessibility
    journey-mapper.md                  User journey maps
    state-modeler.md                   State machines
    handoff-spec.md                    Design-to-dev specs

Compatible With

Works with any AI agent that reads project files and runs shell commands:

• Claude Code — reads CLAUDE.md + hooks.json natively
• GitHub Copilot — reads CLAUDE.md, hooks.json, skills
• Cursor — reads CLAUDE.md / .cursorrules
• Cline — reads CLAUDE.md
• Aider — works via terminal commands
• Hermes Agent — agentskills.io compatible skills

Dogfooding

Bastard manages itself. This repo uses its own Constitution, quality gates, and pre-commit hook. Every commit passes 4 gates before it lands.

Why "Bastard"?

Built from many — patterns absorbed from BMAD, GSD, Aider, Hermes, Claude Code, Cursor, awesome-copilot. Better than all — the only one with Constitution + quality gates + audit trail + 8 skills + workflow commands. A hybrid with no pure lineage — and proud of it.

License

MIT