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  docs/

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

OpenCode compatibility

OpenCode works great for interactive sessions and the native Desktop plugin, but cannot be used for autopilot — the CLI launches an interactive TUI that never exits. Use claude-code or codex for autopilot mode. See docs/opencode-compatibility-matrix.md for the full checklist.

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.