projectstore-claude 0.0.1 → 0.28.0-rc.3

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,88 @@
+#!/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",
+      env: { ...process.env, PROJECTSTORE_DISTRIBUTION_ROOT: root },
+    });
+    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.3",
+      "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.3",
+  "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,264 @@
+# 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 project workflow plugin for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex](https://developers.openai.com/codex/) (experimental).
+
+---
+
+## 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.
+
+**Codex uses its own rendered plugin root and the same one-command shape.**
+Codex support is **experimental** (see [`docs/harnesses.md`](./docs/harnesses.md)
+for what has been measured and what has not), and its shell is not published
+yet. From this checkout, exercise the exact npx path against the built tarball:
+
+```sh
+npm run shells:build -- --only projectstore-codex --dev --out dist
+npx --package "./dist/projectstore-codex-$(node -p 'require("./package.json").version').tgz" projectstore-codex install --project "$PWD"
+```
+
+The Codex shell carries a canonical portable manifest, namespaced workflow and
+role skills, lifecycle hooks, and the exact bundled core. It stages a stable
+marketplace under `CODEX_HOME`, drives `codex plugin marketplace add` and
+`codex plugin add`, then reads the installation back and verifies its version
+and payload digest. Restart Codex, approve the hooks, and run
+`$projectstore-bind <vault-path>`. After the first explicit npm publication,
+the shorter command is
+`npx projectstore-codex@<version> install --project "$PWD"`; use its `upgrade`
+verb for later releases. Because Codex's
+plugin registry is user-global, ordinary uninstall removes only the project's
+agents block; `uninstall --global` is the explicit machine-wide removal.
+
+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` are this package's per-harness shells — the core pinned and bundled, the harness fixed. Codex's shell is experimental and stays private until a live run has exercised every surface it installs, from an installed release ([`docs/harnesses.md`](./docs/harnesses.md)). The opencode shell publishes after its plugin root is rendered. The other `projectstore-*` names are reserved placeholders pointing back here. One source package, one version, N tarballs.
+</details>
+
+## Upgrading
+
+`/plugin update` (or auto-update) and a restart, then one command per project
+bound before 0.28. What an existing project sees afterwards, and why:
+
+- **The project's files move to `.projectstore/`.** `.claude/projectstore.json`
+  and `.claude/.projectstore/` become `.projectstore/projectstore.json`,
+  `.projectstore/harness/claude-code.json` and `.projectstore/state/`. Nothing
+  breaks before you move them: every reader falls back to the old paths through
+  0.29, and the startup line names the command until the move is done. Close
+  every Claude Code session in the project, run that command from a terminal,
+  then restart. The command depends on how you installed:
+  - **From the git marketplace** (every 0.27.x install): the installed copy's
+    own `bin/projectstore.mjs`, with its path spelled out in the startup line —
+    `node "<plugin cache>/bin/projectstore.mjs" upgrade --harness claude-code --no-register --project "$PWD"`.
+    `--no-register` leaves your plugin registration as it is.
+  - **From npm**: `npx projectstore-claude@<version> upgrade --no-register --project "$PWD"`.
+
+  Both forms move only the project's files, so neither touches your plugin
+  registration. The same run re-stamps the status-line launcher at its new path
+  and re-registers the agents block, whose template is now v4. A plain
+  `npx projectstore-claude upgrade` on a git-marketplace install does more: it
+  also registers the plugin from npm for this checkout and turns the
+  git-marketplace copy off here, so `/plugin update` stops reaching the
+  checkout. If that already happened,
+  `npx projectstore-claude@<version> uninstall --surface plugin --project "$PWD"`
+  turns the git-marketplace copy back on. Restart, then run
+  `/projectstore:doctor --fix` in the new session, which re-stamps the status
+  line against that copy.
+- **The status line keeps rendering.** A launcher written by an earlier version
+  still works, but it carries no file stamp and its embedded fallback root is
+  frozen at the old version; the move above 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.
+- **The agents block stays where Claude Code reads it.** In a project with an
+  `AGENTS.md`, the block goes there and `CLAUDE.md` carries a one-line
+  `@AGENTS.md` import; otherwise the block goes into `CLAUDE.md`. A project with
+  an `AGENTS.md` and no `CLAUDE.md` now gains that one-line `CLAUDE.md`.
+- **The passive skills are published under the `projectstore-` prefix**
+  (`projectstore-decision-detector`, `projectstore-peer-reviewer`,
+  `projectstore-story-completion`, `projectstore-vault-communication`). Nothing
+  in a project names them; only a skill listing shows the new names.
+- **Rolling back** to 0.27.x after the move: 0.27.x looks for its binding under
+  `.claude/`, finds none and offers `bind`. Do not accept. A re-bind writes
+  `.claude/projectstore.json` again, and 0.28's `install` and `upgrade` refuse
+  while two bindings exist. To come forward again, delete
+  `.claude/projectstore.json`, then run the command the startup line names
+  once more: a 0.27.x session writes its welcome marker back under `.claude/`.
+- **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 Claude git-marketplace install; `npx projectstore-claude uninstall --project "$PWD"` for its npm registration. For Codex, `npx projectstore-codex uninstall --project "$PWD"` removes only project-owned wiring; add `--global` only to remove the user-global Codex plugin and marketplace. Your vault is yours — plain markdown, untouched. One leftover of a host-managed plugin path can be the agents block in `CLAUDE.md`/`AGENTS.md`; remove it with the harness's agents unregister skill, or delete everything between `<!-- projectstore:agents … -->` and `<!-- /projectstore:agents -->` by hand. `uninstall` leaves a block that lives in `AGENTS.md`, because that file is read by other coding agents too, and removes the `CLAUDE.md` import when that file holds nothing else; `uninstall --surface agents_block` removes the block as well.
+
+## Extending
+
+See [`docs/extending.md`](./docs/extending.md) for adding layouts, templates, and skills, and [`docs/harnesses.md`](./docs/harnesses.md) for which coding agents projectstore runs on — what "experimental" means there, and what adding one takes.
+
+## 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.