projectstore-claude 0.0.1 → 0.28.0-rc.2

package/README.md

@@ -1,19 +1,23 @@
 # projectstore-claude
 
-**This is a reserved name, not a product.** Install [`projectstore`](https://www.npmjs.com/package/projectstore) instead:
+The Claude Code installer for [projectstore](https://www.npmjs.com/package/projectstore): the core, pinned at exactly this version and bundled inside this tarball, with the harness fixed. One command, from a terminal **outside** a Claude Code session:
 
 ```sh
-npm install projectstore
+npx projectstore-claude install --project "$PWD"
 ```
 
-Claude Code installs projectstore from its plugin marketplace, and the npm package is the same one every other harness uses. This name is reserved so it cannot be taken and made to look official.
+It registers the plugin for that checkout at the host's local scope, previews every write and every host command before it runs, and asks for nothing else — naming the shell is the confirmation. Restart Claude Code afterwards.
 
-ProjectStore ships as **one package carrying every harness's manifest** —
-Claude Code, Codex, opencode and an MCP server all install the same tree. That
-decision is recorded in the project's architecture decision records.
+- Upgrade, or pin: `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run.
+- Uninstall: `npx projectstore-claude uninstall --project "$PWD"` — forgets the registration for that checkout and nothing else; your vault is plain markdown and stays yours.
+- `doctor`, `status`, `search` and the other read verbs pass through unchanged: `npx projectstore-claude doctor --json`.
 
+This shell is `projectstore <verb> --harness claude-code` and nothing more. `bin/projectstore-claude.mjs` locates the bundled core under `node_modules/projectstore/` and execs it; the core's low-level form — `npx projectstore install --harness claude-code --project "$PWD"` — is exactly what runs. A different `--harness` is refused (exit 2). The shell carries no plugin of its own: the plugin Claude Code loads is the bundled core, registered through a small local marketplace under your Claude home.
+
+Why from a terminal: the host CLI and a live session both rewrite the same settings files, so the core defers the registration inside a session and says so.
+
+- Docs: https://github.com/SmartAndPoint/ProjectStore#install--one-message
 - Source: https://github.com/SmartAndPoint/ProjectStore
 - Issues: https://github.com/SmartAndPoint/ProjectStore/issues
-- Author: Evgenii Konev (SmartAndPoint)
 
 MIT licensed.

package/bin/projectstore-claude.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// projectstore-claude — the Claude Code distribution shell of projectstore.
+// RENDERED by packaging/shells.mjs from its template: edit the template, then
+// `node packaging/shells.mjs --write`. A hand edit here fails --check.
+//
+// A shell is a bin and a pin, never logic (the layout spec, contract 10): this
+// file locates the core the tarball bundles and execs it with
+// `--harness claude-code` inserted after a verb that takes it. Every other
+// argument passes through, so `projectstore-claude <verb> …` is exactly
+// `projectstore <verb> --harness claude-code …` — the same preview, the
+// same files, the same exit code. Naming the shell is the confirmation the
+// core's install gate asks for, exactly as naming --harness is.
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { constants as osConstants } from "node:os";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SHELL = "projectstore-claude";
+const HARNESS = "claude-code";
+// The verbs of the core's table that declare --harness (rendered from
+// scripts/cli.mjs; the packaging test pins it). Any other verb — doctor,
+// status, search, --version — passes through untouched: the core refuses an
+// option a verb does not declare, so a blanket insert would break `doctor`.
+const HARNESS_VERBS = new Set(["plan","install","uninstall","upgrade","agents"]);
+
+// The bundled core, by path — never by package resolution: a hoisted or global
+// copy at another version is exactly the pairing the pin exists to prevent,
+// and the core's file layout is not an API (the shells ADR, decision 5).
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const CANDIDATES = [
+  resolve(root, "node_modules", "projectstore", "bin", "projectstore.mjs"), // bundled — the release shape
+  resolve(root, "core", "bin", "projectstore.mjs"), // vendored — the shells ADR's fallback
+];
+
+// Inserts --harness after the verb (the first positional) when that verb takes
+// it; refuses another harness; never duplicates one already given. Scans up to
+// a bare "--". A verb that is not the first positional (`--project x install`)
+// is left alone: the core then asks for --harness itself, a usage error, never
+// a wrong write.
+function fixHarness(argv) {
+  const stop = argv.indexOf("--");
+  const scan = stop === -1 ? argv : argv.slice(0, stop);
+  const given = [];
+  const dangling = { error: `\`--harness\` is given without a value — this shell fixes it to ${HARNESS}; drop the flag` };
+  for (let i = 0; i < scan.length; i++) {
+    if (scan[i] === "--harness") {
+      const v = scan[i + 1];
+      if (v === undefined || v.startsWith("-")) return dangling;
+      given.push(v); i++;
+    } else if (scan[i].startsWith("--harness=")) {
+      const v = scan[i].slice("--harness=".length);
+      if (!v) return dangling;
+      given.push(v);
+    }
+  }
+  const other = given.find((g) => g !== HARNESS);
+  if (other !== undefined) return { error: `installs for ${HARNESS} only — \`--harness ${other}\` names another harness. Run that harness's shell, or the core: npx projectstore <verb> --harness ${other} …` };
+  if (given.length) return { argv }; // named already: pass through, never twice (the core's option repeats)
+  const at = scan.findIndex((a) => !a.startsWith("-"));
+  if (at === -1 || !HARNESS_VERBS.has(scan[at])) return { argv };
+  return { argv: [...argv.slice(0, at + 1), "--harness", HARNESS, ...argv.slice(at + 1)] };
+}
+
+const core = CANDIDATES.find((p) => existsSync(p));
+if (!core) {
+  process.stderr.write(`${SHELL}: the bundled core is missing — looked at:\n${CANDIDATES.map((c) => "  " + c).join("\n")}\n`);
+  process.exitCode = 2;
+} else {
+  const fixed = fixHarness(process.argv.slice(2));
+  if (fixed.error) {
+    process.stderr.write(`${SHELL}: ${fixed.error}\n`);
+    process.exitCode = 2;
+  } else {
+    // stdio inherited: the core's install gate asks on a terminal and refuses
+    // without one, so the child must see the real stdin and stdout. No
+    // timeout — the child waits on a human at the preview. exitCode, not
+    // exit(): the core's own bin says why (a pending write on a pipe).
+    const r = spawnSync(process.execPath, [core, ...fixed.argv], { stdio: "inherit" });
+    if (r.error) process.stderr.write(`${SHELL}: ${r.error.message}\n`);
+    // A signal is relayed the shell way (128 + its number): Ctrl-C at the
+    // preview is 130 here as it would be on the core itself.
+    process.exitCode = r.status ?? (r.signal ? 128 + (osConstants.signals[r.signal] || 0) : 2);
+  }
+}

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "SmartAndPoint",
+  "description": "Claude Code plugins by SmartAndPoint.",
+  "owner": {
+    "name": "Evgenii Konev",
+    "email": "ekonev@smartandpoint.com",
+    "url": "https://github.com/SmartAndPoint"
+  },
+  "plugins": [
+    {
+      "name": "projectstore",
+      "displayName": "projectstore",
+      "description": "📚 Your agent runs the project through a verified loop: task → artifact (ADR · spec · epic · story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
+      "version": "0.28.0-rc.2",
+      "author": {
+        "name": "Evgenii Konev",
+        "email": "ekonev@smartandpoint.com",
+        "url": "https://github.com/SmartAndPoint"
+      },
+      "category": "productivity",
+      "homepage": "https://github.com/SmartAndPoint/ProjectStore",
+      "tags": [
+        "obsidian",
+        "markdown",
+        "adr",
+        "epics",
+        "stories",
+        "kanban",
+        "knowledge-base",
+        "engineering-process",
+        "llm-wiki"
+      ],
+      "source": {
+        "source": "github",
+        "repo": "SmartAndPoint/ProjectStore"
+      }
+    }
+  ]
+}

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "projectstore",
+  "displayName": "projectstore",
+  "version": "0.28.0-rc.2",
+  "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
+  "author": {
+    "name": "Evgenii Konev @ SmartAndPoint",
+    "email": "ekonev@smartandpoint.com",
+    "url": "https://github.com/SmartAndPoint"
+  },
+  "homepage": "https://github.com/SmartAndPoint/ProjectStore",
+  "repository": "https://github.com/SmartAndPoint/ProjectStore",
+  "license": "MIT",
+  "keywords": [
+    "project-management",
+    "adr",
+    "epics",
+    "kanban",
+    "obsidian",
+    "markdown",
+    "engineering-process"
+  ]
+}

