cyc-stack 0.0.0-stage → 0.7.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.
Files changed (111) hide show
  1. package/.agents/plugins/marketplace.json +12 -0
  2. package/.claude-plugin/marketplace.json +14 -0
  3. package/.claude-plugin/plugin.json +17 -0
  4. package/.codex-plugin/plugin.json +33 -0
  5. package/.cursor-plugin/marketplace.json +13 -0
  6. package/.cursor-plugin/plugin.json +19 -0
  7. package/INSTALL.md +153 -0
  8. package/LICENSE +21 -0
  9. package/README.md +436 -2
  10. package/bin/cyc.mjs +294 -0
  11. package/catalog/playbooks.json +20 -0
  12. package/docs/README.md +30 -0
  13. package/docs/assets/cyc-method-library.svg +39 -0
  14. package/docs/assets/cyc-overview.svg +44 -0
  15. package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
  16. package/docs/assets/cyc-readme-banner.svg +39 -0
  17. package/docs/assets/cyc-workflow-diagram.svg +415 -0
  18. package/docs/code-quality.md +42 -0
  19. package/docs/context.md +40 -0
  20. package/docs/cyc-method-map.md +58 -0
  21. package/docs/cyc-workflow.md +188 -0
  22. package/docs/engineering/code-standards.md +103 -0
  23. package/docs/engineering/domain-design.md +81 -0
  24. package/docs/engineering/failure-handling.md +105 -0
  25. package/docs/impact-analysis.md +70 -0
  26. package/docs/installation.md +198 -0
  27. package/docs/onboarding-recovery.md +75 -0
  28. package/docs/principles.md +49 -0
  29. package/docs/project-tools.md +108 -0
  30. package/docs/response-standard.md +202 -0
  31. package/docs/runtime.md +249 -0
  32. package/docs/skill-contract.md +70 -0
  33. package/docs/skill-craft.md +23 -0
  34. package/docs/validation.md +39 -0
  35. package/docs/work-assessments.md +180 -0
  36. package/hooks/claude.json +10 -0
  37. package/hooks/codex.json +28 -0
  38. package/hooks/cursor.json +8 -0
  39. package/methods/cyc-build/SKILL.md +65 -0
  40. package/methods/cyc-build/references/file-writes.md +11 -0
  41. package/methods/cyc-challenge/SKILL.md +48 -0
  42. package/methods/cyc-context/SKILL.md +76 -0
  43. package/methods/cyc-context/references/evidence.md +27 -0
  44. package/methods/cyc-context/references/templates.md +54 -0
  45. package/methods/cyc-context/scripts/evidence.mjs +61 -0
  46. package/methods/cyc-correct/SKILL.md +43 -0
  47. package/methods/cyc-deliver/SKILL.md +52 -0
  48. package/methods/cyc-design/SKILL.md +50 -0
  49. package/methods/cyc-design/frontend-design/SKILL.md +43 -0
  50. package/methods/cyc-design/frontend-design/references/color.md +77 -0
  51. package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
  52. package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
  53. package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
  54. package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
  55. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
  56. package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
  57. package/methods/cyc-design/frontend-design/references/typography.md +51 -0
  58. package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
  59. package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
  60. package/methods/cyc-error-ledger/SKILL.md +53 -0
  61. package/methods/cyc-error-ledger/references/entry-format.md +38 -0
  62. package/methods/cyc-explore/SKILL.md +41 -0
  63. package/methods/cyc-frame/SKILL.md +49 -0
  64. package/methods/cyc-impact/SKILL.md +64 -0
  65. package/methods/cyc-reflect/SKILL.md +48 -0
  66. package/methods/cyc-remember/SKILL.md +53 -0
  67. package/methods/cyc-scout/SKILL.md +67 -0
  68. package/methods/cyc-setup/SKILL.md +60 -0
  69. package/methods/cyc-teach/SKILL.md +40 -0
  70. package/methods/cyc-understand/SKILL.md +40 -0
  71. package/methods/cyc-understand/references/diagnose.md +53 -0
  72. package/methods/cyc-verify/SKILL.md +87 -0
  73. package/methods/cyc-verify/references/recipe.md +53 -0
  74. package/package.json +91 -4
  75. package/plugin.json +40 -0
  76. package/rules/cyc-delivery.mdc +33 -0
  77. package/scripts/baseline-worker.mjs +10 -0
  78. package/scripts/catalog.mjs +29 -0
  79. package/scripts/claude-project-hook.mjs +12 -0
  80. package/scripts/context-review.mjs +600 -0
  81. package/scripts/host-activation.mjs +66 -0
  82. package/scripts/install.mjs +387 -0
  83. package/scripts/onboarding.mjs +110 -0
  84. package/scripts/packet.mjs +107 -0
  85. package/scripts/project-tools.mjs +196 -0
  86. package/scripts/recovery.mjs +66 -0
  87. package/scripts/response-gate.mjs +105 -0
  88. package/scripts/response-hook.mjs +237 -0
  89. package/scripts/response-mode.mjs +12 -0
  90. package/scripts/run-gate.mjs +264 -0
  91. package/scripts/runtime.mjs +1832 -0
  92. package/scripts/source-hash-worker.mjs +5 -0
  93. package/scripts/source-snapshot.mjs +405 -0
  94. package/scripts/test-output.mjs +268 -0
  95. package/scripts/work-review.mjs +326 -0
  96. package/skills/cyc/SKILL.md +132 -0
  97. package/skills/cyc/references/playbooks/bug-fix.md +13 -0
  98. package/skills/cyc/references/playbooks/evaluate.md +13 -0
  99. package/skills/cyc/references/playbooks/experience.md +7 -0
  100. package/skills/cyc/references/playbooks/explore.md +9 -0
  101. package/skills/cyc/references/playbooks/feature.md +14 -0
  102. package/skills/cyc/references/playbooks/handoff.md +11 -0
  103. package/skills/cyc/references/playbooks/investigation.md +7 -0
  104. package/skills/cyc/references/playbooks/performance.md +7 -0
  105. package/skills/cyc/references/playbooks/plan.md +11 -0
  106. package/skills/cyc/references/playbooks/refactor.md +12 -0
  107. package/skills/cyc/references/playbooks/reflect.md +11 -0
  108. package/skills/cyc/references/playbooks/resume.md +11 -0
  109. package/skills/cyc/references/playbooks/review.md +9 -0
  110. package/skills/cyc/references/playbooks/teach.md +11 -0
  111. package/skills/cyc/references/playbooks/verify.md +7 -0
