@zalom/plastic 1.0.0-alpha.3 → 1.0.0-alpha.31

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 (87) hide show
  1. package/PLASTIC.md +134 -469
  2. package/README.md +95 -58
  3. package/agents/future-intent-researcher.md +1 -1
  4. package/agents/intent-curator.md +1 -1
  5. package/bin/plastic.js +57 -0
  6. package/bin/test +28 -0
  7. package/deprecations.yml +1 -10
  8. package/hooks/auto-arm +5 -0
  9. package/hooks/bash-gate +3 -0
  10. package/hooks/check-update +12 -8
  11. package/hooks/code-gate +12 -0
  12. package/hooks/gate-check +3 -1
  13. package/hooks/hooks.json +25 -4
  14. package/hooks/statusline +50 -10
  15. package/package.json +2 -2
  16. package/scripts/dashboard.rb +680 -0
  17. package/scripts/doctor.rb +1227 -0
  18. package/scripts/hook-auto-arm +51 -0
  19. package/scripts/hook-bash-gate +41 -0
  20. package/scripts/hook-code-gate +27 -0
  21. package/scripts/hook-continue +15 -114
  22. package/scripts/hook-gate-check +30 -34
  23. package/scripts/hook-session-start +121 -31
  24. package/scripts/install.rb +91 -487
  25. package/scripts/lib/boot_banner.rb +28 -0
  26. package/scripts/lib/bridge.rb +358 -10
  27. package/scripts/lib/installer_core.rb +747 -0
  28. package/scripts/lib/intent_validator.rb +90 -0
  29. package/scripts/lib/qmd_sync.rb +159 -0
  30. package/scripts/lib/store_provisioning.rb +100 -0
  31. package/scripts/migrate-to-global +1 -1
  32. package/scripts/provision-project-store +53 -0
  33. package/scripts/qmd-sync +92 -0
  34. package/scripts/select-update-target +93 -0
  35. package/scripts/uninstall.rb +53 -0
  36. package/scripts/update.rb +164 -0
  37. package/scripts/validate-intent +54 -0
  38. package/scripts/versions.rb +141 -0
  39. package/skills/_active-intent-gate.md +26 -0
  40. package/skills/add-project-store/SKILL.md +54 -0
  41. package/skills/auto/SKILL.md +69 -9
  42. package/skills/auto/evals/evals.json +92 -0
  43. package/skills/auto/references/agent-architecture.md +60 -0
  44. package/skills/brainstorming/SKILL.md +143 -0
  45. package/skills/brainstorming-grill-me/SKILL.md +5 -5
  46. package/skills/continuing/SKILL.md +92 -82
  47. package/skills/continuing/evals/evals.json +136 -0
  48. package/skills/continuing/references/context-management.md +32 -0
  49. package/skills/creating-intent/SKILL.md +38 -9
  50. package/skills/creating-intent/references/lifecycle.md +74 -0
  51. package/skills/creating-intent/references/wikilinks.md +8 -0
  52. package/skills/creating-project/SKILL.md +40 -8
  53. package/skills/creating-project/references/hubs-projects.md +55 -0
  54. package/skills/dashboard/SKILL.md +121 -0
  55. package/skills/dashboard/templates/dashboard-global.md +31 -0
  56. package/skills/dashboard/templates/dashboard-project.md +40 -0
  57. package/skills/doctor/SKILL.md +159 -0
  58. package/skills/doctor/references/gates-stuck-detection.md +38 -0
  59. package/skills/doctor/report.md +100 -0
  60. package/skills/evaluating-skills/SKILL.md +140 -0
  61. package/skills/evaluating-skills/assets/eval-template.json +12 -0
  62. package/skills/evaluating-skills/evals/evals.json +75 -0
  63. package/skills/evaluating-skills/references/convention-checks.md +76 -0
  64. package/skills/evaluating-skills/references/eval-methodology.md +154 -0
  65. package/skills/executing-plan/SKILL.md +5 -3
  66. package/skills/install/SKILL.md +69 -8
  67. package/skills/intent-curator/SKILL.md +3 -3
  68. package/skills/linking-intents/SKILL.md +5 -1
  69. package/skills/linking-intents/references/zettelkasten.md +33 -0
  70. package/skills/managing-index/SKILL.md +5 -1
  71. package/skills/releasing/SKILL.md +119 -18
  72. package/skills/releasing/references/deprecations.md +60 -0
  73. package/skills/research/SKILL.md +114 -0
  74. package/skills/savepoint/SKILL.md +46 -37
  75. package/skills/savepoint/references/context-management.md +32 -0
  76. package/skills/uninstall/SKILL.md +39 -28
  77. package/skills/update/SKILL.md +41 -36
  78. package/skills/versions/SKILL.md +65 -0
  79. package/skills/writing-instructions/SKILL.md +159 -0
  80. package/skills/writing-instructions/references/agentskills-spec.md +135 -0
  81. package/skills/writing-plans/SKILL.md +183 -0
  82. package/templates/agents.md +16 -0
  83. package/templates/outcome.md +13 -0
  84. package/templates/project.yml +5 -0
  85. package/templates/savepoint.md +14 -13
  86. package/templates/spec.md +25 -0
  87. package/bin/install.js +0 -29
