[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92592":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":16,"starSnapshotCount":16,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},92592,"Spexcode","shuxueshuxue\u002FSpexcode","shuxueshuxue","SDD that actually works.","https:\u002F\u002Fspexcode.net",null,"TypeScript",57,7,51,17,0,6,43.31,"MIT License",false,"main",[],"2026-07-22 04:02:06","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"docs\u002Fbanner.png\" alt=\"SpexCode\" width=\"720\">\n\n\u003Cp>\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fspexcode\">\u003Cimg alt=\"npm\" src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fspexcode?logo=npm&logoColor=white&color=cb3837\">\u003C\u002Fa>\n  \u003Cimg alt=\"license: MIT\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-2f81f7\">\n  \u003Cimg alt=\"node ≥ 22\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%E2%89%A5%2022-3fb950?logo=nodedotjs&logoColor=white\">\n  \u003Ca href=\"https:\u002F\u002Fspexcode.net\">\u003Cimg alt=\"docs\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-spexcode.net-8957e5\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003C\u002Fdiv>\n\nSpec-driven development with AI agents in the loop. SpexCode keeps a versioned tree of specs inside\nyour git repo, links every spec to the code it governs, and runs a session manager that dispatches\ncoding agents into isolated worktrees. You review and merge; the tool keeps intent and\nimplementation from drifting apart.\n\n[![Watch: this repo's spec tree grow from its git history](docs\u002Fspec-tree-poster.jpg)](https:\u002F\u002Fspexcode.net\u002Fassets\u002Fspec-tree-growth.mp4)\n\n\u003Csub>▶ This repo's own spec tree, replayed from its git history — 160 spec nodes growing over three weeks. Click for the [full video](https:\u002F\u002Fspexcode.net\u002Fassets\u002Fspec-tree-growth.mp4).\u003C\u002Fsub>\n\nEnglish | [中文](.\u002Fdocs\u002FREADME.zh-CN.md) · Docs: [spexcode.net](https:\u002F\u002Fspexcode.net) · License: MIT\n\nQuick links: [the model](#the-model) · [quick start](#quick-start) ·\n[agents](#working-with-agents) · [yatsu](#measuring-behavior-yatsu) · [config](#configuration)\n\n## The model\n\n\u003Cdiv align=\"center\">\u003Cimg src=\"docs\u002Fsdd-tuxedo-pooh.png\" alt=\"spec-driven development meme\" width=\"260\">\u003C\u002Fdiv>\n\nA spec node is a directory under `.spec\u002F` containing a `spec.md`: frontmatter (title, status, a\n`code:` list of the files it governs) plus a prose body stating what that part of the system is\nsupposed to do, right now. Nodes nest, so the tree mirrors how you think about the project rather\nthan the file layout. The body has two parts. The short **raw source** states the intent; changing it takes explicit\nhuman approval (an agent can draft it, a human signs off). The **expanded spec** is the agent's\ndetailed reading of that intent; it iterates freely but must always match the raw source.\n\n\u003Cimg src=\"docs\u002Freadme-node.png\" alt=\"spec node popup\">\n\nTwo rules make this workable:\n\n1. **Git is the database.** There is no separate store. A node's version count is the number of\n   commits that touched its `spec.md`, its history view is `git log` on that file, and each version\n   is attributed to an agent session through a `Session:` commit trailer. This is also why a spec\n   body always describes present intent and gets rewritten in place: changelog headings inside the\n   body are banned (the linter enforces it), because git already keeps the history.\n2. **Spec and code land together.** A change is one commit that updates both the `spec.md` and the\n   code it justifies. When code moves without its spec, the linter flags it,\n\n   ```\n   drift: spec-cli\u002Fsrc\u002Fboard.ts is 1 commit(s) ahead of spec 'board-lean' (v8) — may be stale\n   ```\n\n   and keeps flagging until the spec catches up.\n\n## The optimization loop\n\nSpecs, commits, and yatsu readings compose into one loop. The spec is the loss function: it states what you want, and\nit's the half a human signs off on. Commits are the optimizer. **yatsu**, the measurement\nsubsystem, is the eval: it scores how far live behavior currently sits from the spec, and the\nscore's history lives in git like everything else.\n\n\u003Cimg src=\"docs\u002Freadme-loop.png\" alt=\"the spec\u002Fcode optimization loop\">\n\nIt also settles where the human stands day to day: nobody reads a neural net by staring at its\nweights, and between merge gates you don't have to stare at agent diffs either. Attention goes to\nthe spec and the eval readings; the diff gets read once, at merge time.\n\n## Quick start\n\nRequires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.\n\n```sh\nnpm i -g spexcode        # installs the `spex` command\ncd your-repo\nspex init                # seeds .spec\u002F, installs git hooks, renders the agent contract\nspex serve               # API backend on :8787\nspex dashboard           # board UI on :5173, proxying to the backend\n```\n\n`spex init` is additive. It works on any existing git repo and never overwrites your files: it\ncreates a root `.spec\u002Fproject\u002Fspec.md` and a starter `spexcode.json`, installs the pre-commit\nhooks, and writes a managed block into `CLAUDE.md`\u002F`AGENTS.md` so any agent working in the repo\ndiscovers the workflow on its own.\n\nThen grow the tree:\n\n1. Edit `.spec\u002Fproject\u002Fspec.md` to describe the project.\n2. Add child nodes for the parts you want governed, each with a `code:` list pointing at existing\n   files.\n3. Run `spex lint`. Coverage warnings list the source files no spec claims yet; that list is your\n   adoption TODO.\n\nYou are not expected to hand-author all of this. The intended workflow is to have an agent do most\nof the spec writing; `spex guide spec` prints the exact file format it needs.\n[Getting started](https:\u002F\u002Fspexcode.net\u002Fgetting-started\u002F) on the docs site walks the setup end to\nend.\n\n\u003Cimg src=\"docs\u002Freadme-board.png\" alt=\"dashboard screenshot\">\n\n*SpexCode's own repo on its own board; the sessions top-left are agents building the tool.*\n\n## Working with agents\n\nThis part needs tmux and a logged-in [Claude Code](https:\u002F\u002Fwww.anthropic.com\u002Fclaude-code) or Codex\non the machine.\n\n```sh\nspex new \"make the settings page remember the last tab\" --node settings\n```\n\nlaunches a worker session in its own worktree on branch `node\u002Fsettings`. The worker reads the\ngoverning spec before touching code, makes the change, rewrites the spec body to match, commits\nboth (a hook stamps the `Session:` trailer), then proposes a merge and stops. Workers never merge\nthemselves. The merge stays with the manager: when you fire it, the session's own agent runs the\nactual `git merge`, so conflicts land on the one who knows the work. The same dispatch is a\nbutton on the dashboard (the new-session box on the board); the command form is what agents\nthemselves use when they delegate.\n\nYou supervise from outside — on the board, or with the same commands your agent uses:\n\n```sh\nspex watch              # stream session transitions: launched \u002F review \u002F done \u002F needs-input ...\nspex review settings    # commits ahead of trunk, merge-base diff, typecheck\u002Flint gates\nspex merge settings     # gated merge into the trunk\nspex session close settings\n```\n\nIndependent tasks run in parallel. Each worker is isolated in its own worktree, git serializes the\nmerges, and a pre-commit guard blocks direct commits on the trunk, so everything flows through\nreviewable node branches.\n\nThe process is enforced by mechanism, not prompt engineering: the backend creates the branch and a\nhook stamps the attribution; the materialized contract block carries the rest, so your dispatch\nprompt stays task-only. More on this mode of working:\n[working with agents](https:\u002F\u002Fspexcode.net\u002Fworking-with-agents\u002F).\n\n## Measuring behavior: yatsu\n\nyatsu — short for **You As The Stupid User** — is the measuring half of\n[the loop](#the-optimization-loop): you measure behavior from the product's real surface, the way a\nclueless real end user would touch it, not through an internal helper or shortcut that makes the\nproof easy. A spec says what a part should do; a\n`yatsu.md` beside it says how to check. Each scenario is a plain description plus an expected\nresult. yatsu itself runs nothing (no DSL, no runner). An agent runs the scenario however it can:\na test file, a real browser, or just clicking through by hand and screenshotting. It compares\nactual to expected and files the reading with evidence:\n\n```sh\nspex yatsu eval settings --scenario remembers-tab --pass --image proof.png\n```\n\nReadings live in a git-tracked ndjson next to the spec, so measurements get the same attribution\nand history as spec versions. Bug fixes are expected to bracket: file a failing reading that\nreproduces the bug, fix, then file a passing reading on the same scenario.\n\n\u003Cimg src=\"docs\u002Freadme-eval.png\" alt=\"eval view screenshot\">\n\n*The eval view: scenario readings on the left; the selected reading's expected result, staleness,\nand recorded video evidence in the middle.*\n\n## What's in the repo\n\n| Package | Role |\n|---|---|\n| `spec-cli` | The `spex` CLI and the HTTP backend (Hono, runs via tsx, no build step). Reads `.spec` and git live; owns the session state machine and the linter. |\n| `spec-dashboard` | React board: the node graph, per-node spec\u002Fhistory\u002Fissues panes, and a real terminal onto each live agent session. |\n| `spec-yatsu` | Scenario definitions, readings, evidence blobs. |\n| `spec-forge` | Read-only tracer that resolves a forge's open issues and PRs to the spec nodes they serve (GitHub today). An issue links itself with a `Spec: \u003Cnode-id>` line in its body; a PR from a `node\u002F\u003Cid>` branch links for free. |\n\n## The linter\n\n`spex lint` checks the spec↔code graph and is the real gate (the git hook is fast local feedback):\n\n- **integrity** (error): a `code:` path that doesn't exist\n- **living** (error): a changelog heading in a spec body\n- **altitude** (warn): a body that slid from contract prose into an implementation dump. The usual\n  smell is a numbered step list or a wall of function names; this rule is why spec bodies stay\n  short enough to actually read\n- **coverage** (warn): unclaimed source files\n- **drift** (warn): governed code changed after its spec's last version, derived live from git\n\n## Configuration\n\n`spexcode.json` (committed, portable: layout, lint budgets, dashboard identity, launcher names) and\n`spexcode.local.json` (gitignored, host-specific: absolute launcher paths, plus a `private: true`\noverlay for repos you use but don't own) cover every setting. No `spex config set` yet: you edit the two files by hand (or ask your agent\nto), and `spex guide config` documents every field. The other\nmanuals are `spex guide` (the workflow), `spex guide spec`, and `spex guide yatsu`; `spex help`\nmaps the commands.\n\n## Contributing\n\n[`docs\u002FCONTRIBUTING.md`](docs\u002FCONTRIBUTING.md) gets you from a clone to a first merged change.\n[`docs\u002FAGENT_GUIDE.md`](docs\u002FAGENT_GUIDE.md) has the full mechanics of the node model and the\nreflexive config system.\n\n## Credit\n\nFirst introduced on the [LINUX DO](https:\u002F\u002Flinux.do) community — thanks to everyone there for the first round of discussion.\n\n## License\n\n[MIT](.\u002FLICENSE).\n","SpexCode 是一个支持规范驱动开发（SDD）的 TypeScript 工具，通过在 Git 仓库中维护版本化的规范树（`.spec\u002F` 目录），将自然语言规范与对应代码文件显式关联。其核心特点是：以 Git 为唯一数据源，规范节点含人类确认的‘原始意图’和 AI 生成的‘扩展说明’，所有变更需同步更新规范与代码；内置会话管理器调度隔离工作区中的编码智能体。适用于需要强可追溯性、人机协同评审、防止规范-实现偏移的中大型软件项目，尤其适合采用 AI 辅助开发且重视工程可审计性的团队。",2,"2026-07-09 02:30:25","CREATED_QUERY"]