cyc-stack 0.0.0-stage → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/.agents/plugins/marketplace.json +12 -0
  2. package/.claude-plugin/marketplace.json +14 -0
  3. package/.claude-plugin/plugin.json +17 -0
  4. package/.codex-plugin/plugin.json +33 -0
  5. package/.cursor-plugin/marketplace.json +13 -0
  6. package/.cursor-plugin/plugin.json +19 -0
  7. package/INSTALL.md +153 -0
  8. package/LICENSE +21 -0
  9. package/README.md +436 -2
  10. package/bin/cyc.mjs +294 -0
  11. package/catalog/playbooks.json +20 -0
  12. package/docs/README.md +30 -0
  13. package/docs/assets/cyc-method-library.svg +39 -0
  14. package/docs/assets/cyc-overview.svg +44 -0
  15. package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
  16. package/docs/assets/cyc-readme-banner.svg +39 -0
  17. package/docs/assets/cyc-workflow-diagram.svg +415 -0
  18. package/docs/code-quality.md +42 -0
  19. package/docs/context.md +40 -0
  20. package/docs/cyc-method-map.md +58 -0
  21. package/docs/cyc-workflow.md +188 -0
  22. package/docs/engineering/code-standards.md +103 -0
  23. package/docs/engineering/domain-design.md +81 -0
  24. package/docs/engineering/failure-handling.md +105 -0
  25. package/docs/impact-analysis.md +70 -0
  26. package/docs/installation.md +198 -0
  27. package/docs/onboarding-recovery.md +75 -0
  28. package/docs/principles.md +49 -0
  29. package/docs/project-tools.md +108 -0
  30. package/docs/response-standard.md +202 -0
  31. package/docs/runtime.md +249 -0
  32. package/docs/skill-contract.md +70 -0
  33. package/docs/skill-craft.md +23 -0
  34. package/docs/validation.md +39 -0
  35. package/docs/work-assessments.md +180 -0
  36. package/hooks/claude.json +10 -0
  37. package/hooks/codex.json +28 -0
  38. package/hooks/cursor.json +8 -0
  39. package/methods/cyc-build/SKILL.md +65 -0
  40. package/methods/cyc-build/references/file-writes.md +11 -0
  41. package/methods/cyc-challenge/SKILL.md +48 -0
  42. package/methods/cyc-context/SKILL.md +76 -0
  43. package/methods/cyc-context/references/evidence.md +27 -0
  44. package/methods/cyc-context/references/templates.md +54 -0
  45. package/methods/cyc-context/scripts/evidence.mjs +61 -0
  46. package/methods/cyc-correct/SKILL.md +43 -0
  47. package/methods/cyc-deliver/SKILL.md +52 -0
  48. package/methods/cyc-design/SKILL.md +50 -0
  49. package/methods/cyc-design/frontend-design/SKILL.md +43 -0
  50. package/methods/cyc-design/frontend-design/references/color.md +77 -0
  51. package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
  52. package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
  53. package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
  54. package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
  55. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
  56. package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
  57. package/methods/cyc-design/frontend-design/references/typography.md +51 -0
  58. package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
  59. package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
  60. package/methods/cyc-error-ledger/SKILL.md +53 -0
  61. package/methods/cyc-error-ledger/references/entry-format.md +38 -0
  62. package/methods/cyc-explore/SKILL.md +41 -0
  63. package/methods/cyc-frame/SKILL.md +49 -0
  64. package/methods/cyc-impact/SKILL.md +64 -0
  65. package/methods/cyc-reflect/SKILL.md +48 -0
  66. package/methods/cyc-remember/SKILL.md +53 -0
  67. package/methods/cyc-scout/SKILL.md +67 -0
  68. package/methods/cyc-setup/SKILL.md +60 -0
  69. package/methods/cyc-teach/SKILL.md +40 -0
  70. package/methods/cyc-understand/SKILL.md +40 -0
  71. package/methods/cyc-understand/references/diagnose.md +53 -0
  72. package/methods/cyc-verify/SKILL.md +87 -0
  73. package/methods/cyc-verify/references/recipe.md +53 -0
  74. package/package.json +91 -4
  75. package/plugin.json +40 -0
  76. package/rules/cyc-delivery.mdc +33 -0
  77. package/scripts/baseline-worker.mjs +10 -0
  78. package/scripts/catalog.mjs +29 -0
  79. package/scripts/claude-project-hook.mjs +12 -0
  80. package/scripts/context-review.mjs +600 -0
  81. package/scripts/host-activation.mjs +66 -0
  82. package/scripts/install.mjs +387 -0
  83. package/scripts/onboarding.mjs +110 -0
  84. package/scripts/packet.mjs +107 -0
  85. package/scripts/project-tools.mjs +196 -0
  86. package/scripts/recovery.mjs +66 -0
  87. package/scripts/response-gate.mjs +105 -0
  88. package/scripts/response-hook.mjs +237 -0
  89. package/scripts/response-mode.mjs +12 -0
  90. package/scripts/run-gate.mjs +264 -0
  91. package/scripts/runtime.mjs +1832 -0
  92. package/scripts/source-hash-worker.mjs +5 -0
  93. package/scripts/source-snapshot.mjs +405 -0
  94. package/scripts/test-output.mjs +268 -0
  95. package/scripts/work-review.mjs +326 -0
  96. package/skills/cyc/SKILL.md +132 -0
  97. package/skills/cyc/references/playbooks/bug-fix.md +13 -0
  98. package/skills/cyc/references/playbooks/evaluate.md +13 -0
  99. package/skills/cyc/references/playbooks/experience.md +7 -0
  100. package/skills/cyc/references/playbooks/explore.md +9 -0
  101. package/skills/cyc/references/playbooks/feature.md +14 -0
  102. package/skills/cyc/references/playbooks/handoff.md +11 -0
  103. package/skills/cyc/references/playbooks/investigation.md +7 -0
  104. package/skills/cyc/references/playbooks/performance.md +7 -0
  105. package/skills/cyc/references/playbooks/plan.md +11 -0
  106. package/skills/cyc/references/playbooks/refactor.md +12 -0
  107. package/skills/cyc/references/playbooks/reflect.md +11 -0
  108. package/skills/cyc/references/playbooks/resume.md +11 -0
  109. package/skills/cyc/references/playbooks/review.md +9 -0
  110. package/skills/cyc/references/playbooks/teach.md +11 -0
  111. package/skills/cyc/references/playbooks/verify.md +7 -0