@@ -0,0 +1,60 @@
1
+ # Agent Architecture
2
+
3
+ ## Main Orchestrator
4
+
5
+ The Main Orchestrator manages the global store (Main Knowledge Base). It:
6
+ - Recognizes, creates, updates, and groups intents
7
+ - Spawns Project Orchestrators for registered projects
8
+ - Receives contributions back from Project Orchestrators
9
+ - Is the only agent that runs in a loop (continuous Build→Observe→Repeat)
10
+
11
+ ## Project Orchestrators
12
+
13
+ Project Orchestrators manage project stores (Project Knowledge Bases). They:
14
+ - Care about intents and execution within their project
15
+ - Spawn teams to develop and execute intents
16
+ - Contribute back to the Main Orchestrator when new intents are born
17
+ that could enrich the Main Knowledge Base
18
+
19
+ Rules:
20
+ - 1 Main Orchestrator : 1 Global Store (`~/.plastic/`)
21
+ - 1 Main Orchestrator : N Project Orchestrators
22
+ - 1 Project Orchestrator : 1 Project Store
23
+ - 1 Agent : 1 Intent (exclusive assignment)
24
+ - 1 Agent : N Sub-agents (for parallel Actions within an intent)
25
+
26
+ ## Two Modes
27
+
28
+ - **Human-driven:** Human chats with Main Orchestrator, creates intents,
29
+ brainstorms, then Main Orchestrator dispatches Project Orchestrators and
30
+ Agents for execution.
31
+ - **Autonomous:** Human gives Main Orchestrator a starting intent with defined
32
+ outcomes. Main Orchestrator runs the full cycle — Agents do the lifecycle
33
+ (What→Why→How→Exec), Main Orchestrator reviews Insights, spawns next intents,
34
+ dispatches again.
35
+
36
+ ## Autonomous Delivery
37
+
38
+ Human owns What and Why for human-initiated intents. Agent assists (research,
39
+ exploration) but human drives until handoff. When Why is complete — or human
40
+ triggers `plastic-auto` — the agent takes over How and Exec autonomously.
41
+
42
+ - **Safe-by-default:** Agent always prefers non-destructive routes (rename vs
43
+ delete, additive migrations, backups before changes). Destructive actions on
44
+ existing projects require human approval unless `--skip-permissions` is set.
45
+ - **One agent per intent.** Agent follows the full W→W→H→E lifecycle.
46
+ - **Notification only on:** finish or hard stop (blocked on destructive action,
47
+ unresolvable error). No progress reports — `## Insights` tracks everything.
48
+ - **Greenfield autonomy:** During initial project creation, all decisions are
49
+ non-destructive (nothing to destroy). Agent has full autonomy for greenfield choices.
50
+ - **Autonomous decisions** are logged in `## Insights` with `(autonomous)` marker.
51
+
52
+ ## Coordinator Loop
53
+
54
+ When "work on Project X":
55
+ 1. Read `projects.yml` → find project path
56
+ 2. Load global config (defaults)
57
+ 3. Load project config (overrides)
58
+ 4. Load global INDEX.md → find hub intents tagged `project-<name>`
59
+ 5. Load project INDEX.md → tactical intents
60
+ 6. Coordinator has full picture, dispatches Agent teams
@@ -0,0 +1,143 @@
1
+ ---
2
+ name: plastic-brainstorming
3
+ description: "Explore intent requirements and design before implementation. Produces spec.md in the active intent directory."
4
+ ---
5
+
6
+ # Brainstorming Ideas Into Designs
7
+
8
+ Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
9
+
10
+ Announce: "I'm using the brainstorming skill to explore the design for intent {id} — {name}."
11
+
12
+ Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
13
+
14
+ <HARD-GATE>
15
+ Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
16
+ </HARD-GATE>
17
+
18
+ ## Active Intent Gate
19
+
20
+ Before proceeding, resolve the active intent:
21
+
22
+ 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/`.
23
+ 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-creating-intent"
24
+ 3. **Resolve intent directory:** `{store}/store/{id}--{slug}/`
25
+
26
+ All artifacts go to the intent directory. Never write to external paths.
27
+
28
+ ## Anti-Pattern: "This Is Too Simple To Need A Design"
29
+
30
+ Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
31
+
32
+ ## Checklist
33
+
34
+ You MUST create a task for each of these items and complete them in order:
35
+
36
+ 1. **Explore project context** — check files, docs, recent commits, read active intent
37
+ 2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
38
+ 3. **Propose 2-3 approaches** — with trade-offs and your recommendation
39
+ 4. **Present design** — in sections scaled to their complexity, get user approval after each section
40
+ 5. **Write spec** — save to `{intent_dir}/spec.md` and commit to store repo
41
+ 6. **Spec self-review** — placeholder scan, consistency, scope, ambiguity
42
+ 7. **User reviews written spec** — ask user to review before proceeding
43
+ 8. **Transition to planning** — invoke `plastic-writing-plans`
44
+
45
+ ## Process Flow
46
+
47
+ ```dot
48
+ digraph brainstorming {
49
+ "Explore project context" [shape=box];
50
+ "Ask clarifying questions" [shape=box];
51
+ "Propose 2-3 approaches" [shape=box];
52
+ "Present design sections" [shape=box];
53
+ "User approves design?" [shape=diamond];
54
+ "Write spec" [shape=box];
55
+ "Spec self-review\n(fix inline)" [shape=box];
56
+ "User reviews spec?" [shape=diamond];
57
+ "Invoke plastic-writing-plans" [shape=doublecircle];
58
+
59
+ "Explore project context" -> "Ask clarifying questions";
60
+ "Ask clarifying questions" -> "Propose 2-3 approaches";
61
+ "Propose 2-3 approaches" -> "Present design sections";
62
+ "Present design sections" -> "User approves design?";
63
+ "User approves design?" -> "Present design sections" [label="no, revise"];
64
+ "User approves design?" -> "Write spec" [label="yes"];
65
+ "Write spec" -> "Spec self-review\n(fix inline)";
66
+ "Spec self-review\n(fix inline)" -> "User reviews spec?";
67
+ "User reviews spec?" -> "Write spec" [label="changes requested"];
68
+ "User reviews spec?" -> "Invoke plastic-writing-plans" [label="approved"];
69
+ }
70
+ ```
71
+
72
+ **The terminal state is invoking `plastic-writing-plans`.** Do NOT invoke any other implementation skill. The ONLY skill you invoke after brainstorming is `plastic-writing-plans`.
73
+
74
+ ## The Process
75
+
76
+ **Understanding the idea:**
77
+ - Check out the current project state first (files, docs, recent commits)
78
+ - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
79
+ - If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
80
+ - For appropriately-scoped projects, ask questions one at a time to refine the idea
81
+ - Prefer multiple choice questions when possible, but open-ended is fine too
82
+ - Only one question per message - if a topic needs more exploration, break it into multiple questions
83
+ - Focus on understanding: purpose, constraints, success criteria
84
+
85
+ **Exploring approaches:**
86
+ - Propose 2-3 different approaches with trade-offs
87
+ - Present options conversationally with your recommendation and reasoning
88
+ - Lead with your recommended option and explain why
89
+
90
+ **Presenting the design:**
91
+ - Once you believe you understand what you're building, present the design
92
+ - Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
93
+ - Ask after each section whether it looks right so far
94
+ - Cover: architecture, components, data flow, error handling, testing
95
+ - Be ready to go back and clarify if something doesn't make sense
96
+
97
+ **Design for isolation and clarity:**
98
+ - Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
99
+ - For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
100
+ - Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
101
+ - Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
102
+
103
+ **Working in existing codebases:**
104
+ - Explore the current structure before proposing changes. Follow existing patterns.
105
+ - Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
106
+ - Don't propose unrelated refactoring. Stay focused on what serves the current goal.
107
+
108
+ ## After the Design
109
+ **Documentation:**
110
+ - Write the validated design (spec) to `{intent_dir}/spec.md` using the `${CLAUDE_PLUGIN_ROOT}/templates/spec.md` form
111
+ - Use elements-of-style:writing-clearly-and-concisely skill if available
112
+ - Commit to the store repo:
113
+ ```
114
+ cd {store_root} && git add . && git commit -m "docs: spec for intent {id} — {name}"
115
+ ```
116
+
117
+ **Spec Self-Review:**
118
+ After writing the spec document, look at it with fresh eyes:
119
+ 1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
120
+ 2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
121
+ 3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
122
+ 4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
123
+
124
+ Fix any issues inline. No need to re-review — just fix and move on.
125
+
126
+ **User Review Gate:**
127
+ After the spec review loop passes, ask the user to review the written spec before proceeding:
128
+ > "Spec written and committed to `{intent_dir}/spec.md`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
129
+
130
+ Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
131
+
132
+ **Implementation:**
133
+ - Invoke `plastic-writing-plans` to create the implementation plan
134
+ - Do NOT invoke any other skill. `plastic-writing-plans` is the next step.
135
+
136
+ ## Key Principles
137
+
138
+ - **One question at a time** - Don't overwhelm with multiple questions
139
+ - **Multiple choice preferred** - Easier to answer than open-ended when possible
140
+ - **YAGNI ruthlessly** - Remove unnecessary features from all designs
141
+ - **Explore alternatives** - Always propose 2-3 approaches before settling
142
+ - **Incremental validation** - Present design, get approval before moving on
143
+ - **Be flexible** - Go back and clarify when something doesn't make sense
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: plastic:brainstorming-grill-me
2
+ name: plastic-brainstorming-grill-me
3
3
  description: >-
4
4
  Deep brainstorming that interviews the user relentlessly about a plan or design until reaching shared understanding.
5
5
  Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
@@ -83,18 +83,18 @@ If ALL items pass, offer autonomous delivery:
83
83
  >
84
84
  > Want to grill more, or should I go autonomous?"
85
85
 
86
- - If human says go → invoke `plastic:auto`
86
+ - If human says go → invoke `plastic-auto`
87
87
  - If human says grill more → continue grilling (reset to step 2)
88
88
  - If human says neither (wants to drive manually) → proceed as before (offer planning)
89
89
 
90
90
  This offer replaces the final question in Close Out ("Ready to plan implementation, or do you want another pass?"). The new options are:
91
- 1. Go autonomous (`plastic:auto`)
91
+ 1. Go autonomous (`plastic-auto`)
92
92
  2. Grill more (continue interrogation)
93
93
  3. Plan manually (invoke `superpowers:writing-plans` or proceed with human-driven planning)
94
94
 
95
95
  ## Relationship to superpowers:brainstorming
96
96
 
97
- | | superpowers:brainstorming | plastic:brainstorming-grill-me |
97
+ | | superpowers:brainstorming | plastic-brainstorming-grill-me |
98
98
  |---|---|---|
99
99
  | Speed | Quick (5-10 min) | Thorough (20-45 min) |
100
100
  | Depth | Surface-level exploration | Exhaustive decision tree |
@@ -102,4 +102,4 @@ This offer replaces the final question in Close Out ("Ready to plan implementati
102
102
  | Output | Initial spec | Battle-tested spec with all branches resolved |
103
103
  | Style | Collaborative, exploratory | Interrogative, relentless |
104
104
 
105
- Use `superpowers:brainstorming` to generate ideas. Use `plastic:brainstorming-grill-me` to pressure-test them.
105
+ Use `superpowers:brainstorming` to generate ideas. Use `plastic-brainstorming-grill-me` to pressure-test them.
@@ -1,104 +1,114 @@
1
1
  ---
2
- name: plastic:continuing
3
- description: Use when the user says "continue" after a /clear, or when resuming work in a new session. Reads intent state from global store (~/.plastic/) or local store, offers active intents first, then future intents, and surfaces stale intents for triage.
2
+ name: plastic-continuing
3
+ description: Use when the user says "continue", "resume", or "pick up where we left off", or when starting a new session. Continues work with the latest project context: lands on the right dashboard, then presents choices. Boot (health check, core context, version, statusline) is owned by the SessionStart hook, not this skill. Does not drive work autonomously (that is plastic-auto).
4
4
  ---
5
5
 
6
6
  # Continuing
7
7
 
8
+ `plastic-continuing` continues work. It presents the latest state via the dashboard and offers
9
+ choices, then stops. It does NOT execute work autonomously (that is `plastic-auto`) and does
10
+ NOT render the dashboard itself (it only invokes it).
11
+
12
+ **Boot is not this skill's job.** The `hook-session-start` hook already runs by construction on
13
+ every session start: it runs the core health check (`doctor --core`), primes `PLASTIC.md` +
14
+ store/project state, and prints the `Plastic Core loaded — v{version}` banner. The
15
+ `plastic-statusline` hook sets the statusline. So by the time this skill runs, core is loaded
16
+ and healthy (or the banner already warned otherwise). This skill picks up from there and
17
+ continues work. This is the seam future continue-flags build on (see [[39]]).
18
+
8
19
  ## When to Use
9
20
  - UserPromptSubmit hook detects "continue" (automatic)
10
21
  - User says "continue", "resume", or "pick up where we left off"
11
- - Starting a new session with existing active intents
22
+ - Starting a new session and you want to resume work with the latest context
12
23
 
13
24
  ## Determine Store
14
25
 
15
- 1. Check `~/.plastic/INDEX.md` → global mode
16
- 2.
17
- 3. If neither exists → announce "No Plastic store found. Run /plastic:install."
18
-
19
- ## Workflow
20
-
21
- ### 1. Read INDEX.md
22
- Read the INDEX.md from the active store. Extract intents under `## Active` and `## Future`.
23
-
24
- ### 2. Detect Current Project (global mode only)
25
- Read `~/.plastic/projects.yml`, match CWD against registered project paths. If in a project:
26
- - Load the governing intent (from `parent` in projects.yml)
27
- - Load tactical intents from `~/.plastic/projects/{slug}/store/`
28
-
29
- ### 3. If Active Intents Exist → Resume
30
-
31
- For each active intent in the store:
32
-
33
- **a. Read `{ID}--{slug}.md`:**
34
- - What we're doing (`## Intent`)
35
- - Why (`## Context`)
36
- - What insights have emerged (`## Insights`)
37
-
38
- **b. Read savepoint.md** (if exists):
39
- - What was in progress, what's next, blockers
40
-
41
- **c. Read checklist.md** (if exists):
42
- - What's completed, what's next
43
-
44
- **d. Announce:**
45
- ```
46
- Resuming intent [ID] — [name]
47
- Store: [global | project:<slug> | local]
48
- Status: active
49
- Last session: [date from savepoint]
50
- In progress: [from savepoint]
51
- Next step: [from checklist or savepoint]
52
- Blockers: [from savepoint, or "none"]
53
- ```
54
-
55
- **e. Resume** — proceed with the next step.
56
-
57
- ### 3b. Detect Autonomous Resume
58
-
59
- When resuming an active intent, check `## Insights` for entries containing `(autonomous)`.
60
-
61
- If found — this intent was being delivered autonomously:
62
-
63
- **Announce:**
64
- ```
65
- Resuming autonomous delivery of intent [ID] — [name]
66
- Store: [global | project:<slug> | local]
67
- Last autonomous action: [last (autonomous) insight entry]
68
- Next step: [from checklist or savepoint]
69
- ```
70
-
71
- **Then:** Continue autonomous execution by invoking `plastic:auto`. The auto skill will pick up from the current lifecycle stage (it reads filesystem state to determine where to resume).
72
-
73
- If NOT found — resume normally as described in step 3.
74
-
75
- ### 4. If No Active Intents → Offer Future Intents
76
-
77
- Present future intents as options. When user picks one, move to Active in INDEX.md. Auto-commit.
78
-
79
- ### 5. Surface Stale Future Intents
80
-
81
- If any future intent has `created` date older than the configured `stale_threshold_days` (default 3):
26
+ 1. **Global store** — `~/.plastic/INDEX.md` exists → global mode.
27
+ 2. **Local store** — a project store under `~/.plastic/projects/{slug}/` whose registered
28
+ path (in `~/.plastic/projects.yml`) matches the current working directory → project mode.
29
+ The SessionStart hook already detects this; here you only need the slug to scope the
30
+ dashboard.
31
+ 3. If neither exists → announce "No Plastic store found. Run /plastic-install."
32
+
33
+ ## Continue (present the dashboard)
34
+
35
+ Land on the Markdown board via the `plastic-dashboard` skill. Rendering belongs there, not
36
+ here — run the data payload and fill + present the matching template:
37
+ - Project loaded → `ruby ~/.plastic/scripts/dashboard.rb project <slug> --data`
38
+ - Otherwise → `ruby ~/.plastic/scripts/dashboard.rb continue --data`
39
+
40
+ Fill the matching template from this skill's `templates/` and **present the filled Markdown
41
+ in your reply** (every time). See `plastic-dashboard` for the fill rules and entry flow.
42
+
43
+ The board load runs the scoped store check on every load (`doctor --store <scope>`): the
44
+ global board runs `--store global` and a project board runs `--store <slug>`. The result
45
+ arrives in the payload as `store_health`; surface it as a one-line store-health note. It is
46
+ non-fatal (a warn or fail is shown as data, it does not block continuing).
47
+
48
+ ### Then stop
49
+ Present "here is the state, what next?" and wait. Offer active intents first, then future
50
+ intents. Do not start executing work. The branches below are the only follow-ups:
51
+ - User/agent names a specific intent to continue → **Conditional ledger-resume** (below).
52
+ - User says "auto" / an agent is instructed to deliver → hand to `plastic-auto`.
53
+
54
+ ## Conditional Ledger-Resume
55
+
56
+ Fires ONLY when the user explicitly asks to continue a SPECIFIC intent, or an agent is
57
+ instructed to continue one. It is not part of every boot. For that intent's directory:
58
+
59
+ 1. **Read `savepoint.md`.** It is a deterministic, append-only stage ledger (one line per
60
+ milestone, newest at the bottom): `{utc-iso8601} {Stage} {milestone}`. The **last line =
61
+ current stage**.
62
+ 2. **Verify the stage file.** Confirm the file the ledger names exists and is non-empty
63
+ (ledger `How plan.md created` → `plan.md` must be present and non-empty).
64
+ 3. **Drift handling.** If the ledger's last line disagrees with files-on-disk, rebuild the
65
+ ledger from filesystem state and note the correction:
66
+ ```bash
67
+ ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.rebuild_savepoint("<intent_dir>")'
68
+ ```
69
+ 4. **Derive the next step:**
70
+ - First unchecked item in `checklist.md` if it exists, else
71
+ - "advance to the next lifecycle stage" (e.g. ledger shows Why/spec.md → next is How).
72
+ - The newest `## Insights` entry supplies human-readable context (Insights are
73
+ append-only, newest at the bottom).
74
+ 5. **Announce and stop:**
75
+ ```
76
+ Resuming intent [ID] — [name]
77
+ Store: [global | project:<slug> | local]
78
+ Stage: [from ledger last line]
79
+ Next step: [first unchecked checklist item | advance to <stage>]
80
+ Context: [newest ## Insights entry]
81
+ Drift: [none | ledger rebuilt from filesystem]
82
+ ```
83
+ Then proceed with the next step. Autonomy is `plastic-auto`'s job — if the intent's
84
+ `## Insights` contains `(autonomous)` entries, it was being delivered autonomously; hand
85
+ to `plastic-auto` to continue from the current stage.
86
+
87
+ ## Priority Order
88
+
89
+ 1. **Active intents first** — surface work in progress.
90
+ 2. **Project context** — if in a registered project, show governing + tactical intents.
91
+ 3. **Stale future intents** — surface for triage (see below).
92
+ 4. **Fresh future intents** — offer as next work.
93
+
94
+ ## Stale Future Intents
95
+
96
+ If a future intent's `created` date is older than the configured `stale_threshold_days`
97
+ (default 3), surface it for triage without taking action:
82
98
 
