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.
- package/.agents/plugins/marketplace.json +12 -0
- package/.claude-plugin/marketplace.json +14 -0
- package/.claude-plugin/plugin.json +17 -0
- package/.codex-plugin/plugin.json +33 -0
- package/.cursor-plugin/marketplace.json +13 -0
- package/.cursor-plugin/plugin.json +19 -0
- package/INSTALL.md +108 -0
- package/LICENSE +21 -0
- package/README.md +359 -2
- package/bin/cyc.mjs +285 -0
- package/catalog/playbooks.json +20 -0
- package/docs/README.md +30 -0
- package/docs/assets/cyc-method-library.svg +39 -0
- package/docs/assets/cyc-overview.svg +44 -0
- package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
- package/docs/assets/cyc-readme-banner.svg +39 -0
- package/docs/assets/cyc-workflow-diagram.svg +415 -0
- package/docs/code-quality.md +42 -0
- package/docs/context.md +40 -0
- package/docs/cyc-method-map.md +58 -0
- package/docs/cyc-workflow.md +188 -0
- package/docs/engineering/code-standards.md +103 -0
- package/docs/engineering/domain-design.md +81 -0
- package/docs/engineering/failure-handling.md +99 -0
- package/docs/impact-analysis.md +70 -0
- package/docs/installation.md +196 -0
- package/docs/onboarding-recovery.md +75 -0
- package/docs/principles.md +49 -0
- package/docs/project-tools.md +108 -0
- package/docs/response-standard.md +202 -0
- package/docs/runtime.md +247 -0
- package/docs/skill-contract.md +70 -0
- package/docs/skill-craft.md +23 -0
- package/docs/validation.md +39 -0
- package/docs/work-assessments.md +102 -0
- package/hooks/claude.json +10 -0
- package/hooks/codex.json +28 -0
- package/hooks/cursor.json +8 -0
- package/methods/cyc-build/SKILL.md +65 -0
- package/methods/cyc-build/references/file-writes.md +11 -0
- package/methods/cyc-challenge/SKILL.md +48 -0
- package/methods/cyc-context/SKILL.md +76 -0
- package/methods/cyc-context/references/evidence.md +27 -0
- package/methods/cyc-context/references/templates.md +54 -0
- package/methods/cyc-context/scripts/evidence.mjs +61 -0
- package/methods/cyc-correct/SKILL.md +43 -0
- package/methods/cyc-deliver/SKILL.md +52 -0
- package/methods/cyc-design/SKILL.md +50 -0
- package/methods/cyc-design/frontend-design/SKILL.md +43 -0
- package/methods/cyc-design/frontend-design/references/color.md +77 -0
- package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
- package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
- package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
- package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
- package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
- package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
- package/methods/cyc-design/frontend-design/references/typography.md +51 -0
- package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
- package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
- package/methods/cyc-error-ledger/SKILL.md +53 -0
- package/methods/cyc-error-ledger/references/entry-format.md +38 -0
- package/methods/cyc-explore/SKILL.md +41 -0
- package/methods/cyc-frame/SKILL.md +49 -0
- package/methods/cyc-impact/SKILL.md +64 -0
- package/methods/cyc-reflect/SKILL.md +48 -0
- package/methods/cyc-remember/SKILL.md +53 -0
- package/methods/cyc-scout/SKILL.md +67 -0
- package/methods/cyc-setup/SKILL.md +60 -0
- package/methods/cyc-teach/SKILL.md +40 -0
- package/methods/cyc-understand/SKILL.md +40 -0
- package/methods/cyc-understand/references/diagnose.md +53 -0
- package/methods/cyc-verify/SKILL.md +84 -0
- package/methods/cyc-verify/references/recipe.md +53 -0
- package/package.json +93 -4
- package/plugin.json +40 -0
- package/rules/cyc-delivery.mdc +33 -0
- package/scripts/baseline-worker.mjs +10 -0
- package/scripts/catalog.mjs +29 -0
- package/scripts/check-response.mjs +13 -0
- package/scripts/claude-project-hook.mjs +12 -0
- package/scripts/context-review.mjs +600 -0
- package/scripts/host-activation.mjs +66 -0
- package/scripts/install.mjs +387 -0
- package/scripts/onboarding.mjs +110 -0
- package/scripts/packet.mjs +107 -0
- package/scripts/project-tools.mjs +196 -0
- package/scripts/recovery.mjs +66 -0
- package/scripts/response-gate.mjs +105 -0
- package/scripts/response-hook.mjs +237 -0
- package/scripts/response-mode.mjs +12 -0
- package/scripts/run-gate.mjs +264 -0
- package/scripts/runtime.mjs +1723 -0
- package/scripts/source-hash-worker.mjs +5 -0
- package/scripts/source-snapshot.mjs +405 -0
- package/scripts/test-output.mjs +258 -0
- package/scripts/work-review.mjs +257 -0
- package/skills/cyc/SKILL.md +130 -0
- package/skills/cyc/references/playbooks/bug-fix.md +13 -0
- package/skills/cyc/references/playbooks/evaluate.md +13 -0
- package/skills/cyc/references/playbooks/experience.md +7 -0
- package/skills/cyc/references/playbooks/explore.md +9 -0
- package/skills/cyc/references/playbooks/feature.md +14 -0
- package/skills/cyc/references/playbooks/handoff.md +11 -0
- package/skills/cyc/references/playbooks/investigation.md +7 -0
- package/skills/cyc/references/playbooks/performance.md +7 -0
- package/skills/cyc/references/playbooks/plan.md +11 -0
- package/skills/cyc/references/playbooks/refactor.md +12 -0
- package/skills/cyc/references/playbooks/reflect.md +11 -0
- package/skills/cyc/references/playbooks/resume.md +11 -0
- package/skills/cyc/references/playbooks/review.md +9 -0
- package/skills/cyc/references/playbooks/teach.md +11 -0
- package/skills/cyc/references/playbooks/verify.md +7 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-reflect
|
|
3
|
+
description: "Turn what went wrong or right in finished work into specific proposed edits to CYC skills, checks, or project rules, each tied to evidence. Use when the user says \"reflect\", \"what did we learn\", or \"improve the workflow\", after a task needed corrections, or when a missed dependency or repeated mistake appeared."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Learn from outcomes
|
|
7
|
+
|
|
8
|
+
The output is proposed edits, not a list of lessons. A lesson that doesn't change a file changes nothing. Follow the [handoff contract](../../docs/skill-contract.md) and the [skill craft guide](../../docs/skill-craft.md).
|
|
9
|
+
|
|
10
|
+
## The core loop
|
|
11
|
+
|
|
12
|
+
1. **Collect the moments that mattered.** User corrections, failed checks, missed dependencies, rework, and things that went unusually well. Read the relevant run's `review.md`, handoffs and verification receipts, the selected error ledger, and available transcript or decision log. Use an improvements log only if the project already maintains one; the controller does not generate `.cyc/runs/improvements.tsv`. An AI-written summary is secondary evidence.
|
|
13
|
+
2. **Read each moment through three lenses.**
|
|
14
|
+
- **Judgment:** what decision was wrong or right, and what would have led to the right one?
|
|
15
|
+
- **Tooling:** what check, script, or search would have caught it mechanically?
|
|
16
|
+
- **Beneath the obvious:** what is the learning under the first explanation? ("Missed the reminder job" may really be "we only searched imports.")
|
|
17
|
+
3. **Pick the strongest mechanism that would prevent it.** In order:
|
|
18
|
+
1. make it impossible (a type or schema)
|
|
19
|
+
2. a test, lint, or CI check
|
|
20
|
+
3. a script or helper the skill tells the agent to run
|
|
21
|
+
4. a sharper step or anti-pattern in an existing skill
|
|
22
|
+
5. a new sentence of prose, as the last resort
|
|
23
|
+
4. **Apply the no-op test to every proposed skill edit.** Would a strong model behave differently with this sentence? If not, drop it.
|
|
24
|
+
5. **Prefer editing an existing skill over creating one.** A new skill needs recurring evidence across tasks.
|
|
25
|
+
6. **Write each proposal as an edit.** Target file, the exact change, the evidence (quoted correction or failed check), where it should *not* apply, and how you would tell if it made things worse.
|
|
26
|
+
|
|
27
|
+
## Acceptance for a proposal
|
|
28
|
+
|
|
29
|
+
Keep a proposal only if it is: tied to a real moment, specific enough to apply, decision-changing, not already covered, and durable (it will still be true next month). Drop one-off facts like commit hashes and versions; keep the pattern behind them.
|
|
30
|
+
|
|
31
|
+
A finding that the skill didn't trigger when it should have is a proposal to tune the skill's **description**, not its body.
|
|
32
|
+
|
|
33
|
+
## Done when
|
|
34
|
+
|
|
35
|
+
Each surviving proposal names a file, the change, its evidence, and its counter-case. "No supported lesson this time" is a valid result.
|
|
36
|
+
|
|
37
|
+
## Anti-patterns
|
|
38
|
+
|
|
39
|
+
| Name | The tell | Fix |
|
|
40
|
+
| --- | --- | --- |
|
|
41
|
+
| Lesson list | "We learned to be more careful" | Write the file edit or drop it |
|
|
42
|
+
| Prose for a machine job | Adding "remember to check X" when a script could | Build the check |
|
|
43
|
+
| One-off promotion | A single correction becomes a global rule | Wait for recurrence or ask the user |
|
|
44
|
+
| Authorship drift | The agent's idea recorded as the user's insight | Keep who said what |
|
|
45
|
+
|
|
46
|
+
## Handoff
|
|
47
|
+
|
|
48
|
+
Return proposals to the user. Apply them only when the current request authorizes editing skills or rules.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-remember
|
|
3
|
+
description: "Keep a running decision log during work and rebuild context when resuming, so the next session knows what was decided, why, and what's next. Use at checkpoints, before stopping mid-task, when the user says \"catch me up\" or \"where did I leave off\", or when handing work to another session or tool."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Remember what matters
|
|
7
|
+
|
|
8
|
+
Write memory as you go, not in a batch at the end. Follow the [handoff contract](../../docs/skill-contract.md).
|
|
9
|
+
|
|
10
|
+
## During work: the decision log
|
|
11
|
+
|
|
12
|
+
Append one row per consequential decision to `.cyc/runs/<runId>/decisions.tsv`, or `.cyc/runs/decisions.tsv` outside a run:
|
|
13
|
+
|
|
14
|
+
```text
|
|
15
|
+
time stage decision why evidence who
|
|
16
|
+
2026-09-25T14:02 design finished is a boolean, default false no other states requested storage.ts:15 user
|
|
17
|
+
2026-09-25T14:20 build count derives from same filter avoids drift Counter.tsx:8 agent
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
- **evidence** is a pointer (file:line, command, or URL), never a paragraph.
|
|
21
|
+
- **who** is `user` (they decided), `agent` (you proposed; not yet adopted), or `adopted` (you proposed, the user agreed).
|
|
22
|
+
- Never edit a row. If a decision changes, append a new row that supersedes it.
|
|
23
|
+
|
|
24
|
+
## At a checkpoint
|
|
25
|
+
|
|
26
|
+
Write a capsule of five bullets or fewer: destination, current stage, what's proven (with evidence pointers), what's open, and the next single action. Tag each open thread with one status: `[done]`, `[in progress]`, `[blocked: reason]`, or `[dropped: reason]`. Untagged threads count as not done.
|
|
27
|
+
|
|
28
|
+
Point to canonical component context and its relevant constraints/checks instead of copying them into the capsule. Retain verified reusable findings through [Context](../cyc-context/SKILL.md) before final verification; a local decision log alone is not shared project memory. Keep adoption status and technical evidence distinct.
|
|
29
|
+
|
|
30
|
+
## When resuming
|
|
31
|
+
|
|
32
|
+
Read `node <cli> run recover --run ID` for the existing run before changing its state. It preserves the recorded budget and exposes historical check receipts without making them current proof. Use the run ID from this task's records, not another session's latest run. If the ID is missing or several match, reconstruct the association from the task records before choosing. A paused run can resume; a blocked run first needs its recorded prerequisite resolved. An exhausted, halted or stopped run needs an explicit continuation decision rather than an automatic fresh budget.
|
|
33
|
+
|
|
34
|
+
1. Read the capsule and decision log first. They are the record; don't re-derive everything from scratch.
|
|
35
|
+
2. Check for drift: compare them with current files and git state. Recheck only what drift affects.
|
|
36
|
+
3. Treat an earlier "tests passed" as history, not a current result. Rerun before relying on it.
|
|
37
|
+
4. Preserve the user's changes made since the checkpoint.
|
|
38
|
+
5. Report what changed since the checkpoint and the next action. State what remains in place without calling it a backup or claiming earlier commands had no side effects. Keep agent-caused and user-caused changes distinct only when evidence establishes authorship. If help is needed, reuse the existing review, failing receipt and recorded prerequisite as the handoff; do not send it to a teammate without authorization.
|
|
39
|
+
|
|
40
|
+
## Done when
|
|
41
|
+
|
|
42
|
+
Another worker could read the capsule and log and state what's decided, by whom, what's proven, and the safe next step, without guessing.
|
|
43
|
+
|
|
44
|
+
## Anti-patterns
|
|
45
|
+
|
|
46
|
+
| Name | The tell | Fix |
|
|
47
|
+
| --- | --- | --- |
|
|
48
|
+
| End-of-day dump | The log is written from memory at the end | Append when the decision happens |
|
|
49
|
+
| Authorship blur | An agent idea recorded as the user's choice | Use the `who` column honestly |
|
|
50
|
+
| Stale proof | Reusing old test results after resuming | Rerun |
|
|
51
|
+
| Silent scope shrink | "Catch me up on everything" answered from the last hour only | Say what range you covered |
|
|
52
|
+
|
|
53
|
+
Keep credentials and unrelated personal data out of every record. Use the controller's pause and resume commands; never edit its state files.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-scout
|
|
3
|
+
description: "Get from request to a concrete plan in one or two minutes: one parallel batch of searches and reads, then a short plan naming the files to change, the consumers to keep consistent, and the checks to run. Use at the start of any feature, bug fix, refactor, or verification task before editing code."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Scout, then build
|
|
7
|
+
|
|
8
|
+
For a new website, composed interface or visual redesign, use the [frontend design method](../cyc-design/frontend-design/SKILL.md) before choosing structure or acceptance criteria: write `design/decisions.md` (archetype, typeface pair, palette values, signature element, rejection condition) and, for several sites, the set-divergence table. A palette, image presence and readability cannot be the entire visual criterion. Keep this within the user's criterion count; a narrow repair preserves the existing direction.
|
|
9
|
+
|
|
10
|
+
Scouting establishes the affected behavior and the next justified action. For an implementation route, aim for a short plan and a useful first edit; for Investigation, Review, or Verify, establish the explanation or checks without assuming permission to change the product. Expand investigation for consequential uncertainty; verification cannot justify skipping relevant project history or a misunderstood goal.
|
|
11
|
+
|
|
12
|
+
For user updates, follow the shared [progress standard](../../docs/response-standard.md#progress-updates): explain the observed behavior and the likely or confirmed mechanism in short, readable prose, then the next useful change or unresolved question. File counts alone do not explain a discovery.
|
|
13
|
+
|
|
14
|
+
Build the engineer's picture of the affected system: connect the relevant input, state, and readers; explain how checked project history informs the approach and which trade-off matters. Follow the [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work). Agreement on scope is not evidence of comprehension; ask only for a consequential missing decision.
|
|
15
|
+
|
|
16
|
+
## The pass
|
|
17
|
+
|
|
18
|
+
After locating the affected paths, run `node <cli> investigate --path <paths>` (or `--run <ID>` with a known scope). Read the returned records and recipe definitions. Run applicable investigation recipes when their prerequisites hold and effects are already authorized; explain unavailable checks. Reuse equivalent current evidence already returned by discovery rather than rerunning solely to create a receipt. Do this without a separate user request, and reuse the result until paths or evidence change. Missing recipes mean ordinary focused discovery, not a new documentation requirement. See [project tools](../../docs/project-tools.md).
|
|
19
|
+
|
|
20
|
+
1. **One parallel batch, not a file-by-file tour.** In a single round of tool calls, run together:
|
|
21
|
+
- a search for the entry point (the visible string, route, function, or error message)
|
|
22
|
+
- a search for every reader and writer of the data you'll change (field name, storage key, event name, exported function)
|
|
23
|
+
- the existing feature map (if any), `docs/context/INDEX.md`, and the selected error ledger for these paths
|
|
24
|
+
- `git status` / `git diff --stat` when work is already in progress
|
|
25
|
+
2. **Reuse what is established.** Read matching current component context, then inspect the affected functions and integration boundaries. Follow [Context](../cyc-context/SKILL.md) for revision/file-evidence checks; revalidate affected claims when dependencies drift. Reuse still-applicable impact knowledge, failed approaches, and check recipes rather than reconstructing them. Expand for missing consumers or consequential unknowns. State when no history applies. Choose **reuse, extend, repair, or create**, with evidence; use the project's existing capability map. Stop when affected behavior, intended files, consumers, and checks are understood.
|
|
26
|
+
When the change introduces or reshapes state, ownership, or an interface, use the [architecture questions](../../docs/code-quality.md#choose-a-structure-that-protects-the-contract) while choosing the approach. Name the authoritative state, permitted writers, and invariant at the real caller. Compare another shape only if consequential uncertainty remains; a familiar local change does not need a design exercise.
|
|
27
|
+
|
|
28
|
+
3. **Write the plan in about ten lines:**
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
Goal: one sentence. Done when: 2-4 checks.
|
|
32
|
+
Approach: reuse/extend/repair/create → existing capability and reason.
|
|
33
|
+
Context: relevant history, freshness, known failed approaches (or no match).
|
|
34
|
+
Change: file → what changes (one line each)
|
|
35
|
+
Keep consistent: consumer → why it depends on this (from the search)
|
|
36
|
+
Test: the checks that would show it broken
|
|
37
|
+
Open: only decisions that change the solution (with your recommendation)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
4. **Explain consequential changes.** Current behavior → proposed change → reason → decision needed. Ask only when an unresolved answer changes the solution; bundle questions with a recommendation. Otherwise state supported assumptions and continue. Record alignment as clear or actually confirmed; unresolved consequential alignment is blocked, not assumed approved.
|
|
41
|
+
5. **Record and move on.** If `run start` was given `scout`, Scout is already recorded: do not record it again, because a second record lands at Build. Otherwise `cyc run record --run ID --summary "<plan>" --assessment <scout.json>` for new implementation runs. The [assessment](../../docs/work-assessments.md) records context lookup/freshness, approach, alignment, and stable consumer IDs/checks, including directly affected behavior. Keep JSON in the run directory. Advisory routes retain ordinary handoffs.
|
|
42
|
+
|
|
43
|
+
## Scale by risk, not by habit
|
|
44
|
+
|
|
45
|
+
- **Normal work:** the pass above. Do not add paperwork or invent alternatives without a real decision to resolve. For visual frontend work, a useful first implementation can resolve the actual composition with meaningful content and assets; source-edit speed is not a reason to settle for a generic scaffold.
|
|
46
|
+
- **High risk** (auth, payments, data migrations, deletes, public interfaces): also run [Challenge](../cyc-challenge/SKILL.md) on the plan before building. It's one focused pass, not a new research phase.
|
|
47
|
+
- **Bugs:** include getting the failure to reproduce in the same batch (run the failing test or request). See the [diagnose branch](../cyc-understand/references/diagnose.md) only if it doesn't reproduce quickly.
|
|
48
|
+
|
|
49
|
+
The detailed skills ([Understand](../cyc-understand/SKILL.md), [Impact](../cyc-impact/SKILL.md), [Design](../cyc-design/SKILL.md)) are reference material for when something is genuinely unclear. Don't read them by default.
|
|
50
|
+
|
|
51
|
+
## Done when
|
|
52
|
+
|
|
53
|
+
The findings name the affected files, consumers supported by inspection, checks to run, and the next stage for the selected route. For implementation, begin a safe, useful test or reversible slice once the plan is ready. For advisory work, pass the supported findings onward without editing the product. If investigation takes longer than expected, identify the unresolved question; surface a real blocker promptly. Never defer a critical permission, data-loss, or interface-contract question on the assumption that verification will catch it.
|
|
54
|
+
|
|
55
|
+
## Anti-patterns
|
|
56
|
+
|
|
57
|
+
| Name | The tell | Fix |
|
|
58
|
+
| --- | --- | --- |
|
|
59
|
+
| Serial tour | One file read per step, narrating each | Batch searches and reads in parallel |
|
|
60
|
+
| Reading for completeness | Understanding code paths the change doesn't touch | Stop when every changed file and consumer is named |
|
|
61
|
+
| Paperwork | Tables, evidence rungs, category checklists | Ten-line plan |
|
|
62
|
+
| Pre-verifying | Measuring or testing hypotheticals before any edit | Build, then let the verify loop measure |
|
|
63
|
+
| Re-reading instructions | Opening unrelated methods at every step | Load needed instructions once; preserve required outcomes |
|
|
64
|
+
|
|
65
|
+
## Handoff
|
|
66
|
+
|
|
67
|
+
Pass the findings to the stage returned by `run next`: Build for implementation, Challenge for review, Verify for verification, Explore for experience work, or Deliver for investigation. Advisory Scout establishes an evidence-backed explanation or review scope, not permission to edit. If later work finds a consumer the plan missed, update the plan and relevant retained context before verification.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-setup
|
|
3
|
+
description: "Set up CYC in the current project: activate it, find the project's real test, lint, and type-check commands, write them into the CYC config, and confirm everything works. Use when the user says \"set up cyc\", \"activate cyc\", \"install cyc here\", or right after installing the CYC plugin."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Set up CYC in this project
|
|
7
|
+
|
|
8
|
+
Guide the developer from installation to one useful task. Keep installed files, configured checks, executed checks, and live host activation distinct. Use the existing project conventions and ask only about consequential missing decisions.
|
|
9
|
+
|
|
10
|
+
The CYC CLI is [bin/cyc.mjs](../../bin/cyc.mjs), two folders up from this skill. Resolve it to an absolute path and run it with `node`.
|
|
11
|
+
|
|
12
|
+
## The core loop
|
|
13
|
+
|
|
14
|
+
1. **Inspect readiness.** Run `node <cli> onboard`. If this request supplied CYC gate context, add `--host codex|claude --session <gate ID> --token <injected review token>`. Otherwise omit the token: native Codex/Claude session identity is detected when available, and missing prompt state is an actionable setup failure. Inspection runs no project commands and changes no files. Explain its first unresolved step in plain language, not the entire JSON report.
|
|
15
|
+
- A project manifest exists: the report includes `doctor` findings. Resolve actual installation conflicts while preserving customized files.
|
|
16
|
+
- Only a config exists: the project is configured, but confirm that the host supplies the plugin. Do not reinstall or overwrite a team's existing checks just to repeat onboarding.
|
|
17
|
+
- No config exists: continue with activation or the project installer, according to how the user obtained CYC.
|
|
18
|
+
2. **Activate.** Run `node <cli> activate --dry-run`, show the planned files, then run it without `--dry-run`. This creates `.cyc/config.json` and `.cyc/.gitignore` only. It changes nothing else.
|
|
19
|
+
3. **Find the real checks.** Use `onboard.evidenceSources` as pointers, then read the project's own sources of truth: CI workflow files (`.github/workflows`, `.gitlab-ci.yml`), `package.json` scripts, `Makefile`, `pyproject.toml`, `go.mod`, `Cargo.toml`, and contributing instructions. Discovery does not parse or endorse commands. CI is the best evidence of what the team actually trusts. Explain each recommended check through the behavior or error it can detect. If no checks exist, say so and propose one bounded behavior check grounded in the project; creating it requires appropriate task scope, and an always-successful command is not a substitute.
|
|
20
|
+
Read existing project recipes with `node <cli> recipe list`. Reuse actual investigation scripts and behavior checks. Register successful, reusable commands in the project's `docs/context/recipes.json` using the [project-tools contract](../../docs/project-tools.md), with concrete coverage, references, prerequisites, effects and expected outcomes. This is authorized project configuration work, not permission to publish or copy CYC's development recipes into the application. Keep mandatory checks in `verification.commands`; optional relevant tools do not replace them.
|
|
21
|
+
4. **Propose the commands in one round**, each with the reason and your recommendation:
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
Proposed verification commands for .cyc/config.json:
|
|
25
|
+
1. test npm test (runs in CI: .github/workflows/ci.yml:31) Recommended: yes
|
|
26
|
+
2. typecheck npx tsc --noEmit (in CI) Recommended: yes
|
|
27
|
+
3. lint npm run lint (in CI, ~40s) Recommended: yes
|
|
28
|
+
4. e2e npm run test:e2e (needs a running server) Recommended: no, keep it in the verify recipe
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Never add a command you haven't seen defined in the project. Never guess. Prefer checks that finish in a few minutes: CYC runs them to verify every change (optional diagnostic baseline checks are off by default). Leave hour-long suites to CI or the verify recipe, and split one giant command into separate ones (unit, integration) so each can be run and judged on its own.
|
|
32
|
+
When no one can answer (an unattended run, or `/cyc` was invoked with instructions not to wait), do not stop: write only commands the project itself defines and runs (CI or a package script), prove them in step 7, and name them in the final handoff as configured checks. That disclosure is information, not a blocker.
|
|
33
|
+
|
|
34
|
+
Do all of this before `run start`. The controller captures the checks when a run starts and protects `.cyc/config.json` while it runs; an edit then halts the run, and `run start` refuses code playbooks while no checks exist.
|
|
35
|
+
5. **Write the approved commands** into `verification.commands` as `{ "id", "command", "args": [], "timeoutMs" }`. Reuse already authorized team configuration; do not ask for approval again when the session already provides it. Do not change configuration beneath an active run. Split the executable from its arguments (`"command": "npm", "args": ["test"]`). On Windows, Node cannot launch `npm`, `npx`, or other `.cmd` shims directly, so wrap them: `"command": "cmd", "args": ["/c", "npm", "test"]`.
|
|
36
|
+
6. **Respect existing conventions.** Reuse the project ledger through `context.ledgerPath`. If another hook already enforces response formatting, configure `delivery.presentation: "project"`; preserve that hook. CYC still enforces controller completion. Show these choices with the proposed commands.
|
|
37
|
+
7. **Prove the configured commands run.** After inspecting their side effects and establishing authorization, run `node <cli> onboard --verify`. It runs the configured checks and saves `.cyc/runtime/onboarding-checks.json`, bound to the configuration and covered source. Read failures from that receipt. A passing exit that changes source is not passing setup verification; later edits make the result stale. This receipt is diagnostic and never replaces a task's `run verify`. Keep baseline checks off for ordinary runs. Report existing failures without fixing unrelated code unasked or weakening checks.
|
|
38
|
+
8. **Check the hooks in the actual host.** `onboard` exits nonzero while setup is not ready. Follow the `host` step rather than treating passing project tests as activation. Missing state means inspect the exact hook definitions and host trust/settings, then open a fresh session or reload. Use the supported hook review UI; do not edit trust records or fabricate hook state. A missing injected token cannot be repaired by reading an older state file or inventing a Cursor tag in Codex/Claude.
|
|
39
|
+
With the current injected token, `pending` plus `canStartTask: true` means the prompt hook ran and the authorized first task can proceed. Do not wait for your own Stop before starting it. After the turn ends, a separate observation can confirm `passed` from matching prompt/Stop identity, exact review/response and unchanged hook/configuration bytes. A rejected draft remains pending repair; blocked/not-ready completion is not successful setup. Old, copied, legacy or changed evidence stays stale/unverified. Cursor retains its own conversation/tag correlation and cannot be certified by a constant token through this check.
|
|
40
|
+
Do not manually invoke a hook script and call it live activation. A missing table alone is not a reliable probe: project-owned presentation and alternative valid visuals change the requirements. Report the observed host/version and remaining limits; local editable trace evidence is not independent certification.
|
|
41
|
+
9. **Connect setup to a first success.** If the user already requested a bounded task, continue that task through the existing orchestrator once prerequisites permit. Otherwise recommend a small task from inspected project evidence and let the user choose it before editing product behavior. Explain the outcome and the checks that would establish it. On delivery, connect one consequential change to its test and point to the existing review. Do not require practice or claim that an explanation proves understanding.
|
|
42
|
+
|
|
43
|
+
## Done when
|
|
44
|
+
|
|
45
|
+
- The report separates installation, configuration, executed checks, and host activation, with actual evidence and one next action for any unresolved step.
|
|
46
|
+
- Configured commands have recorded results; failed, stale or unavailable results remain disclosed. A failed setup is not called ready.
|
|
47
|
+
- The first task is continued when already authorized, or a concrete recommendation is offered without inventing approval. Setup completion and task completion remain separate.
|
|
48
|
+
|
|
49
|
+
## Anti-patterns
|
|
50
|
+
|
|
51
|
+
| Name | The tell | Fix |
|
|
52
|
+
| --- | --- | --- |
|
|
53
|
+
| Invented checks | Adding `npm test` to a project with no test script | Only use commands defined in the project |
|
|
54
|
+
| Silent writes | Changing config before showing the plan | Dry run first, then write |
|
|
55
|
+
| Fixing the baseline | "Tests were failing, so I fixed them" during setup | Report the failing baseline; fixing is a separate task |
|
|
56
|
+
| Committed secrets | Tokens or env values in config commands | Reference env vars by name only |
|
|
57
|
+
|
|
58
|
+
## Handoff
|
|
59
|
+
|
|
60
|
+
Report what is ready, the first unresolved step, and its smallest next action. Cite setup and host evidence separately. `ok`/`ready` require passing setup phases; neither establishes first-task completion or human understanding. Suggest sharing the existing project configuration through the team's normal review process.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-teach
|
|
3
|
+
description: "Teach a concept through the learner's own project with a plain definition, a worked example from their code, and a small practice task. Use when the user says \"explain\", \"teach me\", \"help me understand\", \"why does this work\", or is a student or newer developer learning while building."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Teach through the real work
|
|
7
|
+
|
|
8
|
+
Aim for understanding the learner can use elsewhere, not a longer answer. Follow the [handoff contract](../../docs/skill-contract.md).
|
|
9
|
+
|
|
10
|
+
This method is for a requested lesson or practice. Ordinary implementation already includes explanations through the shared [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work); do not require a separate teaching playbook, quiz, or learner response to provide them.
|
|
11
|
+
|
|
12
|
+
## The core loop
|
|
13
|
+
|
|
14
|
+
1. **Find the starting point from what they said.** Their wording, their code, and past questions show their level. Don't give a placement quiz. If it's genuinely unclear, ask one question.
|
|
15
|
+
2. **Define it plainly first.** One or two sentences with no jargon they haven't seen. "State is the data your app remembers between clicks."
|
|
16
|
+
3. **Tie it to their code immediately.** Show where the concept lives in *their* project, with the file and line. Read the code first; never teach from an imagined version of it.
|
|
17
|
+
4. **Build the picture in steps.** For a flow, draw A → B, then add C, then the return path. Do not start with the full diagram.
|
|
18
|
+
5. **Show one decision and its tradeoff.** "We saved to localStorage because the app has no accounts. The cost: it doesn't sync across devices." This is where understanding forms.
|
|
19
|
+
6. **Give the smallest complete answer, then stop.** Offer to go deeper; don't pre-empt it.
|
|
20
|
+
7. **Offer one practice task on a nearby variation.** "Now make the *delete* button update the count the same way." Give hints in steps if they ask. Provide the solution when asked.
|
|
21
|
+
8. **Check transfer, not recall.** Ask them to predict what happens in a new case ("What if two tabs are open?") rather than repeat the definition.
|
|
22
|
+
|
|
23
|
+
## Done when
|
|
24
|
+
|
|
25
|
+
The explanation is correct, grounded in files you read, and pitched at their level, and practice is offered. Learning is only shown by the learner's own attempt or prediction. Delivering a lesson doesn't prove it landed; say so if no attempt was made.
|
|
26
|
+
|
|
27
|
+
## Anti-patterns
|
|
28
|
+
|
|
29
|
+
| Name | The tell | Fix |
|
|
30
|
+
| --- | --- | --- |
|
|
31
|
+
| Jargon cascade | Explaining a term with three new terms | Define with words they already use |
|
|
32
|
+
| Generic example | A textbook "foo/bar" example | Use their project |
|
|
33
|
+
| Lecture | Five paragraphs before any code | Definition, then their code, then stop |
|
|
34
|
+
| Drama framing | "Here's the key insight", "this is the tricky part" | Just say it |
|
|
35
|
+
| Solving their practice | Writing the solution before they try | Hint in steps unless they ask |
|
|
36
|
+
| Invented voice | Presenting AI-written advice as the project creator's teaching | Label who wrote it; only use reviewed material as theirs |
|
|
37
|
+
|
|
38
|
+
## Handoff
|
|
39
|
+
|
|
40
|
+
Return the explanation, the practice task, and what was actually assessed (for example, "the learner predicted the two-tab case correctly" or "no attempt yet"). If the learner needs to respond before continuing, return blocked on their participation.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-understand
|
|
3
|
+
description: "Build an evidence-backed model of how the existing system behaves, or reproduce and locate a failure. Use for \"how does X work\", \"why does X happen\", bug reports, anything broken, throwing, or slow, and before designing a change to unfamiliar code."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Understand the existing system
|
|
7
|
+
|
|
8
|
+
Produce a model of the real behavior that the next skill can rely on. Read-only unless an experiment is authorized. Follow the [handoff contract](../../docs/skill-contract.md) for labeling observed versus inferred claims.
|
|
9
|
+
|
|
10
|
+
**Something is broken?** Search the [error ledger](../cyc-error-ledger/SKILL.md) first, then use the [diagnose branch](references/diagnose.md). Its rule is "no red loop, no fix."
|
|
11
|
+
|
|
12
|
+
## The core loop
|
|
13
|
+
|
|
14
|
+
1. **Find relevant project evidence.** Once paths are known, use `node <cli> investigate --path <paths>` to retrieve matching [context](../cyc-context/SKILL.md) and recipes; reuse an existing Scout result while it applies. Run relevant investigation recipes when their prerequisites hold and effects are authorized; otherwise explain the specific unavailable check. Consult project instructions, terminology and test layout as needed. Use the project's vocabulary, explaining a user/code naming difference once. The [project tools guide](../../docs/project-tools.md) covers discovery and execution.
|
|
15
|
+
2. **Find the real entry point.** The route, handler, command, event, or component where the behavior starts. Search for the user-visible string or the route first; it is usually faster than guessing file names.
|
|
16
|
+
3. **Trace the path end to end.** Entry, validation, state change, persistence, and what reads the result. Write it as a chain with file:line for each hop:
|
|
17
|
+
`click → Card.onFinish (Card.tsx:42) → store.update (store.ts:88) → saveAll (storage.ts:15)`
|
|
18
|
+
4. **Check the user's claims against the code.** If the user said "it saves to the server" and it writes localStorage, surface that contradiction immediately. It usually changes the plan.
|
|
19
|
+
5. **Observe when reading is ambiguous.** Run the code, print the stored value, or hit the endpoint. One observation beats three paragraphs of inference.
|
|
20
|
+
6. **Answer "why" honestly.** Look for commit messages, ADRs, or comments. Without them, label the reason as inference.
|
|
21
|
+
|
|
22
|
+
## Done when
|
|
23
|
+
|
|
24
|
+
- The path is written as a chain with a real location for every hop.
|
|
25
|
+
- Every claim the next step depends on is marked observed (you ran or saw it) or inferred (you read it).
|
|
26
|
+
- Contradictions between the user's description and the code are listed.
|
|
27
|
+
- For a bug: the diagnose branch's red loop exists and the cause is confirmed.
|
|
28
|
+
|
|
29
|
+
## Anti-patterns
|
|
30
|
+
|
|
31
|
+
| Name | The tell | Fix |
|
|
32
|
+
| --- | --- | --- |
|
|
33
|
+
| File tour | A list of files with one-line summaries | Write the chain of calls instead |
|
|
34
|
+
| Tests as truth | "The test says it works" | Tests show intent; run it to see behavior |
|
|
35
|
+
| Whole-repo read | Opening dozens of files before finding the entry point | Search for the visible string or route first |
|
|
36
|
+
| Fix before repro | Changing code for a bug that was never reproduced | Build the red loop first; reading code to find the repro conditions is fine |
|
|
37
|
+
|
|
38
|
+
## Handoff
|
|
39
|
+
|
|
40
|
+
For a change, pass the chain, observed facts, contradictions, and open questions to [Impact](../cyc-impact/SKILL.md). For an explanation or lesson, return the model to the parent. For a bug, hand the red loop and confirmed cause onward; do not fix unrelated things you noticed, but list them.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Diagnose a failure
|
|
2
|
+
|
|
3
|
+
Use this branch when something is broken, throwing, wrong, or slow. The rule: **no red loop, no fix.** Read code freely: understanding the code is often how you find the conditions that reproduce the bug. But do not change code to fix a bug you have not reproduced, and treat any theory as unconfirmed until the loop shows it.
|
|
4
|
+
|
|
5
|
+
## 0. Check the error ledger
|
|
6
|
+
|
|
7
|
+
Search the project's selected shared history (`run next`'s `projectLedgerPath`) and relevant prior run-local histories for the error signature (see the [error ledger skill](../../cyc-error-ledger/SKILL.md)). If an entry exists, start from its recorded attempts and never repeat a failed fix without a new reason.
|
|
8
|
+
|
|
9
|
+
## 1. Build a red loop
|
|
10
|
+
|
|
11
|
+
A red loop is one command you have already run that shows the user's exact symptom. It must be:
|
|
12
|
+
|
|
13
|
+
- **Red-capable:** asserts the actual symptom, not a nearby one.
|
|
14
|
+
- **Deterministic:** same result every run (or a measured failure rate for flaky bugs).
|
|
15
|
+
- **Fast:** seconds, not minutes, so you can iterate.
|
|
16
|
+
- **Agent-runnable:** no human clicking, unless nothing else works.
|
|
17
|
+
|
|
18
|
+
Try these in order:
|
|
19
|
+
|
|
20
|
+
1. An existing failing test, or a new failing test at the user's boundary
|
|
21
|
+
2. A `curl` or HTTP request against the running app
|
|
22
|
+
3. A CLI invocation with output diffed against a known-good snapshot
|
|
23
|
+
4. A headless browser script for UI symptoms
|
|
24
|
+
5. Replaying a captured request, log, or payload
|
|
25
|
+
6. A throwaway harness that calls the suspect function directly
|
|
26
|
+
7. `git bisect run` with the loop as the test, when "it used to work"
|
|
27
|
+
8. A differential loop: run old and new versions on the same input and compare
|
|
28
|
+
9. A human-in-the-loop script with exact steps and a KEY=VALUE result, as a last resort
|
|
29
|
+
|
|
30
|
+
If you cannot build any loop (the bug only happens in staging, or needs data you cannot access), do not guess at a fix. Continue with what is useful without one: read the code paths, check the error ledger and logs, and narrow the candidates. Then stop and hand off what you learned and ask for one specific thing: access to the environment, a redacted sample of the failing data, or permission to add temporary logging.
|
|
31
|
+
|
|
32
|
+
## 2. Shrink it
|
|
33
|
+
|
|
34
|
+
Remove inputs, steps, and code until every remaining piece is load-bearing: removing any one turns the loop green.
|
|
35
|
+
|
|
36
|
+
## 3. Hypothesize before testing
|
|
37
|
+
|
|
38
|
+
Write up to three ranked, falsifiable hypotheses before testing any: "If X is the cause, then changing Y makes the symptom disappear." Show them to the user as you go; don't wait for approval. When the red loop and the evidence point to one clear cause (a stack trace into a null field, a failing assertion on one line), one hypothesis is enough: state the evidence that makes it clear.
|
|
39
|
+
|
|
40
|
+
## 4. Test one variable at a time
|
|
41
|
+
|
|
42
|
+
Change one thing, rerun the loop, record the result in the error ledger entry, including failures. Tag every temporary log line with a unique marker such as `[DEBUG-7f3a]` so cleanup is one search.
|
|
43
|
+
|
|
44
|
+
## 5. Stop rules
|
|
45
|
+
|
|
46
|
+
- Two hypotheses disproved: step back, re-read the symptom, and check your loop asserts the right thing.
|
|
47
|
+
- Four disproved: report findings and ask the user before continuing.
|
|
48
|
+
|
|
49
|
+
## 6. Hand off
|
|
50
|
+
|
|
51
|
+
Give Build the red loop command, the confirmed cause with evidence, and the smallest fix location. The red loop becomes the regression test. If no clean place exists to test the fix, say so: that is a design finding, not something to hide.
|
|
52
|
+
|
|
53
|
+
Clean up: search for your debug marker and delete throwaway harnesses before handing off.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cyc-verify
|
|
3
|
+
description: "Prove the requested change works and nothing it touches broke, using checks you actually ran against the current files. Use before accepting any change, when asked \"does it work?\", after a repair, or when a handoff claims success."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Verify the promised outcome
|
|
7
|
+
|
|
8
|
+
For a new web interface or visual redesign, score the finished page with the [generic-tells sheet](../cyc-design/frontend-design/references/generic-tells.md#score-sheet) at desktop and phone width, then run the [experience review](../cyc-design/frontend-design/references/experience-review.md) against the decision sheet's rejection condition. A theme description, image presence and no clipping cannot establish design quality. If the criterion admits any default page, restore the original ambition before judging; never weaken it to fit the output. Keep a material visual miss unmet despite passing behavior checks. Inspect the main action and access/recovery states separately. Narrow repairs need only applicable checks.
|
|
9
|
+
|
|
10
|
+
For user updates, follow the shared [progress standard](../../docs/response-standard.md#progress-updates): explain which behavior the checks establish and what remains unverified, rather than reporting only pass counts. When a check fails, explain what it revealed and how that affects the next decision.
|
|
11
|
+
|
|
12
|
+
Help the engineer interpret the evidence: connect an important check to the path or consumer it exercises, the defect or rejected case it could detect, and the limit of that conclusion. Explain separately why the implementation fits the intended behavior; semantic review is a judgment, not an executed check. Follow the [engineering understanding standard](../../docs/response-standard.md#engineering-understanding-throughout-the-work).
|
|
13
|
+
|
|
14
|
+
For implementation, verify the changed behavior with executable checks. For advisory Review or Handoff, verify the claims and cited evidence without manufacturing a code change or failing test. An accurate report of a defect can satisfy a review criterion; it cannot satisfy a criterion that the product works. Follow the [handoff contract](../../docs/skill-contract.md) for evidence labels.
|
|
15
|
+
|
|
16
|
+
Apply the project's applicable `code-standards.md` and the relevant [code standards](../../docs/engineering/code-standards.md) to the actual diff and callers. Check information-bearing comments, justified assertions/suppressions, failure outcomes and useful structure; preserve legitimate exceptions. Record tool results separately from this semantic judgment. Reading the standards, a comment search or an unchecked checklist does not prove compliance.
|
|
17
|
+
|
|
18
|
+
## The core loop
|
|
19
|
+
|
|
20
|
+
0. **Use applicable recipes automatically.** Run `node <cli> recipe list --run <ID>` or `--path <affected paths>`. Read selected expected outcomes, prerequisites/effects and any relevant manual steps in `docs/context/verify-recipe.md`. Execute applicable authorized supplementary checks with `recipe run --recipe <ID>`; explain unavailable prerequisites or scope boundaries. Entries with `configuredCommandIds` are already owned by final configured verification: defer those to step 5 and cite that actual result, avoiding duplicate final execution. Old recipe receipts are diagnostic history. When nothing matches, discover the needed check through [references/recipe.md](references/recipe.md). Retain authorized reusable steps before final verification; document/CLI work does not require a browser recipe.
|
|
21
|
+
1. **Build the check matrix first.** One row per acceptance criterion and one row per consumer named in the plan (or the [impact map](../cyc-impact/SKILL.md) in the detailed chain). Each row names the check that would show it *red* if it were broken. A row with no red-capable check is a gap; record it now, not at the end.
|
|
22
|
+
2. **Establish the appropriate test proof.** For features and bugs, check that the regression test fails on the original code for the intended reason and passes on the candidate. For refactors, characterization tests must pass on both. In a managed run, `run finish` runs `prove-red` when the proof is missing or outdated; run `run prove-red` yourself for an earlier check, and inspect its receipt. Do not manually revert shared working files. New runs retain permitted originals through Git and/or bounded run-start capture, including plain/no-commit projects; older runs cannot gain a capture after edits. Missing or changed needed originals refuse proof. Use a quiescent working folder: the project operation lock coordinates controllers, while external edits are checked only at boundaries. On a conflict or interruption, use `run recover`, preserve current files/locks and the recorded candidate backup, and compare deliberately; never clear locks, overwrite another writer or reset a halted run to force proof. See [ownership and recovery](../../docs/onboarding-recovery.md#proof-conflicts-and-interrupted-ownership). The aggregate proof establishes that at least one new test detects changed behavior, not that every test does. Existing-behavior guards may stay green. For advisory claims, inspect primary evidence and reproduce findings where feasible; no manufactured red test is required. If proof is unavailable, record the actual limitation and alternative evidence through the supported assessment exemption; never describe it as proven or disguise testable behavior as untestable. See [run-start originals](../../docs/runtime.md#run-start-originals).
|
|
23
|
+
3. **Run the journey, not only the unit.** Run the recipe's checks that apply to this change first. For anything the recipe doesn't cover, pick the tightest loop that exercises the real path, in this order of preference:
|
|
24
|
+
1. the project's existing test for that behavior
|
|
25
|
+
2. a new focused test at the boundary the user touches
|
|
26
|
+
3. a script or CLI call with a snapshot or diff of output
|
|
27
|
+
4. an HTTP request (`curl`) against the running app
|
|
28
|
+
5. a headless browser such as Playwright for UI journeys (click, reload, check again)
|
|
29
|
+
6. a human-in-the-loop step, as a last resort, with exact instructions and the expected observation
|
|
30
|
+
4. **Hit the edges the change created.** Old saved data, repeat actions (clicking twice), unknown IDs, empty state, and the error path. For a guard, show a rejected case, not only an allowed one.
|
|
31
|
+
5. **Run configured checks on the final candidate.** For step-by-step execution use `run verify --run <ID>`; the fast implementation route's `run finish` executes these checks itself. Do not run both on an unchanged candidate merely to duplicate a receipt. Advisory routes without configured checks use clearly labeled inspected evidence. Focused checks give fast feedback; final checks cover the affected behavior.
|
|
32
|
+
6. **Fill the matrix with results.** Each row: passed (with the command and what you saw), failed (with output), or unverified (with why, such as no browser access). Model review of code goes in its own labeled row and never turns a row green.
|
|
33
|
+
7. **Record semantic review separately.** Trace the important state, shared invariant, consumers and relevant failure paths in the actual diff; identify where a likely next change belongs. Review intent, conventions and the [engineering principles](../../docs/principles.md), using the [finding adjudication guidance](../../docs/code-quality.md#review-findings-before-turning-them-into-edits) for consequential diffs. For changed business rules/transitions, inspect the owner and callers using the [domain examples](../../docs/engineering/domain-design.md); for rejection, I/O or partial effects, inspect failure identity, committed/unknown state and retry safety using the [failure examples](../../docs/engineering/failure-handling.md). Apply their stated contracts and exceptions rather than requiring their exact code shape. Show the legitimate trigger or concrete maintenance consequence before requiring a repair; check whether a proposed simplification removes policy duplication or merely moves it. Resolve or dismiss findings with evidence, and keep unresolved required findings open and blocking. New implementation runs require the [Verify assessment](../../docs/work-assessments.md#verify-executable-evidence-plus-semantic-judgment), with a passing check for every Scout consumer and newly discovered consumer. Label self-review; extra reviewers depend on risk. If final context/ledger edits change source, rerun checks before recording the assessment.
|
|
34
|
+
|
|
35
|
+
## Done when
|
|
36
|
+
|
|
37
|
+
Applicable checks have captured evidence, every criterion and affected consumer has a result, and every passing claim cites evidence for the current file state. Changed behavior has the required red/green proof; refactors have preservation evidence; exemptions and advisory observations remain labeled. If a required criterion is failed or unverified, do not record a passing stage: route it using the table below. A review can report defects successfully when its criteria ask for supported findings rather than a working product.
|
|
38
|
+
|
|
39
|
+
**Suspect the observation before the system.** When a result surprises you, first check that the check itself measures the right thing (right port, right build, right data).
|
|
40
|
+
|
|
41
|
+
**Pre-existing failures.** Normal runs do not run a baseline before editing. A project may explicitly enable `verification.baseline: true` for diagnostic background measurements; do not wait for them. For bug fixes and features without one, the proof's control run measures every check on the run-start code. An unrelated check that already failed there can be accepted with a reason, in `run finish` (`acceptFailures`) or with `run accept-failure`. It no longer blocks completion while it fails exactly as it did then, and another check passes. "Exactly" means the same exit code, the same output lines apart from timings, and no file you changed named in its output.
|
|
42
|
+
|
|
43
|
+
For a TAP (`node --test`, `tap`), mocha, or jest suite, "exactly" means all of these, also for output longer than the 32,000 characters kept, provided a test in it already failed at the run start:
|
|
44
|
+
- no test fails that did not fail then;
|
|
45
|
+
- every old failure has the same error, and its stack does not run through source you changed;
|
|
46
|
+
- no new non-test line appears. A failed verification lists `failedAtRunStart`: decide for each check whether it is unrelated (accept it) or caused by your change (fix it). Do not retry unchanged. Name it in the reply as a pre-existing failure. New regressions can hide inside the same command. Any of these still leaves verification unverified, with the cause in `acceptedFailuresThatChanged`:
|
|
47
|
+
- a new or lost line;
|
|
48
|
+
- a different exit code or a hang;
|
|
49
|
+
- truncated output;
|
|
50
|
+
- a check that prints nothing. Report a blocked handoff when the failure cannot be repaired within scope. Do not change configuration or drop tests mid-run to obtain success.
|
|
51
|
+
|
|
52
|
+
## Anti-patterns
|
|
53
|
+
|
|
54
|
+
| Name | The tell | Fix |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| Green-by-reading | "The logic looks correct" with no command run | Run something that could fail |
|
|
57
|
+
| Tautological test | The expected value is computed the same way the code computes it | Assert a literal known-good value |
|
|
58
|
+
| Hollow test | It would still pass if every imported function returned `undefined` | Assert on real output, not on mocks or fixtures |
|
|
59
|
+
| Wrong surface | Checked the API when the user asked about the page | Verify where the user sees the behavior |
|
|
60
|
+
| Unit-only for a journey | Component test passes; nobody reloaded the page | Add the journey check from step 3 |
|
|
61
|
+
| Retry until green | Rerunning a flaky test until it passes | Diagnose the flake or mark unverified |
|
|
62
|
+
| Stale evidence | Result is from before the last edit | Rerun after the final change |
|
|
63
|
+
|
|
64
|
+
## Routing failures
|
|
65
|
+
|
|
66
|
+
Read `run recover --run ID` after a verification failure or interruption. Failed receipts remain diagnostic even when current verification has been invalidated. Describe the specific failed behavior, the cause only as far as the evidence supports it, and the next justified action. Executable-not-found and timeout observations do not by themselves diagnose the application. Use the existing review and receipt when teammate help is needed; never automatically message someone or start a new budget after exhaustion. See [recovery guidance](../../docs/onboarding-recovery.md).
|
|
67
|
+
|
|
68
|
+
In fast playbooks (scout → build → verify → deliver), Frame, Impact, and Design map to Scout. Before an authorized implementation repair, use `run retry --run <ID> --stage build --reason "<finding>"`, record the repaired artifacts, and verify again. Return to Scout when a missed consumer or invalid approach changes the plan. Advisory routes report the finding unless repairs are authorized. Changes after a passing Verify handoff require returning to Verify with fresh checks and semantic review before delivery; implementation repairs return through Build first.
|
|
69
|
+
|
|
70
|
+
| What you saw | Send it to |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| Right design, wrong code | [Build](../cyc-build/SKILL.md) with the failing command |
|
|
73
|
+
| A consumer nobody mapped broke | [Impact](../cyc-impact/SKILL.md), then affected work |
|
|
74
|
+
| The approach cannot meet a criterion | [Design](../cyc-design/SKILL.md) with the disproved assumption |
|
|
75
|
+
| The criterion measures the wrong thing | [Frame](../cyc-frame/SKILL.md), keeping the failed result on record |
|
|
76
|
+
| Missing access or service | Blocked, naming the smallest thing the user can provide |
|
|
77
|
+
|
|
78
|
+
Never edit thresholds, skip tests, or loosen criteria to pass. When a recipe check fails, fix the cause and rerun the whole applicable set: this is the loop, and it runs without the user pointing anything out.
|
|
79
|
+
|
|
80
|
+
**Retain missing checks without changing the contract.** Save proposed checks in `.cyc/runs/<runId>/proposed-checks.json` when durable recipe edits are outside scope. Never edit `.cyc/config.json` during an active run. Promote authorized proposals in a subsequent scoped change and verify that change; edits after completion are not covered by the completed run's evidence. Do not ask for permission again when the user already authorized that follow-up.
|
|
81
|
+
|
|
82
|
+
## Example
|
|
83
|
+
|
|
84
|
+
Homework "mark finished": the matrix has rows for the click, the active list, the remaining count, reload persistence, old saved records without a `finished` field, and double-marking. The new persistence test is first run against the unmodified save code and fails, proving it can catch the bug. After the fix it passes, and a reload check in the browser confirms it. The row for cross-device sync stays out of the matrix because it was never requested.
|
|
@@ -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.
|