@@ -0,0 +1,53 @@
1
+ # Project verification recipe
2
+
3
+ The recipe is the project's codified version of "the check a senior developer does by hand after the tests pass." It lives at `docs/context/verify-recipe.md` in the target project, is committed, and is listed in the context index.
4
+
5
+ Executable investigation tools and checks are registered in `docs/context/recipes.json` under the [project-tools contract](../../../docs/project-tools.md). `investigate --path ...` finds matching context and recipes; `recipe list` inspects definitions and current diagnostic receipts; `recipe run --recipe ID` executes a selected authorized command. Verify selects relevant recipes automatically. Preserve manual/browser instructions here when they cannot be expressed as real executable assertions. Required controller checks and test proof remain separate.
6
+
7
+ ## Creating it
8
+
9
+ When applicable checks need discovering, record these steps in run-local notes first. Save a durable recipe only when its path is within authorized scope, before final verification; otherwise retain it as a proposal. Do not require an app recipe for an advisory or document task.
10
+
11
+ 1. Work out how to launch the app (dev server, CLI, simulator) and how to drive it (a browser automation tool or MCP such as Playwright or Chrome DevTools, `curl`, or a simulator tool). If the host ships its own app-verification skill, use it to discover these steps.
12
+ 2. Exercise the change in the running app. Save the steps that worked, exactly, as the recipe.
13
+ 3. Add at least one **measurable** check per surface. The more measurable a check, the easier it is to tell pass from fail.
14
+
15
+ ## Format
16
+
17
+ ```markdown
18
+ # Verify recipe
19
+
20
+ ## Launch
21
+ - `npm run dev` → ready when "Local: http://localhost:3000" prints
22
+ - Stop the process started for this check with Ctrl+C. If the port is occupied, identify its owner or choose another port; do not kill an unrelated process.
23
+
24
+ ## Checks
25
+
26
+ ### UI change (any file under src/components/** or src/app/**)
27
+ | Check | How | Pass when | Evidence |
28
+ | --- | --- | --- | --- |
29
+ | Journey works | Open the page, perform the action, reload | Expected state visible after reload | Screenshot before and after |
30
+ | No console errors | Read the browser console during the journey | Zero errors, zero new warnings | Console log |
31
+ | Layout shift | Chrome DevTools performance trace on page load | CLS < 0.1 | Trace score |
32
+ | Accessibility | axe scan of the page | Zero serious or critical violations | axe report |
33
+
34
+ ### API change (server/**)
35
+ | Check | How | Pass when | Evidence |
36
+ | --- | --- | --- | --- |
37
+ | Contract | `curl -s localhost:3000/api/x`, parsed as JSON | Shape matches the schema; old fields still present | Response body |
38
+ | Latency | 20 sequential requests | p95 < 200 ms | Timing output |
39
+
40
+ ## On failure
41
+ - Layout shift: find the element that moved in the trace, reserve its space (size attributes, skeleton), rerun the trace.
42
+ - Console error: treat it as a bug; search the error ledger first.
43
+
44
+ ## Promoted to controller commands
45
+ - `npm run test:e2e` (journey), `npm run a11y` (axe). These run in `run verify`.
46
+ ```
47
+
48
+ ## Growing it
49
+
50
+ - **Whenever the user checks something by hand and tells the agent what to fix, add that check to the recipe.** That correction was a missing verification step.
51
+ - **Propose useful scriptable checks as controller commands** in `.cyc/config.json` (`verification.commands`). During an active run, retain the proposal in `.cyc/runs/<runId>/proposed-checks.json`; the controller protects configuration mid-run. Apply authorized proposals as a subsequent scoped change with its own verification. Checks that need judgment or a browser tool stay as recipe steps.
52
+ - Keep each check tied to when it applies (the paths or change type), so a backend fix doesn't trigger a layout trace.
53
+ - When a check stops applying, remove it with a note in the context doc. A recipe full of irrelevant checks gets skipped.
package/package.json CHANGED
@@ -1,6 +1,93 @@
1
1
  {
2
2
  "name": "cyc-stack",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.7.0",
4
+ "license": "MIT",
5
+ "private": false,
6
+ "type": "module",
7
+ "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/TheDThompsonDev/cyc-stack.git"
11
+ },
12
+ "homepage": "https://github.com/TheDThompsonDev/cyc-stack#readme",
13
+ "bugs": {
14
+ "url": "https://github.com/TheDThompsonDev/cyc-stack/issues"
15
+ },
16
+ "publishConfig": {
17
+ "access": "public",
18
+ "registry": "https://registry.npmjs.org/"
19
+ },
20
+ "bin": {
21
+ "cyc-stack": "bin/cyc.mjs",
22
+ "cyc": "bin/cyc.mjs"
23
+ },
24
+ "files": [
25
+ "bin",
26
+ "scripts/baseline-worker.mjs",
27
+ "scripts/catalog.mjs",
28
+ "scripts/claude-project-hook.mjs",
29
+ "scripts/context-review.mjs",
30
+ "scripts/host-activation.mjs",
31
+ "scripts/install.mjs",
32
+ "scripts/onboarding.mjs",
33
+ "scripts/packet.mjs",
34
+ "scripts/project-tools.mjs",
35
+ "scripts/recovery.mjs",
36
+ "scripts/response-gate.mjs",
37
+ "scripts/response-hook.mjs",
38
+ "scripts/response-mode.mjs",
39
+ "scripts/run-gate.mjs",
40
+ "scripts/runtime.mjs",
41
+ "scripts/source-hash-worker.mjs",
42
+ "scripts/source-snapshot.mjs",
43
+ "scripts/test-output.mjs",
44
+ "scripts/work-review.mjs",
45
+ "skills",
46
+ "methods",
47
+ "catalog",
48
+ "docs/code-quality.md",
49
+ "docs/README.md",
50
+ "docs/context.md",
51
+ "docs/cyc-method-map.md",
52
+ "docs/cyc-workflow.md",
53
+ "docs/engineering",
54
+ "docs/impact-analysis.md",
55
+ "docs/installation.md",
56
+ "docs/onboarding-recovery.md",
57
+ "docs/principles.md",
58
+ "docs/project-tools.md",
59
+ "docs/response-standard.md",
60
+ "docs/runtime.md",
61
+ "docs/skill-contract.md",
62
+ "docs/skill-craft.md",
63
+ "docs/validation.md",
64
+ "docs/work-assessments.md",
65
+ "docs/assets/cyc-method-library.svg",
66
+ "docs/assets/cyc-overview.svg",
67
+ "docs/assets/cyc-readme-banner.svg",
68
+ "docs/assets/cyc-readme-banner-mobile.svg",
69
+ "docs/assets/cyc-workflow-diagram.svg",
70
+ "hooks",
71
+ "rules",
72
+ ".codex-plugin",
73
+ ".claude-plugin",
74
+ ".cursor-plugin",
75
+ ".agents",
76
+ "plugin.json",
77
+ "README.md",
78
+ "INSTALL.md"
79
+ ],
80
+ "scripts": {
81
+ "check:distribution": "node scripts/check-distribution.mjs",
82
+ "pack:release": "node scripts/pack-release.mjs",
83
+ "build:workflow": "node docs/assets/build-workflow-diagram.mjs",
84
+ "test": "node --test",
85
+ "cyc": "node bin/cyc.mjs"
86
+ },
87
+ "engines": {
88
+ "node": ">=20"
89
+ },
90
+ "devDependencies": {
91
+ "sharp": "0.35.4"
92
+ }
93
+ }
package/plugin.json ADDED
@@ -0,0 +1,40 @@
1
+ {
2
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
+ "name": "cycstack",
4
+ "version": "0.7.0",
5
+ "description": "Portable AI engineering workflows with shared project context and verifiable changes.",
6
+ "author": {
7
+ "name": "CYC Stack contributors"
8
+ },
9
+ "homepage": "https://github.com/TheDThompsonDev/cyc-stack#readme",
10
+ "repository": "https://github.com/TheDThompsonDev/cyc-stack.git",
11
+ "license": "MIT",
12
+ "keywords": [
13
+ "engineering",
14
+ "skills",
15
+ "verification",
16
+ "loop-engineering",
17
+ "context-engineering"
18
+ ],
19
+ "extensions": {
20
+ "com.openai": {
21
+ "hooks": "./hooks/codex.json",
22
+ "interface": {
23
+ "displayName": "CYC Stack",
24
+ "shortDescription": "Portable workflows with visible evidence",
25
+ "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.",
26
+ "developerName": "CYC Stack contributors",
27
+ "category": "Productivity",
28
+ "capabilities": [
29
+ "Interactive",
30
+ "Write"
31
+ ],
32
+ "defaultPrompt": [
33
+ "Set up CYC in this project.",
34
+ "Use CYC to fix this bug and verify affected behavior."
35
+ ]
36
+ },
37
+ "onboardingSkill": "./skills/cyc/SKILL.md"
38
+ }
39
+ }
40
+ }
@@ -0,0 +1,33 @@
1
+ ---
2
+ description: CYC delivery gate protocol for Cursor
3
+ alwaysApply: true
4
+ ---
5
+
6
+ # CYC delivery gate (Cursor)
7
+
8
+ This project uses CYC. A stop hook checks your final response before the turn ends. Cursor hooks cannot pass you per-request instructions, so follow this protocol on every turn.
9
+
10
+ **Existing project formatting:** Read `.cyc/config.json` first. With `delivery.presentation: "project"`, follow the existing project formatting rules instead of the length, visual and review rules below. Still choose a session tag and write `.cyc/runtime/cursor-<tag>.review.json` with `{ "token": "cursor", "response": "<exact final text>", "status": "ready" }` (or `"blocked"` with a reply starting `Blocked:`). This identity packet associates your controller runs with this conversation; it is not a CYC presentation review.
11
+
12
+ **Session tag:** at the start of this conversation, pick a random tag of 6 to 12 lowercase letters and digits (for example `k3v9qd`) and reuse it for the whole conversation. It keeps parallel chats in this folder independent. Pass it as `--session <tag>` whenever you run `cyc run start`.
13
+
14
+
15
+ 1. Draft your final response first. It must include one visual that adds information (a table, a labeled arrow flow like `A → B → C`, a Mermaid diagram, or an image with alt text).
16
+ 2. Length: at most 1,000 characters by default, counting Markdown. If `.cyc/config.json` sets `delivery.defaultCharacterLimitEnabled: false`, new conversations start without the cap; explicit user toggles override that default. If the user sent `limit off` as a standalone message in this conversation, there is no cap until they send `limit on`. A standalone `expand` lifts the cap for one reply.
17
+ 3. Before sending, write `.cyc/runtime/cursor-<tag>.review.json`:
18
+
19
+ ```json
20
+ {
21
+ "token": "cursor",
22
+ "response": "<your exact final response>",
23
+ "status": "ready",
24
+ "checks": [{ "criterion": "<what the user asked>", "result": "passed", "evidence": "<command run, file read, or observation>" }],
25
+ "humanReview": { "answersRequest": true, "understandable": true, "visualAddsInformation": true, "limitationsDisclosed": true },
26
+ "artifacts": [{ "path": "<changed file>", "sha256": "<current sha256>" }]
27
+ }
28
+ ```
29
+
30
+ 4. Send exactly the text you recorded. Any edit after writing the file fails the check.
31
+ 5. If you can't finish, use `"status": "blocked"`, a `"blocker"` string that appears verbatim in the response, and start the response with `Blocked:` or `Not ready:`.
32
+
33
+ If the hook replies with `CYC_GATE_CONTINUE`, fix the listed issues in the work (not only the wording), rewrite the review file, and respond again. Never edit files under `.cyc/runtime/` other than the review file, and never edit the hook to pass. Full standard: `docs/response-standard.md` in the CYC engine.
@@ -0,0 +1,10 @@
1
+ // Measures a run's baseline in the background so the agent can start read-only work immediately.
2
+ // Usage: node baseline-worker.mjs <projectRoot> <runId>
3
+ import { existsSync } from 'node:fs';
4
+ import { resolve } from 'node:path';
5
+ import { measureBaseline } from './runtime.mjs';
6
+
7
+ const [root, id] = process.argv.slice(2);
8
+ if (root && id && existsSync(resolve(root, '.cyc/runs', id, 'state.json'))) {
9
+ try { measureBaseline(root, id); } catch { /* measureBaseline records its own errors when it can */ }
10
+ }
@@ -0,0 +1,29 @@
1
+ import { readFileSync } from 'node:fs';
2
+
3
+ export const catalog = JSON.parse(readFileSync(new URL('../catalog/playbooks.json', import.meta.url), 'utf8'));
4
+ export function getPlaybook(id) {
5
+ const playbook = catalog.playbooks.find(item => item.id === id);
6
+ if (!playbook) throw new Error(`Unknown playbook: ${id}. Use cyc playbooks to list choices.`);
7
+ return playbook;
8
+ }
9
+
10
+ export function routeTask(goal) {
11
+ const rules = [
12
+ ['teach', /\b(teach|learn|lesson|explain.*(?:to me|student))\b/i],
13
+ ['reflect', /\b(reflect|lessons learned)\b/i],
14
+ ['resume', /\b(resume|pick up|continue where)\b/i],
15
+ ['evaluate', /\b(benchmark|evaluate.*(?:skill|workflow)|compare.*baseline)\b/i],
16
+ ['bug-fix', /\b(bug|broken|crash|fails?|regression|fix)\b/i],
17
+ ['performance', /\b(slow|latency|performance|speed up)\b/i],
18
+ ['refactor', /\b(refactor|rename|restructure)\b/i],
19
+ ['review', /\b(review|audit)\b/i],
20
+ ['verify', /\b(verify|test whether|does .* work)\b/i],
21
+ ['plan', /\b(plan|roadmap|phases)\b/i],
22
+ ['explore', /\b(explore|prototype|alternatives|brainstorm)\b/i],
23
+ ['handoff', /\b(handoff|pull request|prepare.*review)\b/i],
24
+ ['experience', /\b(redesign|user journey|cohesion|layout)\b/i],
25
+ ['investigation', /\b(how does|why does|investigate|understand)\b/i]
26
+ ];
27
+ const match = rules.find(([, pattern]) => pattern.test(goal));
28
+ return { playbook: match?.[0] ?? 'feature', basis: match ? 'Keyword suggestion; the orchestrator must confirm intent.' : 'Default suggestion; select a playbook explicitly when uncertain.', advisory: true };
29
+ }
@@ -0,0 +1,12 @@
1
+ // Installed as scripts/claude-hooks/cyc.mjs in the consuming project.
2
+ // Resolve from this file so nested working directories and moved clones work.
3
+ // The project's own linter may parse every .mjs file as a classic script, so this file uses no
4
+ // import declarations, import.meta, or top-level await: they would be parse errors there, which
5
+ // no eslint-disable comment can suppress. The response hook resolves the real project path.
6
+ Promise.all([import('node:path'), import('node:url')]).then(function (modules) {
7
+ var path = modules[0];
8
+ var root = path.resolve(path.dirname(process.argv[1]), '../..');
9
+ var engine = path.resolve(root, '.cyc/engine/scripts/response-hook.mjs');
10
+ process.argv = [process.execPath, engine, 'claude', '--project', root];
11
+ return import(modules[1].pathToFileURL(engine).href);
12
+ });