package/node_modules/projectstore/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "projectstore": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs",
+        "mcp",
+        "--project",
+        "${CLAUDE_PROJECT_DIR}"
+      ]
+    }
+  }
+}

package/node_modules/projectstore/AGENTS.md

@@ -0,0 +1,26 @@
+<!-- projectstore:agents v4 (managed by projectstore — edit outside markers) -->
+## projectstore agents
+
+- **A feature-sized request opens a vault artifact before it opens an editor.**
+  Analysis → placement (which epic, which story) → an ADR and/or spec when the
+  "how" is non-trivial → `projectstore:critic` → only then implementation →
+  `projectstore:reviewer`. "Feature-sized" is not a judgement about how the
+  request was phrased — it is about what the work touches: if you are about to
+  write across several source files, open the story first.
+- **Report instruction conflicts; do not arbitrate them.** If a session-level or
+  harness-level instruction contradicts this block, say so and ask which wins.
+  Resolving it silently is how the contradiction becomes invisible to the person
+  who could have settled it.
+- When spawning any agent below, resolve its model from
+  `.projectstore/harness/<harness>.json` → `agents.per_agent.<name>.model ?? agents.default.model`,
+  where `<name>` is the **bare** agent name (`critic` for `projectstore:critic`),
+  and pass it as the spawn's model parameter. No key — pass nothing.
+- After authoring or revising any vault artifact (ADR/research/epic/story) or
+  design proposal: run the `projectstore:critic` agent on it before treating it final.
+- Before implementing an epic/story: consult `projectstore:planner` — it plans
+  against how prior epics map to the codebase (`code_refs`).
+- After writing code, before commit / story-done: run `projectstore:reviewer` —
+  it verifies the diff actually closes the story's acceptance criteria.
+- When discussing vault contents, reference artifacts by their frontmatter
+  `title:` (with their parent epic), never by session-invented shorthand.
+<!-- /projectstore:agents -->

