xchecker 1.2.0

Spec pipeline with receipts and gateable JSON contracts
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# xchecker


[![Crates.io](https://img.shields.io/crates/v/xchecker.svg)](https://crates.io/crates/xchecker)
[![License](https://img.shields.io/crates/l/xchecker.svg)](https://github.com/EffortlessMetrics/xchecker#license)

Turn rough feature ideas into structured specs -- requirements, designs, and implementation tasks -- using LLM-powered orchestration.

## See It Work


```bash
# Check your environment is ready

$ xchecker doctor
  LLM provider: claude-cli ... ok
  Config: .xchecker/config.toml ... ok
  Permissions: artifacts/ ... ok

# Feed in a feature idea and generate requirements

$ echo "Build a REST API for user management" | xchecker spec my-api
  Phase: requirements ... done (12.4s)
  Artifact: specs/my-api/artifacts/00-requirements.md

# See where you are

$ xchecker status my-api
  Spec: my-api
  Completed: requirements
  Next: design

# Pick up where you left off

$ xchecker resume my-api --phase design
  Phase: design ... done (18.1s)
  Artifact: specs/my-api/artifacts/10-design.md
```

## What xchecker Does for You


- **Structured thinking, not blank-page paralysis.**
  You describe the idea; xchecker walks it through requirements, design, tasks, review, and fixup -- each phase building on the last.

- **Your secrets never leave your machine.**
  45+ secret patterns (API keys, tokens, credentials) are scanned and blocked before any content reaches an LLM. If a secret is detected, execution stops immediately.

- **Your work is never lost.**
  Every artifact is written atomically through a staging directory. Every execution produces an audit receipt with BLAKE3 hashes. You can resume from any phase at any time.

- **Works with your LLM.**
  Claude CLI, Gemini CLI, OpenRouter, or the Anthropic API. Switch providers with a flag; the pipeline stays the same.

- **CI-ready from day one.**
  Deterministic exit codes, JSON output on every command, and policy gates you can wire into any CI pipeline.

## Key Features


### Multi-Phase Orchestration


xchecker walks each spec through a sequential phase pipeline:

```
Requirements → Design → Tasks → Review → Fixup → Final
```

Each phase builds a context packet, invokes the LLM, and writes artifacts atomically. If a phase exceeds its `phase_timeout` (default 600s), execution stops with: "Phase execution exceeded timeout" and exit code 10.

### State Directory


xchecker stores all state in `.xchecker/` by default. Override the location with the `XCHECKER_HOME` environment variable:

```bash
XCHECKER_HOME=/tmp/build xchecker status my-feature
```

Directory structure:

```
.xchecker/
  specs/<spec-id>/
    artifacts/    # Generated requirements, design, and task documents
    receipts/     # Execution audit trails with BLAKE3 hashes
    context/      # Packet previews and debugging files
```

### Lockfile System


Lock reproducibility metadata (model version, CLI version, schema version) with `--create-lock`, then detect drift with `lock_drift` in status output. Use `--strict-lock` to fail hard on any drift.

### Fixup System


The fixup phase proposes file changes as unified diffs. By default, xchecker runs in Preview Mode — showing pending changes without applying them. Pass `--apply-fixups` to apply validated diffs to your working tree.

### Standardized Exit Codes


Every command sets a deterministic `exit_code` that matches the receipt's `exit_code` field:

| Code | Name | Description |
|------|------|-------------|
| 0 | SUCCESS | Operation completed |
| 2 | CLI_ARGS | Invalid arguments |
| 7 | PACKET_OVERFLOW | Packet size exceeded |
| 8 | SECRET_DETECTED | Secret found in packet |
| 9 | LOCK_HELD | Lock already held |
| 10 | PHASE_TIMEOUT | Phase timed out |
| 70 | CLAUDE_FAILURE | LLM provider failure |

## Install


```bash
cargo install xchecker
xchecker doctor
```

**Requirements:** Rust 1.89+ and a configured LLM provider ([Claude CLI](https://claude.ai/download), Gemini CLI, or an API key for OpenRouter/Anthropic).

To build from source:

```bash
git clone https://github.com/EffortlessMetrics/xchecker.git
cd xchecker && cargo install --path .
```

## Next Steps


| I want to...                        | Go to                                                       |
|-------------------------------------|-------------------------------------------------------------|
| Get running in 20 minutes           | [tutorials/QUICKSTART.md](docs/tutorials/QUICKSTART.md)     |
| Understand the full workflow        | [tutorials/SPEC_TO_PR.md](docs/tutorials/SPEC_TO_PR.md)     |
| Configure my LLM provider          | [guides/LLM_PROVIDERS.md](docs/guides/LLM_PROVIDERS.md)     |
| Set up CI gates                     | [guides/CI_SETUP.md](docs/guides/CI_SETUP.md)               |
| Look up a command or exit code      | [reference/CLI.md](docs/reference/CLI.md)                    |
| Understand how it works             | [explanation/ARCHITECTURE.md](docs/explanation/ARCHITECTURE.md) |
| Embed xchecker as a library        | [reference/CLI.md#embedding](docs/reference/CLI.md#embedding-as-a-library) |
| Contribute                          | [contributor/](docs/contributor/)                            |

## License


MIT OR Apache-2.0