cyc-stack 0.0.0-stage → 0.6.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 (112) 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 +108 -0
  8. package/LICENSE +21 -0
  9. package/README.md +359 -2
  10. package/bin/cyc.mjs +285 -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 +99 -0
  25. package/docs/impact-analysis.md +70 -0
  26. package/docs/installation.md +196 -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 +247 -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 +102 -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 +84 -0
  73. package/methods/cyc-verify/references/recipe.md +53 -0
  74. package/package.json +93 -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/check-response.mjs +13 -0
  80. package/scripts/claude-project-hook.mjs +12 -0
  81. package/scripts/context-review.mjs +600 -0
  82. package/scripts/host-activation.mjs +66 -0
  83. package/scripts/install.mjs +387 -0
  84. package/scripts/onboarding.mjs +110 -0
  85. package/scripts/packet.mjs +107 -0
  86. package/scripts/project-tools.mjs +196 -0
  87. package/scripts/recovery.mjs +66 -0
  88. package/scripts/response-gate.mjs +105 -0
  89. package/scripts/response-hook.mjs +237 -0
  90. package/scripts/response-mode.mjs +12 -0
  91. package/scripts/run-gate.mjs +264 -0
  92. package/scripts/runtime.mjs +1723 -0
  93. package/scripts/source-hash-worker.mjs +5 -0
  94. package/scripts/source-snapshot.mjs +405 -0
  95. package/scripts/test-output.mjs +258 -0
  96. package/scripts/work-review.mjs +257 -0
  97. package/skills/cyc/SKILL.md +130 -0
  98. package/skills/cyc/references/playbooks/bug-fix.md +13 -0
  99. package/skills/cyc/references/playbooks/evaluate.md +13 -0
  100. package/skills/cyc/references/playbooks/experience.md +7 -0
  101. package/skills/cyc/references/playbooks/explore.md +9 -0
  102. package/skills/cyc/references/playbooks/feature.md +14 -0
  103. package/skills/cyc/references/playbooks/handoff.md +11 -0
  104. package/skills/cyc/references/playbooks/investigation.md +7 -0
  105. package/skills/cyc/references/playbooks/performance.md +7 -0
  106. package/skills/cyc/references/playbooks/plan.md +11 -0
  107. package/skills/cyc/references/playbooks/refactor.md +12 -0
  108. package/skills/cyc/references/playbooks/reflect.md +11 -0
  109. package/skills/cyc/references/playbooks/resume.md +11 -0
  110. package/skills/cyc/references/playbooks/review.md +9 -0
  111. package/skills/cyc/references/playbooks/teach.md +11 -0
  112. package/skills/cyc/references/playbooks/verify.md +7 -0
