cyc-stack 0.6.0 → 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.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/INSTALL.md +55 -10
- package/README.md +223 -146
- package/bin/cyc.mjs +11 -2
- package/docs/engineering/failure-handling.md +6 -0
- package/docs/installation.md +14 -12
- package/docs/response-standard.md +1 -1
- package/docs/runtime.md +2 -0
- package/docs/work-assessments.md +78 -0
- package/methods/cyc-scout/SKILL.md +1 -1
- package/methods/cyc-verify/SKILL.md +4 -1
- package/package.json +2 -4
- package/plugin.json +1 -1
- package/scripts/runtime.mjs +117 -8
- package/scripts/test-output.mjs +10 -0
- package/scripts/work-review.mjs +73 -4
- package/skills/cyc/SKILL.md +4 -2
- package/scripts/check-response.mjs +0 -13
package/README.md
CHANGED
|
@@ -1,74 +1,65 @@
|
|
|
1
1
|
<a id="readme-top"></a>
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
|
-
<
|
|
5
|
-
<
|
|
6
|
-
<p>
|
|
7
|
-
<p>
|
|
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’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>
|
|
8
10
|
<p>
|
|
9
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>
|
|
10
|
-
<a href="
|
|
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>
|
|
11
13
|
<a href="#get-started"><img src="https://img.shields.io/badge/Node.js-20%2B-397b60" alt="Node.js 20 or later"></a>
|
|
12
14
|
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5268a8" alt="MIT license"></a>
|
|
13
15
|
</p>
|
|
14
|
-
<p><strong>17 supporting skills · 15 task playbooks</strong> / one entry point: <code>/cyc</code></p>
|
|
15
16
|
<p>
|
|
16
|
-
<a href="#
|
|
17
|
-
<a href="#
|
|
18
|
-
<a href="#
|
|
19
|
-
<a href="#skills">Skills</a> ·
|
|
20
|
-
<a href="#playbooks">Playbooks</a> ·
|
|
17
|
+
<a href="#get-started"><strong>Try CYC in your project →</strong></a> ·
|
|
18
|
+
<a href="#why-cyc">Why CYC</a> ·
|
|
19
|
+
<a href="#how-it-works">How it works</a> ·
|
|
21
20
|
<a href="docs/README.md">Docs</a>
|
|
22
21
|
</p>
|
|
23
22
|
</div>
|
|
24
23
|
|
|
25
|
-
## Why CYC?
|
|
26
|
-
|
|
27
|
-
<table>
|
|
28
|
-
<tr>
|
|
29
|
-
<td>
|
|
30
|
-
|
|
31
|
-
Architectural decisions, access rules, integration contracts and earlier failures shape what a correct change looks like. Your team needs that reasoning to remain available when the developer, AI tool or chat changes.
|
|
32
|
-
|
|
33
|
-
**CYC makes that reasoning part of the work.** It guides the assistant to retrieve relevant project knowledge, check it against current code, trace the impact of a change, verify the promised behavior, and retain useful findings for the next task.
|
|
34
|
-
|
|
35
24
|
<picture>
|
|
36
25
|
<source media="(max-width: 600px)" srcset="docs/assets/cyc-readme-banner-mobile.svg">
|
|
37
|
-
<img src="docs/assets/cyc-readme-banner.svg" alt="
|
|
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.">
|
|
38
27
|
</picture>
|
|
39
28
|
|
|
40
|
-
|
|
41
|
-
</tr>
|
|
42
|
-
</table>
|
|
29
|
+
CYC uses project knowledge to guide the task, checks the work, and carries useful lessons forward. Here’s the full workflow:
|
|
43
30
|
|
|
44
|
-
|
|
45
|
-
| --- | --- |
|
|
46
|
-
| **Continuity between people and sessions** | Versioned decisions, constraints and failure history the next task can find and revalidate. |
|
|
47
|
-
| **Changes that fit the existing system** | An account of affected callers, state, storage and interfaces, with checks for the behavior that must remain intact. |
|
|
48
|
-
| **A result someone else can review** | The implementation, executed checks, findings, unresolved limits and the reasoning behind consequential decisions. |
|
|
31
|
+
<a id="workflow-diagram"></a>
|
|
49
32
|
|
|
50
|
-
|
|
33
|
+

