@zalom/plastic 1.14.0 → 2.0.0-alpha.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.
Files changed (190) hide show
  1. package/PLASTIC.md +101 -294
  2. package/README.md +5 -6
  3. package/agents/plastic-advisor.md +18 -17
  4. package/agents/plastic-enforcer.md +57 -69
  5. package/agents/plastic-executor.md +34 -20
  6. package/agents/plastic-faux-advisor.md +18 -18
  7. package/config_asks.yml +38 -0
  8. package/hooks/capture +4 -0
  9. package/hooks/check-update +12 -3
  10. package/hooks/close +5 -0
  11. package/hooks/hooks.json +9 -49
  12. package/hooks/record +4 -0
  13. package/package.json +3 -2
  14. package/scripts/agent-report +8 -9
  15. package/scripts/append-ledger +195 -0
  16. package/scripts/codex-hook +101 -95
  17. package/scripts/dashboard.rb +4 -4
  18. package/scripts/doctor.rb +106 -43
  19. package/scripts/end-intent +77 -76
  20. package/scripts/exec-worktree +11 -20
  21. package/scripts/file-session-intent +61 -0
  22. package/scripts/hook-capture +242 -0
  23. package/scripts/hook-close +34 -0
  24. package/scripts/hook-record +149 -0
  25. package/scripts/hook-session-start +95 -12
  26. package/scripts/install.rb +8 -6
  27. package/scripts/lib/agent_models.rb +1 -7
  28. package/scripts/lib/arm.rb +283 -0
  29. package/scripts/lib/backfill_intent.rb +316 -0
  30. package/scripts/lib/bridge.rb +24 -1597
  31. package/scripts/lib/doctor_core.rb +17 -88
  32. package/scripts/lib/doctor_session_ledger.rb +106 -0
  33. package/scripts/lib/exec_worktree.rb +14 -60
  34. package/scripts/lib/harness_text.rb +5 -4
  35. package/scripts/lib/hook_registry.rb +44 -107
  36. package/scripts/lib/insights.rb +3 -4
  37. package/scripts/lib/installer_core.rb +19 -30
  38. package/scripts/lib/lock.rb +6 -26
  39. package/scripts/lib/outcome_guard.rb +7 -5
  40. package/scripts/lib/project_validator.rb +30 -1
  41. package/scripts/lib/roadmap_queue.rb +3 -3
  42. package/scripts/lib/roadmap_savepoint.rb +1 -1
  43. package/scripts/lib/rule_catalog.rb +6 -3
  44. package/scripts/lib/savepoint.rb +320 -0
  45. package/scripts/lib/scaffold_intent.rb +13 -179
  46. package/scripts/lib/session_backfill.rb +184 -0
  47. package/scripts/lib/session_close.rb +84 -0
  48. package/scripts/lib/session_git.rb +469 -0
  49. package/scripts/lib/session_ledger.rb +497 -0
  50. package/scripts/lib/store_discovery.rb +1 -1
  51. package/scripts/lib/store_provisioning.rb +1 -1
  52. package/scripts/maintenance-run +7 -7
  53. package/scripts/new-intent +63 -4
  54. package/scripts/plastic-lock +94 -41
  55. package/scripts/promote-session-item +150 -0
  56. package/scripts/rebuild-graph +1 -1
  57. package/scripts/roadmap-next +2 -2
  58. package/scripts/rollback.rb +42 -3
  59. package/scripts/scaffold-intent +37 -63
  60. package/scripts/session-commit +116 -0
  61. package/scripts/spawn-preamble +5 -5
  62. package/scripts/update.rb +7 -3
  63. package/skills/agent-advisor/SKILL.md +3 -3
  64. package/skills/agent-advisor/references/advisor-protocol.md +20 -20
  65. package/skills/auto/SKILL.md +218 -317
  66. package/skills/auto/evals/evals.json +10 -10
  67. package/skills/auto/references/agent-architecture.md +102 -90
  68. package/skills/auto/references/agent-report-contract.md +4 -21
  69. package/skills/auto/references/end-tail.md +47 -53
  70. package/skills/auto/references/human-report-contract.md +8 -8
  71. package/skills/conventions/SKILL.md +1 -3
  72. package/skills/conventions/references/lifecycle-and-savepoints.md +35 -1
  73. package/skills/conventions/references/locks-and-worktrees.md +47 -55
  74. package/skills/conventions/references/maintenance-and-revisions.md +12 -12
  75. package/skills/dashboard/SKILL.md +1 -1
  76. package/skills/direct/SKILL.md +66 -0
  77. package/skills/direct/references/request-signals.md +59 -0
  78. package/skills/doctor/SKILL.md +58 -11
  79. package/skills/doctor/report.md +3 -1
  80. package/skills/install/SKILL.md +11 -9
  81. package/skills/intent-continuing/SKILL.md +131 -89
  82. package/skills/intent-continuing/references/boarding-matrix.md +34 -0
  83. package/skills/intent-continuing/references/context-management.md +2 -2
  84. package/skills/intent-creating/SKILL.md +2 -2
  85. package/skills/intent-creating/references/lifecycle.md +1 -1
  86. package/skills/intent-ending/SKILL.md +28 -37
  87. package/skills/intent-ending/evals/evals.json +4 -4
  88. package/skills/intent-executing/SKILL.md +12 -49
  89. package/skills/intent-executing/plan-reviewer-prompt.md +39 -0
  90. package/skills/intent-speccing/SKILL.md +108 -51
  91. package/skills/intent-speccing/evals/evals.json +5 -5
  92. package/skills/intent-speccing/references/per-section-fill-rules.md +4 -4
  93. package/skills/intent-speccing/references/self-verify-checklist.md +1 -2
  94. package/skills/project-creating/SKILL.md +1 -1
  95. package/skills/releasing/SKILL.md +7 -8
  96. package/skills/tutorial/SKILL.md +2 -2
  97. package/skills/tutorial/references/track-1-guided.md +16 -18
  98. package/skills/tutorial/references/track-2-auto.md +12 -13
  99. package/skills/tutorial/references/track-3-projects-and-roadmaps.md +2 -2
  100. package/templates/agents.md +4 -7
  101. package/templates/project.yml +7 -0
  102. package/templates/roadmap.md +1 -1
  103. package/templates/savepoint.md +2 -2
  104. package/templates/session-intent.md +29 -0
  105. package/agents/plastic-brainstorming.md +0 -48
  106. package/agents/plastic-future-intent-researcher.md +0 -35
  107. package/agents/plastic-intent-curator.md +0 -47
  108. package/agents/plastic-intent-discovery.md +0 -43
  109. package/agents/plastic-planner.md +0 -56
  110. package/agents/plastic-spec-specialist.md +0 -53
  111. package/hooks/auto-arm +0 -5
  112. package/hooks/bash-gate +0 -3
  113. package/hooks/continue +0 -31
  114. package/hooks/edit-gates +0 -3
  115. package/hooks/future-intent-check +0 -25
  116. package/hooks/gate-check +0 -12
  117. package/hooks/power-tools +0 -8
  118. package/scripts/hook-auto-arm +0 -51
  119. package/scripts/hook-bash-gate +0 -78
  120. package/scripts/hook-code-gate +0 -38
  121. package/scripts/hook-continue +0 -48
  122. package/scripts/hook-create-gate +0 -51
  123. package/scripts/hook-edit-gates +0 -58
  124. package/scripts/hook-future-intent-check +0 -90
  125. package/scripts/hook-gate-check +0 -169
  126. package/scripts/hook-links-gate +0 -54
  127. package/scripts/hook-lock-gate +0 -47
  128. package/scripts/hook-power-tools +0 -38
  129. package/scripts/hook-savepoint-pre +0 -32
  130. package/scripts/lib/codex_edit_gates.rb +0 -138
  131. package/scripts/lib/edit_gates.rb +0 -398
  132. package/scripts/lib/links_gate.rb +0 -140
  133. package/scripts/lib/qmd_hook.rb +0 -41
  134. package/scripts/lib/spec_header.rb +0 -83
  135. package/scripts/lib/start_intent.rb +0 -296
  136. package/scripts/start-intent +0 -89
  137. package/skills/_active-intent-gate.md +0 -26
  138. package/skills/auto/references/tiers.md +0 -100
  139. package/skills/continuing/SKILL.md +0 -34
  140. package/skills/continuing/evals/evals.json +0 -91
  141. package/skills/conventions/references/gates-and-enforcement.md +0 -53
  142. package/skills/conventions/references/tiers-and-dispatch.md +0 -135
  143. package/skills/doctor/references/gates-stuck-detection.md +0 -43
  144. package/skills/intent-brainstorming/SKILL.md +0 -118
  145. package/skills/intent-brainstorming/evals/evals.json +0 -67
  146. package/skills/intent-continuing/evals/evals.json +0 -145
  147. package/skills/intent-discovering/SKILL.md +0 -56
  148. package/skills/intent-grilling/SKILL.md +0 -108
  149. package/skills/intent-linking/SKILL.md +0 -128
  150. package/skills/intent-linking/evals/evals.json +0 -22
  151. package/skills/intent-linking/references/zettelkasten.md +0 -45
  152. package/skills/intent-locking/SKILL.md +0 -64
  153. package/skills/intent-planning/SKILL.md +0 -145
  154. package/skills/intent-planning/evals/evals.json +0 -81
  155. package/skills/intent-planning/references/plan-format.md +0 -130
  156. package/skills/intent-researching/SKILL.md +0 -123
  157. package/skills/intent-researching/evals/evals.json +0 -22
  158. package/skills/intent-savepoint/SKILL.md +0 -83
  159. package/skills/intent-savepoint/references/context-management.md +0 -32
  160. package/skills/intent-starting/SKILL.md +0 -151
  161. package/skills/intent-starting/evals/evals.json +0 -117
  162. package/skills/intent-starting/references/boarding-matrix.md +0 -35
  163. package/skills/project-continuing/SKILL.md +0 -119
  164. package/skills/project-continuing/evals/evals.json +0 -100
  165. package/skills/roadmap-continuing/SKILL.md +0 -89
  166. package/skills/roadmap-continuing/evals/evals.json +0 -82
  167. package/skills/skill-creating/SKILL.md +0 -75
  168. package/skills/skill-creating/evals/evals.json +0 -108
  169. package/skills/skill-creating/references/agents.md +0 -168
  170. package/skills/skill-creating/references/defaults-first.md +0 -23
  171. package/skills/skill-creating/references/evals.md +0 -41
  172. package/skills/skill-creating/references/hooks.md +0 -251
  173. package/skills/skill-creating/references/progressive-disclosure.md +0 -176
  174. package/skills/skill-creating/references/scripts.md +0 -166
  175. package/skills/skill-creating/references/skills.md +0 -169
  176. package/skills/skill-creating/scripts/scaffold.rb +0 -313
  177. package/skills/skill-evaluating/SKILL.md +0 -141
  178. package/skills/skill-evaluating/assets/eval-template.json +0 -12
  179. package/skills/skill-evaluating/evals/evals.json +0 -75
  180. package/skills/skill-evaluating/references/convention-checks.md +0 -76
  181. package/skills/skill-evaluating/references/eval-methodology.md +0 -154
  182. package/skills/store-curating/SKILL.md +0 -64
  183. package/skills/store-curating/evals/evals.json +0 -38
  184. package/skills/store-indexing/SKILL.md +0 -93
  185. package/skills/store-indexing/evals/evals.json +0 -22
  186. package/skills/store-indexing/references/zettelkasten-linking.md +0 -32
  187. package/skills/store-provisioning/SKILL.md +0 -55
  188. /package/skills/{project-continuing → intent-continuing}/references/board-fill.md +0 -0
  189. /package/skills/{roadmap-continuing → intent-continuing}/references/liveness-ranking.md +0 -0
  190. /package/skills/{intent-brainstorming → intent-speccing}/references/design-principles.md +0 -0
