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
135
136
137
138
139
140
141
142
143
144
145
146
147
148

# Full-Stack Next.js Example


This example demonstrates how to use xchecker to spec out a full-stack Next.js application.

## Overview


This showcase walks through the complete xchecker workflow for building a task management application with:
- Next.js 14 App Router
- TypeScript
- Prisma ORM with PostgreSQL
- NextAuth.js authentication
- Tailwind CSS styling

## Prerequisites


- xchecker installed (`cargo install xchecker`)
- Claude CLI installed and authenticated
- Node.js 18+ (for the actual Next.js development)

## Quick Start


### 1. Initialize the Spec


```bash
cd examples/fullstack-nextjs

# Initialize the spec from the template

xchecker template init fullstack-nextjs task-manager

# Or manually create with a problem statement

echo "Build a task management app with user auth and real-time updates" | xchecker spec task-manager
```

### 2. Run Through Phases


```bash
# Generate requirements

xchecker resume task-manager --phase requirements

# Review and continue to design

xchecker resume task-manager --phase design

# Generate implementation tasks

xchecker resume task-manager --phase tasks

# Check status at any point

xchecker status task-manager --json
```

### 3. Review Outputs


After each phase, review the generated artifacts in `.xchecker/specs/task-manager/artifacts/`:
- `00-requirements.md` - Detailed requirements
- `01-design.md` - Architecture and design
- `02-tasks.md` - Implementation tasks

## Directory Structure


```
examples/fullstack-nextjs/
├── README.md                    # This file
├── workspace.yaml               # Workspace configuration
├── .xchecker/
│   ├── config.toml             # xchecker configuration
│   └── specs/
│       └── task-manager/       # Example spec
│           ├── context/
│           │   └── problem-statement.md
│           └── artifacts/      # Generated artifacts
└── scripts/
    └── validate.sh             # Validation script for CI
```

## Configuration


The `.xchecker/config.toml` is pre-configured for Next.js development:

```toml
[defaults]
model = "haiku"

[selectors]
include = [
    "src/**/*.ts",
    "src/**/*.tsx",
    "app/**/*.ts",
    "app/**/*.tsx",
    "*.json",
    "*.md"
]
exclude = [
    "node_modules/**",
    ".next/**",
    "dist/**"
]
```

## Workflow Tips


### Dry Run Mode


Test the workflow without making Claude API calls:

```bash
xchecker resume task-manager --phase requirements --dry-run
```

### Check Gate Status


Verify the spec meets quality gates:

```bash
xchecker gate task-manager --min-phase design
```

### View Detailed Status


```bash
xchecker status task-manager --json | jq .
```

## CI Integration


This example includes a validation script that can be run in CI:

```bash
./scripts/validate.sh
```

The script verifies:
- Workspace configuration is valid
- Spec structure is correct
- Configuration files are parseable

## Next Steps


After completing the spec workflow:

1. Review the generated tasks in `artifacts/02-tasks.md`
2. Set up your Next.js project based on the design
3. Use the tasks as a development roadmap
4. Run `xchecker gate` in CI to ensure spec compliance

## Related Documentation


- [xchecker Configuration Guide](../../docs/CONFIGURATION.md)
- [Claude Code Integration](../../docs/CLAUDE_CODE_INTEGRATION.md)
- [CI Templates](../../docs/ci/gitlab.md)