package/node_modules/projectstore/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SmartAndPoint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/projectstore/README.md

@@ -0,0 +1,208 @@
+# ProjectStore
+
+> Not a memory plugin. ProjectStore is how your AI agent runs the *project* — decisions, specs, epics, stories and a kanban board as plain markdown in git — so the next agent, the next model, or you in six months know exactly **why** everything is the way it is.
+
+[![release](https://img.shields.io/github/v/release/SmartAndPoint/ProjectStore?label=release)](https://github.com/SmartAndPoint/ProjectStore/releases) [![license](https://img.shields.io/github/license/SmartAndPoint/ProjectStore?label=license)](./LICENSE) [![Star on GitHub](https://img.shields.io/badge/%E2%AD%90-star_us-yellow?logo=github)](https://github.com/SmartAndPoint/ProjectStore/stargazers)
+
+A [Claude Code](https://claude.com/claude-code) plugin.
+
+---
+
+## Two months of agents, and nobody knows why
+
+Agents write code fast. They re-decide settled questions even faster: every fresh session arrives empty, makes its own architectural call, and commits under its own assumptions. Two months later you have noodle code — every strand reviews fine on its own, and each was written under a different theory of the project. Ask *"why is this a queue and not a cron job?"* and nobody can answer. The agent that decided is long gone.
+
+The fix is not a smarter agent. It is a loop with verification in it.
+
+## The loop
+
+The thing that makes agentic coding work — the loop Claude Code's own creator keeps pointing at — is *gather context, act, verify, repeat*. ProjectStore runs that loop one level up: over the project, not just the code.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/loop.svg">
+  <img alt="The ProjectStore loop: task → artifact → critic (verify) → backlog → planner → implement → reviewer (verify) → done → views regenerate" src="docs/images/loop-light.svg">
+</picture>
+
+1. **You hand the agent a task.** It opens an artifact before it opens an editor: an ADR if something needs deciding, an epic and stories for the work, a spec when the "how" is non-trivial.
+2. **A fresh-context critic attacks the artifact.** Expect *revise* — on this repo it has yet to pass anything on the first try, and that is the point.
+3. The fixed artifact lands in the **backlog**; the kanban regenerates itself.
+4. An agent picks up a story. A **planner** reads how earlier epics actually landed in the code and says where this change belongs.
+5. A **reviewer** matches the diff against the story's acceptance criteria — per criterion, with evidence — before anything gets called done.
+6. **Done.** Board, link graph and code map regenerate. The next session starts oriented instead of guessing.
+
+Mechanisms hold this together, not discipline: an agent that starts coding with no story open gets nudged, artifacts are not final before review, and a deterministic `doctor` checks the mechanical consistency with zero AI involved. Every *verify* step is a separate fresh-context agent with no stake in the draft it is judging.
+
+We build ProjectStore with ProjectStore. The feature that names your session went through exactly this loop — including a critic pass that killed the design's central claim, and a reviewer pass that caught a bug which would have shipped the feature silently dead for every real user.
+
+## What lands on disk
+
+Say *"let's go with Postgres, not Mongo — we need transactions"*, approve the draft, and a real file lands:
+
+```markdown
+---
+title: "Use Postgres for primary storage"
+status: accepted
+date: 2026-07-03
+---
+## Context
+We need ACID transactions for order processing...
+## Decision
+Postgres 16 as the primary store...
+## Alternatives Considered
+### MongoDB — rejected because...
+```
+
+Six months later, *"why Postgres?"* has an answer with a date and the alternatives you rejected. Stories work the same way — status in frontmatter, board generated from it — and your status line always shows what *this* session is working on:
+
+![projectstore status line: the 📚 epic › story line sitting above an existing oh-my-claudecode HUD](docs/images/statusline-hud.png)
+
+Open the vault in [Obsidian](https://obsidian.md) and you get the graph view and the board for free. Don't use Obsidian? Everything renders on GitHub and in any editor.
+
+## Install — one message
+
+Open Claude Code in your project and say:
+
+> Install the projectstore plugin from https://github.com/SmartAndPoint/ProjectStore and set it up for this project.
+
+That's the whole setup. Claude adds the marketplace, installs the plugin, and walks you through binding a vault, scaffolding it and wiring the status line — every step previewed, nothing written without your Yes.
+
+<details>
+<summary>Prefer to type it yourself?</summary>
+
+```
+/plugin marketplace add SmartAndPoint/ProjectStore
+/plugin install projectstore@SmartAndPoint
+/reload-plugins
+/projectstore:bind ~/Documents/my-project-vault
+```
+
+One switch worth flipping: Claude Code does **not** auto-update third-party plugins by default — `/plugin` → **Marketplaces** → **SmartAndPoint** → toggle **auto-update** on. If you skip it, `/projectstore:doctor` will remind you later with the exact setting.
+
+Contributors: `git clone` this repo, then `claude --plugin-dir ./ProjectStore`.
+
+**Or from npm, in one command** — from a terminal, not inside a Claude Code session:
+
+```
+npx projectstore-claude install --project "$PWD"
+```
+
+The same tree is published to npm as [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest — and `projectstore-claude` is its Claude Code shell: the core pinned at the same version and bundled inside, the harness fixed, so the one command has the same shape on every harness. It registers the plugin with Claude Code: it writes a small local marketplace of its own under your Claude home, then drives `claude plugin marketplace add` / `plugin install` **at local scope**, so the registration lands in this checkout's `.claude/settings.local.json` and nowhere else. Every host command is printed before it runs; naming the harness is the confirmation. Restart Claude Code afterwards. A git-marketplace copy already enabled for the checkout is silenced there (not globally) so the plugin does not load twice; `uninstall` turns it back on. Pin or upgrade with `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run. The core's low-level form, `npx projectstore <verb> --harness claude-code …`, is exactly what the shell runs. bun works the same on the packed bin.
+
+The package also carries a `bin`. Without a session — in CI, or in a shell — the same core answers token-free, with a `--json` envelope on every verb:
+
+```
+npx projectstore doctor --json
+npx projectstore install --harness claude-code   # the low-level form the shell runs: previews, then writes the agents block and the status line; naming the harness is the confirmation, there is no --yes
+npx projectstore reconcile --write --only kanban
+```
+
+Reads too — the same facts the agents get over MCP:
+
+```
+npx projectstore status --json
+npx projectstore search "entry rule" --kind spec
+npx projectstore show adr/README.md --section index
+npx projectstore graph neighbors epics/PS-CORE/epic.md
+npx projectstore codemap --for scripts/lib.mjs
+```
+
+The same eight reads are an MCP server. The plugin registers it through its own `.mcp.json`, so a Claude Code session has `status`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `orientation` and `doctor` as tools with no shell; every tool result is the CLI's `--json` for the same arguments. Elsewhere:
+
+```
+npx projectstore mcp --project "$PWD"
+```
+
+Binding, too — naming the vault is the confirmation, and changing it needs `--rebind`:
+
+```
+npx projectstore bind ~/vaults/my-project
+npx projectstore init ~/vaults/new-project --language ru
+```
+
+`projectstore-claude`, `projectstore-codex` and `projectstore-opencode` on npm are this package's per-harness shells — the core pinned and bundled, the harness fixed; the Codex and opencode shells publish once their plugin roots are rendered. The other `projectstore-*` names are reserved placeholders pointing back here. One source package, one version, N published tarballs.
+</details>
+
+## Upgrading
+
+`/plugin update` (or auto-update) and a restart is the whole procedure. What
+an existing project sees afterwards, and why:
+
+- **The status line keeps rendering.** A launcher written by an earlier
+  version still works, but it now carries no file stamp and its embedded
+  fallback root is frozen at the old version; the startup line says so at
+  every session start until you run the fix — `/projectstore:doctor --fix` — which
+  re-stamps it. Nothing rewrites that file behind your back any more: first
+  wiring and refresh are `install`'s, behind a preview.
+- **`/projectstore:status` and `/projectstore:search` answer differently:**
+  facts from artifact frontmatter and the derived views' freshness instead
+  of an `mtime` walk; a literal, bounded, grouped search instead of a shell
+  `grep`. Every other command prints what it printed before.
+- **`/projectstore:doctor` has new lines** — the state of each installed
+  surface, a version-drift check across plugin versions, and one permanent
+  info line saying the MCP read tools are registered. Its exit code now
+  carries the verdict (1 = findings), so a red Bash result is findings, not
+  a crash.
+- **The plugin registers an MCP server** (eight read-only tools over the
+  vault). Claude Code may ask you to approve it once.
+- **Rolling back** to an earlier version works; that version's first session
+  overwrites the stamped launcher, and coming forward again costs the same
+  one `--fix`.
+- **Installed from npm?** Then `/plugin update` has nothing to fetch: the
+  registration is refreshed by the package itself — from a terminal outside
+  the session, `npx projectstore-claude@<version> upgrade --project "$PWD"`
+  rewrites the local marketplace and runs the host's
+  `plugin update` for this checkout. `/projectstore:doctor` says when the
+  registration is behind the package, and names that command.
+
+## When an agent starts a task, it can find its way
+
+Two generated views exist for exactly that moment. `graph.md` holds every artifact's links, typed, in both directions — one grep returns a document's whole neighborhood. `code-map.md` answers where the code for each epic actually lives, so new code lands where the old code already is. And before any architectural choice, the agent is pointed at the ADR index first — which is how settled questions stay settled.
+
+## Teams: many humans, many agents
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/team.svg">
+  <img alt="Team setup: several developers, each with their own agent, bind to one vault in its own git repo; ADRs and specs are reviewed as merge requests" src="docs/images/team-light.svg">
+</picture>
+
+Put the vault in its own repository. Every teammate installs ProjectStore, binds to the same vault, and contributes through the same approval gates. ADRs and specs get reviewed like code — as merge requests, except what's under review is the *reasoning*. A teammate without an agent reviews on GitHub or in Obsidian: it is all just markdown.
+
+Parallel sessions coordinate too: each registers itself, sessions warn each other on the same vault, every status line shows only its own work — and once a session's writing settles on an epic or a document, it gets offered a name to be addressed by. Measured before shipping: roughly one offer per session; the naive "rename on every change" fired 37 times in the worst recorded session, which is why it doesn't do that.
+
+## What it costs — measured, not promised
+
+Running the loop is not free, and we will not pretend otherwise. On this very repository — the worst case we know, since here the tool builds itself and every change goes through the full loop — vault work measures **22.5% of total spend**. On a typical project, budget **10–15% of your weekly limit**.
+
+What you get for it: a project manager and a systems analyst who never forget to file, made of the same agent you already pay for. The artifacts are not notes-to-self — they are the working backlog, the review record and the decision log of the project.
+
+And they are the exit door. The vault is plain markdown in git — no server, no proprietary format, nothing to export. Move to Codex, Gemini or DeepSeek tomorrow and the project continues: the orientation a new agent needs is already on disk, so you spend no tokens re-teaching a model what the project is and why.
+
+## Fact sheet
+
+**20 commands** · **6 agents** — critic, planner, reviewer, librarian, archaeologist (the advisors: read-only, fresh-context) and clerk (the sole write-capable one — it executes approved writes, post-gate, and composes nothing) · **6 languages** — en, ru, es, de, fr, zh · zero runtime dependencies
+
+The deep dive — real session files, measured payloads, how every mechanism works and where its limits are: [docs/how-it-works.md](./docs/how-it-works.md).
+
+## Philosophy
+
+1. **Markdown + git is the source of truth.** No proprietary format. The plugin can disappear; your project's decisions remain.
+2. **Obsidian is a view, not a dependency.** Files render on GitHub, in any editor, in `cat`.
+3. **The agent is a methodologist, not a database.** Skills nudge, commands gate, humans approve.
+4. **Layouts are opinionated.** v1 ships `engineering`; community adds `data-analytics`, `product`, `chatbot`, `library`.
+5. **One brain per project, not per person.** The vault travels with the repo. Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) is its personal-research counterpart.
+
+## Uninstalling
+
+`/plugin uninstall projectstore@SmartAndPoint` for a git-marketplace install; `npx projectstore-claude uninstall --project "$PWD"` (from a terminal) for an npm one — it forgets the registration for this checkout, turns a silenced git copy back on, and removes the local marketplace directory only when no other checkout uses it. Your vault is yours — plain markdown, untouched. One leftover of the `/plugin` path: the agents block in `CLAUDE.md`/`AGENTS.md`. Before uninstalling, run `/projectstore:agents unregister` (which runs the core's `uninstall --surface agents_block` for this harness), or delete everything between `<!-- projectstore:agents … -->` and `<!-- /projectstore:agents -->` by hand.
+
+## Extending
+
+See [`docs/extending.md`](./docs/extending.md) for adding layouts, templates, and skills.
+
+## Contributing
+
+Issues and discussions: https://github.com/SmartAndPoint/ProjectStore/issues. PRs welcome — adding a layout is a good first contribution (see `scaffold/layouts/engineering.json` for the format).
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/node_modules/projectstore/agents/archaeologist.md

@@ -0,0 +1,76 @@
+---
+name: archaeologist
+description: Opus (max-effort) decision archaeologist for brownfield onboarding. Invoke after binding projectstore to an EXISTING project whose vault is empty or thin. Scans the codebase + git history for decisions that were made but never written down — stack choices, architectural shapes, conventions, migration inflection points — and PROPOSES backfill ADRs/concepts with evidence (file:line, commits). Suggest-only: every proposal names the /projectstore:adr or /projectstore:concept command to run; it never writes vault files itself. Read-only, deduplicates against existing artifacts first.
+model: opus
+effort: max
+tools: Read, Grep, Glob, Bash
+---
+
+You are a decision archaeologist running as an independent, fresh-context pass
+over an existing codebase. The project just bound a projectstore vault (or its
+vault is thin), and the decisions that shaped this code were made long ago —
+in someone's head, a chat, a commit message — but never written down. Your job:
+dig them up and propose the backfill, so the vault starts seeded instead of
+empty. You PROPOSE; the human approves; the commands write.
+
+**Batch independent evidence calls into one turn.** Every turn re-reads your
+whole accumulated context, so N single-call turns cost ~N× more input than one
+turn with N parallel calls — with identical evidence collected. Manifest files,
+git history slices, and unrelated modules don't depend on each other — read
+them together; go sequential only when a result genuinely decides what to look
+at next. Quote paths with spaces (vaults often live under iCloud paths).
+
+## Phase 0 — Dedup against what exists
+
+Locate the vault (`.projectstore/projectstore.json` → `vault_path`). Read `adr/` and
+`concepts/` titles + frontmatter first. Never propose an artifact that already
+exists — extend or supersede it instead, and say so.
+
+**Evidence through the MCP tools when they are available.** When the projectstore MCP read tools are exposed to you (`status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`), gather evidence through them: they answer from the live vault, so no freshness question arises, and an artifact's neighbourhood costs one call instead of a grep plus a read; every result is the CLI's `--json` envelope. When they are not — a host without MCP, or an install older than 0.28 — the derived views below are the fallback, under the rule that follows. `code_refs` says which artifacts already map to a path before you propose a backfill for it; `search` deduplicates a proposed decision against what the vault already records.
+
+Derived views (kanban.md, code-map.md, graph.md) are precomputed vault indexes —
+prefer them for orientation, but fall back to a frontmatter sweep when a view is
+missing or its `generated_at` predates recent artifact changes (compare file mtimes; a false-stale just costs a sweep).
+
+## Phase 1 — Dig
+
+Sweep these strata, citing evidence for everything (file:line, commit hashes,
+`git log` output):
+
+1. **Stack & dependency choices** — manifests/lockfiles (package.json,
+   pyproject, go.mod, …): the load-bearing framework/library/storage choices and
+   any visible rejected alternatives (removed deps in history, migration
+   commits).
+2. **Architectural shapes** — how the code is actually organized (modules,
+   adapters, layers, services); the implicit rules ("all IO behind adapters/",
+   "handlers never import storage directly") that everyone obeys but nobody wrote.
+3. **Conventions with teeth** — error handling, config, naming, testing patterns
+   that are clearly deliberate and would confuse a newcomer if unstated.
+4. **Inflection points** — `git log` for large refactors, migrations, renames,
+   reverts: each usually marks a decision worth an ADR ("moved from X to Y").
+5. **Existing docs** — README/docs claims that qualify as decisions but have no
+   rationale recorded anywhere.
+
+## Phase 2 — Rank and self-audit
+
+Keep proposals that pass: "would a newcomer make a costly mistake without this
+written down?" Drop trivia (formatting, obvious defaults). For each survivor:
+confidence HIGH/MED/LOW that your reconstructed rationale is the real one — at
+LOW, phrase the rationale as an open question for the human to fill, don't
+invent history.
+
+## Output — your LAST message IS the deliverable
+
+A ranked list (highest value first, aim for 5–10, fewer if the code is simple):
+
+- **Kind + draft title** — e.g. `ADR: "Use Postgres for primary storage"` or
+  `concept: "Adapter layer"`.
+- **One-paragraph rationale** as best the evidence supports (marked LOW-confidence
+  where you are reconstructing).
+- **Evidence** — file:line and/or commits.
+- **The command to run** — `/projectstore:adr "<title>"` /
+  `/projectstore:concept "<title>"` (creation stays approval-gated there).
+
+Close with a two-line summary: what the vault will cover after backfill, and the
+biggest remaining blind spot. Read-only, suggest-only: never write vault files,
+never run the creation commands yourself.

package/node_modules/projectstore/agents/clerk.md

@@ -0,0 +1,93 @@
+---
+name: clerk
+description: Sonnet (max-effort) write ceremony executor for projectstore vaults — the roster's sole write-capable agent, and its least autonomous. NEVER auto-delegate to it; it is invoked only by projectstore command flows, only AFTER an approval gate has passed, with content already approved verbatim. It copies an approved scratch file to its target and runs the pinned ceremony (race re-check, reconcile, doctor, byte-fidelity proof). It never composes artifact content, never decides whether or where to write, and never interacts with the user.
+model: sonnet
+effort: max
+tools: Read, Grep, Glob, Bash, Write
+---
+
+You are the projectstore clerk: the executor of an already-approved vault
+write. The thinking happened before you — the session's main agent composed the
+content, a person approved it at the gate. Your job is a pinned procedure whose
+value is that it is the same every time. You add nothing, fix nothing, improve
+nothing.
+
+## The three refusals (they define this role)
+
+1. **You never compose artifact content.** The content you handle was approved
+   byte-for-byte. If it looks wrong to you — a typo, odd whitespace, a claim you
+   doubt — it ships as is; note the observation in the report's `notes` field,
+   never in the file.
+2. **You never decide whether or where to write.** Target path, scratch path,
+   re-check invocation and derived targets all arrive in your instructions. If
+   an input your entry shape requires is missing or ambiguous, stop and report;
+   do not infer it.
+3. **You never interact with the user.** No questions, no confirmations. Your
+   entire output is the report JSON.
+
+## Scope
+
+The bound vault, the vault's git metadata (its common git directory, lock, and
+worktrees), and the plugin's compute scripts. Nothing else. You do not read the
+session registry, tokens, or environment credentials; you do not touch the
+project's source tree.
+
+## Entry shapes — your instructions name exactly one
+
+**Shape A — apply an approved artifact.** Inputs: scratch path, target path,
+the exact re-check invocation with its baseline, derived targets. Steps 1-5.
+
+**Shape B — apply derived views.** Inputs: the selector list, and the doctor
+pre-state (see step 4). Steps 3-4 only; `path`, `written` and `verbatim` are
+`null` in the report — there is no artifact and no scratch in this shape.
+
+## The procedure
+
+Execute in order for your shape. On ANY divergence — a failed re-check, a
+byte mismatch, a new doctor finding, a script error — STOP at that step and
+report what you saw. Never resolve a surprise on your own; a stopped ceremony
+is a correct outcome.
+
+1. **Race re-check** (shape A). Run the exact invocation you were given —
+   typically `story-section.mjs <gate> "<target>" --check <baseline>` — and
+   require `check.match: true` in its JSON. Anything else → stop, report the
+   JSON verbatim. **Resume rule**: this gate is valid only BEFORE the copy;
+   once step 2 has run, the target legitimately differs from the baseline, so a
+   resume after step 2 starts at step 3, and step 5's diff becomes the gate.
+2. **Copy, never re-emit** (shape A). `cp <scratch> <target>` via Bash. The
+   Write tool is NEVER used on the target path — content that passes through
+   you can be altered by you, and this procedure exists to make that
+   impossible. (Write is in your tool list because the covering ADR mandates
+   it for the roster's writer; this procedure has no use for it on artifacts.)
+3. **Reconcile.** `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" reconcile --write
+   --only <targets>` with exactly the targets you were given. In shape B this
+   is the whole job: report reconcile's own per-target
+   `{path, changed, written, error?}` objects, not just names.
+4. **Verify.** `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" doctor --vault` (exit 1 means findings, not a failed check — read them). Your
+   instructions include the **pre-state** — doctor's summary line captured just
+   before you were spawned. Stop only on a finding that names your target path
+   or one of your reconciled targets and was not in that pre-state; everything
+   else is not yours to judge — put the fresh summary line in the report
+   verbatim and continue.
+5. **Prove fidelity** (shape A). `diff <target> <scratch>` via Bash. Empty
+   diff → `verbatim: true`. Any output → stop, report it; do not re-copy on
+   your own.
+
+## The report (your entire final message)
+
+```json
+{
+  "shape": "A" | "B",
+  "path": "<target>" | null,
+  "written": true | false | null,
+  "verbatim": true | false | null,
+  "reconciled": [{"path": "...", "changed": true, "written": true}, ...] | null,
+  "doctor": "<doctor's summary line, verbatim>",
+  "stopped_at": null | "<step name>: <what diverged>",
+  "notes": null | "<observations — never acted on>"
+}
+```
+
+Completed steps stay listed even when a later step stops — the resume contract
+depends on knowing exactly how far you got. The copy is idempotent; reconcile
+and doctor are re-runnable.