@erclx/aitk 0.53.0 → 0.54.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.
- package/claude/.claude-plugin/plugin.json +1 -1
- package/claude/skills/claude-groundwork/SKILL.md +1 -0
- package/claude/skills/claude-intake/REQUIREMENT.md +46 -0
- package/claude/skills/claude-intake/SKILL.md +139 -0
- package/claude/skills/claude-intake/references/folder-format.md +97 -0
- package/docs/agents/index.md +1 -1
- package/docs/agents/output-shape.md +9 -1
- package/docs/agents/overview.md +1 -1
- package/docs/ai-workflow.md +2 -0
- package/package.json +1 -1
- package/standards/rule.md +8 -0
- package/standards/skill.md +8 -0
|
@@ -14,6 +14,7 @@ Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file i
|
|
|
14
14
|
- If no topic is given, stop: `❌ No topic. Name what needs measuring.`
|
|
15
15
|
- Apply the qualifying test in open mode alone, after Step 1 resolves the mode and before the folder is created. Two of these three must hold: the current state is not known, more than one approach is live, and committing wrong costs more than a day of measuring. When one or fewer holds, stop: `❌ Already decided enough to plan. Run /claude-feature instead.`
|
|
16
16
|
- Resume and close are exempt from the test above. A track that has already been measured fails it by definition, since its current state is now known and its approaches have narrowed, so applying the test to either mode refuses the folder that same test admitted.
|
|
17
|
+
- A refused topic that is a broad dump rather than one question routes to `claude-intake`, not to the planning skill the stop names. Intake dispositions many findings in breadth from what the repository already holds, and one folder holding dozens of unrelated threads is what forcing them past this guard produces.
|
|
17
18
|
- Do not pause for approval between steps. The write scope below is what makes that safe.
|
|
18
19
|
|
|
19
20
|
## Write scope
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: claude-intake
|
|
3
|
+
description: Why a brain dump gets a filed inventory rather than ten plans, and why an empty operator slot means unread
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Claude intake requirement
|
|
7
|
+
|
|
8
|
+
## Gap
|
|
9
|
+
|
|
10
|
+
Without this skill, a brain dump reaches a session that has nowhere to put it. `claude-feature` answers with one plan per independent concern, so forty findings produce ten plan files before anything has been measured. `claude-groundwork` refuses a breadth pass outright, since its qualifying test asks whether the current state is unknown and most items are knowable by grep. What gets filed instead is a list of opinions, because nothing forces a count against the tree and a complaint reads the same whether it covers three sites or three hundred.
|
|
11
|
+
|
|
12
|
+
Two failure modes cost more than the rest. An operator's silence on an item reads as consent when the folder borrows the plan file's blank-means-accept contract, which ships changes nobody approved across a folder read over weeks. And a report naming only a path cannot distinguish three new items from one reworded sentence in a file that holds a dozen items, so every reader diffs it against memory to find out what moved.
|
|
13
|
+
|
|
14
|
+
Four more are cheaper to name than to rediscover. A question filed without a pick comes back unresolved, measured across one folder's 19 open items, where every one carrying a suggestion resolved on a bare `ok` and the five carrying none did not. A session with no numbering convention re-decides the folder shape per dump, so no two intakes are readable the same way and the second one has to be learned from scratch. A question answerable both in the index and on its item resolves to whichever a reader opens first, with no rule saying which wins. And a pass with no write scope starts fixing what it files, which turns a triage into a branch nobody asked for and nobody reviewed.
|
|
15
|
+
|
|
16
|
+
## Must
|
|
17
|
+
|
|
18
|
+
- Route each item on whether the repository can answer it today, sending what needs an experiment or an outside source to the groundwork skill and what is already decided to the planning skill
|
|
19
|
+
- Measure every problem line against the tree during this pass, carrying a number or a file path rather than a figure from recall
|
|
20
|
+
- Close every item with a verdict, and pair every open question with a suggested pick
|
|
21
|
+
- Treat an empty operator slot as unread rather than as agreement
|
|
22
|
+
- Reserve the index number and carry the domain in every other filename, leaving the rest of the numbering as read order
|
|
23
|
+
- Keep answers on items alone, with the index pointing at them
|
|
24
|
+
- Name the heading and the act beside every path the pass wrote
|
|
25
|
+
- Confine writes to the intake folder
|
|
26
|
+
|
|
27
|
+
## Must not
|
|
28
|
+
|
|
29
|
+
- Write a plan, a task file, a standard, a rule, or a source change
|
|
30
|
+
- Fill an operator's answer slot, or infer a disposition from an empty one
|
|
31
|
+
- Replace a verdict with an overlap line, which drops the call on exactly the items where a live board task might be the thing that is wrong
|
|
32
|
+
- Reserve mid-range numbers, which would force every future intake into one dump's shape
|
|
33
|
+
- Date every file, since the first edit to one leaves the rest stale
|
|
34
|
+
- Open a folder for a single question, which is either a groundwork track or a plan
|
|
35
|
+
|
|
36
|
+
## Guards
|
|
37
|
+
|
|
38
|
+
- No dump given: stop rather than inferring one
|
|
39
|
+
- One question rather than a set of findings: stop and route to the groundwork or planning skill
|
|
40
|
+
|
|
41
|
+
## Out of scope
|
|
42
|
+
|
|
43
|
+
- Measuring one question in depth, which `claude-groundwork` owns
|
|
44
|
+
- Planning a promoted item, which `claude-feature` owns
|
|
45
|
+
- Promoting an item onto the board, which `claude-tasks` owns
|
|
46
|
+
- Enforcing any of this. The folder is gitignored, so no check reaches its contents and every rule holds only while a session reads it.
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: claude-intake
|
|
3
|
+
description: Files a raw brain dump into a numbered intake folder under `.claude/intake/<slug>/`, one item per finding carrying a measured problem, a proposed fix, and a verdict. Use when asked to "file this dump", "triage my notes", "work through this list", "sort out this brain dump", or "run an intake pass". Do NOT use for one question that has to be measured before anyone can plan it. That is `claude-groundwork`.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Claude intake
|
|
7
|
+
|
|
8
|
+
Intake dispositions many findings in breadth. A dump goes in, an inventory comes out, and every item carries a problem measured against the tree, one proposed fix, and a verdict. The item that turns out to be already settled is the highest-value output, and it is the one thing neither a plan nor a groundwork track has anywhere to put.
|
|
9
|
+
|
|
10
|
+
Read `${CLAUDE_SKILL_DIR}/references/folder-format.md` before writing any file in the folder. It holds the numbering, the file map, the frontmatter, and the item template.
|
|
11
|
+
|
|
12
|
+
## Routing
|
|
13
|
+
|
|
14
|
+
The test is one question. Can the item be answered by reading the repository today?
|
|
15
|
+
|
|
16
|
+
- Yes: intake owns it, and the cost is a session of grepping
|
|
17
|
+
- No, because it needs an experiment or a source outside the project: route it to `claude-groundwork`, where the cost is measured in runs and days
|
|
18
|
+
- Already decided, with only the work left: route it to `claude-feature`
|
|
19
|
+
|
|
20
|
+
Apply the test per item rather than per dump. A dump of forty items typically yields one groundwork candidate, so routing the whole dump on its worst item buys a folder nobody can close.
|
|
21
|
+
|
|
22
|
+
Using the wrong one fails in two shapes. Intake on a question that needs measuring yields a confident verdict with nothing behind it. Groundwork on a brain dump is refused by its own qualifying guard, and forcing past that refusal gives one folder holding dozens of unrelated threads and a decision file that can close one of them.
|
|
23
|
+
|
|
24
|
+
## Guards
|
|
25
|
+
|
|
26
|
+
- If no dump is given, stop: `❌ No dump to file. Paste the notes or name what to triage.`
|
|
27
|
+
- If the dump is one question rather than a set of findings, stop: `❌ One question, not a dump. Run /claude-groundwork to measure it or /claude-feature to plan it.`
|
|
28
|
+
- Do not pause for approval between steps. The write scope below is what makes that safe.
|
|
29
|
+
|
|
30
|
+
## Write scope
|
|
31
|
+
|
|
32
|
+
- Write only inside `.claude/intake/<slug>/`. A plan file, a task file, a source change, a standard, and a rule all live outside that folder, so this one rule forbids every one of them.
|
|
33
|
+
- There is no exception. Promoting an item onto the board runs through `claude-tasks` after the operator has answered, which is a separate invocation.
|
|
34
|
+
- Reading is unrestricted inside the project. Measuring is the work.
|
|
35
|
+
- Treat the folder as gitignored and unbacked. No check reaches its contents, so every rule stated here holds only while a session reads it.
|
|
36
|
+
|
|
37
|
+
Nothing outside this body carries the floor, and no path-scoped rule can. The item format and the answer contract are heading for a standard covering this folder and a groundwork track together, which is queued rather than written.
|
|
38
|
+
|
|
39
|
+
## Step 1: detect open or resume
|
|
40
|
+
|
|
41
|
+
List `.claude/intake/` from the project root and match the topic against the folders already there before deriving a slug. A second pass over the same subject rarely phrases the topic the way the folder was named, so a fresh slug would open a duplicate beside a live folder.
|
|
42
|
+
|
|
43
|
+
Never match against `.claude/` itself. That directory holds every other workflow surface, so a topic matched there lands on a folder that was never an intake.
|
|
44
|
+
|
|
45
|
+
With no match, derive a kebab-case slug named for the subject rather than the activity. Prefer `toolkit-overview` over `august-triage`. An absent folder opens, and a present one resumes by appending items and revising verdicts the tree has moved under.
|
|
46
|
+
|
|
47
|
+
## Step 2: orient
|
|
48
|
+
|
|
49
|
+
Read these in parallel from the project root, skipping any that do not exist:
|
|
50
|
+
|
|
51
|
+
- `CLAUDE.md`: behavior rules, conventions, commands
|
|
52
|
+
- `.claude/REQUIREMENTS.md`: scope and non-goals
|
|
53
|
+
- `.claude/ARCHITECTURE.md`: decisions already made
|
|
54
|
+
- `.claude/tasks/index.md`: what is already tracked. Open a task file whose entry looks related to an item.
|
|
55
|
+
|
|
56
|
+
Then read only what a live item needs. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
|
|
57
|
+
|
|
58
|
+
## Step 3: measure against the tree
|
|
59
|
+
|
|
60
|
+
Grep for each construct an item names and count the sites. Every problem line carries a number or a file path taken during this pass.
|
|
61
|
+
|
|
62
|
+
Never carry a figure from an earlier session, a summary, or another document. The dump states the complaint and the tree states the size of it, and that measurement is the whole difference between an inventory and a list of opinions. Confirm that any work an item sequences behind is still open, so no item leads with something that already shipped.
|
|
63
|
+
|
|
64
|
+
Name the commit the pass measured against in the overview body. It is the half a later reader can check.
|
|
65
|
+
|
|
66
|
+
## Step 4: cluster
|
|
67
|
+
|
|
68
|
+
Split items by domain, one file per cluster, and let the file count follow the number of separable domains rather than the size of the dump. An item belongs to the domain its fix touches, not the domain the complaint arrived from.
|
|
69
|
+
|
|
70
|
+
Two heading levels is the right depth. A third means the cluster should have been split into its own file.
|
|
71
|
+
|
|
72
|
+
## Step 5: disposition each item
|
|
73
|
+
|
|
74
|
+
Write every item in the format below, in the cluster file its fix belongs to. Close each item with a verdict and an empty operator slot.
|
|
75
|
+
|
|
76
|
+
## Step 6: write the index
|
|
77
|
+
|
|
78
|
+
Write `00-overview.md` last, once the clusters are filed and the counts are real. It carries the format block, the cluster table, the verdict counts, the ready list, and the open questions.
|
|
79
|
+
|
|
80
|
+
Each open question in the index is a labeled markdown link to its owning item's heading anchor. The index points and the item owns, so no answer slot appears in the index. One question in two answerable places has no rule for which wins, and retrieval walks item headings, so an answer typed into the index is found by nothing and lost silently.
|
|
81
|
+
|
|
82
|
+
Add `99-next-session.md` only where the pass ends holding context no cluster file carries, such as a dump half filed or a measurement that has to be redone. Write it self-contained, since the folder is unbacked and the conversation behind it compacts away.
|
|
83
|
+
|
|
84
|
+
## Item format
|
|
85
|
+
|
|
86
|
+
```markdown
|
|
87
|
+
### N. Short title stating the defect
|
|
88
|
+
|
|
89
|
+
- **Problem:** what is wrong today, stated against the tree and carrying a number or a file path
|
|
90
|
+
- **Fix:** the one change proposed
|
|
91
|
+
- **Worth it:** yes, later, or no, with the reason
|
|
92
|
+
- **Open:** only where the call is the operator's
|
|
93
|
+
- **Suggested:** the pick in one sentence, then the reason and the main tradeoff in one or two
|
|
94
|
+
- **Overlaps:** the live board task that already owns this item
|
|
95
|
+
- **You:**
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
- `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
|
|
99
|
+
- `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default. The toolkit's `decision-help` snippet writes the same four-line shape for chat use, and the four lines above are the whole spec.
|
|
100
|
+
- `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
|
|
101
|
+
|
|
102
|
+
## The answer contract
|
|
103
|
+
|
|
104
|
+
`You:` belongs to the operator and ships empty on every item.
|
|
105
|
+
|
|
106
|
+
Empty means unread. It never means agreement. Accepting a verdict is typed as one token, `- **You:** ok`.
|
|
107
|
+
|
|
108
|
+
That inverts the plan file's contract, where a blank `- Answer:` means accept the suggestion, and the inversion is deliberate. A plan is read in one sitting with every question already surfaced in chat. An intake folder is read over weeks, so an empty slot is ambiguous between accepting the verdict and never having reached the item, and the second reading is far more likely. Acting on silence as consent ships a change nobody approved.
|
|
109
|
+
|
|
110
|
+
Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
|
|
111
|
+
|
|
112
|
+
## Numbering
|
|
113
|
+
|
|
114
|
+
Numbers are read order and nothing else. Reserve `00` for the index and carry the domain in every other filename, so `07-tooling.md` says what it holds before anyone opens it.
|
|
115
|
+
|
|
116
|
+
Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. `claude-groundwork` reserves its numbers because its shape is fixed, and that half of the convention does not transfer.
|
|
117
|
+
|
|
118
|
+
## Output
|
|
119
|
+
|
|
120
|
+
Emit the full relative path from the project root for every file written, and name the heading and the act beside it. A path alone cannot distinguish three new items from one reworded sentence in a file that holds a dozen items and lives for weeks, so a bare path sends the reader to diff it against memory. This overrides the paths-only reporting the project states generally, which stays right wherever the reader is about to see a diff.
|
|
121
|
+
|
|
122
|
+
A file the pass only read gets no line, which is what keeps the block short.
|
|
123
|
+
|
|
124
|
+
```plaintext
|
|
125
|
+
📂 Opened .claude/intake/<slug>/
|
|
126
|
+
|
|
127
|
+
**Filed:**
|
|
128
|
+
|
|
129
|
+
- `.claude/intake/<slug>/05-coverage.md` gains items 6 to 8 under a new `## What the merge gate covers`
|
|
130
|
+
- `.claude/intake/<slug>/00-overview.md` cluster rows and verdict counts updated
|
|
131
|
+
|
|
132
|
+
**Routing:** <N> plan-ready, <N> groundwork candidates, <N> already settled
|
|
133
|
+
|
|
134
|
+
**Open questions:** <N> awaiting your call
|
|
135
|
+
|
|
136
|
+
Next: answer the `You:` slots, then /claude-tasks to promote what is ready
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Use `📂 Resumed` in place of `📂 Opened` on a resume pass.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Intake folder reference
|
|
3
|
+
description: Reserved index number, file map, frontmatter and dating, the item template, retrieval, and anti-patterns
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Intake folder reference
|
|
7
|
+
|
|
8
|
+
Applies to an intake folder at `.claude/intake/<slug>/`. One folder holds one dump, filed by domain, and every finding in it is an item carrying a measured problem and a verdict.
|
|
9
|
+
|
|
10
|
+
The folder is gitignored and unbacked. No check reaches its contents, so the shape below survives only by being read.
|
|
11
|
+
|
|
12
|
+
## Files
|
|
13
|
+
|
|
14
|
+
| File | Holds | Required |
|
|
15
|
+
| -------------------- | ------------------------------------------------------------ | -------- |
|
|
16
|
+
| `00-overview.md` | Index: format block, cluster table, verdicts, open questions | Always |
|
|
17
|
+
| `NN-<domain>.md` | One cluster of items, filed by the domain their fixes touch | Always |
|
|
18
|
+
| `99-next-session.md` | What a compaction destroys that no cluster file carries | Optional |
|
|
19
|
+
|
|
20
|
+
`00` is the only reserved number. Everything else is read order, and the domain rides in the filename so a reader knows what `07-tooling.md` holds without opening it.
|
|
21
|
+
|
|
22
|
+
Do not reserve mid-range numbers. Clusters differ per dump, so a contract over `06` would force every future intake into one dump's shape. Groundwork reserves its numbers because its shape is fixed, and that half of the convention does not transfer.
|
|
23
|
+
|
|
24
|
+
Let the file count follow the number of separable domains. A large dump with two domains is a small folder.
|
|
25
|
+
|
|
26
|
+
## Frontmatter and dating
|
|
27
|
+
|
|
28
|
+
Every file carries `title` and `description` per the project's prose standard. `00-overview.md` carries one field the others do not, a `date` holding the day the folder opened.
|
|
29
|
+
|
|
30
|
+
Date the folder once rather than every file. Twelve dated files leave eleven stale the first time one cluster is edited, and the opening date never rots. The checkable half is the commit, which the overview body names as what the claims were measured against.
|
|
31
|
+
|
|
32
|
+
## 00-overview.md
|
|
33
|
+
|
|
34
|
+
The index. It points at items and answers nothing itself.
|
|
35
|
+
|
|
36
|
+
- The item format block, copied so a returning session picks the shape up from the folder
|
|
37
|
+
- The answer contract stated out loud, since it inverts the plan file's
|
|
38
|
+
- A cluster table of file, what it holds, item count, and open count
|
|
39
|
+
- The verdict counts across the folder
|
|
40
|
+
- A ready list, grouped by what shipping one actually costs
|
|
41
|
+
- The open questions, each a labeled markdown link to its owning item's heading anchor
|
|
42
|
+
|
|
43
|
+
The index carries no answer slot. One question in two answerable places has no rule for which wins, and retrieval walks item headings, so an answer typed into the index is found by nothing and lost silently.
|
|
44
|
+
|
|
45
|
+
Where an item touches a task already on the board, say so in the index rather than only inside the item. A reader deciding what to promote reads the index first.
|
|
46
|
+
|
|
47
|
+
## Item template
|
|
48
|
+
|
|
49
|
+
```markdown
|
|
50
|
+
### N. Short title stating the defect
|
|
51
|
+
|
|
52
|
+
- **Problem:** what is wrong today, stated against the tree and carrying a number or a file path
|
|
53
|
+
- **Fix:** the one change proposed
|
|
54
|
+
- **Worth it:** yes, later, or no, with the reason
|
|
55
|
+
- **Open:** only where the call is the operator's
|
|
56
|
+
- **Suggested:** the pick in one sentence, then the reason and the main tradeoff in one or two
|
|
57
|
+
- **Overlaps:** the live board task that already owns this item
|
|
58
|
+
- **You:**
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. `Open:` appears only where the call is the operator's, `Suggested:` is required whenever it does, and `Overlaps:` is optional and never replaces the verdict.
|
|
62
|
+
|
|
63
|
+
Two heading levels is the right depth inside a cluster file. A third means the cluster should have been its own file.
|
|
64
|
+
|
|
65
|
+
An item may carry a bolded standalone line between the bullets where a finding needs a name of its own. Keep it rare. Everything that fits the four bullets belongs in them.
|
|
66
|
+
|
|
67
|
+
## Retrieval
|
|
68
|
+
|
|
69
|
+
Answers live on items, so one pass over the folder reports every touched slot.
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print " "$0}' *.md
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Counting what is still unread runs against the empty slot instead.
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
grep -c '^- \*\*You:\*\*$' *.md
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Both walk `###` headings, which is the mechanical reason an answer typed anywhere else is lost.
|
|
82
|
+
|
|
83
|
+
## Conventions
|
|
84
|
+
|
|
85
|
+
- State a number with what it settles. The strongest items are the ones where a measurement decides the verdict and says so.
|
|
86
|
+
- File an item under the domain its fix touches, not the domain the complaint arrived from.
|
|
87
|
+
- Name a live board task an item overlaps, and keep the verdict beside it.
|
|
88
|
+
- Revise a verdict the tree has moved under rather than appending a second one narrating the change.
|
|
89
|
+
- Report unread items by count on a resume pass. Never decide one.
|
|
90
|
+
|
|
91
|
+
## Anti-patterns
|
|
92
|
+
|
|
93
|
+
- **Silence read as consent.** An empty slot on a folder read over weeks means nobody reached the item, and treating it as acceptance ships a change nobody approved.
|
|
94
|
+
- **A verdict with nothing behind it.** An item whose problem line carries no number is an opinion, and it reads exactly like the ones that were measured.
|
|
95
|
+
- **The overlap that ate the verdict.** Replacing `Worth it:` with `Overlaps:` drops the call on the items most likely to change what a live task should do.
|
|
96
|
+
- **A question in two places.** An open question answerable in the index and on the item resolves to whichever a reader happens to open.
|
|
97
|
+
- **The dump filed as one concern.** Forty findings under one heading is a folder nobody can promote from, and the split by domain is what makes each item liftable on its own.
|
package/docs/agents/index.md
CHANGED
|
@@ -16,7 +16,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
|
|
|
16
16
|
- [Docs](docs.md): How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
|
|
17
17
|
- [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
|
|
18
18
|
- [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
|
|
19
|
-
- [Output shape](output-shape.md):
|
|
19
|
+
- [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
|
|
20
20
|
- [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
|
|
21
21
|
- [Sandbox](sandbox.md): Scenario routing, the expectation scoring surface, and the coverage census over scenarios and skills
|
|
22
22
|
- [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Output shape
|
|
3
|
-
description:
|
|
3
|
+
description: Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Output shape
|
|
@@ -43,3 +43,11 @@ Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to
|
|
|
43
43
|
## JSON and `--names` modes
|
|
44
44
|
|
|
45
45
|
`--json` and `--names` keep stdout clean and machine-readable. The frame still renders on stderr (open, banner, close) so the stream discipline is consistent across modes. Consumers that only read stdout see pure data.
|
|
46
|
+
|
|
47
|
+
## Process exit
|
|
48
|
+
|
|
49
|
+
A command action that writes to stdout sets `process.exitCode` and returns. Calling `process.exit()` there ends the process before the write drains, which truncates piped output at the 64K pipe buffer while still reporting the right exit code. Redirecting to a file hides the truncation, so it surfaces only through a pipe, which is what a check has to use to catch it.
|
|
50
|
+
|
|
51
|
+
A fail-fast path that has written to stderr alone may still call `process.exit()`, and several do. The truncation has nothing to cut there, so the ban is scoped to the stream it protects rather than applied to every exit.
|
|
52
|
+
|
|
53
|
+
Diagnostics reach stderr in every mode, including `--json`. Name the file and the field that failed, because a JSON record carries an action and a reason and an operator reading stderr alone sees neither.
|
package/docs/agents/overview.md
CHANGED
|
@@ -15,7 +15,7 @@ See `CLAUDE.md` design principles. They apply to every command in this folder.
|
|
|
15
15
|
|
|
16
16
|
## Where to start
|
|
17
17
|
|
|
18
|
-
- `output-shape.md`: the stream contract every command renders into, which is what a caller parsing stdout depends on
|
|
18
|
+
- `output-shape.md`: the stream contract every command renders into and the exit discipline behind it, which is what a caller parsing stdout depends on
|
|
19
19
|
- `commands.md`: the full command catalog, project-level and per-domain
|
|
20
20
|
- `scripting.md`: the runtime catalogs that replace hardcoded names, plus headless invocation examples
|
|
21
21
|
|
package/docs/ai-workflow.md
CHANGED
|
@@ -44,6 +44,7 @@ One session works for most features. Prefer splitting across two sessions only w
|
|
|
44
44
|
|
|
45
45
|
Work in Claude Code directly. It reads `CLAUDE.md` automatically and has full file access, no pasting needed.
|
|
46
46
|
|
|
47
|
+
- When the input is a pile of findings rather than one feature, invoke `aitk:claude-intake` first. It files the dump into `.claude/intake/<slug>/`, one item per finding carrying a problem measured against the tree, a proposed fix, and a verdict, then names which items are plan-ready, which need measuring, and which are already settled. The routing test is whether the repository can answer an item today, so a session grepping handles the yes and the next bullet handles the no.
|
|
47
48
|
- When the current state is unmeasured and more than one approach is live, invoke `aitk:claude-groundwork` first. It opens a track folder under `.claude/groundwork/<slug>/` and ends in a decision, which may be to do nothing. Skip it when the approach is already settled. A track may run experiments to settle a question, writing a fixture it reads itself under `.claude/.tmp/groundwork-fixtures/<slug>/` and spawning up to three billed headless runs before it asks. A fixture a headless run is pointed at sits outside the repository, since a session started under the project root inherits that project's `CLAUDE.md` and rules and would measure them instead of the arm.
|
|
48
49
|
- Invoke `aitk:claude-feature` to scan for code-level conflicts and ambiguities, confirm approach before proceeding
|
|
49
50
|
- Implement the feature, then Claude Code runs the commands defined in `CLAUDE.md`, fixes failures, and iterates until all pass
|
|
@@ -131,6 +132,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
|
|
|
131
132
|
|
|
132
133
|
| Skill | When to use |
|
|
133
134
|
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
135
|
+
| `aitk:claude-intake` | File a brain dump into an inventory under `.claude/intake/`, one item per finding with a verdict |
|
|
134
136
|
| `aitk:claude-groundwork` | Before a plan is warranted, measure an unknown in a track folder under `.claude/groundwork/` |
|
|
135
137
|
| `aitk:claude-feature` | Before implementation, scan for conflicts and ambiguities |
|
|
136
138
|
| `aitk:claude-roadmap` | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md` |
|
package/package.json
CHANGED
package/standards/rule.md
CHANGED
|
@@ -19,6 +19,14 @@ Does not govern:
|
|
|
19
19
|
- Skill folders and skill frontmatter: `skill.md`
|
|
20
20
|
- Cross-domain behavior rules, which live in `CLAUDE.md` at the project root
|
|
21
21
|
|
|
22
|
+
## Whether a skill belongs behind the rule
|
|
23
|
+
|
|
24
|
+
A rule fires on a path match with no decision from the session, which is what makes it a floor. Every bullet is one directive and nothing else, so an invariant needing procedure, worked cases, or a branch on project state has no room in the body.
|
|
25
|
+
|
|
26
|
+
Run the two-part test in reverse before calling the rule finished. The rule already holds what fires on a path edit and ships silently when violated. Ask what a session still needs past the directive, and give that to a skill the rule points at, because a rule that grows a procedure has become a skill body wearing rule frontmatter.
|
|
27
|
+
|
|
28
|
+
Write both when both apply. A rule stating the directive and a skill stating how to carry it out are one invariant at two depths rather than two copies of it, and `skill.md` carries the same checkpoint for a session arriving from the other side. Nothing checks either one.
|
|
29
|
+
|
|
22
30
|
## Location
|
|
23
31
|
|
|
24
32
|
- Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`
|
package/standards/skill.md
CHANGED
|
@@ -22,6 +22,14 @@ Does not govern:
|
|
|
22
22
|
- The transform from a branch name to a slug a skill carries in a filename: `slug.md`
|
|
23
23
|
- The domain conventions a skill cites, each of which belongs to the standard that owns it
|
|
24
24
|
|
|
25
|
+
## Whether a rule belongs beside the skill
|
|
26
|
+
|
|
27
|
+
A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads a file matching its glob, with no decision from the session at all. The two are layers rather than alternatives, so the rule is the floor and the skill is the depth.
|
|
28
|
+
|
|
29
|
+
Run the two-part test over what the body states before calling the skill finished. Does the invariant fire when a specific path is edited, and does violating it ship silently? An invariant passing both halves belongs in a rule as well, because a session that never invoked the skill still edits that path and needs the floor under it. An invariant failing either half stays here, which is most of a body, since procedure and orientation are what a rule cannot carry.
|
|
30
|
+
|
|
31
|
+
Write that rule to the shape `rule.md` sets and leave the procedure here, since the two carry one invariant at two depths rather than two copies of it. Nothing checks the split. The checkpoint is a judgment prompt rather than an invariant, so it ships as prose with no gate behind it, and a skill that skips it fails silently in the same way the invariants it is meant to catch do.
|
|
32
|
+
|
|
25
33
|
## Skill types
|
|
26
34
|
|
|
27
35
|
Pick the type before writing. It decides the body shape.
|