@@ -0,0 +1,12 @@
1
+ {
2
+ "name": "cycstack",
3
+ "interface": { "displayName": "CYC Stack" },
4
+ "plugins": [
5
+ {
6
+ "name": "cycstack",
7
+ "source": { "source": "local", "path": "./" },
8
+ "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
9
+ "category": "Productivity"
10
+ }
11
+ ]
12
+ }
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "cycstack",
3
+ "owner": {
4
+ "name": "CYC Stack contributors"
5
+ },
6
+ "description": "CYC Stack: verified, loop-engineered AI workflows for software teams.",
7
+ "plugins": [
8
+ {
9
+ "name": "cycstack",
10
+ "source": "./",
11
+ "description": "Portable AI engineering workflows with shared project context and verifiable changes."
12
+ }
13
+ ]
14
+ }
@@ -0,0 +1,17 @@
1
+ {
2
+ "name": "cycstack",
3
+ "version": "0.6.0",
4
+ "license": "MIT",
5
+ "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
+ "author": {
7
+ "name": "CYC Stack contributors"
8
+ },
9
+ "keywords": [
10
+ "engineering",
11
+ "skills",
12
+ "verification",
13
+ "loop-engineering",
14
+ "context-engineering"
15
+ ],
16
+ "hooks": "./hooks/claude.json"
17
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "name": "cycstack",
3
+ "version": "0.6.0",
4
+ "license": "MIT",
5
+ "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
+ "author": {
7
+ "name": "CYC Stack contributors"
8
+ },
9
+ "skills": "./skills/",
10
+ "keywords": [
11
+ "engineering",
12
+ "skills",
13
+ "verification",
14
+ "loop-engineering",
15
+ "context-engineering"
16
+ ],
17
+ "interface": {
18
+ "displayName": "CYC Stack",
19
+ "shortDescription": "Portable workflows with visible evidence",
20
+ "longDescription": "Coordinate reusable skills, investigate affected behavior, loop until verified, and keep a project history of context and errors. Ask CYC to set up each project to activate the delivery gate.",
21
+ "developerName": "CYC Stack contributors",
22
+ "category": "Productivity",
23
+ "capabilities": [
24
+ "Interactive",
25
+ "Write"
26
+ ],
27
+ "defaultPrompt": [
28
+ "Set up CYC in this project.",
29
+ "Use CYC to fix this bug and verify affected behavior."
30
+ ]
31
+ },
32
+ "hooks": "./hooks/codex.json"
33
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "cycstack",
3
+ "owner": {
4
+ "name": "CYC Stack contributors"
5
+ },
6
+ "plugins": [
7
+ {
8
+ "name": "cycstack",
9
+ "source": ".",
10
+ "description": "Portable AI engineering workflows with shared project context and verifiable changes."
11
+ }
12
+ ]
13
+ }
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "cycstack",
3
+ "version": "0.6.0",
4
+ "license": "MIT",
5
+ "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
+ "author": {
7
+ "name": "CYC Stack contributors"
8
+ },
9
+ "keywords": [
10
+ "engineering",
11
+ "skills",
12
+ "verification",
13
+ "loop-engineering",
14
+ "context-engineering"
15
+ ],
16
+ "skills": "./skills/",
17
+ "rules": "./rules/",
18
+ "hooks": "./hooks/cursor.json"
19
+ }
package/INSTALL.md ADDED
@@ -0,0 +1,108 @@
1
+ # Install CYC Stack
2
+
3
+ Choose one route. All routes use the same CYC methods and project context. Full local workflows need Node.js 20+ and a supported AI host; Claude project hooks also need Bash, including Git Bash on Windows.
4
+
5
+ **Release channels:** the public repository contains the npm and plugin distributions. Registry commands require a published version on the selected channel; a reviewed checkout or approved archive also works. Native-host qualification remains pending. Maintainers: [build and publish the release](https://github.com/TheDThompsonDev/cyc-stack/blob/main/docs/maintainers/distribution.md).
6
+
7
+ ## Install with npm
8
+
9
+ After the pilot is published to `next`, run from the application project root:
10
+
11
+ ```sh
12
+ npx cyc-stack@next init
13
+ ```
14
+
15
+ No flags are required. npm may ask before downloading the package. Installation adds CYC's engine, one public `cyc` skill and host hooks. CYC detects hosts from existing project files; if none are detected, it sets up all three supported hosts. It preserves existing project instructions and unrelated hooks, and refuses conflicts with unowned or customized files.
16
+
17
+ To keep CYC as a dependency in `package.json`, use:
18
+
19
+ ```sh
20
+ npm install --save-dev cyc-stack@next
21
+ npx cyc-stack init
22
+ ```
23
+
24
+ `npm install` downloads the package; `init` sets up the project's AI integration. The one-command route above does both without adding a dependency to `package.json`. Applications can use any language; verification uses their own checks. After installation, [finish project setup](#finish-project-setup).
25
+
26
+ Previewing changes, choosing a host, saving a development dependency and selecting an approved version are [optional install controls](docs/installation.md#optional-npm-controls).
27
+
28
+ ## Ask your agent
29
+
30
+ Give your agent this request in the project where you want CYC:
31
+
32
+ ```text
33
+ Install CYC Stack in this project. Follow its INSTALL.md at
34
+ https://github.com/TheDThompsonDev/cyc-stack/blob/main/INSTALL.md
35
+ or the reviewed local checkout I provide. Preview the local changes,
36
+ preserve our instructions and unrelated hooks, then configure our real
37
+ project checks and tell me whether this host actually loaded the hooks.
38
+ ```
39
+
40
+ Teams can replace `main` with their approved tag or commit. The agent needs its normal command and filesystem capabilities; CYC does not connect to it through a separate service.
41
+
42
+ Agent procedure: follow [agent-guided installation](docs/installation.md#agent-guided-installation).
43
+
44
+ An isolated copy of `skills/cyc` is insufficient: its methods and CLI are part of the same distribution. Use the installer or a complete plugin bundle.
45
+
46
+ ## Install as a plugin
47
+
48
+ Install the native plugin, then ask **“Use CYC to set up this project.”** Plugin installation makes methods available; project activation and check configuration happen separately. Your host owns plugin files and updates. The existing `activate` command creates project config and ignore rules; it does not install Node or prove hooks are active.
49
+
50
+ For **Claude Code**, the repository includes a marketplace. Once the source is accessible and the host integration qualified:
51
+
52
+ ```sh
53
+ claude plugin marketplace add TheDThompsonDev/cyc-stack
54
+ claude plugin install cycstack@cycstack
55
+ ```
56
+
57
+ For **Codex desktop**, register the public repository marketplace using a current Codex CLI:
58
+
59
+ ```sh
60
+ codex plugin marketplace add TheDThompsonDev/cyc-stack
61
+ ```
62
+
63
+ Restart the desktop app, open its plugin browser, select the **CYC Stack** marketplace and install **CYC Stack**. Review and trust its hooks through the host UI, then run setup. If your client lacks this marketplace command, use the [manual repository marketplace flow](https://developers.openai.com/plugins/build/plugins#install-a-local-plugin-manually).
64
+
65
+ The repository catalog is `.agents/plugins/marketplace.json`. Root `plugin.json` is the portable manifest; `.codex-plugin/plugin.json` remains the compatibility fallback. The same npm archive contains both. CYC's lifecycle-hook plugin cannot currently be listed unchanged in OpenAI's public directory. Installing a skills-only listing on the web would not deploy local hooks. [OpenAI distribution limits](https://developers.openai.com/plugins/build/plugins#bundled-mcp-servers-and-lifecycle-hooks).
66
+
67
+ For **Cursor**, use its native plugin flow with `.cursor-plugin/plugin.json`; the full bundle includes rules and Cursor-specific hooks. Local import can be restricted by team policy. Official marketplace listing is a separate review step. [Cursor plugin installation](https://cursor.com/docs/plugins).
68
+
69
+ The discovered invocation can be namespaced, such as a plugin's `cyc` command. You can always ask the host to use the discovered CYC skill by name. Do not install both routes just to obtain the same methods. If both exist, verify which integration owns the hooks; plugin hooks defer to a project installation for that host.
70
+
71
+ ## Finish project setup
72
+
73
+ Reload the host and review any hook-trust prompt through its normal UI. Ask CYC to find and configure the project's existing checks. For project installations:
74
+
75
+ ```sh
76
+ node .cyc/engine/bin/cyc.mjs doctor
77
+ node .cyc/engine/bin/cyc.mjs onboard
78
+ ```
79
+
80
+ `doctor` checks files and configuration. `onboard` separates remaining setup steps; inspection runs no project checks. Passing diagnostics alone does not establish native hook activation. For plugin installs, the agent resolves these CLI commands from the plugin's own directory.
81
+
82
+ Local run/check records support verification and recovery in the target project. No adoption analytics system is required. Review [installation details](docs/installation.md) for file ownership, retained records, updates and removal.
83
+
84
+ ## Updates and removal
85
+
86
+ Plugins use their host's update controls. Enable automatic marketplace updates where the host and team allow them. A team can keep an approved version; a publisher cannot force updates onto arbitrary public installations.
87
+
88
+ For npm, select the desired published version and rerun its installer. Updating the dependency alone does not refresh `.cyc/engine` or the copied skills. Preview changes, finish or stop active work under the existing recovery rules, update, then reload the host. CYC does not yet provide an automatic update checker or scheduler.
89
+
90
+ To remove a project installation, preview first:
91
+
92
+ ```sh
93
+ node .cyc/engine/bin/cyc.mjs uninstall --dry-run
94
+ node .cyc/engine/bin/cyc.mjs uninstall
95
+ ```
96
+
97
+ Then remove the npm development dependency if you added it. Customized files and run records can be retained; inspect the command report. Plugin removal uses the host's own controls and does not imply deletion of project context or local evidence.
98
+
99
+ ## Before registry publication
100
+
101
+ Use a reviewed checkout with repository access:
102
+
103
+ ```sh
104
+ node /path/to/cycstack/bin/cyc.mjs init --project /path/to/application --dry-run
105
+ node /path/to/cycstack/bin/cyc.mjs init --project /path/to/application
106
+ ```
107
+
108
+ Quote paths containing spaces. An approved packed archive is another option; see [offline installation](docs/installation.md#private-repositories-and-npm-git-fetch-failures). These paths use the real installer while publication is pending.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Danny Thompson
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,360 @@
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
+ <h1>CYC Stack</h1>
5
+ <p><strong>AI coding work your team can pick up and verify.</strong></p>
6
+ <p>Give every developer and AI session the benefit of what your team has already learned.</p>
7
+ <p>A project-local workflow for <strong>Claude Code, Codex and Cursor</strong>.<br>Context engineering, focused skills and executable checks for enterprise codebases.</p>
8
+ <p>
9
+ <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="#validation-status"><img src="https://img.shields.io/badge/release-0.6.0%20pilot-5268a8" alt="Release: 0.6.0 pilot"></a>
11
+ <a href="#get-started"><img src="https://img.shields.io/badge/Node.js-20%2B-397b60" alt="Node.js 20 or later"></a>
12
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-5268a8" alt="MIT license"></a>
13
+ </p>
14
+ <p><strong>17 supporting skills &middot; 15 task playbooks</strong> &nbsp; / &nbsp; one entry point: <code>/cyc</code></p>
15
+ <p>
16
+ <a href="#why-cyc"><strong>Why CYC</strong></a> &nbsp; &middot; &nbsp;
17
+ <a href="#installation">Installation</a> &nbsp; &middot; &nbsp;
18
+ <a href="#updating">Updating</a> &nbsp; &middot; &nbsp;
19
+ <a href="#skills">Skills</a> &nbsp; &middot; &nbsp;
20
+ <a href="#playbooks">Playbooks</a> &nbsp; &middot; &nbsp;
21
+ <a href="docs/README.md">Docs</a>
22
+ </p>
23
+ </div>
24
+
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
+ <picture>
36
+ <source media="(max-width: 600px)" srcset="docs/assets/cyc-readme-banner-mobile.svg">
37
+ <img src="docs/assets/cyc-readme-banner.svg" alt="CYC context loop: project knowledge informs the next change, the work produces reviewable evidence, and verified lessons return to the project.">
38
+ </picture>
39
+
40
+ </td>
41
+ </tr>
42
+ </table>
43
+
44
+ | What your team needs | What the workflow asks the assistant to leave |
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. |
49
+
50
+ **Instructions plus executable checks:** CYC's local controller runs your project commands, checks source freshness and records completion. Applicable new regression tests must fail against the original code before the change can be accepted by the controller.
51
+
52
+ ### What that means in a real task
53
+
54
+ **Illustrative example: “Add CSV export to the orders dashboard.”**
55
+
56
+ CYC directs the assistant to investigate pagination, filters and access rules before implementing a download. Verification should exercise complete authorized results, including records beyond the visible page and rejected access. The handoff explains the query decision, the cases actually checked and any unmeasured limits.
57
+
58
+ A teammate extending that export can then retrieve the saved constraint and its evidence, check whether it still holds, and continue without reconstructing the original conversation.
59
+
60
+ <details>
61
+ <summary><strong>On this page</strong></summary>
62
+
63
+ - [Why CYC?](#why-cyc)
64
+ - [Installation](#installation)
65
+ - [Updating](#updating)
66
+ - [Context engineering for enterprise teams](#context-engineering-for-enterprise-teams)
67
+ - [How it works](#how-it-works)
68
+ - [Every supporting skill](#skills)
69
+ - [All 15 playbooks](#playbooks)
70
+ - [Validation status](#validation-status)
71
+ - [Documentation](#documentation)
72
+ - [Contribute](#contribute)
73
+ - [License](#license)
74
+
75
+ </details>
76
+
77
+ <a id="get-started"></a>
78
+
79
+ ## Installation
80
+
81
+ <table>
82
+ <tr>
83
+ <td>
84
+
85
+ **Before you install**
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>
94
+
95
+ > [!NOTE]
96
+ > **The npm pilot uses the `next` channel.** Registry commands require a published version; source and archive installation also work. Native-host qualification remains pending. [Other installation routes](#other-installation-routes) · [Validation status](#validation-status)
97
+
98
+ ### 1. Open your project
99
+
100
+ Open a terminal in the existing application project where you want CYC. Your application can use any language; no source checkout or global installation is required for the npm route.
101
+
102
+ <a id="preview-and-install"></a>
103
+
104
+ ### 2. Install CYC
105
+
106
+ ```sh
107
+ npx cyc-stack@next init
108
+ ```
109
+
110
+ Add `--dry-run` to preview the changes first. npm may ask before downloading the package.
111
+
112
+ 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
+
114
+ ### 3. Connect your project's checks
115
+
116
+ Open the target project in your AI host, reload it and review any hook-trust prompts. Then ask:
117
+
118
+ ```text
119
+ /cyc Set up CYC for this project. Find the checks we already use in CI,
120
+ help me configure verification, and preserve our hooks and conventions.
121
+ ```
122
+
123
+ 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
+
125
+ ### 4. Start your first task
126
+
127
+ ```text
128
+ /cyc Add CSV export to the orders dashboard. Respect the current filters
129
+ and access rules. Export all matching orders, not just the visible page.
130
+ ```
131
+
132
+ If `/cyc` is unavailable, select the discovered `cyc` skill or say **“Use the cyc skill to…”**
133
+
134
+ <a id="other-installation-routes"></a>
135
+
136
+ <details>
137
+ <summary><strong>Other installation routes</strong></summary>
138
+
139
+ | Route | Start here |
140
+ | --- | --- |
141
+ | Ask your agent | [Agent-guided installation](docs/installation.md#agent-guided-installation) |
142
+ | Native plugin | [Host installation and activation](INSTALL.md#install-as-a-plugin) |
143
+ | Source checkout or archive | [Installation without the registry](INSTALL.md#before-registry-publication) |
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
+ Maintainers can build the npm/plugin candidate and its checksum with `npm run pack:release`. [First publication and plugin distribution →](https://github.com/TheDThompsonDev/cyc-stack/blob/main/docs/maintainers/distribution.md)
152
+
153
+ ## Updating
154
+
155
+ 1. **Select the release your team wants**, for example `cyc-stack@next` for the pilot or an approved exact version.
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.
158
+
159
+ > [!IMPORTANT]
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)
161
+
162
+ For team rollouts, select a fixed revision and qualify it with a representative task. [Release and validation boundaries](#validation-status)
163
+
164
+ <p align="right"><a href="#readme-top">Back to top ↑</a></p>
165
+
166
+ ## Context engineering for enterprise teams
167
+
168
+ CYC keeps useful project knowledge in Git, where the team can review it alongside the code.
169
+
170
+ 1. **Retain the reasoning.** Component notes hold decisions, integration constraints, useful failed approaches and supporting evidence.
171
+ 2. **Find relevant context.** A path-based index connects the task to the matching notes, failure history and check recipes.
172
+ 3. **Check freshness.** The assistant revalidates consequential claims against current code and dependencies before relying on them.
173
+ 4. **Carry learning forward.** Verified findings and useful decisions become starting context for later work.
174
+
175
+ 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
+
177
+ [Context engineering guide](docs/context.md) · [Engineering standards](docs/code-quality.md) · [Project tools and recipes](docs/project-tools.md)
178
+
179
+ ## How it works
180
+
181
+ **Skills describe how to perform part of the work. Playbooks choose the recorded route for a task.**
182
+
183
+ Use the public [`/cyc` skill](skills/cyc/SKILL.md) to describe your outcome. The assistant selects a playbook and loads the relevant supporting skills. The local controller records stage handoffs, runs configured checks and checks evidence freshness.
184
+
185
+ The common implementation route is:
186
+
187
+ ```text
188
+ Scout → Build → Verify → Deliver
189
+ ```
190
+
191
+ | Stage | What moves forward |
192
+ | --- | --- |
193
+ | **Scout** | A concrete outcome, relevant history, affected behavior and a plan with checks. |
194
+ | **Build** | Tested changes, reviewed decisions and useful context updates. |
195
+ | **Verify** | Current check results, applicable original-code test proof, findings and limits. |
196
+ | **Deliver** | A reviewable result the next person can open, inspect and continue. |
197
+
198
+ Failed checks return to the responsible work within a shared retry budget. Planning, exploration, learning and other tasks use different routes. Supporting skills can work within or across recorded stages; the four-stage route is one use of the full library.
199
+
200
+ ![Full CYC engineering workflow: project knowledge, Scout, Build, Verify, Deliver and the recovery paths between them.](docs/assets/cyc-workflow-diagram.svg)
201
+
202
+ [Open the full-size diagram](docs/assets/cyc-workflow-diagram.svg) · [Step-by-step walkthrough](docs/cyc-workflow.md)
203
+
204
+ <p align="right"><a href="#readme-top">Back to top ↑</a></p>
205
+
206
+ ## Skills
207
+
208
+ CYC exposes **one entry skill, 17 supporting methods, and a frontend design specialization inside Design**. The host assistant reads and performs these skills; each method is a focused procedure, not automatically a separate agent.
209
+
210
+ ### Start with understanding
211
+
212
+ | Skill | What it does and leaves you with |
213
+ | --- | --- |
214
+ | [**Setup**](methods/cyc-setup/SKILL.md) | Discovers the project's real checks, configures CYC and reports setup results and host-activation evidence. |
215
+ | [**Scout**](methods/cyc-scout/SKILL.md) | Makes a focused initial plan: relevant history, files to change, affected consumers and checks to run. |
216
+ | [**Frame**](methods/cyc-frame/SKILL.md) | Clarifies the outcome, scope, acceptance criteria and behavior that must remain intact. |
217
+ | [**Understand**](methods/cyc-understand/SKILL.md) | Traces how the system behaves or reproduces a failure, separating confirmed causes from open hypotheses. |
218
+ | [**Impact**](methods/cyc-impact/SKILL.md) | Finds readers, writers, storage and API consumers a change could affect; records risks, evidence and verification needs. |
219
+
220
+ ### Choose and deliver the change
221
+
222
+ | Skill | What it does and leaves you with |
223
+ | --- | --- |
224
+ | [**Explore**](methods/cyc-explore/SKILL.md) | Compares genuinely different approaches or scoped prototypes, then recommends one with trade-offs and limits. |
225
+ | [**Design**](methods/cyc-design/SKILL.md) | Defines state, interfaces, compatibility and implementation slices, including the observations that would invalidate the approach. |
226
+ | [**Challenge**](methods/cyc-challenge/SKILL.md) | Tests a plan, change or claim against concrete counter-cases and returns supported, actionable findings. |
227
+ | [**Build**](methods/cyc-build/SKILL.md) | Implements tested slices, reviews the diff and records changed behavior and deviations from the plan. |
228
+ | [**Verify**](methods/cyc-verify/SKILL.md) | Exercises the promised behavior, affected consumers and relevant rejection/recovery paths; retains current evidence and unresolved findings. |
229
+ | [**Deliver**](methods/cyc-deliver/SKILL.md) | Produces the final handoff: result, check evidence, a useful visual, working scope and honest limits. |
230
+
231
+ **[Frontend design](methods/cyc-design/frontend-design/SKILL.md)** specializes web work within this flow: concrete design decisions, meaningful visual material, a rendered signature section, desktop/phone review and executed usability/access checks. Its visual judgment remains review work; a passing build cannot establish design quality.
232
+
233
+ ### Continuity, learning and correction
234
+
235
+ | Skill | What it does and leaves you with |
236
+ | --- | --- |
237
+ | [**Context**](methods/cyc-context/SKILL.md) | Retrieves and revalidates component knowledge, then retains verified findings and relevant decisions in indexed project notes. |
238
+ | [**Remember**](methods/cyc-remember/SKILL.md) | Keeps task decisions and checkpoints, and reconstructs what was decided, why and what comes next after interruption. |
239
+ | [**Error Ledger**](methods/cyc-error-ledger/SKILL.md) | Makes failure history searchable: hypotheses, attempted fixes, outcomes, confirmed causes and regression evidence. |
240
+ | [**Correct**](methods/cyc-correct/SKILL.md) | Turns feedback or repeated misses into an explicit missing criterion, a targeted repair and renewed checks. |
241
+ | [**Reflect**](methods/cyc-reflect/SKILL.md) | Uses completed outcomes to propose specific improvements to methods or checks, with evidence for each proposal. |
242
+ | [**Teach**](methods/cyc-teach/SKILL.md) | Explains a concept through the learner's own code, using worked examples and optional practice. |
243
+
244
+ **Context** preserves component knowledge; **Remember** preserves task continuity; **Reflect** proposes improvements to the working method. They serve different needs.
245
+
246
+ [Full method map and examples →](docs/cyc-method-map.md)
247
+
248
+ <a id="example-tasks"></a>
249
+
250
+ ## Playbooks
251
+
252
+ A playbook gives a task its sequence and completion criteria. **Describe the outcome through `/cyc`; you do not need to memorize these route names.**
253
+
254
+ | Playbook | Use it to… |
255
+ | --- | --- |
256
+ | [**Investigation**](skills/cyc/references/playbooks/investigation.md) | Explain a behavior or cause from evidence and recommend a next step without changing the product. |
257
+ | [**Explore**](skills/cyc/references/playbooks/explore.md) | Compare approaches or scoped prototypes before committing to a direction. |
258
+ | [**Plan**](skills/cyc/references/playbooks/plan.md) | Break a substantial change into verifiable units, with dependencies, design decisions and risks. |
259
+ | [**Feature**](skills/cyc/references/playbooks/feature.md) | Build new or changed behavior and verify its affected consumers. |
260
+ | [**Bug fix**](skills/cyc/references/playbooks/bug-fix.md) | Reproduce a defect, repair its cause and establish regression evidence. |
261
+ | [**Refactor**](skills/cyc/references/playbooks/refactor.md) | Improve structure while proving preserved behavior. |
262
+ | [**Performance**](skills/cyc/references/playbooks/performance.md) | Establish a measured baseline, target a bottleneck and check the resulting change. |
263
+ | [**Review**](skills/cyc/references/playbooks/review.md) | Assess existing work and return supported findings worth acting on. |
264
+ | [**Verify**](skills/cyc/references/playbooks/verify.md) | Evaluate an executable result against explicit criteria and current evidence. |
265
+ | [**Experience**](skills/cyc/references/playbooks/experience.md) | Explore a direction, build the change and verify the connected user journey. |
266
+ | [**Teach**](skills/cyc/references/playbooks/teach.md) | Learn a concept through the project's actual code, examples and suitable practice. |
267
+ | [**Handoff**](skills/cyc/references/playbooks/handoff.md) | Prepare current state, evidence, decisions and limits for another person or agent. |
268
+ | [**Resume**](skills/cyc/references/playbooks/resume.md) | Reconstruct interrupted work, check for drift and identify the next justified step. |
269
+ | [**Reflect**](skills/cyc/references/playbooks/reflect.md) | Turn finished outcomes into evidence-backed proposals for improving future work. |
270
+ | [**Evaluate**](skills/cyc/references/playbooks/evaluate.md) | Compare a workflow against a baseline using recorded outcomes and disclosed limits. |
271
+
272
+ <details>
273
+ <summary><strong>See every recorded route</strong></summary>
274
+
275
+ | Playbook | Recorded stages |
276
+ | --- | --- |
277
+ | `investigation` | Scout → Deliver |
278
+ | `explore` | Frame → Understand → Explore → Challenge → Deliver |
279
+ | `plan` | Frame → Understand → Impact → Design → Challenge → Deliver |
280
+ | `feature` | Scout → Build → Verify → Deliver |
281
+ | `bug-fix` | Scout → Build → Verify → Deliver |
282
+ | `refactor` | Scout → Build → Verify → Deliver |
283
+ | `performance` | Scout → Build → Verify → Deliver |
284
+ | `review` | Scout → Challenge → Verify → Deliver |
285
+ | `verify` | Scout → Verify → Deliver |
286
+ | `experience` | Scout → Explore → Build → Verify → Deliver |
287
+ | `teach` | Frame → Understand → Teach → Deliver |
288
+ | `handoff` | Understand → Verify → Deliver |
289
+ | `resume` | Remember → Understand → Deliver |
290
+ | `reflect` | Remember → Reflect → Deliver |
291
+ | `evaluate` | Frame → Understand → Explore → Verify → Reflect → Deliver |
292
+
293
+ These sequences come from the [playbook catalog](catalog/playbooks.json). A stage may use additional supporting methods as the task warrants. The controller records and validates handoffs; it does not automatically launch the skills or establish that the assistant performed them well.
294
+
295
+ </details>
296
+
297
+ ### Try a different kind of task
298
+
299
+ ```text
300
+ /cyc Review this diff for API compatibility, error handling and affected consumers.
301
+ Explain the evidence behind the findings. No edits.
302
+ ```
303
+
304
+ ```text
305
+ /cyc Improve this site's complete signup journey. Establish a visual direction,
306
+ build a usable mobile layout, and check keyboard, validation and recovery states.
307
+ ```
308
+
309
+ Progress updates explain consequential decisions. Final summaries stay brief and link to detailed 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)
310
+
311
+ <p align="right"><a href="#readme-top">Back to top ↑</a></p>
312
+
313
+ ## Validation status
314
+
315
+ CYC combines instructions the assistant follows with code that checks recorded work.
316
+
317
+ | Area | What is established |
318
+ | --- | --- |
319
+ | **Automated checks** | Exercise controller behavior, original-code test proof, recovery, context and installation. The CI badge links to current results. |
320
+ | **Host adapters** | Hook tests use simulated events. Actual prompt/Stop behavior needs confirmation in a fresh host session. |
321
+ | **Distribution** | One npm/plugin archive supports project installation and native host discovery. Registry commands require a published version; public directory listings and native-host qualification are separate release steps. |
322
+
323
+ Inspect the methods, `.cyc/config.json` and local `.cyc/runs/` records. Current source hashes and passing commands do not prove every dependency was found or every check was sufficient. These are workflow guardrails, not a security sandbox, tamper-proof attestation or permission to merge or deploy.
324
+
325
+ Before a team rollout, use a fixed revision and a representative task; inspect the work and a fresh-chat or teammate handoff. Speed, token savings and universal reliability are not established.
326
+
327
+ [Validation details →](docs/validation.md)
328
+
329
+ ## Documentation
330
+
331
+ | I want to… | Guide |
332
+ | --- | --- |
333
+ | Inspect all skills and routes | [Method map](docs/cyc-method-map.md) · [Playbook catalog](catalog/playbooks.json) |
334
+ | Install, update or remove CYC | [Installation](docs/installation.md) |
335
+ | Configure checks or recover interrupted work | [Onboarding and recovery](docs/onboarding-recovery.md) |
336
+ | Share project knowledge | [Context engineering](docs/context.md) |
337
+ | Build a usable frontend | [Frontend design](methods/cyc-design/frontend-design/SKILL.md) |
338
+ | Reuse checks and recipes | [Project tools](docs/project-tools.md) |
339
+ | Inspect the controller and contracts | [Runtime](docs/runtime.md) · [Skill contract](docs/skill-contract.md) |
340
+
341
+ [Browse all documentation →](docs/README.md)
342
+
343
+ ## Contribute
344
+
345
+ Have a reproducible bug or an idea? [Open an issue](https://github.com/TheDThompsonDev/cyc-stack/issues) with the host, Node version, steps and observed result.
346
+
347
+ For source changes, run:
348
+
349
+ ```sh
350
+ node --test
351
+ npm run check:distribution
352
+ ```
353
+
354
+ 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)
355
+
356
+ ## License
357
+
358
+ Distributed under the [MIT License](LICENSE).
359
+
360
+ <p align="right"><a href="#readme-top">Back to top ↑</a></p>