@ikon85/agent-workflow-kit 0.20.0 → 0.22.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/.agents/skills/project-release/SKILL.md +71 -0
- package/.agents/skills/setup-workflow/SKILL.md +36 -0
- package/.agents/skills/setup-workflow/workflow-overview.md +1 -0
- package/.agents/skills/setup-workflow/worktree-lifecycle.md +81 -0
- package/.claude/hooks/slice-handoff-hint.py +25 -0
- package/.claude/skills/project-release/SKILL.md +71 -0
- package/.claude/skills/setup-workflow/SKILL.md +36 -0
- package/.claude/skills/setup-workflow/workflow-overview.md +1 -0
- package/.claude/skills/setup-workflow/worktree-lifecycle.md +81 -0
- package/.claude/skills/skill-manifest.json +10 -0
- package/PROVENANCE.md +1 -1
- package/README.md +26 -2
- package/agent-workflow-kit.package.json +74 -10
- package/package.json +1 -1
- package/scripts/kit-release.mjs +15 -10
- package/scripts/project-release.mjs +70 -0
- package/scripts/test_skill_publish_audit.py +28 -9
- package/scripts/test_worktree_wrapup_contract.py +52 -0
- package/scripts/worktree-lifecycle/README.md +8 -0
- package/scripts/worktree-lifecycle/capabilities.json +8 -0
- package/scripts/worktree-lifecycle/cleanup.py +57 -0
- package/scripts/worktree-lifecycle/core.py +80 -0
- package/scripts/wrapup-land.py +45 -0
- package/src/lib/bundle.mjs +6 -1
- package/src/lib/release-apply.mjs +81 -0
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: project-release
|
|
3
|
+
description: "Preview and prepare one coherent version change across a consumer's profiled packages without duplicating release logic or creating commits, tags, pushes, publishes, or merges."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Project Release
|
|
7
|
+
|
|
8
|
+
Prepare a consumer-owned multi-package release through the kit's shared
|
|
9
|
+
SemVer, preview, and transactional apply engine. This skill changes only the
|
|
10
|
+
profiled version files. It does not commit, tag, push, publish, or merge.
|
|
11
|
+
|
|
12
|
+
## Profile contract
|
|
13
|
+
|
|
14
|
+
Read `docs/agents/workflow-capabilities.json`. The consumer owns this file and
|
|
15
|
+
its unknown keys. Project Release requires this versioned section:
|
|
16
|
+
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"schemaVersion": 1,
|
|
20
|
+
"projectRelease": {
|
|
21
|
+
"versionFiles": [
|
|
22
|
+
"package.json",
|
|
23
|
+
"packages/example/package.json"
|
|
24
|
+
],
|
|
25
|
+
"tagPrefix": "v"
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Every `versionFiles` path is repository-relative and must name a JSON file with
|
|
31
|
+
the same current SemVer. Never infer or silently add package files.
|
|
32
|
+
|
|
33
|
+
## Workflow
|
|
34
|
+
|
|
35
|
+
1. Run a byte-neutral preview for exactly one Patch, Minor, Major, or explicit
|
|
36
|
+
SemVer target:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
node scripts/project-release.mjs preview <patch|minor|major|version>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
2. Report the structured result: exact current and target version, package
|
|
43
|
+
count, synchronized files, planned commit/tag actions, confirmation token,
|
|
44
|
+
and every blocker. Invalid or divergent versions, dirty profiled targets,
|
|
45
|
+
and an existing target tag block before the first write.
|
|
46
|
+
|
|
47
|
+
3. Ask the user to confirm the exact target and preview confirmation token.
|
|
48
|
+
Do not treat a bump recommendation or a prior preview as confirmation.
|
|
49
|
+
|
|
50
|
+
4. Apply only that still-current preview:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
node scripts/project-release.mjs apply <patch|minor|major|version> \
|
|
54
|
+
--confirm <confirmation-token>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Apply re-reads repository facts and every target byte. A stale token,
|
|
58
|
+
changed target, blocked preview, partial write, or repeated apply fails
|
|
59
|
+
without a double bump. Partial writes roll back to the original bytes.
|
|
60
|
+
|
|
61
|
+
5. Inspect the resulting version-file diff, then hand commit, tag, push,
|
|
62
|
+
publish, and merge to the repository's normal release/landing workflow.
|
|
63
|
+
Project Release does not commit, tag, push, publish, or merge.
|
|
64
|
+
|
|
65
|
+
## Safety contract
|
|
66
|
+
|
|
67
|
+
- Preview is repeatable and byte-neutral.
|
|
68
|
+
- Apply writes only `projectRelease.versionFiles`.
|
|
69
|
+
- Commit and tag entries in preview output are plans, never side effects.
|
|
70
|
+
- Existing tags are never overwritten.
|
|
71
|
+
- No runtime dependency is required beyond Node.js and Git.
|
|
@@ -26,6 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
|
|
|
26
26
|
| `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
|
|
27
27
|
| `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
|
|
28
28
|
| `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
|
|
29
|
+
| `docs/agents/workflow-capabilities.json` | consumer-owned capability profile, including optional Worktree Lifecycle activation (Section A4) |
|
|
29
30
|
|
|
30
31
|
## Idempotency contract — read before writing anything
|
|
31
32
|
|
|
@@ -56,6 +57,7 @@ Read the current state; don't assume. For every target file, read its first line
|
|
|
56
57
|
- `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
|
|
57
58
|
- `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
|
|
58
59
|
- `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
|
|
60
|
+
- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — an existing Worktree Lifecycle choice/profile and hook wiring to adopt.
|
|
59
61
|
- `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
|
|
60
62
|
|
|
61
63
|
### 2. Section A — Issue tracker
|
|
@@ -135,6 +137,34 @@ activate without rerunning setup. Disable enforcement first, but retain every
|
|
|
135
137
|
consumer-owned profile, scanner, test, and active snapshot unless the user
|
|
136
138
|
separately approves deletion. Repeated runs are no-ops after reconciliation.
|
|
137
139
|
|
|
140
|
+
### 2c. Section A4 — Optional Worktree Lifecycle
|
|
141
|
+
|
|
142
|
+
> Worktree Lifecycle is one consumer capability for isolated setup, shared
|
|
143
|
+
> branch/worktree facts, enforcement, handoff, and safe cleanup. The profile is
|
|
144
|
+
> tracked and consumer-owned; hook wiring activates only after an explicit yes.
|
|
145
|
+
|
|
146
|
+
Read [worktree-lifecycle.md](./worktree-lifecycle.md) in full. Reconcile the
|
|
147
|
+
complete `yes / later / no / existing / disable` matrix from its structured
|
|
148
|
+
contract. If no choice exists, ask: *"Should setup activate the portable
|
|
149
|
+
Worktree Lifecycle for this repository?"* Offer exactly **Yes**, **Later**, and
|
|
150
|
+
**No**.
|
|
151
|
+
|
|
152
|
+
- **Yes** — create or deepen only the `worktreeLifecycle` section in
|
|
153
|
+
`docs/agents/workflow-capabilities.json`, preserve every other section and
|
|
154
|
+
unknown key, and reconcile only the exact kit-owned hook commands listed in
|
|
155
|
+
the seed.
|
|
156
|
+
- **Later / No** — record the choice in the tracked profile without installing
|
|
157
|
+
hook wiring. Ordinary reruns do not ask again.
|
|
158
|
+
- **Existing** — adopt the current section and wiring without normalizing
|
|
159
|
+
consumer-owned values.
|
|
160
|
+
- **Disable** — remove only the exact kit-owned hook commands first, then set
|
|
161
|
+
`enabled: false`; retain the profile, setup policy, and unknown keys.
|
|
162
|
+
|
|
163
|
+
The default setup entry is
|
|
164
|
+
`python3 scripts/worktree-lifecycle/setup.py`; a proven consumer-native helper
|
|
165
|
+
may remain the configured `setupEntry` for parity. The handoff advisory always
|
|
166
|
+
reads that configured entry and never hardcodes a project script.
|
|
167
|
+
|
|
138
168
|
### 3. Section B — Triage labels
|
|
139
169
|
|
|
140
170
|
> When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
|
|
@@ -220,6 +250,12 @@ pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
|
|
|
220
250
|
existing census are terminal for ordinary setup reruns. Only an explicit user
|
|
221
251
|
request changes a recorded choice.
|
|
222
252
|
|
|
253
|
+
For `docs/agents/workflow-capabilities.json`, reconcile only the selected
|
|
254
|
+
capability section. Never replace the whole file: Project Release, Memory
|
|
255
|
+
Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
|
|
256
|
+
this profile. Apply the Worktree Lifecycle transition and hook ownership rules
|
|
257
|
+
from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
|
|
258
|
+
|
|
223
259
|
For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
|
|
224
260
|
|
|
225
261
|
- If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).
|
|
@@ -21,6 +21,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
|
|
|
21
21
|
- **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
|
|
22
22
|
- **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
|
|
23
23
|
- **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
|
|
24
|
+
- **Consumer project release:** use `project-release` to preview and transactionally prepare one coherent version across the package files named by the consumer-owned capability profile.
|
|
24
25
|
- **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
|
|
25
26
|
- **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
|
|
26
27
|
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Worktree Lifecycle setup contract
|
|
2
|
+
|
|
3
|
+
Worktree Lifecycle is one opt-in capability backed by the consumer-owned
|
|
4
|
+
`docs/agents/workflow-capabilities.json` profile. Enabling it activates the
|
|
5
|
+
portable setup entry, shared branch/worktree facts, thin hook adapters, handoff
|
|
6
|
+
advisory, and safe cleanup policy as one unit.
|
|
7
|
+
|
|
8
|
+
## Choice matrix
|
|
9
|
+
|
|
10
|
+
| State | Setup action |
|
|
11
|
+
|---|---|
|
|
12
|
+
| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
|
|
13
|
+
| `yes` | Reconcile the enabled profile and exact kit-owned hook commands. |
|
|
14
|
+
| `later` | Record the retryable deferral; do not activate hooks. |
|
|
15
|
+
| `no` | Record the opt-out; do not activate hooks. |
|
|
16
|
+
| `existing` | Adopt the consumer profile byte-safely and preserve unknown keys. |
|
|
17
|
+
| `disable` | Remove only kit-owned hook wiring, then set `enabled: false`; retain the profile and unknown keys. |
|
|
18
|
+
|
|
19
|
+
```json worktree-lifecycle-setup-effects
|
|
20
|
+
[
|
|
21
|
+
{
|
|
22
|
+
"state": "missing",
|
|
23
|
+
"choice": null,
|
|
24
|
+
"operations": []
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"state": "yes",
|
|
28
|
+
"choice": "yes",
|
|
29
|
+
"operations": [
|
|
30
|
+
"record-choice",
|
|
31
|
+
"reconcile-profile-enabled",
|
|
32
|
+
"reconcile-hook-wiring"
|
|
33
|
+
]
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
"state": "later",
|
|
37
|
+
"choice": "later",
|
|
38
|
+
"operations": [
|
|
39
|
+
"record-choice"
|
|
40
|
+
]
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
"state": "no",
|
|
44
|
+
"choice": "no",
|
|
45
|
+
"operations": [
|
|
46
|
+
"record-choice"
|
|
47
|
+
]
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
"state": "existing",
|
|
51
|
+
"choice": "yes",
|
|
52
|
+
"operations": [
|
|
53
|
+
"adopt-existing"
|
|
54
|
+
]
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
"state": "disable",
|
|
58
|
+
"choice": "yes",
|
|
59
|
+
"operations": [
|
|
60
|
+
"remove-hook-wiring",
|
|
61
|
+
"update-profile-disabled"
|
|
62
|
+
]
|
|
63
|
+
}
|
|
64
|
+
]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Hook ownership
|
|
68
|
+
|
|
69
|
+
The exact kit-owned commands are:
|
|
70
|
+
|
|
71
|
+
- SessionStart: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/branch-context.py"`
|
|
72
|
+
- UserPromptSubmit: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/slice-handoff-hint.py"`
|
|
73
|
+
- PostToolUse on Bash: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/branch-watch.py"`
|
|
74
|
+
- PreToolUse on Edit/Write/MultiEdit:
|
|
75
|
+
`python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree.py"`
|
|
76
|
+
- PreToolUse on Bash:
|
|
77
|
+
`python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree-cwd.py"` and
|
|
78
|
+
`python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree-discipline.py"`
|
|
79
|
+
|
|
80
|
+
Preserve unrelated settings, hook groups, profile sections, and unknown keys.
|
|
81
|
+
Repeated reconciliation with the same choice is byte-identical.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""UserPromptSubmit adapter for configured Worktree Lifecycle handoffs."""
|
|
3
|
+
|
|
4
|
+
import json
|
|
5
|
+
import sys
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
from _hook_utils import hook_event_output, load_worktree_lifecycle_core
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def main() -> int:
|
|
12
|
+
try:
|
|
13
|
+
payload = json.load(sys.stdin)
|
|
14
|
+
core = load_worktree_lifecycle_core()
|
|
15
|
+
profile = core.load_profile(Path("docs/agents/workflow-capabilities.json"))
|
|
16
|
+
decision = core.evaluate(profile, core.collect_facts(Path.cwd()), "handoff", payload)
|
|
17
|
+
except Exception:
|
|
18
|
+
return 0
|
|
19
|
+
if decision.action == "emit":
|
|
20
|
+
print(json.dumps(hook_event_output(decision.event_name, decision.message)))
|
|
21
|
+
return 0
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
if __name__ == "__main__":
|
|
25
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: project-release
|
|
3
|
+
description: "Preview and prepare one coherent version change across a consumer's profiled packages without duplicating release logic or creating commits, tags, pushes, publishes, or merges."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Project Release
|
|
7
|
+
|
|
8
|
+
Prepare a consumer-owned multi-package release through the kit's shared
|
|
9
|
+
SemVer, preview, and transactional apply engine. This skill changes only the
|
|
10
|
+
profiled version files. It does not commit, tag, push, publish, or merge.
|
|
11
|
+
|
|
12
|
+
## Profile contract
|
|
13
|
+
|
|
14
|
+
Read `docs/agents/workflow-capabilities.json`. The consumer owns this file and
|
|
15
|
+
its unknown keys. Project Release requires this versioned section:
|
|
16
|
+
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"schemaVersion": 1,
|
|
20
|
+
"projectRelease": {
|
|
21
|
+
"versionFiles": [
|
|
22
|
+
"package.json",
|
|
23
|
+
"packages/example/package.json"
|
|
24
|
+
],
|
|
25
|
+
"tagPrefix": "v"
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Every `versionFiles` path is repository-relative and must name a JSON file with
|
|
31
|
+
the same current SemVer. Never infer or silently add package files.
|
|
32
|
+
|
|
33
|
+
## Workflow
|
|
34
|
+
|
|
35
|
+
1. Run a byte-neutral preview for exactly one Patch, Minor, Major, or explicit
|
|
36
|
+
SemVer target:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
node scripts/project-release.mjs preview <patch|minor|major|version>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
2. Report the structured result: exact current and target version, package
|
|
43
|
+
count, synchronized files, planned commit/tag actions, confirmation token,
|
|
44
|
+
and every blocker. Invalid or divergent versions, dirty profiled targets,
|
|
45
|
+
and an existing target tag block before the first write.
|
|
46
|
+
|
|
47
|
+
3. Ask the user to confirm the exact target and preview confirmation token.
|
|
48
|
+
Do not treat a bump recommendation or a prior preview as confirmation.
|
|
49
|
+
|
|
50
|
+
4. Apply only that still-current preview:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
node scripts/project-release.mjs apply <patch|minor|major|version> \
|
|
54
|
+
--confirm <confirmation-token>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Apply re-reads repository facts and every target byte. A stale token,
|
|
58
|
+
changed target, blocked preview, partial write, or repeated apply fails
|
|
59
|
+
without a double bump. Partial writes roll back to the original bytes.
|
|
60
|
+
|
|
61
|
+
5. Inspect the resulting version-file diff, then hand commit, tag, push,
|
|
62
|
+
publish, and merge to the repository's normal release/landing workflow.
|
|
63
|
+
Project Release does not commit, tag, push, publish, or merge.
|
|
64
|
+
|
|
65
|
+
## Safety contract
|
|
66
|
+
|
|
67
|
+
- Preview is repeatable and byte-neutral.
|
|
68
|
+
- Apply writes only `projectRelease.versionFiles`.
|
|
69
|
+
- Commit and tag entries in preview output are plans, never side effects.
|
|
70
|
+
- Existing tags are never overwritten.
|
|
71
|
+
- No runtime dependency is required beyond Node.js and Git.
|
|
@@ -26,6 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
|
|
|
26
26
|
| `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
|
|
27
27
|
| `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
|
|
28
28
|
| `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
|
|
29
|
+
| `docs/agents/workflow-capabilities.json` | consumer-owned capability profile, including optional Worktree Lifecycle activation (Section A4) |
|
|
29
30
|
|
|
30
31
|
## Idempotency contract — read before writing anything
|
|
31
32
|
|
|
@@ -56,6 +57,7 @@ Read the current state; don't assume. For every target file, read its first line
|
|
|
56
57
|
- `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
|
|
57
58
|
- `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
|
|
58
59
|
- `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
|
|
60
|
+
- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — an existing Worktree Lifecycle choice/profile and hook wiring to adopt.
|
|
59
61
|
- `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
|
|
60
62
|
|
|
61
63
|
### 2. Section A — Issue tracker
|
|
@@ -135,6 +137,34 @@ activate without rerunning setup. Disable enforcement first, but retain every
|
|
|
135
137
|
consumer-owned profile, scanner, test, and active snapshot unless the user
|
|
136
138
|
separately approves deletion. Repeated runs are no-ops after reconciliation.
|
|
137
139
|
|
|
140
|
+
### 2c. Section A4 — Optional Worktree Lifecycle
|
|
141
|
+
|
|
142
|
+
> Worktree Lifecycle is one consumer capability for isolated setup, shared
|
|
143
|
+
> branch/worktree facts, enforcement, handoff, and safe cleanup. The profile is
|
|
144
|
+
> tracked and consumer-owned; hook wiring activates only after an explicit yes.
|
|
145
|
+
|
|
146
|
+
Read [worktree-lifecycle.md](./worktree-lifecycle.md) in full. Reconcile the
|
|
147
|
+
complete `yes / later / no / existing / disable` matrix from its structured
|
|
148
|
+
contract. If no choice exists, ask: *"Should setup activate the portable
|
|
149
|
+
Worktree Lifecycle for this repository?"* Offer exactly **Yes**, **Later**, and
|
|
150
|
+
**No**.
|
|
151
|
+
|
|
152
|
+
- **Yes** — create or deepen only the `worktreeLifecycle` section in
|
|
153
|
+
`docs/agents/workflow-capabilities.json`, preserve every other section and
|
|
154
|
+
unknown key, and reconcile only the exact kit-owned hook commands listed in
|
|
155
|
+
the seed.
|
|
156
|
+
- **Later / No** — record the choice in the tracked profile without installing
|
|
157
|
+
hook wiring. Ordinary reruns do not ask again.
|
|
158
|
+
- **Existing** — adopt the current section and wiring without normalizing
|
|
159
|
+
consumer-owned values.
|
|
160
|
+
- **Disable** — remove only the exact kit-owned hook commands first, then set
|
|
161
|
+
`enabled: false`; retain the profile, setup policy, and unknown keys.
|
|
162
|
+
|
|
163
|
+
The default setup entry is
|
|
164
|
+
`python3 scripts/worktree-lifecycle/setup.py`; a proven consumer-native helper
|
|
165
|
+
may remain the configured `setupEntry` for parity. The handoff advisory always
|
|
166
|
+
reads that configured entry and never hardcodes a project script.
|
|
167
|
+
|
|
138
168
|
### 3. Section B — Triage labels
|
|
139
169
|
|
|
140
170
|
> When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
|
|
@@ -220,6 +250,12 @@ pre-existing consumer-owned census file. `yes`, `later`, `no`, and an adopted
|
|
|
220
250
|
existing census are terminal for ordinary setup reruns. Only an explicit user
|
|
221
251
|
request changes a recorded choice.
|
|
222
252
|
|
|
253
|
+
For `docs/agents/workflow-capabilities.json`, reconcile only the selected
|
|
254
|
+
capability section. Never replace the whole file: Project Release, Memory
|
|
255
|
+
Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
|
|
256
|
+
this profile. Apply the Worktree Lifecycle transition and hook ownership rules
|
|
257
|
+
from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
|
|
258
|
+
|
|
223
259
|
For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
|
|
224
260
|
|
|
225
261
|
- If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).
|
|
@@ -21,6 +21,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
|
|
|
21
21
|
- **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
|
|
22
22
|
- **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
|
|
23
23
|
- **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
|
|
24
|
+
- **Consumer project release:** use `project-release` to preview and transactionally prepare one coherent version across the package files named by the consumer-owned capability profile.
|
|
24
25
|
- **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
|
|
25
26
|
- **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
|
|
26
27
|
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Worktree Lifecycle setup contract
|
|
2
|
+
|
|
3
|
+
Worktree Lifecycle is one opt-in capability backed by the consumer-owned
|
|
4
|
+
`docs/agents/workflow-capabilities.json` profile. Enabling it activates the
|
|
5
|
+
portable setup entry, shared branch/worktree facts, thin hook adapters, handoff
|
|
6
|
+
advisory, and safe cleanup policy as one unit.
|
|
7
|
+
|
|
8
|
+
## Choice matrix
|
|
9
|
+
|
|
10
|
+
| State | Setup action |
|
|
11
|
+
|---|---|
|
|
12
|
+
| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
|
|
13
|
+
| `yes` | Reconcile the enabled profile and exact kit-owned hook commands. |
|
|
14
|
+
| `later` | Record the retryable deferral; do not activate hooks. |
|
|
15
|
+
| `no` | Record the opt-out; do not activate hooks. |
|
|
16
|
+
| `existing` | Adopt the consumer profile byte-safely and preserve unknown keys. |
|
|
17
|
+
| `disable` | Remove only kit-owned hook wiring, then set `enabled: false`; retain the profile and unknown keys. |
|
|
18
|
+
|
|
19
|
+
```json worktree-lifecycle-setup-effects
|
|
20
|
+
[
|
|
21
|
+
{
|
|
22
|
+
"state": "missing",
|
|
23
|
+
"choice": null,
|
|
24
|
+
"operations": []
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"state": "yes",
|
|
28
|
+
"choice": "yes",
|
|
29
|
+
"operations": [
|
|
30
|
+
"record-choice",
|
|
31
|
+
"reconcile-profile-enabled",
|
|
32
|
+
"reconcile-hook-wiring"
|
|
33
|
+
]
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
"state": "later",
|
|
37
|
+
"choice": "later",
|
|
38
|
+
"operations": [
|
|
39
|
+
"record-choice"
|
|
40
|
+
]
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
"state": "no",
|
|
44
|
+
"choice": "no",
|
|
45
|
+
"operations": [
|
|
46
|
+
"record-choice"
|
|
47
|
+
]
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
"state": "existing",
|
|
51
|
+
"choice": "yes",
|
|
52
|
+
"operations": [
|
|
53
|
+
"adopt-existing"
|
|
54
|
+
]
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
"state": "disable",
|
|
58
|
+
"choice": "yes",
|
|
59
|
+
"operations": [
|
|
60
|
+
"remove-hook-wiring",
|
|
61
|
+
"update-profile-disabled"
|
|
62
|
+
]
|
|
63
|
+
}
|
|
64
|
+
]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Hook ownership
|
|
68
|
+
|
|
69
|
+
The exact kit-owned commands are:
|
|
70
|
+
|
|
71
|
+
- SessionStart: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/branch-context.py"`
|
|
72
|
+
- UserPromptSubmit: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/slice-handoff-hint.py"`
|
|
73
|
+
- PostToolUse on Bash: `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/branch-watch.py"`
|
|
74
|
+
- PreToolUse on Edit/Write/MultiEdit:
|
|
75
|
+
`python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree.py"`
|
|
76
|
+
- PreToolUse on Bash:
|
|
77
|
+
`python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree-cwd.py"` and
|
|
78
|
+
`python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-worktree-discipline.py"`
|
|
79
|
+
|
|
80
|
+
Preserve unrelated settings, hook groups, profile sections, and unknown keys.
|
|
81
|
+
Repeated reconciliation with the same choice is byte-identical.
|
|
@@ -395,6 +395,16 @@
|
|
|
395
395
|
],
|
|
396
396
|
"provenance": "own"
|
|
397
397
|
},
|
|
398
|
+
"project-release": {
|
|
399
|
+
"class": "generic",
|
|
400
|
+
"publish": true,
|
|
401
|
+
"entryPoint": true,
|
|
402
|
+
"surfaces": [
|
|
403
|
+
"claude",
|
|
404
|
+
"codex"
|
|
405
|
+
],
|
|
406
|
+
"provenance": "own"
|
|
407
|
+
},
|
|
398
408
|
"kit-update": {
|
|
399
409
|
"class": "generic",
|
|
400
410
|
"publish": true,
|
package/PROVENANCE.md
CHANGED
|
@@ -33,7 +33,7 @@ carries Chase's `THIRD-PARTY-NOTICES.md`.
|
|
|
33
33
|
|
|
34
34
|
retro, wrapup, spec-self-critique, board-to-waves, verify-spike, decision-gate,
|
|
35
35
|
codex-adapter-sync, setup-pre-commit, code-review, orchestrate-wave,
|
|
36
|
-
census-update, memory-lifecycle — covered by the root LICENSE.
|
|
36
|
+
census-update, memory-lifecycle, project-release — covered by the root LICENSE.
|
|
37
37
|
`setup-pre-commit` was rewritten from Matt Pocock's husky-based skill to a
|
|
38
38
|
zero-dep native git `core.hooksPath` scaffold; nothing of the original
|
|
39
39
|
mechanic remains (courtesy attribution).
|
package/README.md
CHANGED
|
@@ -332,6 +332,29 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
|
|
|
332
332
|
|
|
333
333
|
## Release notes
|
|
334
334
|
|
|
335
|
+
### 0.22.0
|
|
336
|
+
|
|
337
|
+
- added: `.agents/skills/setup-workflow/worktree-lifecycle.md`
|
|
338
|
+
- added: `.claude/hooks/slice-handoff-hint.py`
|
|
339
|
+
- added: `.claude/skills/setup-workflow/worktree-lifecycle.md`
|
|
340
|
+
- added: `scripts/worktree-lifecycle/cleanup.py`
|
|
341
|
+
- changed: `.agents/skills/setup-workflow/SKILL.md`
|
|
342
|
+
- changed: `.claude/skills/setup-workflow/SKILL.md`
|
|
343
|
+
- changed: `scripts/worktree-lifecycle/README.md`
|
|
344
|
+
- changed: `scripts/worktree-lifecycle/capabilities.json`
|
|
345
|
+
- changed: `scripts/worktree-lifecycle/core.py`
|
|
346
|
+
- changed: `scripts/wrapup-land.py`
|
|
347
|
+
|
|
348
|
+
### 0.21.0
|
|
349
|
+
|
|
350
|
+
- added: `.agents/skills/project-release/SKILL.md`
|
|
351
|
+
- added: `.claude/skills/project-release/SKILL.md`
|
|
352
|
+
- added: `scripts/project-release.mjs`
|
|
353
|
+
- added: `src/lib/release-apply.mjs`
|
|
354
|
+
- changed: `.agents/skills/setup-workflow/workflow-overview.md`
|
|
355
|
+
- changed: `.claude/skills/setup-workflow/workflow-overview.md`
|
|
356
|
+
- changed: `scripts/kit-release.mjs`
|
|
357
|
+
|
|
335
358
|
### 0.20.0
|
|
336
359
|
|
|
337
360
|
- added: `.claude/hooks/branch-context.py`
|
|
@@ -652,12 +675,13 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
|
|
|
652
675
|
|
|
653
676
|
## What's in the box
|
|
654
677
|
|
|
655
|
-
**
|
|
678
|
+
**42 skills** (Router: ask-matt — "which skill/flow fits?" · Plan: grill-me,
|
|
656
679
|
grill-with-docs, to-prd, to-issues, board-to-waves, triage, spec-self-critique,
|
|
657
680
|
verify-spike, decision-gate, scale-check, to-waves, wayfinder, research · Execute: tdd, prototype, implement, orchestrate-wave ·
|
|
658
681
|
Design/diagnose/refactor streams: diagnose, zoom-out,
|
|
659
682
|
improve-codebase-architecture, codebase-design, domain-modeling, security-audit · Land: wrapup,
|
|
660
|
-
resolving-merge-conflicts, code-review, local-ci, git-worktree-recover, kit-release
|
|
683
|
+
resolving-merge-conflicts, code-review, local-ci, git-worktree-recover, kit-release,
|
|
684
|
+
project-release · Learn: retro, audit-skills, write-a-skill · Setup:
|
|
661
685
|
setup-workflow, git-guardrails, setup-pre-commit · Codex cross-model: grill-me-codex,
|
|
662
686
|
grill-with-docs-codex, codex-review, codex-build),
|
|
663
687
|
installed for both surfaces — `.claude/skills`
|