cyc-stack 0.8.3 → 0.9.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.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.8.3",
3
+ "version": "0.9.0",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.8.3",
3
+ "version": "0.9.0",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cycstack",
3
- "version": "0.8.3",
3
+ "version": "0.9.0",
4
4
  "license": "MIT",
5
5
  "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
6
  "author": {
package/README.md CHANGED
@@ -2,11 +2,8 @@
2
2
 
3
3
  <div align="center">
4
4
  <p><strong>CYC Stack</strong></p>
5
- <h1>Make your AI worth the tokens it uses.</h1>
6
- <p>CYC is a portable library of engineering skills and playbooks for Claude Code, Codex and Cursor, built around <strong>context engineering, token optimization and clear, actionable results.</strong></p>
7
- <p>You spent the tokens getting it right. <strong>The decisions and lessons that got you there shouldn&rsquo;t disappear when the chat ends.</strong></p>
8
- <p>Give your agent the context that matters. Carry what you learn into the next task. Get answers that show what changed, what was checked and what still needs attention.</p>
9
- <p><strong>Put it to work on your next task. Make it a shared standard for your team.</strong></p>
5
+ <h1>Give your AI the project knowledge behind the change.</h1>
6
+ <p>CYC helps your coding assistant find relevant project rules, check its changes and leave useful knowledge for the next chat. Inspect what changed, what was checked and what remains uncertain.</p>
10
7
  <p>
11
8
  <a href="https://github.com/TheDThompsonDev/cyc-stack/actions/workflows/ci.yml"><img src="https://github.com/TheDThompsonDev/cyc-stack/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
12
9
  <a href="https://www.npmjs.com/package/cyc-stack"><img src="https://img.shields.io/npm/v/cyc-stack" alt="Latest cyc-stack version on npm"></a>
@@ -36,34 +33,9 @@ CYC uses project knowledge to guide the task, checks the work, and carries usefu
36
33
 
37
34
  ## Why CYC?
38
35
 
39
- **Make the next task start with what you already learned.**
36
+ Your request says what to change. Project rules and earlier decisions say what must keep working. CYC guides the assistant to find that knowledge, recheck it, verify the change and leave a useful handoff. The intended payoff is easier review and continuation; speed, token savings and universal reliability require separate evidence.
40
37
 
41
- Your codebase has decisions, constraints and lessons behind it. CYC gives your coding agent a method for finding that knowledge, checking whether it still holds, and using it on the work in front of you.
42
-
43
- | Put your effort toward… | How CYC helps |
44
- | --- | --- |
45
- | **Context that earns its place** | An index points the agent to relevant project notes, decisions and failure history. |
46
- | **Corrections that carry forward** | Record what failed, what changed and what the next attempt needs to account for. |
47
- | **Work you can inspect** | Run your project's checks and retain the results, decisions and remaining limits. |
48
- | **Answers you can use** | Lead with the result, show the evidence and make unfinished work clear. |
49
-
50
- <details>
51
- <summary><strong>Find your next step</strong></summary>
52
-
53
- - [Install CYC and start a task](#installation)
54
- - [Put context engineering and token optimization to work](#context-engineering-for-enterprise-teams)
55
- - [Get answers you can use](#get-answers-you-can-use)
56
- - [Make it a shared standard](#make-it-a-shared-standard)
57
- - [See how the workflow runs](#how-it-works)
58
- - [Explore the skills](#skills)
59
- - [Find a playbook for the work](#playbooks)
60
- - [Update an existing installation](#updating)
61
- - [Inspect validation status](#validation-status)
62
- - [Go deeper in the docs](#documentation)
63
- - [Contribute](#contribute)
64
- - [License](#license)
65
-
66
- </details>
38
+ Start with a task you know, then observe a fresh chat extending it. Inspect actual decisions, checks, retained context and missed behavior. [How it works](#how-it-works) · [Validation](#validation-status)
67
39
 
68
40
  <a id="get-started"></a>
69
41
 
@@ -128,225 +100,65 @@ and access rules. Export all matching orders, not just the visible page.
128
100
 
129
101
  Replace the example with your own task. Use `/cyc` in your AI host. If it is unavailable, select the discovered `cyc` skill or say **“Use the cyc skill to…”**
130
102
 
131
- Inspect the change, the checks and the handoff. Look for a useful decision or lesson the next task should be able to find.
103
+ Expect a short explanation before work: the outcome, existing behavior to preserve and the relevant project knowledge. During work, discoveries and failed checks should explain a decision. At delivery, inspect actual checks, limitations and the linked project notes. These explanations are guidance, not automatic proof of quality.
132
104
 
133
- <a id="other-installation-routes"></a>
134
-
135
- <details>
136
- <summary><strong>Choose another installation route</strong></summary>
105
+ For a first exercise, use a bounded task in a project you know. Illustrative example: add an Open tasks filter while preserving the All tasks view and stored records. A useful discovery might be that imported fields exist outside the screen model; the filter should preserve them. A fresh chat can later add an Open tasks count using the same revalidated rule. Observe whether it actually finds and uses the saved knowledge.
137
106
 
138
- | Route | Start here |
139
- | --- | --- |
140
- | Ask your agent | [Agent-guided installation](docs/installation.md#agent-guided-installation) |
141
- | Native plugin | [Host installation and activation](INSTALL.md#install-as-a-plugin) |
142
- | Source checkout or archive | [Installation without npm](INSTALL.md#install-without-npm) |
143
- | Save a development dependency or pin a version | [Optional npm controls](docs/installation.md#optional-npm-controls) |
107
+ Request → find relevant knowledge → check the change → retain what matters
144
108
 
145
- Downloading a package and activating it in a project are separate steps. [Versions, archives and removal →](docs/installation.md)
109
+ Say `expand` for more detail once, or `limit off` to allow longer replies in this chat. `limit on` restores short replies. Send commands as their own message; allowing longer answers keeps CYC's workflow and evidence requirements. The ambiguous phrase “turn this off” is not a supported control.
146
110
 
147
- </details>
111
+ <a id="other-installation-routes"></a>
148
112
 
149
- [Full installation guide →](INSTALL.md)
113
+ [Agent-guided, plugin, archive and pinned installation options](docs/installation.md) · [Full install guide](INSTALL.md). Downloading the package and activating it in the project are separate steps.
150
114
 
151
115
  <a id="context-engineering-for-enterprise-teams"></a>
152
116
 
153
117
  ## Context engineering: put your project knowledge to work
154
118
 
155
- **Keep the knowledge that made the change possible.**
119
+ Load the project's index and matching notes, check consequential claims against current code and your request, then apply and retain what matters. The target project's focused records live under docs/context/ with INDEX.md; engine documentation is not application knowledge.
156
120
 
157
- CYC's context method directs the agent to retain decisions, constraints, useful failed approaches and supporting evidence in repository notes. A path-based index connects later tasks to the relevant knowledge. The agent checks consequential claims against current code before relying on them.
158
-
159
- ```text
160
- Find relevant knowledge → Check it against the code → Use it → Retain what you learned
161
- ```
121
+ Find → revalidate → apply to a decision → retain → reuse
162
122
 
163
123
  ### Token optimization: give context a purpose
164
124
 
165
- Load the index and matching notes for the task. Bring forward the decisions, known dead ends and check recipes that matter. Open deeper methods when the work calls for them.
166
-
167
- That is CYC's strategy for focused context and useful reuse. Investigation and verification can consume additional tokens upfront. **Speed, token savings and universal reliability are not established.** Reading-size estimates do not establish provider billing or successful reuse.
168
-
169
- [Context engineering and measurement limits →](docs/context.md)
125
+ Load deeper methods only when relevant. Reading-size estimates cannot establish billing or useful reuse; investigation can add work upfront. [Context and measurement limits](docs/context.md).
170
126
 
171
127
  <a id="what-that-means-in-a-real-task"></a>
172
128
 
173
129
  ### A lesson the next task can use
174
130
 
175
- **Illustrative example: “Add CSV export to the orders dashboard.”**
176
-
177
- CYC directs the assistant to investigate pagination, filters and access rules before implementing the download. Verification should exercise all authorized matching records, including results beyond the visible page and rejected access.
178
-
179
- The useful lesson is the export contract: which filters apply, how access is enforced, and why the visible page is insufficient. Retain that decision with its evidence. A later task can retrieve it, check whether it still holds, and build on it.
180
-
181
- This illustrates the intended workflow. To assess reuse in your project, inspect whether a fresh session actually finds and applies the retained knowledge.
131
+ For the illustrative task-board filter, preserve imported fields even if the screen does not show them. Save the rule and its evidence. A fresh chat adding a count should find/revalidate the same definition of Open tasks. Observe that behavior before claiming successful reuse.
182
132
 
183
133
  ## Get answers you can use
184
134
 
185
- **The result should be easy to find. The evidence should be easy to inspect.**
186
-
187
- CYC's delivery skills ask the assistant to make the handoff useful to the person reading it:
188
-
189
- | What you need to know | What the handoff should show |
190
- | --- | --- |
191
- | **What happened?** | The result or blocker up front, with links to the work. |
192
- | **What supports it?** | The checks actually run, their outcomes and a visual that clarifies the result. |
193
- | **What still needs attention?** | Unchecked behavior, unresolved limits and any decision you need to make. |
194
- | **What carries forward?** | Useful decisions, lessons and evidence the next task can find. |
195
-
196
- Progress updates explain consequential choices while the work is happening. Final summaries stay brief and link to deeper evidence. Use `expand` for more detail once, or `limit off` for longer replies throughout the conversation. [Response controls](docs/response-standard.md#character-limit-toggle)
197
-
198
- Delivery hooks check reply structure and recorded readiness where active. The assistant remains responsible for clarity and substance; structural checks alone cannot establish either.
135
+ Delivery leads with the result or blocker, actual checks and limits, one useful visual, and links to retained project knowledge. Progress explains consequential decisions. Response-length choices are shown with the first task above; [the response standard](docs/response-standard.md) explains them. Where active, hooks validate structure and recorded readiness. Clarity, semantics and human understanding still need judgment.
199
136
 
200
137
  ## Make it a shared standard
201
138
 
202
- **Start with work you know. Share the practices that earn their place.**
203
-
204
- For an independent engineer, that starts with a useful task and a later session that can find its lessons. For an engineering manager, it becomes a repeatable way to bring project knowledge, verification and clear handoffs into the team's AI work.
205
-
206
- 1. **Try a representative task.** Use a fixed release and inspect the implementation, checks and final response.
207
- 2. **Check the handoff.** Ask a fresh session or teammate to use the retained knowledge on related work. Look for missed context, stale guidance and lessons that actually help.
208
- 3. **Share the working practices.** Review the context and check configuration with the code. Pin the release you qualified, and confirm activation in each teammate's AI host.
209
-
210
- Your team owns the context, verification commands and review process. Shared knowledge lives in repository documents; detailed run records stay local by default. Existing CI, access rules and merge controls remain yours.
211
-
212
- [Engineering standards](docs/code-quality.md) · [Project tools and recipes](docs/project-tools.md) · [Rollout and validation boundaries](#validation-status)
139
+ Try a bounded task on a fixed release, inspect the evidence and observe a fresh chat using its knowledge. Confirm hooks in each actual host before rollout. Teams retain ownership of context, verification commands and merge/access controls. Detailed receipts stay local by default. [Engineering standards](docs/code-quality.md) · [Rollout limits](#validation-status)
213
140
 
214
141
  ## How it works
215
142
 
216
- **Describe the outcome. Follow a method. Inspect the evidence.**
217
-
218
- Start with [`/cyc`](skills/cyc/SKILL.md). The assistant selects a playbook and loads the relevant supporting skills. **Skills guide how to do the work. Playbooks give the task its route and completion criteria.**
219
-
220
- CYC also includes a local controller: it records stage handoffs, runs your configured project checks and checks evidence freshness. Applicable new regression tests must fail against the original code before the controller accepts the change.
143
+ Start with [`/cyc`](skills/cyc/SKILL.md). The assistant selects relevant methods and a route. The controller records handoffs, runs configured checks and validates evidence freshness, including applicable original-code proof. Failed checks return to responsible work within recorded budgets.
221
144
 
222
- The common implementation route is:
223
-
224
- ```text
225
145
  Scout → Build → Verify → Deliver
226
- ```
227
-
228
- | Stage | What you should get |
229
- | --- | --- |
230
- | **Scout** | Relevant history, affected behavior and a plan with checks. |
231
- | **Build** | Changes that account for the plan, project conventions and affected consumers. |
232
- | **Verify** | Current check results, applicable original-code test proof, findings and limits. |
233
- | **Deliver** | A clear result, reviewable evidence and useful knowledge for the next task. |
234
-
235
- Failed checks return to the responsible work within a shared retry budget. Other tasks use routes suited to their outcome. The controller bounds its recorded retries; it does not continuously monitor or terminate the host agent.
236
146
 
237
- [See the workflow diagram above](#workflow-diagram) · [Step-by-step walkthrough](docs/cyc-workflow.md)
238
-
239
- <p align="right"><a href="#readme-top">Back to top ↑</a></p>
147
+ Recorded stages do not certify comprehension or product correctness. The controller does not continuously monitor the host agent. [Workflow diagram](#workflow-diagram) · [Walkthrough](docs/cyc-workflow.md) · [Runtime](docs/runtime.md)
240
148
 
241
149
  ## Skills
242
150
 
243
- **Give your agent a method for the work in front of it.**
244
-
245
- CYC has **one entry skill, 17 supporting methods, and a frontend design specialization inside Design**. Start with `/cyc`; the assistant loads what the task needs. Your existing AI host performs the skills. Each method is a focused procedure, not automatically a separate agent.
151
+ Use the single `/cyc` entry point and describe the outcome. CYC selects supporting methods; you do not need to choose an internal skill. The [method map](docs/cyc-method-map.md) and [skill index](docs/README.md) describe the library when you need deeper detail.
246
152
 
247
153
  <a id="start-with-understanding"></a>
248
-
249
- <details>
250
- <summary><strong>Understand the task and the codebase</strong></summary>
251
-
252
- | Skill | What it brings to the task |
253
- | --- | --- |
254
- | [**Setup**](methods/cyc-setup/SKILL.md) | Find the project's checks, configure verification and report setup and host-activation evidence. |
255
- | [**Scout**](methods/cyc-scout/SKILL.md) | Bring relevant history, affected files and verification needs into an initial plan. |
256
- | [**Frame**](methods/cyc-frame/SKILL.md) | Define the outcome, scope and criteria for success. |
257
- | [**Understand**](methods/cyc-understand/SKILL.md) | Trace behavior or reproduce a failure; separate confirmed causes from hypotheses. |
258
- | [**Impact**](methods/cyc-impact/SKILL.md) | Find the callers, state, storage and interfaces a change could affect. |
259
-
260
- </details>
261
-
262
154
  <a id="choose-and-deliver-the-change"></a>
263
-
264
- <details>
265
- <summary><strong>Choose an approach, build it and check the result</strong></summary>
266
-
267
- | Skill | What it brings to the task |
268
- | --- | --- |
269
- | [**Explore**](methods/cyc-explore/SKILL.md) | Compare distinct approaches or scoped prototypes before choosing a direction. |
270
- | [**Design**](methods/cyc-design/SKILL.md) | Define state, interfaces, compatibility and implementation slices. |
271
- | [**Challenge**](methods/cyc-challenge/SKILL.md) | Test a plan or change against concrete counter-cases and return supported findings. |
272
- | [**Build**](methods/cyc-build/SKILL.md) | Implement tested slices, review the diff and record consequential decisions. |
273
- | [**Verify**](methods/cyc-verify/SKILL.md) | Exercise the promised behavior, affected consumers and relevant rejection and recovery paths. |
274
- | [**Deliver**](methods/cyc-deliver/SKILL.md) | Put the result, evidence, a useful visual and honest limits into a reviewable handoff. |
275
-
276
- [**Frontend design**](methods/cyc-design/frontend-design/SKILL.md) adds visual direction, desktop and phone review, and usability and access checks. Design quality still requires review; a passing build cannot establish it.
277
-
278
- </details>
279
-
280
155
  <a id="continuity-learning-and-correction"></a>
281
156
 
282
- <details>
283
- <summary><strong>Carry knowledge forward and learn from corrections</strong></summary>
284
-
285
- | Skill | What it brings to the task |
286
- | --- | --- |
287
- | [**Context**](methods/cyc-context/SKILL.md) | Retrieve and revalidate component knowledge; retain useful findings in indexed project notes. |
288
- | [**Remember**](methods/cyc-remember/SKILL.md) | Keep task checkpoints and reconstruct decisions and next steps after interruption. |
289
- | [**Error Ledger**](methods/cyc-error-ledger/SKILL.md) | Make failed approaches, confirmed causes and regression evidence searchable. |
290
- | [**Correct**](methods/cyc-correct/SKILL.md) | Turn feedback into a missing criterion, a targeted repair and renewed checks. |
291
- | [**Reflect**](methods/cyc-reflect/SKILL.md) | Propose improvements to the methods from completed outcomes and evidence. |
292
- | [**Teach**](methods/cyc-teach/SKILL.md) | Explain a concept through the project's own code, examples and optional practice. |
293
-
294
- Context preserves component knowledge. Remember preserves task continuity. Reflect proposes improvements to the working method.
295
-
296
- </details>
297
-
298
- [Full method map and examples →](docs/cyc-method-map.md)
299
-
300
- <a id="example-tasks"></a>
301
-
302
157
  ## Playbooks
303
158
 
304
- **Name the outcome. The assistant selects the route.**
305
-
306
- The 15 playbooks cover implementation, investigation, learning and handoffs. Describe your task through `/cyc`; you do not need to memorize the catalog.
307
-
308
- | Playbook | Bring it work like this |
309
- | --- | --- |
310
- | [**Investigation**](skills/cyc/references/playbooks/investigation.md) | Explain what causes a behavior, with evidence. |
311
- | [**Explore**](skills/cyc/references/playbooks/explore.md) | Compare approaches before committing to one. |
312
- | [**Plan**](skills/cyc/references/playbooks/plan.md) | Break a substantial change into verifiable units. |
313
- | [**Feature**](skills/cyc/references/playbooks/feature.md) | Build changed behavior and check the affected consumers. |
314
- | [**Bug fix**](skills/cyc/references/playbooks/bug-fix.md) | Reproduce the failure, repair its cause and establish regression evidence. |
315
- | [**Refactor**](skills/cyc/references/playbooks/refactor.md) | Improve structure and verify preserved behavior. |
316
- | [**Performance**](skills/cyc/references/playbooks/performance.md) | Measure the baseline, target a bottleneck and check the change. |
317
- | [**Review**](skills/cyc/references/playbooks/review.md) | Find consequential issues in existing work and explain the evidence. |
318
- | [**Verify**](skills/cyc/references/playbooks/verify.md) | Check an executable result against explicit criteria. |
319
- | [**Experience**](skills/cyc/references/playbooks/experience.md) | Improve a complete user journey and check its connected behavior. |
320
- | [**Teach**](skills/cyc/references/playbooks/teach.md) | Learn through the project's code and worked examples. |
321
- | [**Handoff**](skills/cyc/references/playbooks/handoff.md) | Leave decisions, evidence and limits someone else can use. |
322
- | [**Resume**](skills/cyc/references/playbooks/resume.md) | Reconstruct interrupted work and check what has changed. |
323
- | [**Reflect**](skills/cyc/references/playbooks/reflect.md) | Turn completed outcomes into proposals for better methods. |
324
- | [**Evaluate**](skills/cyc/references/playbooks/evaluate.md) | Compare a workflow against a baseline with recorded outcomes and limits. |
325
-
326
- <details>
327
- <summary><strong>Inspect the recorded routes</strong></summary>
328
-
329
- | Playbook | Recorded stages |
330
- | --- | --- |
331
- | `investigation` | Scout → Deliver |
332
- | `explore` | Frame → Understand → Explore → Challenge → Deliver |
333
- | `plan` | Frame → Understand → Impact → Design → Challenge → Deliver |
334
- | `feature` | Scout → Build → Verify → Deliver |
335
- | `bug-fix` | Scout → Build → Verify → Deliver |
336
- | `refactor` | Scout → Build → Verify → Deliver |
337
- | `performance` | Scout → Build → Verify → Deliver |
338
- | `review` | Scout → Challenge → Verify → Deliver |
339
- | `verify` | Scout → Verify → Deliver |
340
- | `experience` | Scout → Explore → Build → Verify → Deliver |
341
- | `teach` | Frame → Understand → Teach → Deliver |
342
- | `handoff` | Understand → Verify → Deliver |
343
- | `resume` | Remember → Understand → Deliver |
344
- | `reflect` | Remember → Reflect → Deliver |
345
- | `evaluate` | Frame → Understand → Explore → Verify → Reflect → Deliver |
346
-
347
- Routes come from the [playbook catalog](catalog/playbooks.json). A stage may use additional supporting methods. The controller records and validates handoffs; it does not automatically launch skills or establish that the assistant performed them well.
159
+ <a id="example-tasks"></a>
348
160
 
349
- </details>
161
+ Implementation uses Scout → Build → Verify → Deliver. Investigation, planning, review, teaching and recovery have their own recorded routes. The [catalog](catalog/playbooks.json) defines those stages; the [CYC guide](skills/cyc/SKILL.md#playbooks) links each procedure. Routes and stages support the requested outcome; their completion does not establish product correctness or user comprehension.
350
162
 
351
163
  ### Try a different kind of task
352
164
 
@@ -362,58 +174,17 @@ build a usable mobile layout, and check keyboard, validation and recovery states
362
174
 
363
175
  ## Updating
364
176
 
365
- **Keep the methods current as your project moves forward.**
366
-
367
- From your project root, preview the latest release's changes:
368
-
369
- ```sh
370
- npx cyc-stack@latest init --dry-run
371
- ```
372
-
373
- Then apply the update:
374
-
375
- ```sh
376
- npx cyc-stack@latest init
377
- ```
378
-
379
- Valid project configuration and local run records are preserved. Updating an npm dependency alone does not refresh the copied engine. **Reload your AI host** after updating and repeat the setup check so the session uses the new skills and hooks. Teams can [pin an approved version](docs/installation.md#optional-npm-controls).
380
-
381
- > [!IMPORTANT]
382
- > If you edited a CYC-managed file, the installer reports a conflict and writes nothing. Back up and merge that customization before retrying. [Update and conflict guidance](docs/installation.md#updating-conflicts-and-removal)
177
+ From the target project, preview with `npx cyc-stack@latest init --dry-run`, then update with `npx cyc-stack@latest init`. Reload the host and repeat setup validation. Project configuration and run records are preserved. Modified managed files cause a conflict with no writes; merge deliberately before retrying. [Updates, version pinning and conflicts](docs/installation.md#updating-conflicts-and-removal).
383
178
 
384
179
  ## Validation status
385
180
 
386
- **Inspect the evidence before you make it a team standard.**
387
-
388
- CYC combines instructions the assistant follows with code that checks recorded work.
181
+ CYC is a pilot. Automated tests exercise controller, recovery, context and installation behavior; adapter tests use simulated events. Qualify fresh prompt/Stop, rejection/correction, restart and upgrade in each actual host before making compatibility claims. Inspect configuration, source-bound receipts and retained context on representative work.
389
182
 
390
- | Area | What is established |
391
- | --- | --- |
392
- | **Automated checks** | Exercise controller behavior, original-code test proof, recovery, context and installation. The CI badge links to current results. |
393
- | **Host adapters** | Hook tests use simulated events. Actual prompt/Stop behavior needs confirmation in a fresh host session. |
394
- | **Distribution** | Published on [npm](https://www.npmjs.com/package/cyc-stack), with source and archive routes available. Public directory listings and fresh native-host qualification remain separate release steps. |
395
-
396
- Inspect the methods, `.cyc/config.json` and local `.cyc/runs/` records. Source hashes and passing commands do not establish that every dependency was found or every check was sufficient. Local hooks are workflow guardrails; they do not provide a security sandbox, tamper-proof attestation or authorization to merge or deploy.
397
-
398
- Before a team rollout, use a fixed revision and a representative task. Inspect the work and confirm that a fresh chat or teammate can use the retained knowledge. Speed, token savings and universal reliability are not established.
399
-
400
- [Validation details →](docs/validation.md)
183
+ Local hooks are workflow guardrails, not a security sandbox or tamper-proof attestation. Stage/hash/test passes do not certify complete coverage, human comprehension or universal correctness. Speed and token savings remain unestablished. [Evidence and rollout limits](docs/validation.md).
401
184
 
402
185
  ## Documentation
403
186
 
404
- **Go deeper where your project needs it.**
405
-
406
- | I want to… | Guide |
407
- | --- | --- |
408
- | Inspect all skills and routes | [Method map](docs/cyc-method-map.md) · [Playbook catalog](catalog/playbooks.json) |
409
- | Install, update or remove CYC | [Installation](docs/installation.md) |
410
- | Configure checks or recover interrupted work | [Onboarding and recovery](docs/onboarding-recovery.md) |
411
- | Share project knowledge and inspect context measurements | [Context engineering](docs/context.md) |
412
- | Build a usable frontend | [Frontend design](methods/cyc-design/frontend-design/SKILL.md) |
413
- | Reuse checks and recipes | [Project tools](docs/project-tools.md) |
414
- | Inspect the controller and contracts | [Runtime](docs/runtime.md) · [Skill contract](docs/skill-contract.md) |
415
-
416
- [Browse all documentation →](docs/README.md)
187
+ [Browse the guides](docs/README.md) for installation, context, recovery, recipes, frontend design and controller contracts. Start with [onboarding/recovery](docs/onboarding-recovery.md) for setup or interrupted work, and [project tools](docs/project-tools.md) for existing investigation/check recipes.
417
188
 
418
189
  ## Contribute
419
190
 
package/bin/cyc.mjs CHANGED
@@ -4,7 +4,8 @@ import { dirname, resolve } from 'node:path';
4
4
  import { resolveExecution, artifactFiles } from '../scripts/execution.mjs';
5
5
  import { isDeepStrictEqual } from 'node:util';
6
6
  import { catalog, routeTask } from '../scripts/catalog.mjs';
7
- import { acceptFailure, activeRun, callerSession, inputPath, completeRun, controlRun, finishRun, nextRun, projectFile, proveRun, quickHandoff, readRun, recordHandoff, recoverRun, retryRun, reviewRun, startRun, verifyRun, captureReview, recordReview, startOperation, waitOperation, prepareRunContext } from '../scripts/runtime.mjs';
7
+ import { completionGuidance } from '../scripts/recovery.mjs';
8
+ import { acceptFailure, activeRun, callerSession, inputPath, completeRun, controlRun, finishRun, nextRun, projectFile, proveRun, quickHandoff, readRun, recordHandoff, recoverRun, retryRun, reviewRun, startRun, verifyRun, captureReview, recordReview, startOperation, waitOperation, prepareRunContext, taskContext, delegateRun } from '../scripts/runtime.mjs';
8
9
 
9
10
  const args = process.argv.slice(2);
10
11
  const positionals = [];
@@ -54,6 +55,9 @@ Discover:
54
55
  (execute an applicable authorized recipe; retain diagnostic evidence)
55
56
 
56
57
  Component context docs (docs/context/):
58
+ cyc context task --run ID
59
+ cyc context ack --run ID --file ACK.json
60
+ cyc delegate swarm|decide|assign|execute|record|cancel|cancel-swarm|reconcile --run ID --file INPUT.json
57
61
  cyc context prepare --run ID [--file CONTEXT.json]
58
62
  cyc context review [--run ID | --since YYYY-MM-DD | --all] [--write --update-run UPDATE_ID] [--new NAME]
59
63
  (map completed runs' changed files to component docs and propose the doc entry from each run's
@@ -109,7 +113,7 @@ All commands accept --project PATH. Criteria file: [{"id":"saved","description":
109
113
  Store handoff files under .cyc/runs/ID/ to avoid changing the source being verified.
110
114
  New implementation runs require Scout, Verify, and Deliver assessments; run next lists required fields.
111
115
  See docs/work-assessments.md for the compact JSON contract and knowledge lifecycle.
112
- The host agent reads and executes the returned skill; CYC does not launch paid model calls.
116
+ The host executes skills; opt-in delegate execute launches Codex model calls.
113
117
  Configure verification.commands in .cyc/config.json; without them, executable runs use the project's declared test command or are refused.
114
118
  Hook activation/trust must be checked in your host; doctor does not certify it.`);
115
119
  process.exit(0);
@@ -138,6 +142,17 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
138
142
  result = await tools.runRecipe(root, options.recipe, { run: options.run });
139
143
  if (!options.verbose && result.results) result.results = result.results.map(({ id, command, args, passed, exitCode, error, errorCode, stdout, stderr }) => ({ id, command, args, passed, exitCode, error, errorCode, outputTail: `${stdout ?? ''}${stderr ?? ''}`.trim().split('\n').slice(-15).join('\n') }));
140
144
  } else throw new Error('Use recipe list or recipe run.');
145
+ } else if (command === 'delegate') {
146
+ if (!options.run || !options.file) throw new Error('delegate needs the exact --run ID and --file JSON.');
147
+ fileOnly(options, ['run','file','project','verbose']);
148
+ result = action === 'swarm' ? await (await import('../scripts/swarm.mjs')).executeSwarm(root,options.run,readJSON(options.file)) : action === 'execute'
149
+ ? await (await import('../scripts/codex-host.mjs')).executeCodex(root, options.run, readJSON(options.file))
150
+ : delegateRun(root, options.run, action, readJSON(options.file));
151
+ } else if (command === 'context' && ['task','ack'].includes(action)) {
152
+ if (!options.run) throw new Error('Task context needs the exact --run ID.');
153
+ fileOnly(options, action === 'ack' ? ['run','file','project','verbose'] : ['run','project','verbose']);
154
+ if (action === 'ack' && !options.file) throw new Error('context ack needs --file JSON.');
155
+ result = taskContext(root, options.run, action, action === 'ack' ? readJSON(options.file) : {});
141
156
  } else if (command === 'context') {
142
157
  const context = await import('../scripts/context-review.mjs');
143
158
  if (action === 'review') result = context.reviewContext(root, { run: options.run, since: options.since, all: !!options.all, write: !!options.write, newDoc: options.new, updateRun: options['update-run'] });
@@ -177,14 +192,14 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
177
192
  } else if (command === 'playbooks') result = catalog;
178
193
  else if (command === 'route') {
179
194
  if (!options.goal) throw new Error('--goal is required.');
180
- result = routeTask(options.goal);
195
+ result = routeTask(options.goal,{paths:options.path??[]});
181
196
  } else if (command === 'run') {
182
197
  switch (action) {
183
198
  case 'start': {
184
199
  let input;
185
200
  if (options.file) {
186
201
  fileOnly(options, ['file', 'project', 'verbose']);
187
- input = inputObject(options.file, ['goal', 'playbook', 'criteria', 'allowedPaths', 'session', 'scout', 'plan', 'evidenceVersion', 'requirements', 'reviewPolicy', 'executionMode', 'conversationId', 'proofCommands', 'contextRetention']);
202
+ input = inputObject(options.file, ['goal', 'playbook', 'criteria', 'allowedPaths', 'session', 'scout', 'plan', 'evidenceVersion', 'requirements', 'reviewPolicy', 'executionMode', 'conversationId', 'proofCommands', 'contextRetention', 'taskContext', 'delegation']);
188
203
  for (const key of ['goal', 'playbook', 'session', 'plan']) if (input[key] !== undefined && typeof input[key] !== 'string') throw new Error(`${key} must be a string.`);
189
204
  if (input.scout !== undefined && !object(input.scout)) throw new Error('scout must be the Scout assessment object (run start without it returns the template).');
190
205
  if (input.criteria !== undefined && (!Array.isArray(input.criteria) || !input.criteria.length || input.criteria.some(item => !object(item) || typeof item.id !== 'string' || typeof item.description !== 'string'))) throw new Error('criteria must be a nonempty array of {id, description} string records.');
@@ -252,7 +267,7 @@ Hook activation/trust must be checked in your host; doctor does not certify it.`
252
267
  } else throw new Error(`Unknown command ${command}. Use cyc help.`);
253
268
  if (command === 'run' && !options.verbose) result = compact(action, result, root, options);
254
269
  console.log(humanInstallOutput(command) ? formatInstall(result) : JSON.stringify(result, null, 2));
255
- if (result?.ok === false || ['halted', 'exhausted', 'blocked'].includes(result?.status) || result?.passed === false || result?.result?.passed === false || ['halted', 'exhausted', 'blocked'].includes(result?.result?.status)) process.exitCode = 1;
270
+ if (result?.ok === false || result?.status === 'needs-context-sync' || ['halted', 'exhausted', 'blocked'].includes(result?.status) || result?.passed === false || result?.result?.passed === false || ['halted', 'exhausted', 'blocked'].includes(result?.result?.status)) process.exitCode = 1;
256
271
  } catch (error) {
257
272
  const result = { ok: false, error: error.message, ...(error.setup ? { setup: error.setup } : {}), ...(error.field ? { field: error.field, repairTemplate: error.repairTemplate } : {}) };
258
273
  console.error(humanInstallOutput(positionals[0]) ? formatInstall(result) : JSON.stringify(result));
@@ -329,11 +344,15 @@ function preexistingHint(ids) {
329
344
 
330
345
  function compact(action, result, root, options) {
331
346
  if (!result || typeof result !== 'object' || ['status', 'recover'].includes(action)) return result;
332
- if (result.operationId) return result;
333
347
  const id = result.runId ?? result.id ?? options.run;
348
+ const guidance = value => completionGuidance(value, { executionMode: (value.result ?? value).packet?.written === false ? readRun(root, id).execution?.mode : undefined });
349
+ if (result.operationId) return { ...result, guidance: guidance(result) };
334
350
  if (['review-capture', 'review-record'].includes(action)) { const { files, ...receipt } = result; return receipt; }
335
351
  if (action === 'prove-red') return result;
336
- if (action === 'finish') return result.failedAt === 'verify' && 'verificationStatus' in result ? { ...compact('verify', result, root, options), finished: false, failedAt: 'verify' } : result;
352
+ if (action === 'finish') {
353
+ const display = result.failedAt === 'verify' && 'verificationStatus' in result ? { ...compact('verify', result, root, options), finished: false, failedAt: 'verify' } : result;
354
+ return { ...display, guidance: guidance(display) };
355
+ }
337
356
  if (action === 'verify') {
338
357
  const recovery = result.passed ? null : recoverRun(root, id);
339
358
  return { runId: id, status: result.status, passed: result.passed, sourceStable: result.sourceStable, changedPaths: result.changedPaths, verificationStatus: result.verificationStatus, acceptedPreexistingFailures: result.acceptedPreexistingFailures, ...(result.acceptedFailuresThatChanged ? { acceptedFailuresThatChanged: result.acceptedFailuresThatChanged } : {}), ...(result.failedAtRunStart ? { failedAtRunStart: result.failedAtRunStart } : {}), ...(result.awaitingAcceptance ? { awaitingAcceptance: true } : {}),
@@ -345,6 +364,10 @@ function compact(action, result, root, options) {
345
364
  }
346
365
  if (!id) return result;
347
366
  const next = nextRun(root, id);
367
+ if(action==='next') {
368
+ const state=readRun(root,id);
369
+ next.workflowAdvice=routeTask(state.goal,{paths:state.allowedPaths}).guidance;
370
+ }
348
371
  const { previousHandoff, criteria, limits, assessmentRequired, assessmentTemplate, ...rest } = next;
349
372
  // Agents often read only the first lines (| head -40), so what they act on comes first and the
350
373
  // long fill-in template last.