@haaaiawd/skeinn 0.0.0-stage → 2.4.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/CHANGELOG.md ADDED
@@ -0,0 +1,90 @@
1
+ # Changelog
2
+
3
+ ## 2.4.0
4
+
5
+ - Upgraded Evil Eval (`skeinn eval scaffold`) to a 3-tier budget-aware pyramid (`probe` ¥2–5, default 3-baton zero-memory `relay` ~¥20, and `full`), adding per-baton prompts, `hidden-oracle.mjs`, `telemetry-template.json`, and Pairwise Forced-Choice (`X_CLEAR_WIN | TIE | Y_CLEAR_WIN`) blind judging.
6
+ - Renamed project, CLI binary, and state directory from LOOM/`.loom/` to Skeinn (`@haaaiawd/skeinn`, `skeinn`, `.skeinn/`), with a legacy `.loom/` migration guard and minimalist 3-element SVG brand assets.
7
+ - Redesigned Capability into a low-friction, high-substance single-file workflow (`.skeinn/capabilities/<slug>.md`): replaced the 4-command decision-tree ceremony (`add → research → synthesize → confirm` + `research/` folder) with one command (`skeinn capability add <slug> --title <field> [--mode external_researched|codebase_grounded|offline_reflection]`) and a natural three-part flow: **How real practitioners operate** (with verifiable external sources), **Reflection for this project**, and **Operational rules and Design delta** (Before → After).
8
+ - Closed anti-laziness loopholes at `skeinn project ready` and `skeinn check`: silent Capability omission is now rejected (projects must add 1–3 bottleneck capabilities or explicitly record `skeinn capability exempt --reason <text>`, which Keeper audits); `external_researched` capabilities reject `agent-authored` / self-authored filler and missing `Design delta`; offline runs must declare `Mode: offline_reflection` honestly and stay visibly marked.
9
+ - Upgraded core Design templates (`product`, `experience`, `system`, `contract`) with **Applied capabilities**, **Alternatives considered** (requiring at least two genuinely viable options, no strawmen), and **How this could look done yet fail**.
10
+ - Removed the mandatory per-Task `capability_hooks` ceremony tax and added lightweight `guardrails[]` injected directly into active Task context (legacy `capability_hooks` remain supported).
11
+ - Added **Anti-laziness audit** to the independent Keeper prompt (auditing unjustified exemptions, fake research, zero-delta capabilities, strawman Design options, and dropped guardrails).
12
+ - Fixed a latent bug in `startTask` dependency checking (`item.status === 'done'`) and added stale-downstream `needs_recheck` warnings in `skeinn check` when an upstream Task is reopened.
13
+ - Included `STRUCTURE.md` and `capability_exemption` in `projectDigest`.
14
+
15
+ ## 2.3.0
16
+
17
+ - Clarification rounds: `skeinn clarify start --reason` pauses material work when the human changes direction; answers and new frontier questions (each carrying a persisted recommendation) record through `skeinn clarify resolve --json-file`, and `skeinn clarify close` refuses until every question is resolved or deliberately skipped — then cascades into `skeinn decision`, document updates, and Task impact warnings.
18
+ - Clarification guidance is wired into `skeinn --help`, `skeinn help clarify`, `skeinn clarify --help`, the runtime and execution protocols, the AGENTS.md anchor, and context recommendations; an open round becomes the top recommendation and lists current frontier questions with their recommendations.
19
+ - `skeinn context` is lean by default: it returns the state header, shaping state, PROJECT.md, STRUCTURE.md, and active Task context without re-injecting the ~190-line static protocol (~1.4k tokens saved per repeat call). `skeinn context --full` restores the complete protocol; lean output points first-entry and post-reset Agents at it, and `--keeper` always stays full.
20
+ - The capability quality bar (nodes need a source citation and a counterexample) is visible in the lean state block, not only in the full protocol.
21
+
22
+ ## 2.2.0
23
+
24
+ - Shaping-path guidance: `skeinn --help` now states what each shaping step buys and what skipping costs, and names conceptual help topics.
25
+ - `skeinn help <concept>` (`shaping`, `design`, `capability`, `task`, `deliverable`) gives each artifact a short purpose-plus-pointer; bare subcommands like `skeinn capability` and `skeinn design --help` land on the same pointers instead of a usage error.
26
+ - Shaping commands return an additive `next` field chaining the lifecycle: init → record → capability add/research/synthesize/confirm → design add → deliverable → task plan → project ready; `skeinn task start` points back at `skeinn context`.
27
+ - `skeinn context` during shaping names the actual unfinished frontier — template PROJECT.md, missing or templated design documents, capability lifecycle states, open high-impact questions, empty Work Map — instead of a generic keep-shaping sentence.
28
+ - Capabilities now precede design in every guided path: dossier decision trees produce the design decisions, so design documents are written informed by confirmed dossiers.
29
+ - `skeinn init` output lists the `AGENTS.md` anchor it installs (omitted correctly in sidecar mode).
30
+
31
+ ## 2.1.3
32
+
33
+ - Removed Keeper auto-pass: every still-open finding must be closed with evidence in a later independently attested pass. A changed project digest proves a change, not that findings were resolved.
34
+ - `skeinn task start` now requires an independently attested Keeper pass (`review.mode: "independent"`) or a recorded `skeinn keeper skip`; `skeinn check` reports an unattested legacy pass as an error instead of a quiet warning.
35
+ - Keeper findings are cumulative across attempts: a passing record must carry `closure_results` for every gap still open from earlier rounds.
36
+ - Task references are verified, not just non-empty: `implements` must resolve to an existing design file and section (or a decision name present in project truth), and `capability_hooks` must resolve to an existing dossier and node. `skeinn project ready` runs this integrity check.
37
+ - `skeinn context` lists each blocked Task with its reason and recovery conditions, and recommends `skeinn task reopen <id> --reason` when nothing is executable.
38
+ - Done Tasks resist silent rewrites: `skeinn task update` on a done Task is rejected with a reopen pointer, and reopening a blocked Task requires a concrete reason describing how the recovery conditions were met.
39
+ - Decision-affected done Tasks warn only until re-verified: reopening and re-completing the Task after the decision clears the warning.
40
+ - Deliverable coverage now distinguishes planned from delivered: units covered only by open or blocked Tasks no longer count as delivered.
41
+ - `skeinn record --help` documents `resolved` and `retire_assumptions` so Agents can close questions and assumptions they opened.
42
+ - Planning new Tasks on a completed project returns status to `building`; `skeinn context` no longer claims "all done" while new Tasks are open.
43
+
44
+ ## 2.1.2
45
+
46
+ - Added environment-aware clarification through `skeinn context --human-channel available|unavailable`. Unattended Agents inspect first, research only permitted objective facts, and then use bounded assumptions or blocks rather than fabricating users or substituting web search for intent.
47
+ - Added `--state-dir <outside-workspace-dir>` sidecars for isolated benchmark and sandbox runs. Sidecars preserve virtual `.skeinn/` Task references without mutating the scored workspace or its `AGENTS.md`.
48
+ - Added equal human-channel controls and unattended condition prompts to Evil Eval scaffolding.
49
+ - Added explicit capability authority provenance: human selections become confirmed, while Agent selections remain visibly provisional until human confirmation.
50
+ - Required independent Keeper review provenance for a passing handoff; known self-review can no longer be recorded as an independent pass.
51
+ - Added Task integrity enforcement for design links, capability hooks or explicit exemptions, plus declared output existence checks before completion.
52
+ - Added command-specific canonical JSON help and recovery pointers for every structured-write command.
53
+ - Updated generated Agent guidance and both public READMEs so installed and source-checkout invocation paths are unambiguous.
54
+
55
+ ## 2.1.1
56
+
57
+ - Re-published 2.1.0 content with corrected CHANGELOG line endings.
58
+
59
+ ## 2.1.0
60
+
61
+ - Added a current-state and recommended-action header to `skeinn context` output. Agents entering a project or resuming after compression now see project status, active task, work-map counts, and a recommended next action before the full protocol. The recommendation is advisory, not a script.
62
+ - Rewrote `AGENTS.md` with explicit Skeinn trigger conditions (project entry, context reset, before substantial work, between Tasks) and a standard work rhythm that keeps Agent judgment while making the next step obvious.
63
+ - Integrated Crux integrity-chain review into the Keeper handoff. The Keeper now checks that responsible intent, project promises, design and capability decisions, Work Map, executable behavior, and human feedback loop form an intact chain, and looks for omission, substitution, drift, unsupported leaps, blindness, and ownerless gaps.
64
+ - Added staged visibility and review guidance to the project template and active-Task execution protocol. Tasks should prefer human-visible acceptance evidence, the Agent should show real working things at milestones, run `skeinn check` and project tests together before declaring a batch done, and prioritize reaching an exciting surface early to sustain the human's momentum.
65
+ - Strengthened capability source validation: `skeinn capability synthesize` now requires each decision-tree node's `source:` citation to reference a real `.md` file in the dossier's `research/` directory.
66
+ - Added `research/_guide.md` generation in `skeinn capability research` so Agents know what good research material looks like, what to avoid, and how to cite sources.
67
+ - Added `.skeinn/STRUCTURE.md` as a fifth project-truth layer declaring where source code, tests, docs, assets, and configuration files live. `skeinn check` warns when it is missing or still templated.
68
+ - Added `skeinn decision --json-file` for recording consequential superseding decisions with affected files and tasks. `skeinn check` warns when a done Task is marked affected by a later decision.
69
+ - Added `acceptance[]` as the primary Task completion structure, pairing `criterion`, `verify_by`, and `evidence`. Legacy `done_when[]` remains supported.
70
+ - Added Keeper auto-pass: when all Keeper gaps are minor and 3 or fewer, fixing them and running `skeinn project ready` auto-passes without another Keeper round. (removed in 2.1.3)
71
+ - Added deliverable coverage tracking through `skeinn deliverable add` and Task `covers` field. `skeinn check` reports uncovered delivery units.
72
+ - Added `skeinn capability research → synthesize → confirm` lifecycle with status tracking per dossier.
73
+ - Updated help text with a typical first-pass flow and capability lifecycle sequence.
74
+
75
+ ## 2.0.1
76
+
77
+ - Added an active-Task execution protocol that restores workspace-aware coding guidance, risk-based testing, restartable progress, criterion-level proof, and conditional commit/PR boundaries after context resets.
78
+ - Strengthened the generated `AGENTS.md` anchor so Agents reload Skeinn at project entry, after context loss, and before resumed editing without invoking it before every tool call.
79
+
80
+ ## 2.0.0
81
+
82
+ - Rebuilt Skeinn as invisible Agent infrastructure around project understanding, a scalable design-document graph, separate professional-field dossiers, a broad Work Map, and one active Task.
83
+ - Replaced fixed roles and stages with an adaptive clarification protocol and explicit convergence conditions.
84
+ - Added human-editable project truth, structured continuity state, and superseding decision history.
85
+ - Added context selection that keeps very large Task maps on disk and injects only the active horizon.
86
+ - Added seven adaptable design-document templates and `skeinn prompts` as a complete live prompt inventory.
87
+ - Reduced Keeper to one independent build-readiness handoff with revision, changed-digest, fresh-run, and stale-state enforcement.
88
+ - Added controlled Evil Eval scaffolding for equal-condition, repeated, reset-heavy blind comparison.
89
+ - Added bilingual English/Chinese release documentation and a flat, minimal visual system with editable loop diagrams.
90
+ - Deliberately stopped automatic mutation of legacy `.skeinn/v1` projects.
@@ -0,0 +1,37 @@
1
+ # Contributing to Skeinn
2
+
3
+ Skeinn should become simpler when it changes. A contribution is strongest when it preserves the natural
4
+ human–Agent conversation, keeps project truth inspectable on disk, and proves its effect without adding
5
+ another ritual.
6
+
7
+ ## Before changing code
8
+
9
+ 1. Read [the system design](design.md) and [the UX loop](docs/UX_FLOW.md).
10
+ 2. Run the current suite and CLI locally:
11
+
12
+ ```bash
13
+ npm test
14
+ node cli/bin/skeinn.js --help
15
+ node cli/bin/skeinn.js prompts
16
+ ```
17
+
18
+ 3. Keep a change inside one observable problem. If a contract or stored shape changes, update its design,
19
+ prompt, help text, and tests together.
20
+
21
+ ## Pull requests
22
+
23
+ A useful pull request explains:
24
+
25
+ - the user or Agent failure it fixes;
26
+ - the smallest complete change that fixes it;
27
+ - the exact command or artifact that proves the result;
28
+ - any compatibility, migration, or unverified boundary.
29
+
30
+ Prompt changes must remain visible through `skeinn prompts` and be reflected in
31
+ [`docs/PROMPT_CATALOG.md`](docs/PROMPT_CATALOG.md). Changes that claim better quality need a baseline-relative
32
+ proof; a nicer-looking output alone is not evidence that Skeinn caused the improvement.
33
+
34
+ ## Release checks
35
+
36
+ Run `npm test` and `npm pack --dry-run` before requesting release. See the
37
+ [release checklist](docs/RELEASE_CHECKLIST.md) for the maintainer flow.
package/EVIL_EVAL.md ADDED
@@ -0,0 +1,84 @@
1
+ # Evil Eval v2 — 三层高性价比评测体系
2
+
3
+ Evil Eval 只回答一个冷酷的问题:**Skeinn 到底有没有在真实项目里显著提升 Agent 的交付质量,还是只是多写了一堆看起来很严谨的文档?**
4
+
5
+ 为了既保证科学对照、又能以 **单次 ~¥20 人民币(适配 DeepSeek 4.1 Flash 等高性价比快模型)** 的成本高频跑起来,Evil Eval 按成本和用途拆成三层:
6
+
7
+ | 层级 | 命令模式 | 单次参考预算 | 适用时机 | 判定机制 |
8
+ | :--- | :--- | :--- | :--- | :--- |
9
+ | **L1:微探针(Micro-Probe)** | `mode: "probe"` | **¥2–¥5** | 每次改 `protocol.js` / `store.js` 后 | 5 项硬断言 Pass/Fail(防偷懒、禁伪调研、设计对撞、CLI 零摩擦、冷启动首步) |
10
+ | **L2:三棒盲接力赛(Relay Eval,主力推荐)** | `mode: "relay"` | **¥15–¥20** | 每个小版本 / 核心改动验收 | **3 棒零记忆接力 + 中途需求反转 + 隐藏自动化断言(Hidden Oracle)+ 三选一盲评 + 真实遥测** |
11
+ | **L3:完整发布评测(Full Eval)** | `mode: "full"` | **¥50–¥60** | 大版本发布前 / 消融实验 | 3 次重复 + 全量盲评 + 消融对照 |
12
+
13
+ ---
14
+
15
+ ## 核心对照组(绝不削弱基线)
16
+
17
+ 每个场景同时跑两条臂(Arm):
18
+ - **Baseline**:同等模型、工具、工作区、用户回答与预算,**无 Skeinn**(允许其自由规划、写文档、用自身记忆)。
19
+ - **Skeinn**:完全相同的模型与条件,仅允许后台静默使用 `skeinn` CLI。
20
+
21
+ ---
22
+
23
+ ## 主力推荐:~¥20 人民币的 L2 三棒盲接力赛(`mode: "relay"`)
24
+
25
+ 单轮原型任务很难拉开裸 Agent 与框架的差距。Skeinn 真正的护城河在**跨多次失忆接棒、中途推翻决策与专业域避坑**。一轮完整 L2 Relay 恰好把预算花在刀刃上:
26
+
27
+ 1. **第 1 棒(塑形 + 纵向切片 1)**:两条臂分别拿到同一份原始需求,完成初步设计与第一个可运行切片。
28
+ 2. **第 2 棒(清空上下文 + 中途方向反转)**:强制开启**零聊天记忆的新 Agent**,只读磁盘恢复项目,并注入一条实质性的中途需求变更(`pivot`),要求不破坏第 1 棒已成立的不变量。
29
+ 3. **第 3 棒(清空上下文 + 边界加固与收口)**:再次开启**零记忆新 Agent**(可选降级为更轻模型测试交接韧性),补齐边界条件、运行验证并诚实报告盲点。
30
+
31
+ ### ¥20 预算怎么分配(以 Flash 级快模型为例)
32
+ - **Baseline 3 棒**:约 ¥4–¥6
33
+ - **Skeinn 3 棒(含 1–2 个瓶颈 Capability 与 1 次独立 Keeper)**:约 ¥8–¥10
34
+ - **Hidden Oracle 自动化验收(`hidden-oracle.mjs`)**:**¥0**(纯本地 Node 脚本,客观零偏见)
35
+ - **双顺序盲评裁判(X→Y 与 Y→X 各一次)**:约 ¥2–¥3
36
+ - **合计**:稳定控制在 **¥15–¥20 / 次**,既不因省钱缩水到没参考意义,也不会重到跑不动。
37
+
38
+ ---
39
+
40
+ ## 为什么废除 1–5 分制,改用“隐藏断言 + 三选一盲评 + 真实遥测”?
41
+
42
+ 1. **隐藏断言脚本(`hidden-oracle.mjs`)**:Agent 施工期间完全不可见,收尾后直接跑客观检查(文件/契约存在性、零外链扫描、重启恢复、回归破损率),彻底消灭“嘴上说完成了”。
43
+ 2. **强制三选一盲评(Pairwise Forced-Choice)**:废除容易打出 4 vs 5 贴脸分的 1–5 分制。裁判对 6 个维度只输出 **`X_CLEAR_WIN` / `TIE` / `Y_CLEAR_WIN`**,并强制交换顺序(X→Y 与 Y→X)复评,凡是翻转的结论一律标 **`UNSTABLE`**。
44
+ 3. **真实遥测落盘(`telemetry-template.json`)**:强制记录每条臂的真实 `input_tokens`、`output_tokens`、`cost_cny`、`wall_seconds`、`tool_calls`、`cli_retries` 与 `hidden_oracle_passed`,直接计算**每元人民币换来的净质量提升**。
45
+
46
+ ---
47
+
48
+ ## 快速生成一个评测脚手架
49
+
50
+ 准备 `scenario.json`:
51
+
52
+ ```json
53
+ {
54
+ "id": "RELAY-001",
55
+ "title": "本地离线复盘工具三棒接力",
56
+ "mode": "relay",
57
+ "budget_cny": 20,
58
+ "brief": "做一个单文件本地离线的会议后 3 分钟复盘工具,刷新保留草稿,支持一键清空。",
59
+ "pivot": "第 2 棒中途新增:用户要求支持本地加密 JSON 导出与导入,但仍必须 100% 离线零外链。",
60
+ "hidden_checks": [
61
+ "静态扫描零外部 HTTP/CDN/字体请求",
62
+ "刷新后草稿完整恢复,一键清空后存储归零",
63
+ "加密导出再导入后数据无损且错误密码被诚实拒绝"
64
+ ],
65
+ "human_channel": "unavailable",
66
+ "success_criteria": ["三棒零记忆接力后全部隐藏断言通过且无回归破损"]
67
+ }
68
+ ```
69
+
70
+ 运行:
71
+
72
+ ```bash
73
+ skeinn eval scaffold --json-file scenario.json
74
+ ```
75
+
76
+ Skeinn 会在 `.skeinn/eval/<scenario>/` 下自动生成:
77
+ - `manifest.json`(控制变量与预算上限)
78
+ - `batons/baseline-baton-{1,2,3}.md` 与 `batons/skeinn-baton-{1,2,3}.md`(可直接喂给各棒新会话的提示词)
79
+ - `hidden-oracle.mjs`(填入你的客观断言脚本)
80
+ - `telemetry-template.json`(成本与重试遥测模板)
81
+ - `judge-prompt.md`(双顺序三选一盲评裁判提示词)
82
+ - 若 `mode: "probe"`,额外生成 `probe-checklist.md`(5 项 L1 防偷懒硬检查清单)。
83
+
84
+ > 无人值守运行 Skeinn 臂时,请配合 `--state-dir <工作区外目录>` 与 `--human-channel unavailable`,确保 `.skeinn/` 状态不污染被评测工作区。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 haaaiawd
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,165 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="docs/brand/skeinn-wordmark-dark.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="docs/brand/skeinn-wordmark-light.svg">
6
+ <img alt="Skeinn" src="docs/brand/skeinn-wordmark-light.svg" height="64">
7
+ </picture>
8
+
9
+ <p><strong>Remember the whole. Build like a practitioner.</strong></p>
10
+ <p>Invisible continuity, firsthand practitioner judgment, and proof infrastructure for AI coding agents.</p>
11
+
12
+ <p>
13
+ <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a> ·
14
+ <a href="design.md">System Design</a> ·
15
+ <a href="EVIL_EVAL.md">Evil Eval</a> ·
16
+ <a href="CHANGELOG.md">Changelog</a>
17
+ </p>
18
+
19
+ <p>
20
+ <img src="https://img.shields.io/badge/node-%E2%89%A518-17212B?style=flat-square" alt="Node.js 18+">
21
+ <img src="https://img.shields.io/badge/for-AI%20Coding%20Agents-3B63F6?style=flat-square" alt="For AI Coding Agents">
22
+ <img src="https://img.shields.io/badge/languages-Multilingual-17212B?style=flat-square" alt="Multilingual">
23
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9AD8C2?style=flat-square&amp;labelColor=17212B" alt="MIT License"></a>
24
+ </p>
25
+
26
+ </div>
27
+
28
+ ---
29
+
30
+ ## Why Skeinn?
31
+
32
+ AI coding feels effortless on small scripts, yet multi-day, multi-module projects under unstructured Vibe Coding reliably hit four walls:
33
+
34
+ | Failure mode | Unstructured Vibe Coding | Agent backed by Skeinn |
35
+ | :--- | :--- | :--- |
36
+ | **Context amnesia** | Compaction or a new session wipes out architecture, boundaries, and earlier corrections | Project truth, decisions, progress, and proof live on disk; a fresh Agent resumes directly |
37
+ | **Generic average output** | Models default to safe statistical averages that look templated and amateur | Targets 1–3 bottleneck domains, **researches how real practitioners operate**, and reflects on project constraints |
38
+ | **First-draft lock-in** | Codes the first plausible idea immediately, hiding expensive rework | Core designs force **at least 2 genuinely viable alternatives** (including a simpler or unconventional angle) |
39
+ | **False-green completion** | Claims "done" while missing files, skipping edge cases, or breaking upstream work | A **fresh independent Keeper** audits build-readiness once; every Task closes with reproducible evidence |
40
+
41
+ > **Core rule: Skeinn is for the Agent, not the human.**
42
+ > Multilingual by default — talk naturally in English, Chinese, Japanese, or any language you prefer. The Agent operates the `skeinn` CLI silently in the background.
43
+
44
+ ---
45
+
46
+ ## How a real project flows
47
+
48
+ ```text
49
+ You (natural chat in any language) Agent (silent skeinn CLI on disk)
50
+ ─────────────────────────────────────────────────────────────────────────
51
+ 1. Share an early idea Inspect workspace → ask one dense
52
+ "Build an offline reflection tool..." batch of consequential questions
53
+
54
+ 2. Settle key tradeoffs Anchor PROJECT.md → iterate core
55
+ Design docs & 1–3 bottleneck
56
+ Capabilities (practitioner research
57
+ → reflection → Design delta)
58
+
59
+ 3. Confirm the whole Freeze digest → fresh zero-memory
60
+ Keeper audits startability, fake
61
+ research, strawmen, and guardrails
62
+
63
+ 4. See working slices, steer anytime Execute one restartable Task at a
64
+ time with guardrails & exact proof;
65
+ direction shifts flag stale work
66
+ ```
67
+
68
+ ---
69
+
70
+ ## What real Skeinn artifacts look like
71
+
72
+ Example: building a **3-minute offline post-meeting reflection tool**.
73
+
74
+ ### 1. Bottleneck capability (`.skeinn/capabilities/reflective-ux.md`)
75
+
76
+ ```markdown
77
+ # Reflective UX Design
78
+ - Mode: external_researched
79
+ - Authority: human_confirmed
80
+
81
+ ## How real practitioners operate
82
+ - Progressive disclosure with low-cognitive-load single-column flows — Source: https://linear.app/method
83
+ - Local-first tools surface storage boundaries and instant deletion upfront — Source: https://localfirstweb.dev/
84
+
85
+ ## Reflection for this project
86
+ - What to refuse: streaks, mood scores, and timers create assessment anxiety right after a tense meeting.
87
+ - Non-obvious craft move: mirror the user's own phrasing and let them pick one small next step instead of AI lecturing.
88
+
89
+ ## Operational rules and Design delta
90
+ - Anti-patterns: countdown timers, emotion ratings, silent network requests
91
+ - Design delta (Before -> After): Replaced 3-pane dashboard with a skippable 4-step single-column flow + upfront clear control.
92
+ ```
93
+
94
+ ### 2. Decision-collision design (`.skeinn/design/first-use-flow.md`)
95
+
96
+ ```markdown
97
+ ## Alternatives considered
98
+ - Option A (chosen): Single self-contained HTML file + localStorage (zero install, instant open, provably offline).
99
+ - Option B (rejected): Vite + local SQLite server. More extensible, but breaks zero-friction 3-minute use.
100
+
101
+ ## How this could look done yet fail
102
+ - Tests pass, yet a remote Google Font leaks network traffic or page reload silently drops an in-progress draft.
103
+ ```
104
+
105
+ ### 3. Restartable Task with guardrails (`.skeinn/tasks.json`)
106
+
107
+ ```json
108
+ {
109
+ "id": "TASK-001",
110
+ "title": "Build offline reflection flow and instant local wipe",
111
+ "implements": ".skeinn/design/first-use-flow.md#Alternatives considered",
112
+ "guardrails": [
113
+ "Zero external network requests, remote fonts, or analytics scripts",
114
+ "No emotion scoring, timers, or mandatory completion locks"
115
+ ],
116
+ "acceptance": [
117
+ {
118
+ "criterion": "Static scan finds zero external URLs; reload restores draft; clear wipes storage",
119
+ "verify_by": "Run node tests/verify.mjs and verify reload/clear in browser",
120
+ "evidence": "verify.mjs: 0 external URLs; reload restored draft; clear wiped localStorage"
121
+ }
122
+ ]
123
+ }
124
+ ```
125
+
126
+ ---
127
+
128
+ ## Quick start
129
+
130
+ ```bash
131
+ npm install --global @haaaiawd/skeinn
132
+ ```
133
+
134
+ Open your coding Agent (Claude Code, Cursor, Windsurf, Codex, etc.) in your project directory and say:
135
+
136
+ > "This project uses Skeinn for continuity and design quality. Run `skeinn init` and `skeinn context --full` to load the protocol; talk to me naturally and maintain state silently in the background."
137
+
138
+ <details>
139
+ <summary><strong>Agent CLI quick reference (for Agents, not humans)</strong></summary>
140
+
141
+ ```bash
142
+ skeinn init
143
+ skeinn context --full # first entry or after context reset
144
+ skeinn context # lean resume between Tasks
145
+ skeinn record --json-file understanding.json
146
+ skeinn design add core --title "Core system" --kind system
147
+ skeinn capability add ui-ux --title "UI/UX design" --mode external_researched
148
+ skeinn capability confirm ui-ux --scenario "<project scenario>" --source human
149
+ skeinn capability exempt --reason "<why standard engineering suffices>"
150
+ skeinn deliverable add cli-core --title "CLI core" --kind module
151
+ skeinn task plan --json-file work-map.json
152
+ skeinn project ready
153
+ skeinn keeper record --json-file keeper-result.json
154
+ skeinn task next && skeinn task start TASK-001
155
+ skeinn task done TASK-001 --json-file evidence.json
156
+ skeinn check
157
+ ```
158
+
159
+ </details>
160
+
161
+ ---
162
+
163
+ ## Verify it actually helps
164
+
165
+ Run `npm test` (31 end-to-end contract tests), or use `skeinn eval scaffold` to run controlled **Evil Eval** comparisons (equal model, tools, workspace, user facts, forced resets, and blind order-swapped judging). See [EVIL_EVAL.md](EVIL_EVAL.md).
@@ -0,0 +1,229 @@
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="docs/brand/skeinn-wordmark-dark.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="docs/brand/skeinn-wordmark-light.svg">
6
+ <img alt="Skeinn" src="docs/brand/skeinn-wordmark-light.svg" height="64">
7
+ </picture>
8
+
9
+ <p><strong>记住全貌,像高手一样把项目做完。</strong></p>
10
+ <p>为 AI 编码 Agent 打造的隐形项目理解、一线专业判准与断电续接底座。</p>
11
+
12
+ <p>
13
+ <a href="README.md">English</a> · <strong>简体中文</strong> ·
14
+ <a href="design.md">系统设计</a> ·
15
+ <a href="EVIL_EVAL.md">Evil Eval</a> ·
16
+ <a href="CHANGELOG.md">更新日志</a>
17
+ </p>
18
+
19
+ <p>
20
+ <img src="https://img.shields.io/badge/node-%E2%89%A518-17212B?style=flat-square" alt="Node.js 18+">
21
+ <img src="https://img.shields.io/badge/for-AI%20Coding%20Agents-3B63F6?style=flat-square" alt="For AI Coding Agents">
22
+ <img src="https://img.shields.io/badge/languages-Multilingual-17212B?style=flat-square" alt="Multilingual">
23
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9AD8C2?style=flat-square&amp;labelColor=17212B" alt="MIT License"></a>
24
+ </p>
25
+
26
+ </div>
27
+
28
+ ---
29
+
30
+ ## 为什么需要 Skeinn?
31
+
32
+ 用 AI 写几百行脚本很顺,但一旦进入**三天以上、多模块的中大型项目**,无规则 Vibe Coding 几乎都会撞上四堵墙:
33
+
34
+ | 痛点 | 无规则 Vibe Coding | 接入 Skeinn 后的 Agent |
35
+ | :--- | :--- | :--- |
36
+ | **聊久就失忆** | 上下文压缩或新开会话后,架构决策、边界和偏好全丢,越改越散 | 项目全貌、设计、任务进度与证据全部落盘,换新 Agent 直接续接 |
37
+ | **方案平庸、像外行** | 默认收敛到“互联网统计学平均解”,界面与架构一看就是模板拼凑 | 锁定 1–3 个瓶颈专业域,**调研真实一线从业者怎么干**并反思转化为项目规则 |
38
+ | **一稿过、后期返工** | 想到第一个可行方案就开写,隐患全部埋在实现阶段 | 核心设计强制**至少 2 个真实可行方案对撞**(含更简或非常规视角),写清取舍 |
39
+ | **假绿灯完成** | Agent 口头宣布“已实现”,实测缺文件、漏边界或改坏上游 | 开工前由**全新无记忆 Keeper** 独立验盘;每个 Task 凭可复现证据逐条关闭 |
40
+
41
+ > **核心原则:Skeinn 是给 Agent 用的,不是给人学的新框架。**
42
+ > 它天然支持多语言协作——你用中文、英文、日文或任何语言自然聊天即可;Agent 在后台静默调用 `skeinn` CLI 维护 `.skeinn/` 状态,你永远不需要手动敲这些命令。
43
+
44
+ ---
45
+
46
+ ## 30 秒看懂一次真实协作
47
+
48
+ ```text
49
+ 你(用任意语言自然对话) Agent(后台静默运行 skeinn)
50
+ ─────────────────────────────────────────────────────────────────────────
51
+ 1. 抛出想法 检查工作区 → 只问真正改变方案的
52
+ "帮我做一个本地离线复盘工具..." 关键问题 → 记录事实、假设与边界
53
+
54
+ 2. 回答关键取舍 写清 PROJECT.md → 迭代核心 Design
55
+ 与 1–3 个瓶颈 Capability(查一线
56
+ 实操 → 项目反思 → 写回 Design Delta)
57
+
58
+ 3. 确认整体方向 冻结摘要 → 拉起全新无记忆 Keeper
59
+ 审查:能否直接开工?有无伪调研、
60
+ 稻草人对比或漏掉的防呆红线?
61
+
62
+ 4. 陆续看到可运行成果,随时提新想法 一次只做 1 个可恢复 Task(自带
63
+ guardrails 红线),逐条填实证闭环;
64
+ 中途改方向则暂停并标出受影响的旧任务
65
+ ```
66
+
67
+ ---
68
+
69
+ ## 真实产物长什么样?(具体演示)
70
+
71
+ 以**“做一个本地离线的会议后 3 分钟复盘工具”**为例,看看 Skeinn 在后台到底帮 Agent 沉淀了什么高价值内容(而不是一堆废话文档):
72
+
73
+ ### 1. 一份瓶颈领域判准(`.skeinn/capabilities/reflective-ux.md`)
74
+
75
+ ```markdown
76
+ # Reflective UX Design
77
+ - Mode: external_researched
78
+ - Authority: human_confirmed
79
+
80
+ ## How real practitioners operate
81
+ - 渐进披露与单屏低认知负荷 — Source: https://linear.app/method
82
+ - 敏感个人笔记工具必须将“本地存储边界与一键清空”前置可见,而非藏进隐私条款 — Source: https://localfirstweb.dev/
83
+
84
+ ## Reflection for this project
85
+ - 哪些不能照搬:大厂日记 App 的“连续打卡/情绪打分”会给刚开完高压会议的人制造考核焦虑,必须砍掉。
86
+ - 高手的非显性手法:用“原话回显 + 自主选下一步”替代 AI 总结说教,让用户感到被托住而不是被评估。
87
+
88
+ ## Operational rules and Design delta
89
+ - Anti-patterns: 禁止倒计时、禁止情绪打分、禁止任何静默外链请求
90
+ - Design delta (Before -> After): 将首屏从“3 栏仪表盘 + 情绪雷达图”改为“4 步可跳过单栏卡片流”,并在首屏直接暴露一键清除按钮。
91
+ ```
92
+
93
+ ### 2. 一段方案对撞设计(`.skeinn/design/first-use-flow.md`)
94
+
95
+ ```markdown
96
+ ## Alternatives considered
97
+ - 方案 A(采纳):单 HTML 文件 + localStorage 渐进式 4 步卡片流(零安装、双击即用、离线可验)。
98
+ - 方案 B(否决):Vite + SQLite 本地服务版。虽然扩展性更强,但违背“会后 3 分钟零摩擦打开”的核心体验。
99
+
100
+ ## How this could look done yet fail
101
+ - 页面跑通、测试全绿,但引入了远程 Google Fonts 导致弱网下泄漏请求;或刷新页面后草稿静默丢失。
102
+ ```
103
+
104
+ ### 3. 一条带防呆红线的可恢复 Task(`.skeinn/tasks.json`)
105
+
106
+ ```json
107
+ {
108
+ "id": "TASK-001",
109
+ "title": "实现单文件离线复盘主流程与本地清空",
110
+ "implements": ".skeinn/design/first-use-flow.md#Alternatives considered",
111
+ "guardrails": [
112
+ "禁止任何外部网络请求、远程字体或分析脚本",
113
+ "禁止添加情绪打分、倒计时或强制填写校验"
114
+ ],
115
+ "acceptance": [
116
+ {
117
+ "criterion": "源码静态扫描零外链请求,刷新后草稿保留且一键清空生效",
118
+ "verify_by": "运行 node tests/verify.mjs 并在浏览器实测刷新与清空",
119
+ "evidence": "verify.mjs: 0 external URLs; reload restored draft; clear wiped localStorage"
120
+ }
121
+ ]
122
+ }
123
+ ```
124
+
125
+ ---
126
+
127
+ ## 四个核心设计:低摩擦,且防偷懒
128
+
129
+ 1. **单文件 Capability(真调研 + 真反思 + Design Delta)**:聚焦 1–3 个决定上限的瓶颈域,1 条命令创建 `.skeinn/capabilities/<field>.md`。禁止静默跳过(纯常规工程必须显式 `skeinn capability exempt` 并接受 Keeper 审计);`external_researched` 直接拦截 `agent-authored` 自造来源;无网时诚实标 `offline_reflection`。
130
+ 2. **方案对撞型 Design**:核心设计(`product` / `experience` / `system` / `contract`)强制对比至少 2 个真实可行方案(含更简或非常规视角),把 Capability 判准编译进机制,并提前写清假阳性失败面。
131
+ 3. **一次性独立 Keeper**:开工前由全新无记忆 Agent 只读磁盘试跑,并执行四项反敷衍核查(豁免合理性、伪调研、稻草人备选、红线是否落地)。通过后退场,不打扰日常施工。
132
+ 4. **可恢复 Task + 防呆红线**:广度 Work Map 留盘,每次只注入当前唯一活跃 Task、精确 `reads` 与 1–3 条 `guardrails`;完成校验产出存在与逐条实证,上游重开自动标出需要复核的下游任务。
133
+
134
+ ---
135
+
136
+ ## 快速开始
137
+
138
+ ### 1. 安装 CLI(Node.js ≥ 18)
139
+
140
+ ```bash
141
+ npm install --global @haaaiawd/skeinn
142
+ ```
143
+
144
+ 或从源码仓库本地安装:
145
+
146
+ ```bash
147
+ npm install --global .
148
+ ```
149
+
150
+ ### 2. 把这句话交给你的编码 Agent
151
+
152
+ 在项目目录中打开 Claude Code / Cursor / Windsurf / Codex 等具备终端能力的 Agent,直接说:
153
+
154
+ > “这个项目使用 Skeinn 维护项目理解与连续性。请先运行 `skeinn init` 和 `skeinn context --full` 读取协议;之后你只管和我自然沟通,在后台维护项目状态。”
155
+
156
+ ---
157
+
158
+ ## 磁盘结构
159
+
160
+ ```text
161
+ .skeinn/
162
+ ├── PROJECT.md 项目全貌入口与导航图
163
+ ├── STRUCTURE.md 代码、测试、文档与资源目录约定
164
+ ├── DECISIONS.md 重要决策变更与受影响任务记录
165
+ ├── capabilities/ 1–3 份单文件瓶颈领域判准(一线实操 + 反思 + Design Delta)
166
+ ├── design/ 按子系统拆分的设计文档图谱(含方案对撞与假阳性失败面)
167
+ ├── state.json 已确认事实、假设、未决问题、豁免与 Keeper 状态
168
+ ├── deliverables.json 可观察交付面(区分已规划与已交付)
169
+ └── tasks.json 磁盘上的广度 Work Map 与当前活跃 Task
170
+ ```
171
+
172
+ <details>
173
+ <summary><strong>Agent CLI 速查(仅 Agent 在后台调用,人类无需记忆)</strong></summary>
174
+
175
+ ```bash
176
+ # 初始化与上下文恢复(首次进入或重置后用 --full,任务间隙用精简 context)
177
+ skeinn init
178
+ skeinn context --full
179
+ skeinn context
180
+
181
+ # 记录理解、迭代设计与瓶颈能力
182
+ skeinn record --json-file understanding.json
183
+ skeinn design add core --title "Core system" --kind system
184
+ skeinn capability add ui-ux --title "UI/UX design" --mode external_researched
185
+ skeinn capability confirm ui-ux --scenario "<项目情境>" --source human
186
+ # 纯常规工程无需专项能力时显式豁免(由 Keeper 审计):
187
+ skeinn capability exempt --reason "<为何常规工程能力已足够>"
188
+
189
+ # 规划交付面与任务,冻结摘要并由独立 Keeper 验盘
190
+ skeinn deliverable add cli-core --title "CLI core" --kind module
191
+ skeinn task plan --json-file work-map.json
192
+ skeinn project ready
193
+ # 新开无继承上下文的 Agent 运行 skeinn keeper prompt,并提交含 review.mode: "independent" 的结果
194
+ skeinn keeper record --json-file keeper-result.json
195
+
196
+ # 单任务实证施工与变更演化
197
+ skeinn task next
198
+ skeinn task start TASK-001
199
+ skeinn task done TASK-001 --json-file evidence.json # 详见 skeinn task done --help
200
+ skeinn decision --json-file decision.json
201
+ skeinn clarify start --reason "<方向变化原因>"
202
+ skeinn check
203
+ ```
204
+
205
+ > 无人值守或 Benchmark 运行时,可附加 `--human-channel unavailable` 与 `--state-dir <外部目录>`,在不污染评分工作区的前提下保持完整状态。
206
+
207
+ </details>
208
+
209
+ ---
210
+
211
+ ## 证明它真的有用(Evil Eval)
212
+
213
+ 内置 **Evil Eval** 脚手架:在完全相同的模型、工具、工作区、用户事实与预算下,对“无框架基线”与“接入 Skeinn”执行**强制上下文重置 + 匿名盲评 + 顺序交换**,把仪式成本、用户负担与最终质量一起计分。详见 [EVIL_EVAL.md](EVIL_EVAL.md)。
214
+
215
+ ```bash
216
+ npm test
217
+ ```
218
+
219
+ ---
220
+
221
+ ## 文档导航
222
+
223
+ | 文档 | 内容 |
224
+ | :--- | :--- |
225
+ | [系统设计](design.md) | 架构、存储模型、不变量与命令契约 |
226
+ | [UX 与闭环规范](docs/UX_FLOW.md) | 人、Agent、Keeper 与 Task 的完整转换 |
227
+ | [提示词目录](docs/PROMPT_CATALOG.md) | 注入给 Agent 的全部认知层与模板 |
228
+ | [Evil Eval 协议](EVIL_EVAL.md) | 有无框架的受控对照实验规范 |
229
+ | [更新日志](CHANGELOG.md) | v2.4.0 及历次演进记录 |
package/SECURITY.md ADDED
@@ -0,0 +1,11 @@
1
+ # Security policy
2
+
3
+ Please do not publish exploitable details in a public issue.
4
+
5
+ Report a vulnerability through [GitHub private vulnerability reporting](https://github.com/Haaaiawd/skeinn/security/advisories/new).
6
+ Include the affected version, reproduction steps, impact, and any suggested mitigation. If private reporting
7
+ is unavailable, open a minimal issue asking for a private contact channel without including the vulnerability.
8
+
9
+ Skeinn reads and writes project-local state and may be used by Agents with broad command-line permissions.
10
+ Security reports involving path traversal, unintended workspace mutation, command construction, stale Keeper
11
+ authorization, or untrusted project content are especially relevant.