cyc-stack 0.8.3 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/README.md +25 -254
- package/bin/cyc.mjs +30 -7
- package/docs/assets/cyc-method-library.svg +1 -39
- package/docs/assets/cyc-overview.svg +1 -44
- package/docs/assets/cyc-workflow-diagram.svg +1 -415
- package/docs/context.md +6 -0
- package/docs/cyc-workflow.md +31 -84
- package/docs/installation.md +66 -124
- package/docs/onboarding-recovery.md +31 -37
- package/docs/project-tools.md +2 -0
- package/docs/response-standard.md +8 -0
- package/docs/runtime.md +22 -108
- package/docs/skill-contract.md +13 -56
- package/docs/task-context.md +56 -0
- package/docs/validation.md +2 -0
- package/methods/cyc-build/SKILL.md +8 -53
- package/methods/cyc-context/SKILL.md +2 -0
- package/methods/cyc-deliver/SKILL.md +6 -42
- package/methods/cyc-scout/SKILL.md +1 -1
- package/methods/cyc-setup/SKILL.md +7 -19
- package/package.json +6 -1
- package/plugin.json +1 -1
- package/scripts/catalog.mjs +9 -2
- package/scripts/codex-host.mjs +178 -0
- package/scripts/context-review.mjs +13 -3
- package/scripts/delegation.mjs +156 -0
- package/scripts/onboarding.mjs +14 -1
- package/scripts/project-tools.mjs +26 -5
- package/scripts/recovery.mjs +20 -1
- package/scripts/response-mode.mjs +8 -0
- package/scripts/runtime.mjs +169 -6
- package/scripts/swarm.mjs +154 -0
- package/scripts/task-context.mjs +164 -0
- package/skills/cyc/SKILL.md +6 -0
package/docs/context.md
CHANGED
|
@@ -8,6 +8,8 @@ Read docs/context/INDEX.md, then matched records and relevant error history. Rev
|
|
|
8
8
|
|
|
9
9
|
Scout/Start plans canonical records and representative entrypoints before scope freezes. Finish prepares/validates authored knowledge, History/source evidence and index before final checks. Missing/stale context returns needs-context with remaining input; fill learning.context or use context prepare --run ID for earlier feedback. Explicit restrictions remain pending without unauthorized writes. See the [Context method](../methods/cyc-context/SKILL.md) for schemas, fixed layout and recovery.
|
|
10
10
|
|
|
11
|
+
Context-only upkeep can bind unchanged implementation files from its focused owner's Covers. Missing anchors remain pending; self/index hashes and unrelated source cannot substitute. Completion guidance retains the exact remaining input and owned command.
|
|
12
|
+
|
|
11
13
|
```text
|
|
12
14
|
node bin/cyc.mjs investigate --path src/orders
|
|
13
15
|
node bin/cyc.mjs context lint
|
|
@@ -22,3 +24,7 @@ Installed projects use .cyc/engine/bin/cyc.mjs. Read-only inspection executes no
|
|
|
22
24
|
Lint validates structure, mapping and supported freshness, not semantic truth or adoption. Optional manifests bind selected bytes, not complete dependencies. Context measure counts unique selected local files, estimates tokens as Unicode characters/4 and cannot see chat usage, billing or savings. Run records are not transcripts and may exist only in ignored local storage.
|
|
23
25
|
|
|
24
26
|
To evaluate actual reuse, give a fresh chat/teammate a related bounded task without the original conversation; observe discovery, reading, revalidation and successful use with real checks. Record missed/stale guidance. Parser/fixture passes alone do not establish future model quality or measured workflow savings.
|
|
27
|
+
|
|
28
|
+
## Consolidate delegated findings
|
|
29
|
+
|
|
30
|
+
[Task context](task-context.md) reconciles read-only worker evidence into one parent document and feeds existing canonical feature owners before checks. It creates no permanent worker context documents and waives no retention, proof or freshness requirement.
|
package/docs/cyc-workflow.md
CHANGED
|
@@ -1,21 +1,11 @@
|
|
|
1
1
|
# CYC engineering workflow: decisions, evidence, and recovery
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[Workflow](assets/cyc-workflow-diagram.svg), [overview](assets/cyc-overview.svg), [17-method map](assets/cyc-method-library.svg) and [method roles](cyc-method-map.md) cover **Scout → Build → Verify → Deliver**. Twelve responsibilities sit inside these stages. Other routes use the [catalog](../catalog/playbooks.json); Teach adds requested lessons.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
The common implementation route does not show the entire library. See the [full map of all 17 methods](assets/cyc-method-library.svg) and [method roles, examples and routing limitations](cyc-method-map.md), including Setup, Remember, Explore, Correct and Reflect. CYC has 15 playbooks; planning, exploration, teaching, resumption and evaluation use other recorded sequences.
|
|
8
|
-
|
|
9
|
-
CYC moves work forward when the next stage has usable evidence. A failure sends work back to the earliest affected decision, so the agent can repair the cause and regenerate the conclusions that depended on it. The engineer should be able to inspect both the change and the reasoning for taking that route.
|
|
10
|
-
|
|
11
|
-
This document describes the current local implementation and its method instructions for the common feature, bug-fix, and refactor routes. The controller records **Scout → Build → Verify → Deliver**. The twelve responsibilities below occur inside those stages; they are not twelve machine-enforced states. Other routes use the [playbook catalog](../catalog/playbooks.json).
|
|
12
|
-
|
|
13
|
-
**Read the boundaries literally:** the agent investigates, explains, chooses checks, and judges meaning. The controller validates recorded fields, stage identity, covered file state, configured command results, and budgets. A required evidence field does not prove the evidence is true.
|
|
5
|
+
Explain consequential behavior. Agents investigate/judge; the controller checks records, stages, files, commands and failure limits. Fields, hashes and green commands certify no truth/comprehension. SVGs ship; bitmap/HTML exports and docs/maintainers/cyc-workflow-reference.md stay source-only.
|
|
14
6
|
|
|
15
7
|
## 1. The engineering path
|
|
16
8
|
|
|
17
|
-
Each box describes work and the evidence it produces. The separate recovery map below explains backward movement; those returns are deliberately not repeated across this entire diagram.
|
|
18
|
-
|
|
19
9
|
```mermaid
|
|
20
10
|
flowchart TB
|
|
21
11
|
subgraph SC["SCOUT — establish what must change and what must remain true"]
|
|
@@ -63,59 +53,43 @@ flowchart TB
|
|
|
63
53
|
DC --> OUT["Ready handoff when completion and delivery checks pass<br/>Team review and publication follow project authorization"]
|
|
64
54
|
```
|
|
65
55
|
|
|
66
|
-
|
|
56
|
+
Record attempts when they happen. Steps 8/9 can interleave, but finish authorized source, context/index and ledger edits before final executable checks. Missing prerequisites remain blockers.
|
|
67
57
|
|
|
68
58
|
### Scout: why these seven responsibilities precede implementation
|
|
69
59
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
**5. Trace impact and choose the design.** Follow the affected input through state, services, interfaces, persistence, and readers that exist in the project. Name the consumers whose behavior must remain consistent, then select reuse, extension, repair, or new construction with a reason. Pair each consumer with a behavior check. An affected area is a verification concern, not permission to broaden the feature. Explain where the change belongs and why an alternative would create a consequential cost or risk.
|
|
79
|
-
|
|
80
|
-
**6. Explain the causal path and resolve decisions.** Connect observed behavior to the mechanism producing it, then explain what will change and what must remain true. Ask only when an unresolved answer changes the solution. A settled request can be recorded as clear; confirmed alignment requires actual confirmation. The controller rejects a passing Scout assessment marked needs-input. Supplying an explanation does not establish comprehension, and silence does not establish approval.
|
|
81
|
-
|
|
82
|
-
**7. Plan slices that can be evaluated.** Sequence implementation around observable behavior, not a list of arbitrary files. Identify how the first slice can fail, how later slices depend on it, and what broader checks will cover the result. For high-risk work, challenge consequential assumptions and revise the plan if evidence defeats them. This is method guidance inside Scout; the runtime does not independently judge the plan or enforce a separate Challenge state for the fast routes. Explain the dependency that determines the sequence.
|
|
60
|
+
1. **Define success.** Preserve observable outcomes, constraints, exclusions and criterion IDs; explain what checks distinguish. Criteria quality needs judgment.
|
|
61
|
+
2. **Choose route/risk treatment.** Select playbook and meaningful checks before start; captured config is protected. Match review depth to changed behavior; challenge high-risk assumptions.
|
|
62
|
+
3. **Retrieve history.** Read index, matched records, capabilities and ledger. Cite applicable decisions/failures or their absence.
|
|
63
|
+
4. **Revalidate.** Compare claims with current code/revisions/dirty files. Retain file evidence, freshness reasoning, contradictions and unknowns.
|
|
64
|
+
5. **Trace/design.** Follow writers, state, services, persistence and readers. Name consumers/checks and justify reuse/extension/repair/creation. Impact grants no broader authority.
|
|
65
|
+
6. **Settle decisions.** Explain behavior, mechanism, change and invariants. Ask consequential questions only. Clear requests need no invented approval; confirmation needs actual confirmation. needs-input cannot pass Scout. Silence is not approval.
|
|
66
|
+
7. **Plan slices.** Sequence observable outcomes, failures, dependencies and checks. Challenge defeated high-risk premises; fast routes add no Challenge state.
|
|
83
67
|
|
|
84
68
|
### Build: keep changes and explanations connected
|
|
85
69
|
|
|
86
|
-
|
|
70
|
+
8. **Tested slices.** Reproduce bugs, characterize refactors and exercise feature outcomes; prove relevant original behavior. Use existing checks/reasoned exemption when no new testable behavior exists. Inspect diffs/consumers, diagnose failures and ledger actual attempts/results. Explain affected state/interface and repair location.
|
|
71
|
+
9. **Knowledge.** Plan required component owners/index before Build. Retain capability, contracts, adopted decisions, evidenced failures, dependencies, checks and issues. Preserve/supersede history explicitly and bind paths/current files, including dirty evidence.
|
|
87
72
|
|
|
88
|
-
|
|
73
|
+
docs/context/<area>.md holds component reasoning; docs/context/INDEX.md maps paths/freshness; the ledger holds failures/causes. Name by component, not task/chat. Keep hypotheses pending; adoption needs acceptance. No filler/generic waiver of feature retention. Explain retrieval/revalidation. Deliver records disposition, not source edits.
|
|
89
74
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
| Output | What it preserves | How subsequent work uses it |
|
|
93
|
-
| --- | --- | --- |
|
|
94
|
-
| `docs/context/<area>.md` | Why the component behaves this way, what failed, dependencies, checks and known limits | Step 3 retrieves the matching document; step 4 checks its freshness against the current code |
|
|
95
|
-
| `docs/context/INDEX.md` | Component/area, covered paths, document location, reviewed revision and a short summary | Locates relevant history from the files being changed |
|
|
96
|
-
| Selected error ledger | Failed attempts, observed results and confirmed causes | Supplies failure evidence that component entries can reference without duplicating the entire log |
|
|
97
|
-
|
|
98
|
-
For example, an export-component entry could preserve why exports query all authorized matching records rather than the current UI page, the failed page-state approach and its evidence, and the regression check covering pagination. This is an illustrative entry, not a claim about this project's components.
|
|
99
|
-
|
|
100
|
-
Finish authorized durable context/index and ledger edits before final verification because those files belong to the candidate being checked. Retain useful verified technical facts with their evidence and limits. Keep unverified hypotheses and undecided proposals explicitly pending; mark a decision adopted only with actual acceptance. Do not create filler documents when there is no reusable finding. Explain the retained reasoning and how a future engineer would locate and revalidate it. Deliver records this disposition; it is not a second opportunity to mutate verified source. The existing component-context method and templates define this responsibility; the diagram does not add a new runtime state or claim the controller proves documentation quality.
|
|
75
|
+
[Task delegation](task-context.md) preserves parent authority and one document; worker results cannot replace parent proof/review/checks/retention.
|
|
101
76
|
|
|
102
77
|
### Verify: require both executed behavior and explained judgment
|
|
103
78
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
**11. Review whether the implementation means the right thing.** Review the current diff for intent, affected consumers, and project conventions. Tests can pass while encoding an incomplete assumption, missing a consumer, or accepting the wrong behavior. Record findings as resolved or dismissed with evidence; open findings prevent a passing assessment. Every consumer named in Scout needs passing evidence; newly discovered consumers also belong in the review. Label self-review and peer review accurately. Explain the consequence of a finding and why its resolution addresses that consequence. Required fields make the judgment inspectable, not independently true.
|
|
79
|
+
10. **Prove/verify.** Changed feature/bug tests must fail on originals; refactor characterization must pass. Classify interface/setup/behavior honestly; exemptions retain reasons/limits. Run relevant journeys/recipes, negatives and all configured commands. Map criteria/consumers. Receipts bind arguments/status/output/source; failure/drift rejects passing verification. Explain omissions.
|
|
80
|
+
11. **Review meaning.** Inspect intent/consumers/conventions in the current diff. Resolve/dismiss findings with evidence; open findings block. Evidence every Scout consumer and add discoveries. Label self/fresh/peer provenance.
|
|
107
81
|
|
|
108
82
|
### Deliver: expose the basis for acceptance
|
|
109
83
|
|
|
110
|
-
|
|
84
|
+
12. **Account for outcomes.** Record criteria, limits, learning/history; bugs/failures require the ledger. Reuse the review; Deliver needs current executable/semantic evidence. Completion rechecks conditions/artifacts. Supply mechanism, trade-offs, checks and maintenance pointers. Publication needs authorization.
|
|
111
85
|
|
|
112
|
-
|
|
86
|
+
run start can record Scout; run finish can combine Build, proof/judgment, verification, Verify/Deliver and completion. Sharing local evidence needs authorization.
|
|
113
87
|
|
|
114
|
-
|
|
88
|
+
An active host hook separately checks readiness/session runs. Ready delivery needs completion; blocked/exhausted work allows honest blocked handoffs, never concealed running work. Native Codex/Claude Stop supplies reply text; finish may write request-bound evidence. Cursor needs the exact-response packet. Follow [response rules](response-standard.md#engineering-understanding-throughout-the-work), actual capability/current hook context. Files/simulations prove no activation.
|
|
115
89
|
|
|
116
90
|
## 2. Why the process loops, and why the return destination matters
|
|
117
91
|
|
|
118
|
-
|
|
92
|
+
Preserve results; confirm intended build, data and requirement.
|
|
119
93
|
|
|
120
94
|
```mermaid
|
|
121
95
|
flowchart TB
|
|
@@ -132,57 +106,30 @@ flowchart TB
|
|
|
132
106
|
T --> RE
|
|
133
107
|
```
|
|
134
108
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
| Evidence that changes the route | Why the return is necessary | What must be established again |
|
|
138
|
-
| --- | --- | --- |
|
|
139
|
-
| A correctly specified export omits the last page because its loop stops early | The design still works; a local implementation violates it | The failing pagination case, affected consumers, current configured checks and review |
|
|
140
|
-
| Export reuses a UI-only filter while server access rules differ | The design relied on the wrong source of truth; another patch to pagination cannot repair that premise | Relevant context and impact, design rationale, access consumers, implementation and verification |
|
|
141
|
-
| A passing review is followed by another covered source edit | The old result describes different bytes | Executed checks and semantic review for the new candidate |
|
|
142
|
-
| A check hits an old build or asserts the wrong requirement | The observation cannot support the intended conclusion | Correct target or justified assertion and a fresh result; do not simply lower the threshold |
|
|
143
|
-
| A required service or decision is unavailable | More code cannot supply the missing prerequisite | An honest blocker and the smallest needed input; verification after work resumes |
|
|
144
|
-
|
|
145
|
-
When a legitimate correction requires changing protected verification configuration or run criteria, explain it and start a new authorized run while retaining the old outcome. Do not weaken the current run to pass.
|
|
109
|
+
These are destinations, not mandatory restarts. Before passed Verify, repair may stay active. Recorded returns use run retry, invalidating dependent handoffs/verification. Post-Verify edits require Verify plus fresh checks/review. Fast routes map impact/design returns to Scout. Re-establish affected source/consumer/check/review evidence.
|
|
146
110
|
|
|
147
|
-
|
|
111
|
+
Protected criteria/config changes need explained, authorized new runs retaining old outcomes; never weaken the active run. Record/verify/retry/resume/complete guards halt on protected/out-of-scope changes, preserving files without rollback or continuous monitoring. Halted/exhausted runs are terminal. Blocked work may resume after resolution within guards/remaining allowance; halted work needs resolved scope/authority before a new run.
|
|
148
112
|
|
|
149
|
-
|
|
113
|
+
Defaults share three failures/two unchanged repeated signatures across stages; returns never reset them. No-progress detection is heuristic.
|
|
150
114
|
|
|
151
115
|
### A worked example: why going back to Scout is sometimes essential
|
|
152
116
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
The request is to export every order matching the dashboard filters while preserving access restrictions. The initial plan assumes the browser holds the complete filtered result. A multiple-page test shows that only the visible page reaches the export.
|
|
156
|
-
|
|
157
|
-
If the server already provides the correct complete query and the export loop stops early, the repair belongs in implementation. If the browser only ever receives one page and applies different filtering from the server, the assumption behind the design is false. Return to Scout, inspect the authoritative query and access boundary, revise the impact map, and choose the correct data path before rebuilding.
|
|
158
|
-
|
|
159
|
-
The explanation to the engineer should identify that distinction: “The browser only has one page, so formatting its rows cannot produce the requested export. We need the server's filtered query, with the same access restriction, and checks for both multiple pages and denied access.” The ledger retains the failed browser-only attempt and its evidence so the next task does not repeat it.
|
|
117
|
+
Illustrative export: an early loop exit needs Build repair; a browser holding one page/different filters defeats the design. Revisit Scout/query/access, rebuild and check pagination/denied access. Explain absent-record limits and retain the failure.
|
|
160
118
|
|
|
161
119
|
## 3. What an engineering team can inspect before trusting a result
|
|
162
120
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
| Claim presented to the team | Current mechanism and inspectable record | Boundary of that assurance |
|
|
166
|
-
| --- | --- | --- |
|
|
167
|
-
| The delivered change addresses the agreed criteria | Every handoff preserves criterion IDs; passing Verify and Deliver require all criterion results passed with evidence | The agent and engineer must choose meaningful criteria and judge the supplied evidence |
|
|
168
|
-
| The result still covers the candidate being handed over | Covered source fingerprints, referenced artifact hashes, verification receipts, and a semantic-review source snapshot are rechecked | Coverage has documented exclusions; external services and omitted dependencies are not frozen by a file hash |
|
|
169
|
-
| Green commands cannot replace reviewing the change | Required intent/consumer/convention assessment; open findings and missing Scout consumer checks reject a passing handoff | Review and consumer evidence are agent-reported; this is not automatic dependency discovery or independent approval |
|
|
170
|
-
| A failed attempt cannot be silently turned into completed work through ordinary controller operations | Shared failure budget, retry history, invalidated dependent handoffs, stage/attempt identity, terminal outcomes | Local records are editable; unreported agent actions are invisible to the controller |
|
|
171
|
-
| The reasoning remains available after the conversation | Matched context references, selected error ledger, pending/recorded learning disposition, generated review | The agent must write accurate history, and acceptance must be real |
|
|
172
|
-
| The engineer can follow and maintain the change | Stage-specific explanation responsibilities and qualitative delivery review | This is instruction-level behavior; there is no automated comprehension measurement |
|
|
173
|
-
|
|
174
|
-
The useful question for a reviewer is: **“What evidence supports this claim, does it still describe these files, and what has not been established?”** A diagram, an agent's confidence, or a successful exit code alone cannot answer that.
|
|
121
|
+
Ask **what supports this claim, does it describe these files, and what remains unestablished?** Inspect criteria/results, hashes/receipts/external and excluded inputs, intent/consumer/convention findings, limits/retries/outcomes, context/ledger/learning and explanation. Editable reports cannot reveal concealed actions or certify independent approval/comprehension. Adoption needs evidence.
|
|
175
122
|
|
|
176
|
-
|
|
123
|
+
Inspect [assessment validation](../scripts/work-review.mjs), [runtime](../scripts/runtime.mjs), [source coverage](../scripts/source-snapshot.mjs) and [session rules](../scripts/run-gate.mjs). Source regressions: test/work-review.test.mjs and test/runtime-adversarial.test.mjs; names are not results.
|
|
177
124
|
|
|
178
125
|
## Regenerating the diagram
|
|
179
126
|
|
|
180
|
-
In
|
|
127
|
+
In source, npm install (or npm ci), then npm run build:workflow uses dev-only sharp for PNG/SVG/HTML previews and twelve titles. Missing renderer/HTML marker/title fails before updates. Fonts vary by machine; same-machine repeats should agree. Installed CYC needs no authoring dependency.
|
|
181
128
|
|
|
182
129
|
## Supporting references and earlier overview
|
|
183
130
|
|
|
184
|
-
- [Runtime
|
|
185
|
-
- [
|
|
186
|
-
- [Impact
|
|
187
|
-
- [
|
|
131
|
+
- [Runtime](runtime.md)
|
|
132
|
+
- [Assessments](work-assessments.md)
|
|
133
|
+
- [Impact](impact-analysis.md)
|
|
134
|
+
- [Explanation](response-standard.md#engineering-understanding-throughout-the-work)
|
|
188
135
|
- [Orchestrator](../skills/cyc/SKILL.md), [Build](../methods/cyc-build/SKILL.md), and [Verify](../methods/cyc-verify/SKILL.md)
|
package/docs/installation.md
CHANGED
|
@@ -1,202 +1,144 @@
|
|
|
1
1
|
# Installing CYC in an existing project
|
|
2
2
|
|
|
3
|
-
CYC
|
|
3
|
+
CYC installs project-local skills/engine/hooks, preserving application instructions/package.json/dependencies and unrelated hooks. No global changes or application-script execution. The AI host needs Node.js 20+; applications may use any language.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Follow [INSTALL.md](../INSTALL.md) for the [published npm package](https://www.npmjs.com/package/cyc-stack), route selection and setup request. From the target root:
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
~~~text
|
|
8
|
+
npx cyc-stack@latest init
|
|
9
|
+
~~~
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
Reload and ask /cyc to configure checks; download alone does not activate CYC. From a reviewed checkout:
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
~~~text
|
|
12
14
|
node bin/cyc.mjs init --project "/absolute/path/to/project" --hosts claude,codex,cursor --dry-run
|
|
13
15
|
node bin/cyc.mjs init --project "/absolute/path/to/project"
|
|
14
16
|
node bin/cyc.mjs doctor --project "/absolute/path/to/project"
|
|
15
17
|
node bin/cyc.mjs uninstall --project "/absolute/path/to/project" --dry-run
|
|
16
|
-
|
|
18
|
+
~~~
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
CLI detection uses CLAUDE.md/.claude, AGENTS.md/.agents/.codex and .cursor/.cursorrules; no signals selects all three. --hosts overrides selection. Installed CLI: .cyc/engine/bin/cyc.mjs.
|
|
19
21
|
|
|
20
|
-
|
|
21
|
-
import { installProject, doctorProject, uninstallProject } from './scripts/install.mjs';
|
|
22
|
+
A complete cycstack plugin supplies engine/skills/hooks. cyc activate or /cyc set up this project writes only .cyc/config.json/.cyc/.gitignore. Hooks ignore unactivated projects and defer to project installs.
|
|
22
23
|
|
|
23
|
-
installProject(
|
|
24
|
-
hosts: ['codex', 'claude'],
|
|
25
|
-
dryRun: true,
|
|
26
|
-
});
|
|
27
|
-
installProject('/absolute/path/to/project', { hosts: ['codex', 'claude'] });
|
|
28
|
-
doctorProject('/absolute/path/to/project');
|
|
29
|
-
uninstallProject('/absolute/path/to/project', { dryRun: true });
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
These functions return JSON-friendly objects. Inspect `ok` before proceeding. Installation results include planned `changes`, `conflicts`, `warnings`, and an `error` when applicable. A dry run performs validation and reports changes without writing them. Hosts default to both supported integrations. Adding a host preserves previously installed hosts.
|
|
24
|
+
scripts/install.mjs exports installProject(target,{hosts,dryRun}), doctorProject(target), uninstallProject(target,{dryRun}). API hosts default to codex/claude and retain existing hosts. Inspect JSON ok/changes/conflicts/warnings/error. dryRun validates without writes. Source reference: docs/maintainers/installation-reference.md.
|
|
33
25
|
|
|
34
26
|
## Optional npm controls
|
|
35
27
|
|
|
36
|
-
Interactive
|
|
37
|
-
|
|
38
|
-
Use `--json` for the complete structured installer result. Redirected/piped output remains JSON automatically, preserving existing automation, and `--verbose` retains its existing detailed JSON behavior. Other command output and the installer API are unchanged. For example: `npx cyc-stack@latest init --json`.
|
|
39
|
-
|
|
40
|
-
These options are for specific needs; the normal install requires none of them.
|
|
28
|
+
Interactive init/install shows outcome, project, hosts, changes, warnings/conflicts and next action. Previews/failed plans qualify unapplied migrations; unchanged installs report up to date. --json/--verbose exposes details; piped output stays JSON. Other commands/API stay unchanged.
|
|
41
29
|
|
|
42
30
|
| Need | Command |
|
|
43
31
|
| --- | --- |
|
|
44
|
-
| Preview
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
| Save as a development dependency | `npm install --save-dev cyc-stack`, then `npx cyc-stack init` |
|
|
32
|
+
| Preview | npx cyc-stack@latest init --dry-run |
|
|
33
|
+
| One host | npx cyc-stack@latest init --hosts codex |
|
|
34
|
+
| Exact nested root | npx cyc-stack@latest init --project . |
|
|
35
|
+
| Approved version/channel | npx cyc-stack@0.6.0 init or npx cyc-stack@next init |
|
|
36
|
+
| Dependency | npm install --save-dev cyc-stack; npx cyc-stack init |
|
|
50
37
|
|
|
51
|
-
|
|
38
|
+
@latest selects a tag, not qualification. Unversioned commands may use project packages; --save-exact pins. npm --yes precedes the package name. Reload/trust/check setup still apply.
|
|
52
39
|
|
|
53
40
|
## Agent-guided installation
|
|
54
41
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
1. Read the target project's instructions. Use the requested project and release, whether a published npm version or a supplied reviewed checkout/archive. Do not treat a registry error as permission to alter credentials, visibility or global settings.
|
|
60
|
-
2. Preview with the selected CLI's `init --dry-run`, using `--project` for a different existing target directory. Explain the proposed changes and continue within the user's installation authorization. Resolve reported conflicts without deleting or taking ownership of existing files.
|
|
61
|
-
3. Complete `init`, then follow [project setup](../methods/cyc-setup/SKILL.md). Find checks in the project's CI and configuration, explain which behavior they exercise, and use the project's authorization rules before running them. Do not invent always-passing checks.
|
|
62
|
-
4. Keep installed files, configured checks, executed checks and real host activation distinct. Missing trust or prompt/Stop observations remain unverified. Use supported host controls; never simulate callbacks or edit trust/state to claim activation.
|
|
63
|
-
|
|
42
|
+
1. Read target instructions; use the requested project/reviewed release. Registry errors authorize no credential, visibility or global changes.
|
|
43
|
+
2. Preview init --dry-run with --project when needed. Explain/proceed within installation authorization; resolve conflicts without deleting or claiming existing files.
|
|
44
|
+
3. Install; follow [project setup](../methods/cyc-setup/SKILL.md). Find meaningful CI/config checks, explain coverage and honor execution authorization. No always-passing substitutes.
|
|
45
|
+
4. Distinguish installed files, configured/executed checks and activation. Use supported trust controls; missing prompt/Stop observations stay unverified. Never simulate callbacks or edit trust/state to claim activation.
|
|
64
46
|
|
|
65
|
-
An isolated skill
|
|
47
|
+
An isolated skill lacks its methods/CLI; use the installer or complete qualified plugin.
|
|
66
48
|
|
|
67
49
|
## What is installed
|
|
68
50
|
|
|
69
|
-
|
|
|
51
|
+
| Location | Purpose |
|
|
70
52
|
| --- | --- |
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
53
|
+
| .cyc/engine/ | Runtime/CLI, methods/catalog/docs/skills, compact SVGs and ESLint config |
|
|
54
|
+
| .cyc/config.json | Checks/limits |
|
|
55
|
+
| .cyc/install-manifest.json | Version, ownership hashes/exact hooks |
|
|
56
|
+
| .cyc/.gitignore | Excludes runtime/ and runs/ |
|
|
57
|
+
| .agents/skills/cyc/ | Codex/Cursor entry |
|
|
58
|
+
| .claude/skills/cyc/ | Claude entry |
|
|
59
|
+
| .codex/hooks.json | UserPromptSubmit/Stop |
|
|
60
|
+
| .claude/settings.json | UserPromptSubmit/Stop |
|
|
61
|
+
| scripts/claude-hooks/cyc.mjs | Claude launcher |
|
|
62
|
+
| .cursor/hooks.json | beforeSubmitPrompt/afterAgentResponse/stop |
|
|
63
|
+
| .cursor/rules/cyc-delivery.mdc | Cursor protocol |
|
|
82
64
|
|
|
83
|
-
|
|
65
|
+
package.json selects npm/copied payload; skill links target the engine. Tests/evaluations/reports and bitmap/HTML generators/exports stay source-only. Verification uses project commands.
|
|
84
66
|
|
|
85
|
-
|
|
67
|
+
Defaults: schema 1, no checks, three failures/two consecutive no-progress attempts, no wall-clock deadline. limits.maxDurationMs opts into time bounds. Configure meaningful checks; installation neither guesses/runs unfamiliar scripts nor guarantees success.
|
|
86
68
|
|
|
87
|
-
|
|
69
|
+
Scripts carry eslint-disable after shebangs; ESLint 10's nearest engine config ignores the engine. The Claude launcher avoids static imports/import.meta/top-level await; dynamic import needs ES2020. Comments cannot fix parsing. Project ignores may remain necessary for below-ES2020 script parsers, type-aware linting or unused-disable launcher warnings under --max-warnings 0.
|
|
88
70
|
|
|
89
|
-
|
|
90
|
-
- a linter that parses `.mjs` as a script below ES2020;
|
|
91
|
-
- one that needs type information for every file;
|
|
92
|
-
- `--max-warnings 0` where a file's header suppresses nothing. ESLint reports that as an unused directive; ESLint 10's engine config avoids it for `.cyc/engine` but not for the launcher.
|
|
93
|
-
|
|
94
|
-
Hook commands use `node` on PATH. Claude invokes `node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/cyc.mjs"` through Bash (Git Bash required on Windows). The launcher resolves the engine relative to its own location, preserving nested-directory and relocated-clone behavior. Codex and Cursor retain an inline bootstrap that locates the copied engine from the host event. No installer-specific Node or project paths are embedded. Host trust/reload is still required. `doctor` reports the installed version and checks installed command definitions and file hashes. Tests exercise simulated events, not live host activation. Claude's shell setting follows the [official hook command contract](https://code.claude.com/docs/en/hooks).
|
|
71
|
+
Hooks need node on PATH. Claude uses node "$CLAUDE_PROJECT_DIR/scripts/claude-hooks/cyc.mjs" through Bash (Git Bash on Windows), then relative engine resolution. Codex/Cursor bootstrap from host events. No machine-specific paths; trust/reload remains required. [Claude hook contract](https://code.claude.com/docs/en/hooks).
|
|
95
72
|
|
|
96
73
|
## Updating, conflicts, and removal
|
|
97
74
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
Installation builds and validates the complete operation plan before writing. Ordinary write failures trigger rollback to the previous file contents. This is an in-process rollback, not a filesystem transaction: abrupt termination or power loss can leave a partial operation. Inspect the manifest and run doctor before retrying; do not erase custom files to force an update.
|
|
75
|
+
Reinstall the selected distribution; unchanged files stay untouched. Modified owned skills/engine files cause a no-write conflict: reconcile deliberately. Valid config stays. Obsolete payload is removed only on matching ownership hashes; modified leftovers/records remain and may exceed fresh-install size.
|
|
101
76
|
|
|
102
|
-
|
|
77
|
+
Preflight validates the full plan. Ordinary write failures restore prior bytes; abrupt termination/power loss may leave partial work. Inspect manifest/doctor before retrying; rollback is not a filesystem transaction.
|
|
103
78
|
|
|
104
|
-
|
|
79
|
+
Uninstall removes matching owned files/exact hooks only. Retained/custom/duplicate hooks referencing engine/launcher cause an atomic conflict leaving everything unchanged; adapt deliberately. Other customizations/records remain, including .cyc/.gitignore with records. Tracked files/force-adds are outside that protection. Empty directories may remain; later installs treat unmanaged leftovers as collisions.
|
|
105
80
|
|
|
106
|
-
|
|
81
|
+
Corrupt config, unsafe manifests and destination symlinks/junctions reject before writes. Avoid concurrent integration-file installers/editors.
|
|
107
82
|
|
|
108
83
|
## Activation and diagnosis
|
|
109
84
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
Reload the host and use its hook trust/activation flow where required. Validate a real session with a deliberately invalid response, then a valid review-backed response. Hook tests using simulated events do not establish real-session activation. Skill discovery, plugin command prefixes, and host UI behavior must also be checked in the actual supported host version.
|
|
85
|
+
doctorProject checks Node/config/manifest/hashes/hook structure, not verification or loaded/trusted hooks. Notices distinguish missing, edited and outdated entries; rerun init or retain a deliberate edit with its notice.
|
|
113
86
|
|
|
114
|
-
|
|
87
|
+
Reload/trust exact definitions. Observe fresh prompt state, invalid-response rejection/correction and valid review-backed Stop in the actual host/version/invocation. Installation, simulated callbacks, manual packets or one acceptance prove no other outcome/host. See [validation](validation.md).
|
|
115
88
|
|
|
116
|
-
|
|
89
|
+
onboard --host codex --session ID --token TOKEN uses the current injected token to distinguish pending prompt from accepted Stop. Missing/stale/mismatched observations stay unready despite passing checks. See [setup diagnostics](onboarding-recovery.md) and [OpenAI hooks guidance](https://learn.chatgpt.com/docs/hooks).
|
|
117
90
|
|
|
118
|
-
|
|
91
|
+
Resources include .claude-plugin, root plugin.json/.codex-plugin compatibility/.agents/plugins/marketplace.json, and .cursor-plugin with host-specific hook events/variables. Files/public visibility/manual distribution prove no activation or directory listing. Full CYC includes hooks; fresh native qualification remains pending. [OpenAI distribution limits](https://developers.openai.com/plugins/build/plugins#bundled-mcp-servers-and-lifecycle-hooks) direct directory-excluded hook plugins to manual desktop installation.
|
|
119
92
|
|
|
120
|
-
Cursor
|
|
93
|
+
Cursor prompt cannot inject context; stop lacks reply text. afterAgentResponse captures it, and the rule supplies protocol. Each conversation chooses a tag and writes .cyc/runtime/cursor-<tag>.review.json, token cursor. Freshness after request start/exact reply match isolates parallel chats. Claude/Codex third-party hooks stay silent under Cursor.
|
|
121
94
|
|
|
122
|
-
|
|
95
|
+
Relative commands survive relocation with Node on PATH. Update legacy absolute-command installs once; new machines still need trust/loading.
|
|
123
96
|
|
|
124
97
|
## Impact investigation for this installer
|
|
125
98
|
|
|
126
|
-
|
|
127
|
-
| --- | --- | --- |
|
|
128
|
-
| Existing `.codex/hooks.json` and `.claude/settings.json` | Both call `scripts/response-hook.mjs` with a host argument; add an explicit target root and merge exact owned entries | Seed unrelated hook entries and confirm install/update/uninstall preservation |
|
|
129
|
-
| `scripts/response-hook.mjs` | Runtime previously derived from its source location; portable copies require root resolution independent of engine location | Root coordinator adapts `--project`; integration tests check copied hooks in a temporary target |
|
|
130
|
-
| Skill discovery folders | Copy the same skills for each host; relative documentation links require adjustment | Check installed copies and link targets; do not claim host discovery from file presence |
|
|
131
|
-
| `.cyc/config.json` and ownership manifest | Durable editable config and installation bookkeeping | Invalid schemas, path traversal, file modification, and idempotence tests |
|
|
132
|
-
| Existing `AGENTS.md`, `CLAUDE.md`, package.json | User-owned instructions and application configuration are outside installation scope | Seed content and confirm unchanged bytes |
|
|
133
|
-
| Target filesystem | Partial writes or symlink traversal could damage unrelated files | Up-front collision checks, rollback, temp project tests, junction refusal |
|
|
134
|
-
|
|
135
|
-
The investigated source is the working tree used for this implementation. Host activation and compatibility beyond simulated/file-level checks remain external verification gaps. This installer is a distribution mechanism, not an automatic whole-project dependency analyzer.
|
|
136
|
-
|
|
99
|
+
The source reference holds the full investigation. Temporary-project/simulated tests cover preservation, links, schema/ownership, collision, rollback and linked-path rejection; no live activation/dependency-discovery claim.
|
|
137
100
|
|
|
138
101
|
## Existing project conventions
|
|
139
102
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
After updating, reload the host so the conversation does not mix previously loaded skills with the new engine. For repeatable trials, pin the selected full Git commit in the GitHub install command and record the installed manifest version. Qualify the exact revision used; an older release tag installs the behavior at that tag.
|
|
103
|
+
Keep unrelated Stop hooks. delivery.presentation:"project" delegates formatting but retains completion checks; context.ledgerPath reuses a ledger. Updates preserve valid config, including delivery.defaultCharacterLimitEnabled:false for unlimited new-session replies. Avoid managed-hook edits.
|
|
143
104
|
|
|
105
|
+
Reload to avoid mixed old/new code. Pin/record full commit and manifest version; old tags retain old behavior.
|
|
144
106
|
|
|
145
107
|
## Private repositories and npm Git fetch failures
|
|
146
108
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
Use an authenticated checkout of the desired commit and invoke its installer directly. This avoids npm's GitFetcher entirely. In a separate tools directory, clone once, check out the exact published commit, and record it:
|
|
109
|
+
npm archive auth can differ from Git/gh and return 404/packing errors. Do not change visibility or clear global caches. In a new authenticated clone, stop on failed commands:
|
|
150
110
|
|
|
151
|
-
|
|
111
|
+
~~~text
|
|
152
112
|
gh repo clone TheDThompsonDev/cyc-stack cyc-source
|
|
153
113
|
git -C cyc-source checkout --detach <full-commit-sha>
|
|
154
114
|
git -C cyc-source rev-parse HEAD
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
If any command fails, stop before installing. Use a new clone directory to avoid disturbing existing local work. Then run:
|
|
115
|
+
~~~
|
|
158
116
|
|
|
159
|
-
|
|
160
|
-
node <cyc-checkout>/bin/cyc.mjs init --project <target-project> --dry-run
|
|
161
|
-
node <cyc-checkout>/bin/cyc.mjs init --project <target-project>
|
|
162
|
-
node <target-project>/.cyc/engine/bin/cyc.mjs doctor
|
|
163
|
-
```
|
|
117
|
+
Use that checkout's CLI init --project <target-project> --dry-run, then init and target doctor. Alternatively npm pack --ignore-scripts once, using the same archive from the target root:
|
|
164
118
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
```text
|
|
119
|
+
~~~text
|
|
168
120
|
npm exec --offline --yes --package "/absolute/path/cyc-stack-X.Y.Z.tgz" -- cyc init --dry-run
|
|
169
121
|
npm exec --offline --yes --package "/absolute/path/cyc-stack-X.Y.Z.tgz" -- cyc init
|
|
170
|
-
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
Run these from the target project root. Both preview and installation use the same archive. There are no runtime npm dependencies. Our packaging regression test uses an empty npm cache and offline installation, checking dry-run, install, bundled methods, and doctor.
|
|
174
|
-
|
|
175
|
-
Future tagged releases built with the updated release workflow attach this `.tgz` and `SHA256SUMS`. They can be downloaded through authenticated `gh release download <tag> --repo TheDThompsonDev/cyc-stack --pattern "*.tgz" --pattern SHA256SUMS`. Compare the archive's SHA-256 with the downloaded checksum before installation. This is an integrity check, not an independent signature. These assets do not exist until that release workflow runs; no release was published by this repair.
|
|
176
|
-
|
|
177
|
-
Keep custom preferences in `.cyc/config.json`. For example, `"delivery": { "defaultCharacterLimitEnabled": false }` preserves an unlimited new-session default without editing managed hook files. Back up and reconcile existing managed-file modifications before updating; the installer intentionally refuses to overwrite them.
|
|
122
|
+
~~~
|
|
178
123
|
|
|
124
|
+
No runtime npm dependencies. Tagged workflows attach .tgz/SHA256SUMS only after running; fetch with gh release download <tag> --repo TheDThompsonDev/cyc-stack --pattern "*.tgz" --pattern SHA256SUMS. Compare SHA-256: integrity, not independent signature. Reconcile managed customizations before updates.
|
|
179
125
|
|
|
180
126
|
## One public entry point
|
|
181
127
|
|
|
182
|
-
Use
|
|
183
|
-
|
|
184
|
-
An update removes unchanged CYC-owned legacy supporting entries from `.claude/skills` and `.agents/skills`. Customized legacy entries cause an atomic conflict so their changes can be preserved and deliberately migrated; unrelated user skills are untouched. Reload the host after updating to remove previously loaded menu entries. Live menu rendering still requires host verification.
|
|
128
|
+
Use /cyc (possibly /cycstack:cyc) for tasks/setup. Only the parent skill is discoverable; .cyc/engine/methods loads by path.
|
|
185
129
|
|
|
130
|
+
Updates remove unchanged legacy skills. Customized .claude/skills/.agents/skills entries require atomic conflict resolution and deliberate migration; unrelated skills stay. Reload clears old entries; actual menus need host verification.
|
|
186
131
|
|
|
187
132
|
<a id="npm-publication-preparation"></a>
|
|
188
133
|
|
|
189
134
|
## npm publication maintenance
|
|
190
135
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
The source workflow `.github/workflows/publish-npm.yml` is manually invoked for an existing release tag and defaults to the `next` channel. It uses Node 24, validates publishing-tool versions, runs tests, packs the candidate and uses npm OIDC. Package ownership, the exact npm trusted-publisher repository/workflow/environment binding and any required `npm-publish` environment reviewers must be configured by the maintainer. The repository is public; registry publication still requires an authorized npm account. This preparation does not publish anything. Registry install examples require an actual published release.
|
|
194
|
-
|
|
136
|
+
Source-only publishing is not consumer setup. npm run check:distribution validates metadata/optional tag versions. Manual publish-npm.yml uses Node 24, validates tools, tests/packs and npm OIDC. Maintainers authorize ownership, exact trusted-publisher repository/workflow/environment binding and npm-publish reviewers.
|
|
195
137
|
|
|
196
|
-
|
|
138
|
+
Dispatch with matching existing input tag, event SHA/ref and checkout HEAD:
|
|
197
139
|
|
|
198
|
-
|
|
140
|
+
~~~text
|
|
199
141
|
gh workflow run publish-npm.yml --ref v0.6.0 -f tag=v0.6.0 -f channel=next
|
|
200
|
-
|
|
142
|
+
~~~
|
|
201
143
|
|
|
202
|
-
|
|
144
|
+
Default next; authorized npm account/published release required. Preparation publishes nothing.
|