planwarden 0.3.0

CLI planning enforcer for AI agents
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

# planwarden

`planwarden` is a CLI planning enforcer for AI agents. The agent explores the repo and gathers facts; `planwarden` validates the planning contract, pushes back on weak slices, writes a durable plan file, walks the user through review one section at a time, and only surfaces execution chunks instead of a wall of text.

## Install

```bash
# Homebrew (recommended)
brew install nclandrei/tap/planwarden

# crates.io
cargo install planwarden --locked
```

## Quick Start

```bash
# 1. Investigate first, then ask for the contract.
planwarden schema review plan

# 2. Send structured findings to review.
planwarden review plan --input findings.json

# 3. Write the full plan file once review is ready.
planwarden create plan --input review.json

# 4. Review the draft section by section in chat.
planwarden review-next plans/my-plan.md --format text
planwarden advance-review plans/my-plan.md

# 5. Approve, start, and execute the plan.
planwarden approve plans/my-plan.md
planwarden start plans/my-plan.md
planwarden next plans/my-plan.md --format text
planwarden set-status plans/my-plan.md P1 in-progress
planwarden complete plans/my-plan.md
```

## Agent Workflow

1. The agent investigates the repo and request.
2. The agent runs `planwarden schema review plan|task` to see the contract.
3. The agent sends structured findings to `planwarden review plan|task`.
4. `planwarden` returns `decision`, `missing`, `questions`, `pushback`, and `normalized_plan`.
5. The agent resolves any gaps before creating the plan file.
6. The agent writes the full plan with `planwarden create`.
7. The agent immediately runs `planwarden review-next <plan-file> --format text`, shows only that section in chat, and advances review until every section is done.
8. The agent approves and starts the plan only after review is complete, then uses `planwarden next <plan-file> --format text` for execution chunks.
9. The plan moves through `draft -> approved -> in_progress -> done`.

## Working Contract

- The plan file is the source of truth; chat should stay chunked.
- The agent decides whether a concern applies and must justify `applicable = false`.
- `planwarden` enforces consistency, slice size, and required coverage.
- Bugfix work must prove red before green.

## Commands

- `planwarden schema review plan|task`
- `planwarden review plan|task`
- `planwarden create plan|task`
- `planwarden review-next <plan-file>`
- `planwarden advance-review <plan-file>`
- `planwarden next <plan-file>`
- `planwarden approve <plan-file>`
- `planwarden start <plan-file>`
- `planwarden set-status <plan-file> <item-id> <todo|in-progress|done>`
- `planwarden complete <plan-file>`

## Release Automation

Pushing a new version to `main` can be automated the same way as `distill`:

- build release artifacts with `cargo-dist`
- publish the crate to crates.io
- update the Homebrew formula in `nclandrei/homebrew-tap`
- publish the GitHub release

Required GitHub Actions secrets:

- `CARGO_REGISTRY_TOKEN`: crates.io publish token for `planwarden`
- `HOMEBREW_TAP_TOKEN`: GitHub token with push access to `nclandrei/homebrew-tap`

## License

MIT