package/README.md CHANGED
@@ -1,3 +1,437 @@
1
- # Temporary Holding Version
1
+ <a id="readme-top"></a>
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <div align="center">
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&mdash;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>
10
+ <p>
11
+ <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
+ <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>
13
+ <a href="#get-started"><img src="https://img.shields.io/badge/Node.js-20%2B-397b60" alt="Node.js 20 or later"></a>
14
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5268a8" alt="MIT license"></a>
15
+ </p>
16
+ <p>
17
+ <a href="#get-started"><strong>Try CYC in your project &rarr;</strong></a> &nbsp; &middot; &nbsp;
18
+ <a href="#why-cyc">Why CYC</a> &nbsp; &middot; &nbsp;
19
+ <a href="#how-it-works">How it works</a> &nbsp; &middot; &nbsp;
20
+ <a href="docs/README.md">Docs</a>
21
+ </p>
22
+ </div>
23
+
24
+ <picture>
25
+ <source media="(max-width: 600px)" srcset="docs/assets/cyc-readme-banner-mobile.svg">
26
+ <img src="docs/assets/cyc-readme-banner.svg" alt="Project knowledge informs the next change. Checks produce reviewable evidence, and verified lessons return to the project for the next task or teammate.">
27
+ </picture>
28
+
29
+ CYC uses project knowledge to guide the task, checks the work, and carries useful lessons forward. Here&rsquo;s the full workflow:
30
+
31
+ <a id="workflow-diagram"></a>
32
+
33
+ ![CYC workflow: project knowledge informs Scout, Build, Verify and Deliver; failed checks return to the responsible stage, and retained lessons support later work.](docs/assets/cyc-workflow-diagram.svg)
34
+
35
+ [Open the full-size diagram](docs/assets/cyc-workflow-diagram.svg) · [Step-by-step walkthrough](docs/cyc-workflow.md)
36
+
37
+ ## Why CYC?
38
+
39
+ **Make the next task start with what you already learned.**
40
+
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>
67
+
68
+ <a id="get-started"></a>
69
+
70
+ ## Installation
71
+
72
+ **Put CYC to work in a project you already know.**
73
+
74
+ You need **Node.js 20+, npm, and Claude Code, Codex or Cursor**. Your application can use any language. Claude project hooks also need Bash, including Git Bash on Windows.
75
+
76
+ > [!NOTE]
77
+ > CYC is available on [npm](https://www.npmjs.com/package/cyc-stack). CYC is a pilot; confirm hooks in your own AI host before a team rollout. [Validation status](#validation-status)
78
+
79
+ ### 1. Open your project
80
+
81
+ Open a terminal in the root of the project where you want to use CYC. No source checkout or global installation is needed.
82
+
83
+ <a id="preview-and-install"></a>
84
+ <a id="2-install-cyc"></a>
85
+
86
+ ### 2. Install the skills and checks
87
+
88
+ ```sh
89
+ npx cyc-stack@latest init
90
+ ```
91
+
92
+ Accept npm's package-download prompt if it appears. The command installs the latest published release into this project without adding a dependency to your application's `package.json`.
93
+
94
+ The installer adds CYC's engine, the `cyc` entry skill and host hooks. Existing project instructions and unrelated hooks are preserved. Hosts are detected automatically; [choose a host explicitly](docs/installation.md) when needed.
95
+
96
+ <details>
97
+ <summary><strong>Preview the changes first</strong></summary>
98
+
99
+ ```sh
100
+ npx cyc-stack@latest init --dry-run
101
+ ```
102
+
103
+ Review the proposed changes, then run the install command above to apply them.
104
+
105
+ </details>
106
+
107
+ ### 3. Connect your project's checks
108
+
109
+ Reload your AI host and review any hook-trust prompts. Then paste this into your **AI chat**:
110
+
111
+ ```text
112
+ /cyc Set up CYC for this project. Find the checks we already use in CI,
113
+ help me configure verification, and preserve our hooks and conventions.
114
+ ```
115
+
116
+ Setup records approved commands in `.cyc/config.json` and reports their results. Confirm real prompt/Stop hook behavior in a fresh session; installed files alone do not establish activation. [Setup and activation guide](docs/installation.md#activation-and-diagnosis)
117
+
118
+ <a id="4-start-your-first-task"></a>
119
+
120
+ ### 4. Give it a real task
121
+
122
+ Describe the outcome you want. For example:
123
+
124
+ ```text
125
+ /cyc Add CSV export to the orders dashboard. Respect the current filters
126
+ and access rules. Export all matching orders, not just the visible page.
127
+ ```
128
+
129
+ 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
+
131
+ Inspect the change, the checks and the handoff. Look for a useful decision or lesson the next task should be able to find.
132
+
133
+ <a id="other-installation-routes"></a>
134
+
135
+ <details>
136
+ <summary><strong>Choose another installation route</strong></summary>
137
+
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) |
144
+
145
+ Downloading a package and activating it in a project are separate steps. [Versions, archives and removal →](docs/installation.md)
146
+
147
+ </details>
148
+
149
+ [Full installation guide →](INSTALL.md)
150
+
151
+ <a id="context-engineering-for-enterprise-teams"></a>
152
+
153
+ ## Context engineering: put your project knowledge to work
154
+
155
+ **Keep the knowledge that made the change possible.**
156
+
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
+ ```
162
+
163
+ ### Token optimization: give context a purpose
164
+
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)
170
+
171
+ <a id="what-that-means-in-a-real-task"></a>
172
+
173
+ ### A lesson the next task can use
174
+
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.
182
+
183
+ ## Get answers you can use
184
+
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.
199
+
200
+ ## Make it a shared standard
201
+
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)
213
+
214
+ ## How it works
215
+
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.
221
+
222
+ The common implementation route is:
223
+
224
+ ```text
225
+ 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
+
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>
240
+
241
+ ## Skills
242
+
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.
246
+
247
+ <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
+ <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
+ <a id="continuity-learning-and-correction"></a>
281
+
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
+ ## Playbooks
303
+
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.
348
+
349
+ </details>
350
+
351
+ ### Try a different kind of task
352
+
353
+ ```text
354
+ /cyc Review this diff for API compatibility, error handling and affected consumers.
355
+ Explain the evidence behind the findings. No edits.
356
+ ```
357
+
358
+ ```text
359
+ /cyc Improve this site's complete signup journey. Establish a visual direction,
360
+ build a usable mobile layout, and check keyboard, validation and recovery states.
361
+ ```
362
+
363
+ ## Updating
364
+
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)
383
+
384
+ ## Validation status
385
+
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.
389
+
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)
401
+
402
+ ## Documentation
403
+
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)
417
+
418
+ ## Contribute
419
+
420
+ **Bring a reproducible problem or a tested improvement.**
421
+
422
+ [Open an issue](https://github.com/TheDThompsonDev/cyc-stack/issues) with the host, Node version, steps and observed result.
423
+
424
+ For source changes, run:
425
+
426
+ ```sh
427
+ node --test
428
+ npm run check:distribution
429
+ ```
430
+
431
+ The local runtime has no third-party dependencies. For method changes, compare a representative task before rollout and retain evidence of improvements and regressions. [Skill-writing guidance](docs/skill-craft.md)
432
+
433
+ ## License
434
+
435
+ Distributed under the [MIT License](LICENSE).
436
+
437
+ <p align="right"><a href="#readme-top">Back to top ↑</a></p>