Quickstart

Five minutes from clone to your first flow-policed commit.

Prerequisites

  • Node 20+ and pnpm 10+ (the monorepo uses pnpm workspaces).
  • git and a repo you'd like to work in.
  • One coding-agent runtime: Claude Code (best supported), Cursor, Codex CLI, or OpenCode. xCoder wraps whichever you use.

1. Install xCoder

Private alpha — not on npm yet

v0.1.0-alpha.0 ships from the source repo. Once it's published you'll be able to npm i -g @xcoder/xcoder@alpha. Until then, install from the local clone:

bash
git clone https://github.com/DecOperations/xCoder.WTF.git
cd xCoder.WTF
pnpm install
pnpm install:local      # runs `pnpm build && npm link`

xc --version            # 0.1.0-alpha.0

2. Infer guidelines from your project

xCoder reads your repo to derive what counts as “branched correctly,” “QA passed,” etc. — your package.json scripts, git log dominant prefixes, eslint config, CLAUDE.md, CI workflows, and so on:

bash
cd ~/code/your-project
xc flow guidelines refresh       # writes .xcoder/guidelines.cache.json
xc flow guidelines show          # review what was inferred

Output looks like:

text
Resolved guidelines
  source       inferred
  cache file   .xcoder/guidelines.cache.json
  config file  (none)

specify
    required   true
    spec path  specs/

branched
    off        main
    prefix     feat/ | fix/ | docs/ | test/ | chore/

qa
    typecheck  pnpm run type-check
    test       pnpm run test
    lint       pnpm run lint

prioritize
    source     github-issues

3. Override anything you don't like (optional)

Drop a .xcoder/guidelines.yaml with the keys you want to pin. Config beats inferred beats default:

yaml
# .xcoder/guidelines.yaml
specify:
  specRequired: true
  specPath: docs/specs/

branched:
  prefix: ['feat/', 'fix/']
  off: develop

qa:
  typecheck: pnpm run typecheck
  test: pnpm run test
  lint: pnpm run lint

4. Attach the SDLC flow to your coding agent

One command compiles the bundled SDLC flow + your guidelines into the host agent's hook config:

bash
xc flow attach claude-code         # writes .claude/settings.json
# also supported: cursor, codex, opencode
xc flow attach cursor              # writes .cursor/hooks.json
xc flow attach codex               # writes .codex/hooks.json
xc flow attach opencode            # writes .opencode/plugins/xcoder.ts

From this point on, every Edit, Write, Bash, etc. call from your coding agent passes through the flow's policies.

5. The policies in action

Open your coding agent and try a few things:

  • Edit a file while on main → BLOCKED by no-edit-on-integration.
  • git checkout -b randomname → BLOCKED by branch-prefix-must-match.
  • git checkout -b feat/oauth → ALLOWED.
  • git commit -m "fix typo" → BLOCKED by commit-must-reference-issue (when specRequired: true).
  • git commit -m "feat: oauth #142" → BLOCKED by typecheck-must-pass-before-commitif you haven't run QA yet.

6. Run QA before committing

Heavy verification (typecheck, tests) doesn't run inside the synchronous hook — it runs out of band and writes a verdict that the next commit-hook reads. Run it before each commit cycle:

bash
xc qa typecheck          # runs guidelines.qa.typecheck → writes verdict
xc qa test               # runs guidelines.qa.test → writes verdict
xc qa lint               # runs guidelines.qa.lint → writes verdict
xc qa show               # show all current verdicts + ages

git commit -m "feat: oauth #142"     # now allowed

Verdicts older than 5 minutes are treated as missing — rerun xc qa typecheck after each round of edits.

7. Bypass when you really need to

Each policy has a documented escape hatch for legitimate hotfix / WIP cases:

bash
# bypass no-edit-on-integration for hotfix
XCODER_ALLOW_INTEGRATION_EDIT=1

# bypass typecheck gate (e.g. for WIP commit)
XCODER_SKIP_QA_GATE=1

# bypass issue-ref check
XCODER_SKIP_ISSUE_REF=1

# git's own bypasses also recognized
git commit -m "wip" --no-verify
git commit --amend
git commit --allow-empty

That's it.

Your coding agent now executes against a declared flow graph with pre/post hooks, evidence-based gates, and a deterministic policy set. Every step is enforced; every override is logged.

Next

Configure / customize policies →

Override guidelines, write your own flow, add new policies.

Mental model →

How flow-engine, hooks, and the SDLC flow fit together.

CLI reference →

Every xc command with examples.

Flow engine →

The runtime that wraps your coding agent.