83
99
  ```
84
100
  Stale future intents (no action taken):
85
101
 
86
102
  - [ID — name] (X days old)
87
- Options:
88
103
  a) Activate — start working on it now
89
104
  b) Abandon — mark as abandoned
90
- c) Defer to agent:
91
- - implement: agent builds it
92
- - research: agent investigates feasibility
93
- - ideate: agent explores the problem space
94
- d) Auto — go fully autonomous (invokes plastic:auto — agent delivers the intent end-to-end)
105
+ c) Defer to agent: implement | research | ideate
106
+ d) Auto — go fully autonomous (invokes plastic-auto)
95
107
  ```
96
108
 
97
- Auto-commit all triage changes.
109
+ When the user activates a future intent, move it to `## Active` in INDEX.md and auto-commit.
98
110
 
99
- ### 6. Priority Order
111
+ ## References
100
112
 
101
- 1. **Active intents first** — resume work in progress
102
- 2. **Project context** — if in a registered project, show governing intent + tactical intents
103
- 3. **Stale future intents** — surface for triage
104
- 4. **Fresh future intents** — offer as next work
113
+ - Read `references/context-management.md` for the full save/continue protocol and for
114
+ debugging the resume flow.
@@ -0,0 +1,136 @@
1
+ {
2
+ "skill_name": "plastic-continuing",
3
+ "notes": "Intent 36, updated for 36a (boot moved into hook-session-start; the skill is now work-continuation only). Scopes: description triggering (1-8) and behavior/convention compliance of the work-continuation skill (9-14). Triggering assertions follow the plastic-auto eval style (one subagent router per case). Behavior assertions are convention checks against the SKILL.md.",
4
+ "results": {
5
+ "triggering": { "cases": 8, "passed": 8, "run": "2026-06-16, one subagent per case" },
6
+ "behavior": { "cases": 6, "passed": 6, "evidence": "convention checks against skills/continuing/SKILL.md after the intent-36 rewrite; doctor --core verified at 0.07s with 9 liveness checks and full doctor unchanged at 30 checks" }
7
+ },
8
+ "evals": [
9
+ {
10
+ "id": 1, "scope": "triggering", "set": "train",
11
+ "prompt": "continue",
12
+ "expected_output": "Activates plastic-continuing (the bare 'continue' keyword is the documented trigger).",
13
+ "files": [],
14
+ "assertions": [
15
+ { "type": "code", "check": "router CHOICE == plastic-continuing", "observed": "plastic-continuing", "result": "pass" }
16
+ ]
17
+ },
18
+ {
19
+ "id": 2, "scope": "triggering", "set": "train",
20
+ "prompt": "resume where we left off",
21
+ "expected_output": "Activates plastic-continuing.",
22
+ "files": [],
23
+ "assertions": [
24
+ { "type": "code", "check": "router CHOICE == plastic-continuing", "observed": "plastic-continuing", "result": "pass" }
25
+ ]
26
+ },
27
+ {
28
+ "id": 3, "scope": "triggering", "set": "validation",
29
+ "prompt": "pick up where we left off in this project",
30
+ "expected_output": "Activates plastic-continuing.",
31
+ "files": [],
32
+ "assertions": [
33
+ { "type": "code", "check": "router CHOICE == plastic-continuing", "observed": "plastic-continuing", "result": "pass" }
34
+ ]
35
+ },
36
+ {
37
+ "id": 4, "scope": "triggering", "set": "train",
38
+ "prompt": "boot plastic and show me where things stand",
39
+ "expected_output": "Activates plastic-continuing (continuing work + presenting state is the skill's purpose; boot itself is hook-owned).",
40
+ "files": [],
41
+ "assertions": [
42
+ { "type": "code", "check": "router CHOICE == plastic-continuing", "observed": "plastic-continuing", "result": "pass" }
43
+ ]
44
+ },
45
+ {
46
+ "id": 5, "scope": "triggering", "set": "train",
47
+ "prompt": "continue delivering this intent autonomously, don't ask me",
48
+ "expected_output": "Does NOT settle on plastic-continuing for execution. Shares 'continue' but the autonomous-delivery intent routes to plastic-auto.",
49
+ "files": [],
50
+ "assertions": [
51
+ { "type": "code", "check": "router CHOICE == plastic-auto", "observed": "plastic-auto", "result": "pass" }
52
+ ]
53
+ },
54
+ {
55
+ "id": 6, "scope": "triggering", "set": "validation",
56
+ "prompt": "continue the for-loop to the next iteration in this function",
57
+ "expected_output": "Does NOT activate plastic-continuing. Near-miss: shares 'continue' but is a code-editing task.",
58
+ "files": [],
59
+ "assertions": [
60
+ { "type": "code", "check": "router CHOICE != plastic-continuing", "observed": "none", "result": "pass" }
61
+ ]
62
+ },
63
+ {
64
+ "id": 7, "scope": "triggering", "set": "train",
65
+ "prompt": "resume the paused background download",
66
+ "expected_output": "Does NOT activate plastic-continuing. Near-miss: shares 'resume' but is unrelated to Plastic sessions.",
67
+ "files": [],
68
+ "assertions": [
69
+ { "type": "code", "check": "router CHOICE != plastic-continuing", "observed": "none", "result": "pass" }
70
+ ]
71
+ },
72
+ {
73
+ "id": 8, "scope": "triggering", "set": "validation",
74
+ "prompt": "what's the dashboard look like right now",
75
+ "expected_output": "May activate plastic-dashboard rather than plastic-continuing; an overview request without 'continue/resume' is a dashboard task.",
76
+ "files": [],
77
+ "assertions": [
78
+ { "type": "code", "check": "router CHOICE != plastic-continuing", "observed": "plastic-dashboard", "result": "pass" }
79
+ ]
80
+ },
81
+ {
82
+ "id": 9, "scope": "behavior", "set": "train",
83
+ "prompt": "Does the skill defer boot to the SessionStart hook rather than running it itself?",
84
+ "expected_output": "SKILL.md states boot (health check, core context, version banner, statusline) is owned by hook-session-start / plastic-statusline, not this skill.",
85
+ "files": ["skills/continuing/SKILL.md"],
86
+ "assertions": [
87
+ { "type": "convention", "check": "SKILL.md says boot is owned by the SessionStart hook and the skill does not run it", "observed": "'Boot is not this skill's job.' paragraph naming hook-session-start and plastic-statusline", "result": "pass" }
88
+ ]
89
+ },
90
+ {
91
+ "id": 10, "scope": "behavior", "set": "train",
92
+ "prompt": "Does the skill avoid running doctor / setting the statusline itself?",
93
+ "expected_output": "SKILL.md does NOT instruct running doctor.rb --core or setting the statusline; it attributes those to the hooks.",
94
+ "files": ["skills/continuing/SKILL.md"],
95
+ "assertions": [
96
+ { "type": "convention", "check": "no in-skill boot step invokes doctor.rb --core or sets the statusline; both are attributed to hooks", "observed": "doctor --core and statusline mentioned only as hook-owned in the 'Boot is not this skill's job' note", "result": "pass" }
97
+ ]
98
+ },
99
+ {
100
+ "id": 11, "scope": "behavior", "set": "train",
101
+ "prompt": "Is dashboard selection project-aware?",
102
+ "expected_output": "Project loaded -> `dashboard.rb project <slug>`; otherwise -> `dashboard.rb continue`. Skill only invokes, does not render.",
103
+ "files": ["skills/continuing/SKILL.md"],
104
+ "assertions": [
105
+ { "type": "convention", "check": "both dashboard invocations present and gated on project detection", "observed": "'dashboard.rb project <slug>' and 'dashboard.rb continue' in the 'Continue (present the dashboard)' section", "result": "pass" }
106
+ ]
107
+ },
108
+ {
109
+ "id": 12, "scope": "behavior", "set": "validation",
110
+ "prompt": "Is ledger-resume conditional and ledger-driven?",
111
+ "expected_output": "Resume fires only when a specific intent is named; reads savepoint.md last line as stage, verifies the stage file, rebuilds on drift, derives next step from first unchecked checklist item.",
112
+ "files": ["skills/continuing/SKILL.md"],
113
+ "assertions": [
114
+ { "type": "convention", "check": "Conditional Ledger-Resume section reads last ledger line, verifies stage file, calls rebuild_savepoint on drift, uses first unchecked checklist item", "observed": "all four present in 'Conditional Ledger-Resume'", "result": "pass" }
115
+ ]
116
+ },
117
+ {
118
+ "id": 13, "scope": "behavior", "set": "validation",
119
+ "prompt": "Are the stale prose-savepoint fields gone?",
120
+ "expected_output": "No 'In progress' / 'Blockers' fields read from a prose savepoint remain; the ledger model is used instead.",
121
+ "files": ["skills/continuing/SKILL.md"],
122
+ "assertions": [
123
+ { "type": "convention", "check": "no prose-savepoint announce template (In progress / Blockers from prose)", "observed": "absent; announce uses Stage/Next step/Context/Drift derived from ledger + checklist", "result": "pass" }
124
+ ]
125
+ },
126
+ {
127
+ "id": 14, "scope": "behavior", "set": "validation",
128
+ "prompt": "Is the 'Determine Store' local-store gap filled?",
129
+ "expected_output": "Step 2 of Determine Store describes local/project-store detection (no empty step).",
130
+ "files": ["skills/continuing/SKILL.md"],
131
+ "assertions": [
132
+ { "type": "convention", "check": "Determine Store step 2 documents local/project store detection via projects.yml + CWD match", "observed": "filled", "result": "pass" }
133
+ ]
134
+ }
135
+ ]
136
+ }
@@ -0,0 +1,32 @@
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