kadence 0.1.4 → 0.1.5
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.
- package/CHANGELOG.md +11 -0
- package/README.md +121 -166
- package/dist/cli.js +1 -1
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,16 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.1.5] — 2026-09-03
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- README rewritten to lead with the number the product exists for — what a
|
|
8
|
+
story point actually costs — instead of a feature list. Claims now carry
|
|
9
|
+
their evidence inline: the merge thesis links to the 8,396-commit study and
|
|
10
|
+
to the integration test that proves it, and the performance table says these
|
|
11
|
+
are tests that fail the build.
|
|
12
|
+
- Repository URLs follow the rename to `bogutskiandriy/kadence`.
|
|
13
|
+
|
|
3
14
|
## [0.1.4] — 2026-09-03
|
|
4
15
|
|
|
5
16
|
### Fixed
|
package/README.md
CHANGED
|
@@ -1,236 +1,191 @@
|
|
|
1
1
|
# kadence
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
|
|
5
|
-
Tasks, sprints and velocity as plain files inside your git repo. No server, no
|
|
6
|
-
account, no network. Works offline, and works for AI agents because the data is
|
|
7
|
-
just files they can read.
|
|
3
|
+
**Sprint tracking that lives in your git repo — and tells you what a story point actually costs.**
|
|
8
4
|
|
|
9
5
|
```bash
|
|
10
6
|
npm install -g kadence
|
|
11
|
-
|
|
12
7
|
kadence init
|
|
13
|
-
kadence task add "Fix login" -d "Broken since 2.3" --type bug --estimate 3
|
|
14
|
-
kadence ui # interactive board, or `kadence board` for a plain list
|
|
15
8
|
```
|
|
16
9
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
> with users yet. See [Honest status](#honest-status).
|
|
10
|
+
No server. No account. No network. Your tasks are files next to your code, and
|
|
11
|
+
they move with your branches.
|
|
20
12
|
|
|
21
|
-
|
|
13
|
+
---
|
|
22
14
|
|
|
23
|
-
|
|
24
|
-
[git-bug](https://github.com/git-bug/git-bug),
|
|
25
|
-
[Backlog.md](https://github.com/MrLesk/Backlog.md),
|
|
26
|
-
[git-issues](https://steviee.github.io/git-issues/). kadence differs in two ways.
|
|
15
|
+
## The number nobody has
|
|
27
16
|
|
|
28
|
-
|
|
29
|
-
so two branches touching one task collide. kadence stores an append-only journal
|
|
30
|
-
of events: one file per event, never rewritten.
|
|
17
|
+
Every team estimates in points. Almost none can say what a point costs them.
|
|
31
18
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
in 15% of repositories — and **89% of them are `CONFLICT (content)`**, exactly
|
|
35
|
-
the type this design eliminates. Full data:
|
|
36
|
-
[probe-a-results.md](docs/research/probe-a-results.md).
|
|
19
|
+
```
|
|
20
|
+
$ kadence sprint close
|
|
37
21
|
|
|
38
|
-
|
|
39
|
-
estimates compare with reality. kadence derives all of it from the journal, so
|
|
40
|
-
the numbers cannot be forgotten or faked — they are a product of the work.
|
|
22
|
+
Sprint "Sprint 14" closed.
|
|
41
23
|
|
|
42
|
-
|
|
43
|
-
|
|
24
|
+
Velocity: 23 of 28 points
|
|
25
|
+
Actual: 37h — 1.6h per point
|
|
44
26
|
|
|
45
|
-
|
|
46
|
-
|
|
27
|
+
Carried over (2):
|
|
28
|
+
· KAD-12 Auth refactor
|
|
47
29
|
```
|
|
48
30
|
|
|
49
|
-
|
|
50
|
-
|
|
31
|
+
`1.6h per point` is derived from the journal — every state change your team
|
|
32
|
+
already made, timestamped. Nobody fills in a form. Nobody can forget to update
|
|
33
|
+
it. Next sprint you plan against a measured number instead of a feeling.
|
|
51
34
|
|
|
52
|
-
##
|
|
35
|
+
## Three things a browser tab cannot do
|
|
53
36
|
|
|
54
|
-
|
|
37
|
+
**Your board is in the commit.** `git checkout` a release from three months ago
|
|
38
|
+
and the tasks are exactly as they were that day. Not roughly — the same files.
|
|
55
39
|
|
|
56
|
-
|
|
40
|
+
**Merges do not fight you.** Two people editing one task on two branches is a
|
|
41
|
+
conflict in every file-based tracker. Here it is not, by construction: the
|
|
42
|
+
journal is append-only, one file per event.
|
|
57
43
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
kadence init
|
|
61
|
-
```
|
|
44
|
+
**Agents read it without a bridge.** No MCP server, no token, no network. It is
|
|
45
|
+
files, plus `--json` on every command.
|
|
62
46
|
|
|
63
|
-
|
|
64
|
-
one command and leaves nothing behind, so every later call needs `npx` too:
|
|
47
|
+
---
|
|
65
48
|
|
|
66
|
-
|
|
67
|
-
npx kadence init
|
|
68
|
-
npx kadence board
|
|
69
|
-
```
|
|
49
|
+
## Why the merge claim holds
|
|
70
50
|
|
|
71
|
-
|
|
72
|
-
short guide for AI agents. It does **not** commit anything — that call is yours.
|
|
51
|
+
We measured it before building on it.
|
|
73
52
|
|
|
74
|
-
|
|
53
|
+
Across **8,396 merge commits in 130 public repositories** using file-based
|
|
54
|
+
trackers, conflicts in task files hit **15% of repositories** — and **89% are
|
|
55
|
+
`CONFLICT (content)`**, the exact type an append-only journal removes.
|
|
75
56
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
kadence task add "<title>" create a task
|
|
81
|
-
-d, --description <text> full description
|
|
82
|
-
--type task|bug|story|epic type; an epic is simply a parent task
|
|
83
|
-
--priority low|normal|high|urgent
|
|
84
|
-
-a, --assignee <who> assignee
|
|
85
|
-
--label <name> label; repeat for several
|
|
86
|
-
--due <date> deadline, YYYY-MM-DD
|
|
87
|
-
--parent <task> make it a subtask
|
|
88
|
-
--template <name> pre-fill from a saved template
|
|
89
|
-
--estimate <points> estimate, always last
|
|
90
|
-
kadence task list list tasks
|
|
91
|
-
--search <text> title, description and comments
|
|
92
|
-
--status|--type|--priority|--assignee|--label
|
|
93
|
-
--overdue --due-before <date>
|
|
94
|
-
--sort created|priority|due|estimate
|
|
95
|
-
--tree show parent/child structure
|
|
96
|
-
kadence task show KAD-1 full detail and history
|
|
97
|
-
kadence task edit KAD-1 opens $EDITOR; or pass field flags
|
|
98
|
-
kadence task move KAD-1 done change state
|
|
99
|
-
kadence task assign KAD-1 <who> assign; "none" unassigns
|
|
100
|
-
kadence task comment KAD-1 "text" comment
|
|
101
|
-
kadence task log KAD-1 2h log time; 90m, -30m to correct
|
|
102
|
-
kadence task parent KAD-2 KAD-1 nest under a parent
|
|
103
|
-
kadence task block KAD-2 KAD-1 KAD-2 waits for KAD-1
|
|
104
|
-
kadence task cancel KAD-1 keeps it in history
|
|
105
|
-
kadence task delete KAD-1 drops it from the board
|
|
106
|
-
|
|
107
|
-
kadence board plain board, one column per status
|
|
108
|
-
-a, --assignee me only your tasks
|
|
109
|
-
--sprint only the active sprint
|
|
110
|
-
kadence board config show or change the columns
|
|
111
|
-
--statuses "todo,doing,done" your own workflow
|
|
112
|
-
|
|
113
|
-
kadence sprint create "Sprint 1" first starts now, later ones are planned
|
|
114
|
-
kadence sprint add KAD-1 [--sprint "Sprint 2"]
|
|
115
|
-
kadence sprint start ["Sprint 2"] start the next planned sprint
|
|
116
|
-
kadence sprint close close and report velocity
|
|
117
|
-
kadence sprint status progress of the active sprint
|
|
118
|
-
kadence sprint burndown chart rebuilt from the journal
|
|
119
|
-
kadence sprint list every sprint
|
|
120
|
-
|
|
121
|
-
kadence template save bug --type bug --priority high
|
|
122
|
-
kadence template list | delete <name>
|
|
123
|
-
```
|
|
57
|
+
Then the other direction: three people editing one task on three branches,
|
|
58
|
+
merged in every order. Zero conflicts, every author preserved, identical final
|
|
59
|
+
state. That is an [integration test](test/integration/merge.test.ts), not a
|
|
60
|
+
claim.
|
|
124
61
|
|
|
125
|
-
|
|
126
|
-
— and apply **all or nothing**: if one id does not exist, nothing changes.
|
|
62
|
+
Full data: [probe-a-results.md](docs/research/probe-a-results.md).
|
|
127
63
|
|
|
128
|
-
|
|
64
|
+
---
|
|
129
65
|
|
|
130
|
-
##
|
|
66
|
+
## In practice
|
|
131
67
|
|
|
132
|
-
```
|
|
133
|
-
kadence
|
|
68
|
+
```bash
|
|
69
|
+
kadence init
|
|
70
|
+
|
|
71
|
+
kadence sprint create "Sprint 14"
|
|
72
|
+
kadence task add "Fix login" -d "Broken since 2.3" --type bug --priority high --estimate 3
|
|
73
|
+
kadence sprint add KAD-1
|
|
74
|
+
kadence task move KAD-1 done
|
|
75
|
+
kadence sprint close
|
|
134
76
|
```
|
|
135
77
|
|
|
136
|
-
|
|
78
|
+
**The board, when you want to look at it:**
|
|
137
79
|
|
|
138
80
|
```
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
81
|
+
$ kadence ui
|
|
82
|
+
|
|
83
|
+
kadence Sprint 14 9 tasks, 28 points
|
|
84
|
+
+- backlog (2) -------++- in_progress (1) --++- in_review (1) ----++- done (3) ---------+
|
|
85
|
+
| ^# KAD-1 Auth epic || . KAD-4 Tokens @dev||!! KAD-7 Crash [] || v KAD-2 Export |
|
|
86
|
+
| * KAD-3 Login form || || || v KAD-5 Docs |
|
|
87
|
+
+---------------------++--------------------++--------------------++--------------------+
|
|
88
|
+
arrows move enter details m status a assign e edit s sprint / filter q quit
|
|
144
89
|
```
|
|
145
90
|
|
|
146
|
-
|
|
147
|
-
the
|
|
148
|
-
does, so the board can never disagree with the terminal.
|
|
149
|
-
|
|
150
|
-
The board loads its UI layer lazily — `kadence task add` never pays for it.
|
|
91
|
+
Keyboard, mouse, drag between columns, every field editable in place. It calls
|
|
92
|
+
the same commands the CLI does, so the two can never disagree.
|
|
151
93
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
Tasks are files. An agent reads them directly, or through the CLI — no MCP
|
|
155
|
-
server, no token, no network:
|
|
94
|
+
**For an agent:**
|
|
156
95
|
|
|
157
96
|
```bash
|
|
158
97
|
kadence board --json
|
|
159
|
-
kadence task list --json --status in_progress --sort priority
|
|
160
|
-
kadence task show KAD-1 --json
|
|
161
|
-
kadence sprint status --json
|
|
162
98
|
KADENCE_SOURCE=agent kadence task move KAD-1 in_progress
|
|
163
99
|
```
|
|
164
100
|
|
|
165
|
-
Every
|
|
166
|
-
|
|
167
|
-
`2` bad arguments.
|
|
101
|
+
Every response carries `schema: "kadence/v1"`. stdout is JSON and nothing else;
|
|
102
|
+
warnings go to stderr. `init` writes a guide the agent finds on its own.
|
|
168
103
|
|
|
169
|
-
|
|
170
|
-
finds this on its own.
|
|
104
|
+
---
|
|
171
105
|
|
|
172
|
-
##
|
|
106
|
+
## Commands
|
|
173
107
|
|
|
174
108
|
```
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
109
|
+
kadence init set up in this repository
|
|
110
|
+
kadence ui interactive board
|
|
111
|
+
|
|
112
|
+
kadence task add "<title>" -d --type --priority -a --label --due
|
|
113
|
+
--parent --template --estimate
|
|
114
|
+
kadence task list --search --status --assignee --overdue
|
|
115
|
+
--sort --tree
|
|
116
|
+
kadence task show KAD-1 detail, comments and history
|
|
117
|
+
kadence task edit KAD-1 opens $EDITOR, or pass field flags
|
|
118
|
+
kadence task move KAD-1 done also: assign, comment, log, parent, block,
|
|
119
|
+
cancel, delete
|
|
120
|
+
kadence board plain columns; `board config` sets your own
|
|
121
|
+
kadence sprint create|add|start|close|status|burndown|list
|
|
122
|
+
kadence template save|list|delete
|
|
180
123
|
```
|
|
181
124
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
125
|
+
Bulk works everywhere: `kadence task move KAD-1,KAD-2 done` — **all or
|
|
126
|
+
nothing**, so a typo changes nothing rather than half your board.
|
|
127
|
+
|
|
128
|
+
---
|
|
185
129
|
|
|
186
|
-
|
|
130
|
+
## What it costs you
|
|
187
131
|
|
|
188
132
|
| | |
|
|
189
133
|
|---|---|
|
|
190
|
-
|
|
|
191
|
-
|
|
|
192
|
-
|
|
|
193
|
-
|
|
|
134
|
+
| Install | 32 KB, one runtime dependency |
|
|
135
|
+
| Startup | 80 ms |
|
|
136
|
+
| 10,000 events | 28 ms cold, 7 ms warm |
|
|
137
|
+
| Journal on disk | 1.9 MB |
|
|
194
138
|
|
|
195
|
-
These are
|
|
139
|
+
These are tests. They fail the build on regression, which is why they are still
|
|
140
|
+
true.
|
|
141
|
+
|
|
142
|
+
---
|
|
196
143
|
|
|
197
144
|
## Honest status
|
|
198
145
|
|
|
199
|
-
|
|
146
|
+
**Verified.** The merge thesis, on real git branches. Performance and size, by
|
|
147
|
+
tests that fail if they regress. That the conflict problem exists in the wild —
|
|
148
|
+
measured, not assumed. 390 tests, including an end-to-end run through the
|
|
149
|
+
installed binary.
|
|
150
|
+
|
|
151
|
+
**Not verified.** Whether teams want this. The velocity bet rests on reasoning,
|
|
152
|
+
not on user interviews — that research is
|
|
153
|
+
[designed](docs/research/interview-script.md) and not yet run.
|
|
200
154
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
- The conflict problem exists in the wild — measured, not assumed.
|
|
155
|
+
**Known limits.** Conflicts are real but rare: roughly one merge in two
|
|
156
|
+
hundred. That is why the headline is analytics, not conflict-freedom. Terminal
|
|
157
|
+
interaction is covered by manual testing; only the key router is unit-tested.
|
|
205
158
|
|
|
206
|
-
|
|
159
|
+
---
|
|
207
160
|
|
|
208
|
-
|
|
209
|
-
interviews. That research is designed but not yet run
|
|
210
|
-
([interview script](docs/research/interview-script.md)).
|
|
211
|
-
- Conflicts are real but **rare** — roughly one merge in two hundred. That is
|
|
212
|
-
why the headline message is analytics, not conflict-freedom.
|
|
161
|
+
## How it works
|
|
213
162
|
|
|
214
|
-
|
|
215
|
-
|
|
163
|
+
```
|
|
164
|
+
.kadence/
|
|
165
|
+
|- state.json derived cache - gitignored, safe to delete
|
|
166
|
+
`- events/
|
|
167
|
+
|- archive/ compacted history, one file per month
|
|
168
|
+
`- 2026-09/ recent events, one file each
|
|
169
|
+
```
|
|
216
170
|
|
|
217
|
-
|
|
171
|
+
Every command appends one event. State is folded from the journal on read, so
|
|
172
|
+
the board cannot drift from reality. Two branches writing at once produce two
|
|
173
|
+
different files, and git merges them without a conflict by construction.
|
|
174
|
+
|
|
175
|
+
Design decisions, each recording what was measured and what would make us
|
|
176
|
+
revisit it: [docs/decisions/](docs/decisions/).
|
|
177
|
+
|
|
178
|
+
## Contributing
|
|
218
179
|
|
|
219
180
|
```bash
|
|
220
181
|
npm install
|
|
221
|
-
npm test #
|
|
222
|
-
npm run build #
|
|
223
|
-
npm run typecheck
|
|
182
|
+
npm test # 390 tests
|
|
183
|
+
npm run build # 32 KB bundle
|
|
224
184
|
```
|
|
225
185
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
for a seven-field object ([ADR-003](docs/decisions/003-zero-runtime-deps-in-core.md)).
|
|
229
|
-
The CLI layer uses `cac` and nothing else.
|
|
230
|
-
|
|
231
|
-
Architecture decisions are in [docs/decisions/](docs/decisions/); each one
|
|
232
|
-
records what was measured and what would make us revisit it.
|
|
186
|
+
`CLAUDE.md` documents the invariants, the boundaries, and the decisions that
|
|
187
|
+
look arbitrary without their reasoning. Read it before changing the core.
|
|
233
188
|
|
|
234
|
-
##
|
|
189
|
+
## Licence
|
|
235
190
|
|
|
236
191
|
MIT
|
package/dist/cli.js
CHANGED
|
@@ -129,7 +129,7 @@ Available: create, add, edit, start, close, status, list, burndown
|
|
|
129
129
|
kadence sprint --help`),e)}});h.command("template [action] [name]","Task templates: save | list | delete").option("-d, --description <text>","Default description").option("--type <type>","Default type").option("--priority <level>","Default priority").option("-a, --assignee <who>","Default assignee").option("--label <name>","Default label; repeat for several").option("--estimate <points>","Default estimate").option("--json","Machine-readable output for agents").example(" kadence template save bug --type bug --priority high --label triage").example(" kadence template list").action((n,t,s)=>{let e=s.json===!0,a=process.cwd();switch(n){case"save":{t===void 0&&c(f(`A template name is required:
|
|
130
130
|
kadence template save bug --type bug`),e);let i=s.label===void 0?void 0:Array.isArray(s.label)?s.label:[s.label];c(Te(a,process.env,t,{...s.description!==void 0?{description:s.description}:{},...s.type!==void 0?{type:s.type}:{},...s.priority!==void 0?{priority:s.priority}:{},...s.assignee!==void 0?{assignee:s.assignee}:{},...i!==void 0?{labels:i}:{},...s.estimate!==void 0?{estimate:Number(s.estimate)}:{}}),e);break}case"list":case void 0:c(Ke(a,process.env),e);break;case"delete":t===void 0&&c(f(`Which template?
|
|
131
131
|
kadence template delete bug`),e),c(Ne(a,process.env,t),e);break;default:c(f(`Unknown action "${n}".
|
|
132
|
-
Available: save, list, delete`),e)}});h.command("ui","Interactive kanban board").alias("board:ui").example(" kadence ui").action(async()=>{let{runUi:n}=await import("./chunks/ui-WFLRVGUH.js"),t=await n(process.cwd(),process.env);t.ok||c(t,!1)});h.help();h.version("0.1.
|
|
132
|
+
Available: save, list, delete`),e)}});h.command("ui","Interactive kanban board").alias("board:ui").example(" kadence ui").action(async()=>{let{runUi:n}=await import("./chunks/ui-WFLRVGUH.js"),t=await n(process.cwd(),process.env);t.ok||c(t,!1)});h.help();h.version("0.1.5");var v=process.argv;if(v[2]==="task"&&v[3]==="log"&&v[4]!==void 0&&v[5]!==void 0){let n=T(process.cwd(),process.env,v[4],v[5]),t=v.includes("--json");c(n,t)}var _e=process.argv.findIndex((n,t)=>n.startsWith("-")&&/^-\d+(\.\d+)?$/.test(n)&&process.argv[t-1]==="--estimate");_e!==-1&&(process.stderr.write(`Estimate must be a positive number, got "${process.argv[_e]}".
|
|
133
133
|
kadence task add "Fix login" --estimate 3
|
|
134
134
|
`),process.exit(2));try{h.parse()}catch(n){process.stderr.write(`${n.message}
|
|
135
135
|
`),process.exit(2)}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "kadence",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"description": "Tasks, sprints and velocity as plain files inside your git repository",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -49,10 +49,10 @@
|
|
|
49
49
|
],
|
|
50
50
|
"repository": {
|
|
51
51
|
"type": "git",
|
|
52
|
-
"url": "git+https://github.com/bogutskiandriy/
|
|
52
|
+
"url": "git+https://github.com/bogutskiandriy/kadence.git"
|
|
53
53
|
},
|
|
54
|
-
"homepage": "https://github.com/bogutskiandriy/
|
|
54
|
+
"homepage": "https://github.com/bogutskiandriy/kadence#readme",
|
|
55
55
|
"bugs": {
|
|
56
|
-
"url": "https://github.com/bogutskiandriy/
|
|
56
|
+
"url": "https://github.com/bogutskiandriy/kadence/issues"
|
|
57
57
|
}
|
|
58
58
|
}
|