@sentropic/track 0.14.0 → 0.14.1
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/package.json
CHANGED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: track-operation
|
|
3
|
+
description: "Use when an agent needs to read, update, import, or verify track state in a repo; when a BRANCH.md or plan/NN-BRANCH_*.md file changed; when a session reports that track write/import is not exposed; or when deciding whether to use track MCP versus the track CLI. The skill enforces the contract: MCP is read-only, writes/imports use the track CLI from the target repo root, and .track is append-only/single-writer."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Track Operation
|
|
7
|
+
|
|
8
|
+
Use this for ordinary track hygiene: reading status, importing BRANCH files, recording item or decision
|
|
9
|
+
updates, and verifying that the sidecar is current. This is the general operational skill; use
|
|
10
|
+
`present-decision` for human decision dossiers and `propose-workpackages` for backlog restructuring.
|
|
11
|
+
|
|
12
|
+
## Contract
|
|
13
|
+
|
|
14
|
+
- The `track` MCP server is read-only by design. MCP tools may report, query, validate, inspect canvas
|
|
15
|
+
state, or show cursor/status data; they must not append to `.track/`.
|
|
16
|
+
- Do not treat missing MCP write/import tools as a blocker. Writes and imports are CLI operations.
|
|
17
|
+
- Run CLI writes from the target repository root, never from a different checkout. `track branch import
|
|
18
|
+
../other-repo/plan/X.md` writes to the current repo's `.track/`, not the other repo's store.
|
|
19
|
+
- `.track/events.jsonl` is append-only and single-writer. Do not write or commit `.track/` from a
|
|
20
|
+
concurrent worktree unless the user has explicitly designated that worktree as the writer.
|
|
21
|
+
|
|
22
|
+
## Before A Write
|
|
23
|
+
|
|
24
|
+
1. Confirm the repository root you are operating in.
|
|
25
|
+
2. Confirm `.track/` exists. If it is absent, recommend `track init` and stop unless the user explicitly
|
|
26
|
+
asked to initialize tracking.
|
|
27
|
+
3. If you are in a concurrent worktree, update the mergeable source artifact instead, usually the
|
|
28
|
+
`plan/NN-BRANCH_*.md` file. Leave `.track/` import to the designated writer checkout unless told
|
|
29
|
+
otherwise.
|
|
30
|
+
|
|
31
|
+
## BRANCH Import
|
|
32
|
+
|
|
33
|
+
When progress is represented by a `BRANCH.md` or `plan/NN-BRANCH_*.md` file:
|
|
34
|
+
|
|
35
|
+
1. Update the checkboxes in the BRANCH file. Keep the BRANCH file as the source of truth.
|
|
36
|
+
2. From the same repo root, run:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
track branch import plan/<BRANCH_FILE>.md
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
3. Verify immediately:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
track report --format text
|
|
46
|
+
track validate
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
4. If the import reports `0 created, 0 updated`, that is a valid idempotent result when the sidecar was
|
|
50
|
+
already current.
|
|
51
|
+
|
|
52
|
+
## Direct Writes
|
|
53
|
+
|
|
54
|
+
Use direct CLI writes only for the event they actually represent:
|
|
55
|
+
|
|
56
|
+
- New item: `track item new --kind <feature|bug|chore> --title "<title>" --workspace <workspace>`
|
|
57
|
+
- Realization: `track item realize <itemId> <in-progress|done|cancelled>`
|
|
58
|
+
- Decision dossier: `track decision dossier <decisionId> --context <context>`
|
|
59
|
+
- Artifact evidence: `track decision add-artifact <decisionId> ...`
|
|
60
|
+
- Workpackage changes: follow `propose-workpackages`; do not reparent without human approval.
|
|
61
|
+
|
|
62
|
+
## Reporting Back
|
|
63
|
+
|
|
64
|
+
Report track results from the verified state, not from memory:
|
|
65
|
+
|
|
66
|
+
- Use `track report --format text` for human status.
|
|
67
|
+
- Use `track report --wp` only when the repo is structured into workpackages.
|
|
68
|
+
- Mention if `.track/` was intentionally not written because the current checkout is not the designated
|
|
69
|
+
writer.
|
|
70
|
+
|
|
71
|
+
## Do Not
|
|
72
|
+
|
|
73
|
+
- Do not say "track write/import is not exposed" when the CLI exists. The correct statement is "MCP is
|
|
74
|
+
read-only; I will use the track CLI from the repo root."
|
|
75
|
+
- Do not initialize tracking in another repo without explicit user approval.
|
|
76
|
+
- Do not manually edit `.track/events.jsonl` except for a deliberate repair with owner approval.
|
|
77
|
+
- Do not commit `.track/` updates produced from the wrong repo root or an undesignated concurrent worktree.
|
|
78
|
+
|
|
79
|
+
## Per-Agent Mapping
|
|
80
|
+
|
|
81
|
+
| Capability | Claude | Codex | Gemini-agy |
|
|
82
|
+
| --- | --- | --- | --- |
|
|
83
|
+
| skill entrypoint | `~/.claude/skills/track-operation/SKILL.md` | `~/.codex/skills/track-operation/SKILL.md` | `~/.gemini/commands/track-operation.toml` |
|
|
84
|
+
| read tools | track MCP or CLI report/query/validate | track MCP or CLI report/query/validate | track MCP or CLI report/query/validate |
|
|
85
|
+
| write/import tools | `track` CLI | `track` CLI | `track` CLI |
|
|
86
|
+
|
|
87
|
+
Existing repo methods win on conflict. If a repo has a harness flow, let harness own the BRANCH artifact and
|
|
88
|
+
use `track branch import` to project it into the track sidecar.
|