@@ -1,130 +0,0 @@
1
- # Plan, Checklist, and Action Format
2
-
3
- The exact templates for `plan.md`'s header and task structure, and for the
4
- `checklist.md` and `actions/ACTION_N.md` artifacts. Read this before writing
5
- plan.md so the shape matches on the first pass.
6
-
7
- ## Table of Contents
8
-
9
- - [Plan Document Header](#plan-document-header)
10
- - [Task Structure (worked example)](#task-structure-worked-example)
11
- - [checklist.md format](#checklistmd-format)
12
- - [actions/ACTION_N.md format](#actionsaction_nmd-format)
13
-
14
- ## Plan Document Header
15
-
16
- **Every plan MUST start with this header:**
17
-
18
- ```markdown
19
- # [Feature Name] Implementation Plan
20
-
21
- > **For agentic workers:** Use `plastic-intent-executing` to implement this plan task-by-task.
22
-
23
- **Goal:** [One sentence describing what this builds]
24
-
25
- **Architecture:** [2-3 sentences about approach]
26
-
27
- **Tech Stack:** [Key technologies/libraries]
28
-
29
- **Intent:** {id}: {name}
30
-
31
- **Tier:** S|M|L, copied from the spec's stamped `Tier:` line. Every tier produces at
32
- least one real `actions/ACTION_N.md`; S and M consolidate the delivery into one action
33
- file, L uses one `actions/ACTION_N.md` per task.
34
-
35
- ---
36
- ```
37
-
38
- ## Task Structure (worked example)
39
-
40
- ````markdown
41
- ### Task N: [Component Name]
42
-
43
- **Files:**
44
- - Create: `exact/path/to/file.rb`
45
- - Modify: `exact/path/to/existing.rb:123-145`
46
- - Test: `test/exact/path/to/test.rb`
47
-
48
- - [ ] **Step 1: Write the failing test**
49
-
50
- ```ruby
51
- def test_specific_behavior
52
- result = function(input)
53
- assert_equal expected, result
54
- end
55
- ```
56
-
57
- - [ ] **Step 2: Run test to verify it fails**
58
-
59
- Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
60
- Expected: FAIL with "undefined method"
61
-
62
- - [ ] **Step 3: Write minimal implementation**
63
-
64
- ```ruby
65
- def function(input)
66
- expected
67
- end
68
- ```
69
-
70
- - [ ] **Step 4: Run test to verify it passes**
71
-
72
- Run: `ruby -Itest test/path/test.rb --name test_specific_behavior`
73
- Expected: PASS
74
-
75
- - [ ] **Step 5: Commit**
76
-
77
- ```bash
78
- git add test/path/test.rb lib/path/file.rb
79
- git commit -m "feat: add specific feature"
80
- ```
81
- ````
82
-
83
- ## checklist.md format
84
-
85
- Execution registry with one checkbox per task, following this FORM regardless
86
- of tier (S, M, or L):
87
-
88
- ```markdown
89
- # Checklist: {name}
90
-
91
- ## In Progress
92
- - [ ] Task 1: {task title}
93
- - [ ] Task 2: {task title}
94
- - [ ] Task 3: {task title}
95
-
96
- ## Completed
97
- (empty at plan time; move each item here, checked, the moment its task lands)
98
-
99
- ## Session Log
100
- | Date | Items Completed | Notes |
101
- |------|-----------------|-------|
102
- ```
103
-
104
- - `## In Progress` holds every unchecked task, in plan order.
105
- - `## Completed` starts empty. As execution lands a task, move its item here
106
- (checked) instead of leaving a checked box under `## In Progress`.
107
- - `## Session Log` gets one row per work session: the date, which items
108
- completed, and any deviation or finding worth recording.
109
- - An owner-decision hard-gate item (see the parent SKILL.md's
110
- `## Owner-decision hard-gate items`) is a normal checklist item prefixed
111
- `[ORCHESTRATOR]`; it lives under `## In Progress` until the owner rules, then
112
- moves to `## Completed` like any other item.
113
-
114
- ## actions/ACTION_N.md format
115
-
116
- Every tier writes at least one real action file here (see the parent SKILL.md's
117
- `## Tier shapes`): S and M consolidate the whole delivery into a single
118
- `actions/ACTION_1.md`, L writes one file per task.
119
-
120
- Each action is self-contained: a subagent (or a solo executor) can execute it without
121
- reading the plan. It carries the ordered steps to deliver the task plus the exact changes
122
- to make (for code, the anchor or `file:line` and the old/new text).
123
-
124
- ```markdown
125
- # Action {N}: {task title}
126
-
127
- {Full task text copied from plan.md: all steps, all code, all commands. Nothing omitted.}
128
- ```
129
-
130
- Create the `actions/` directory inside the intent directory: `{intent_dir}/actions/`
@@ -1,123 +0,0 @@
1
- ---
2
- name: plastic-intent-researching
3
- description: "Research a topic for the active intent. Agent decides shallow vs deep based on scope. Produces reports in the intent's resources/ directory."
4
- user-invocable: true
5
- ---
6
-
7
- # Research
8
-
9
- Investigate a topic related to the active intent. Choose the right depth, produce a cited report.
10
-
11
- ## Active Intent Gate
12
-
13
- Before proceeding, resolve the active intent:
14
-
15
- 1. **Detect store:** Read `~/.plastic/projects.yml`, match CWD against registered project paths. If match → project store at `~/.plastic/projects/{slug}/store/`. If no match → global store at `~/.plastic/store/`.
16
- 2. **Find active intent:** Read `INDEX.md` from the detected store. Look under `## Active`. If exactly one → use it. If multiple → ask which. If none → refuse: "No active intent. Create one first with /plastic-intent-creating"
17
- 3. **Resolve intent directory:** `{store}/store/{id}--{slug}/`
18
-
19
- ## Check Prior Work First
20
-
21
- QMD-first (when available): before scanning the store with grep/Read or searching the web, run
22
- `ruby ~/.plastic/scripts/qmd-sync search "<terms>"` to surface candidate, prior, or related intents
23
- and existing research, then open the authoritative intent file for any hit you act on. Reusing a
24
- prior report beats re-deriving it. The command is a no-op when QMD is absent, so fall back to the
25
- existing INDEX.md / file scan.
26
-
27
- ## Depth Decision
28
-
29
- Before starting research, assess the question against these criteria:
30
-
31
- ### Shallow Research
32
- Use when:
33
- - The question is narrow and factual (e.g., "what's the API for X?", "does library Y support Z?")
34
- - A single source or quick search is sufficient
35
- - The answer is likely well-documented
36
- - Time budget: minutes, not hours
37
-
38
- **Method:** Direct web search + codebase exploration + single-pass synthesis.
39
-
40
- ### Deep Research
41
- Use when:
42
- - The question needs multiple sources and cross-verification
43
- - It's a landscape survey, competitive analysis, or architectural decision
44
- - The user explicitly asks for thorough/exhaustive/comprehensive research
45
- - Conflicting information exists and needs adversarial verification
46
- - Time budget: significant, user expects depth
47
-
48
- **Method:** Delegate to the native agent's deep research capability.
49
- - On Claude Code: invoke the `deep-research` skill via `Skill` tool
50
- - On other agents: use the agent's equivalent (see intent 7 for cross-agent mapping)
51
- - If no native deep research exists: fan out multiple web searches manually, cross-reference, synthesize
52
-
53
- ### Decision Heuristic
54
-
55
- Ask yourself:
56
- 1. Can I answer this with 1-2 searches? → **Shallow**
57
- 2. Do I need to compare 3+ sources? → **Deep**
58
- 3. Is the user asking for a survey or landscape view? → **Deep**
59
- 4. Am I fact-checking a specific claim? → **Shallow**
60
- 5. Could wrong information here cause architectural mistakes? → **Deep**
61
-
62
- Announce your choice: "This needs [shallow/deep] research because [reason]."
63
-
64
- ## Output
65
-
66
- ### File Location
67
- `{intent_dir}/resources/{type}--{topic}.md`
68
-
69
- Create the resources/ directory if it doesn't exist.
70
-
71
- ### Naming Convention
72
- - `{type}` — one of: `deep-research`, `competitive-analysis`, `technical-spike`, `reference`, `landscape-survey`
73
- - `{topic}` — kebab-case description of the research subject
74
-
75
- Examples:
76
- - `deep-research--installer-patterns.md`
77
- - `technical-spike--sqlite-vec-performance.md`
78
- - `reference--claude-code-hooks-api.md`
79
- - `landscape-survey--ai-agent-ecosystem.md`
80
-
81
- ### Report Structure
82
-
83
- Default to tabular-first per `PLASTIC.md` (## Tabular-First Reporting, intent 160): tables for findings and comparisons, prose for simple summaries.
84
-
85
- ```markdown
86
- # {Type}: {Topic}
87
-
88
- **Intent:** {id} — {name}
89
- **Depth:** shallow | deep
90
- **Date:** YYYY-MM-DD
91
-
92
- ## Summary
93
- [2-3 sentence executive summary]
94
-
95
- ## Findings
96
-
97
- ### [Finding 1 title]
98
- [Details with inline citations where applicable]
99
-
100
- ### [Finding 2 title]
101
- ...
102
-
103
- ## Sources
104
- - [Source 1 title](url) — what was learned from this source
105
- - [Source 2 title](url) — ...
106
-
107
- ## Relevance to Intent
108
- [How these findings affect the active intent's decisions or design]
109
- ```
110
-
111
- ## After Research
112
-
113
- 1. Commit to store repo:
114
- ```
115
- cd {store_root} && git add . && git commit -m "research: {type} — {topic} (intent {id})"
116
- ```
117
-
118
- 2. Log in intent's `## Insights`:
119
- ```
120
- - Research: {type} — {topic}. Key finding: [one sentence]. See resources/{filename}.
121
- ```
122
-
123
- 3. Research does NOT chain to any other skill. It's a side quest — the user decides what to do with the findings.
@@ -1,22 +0,0 @@
1
- {
2
- "skill_name": "plastic-intent-researching",
3
- "notes": "Intent 66a. Spec for the QMD-first step before researching (reuse prior intents/reports before grep/Read or web search). Runner is intent 76; spec only.",
4
- "evals": [
5
- {
6
- "id": 1,
7
- "scope": "behavior",
8
- "set": "validation",
9
- "prompt": "QMD is present. The user asks the agent to research installer patterns for the active intent.",
10
- "expected_output": "Before scanning the store with grep/Read or searching the web, runs `ruby ~/.plastic/scripts/qmd-sync search \"installer patterns\"` to surface candidate, prior, or related intents and existing research, then opens the authoritative intent file for any hit it reuses. No-op fallback to INDEX.md / file scan when QMD is absent.",
11
- "files": [],
12
- "assertions": [
13
- {
14
- "type": "human",
15
- "check": "qmd-sync search is run before grep/Read and web search; authoritative file opened for any prior report reused",
16
- "observed": "SKILL.md (or agent file) carries the QMD-first step: run qmd-sync search before grep/Read, then open the authoritative file; no-op fallback when QMD is absent",
17
- "result": "pass"
18
- }
19
- ]
20
- }
21
- ]
22
- }
@@ -1,83 +0,0 @@
1
- ---
2
- name: plastic-intent-savepoint
3
- description: Use when verifying or repairing an intent's savepoint ledger, when the user says "save" or "savepoint", or when a PreCompact hook fires. The ledger is written automatically by the gate hook at each lifecycle boundary; this skill only reads, verifies, and rebuilds it.
4
- user-invocable: false
5
- ---
6
-
7
- # Savepoint
8
-
9
- `savepoint.md` is a deterministic, append-only ledger of an intent's cycle steps, one line
10
- per lifecycle milestone, newest at the bottom:
11
-
12
- ```
13
- 2026-06-16T14:02Z What 34--cycle-step-savepoints.md
14
- 2026-06-16T14:20Z Why spec.md created
15
- 2026-06-16T15:10Z How plan.md created
16
- 2026-06-16T15:11Z How checklist.md created
17
- 2026-06-16T16:40Z Exec outcome.md created
18
- ```
19
-
20
- It is **sugar on top of the conventions**, not a source of truth. The gate hook
21
- (`hook-gate-check`) writes each line automatically when a stage file is created, so there is
22
- nothing to save by hand. State is always derivable from files-on-disk; the ledger just lets
23
- a resuming agent read the cycle's succession from one glance (last line = where we are).
24
-
25
- Read `../plastic-conventions/references/lifecycle-and-savepoints.md` for the subagent
26
- report-home contract that this ledger feeds. This path resolves relative to this skill's own
27
- installed directory.
28
-
29
- ## When to Use
30
- - A PreCompact hook fires, or the user says "save" / "savepoint": verify the ledger is current.
31
- - Resuming an intent: read the ledger to learn the cycle's succession quickly.
32
- - The ledger looks stale, empty, or missing: rebuild it from the filesystem.
33
-
34
- ## What this skill does NOT do
35
- - It does not write prose, "in progress", "next step", or "blockers". The old 50%-context
36
- prose savepoint is retired. The semantic trace lives in `## Insights` (append-only,
37
- newest at the bottom); the byte history lives in git.
38
-
39
- ## Workflow
40
-
41
- ### 1. Find Active Intent(s)
42
- Read the active store's `INDEX.md` and extract intents under `## Active`.
43
-
44
- ### 2. For Each Active Intent — verify the ledger
45
- - Read `savepoint.md`. Confirm it exists and is non-empty.
46
- - Confirm the **last line's stage** matches the stage derived from files-on-disk
47
- (`Bridge.derive_stage`). If they disagree, or the file is missing/empty, the ledger has
48
- drifted.
49
- - Run `Bridge.savepoint_phantom_lines(intent_dir)` (pure, disk-only, no bridge or session
50
- resolution; intent 134). It flags a line disk evidence contradicts: a file-landing milestone
51
- whose file is absent or still a sentinel placeholder, a duplicate `(stage, milestone)` pair, or
52
- a state line (`How started` / `Exec started`) whose stage prerequisites are absent. If it
53
- returns any lines:
54
- - **LIVE intent (INDEX `## Active`):** rebuild via step 3 below.
55
- - **INDEX `## Completed`/`## Abandoned` intent:** REPORT the phantom lines and STOP. Do not
56
- rewrite. Completed intents are immutable. A repair is available only under an explicit human
57
- grant, following the 124a precedent: rebuild the file-landing skeleton (step 3), then
58
- re-append the terminal `Done <disposition>` bookend with the disposition read from
59
- `outcome.md`'s `disposition:` frontmatter and the timestamp recovered from the merge commit or
60
- the file's mtime, never invented.
61
-
62
- ### 3. Rebuild on drift
63
- Reconstruct from the filesystem rather than hand-editing:
64
-
65
- ```bash
66
- ruby -r ~/.plastic/scripts/lib/bridge -e \
67
- 'Bridge.rebuild_savepoint("<intent_dir>")'
68
- ```
69
-
70
- This rewrites `savepoint.md` from the milestone files present (timestamps from mtimes),
71
- in stage order. Safe to run anytime: the ledger is derived.
72
-
73
- ### 4. Commit (store only)
74
- If a rebuild changed the ledger, commit it in the store repo:
75
- ```bash
76
- cd <store-root> && git add . && git commit -m "chore: rebuild savepoint ledger — [intent]"
77
- ```
78
- Never push `~/.plastic/`.
79
-
80
- ## References
81
-
82
- - Read `references/context-management.md` for the full save/continue protocol and how the
83
- resume flow consumes the ledger.
@@ -1,32 +0,0 @@
1
- # Context Management (Start-Save-Continue)
2
-
3
- ## Save Point
4
- Triggered by PreCompact hook or manually:
5
- 1. Find active intent(s) from `~/.plastic/INDEX.md`
6
- 2. Update active intent's `checklist.md` (check off completed items)
7
- 3. Update active intent's `savepoint.md` (in-progress, next steps, blockers, discoveries)
8
- 4. Add observations to `## Insights`
9
- 5. Update INDEX.md
10
- 6. Commit: `cd ~/.plastic && git add . && git commit -m "chore: savepoint — [intent name]"`
11
- 7. Notify user to `/clear`
12
-
13
- ## Continue
14
- Triggered by UserPromptSubmit hook when user says "continue". Priority order:
15
-
16
- **1. Active intents first (resume work):**
17
- 1. Read INDEX.md → find active intent(s)
18
- 2. Read active intent's `intent.md` → what and why
19
- 3. Read active intent's `savepoint.md` → where we left off
20
- 4. Read active intent's `checklist.md` → what's next
21
- 5. Announce: intent name, current state, next step, blockers
22
- 6. Resume
23
-
24
- **2. No active intents → offer future intents:**
25
- 1. List all future intents from INDEX.md
26
- 2. Present them as options
27
- 3. When user picks one, move to Active in INDEX.md
28
-
29
- **3. Stale future intents (untouched 3+ days) → triage:**
30
- - **activate** — start working on it now
31
- - **abandon** — mark as abandoned
32
- - **defer to agent** — implement, research, or ideate
@@ -1,151 +0,0 @@
1
- ---
2
- name: plastic-intent-starting
3
- description: >-
4
- Board a session onto an intent: take the lock FIRST, confirm savepoint state, ask auto or
5
- guided ONCE, then resume at the latest delivered station and run the cycle to Done. Use on
6
- `continuing --intent {id}`, when a new intent is registered and the user asks to work it,
7
- or when the user picks an intent to work. Requires the intent in INDEX `## Active`.
8
- user-invocable: true
9
- ---
10
-
11
- # Intent Starting — board a session onto an intent
12
-
13
- `plastic-intent-starting` is the Start procedure. It boards a session onto one intent: take
14
- the lock FIRST, confirm the delivery state, ask **auto or guided ONCE**, board at the latest
15
- delivered station, then run the cycle to Done. The What → Why → How → Exec stations are the
16
- train track; Start boards the train, the ending procedure (~93) exits it.
17
-
18
- ## Precondition + trigger
19
-
20
- Fires when the user picks an intent to work, when an agent is told to continue a SPECIFIC
21
- intent, or on `continuing --intent {id}` (the `continuing` → `starting` router is 106's job;
22
- this skill is invokable standalone now).
23
-
24
- If the intent is **terminal** (Done / Abandoned in INDEX): report only. Take NO lock, run NO
25
- resume, do NOT reopen it. Summarize the outcome and ask what is next. Stop here.
26
-
27
- ## Lock FIRST (the spine)
28
-
29
- The lock is non-negotiable and comes before any mutating work. The ACTION-3 lock-gate
30
- enforces it: without a held lock, mutating writes to this active intent's dir are denied with
31
- "run /plastic-intent-starting to lock and begin".
32
-
33
- Read `../plastic-conventions/references/locks-and-worktrees.md` for delivery isolation: the
34
- single-owner lock, claims, worktrees, solo mode, and the station ledger behind everything below.
35
- This path resolves relative to this skill's own installed directory.
36
-
37
- 1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
38
- (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
39
- brand-new What intent is activated here, then locked.
40
- 2. **Self-heal the lock state first.** Run:
41
- `ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <STORE>/<dir>`
42
- This is the one repair function (same one /plastic-lock exposes): it removes
43
- corrupt or legacy lock state and rebuilds the lock and bridge from disk for
44
- this session. If it reports `held`, another session owns the intent: STOP
45
- and tell the user who holds it. If it reports `stale`, ask the user before
46
- running `plastic-lock reclaim` (takeover is audited).
47
- 3. **Arm the bridge.** Which arm is chosen by the mode answer (below), but the lock itself is
48
- taken first. Reuse the arm one-liner shape from `plastic-auto`:
49
- ```bash
50
- # guided (lock only):
51
- ruby -r ~/.plastic/scripts/lib/bridge -e \
52
- 'codex=ENV["CODEX_THREAD_ID"].to_s.strip; claude=ENV["CLAUDE_CODE_SESSION_ID"].to_s.strip; harness=!codex.empty? ? "codex" : (!claude.empty? ? "claude" : nil); session=!codex.empty? ? codex : (!claude.empty? ? claude : nil); Bridge.arm_guided(session, intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>", harness: harness, agent: "plastic-enforcer", thread: (!codex.empty? ? codex : nil))'
53
- # auto (lock + auto), then hand to plastic-auto:
54
- ruby -r ~/.plastic/scripts/lib/bridge -e \
55
- 'codex=ENV["CODEX_THREAD_ID"].to_s.strip; claude=ENV["CLAUDE_CODE_SESSION_ID"].to_s.strip; harness=!codex.empty? ? "codex" : (!claude.empty? ? "claude" : nil); session=!codex.empty? ? codex : (!claude.empty? ? claude : nil); Bridge.arm_auto(session, intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>", harness: harness, agent: "plastic-enforcer", thread: (!codex.empty? ? codex : nil))'
56
- ```
57
- Replace `<ID>`, `<STORE>` (`~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
58
- `<dir>` (the `ID--slug` directory), and `<name>`.
59
- 4. **Dispatch What-stage discovery (under the lock).** Right after arming, when the intent
60
- was just activated in step 1 (on a resume that already has
61
- `resources/discovery--<slug>.md`, skip: discovery runs once per intent, at activation
62
- only), dispatch the `plastic-intent-discovery` agent (see the `plastic-intent-discovering`
63
- skill), now that this session owns the lock, deposit authorized as the owner session. Resolve its
64
- model explicitly and pass it at dispatch time (belt-and-braces): `read-config
65
- agents.models.plastic-intent-discovery --project <repo>`. The agent runs QMD discovery
66
- over the intent's `chain`/`sources` and deposits findings to
67
- `resources/discovery--<slug>.md` only; it never writes the intent file, so the
68
- lock-owner-only rule is untouched. This is advisory context for Why, not a gate: if
69
- discovery yields nothing, proceed to Why normally.
70
-
71
- **Skip the dispatch only at Tier S, when there is nothing to discover.** The skip fires
72
- only when BOTH hold: a size of S is already on record for this intent, and the activating
73
- intent's `chain` and `sources` frontmatter fields are both empty. On record means a
74
- stamped `Tier: S` line at the top of `spec.md`. Sizing happens at Why, which is after this
75
- step, so a first activation usually has no size yet: run the pass. The skip mainly earns
76
- its keep on a re-activated intent that is already sized S. Never guess a size here to
77
- unlock the skip. When both conditions hold, write the single line
78
- `no chain/sources, discovery skipped` to `resources/discovery--<slug>.md` in its place,
79
- then go to Why.
80
-
81
- **Session id resolution (verbatim from `plastic-auto`).** The first argument is the session
82
- id the bridge is keyed by: pass the hook stdin `session_id` when you have it; in the executable
83
- snippets, a nonblank `CODEX_THREAD_ID` identifies Codex, otherwise a nonblank
84
- `CLAUDE_CODE_SESSION_ID` identifies Claude, otherwise identity remains unknown. Never infer a
85
- harness from an absent variable. Both arms call `resolve_session`, which
86
- picks the first non-empty of: the explicit id you pass → `CLAUDE_CODE_SESSION_ID` → a
87
- deterministic derived key (a hash of the store and intent id). It never returns nil, so the
88
- lock is taken even when every session env var is empty; arming prints a one-line stderr
89
- notice when it falls through to the derived key.
90
-
91
- **What the lock IS.** Ownership is session-keyed and lease-based: arming writes a durable
92
- `delivery.lock` file in the intent dir naming this session as owner, and the owner's hooks
93
- refresh the file mtime on tool activity (the lease heartbeat). The /tmp bridge is only a
94
- cache of that file; on any disagreement the lock file wins, so a wiped /tmp never strands
95
- the owner. Idempotent re-arm: arming again with the same owner just refreshes the lock; it
96
- is not an error to re-board an intent this session already owns. A failed arm raises with
97
- a message naming the resolving `plastic-lock` verb (`status`, `reclaim`, or `fix`): follow
98
- that message, never delete a lock file by hand.
99
-
100
- ## Confirm delivery state
101
-
102
- Read `savepoint.md` and classify from the **last line** alone, then verify ONLY that line's
103
- artifact is real (sentinel-aware via `Bridge.stage_file_present?`). On drift (the last line
104
- disagrees with files on disk), rebuild the ledger from disk and note the correction. Do not
105
- inline the rebuild; the `plastic-intent-savepoint` skill owns it:
106
- ```bash
107
- ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
108
- ```
109
-
110
- ## Report + ask "auto or guided?" ONCE
111
-
112
- Report: the intent, the station it lands at (the matrix below), what is delivered, the next
113
- step. Then ask the user **"auto or guided?"** — exactly ONCE, whatever station it lands at.
114
- Never re-ask at a later station.
115
-
116
- - **guided** → `arm_guided` (lock only); continue step by step with the user through the
117
- station's work below.
118
- - **auto** → `arm_auto` (lock + auto), then hand off to `plastic-auto`. The auto branch's
119
- only remaining job is the handoff; `plastic-auto` runs the cycle from here.
120
-
121
- Read `../plastic-conventions/references/tiers-and-dispatch.md` for tier sizing and the
122
- stage-to-agent dispatch rules behind the auto branch above.
123
-
124
- ## Board at the latest delivered station
125
-
126
- The station is derived from `savepoint.md` last line + real artifacts on disk. See
127
- `references/boarding-matrix.md` for the full table (last line → latest delivered → boards at →
128
- continue with) and the per-station notes. Summary of what "continue" means per station:
129
-
130
- Read `../plastic-conventions/references/gates-and-enforcement.md` for the transition-gate
131
- mechanics, the audited escape, and gate logging that govern moving between the stations below.
132
-
133
- - **What** → do what What requires (106-expanded), then brainstorm → `spec.md`.
134
- - **Why** → continue brainstorming → `spec.md`.
135
- - **How** → continue `plan.md` + `actions/` + `checklist.md`.
136
- - **Exec** → verify what has been delivered, then continue (or restart) the delivery /
137
- research; tick the checklist.
138
- - **ready to complete** (`Exec outcome.md created`) → exit at Done.
139
- - **Done** → report only, ask what is next, never reopen.
140
-
141
- ## Disarm / release on done
142
-
143
- When delivery finishes, disarm and release per the `plastic-auto` disarm/release prose (do
144
- not duplicate it here). The guided branch releases the lock via `disarm_auto`, which is
145
- mode-agnostic (it sets `auto = false` and calls `Worktree.release`), so it releases a guided
146
- lock too. When the work ships through a release, the release path merges the branch before the
147
- worktree is removed; the plain disarm remove is only for the no-release case.
148
-
149
- ## References
150
-
151
- - `references/boarding-matrix.md` — the full boarding table and per-station behaviour.
@@ -1,117 +0,0 @@
1
- {
2
- "skill_name": "plastic-intent-starting",
3
- "notes": "Intent 96. Scopes: description triggering (1-5) and behavior (6-10: lock-first spine, ask-mode-once, terminal report-only, mode->arm mapping, boarding matrix). The lock-first and gate behaviors are also proven by Ruby tests (test/bridge_guided_test.rb, test/lock_gate_test.rb, test/lock_gate_hook_test.rb).",
4
- "evals": [
5
- {
6
- "id": 1,
7
- "scope": "triggering",
8
- "set": "train",
9
- "prompt": "start work on intent 96",
10
- "expected_output": "Activates plastic-intent-starting (board a session onto the named intent).",
11
- "files": [],
12
- "assertions": [
13
- { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
14
- ]
15
- },
16
- {
17
- "id": 2,
18
- "scope": "triggering",
19
- "set": "train",
20
- "prompt": "continuing --intent 96",
21
- "expected_output": "Activates plastic-intent-starting (the --intent form boards a specific intent).",
22
- "files": [],
23
- "assertions": [
24
- { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
25
- ]
26
- },
27
- {
28
- "id": 3,
29
- "scope": "triggering",
30
- "set": "validation",
31
- "prompt": "work this intent",
32
- "expected_output": "Activates plastic-intent-starting when an intent is in context to be worked.",
33
- "files": [],
34
- "assertions": [
35
- { "type": "code", "check": "router CHOICE == plastic-intent-starting", "result": "expect-pass" }
36
- ]
37
- },
38
- {
39
- "id": 4,
40
- "scope": "triggering",
41
- "set": "validation",
42
- "prompt": "continue",
43
- "expected_output": "Does NOT activate plastic-intent-starting; bare 'continue' is plastic-continuing (the router, no specific intent named).",
44
- "files": [],
45
- "assertions": [
46
- { "type": "code", "check": "router CHOICE != plastic-intent-starting", "result": "expect-pass" }
47
- ]
48
- },
49
- {
50
- "id": 5,
51
- "scope": "triggering",
52
- "set": "validation",
53
- "prompt": "create a new intent for the uploader retry policy",
54
- "expected_output": "Does NOT activate plastic-intent-starting; activates plastic-intent-creating.",
55
- "files": [],
56
- "assertions": [
57
- { "type": "code", "check": "router CHOICE != plastic-intent-starting", "result": "expect-pass" }
58
- ]
59
- },
60
- {
61
- "id": 6,
62
- "scope": "behavior",
63
- "set": "train",
64
- "prompt": "Active intent X exists at the Why station. Start work on it (guided).",
65
- "expected_output": "Takes the lock FIRST via Bridge.arm_guided (auto stays false) before any mutating work, confirms savepoint, then boards at Why and continues brainstorming toward spec.md.",
66
- "files": [],
67
- "assertions": [
68
- { "type": "human", "check": "lock acquired before any mutating write; SKILL.md 'Lock FIRST' section precedes station work", "result": "expect-pass" },
69
- { "type": "code", "check": "Bridge.arm_guided stamps the lock with auto=false (test/bridge_guided_test.rb green); lock-gate denies a no-lock write to the active intent dir (test/lock_gate_hook_test.rb green)", "result": "pass" }
70
- ]
71
- },
72
- {
73
- "id": 7,
74
- "scope": "behavior",
75
- "set": "train",
76
- "prompt": "Start work on an active intent without saying auto or guided.",
77
- "expected_output": "Asks 'auto or guided?' exactly once after reporting the station; never re-asks at later stations.",
78
- "files": [],
79
- "assertions": [
80
- { "type": "human", "check": "SKILL.md asks the mode exactly once and states 'never re-asked at a later station'", "result": "expect-pass" }
81
- ]
82
- },
83
- {
84
- "id": 8,
85
- "scope": "behavior",
86
- "set": "train",
87
- "prompt": "Start work on an intent that is Done in INDEX.",
88
- "expected_output": "Reports only: no lock, no resume, no reopen. Summarizes the outcome and asks what is next.",
89
- "files": [],
90
- "assertions": [
91
- { "type": "human", "check": "terminal intent -> report only, no arm call", "result": "expect-pass" }
92
- ]
93
- },
94
- {
95
- "id": 9,
96
- "scope": "behavior",
97
- "set": "validation",
98
- "prompt": "Start work and choose auto.",
99
- "expected_output": "guided -> Bridge.arm_guided; auto -> Bridge.arm_auto then hand off to plastic-auto (auto branch's only remaining job is the handoff).",
100
- "files": [],
101
- "assertions": [
102
- { "type": "human", "check": "SKILL.md maps guided->arm_guided and auto->arm_auto+handoff to plastic-auto", "result": "expect-pass" }
103
- ]
104
- },
105
- {
106
- "id": 10,
107
- "scope": "behavior",
108
- "set": "validation",
109
- "prompt": "Start an intent whose savepoint last line is 'How checklist.md created'.",
110
- "expected_output": "Boards at Exec (verify plan + checklist real), per references/boarding-matrix.md, and continues delivery/ticks the checklist.",
111
- "files": [],
112
- "assertions": [
113
- { "type": "human", "check": "boarding matrix lands 'How checklist.md created' / 'Exec started' at Exec", "result": "expect-pass" }
114
- ]
115
- }
116
- ]
117
- }