|
|
51
34
|
|
|
52
|
-
|
|
35
|
+
[Open the full-size diagram](docs/assets/cyc-workflow-diagram.svg) · [Step-by-step walkthrough](docs/cyc-workflow.md)
|
|
53
36
|
|
|
54
|
-
|
|
37
|
+
## Why CYC?
|
|
55
38
|
|
|
56
|
-
|
|
39
|
+
**Make the next task start with what you already learned.**
|
|
57
40
|
|
|
58
|
-
|
|
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. |
|
|
59
49
|
|
|
60
50
|
<details>
|
|
61
|
-
<summary><strong>
|
|
62
|
-
|
|
63
|
-
- [
|
|
64
|
-
- [
|
|
65
|
-
- [
|
|
66
|
-
- [
|
|
67
|
-
- [
|
|
68
|
-
- [
|
|
69
|
-
- [
|
|
70
|
-
- [
|
|
71
|
-
- [
|
|
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)
|
|
72
63
|
- [Contribute](#contribute)
|
|
73
64
|
- [License](#license)
|
|
74
65
|
|
|
@@ -78,42 +69,44 @@ A teammate extending that export can then retrieve the saved constraint and its
|
|
|
78
69
|
|
|
79
70
|
## Installation
|
|
80
71
|
|
|
81
|
-
|
|
82
|
-
<tr>
|
|
83
|
-
<td>
|
|
72
|
+
**Put CYC to work in a project you already know.**
|
|
84
73
|
|
|
85
|
-
**
|
|
86
|
-
|
|
87
|
-
- **Runtime:** Node.js 20+. Your application can use any language.
|
|
88
|
-
- **AI host:** Claude Code, Codex or Cursor.
|
|
89
|
-
- **Tools:** npm (included with Node.js). Claude project hooks also need Bash, including Git Bash on Windows.
|
|
90
|
-
|
|
91
|
-
</td>
|
|
92
|
-
</tr>
|
|
93
|
-
</table>
|
|
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.
|
|
94
75
|
|
|
95
76
|
> [!NOTE]
|
|
96
|
-
>
|
|
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)
|
|
97
78
|
|
|
98
79
|
### 1. Open your project
|
|
99
80
|
|
|
100
|
-
Open a terminal in the
|
|
81
|
+
Open a terminal in the root of the project where you want to use CYC. No source checkout or global installation is needed.
|
|
101
82
|
|
|
102
83
|
<a id="preview-and-install"></a>
|
|
84
|
+
<a id="2-install-cyc"></a>
|
|
103
85
|
|
|
104
|
-
### 2. Install
|
|
86
|
+
### 2. Install the skills and checks
|
|
105
87
|
|
|
106
88
|
```sh
|
|
107
|
-
npx cyc-stack@
|
|
89
|
+
npx cyc-stack@latest init
|
|
108
90
|
```
|
|
109
91
|
|
|
110
|
-
|
|
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`.
|
|
111
93
|
|
|
112
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.
|
|
113
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
|
+
|
|
114
107
|
### 3. Connect your project's checks
|
|
115
108
|
|
|
116
|
-
|
|
109
|
+
Reload your AI host and review any hook-trust prompts. Then paste this into your **AI chat**:
|
|
117
110
|
|
|
118
111
|
```text
|
|
119
112
|
/cyc Set up CYC for this project. Find the checks we already use in CI,
|
|
@@ -122,25 +115,32 @@ help me configure verification, and preserve our hooks and conventions.
|
|
|
122
115
|
|
|
123
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)
|
|
124
117
|
|
|
125
|
-
|
|
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:
|
|
126
123
|
|
|
127
124
|
```text
|
|
128
125
|
/cyc Add CSV export to the orders dashboard. Respect the current filters
|
|
129
126
|
and access rules. Export all matching orders, not just the visible page.
|
|
130
127
|
```
|
|
131
128
|
|
|
132
|
-
|
|
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.
|
|
133
132
|
|
|
134
133
|
<a id="other-installation-routes"></a>
|
|
135
134
|
|
|
136
135
|
<details>
|
|
137
|
-
<summary><strong>
|
|
136
|
+
<summary><strong>Choose another installation route</strong></summary>
|
|
138
137
|
|
|
139
138
|
| Route | Start here |
|
|
140
139
|
| --- | --- |
|
|
141
140
|
| Ask your agent | [Agent-guided installation](docs/installation.md#agent-guided-installation) |
|
|
142
141
|
| Native plugin | [Host installation and activation](INSTALL.md#install-as-a-plugin) |
|
|
143
|
-
| Source checkout or archive | [Installation without
|
|
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
144
|
|
|
145
145
|
Downloading a package and activating it in a project are separate steps. [Versions, archives and removal →](docs/installation.md)
|
|
146
146
|
|
|
@@ -148,39 +148,76 @@ Downloading a package and activating it in a project are separate steps. [Versio
|
|
|
148
148
|
|
|
149
149
|
[Full installation guide →](INSTALL.md)
|
|
150
150
|
|
|
151
|
-
|
|
151
|
+
<a id="context-engineering-for-enterprise-teams"></a>
|
|
152
152
|
|
|
153
|
-
##
|
|
153
|
+
## Context engineering: put your project knowledge to work
|
|
154
154
|
|
|
155
|
-
|
|
156
|
-
2. **Repeat [installation](#preview-and-install)** from the target project with `--dry-run` to preview, then without it to apply the update. Valid project configuration and local run records are preserved. Updating an npm dependency alone does not refresh the copied engine.
|
|
157
|
-
3. **Reload your AI host** and repeat the setup check so it uses the updated skills and hooks.
|
|
155
|
+
**Keep the knowledge that made the change possible.**
|
|
158
156
|
|
|
159
|
-
|
|
160
|
-
> 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)
|
|
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.
|
|
161
158
|
|
|
162
|
-
|
|
159
|
+
```text
|
|
160
|
+
Find relevant knowledge → Check it against the code → Use it → Retain what you learned
|
|
161
|
+
```
|
|
163
162
|
|
|
164
|
-
|
|
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
|
|
165
184
|
|
|
166
|
-
|
|
185
|
+
**The result should be easy to find. The evidence should be easy to inspect.**
|
|
167
186
|
|
|
168
|
-
CYC
|
|
187
|
+
CYC's delivery skills ask the assistant to make the handoff useful to the person reading it:
|
|
169
188
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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.
|
|
174
209
|
|
|
175
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.
|
|
176
211
|
|
|
177
|
-
[
|
|
212
|
+
[Engineering standards](docs/code-quality.md) · [Project tools and recipes](docs/project-tools.md) · [Rollout and validation boundaries](#validation-status)
|
|
178
213
|
|
|
179
214
|
## How it works
|
|
180
215
|
|
|
181
|
-
**
|
|
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.**
|
|
182
219
|
|
|
183
|
-
|
|
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.
|
|
184
221
|
|
|
185
222
|
The common implementation route is:
|
|
186
223
|
|
|
@@ -188,60 +225,75 @@ The common implementation route is:
|
|
|
188
225
|
Scout → Build → Verify → Deliver
|
|
189
226
|
```
|
|
190
227
|
|
|
191
|
-
| Stage | What
|
|
228
|
+
| Stage | What you should get |
|
|
192
229
|
| --- | --- |
|
|
193
|
-
| **Scout** |
|
|
194
|
-
| **Build** |
|
|
230
|
+
| **Scout** | Relevant history, affected behavior and a plan with checks. |
|
|
231
|
+
| **Build** | Changes that account for the plan, project conventions and affected consumers. |
|
|
195
232
|
| **Verify** | Current check results, applicable original-code test proof, findings and limits. |
|
|
196
|
-
| **Deliver** | A
|
|
233
|
+
| **Deliver** | A clear result, reviewable evidence and useful knowledge for the next task. |
|
|
197
234
|
|
|
198
|
-
Failed checks return to the responsible work within a shared retry budget.
|
|
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.
|
|
199
236
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
[Open the full-size diagram](docs/assets/cyc-workflow-diagram.svg) · [Step-by-step walkthrough](docs/cyc-workflow.md)
|
|
237
|
+
[See the workflow diagram above](#workflow-diagram) · [Step-by-step walkthrough](docs/cyc-workflow.md)
|
|
203
238
|
|
|
204
239
|
<p align="right"><a href="#readme-top">Back to top ↑</a></p>
|
|
205
240
|
|
|
206
241
|
## Skills
|
|
207
242
|
|
|
208
|
-
|
|
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.
|
|
209
246
|
|
|
210
|
-
|
|
247
|
+
<a id="start-with-understanding"></a>
|
|
211
248
|
|
|
212
|
-
|
|
249
|
+
<details>
|
|
250
|
+
<summary><strong>Understand the task and the codebase</strong></summary>
|
|
251
|
+
|
|
252
|
+
| Skill | What it brings to the task |
|
|
213
253
|
| --- | --- |
|
|
214
|
-
| [**Setup**](methods/cyc-setup/SKILL.md) |
|
|
215
|
-
| [**Scout**](methods/cyc-scout/SKILL.md) |
|
|
216
|
-
| [**Frame**](methods/cyc-frame/SKILL.md) |
|
|
217
|
-
| [**Understand**](methods/cyc-understand/SKILL.md) |
|
|
218
|
-
| [**Impact**](methods/cyc-impact/SKILL.md) |
|
|
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>
|
|
219
263
|
|
|
220
|
-
|
|
264
|
+
<details>
|
|
265
|
+
<summary><strong>Choose an approach, build it and check the result</strong></summary>
|
|
221
266
|
|
|
222
|
-
| Skill | What it
|
|
267
|
+
| Skill | What it brings to the task |
|
|
223
268
|
| --- | --- |
|
|
224
|
-
| [**Explore**](methods/cyc-explore/SKILL.md) |
|
|
225
|
-
| [**Design**](methods/cyc-design/SKILL.md) |
|
|
226
|
-
| [**Challenge**](methods/cyc-challenge/SKILL.md) |
|
|
227
|
-
| [**Build**](methods/cyc-build/SKILL.md) |
|
|
228
|
-
| [**Verify**](methods/cyc-verify/SKILL.md) |
|
|
229
|
-
| [**Deliver**](methods/cyc-deliver/SKILL.md) |
|
|
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.
|
|
230
277
|
|
|
231
|
-
|
|
278
|
+
</details>
|
|
232
279
|
|
|
233
|
-
|
|
280
|
+
<a id="continuity-learning-and-correction"></a>
|
|
281
|
+
|
|
282
|
+
<details>
|
|
283
|
+
<summary><strong>Carry knowledge forward and learn from corrections</strong></summary>
|
|
234
284
|
|
|
235
|
-
| Skill | What it
|
|
285
|
+
| Skill | What it brings to the task |
|
|
236
286
|
| --- | --- |
|
|
237
|
-
| [**Context**](methods/cyc-context/SKILL.md) |
|
|
238
|
-
| [**Remember**](methods/cyc-remember/SKILL.md) |
|
|
239
|
-
| [**Error Ledger**](methods/cyc-error-ledger/SKILL.md) |
|
|
240
|
-
| [**Correct**](methods/cyc-correct/SKILL.md) |
|
|
241
|
-
| [**Reflect**](methods/cyc-reflect/SKILL.md) |
|
|
242
|
-
| [**Teach**](methods/cyc-teach/SKILL.md) |
|
|
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. |
|
|
243
293
|
|
|
244
|
-
|
|
294
|
+
Context preserves component knowledge. Remember preserves task continuity. Reflect proposes improvements to the working method.
|
|
295
|
+
|
|
296
|
+
</details>
|
|
245
297
|
|
|
246
298
|
[Full method map and examples →](docs/cyc-method-map.md)
|
|
247
299
|
|
|
@@ -249,28 +301,30 @@ CYC exposes **one entry skill, 17 supporting methods, and a frontend design spec
|
|
|
249
301
|
|
|
250
302
|
## Playbooks
|
|
251
303
|
|
|
252
|
-
|
|
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.
|
|
253
307
|
|
|
254
|
-
| Playbook |
|
|
308
|
+
| Playbook | Bring it work like this |
|
|
255
309
|
| --- | --- |
|
|
256
|
-
| [**Investigation**](skills/cyc/references/playbooks/investigation.md) | Explain a behavior
|
|
257
|
-
| [**Explore**](skills/cyc/references/playbooks/explore.md) | Compare approaches
|
|
258
|
-
| [**Plan**](skills/cyc/references/playbooks/plan.md) | Break a substantial change into verifiable units
|
|
259
|
-
| [**Feature**](skills/cyc/references/playbooks/feature.md) | Build
|
|
260
|
-
| [**Bug fix**](skills/cyc/references/playbooks/bug-fix.md) | Reproduce
|
|
261
|
-
| [**Refactor**](skills/cyc/references/playbooks/refactor.md) | Improve structure
|
|
262
|
-
| [**Performance**](skills/cyc/references/playbooks/performance.md) |
|
|
263
|
-
| [**Review**](skills/cyc/references/playbooks/review.md) |
|
|
264
|
-
| [**Verify**](skills/cyc/references/playbooks/verify.md) |
|
|
265
|
-
| [**Experience**](skills/cyc/references/playbooks/experience.md) |
|
|
266
|
-
| [**Teach**](skills/cyc/references/playbooks/teach.md) | Learn
|
|
267
|
-
| [**Handoff**](skills/cyc/references/playbooks/handoff.md) |
|
|
268
|
-
| [**Resume**](skills/cyc/references/playbooks/resume.md) | Reconstruct interrupted work
|
|
269
|
-
| [**Reflect**](skills/cyc/references/playbooks/reflect.md) | Turn
|
|
270
|
-
| [**Evaluate**](skills/cyc/references/playbooks/evaluate.md) | Compare a workflow against a baseline
|
|
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. |
|
|
271
325
|
|
|
272
326
|
<details>
|
|
273
|
-
<summary><strong>
|
|
327
|
+
<summary><strong>Inspect the recorded routes</strong></summary>
|
|
274
328
|
|
|
275
329
|
| Playbook | Recorded stages |
|
|
276
330
|
| --- | --- |
|
|
@@ -290,7 +344,7 @@ A playbook gives a task its sequence and completion criteria. **Describe the out
|
|
|
290
344
|
| `reflect` | Remember → Reflect → Deliver |
|
|
291
345
|
| `evaluate` | Frame → Understand → Explore → Verify → Reflect → Deliver |
|
|
292
346
|
|
|
293
|
-
|
|
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.
|
|
294
348
|
|
|
295
349
|
</details>
|
|
296
350
|
|
|
@@ -306,34 +360,55 @@ Explain the evidence behind the findings. No edits.
|
|
|
306
360
|
build a usable mobile layout, and check keyboard, validation and recovery states.
|
|
307
361
|
```
|
|
308
362
|
|
|
309
|
-
|
|
363
|
+
## Updating
|
|
310
364
|
|
|
311
|
-
|
|
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)
|
|
312
383
|
|
|
313
384
|
## Validation status
|
|
314
385
|
|
|
386
|
+
**Inspect the evidence before you make it a team standard.**
|
|
387
|
+
|
|
315
388
|
CYC combines instructions the assistant follows with code that checks recorded work.
|
|
316
389
|
|
|
317
390
|
| Area | What is established |
|
|
318
391
|
| --- | --- |
|
|
319
392
|
| **Automated checks** | Exercise controller behavior, original-code test proof, recovery, context and installation. The CI badge links to current results. |
|
|
320
393
|
| **Host adapters** | Hook tests use simulated events. Actual prompt/Stop behavior needs confirmation in a fresh host session. |
|
|
321
|
-
| **Distribution** |
|
|
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. |
|
|
322
395
|
|
|
323
|
-
Inspect the methods, `.cyc/config.json` and local `.cyc/runs/` records.
|
|
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.
|
|
324
397
|
|
|
325
|
-
Before a team rollout, use a fixed revision and a representative task
|
|
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.
|
|
326
399
|
|
|
327
400
|
[Validation details →](docs/validation.md)
|
|
328
401
|
|
|
329
402
|
## Documentation
|
|
330
403
|
|
|
404
|
+
**Go deeper where your project needs it.**
|
|
405
|
+
|
|
331
406
|
| I want to… | Guide |
|
|
332
407
|
| --- | --- |
|
|
333
408
|
| Inspect all skills and routes | [Method map](docs/cyc-method-map.md) · [Playbook catalog](catalog/playbooks.json) |
|
|
334
409
|
| Install, update or remove CYC | [Installation](docs/installation.md) |
|
|
335
410
|
| Configure checks or recover interrupted work | [Onboarding and recovery](docs/onboarding-recovery.md) |
|
|
336
|
-
| Share project knowledge | [Context engineering](docs/context.md) |
|
|
411
|
+
| Share project knowledge and inspect context measurements | [Context engineering](docs/context.md) |
|
|
337
412
|
| Build a usable frontend | [Frontend design](methods/cyc-design/frontend-design/SKILL.md) |
|
|
338
413
|
| Reuse checks and recipes | [Project tools](docs/project-tools.md) |
|
|
339
414
|
| Inspect the controller and contracts | [Runtime](docs/runtime.md) · [Skill contract](docs/skill-contract.md) |
|
|
@@ -342,7 +417,9 @@ Before a team rollout, use a fixed revision and a representative task; inspect t
|
|
|
342
417
|
|
|
343
418
|
## Contribute
|
|
344
419
|
|
|
345
|
-
|
|
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.
|
|
346
423
|
|
|
347
424
|
For source changes, run:
|
|
348
425
|
|