@pmelab/gtd 5.0.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +32 -19
  2. package/dist/gtd.bundle.mjs +281 -153
  3. package/docs/cli.md +85 -12
  4. package/docs/configuration.md +116 -51
  5. package/docs/development.md +7 -5
  6. package/docs/examples/advanced-workflow.md +33 -23
  7. package/docs/upgrading.md +49 -32
  8. package/package.json +1 -1
  9. package/schema.json +4 -0
package/README.md CHANGED
@@ -48,15 +48,23 @@ Or run without installing:
48
48
  npx @pmelab/gtd
49
49
  ```
50
50
 
51
- No config file, no setup subcommand — `gtd` auto-initializes a `.gtdrc.json`
52
- schema stub on first run (see [Configuration](docs/configuration.md#auto-init)).
51
+ Then scaffold a workflow for the repo — run once:
52
+
53
+ ```bash
54
+ gtd init simple # or: gtd init advanced
55
+ ```
56
+
57
+ This writes a `.gtdrc.json` with the chosen workflow inline (review and commit
58
+ it). gtd ships **no** default workflow: a state command run before `gtd init`
59
+ fails, pointing you back here. See
60
+ [Configuration](docs/configuration.md#gtd-init) for the two templates.
53
61
 
54
62
  ## How it works
55
63
 
56
64
  gtd is a small **pattern machine**: named states, each awaiting one actor and
57
65
  carrying one piece of content (a script, a prompt, a message, or a squash commit
58
66
  template), with an ordered set of change-patterns routing to the next state.
59
- Three commands drive it:
67
+ Four commands drive it:
60
68
 
61
69
  - **`gtd step <actor>`** — authenticate as `<actor>` and perform the one
62
70
  transition the pending changes match.
@@ -64,6 +72,9 @@ Three commands drive it:
64
72
  should do, without mutating anything.
65
73
  - **`gtd status`** — a dry-run report of the resolved state and which pattern
66
74
  each pending change matches.
75
+ - **`gtd review <commitish>`** — start a brand new review process reviewing
76
+ `<commitish>..HEAD` (e.g. a colleague's PR branch), reusing the workflow's
77
+ existing review/feedback machinery over that diff.
67
78
 
68
79
  The loop is one beat, repeated: run `gtd next --json` and dispatch on `kind` —
69
80
  `"message"` means it's a human's move (stop and hand off); `"script"` means the
@@ -73,20 +84,22 @@ never executes anything — the driver owns running scripts. See
73
84
  [STATES.md](STATES.md) for the model and [Driving the loop](docs/loop.md) for
74
85
  the full protocol.
75
86
 
76
- Along the way, the bundled default workflow develops your sketch into an
77
- implementation plan — asking any open question it can't settle itself via a
78
- deterministic `.gtd/TODO.md` format, validated before it ever reaches you —
79
- builds it, runs your tests (looping on failures), and hands you a
87
+ Along the way, the `simple` workflow (`gtd init simple`) develops your sketch
88
+ into an implementation plan — asking any open question it can't settle itself
89
+ via a deterministic `.gtd/TODO.md` format, validated before it ever reaches you
90
+ — builds it, runs your tests (looping on failures), and hands you a
80
91
  `.gtd/REVIEW.md` checkbox review of the cycle's diff: tick a box to approve that
81
- item, or edit/untick for feedback. Approving rests the cycle back at idle, with
82
- every turn commit still sitting in history for you to squash however you like
83
- (or not at all; gtd makes no assumption) — see
84
- [STATES.md](STATES.md#10-the-bundled-default-workflow) for the full shape. A
85
- heavier machine — two-phase Q&A planning, an architecture phase, task
86
- decomposition, a per-task build loop, and a squash finale — is preserved as a
87
- copy-paste `.gtdrc` example at
88
- [docs/examples/advanced-workflow.md](docs/examples/advanced-workflow.md). The
89
- workflow itself is just `.gtdrc` config — swap it for your own (see
92
+ item, or edit/untick for feedback. The same review flow also has a direct entry
93
+ point — `gtd review <commitish>` starts a brand new process reviewing
94
+ `<commitish>..HEAD` with no cycle of its own, e.g. a colleague's PR branch.
95
+ Approving rests the cycle back at idle, with every turn commit still sitting in
96
+ history for you to squash however you like (or not at all; gtd makes no
97
+ assumption) — see [STATES.md](STATES.md#10-the-bundled-workflow-templates) for
98
+ the full shape. The `advanced` template (`gtd init advanced`) is a heavier
99
+ machine — two-phase Q&A planning, an architecture phase, task decomposition, a
100
+ per-task build loop, and a squash finale — walked through at
101
+ [docs/examples/advanced-workflow.md](docs/examples/advanced-workflow.md). Either
102
+ way the workflow is just `.gtdrc` config — edit it or write your own (see
90
103
  [Configuration](docs/configuration.md)).
91
104
 
92
105
  `gtd-loop`, installed alongside `gtd`, is a ready-to-run driver for the whole
@@ -114,13 +127,13 @@ Both halves are enforced by `gtd validate` and the `gtd step` gate.
114
127
 
115
128
  - [STATES.md](STATES.md) — the full pattern-machine specification: the model,
116
129
  the pattern grammar, resolution, retry, the squash lifecycle, and the bundled
117
- default workflow
130
+ workflow templates
118
131
  - [CLI reference](docs/cli.md) — every command, exit codes, JSON schemas,
119
132
  repository requirements
120
133
  - [Driving the loop](docs/loop.md) — the reference loop driver, `gtd-loop`,
121
134
  custom agents
122
- - [Configuration](docs/configuration.md) — `.gtdrc` `workflow:` schema, lookup,
123
- auto-init
135
+ - [Configuration](docs/configuration.md) — `gtd init`, the `.gtdrc` `workflow:`
136
+ schema, lookup
124
137
  - [Upgrading](docs/upgrading.md) — breaking changes and migration
125
138
  - [Development](docs/development.md) — building, testing, releasing
126
139