projectstore-codex 0.0.1 → 0.28.1

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "projectstore-codex",
-  "description": "Reserved name. The package you want is `projectstore`.",
-  "version": "0.0.1",
-  "license": "MIT",
-  "author": {
-    "name": "Evgenii Konev",
-    "email": "ekonev@smartandpoint.com",
-    "url": "https://github.com/SmartAndPoint"
-  },
+  "version": "0.28.1",
+  "description": "ProjectStore for Codex: portable project memory, rendered workflow skills and lifecycle hooks, with the core pinned and bundled.",
+  "keywords": [
+    "projectstore",
+    "installer",
+    "codex",
+    "project-management",
+    "adr",
+    "markdown",
+    "agentic"
+  ],
   "homepage": "https://github.com/SmartAndPoint/ProjectStore#readme",
   "bugs": {
     "url": "https://github.com/SmartAndPoint/ProjectStore/issues"
@@ -16,13 +19,32 @@
     "type": "git",
     "url": "git+https://github.com/SmartAndPoint/ProjectStore.git"
   },
-  "keywords": [
-    "projectstore",
-    "placeholder",
-    "reserved"
-  ],
+  "license": "MIT",
+  "author": {
+    "name": "Evgenii Konev",
+    "email": "ekonev@smartandpoint.com",
+    "url": "https://github.com/SmartAndPoint"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "projectstore-codex": "bin/projectstore-codex.mjs"
+  },
   "files": [
-    "README.md"
+    "bin/",
+    "README.md",
+    "plugin.json",
+    ".codex-plugin/",
+    "skills/",
+    "hooks/"
+  ],
+  "dependencies": {
+    "projectstore": "=0.28.1"
+  },
+  "bundleDependencies": [
+    "projectstore"
   ],
   "publishConfig": {
     "access": "public"

package/plugin.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "projectstore",
+  "version": "0.28.1",
+  "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",
+    "email": "ekonev@smartandpoint.com",
+    "url": "https://github.com/SmartAndPoint"
+  },
+  "homepage": "https://github.com/SmartAndPoint/ProjectStore#readme",
+  "repository": "git+https://github.com/SmartAndPoint/ProjectStore.git",
+  "license": "MIT",
+  "keywords": [
+    "project-management",
+    "adr",
+    "epics",
+    "stories",
+    "kanban",
+    "obsidian",
+    "markdown",
+    "knowledge-base",
+    "engineering-process",
+    "claude-code",
+    "codex",
+    "agentic",
+    "ai-agents"
+  ],
+  "extensions": {
+    "com.openai": {
+      "hooks": "./hooks/hooks.json",
+      "interface": {
+        "displayName": "ProjectStore",
+        "shortDescription": "Versioned project memory for developer teams and agents.",
+        "longDescription": "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.",
+        "developerName": "SmartAndPoint",
+        "category": "Developer Tools",
+        "capabilities": [
+          "Project memory",
+          "Architecture decisions",
+          "Planning",
+          "Peer review"
+        ],
+        "websiteURL": "https://github.com/SmartAndPoint/ProjectStore#readme",
+        "defaultPrompt": [
+          "Show the current ProjectStore status and work in progress.",
+          "Capture this technical decision as a ProjectStore ADR.",
+          "Plan the next ProjectStore story, then review the implementation."
+        ]
+      }
+    }
+  }
+}

package/skills/projectstore-adr/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: projectstore-adr
+description: "Create a new Architecture Decision Record (ADR) in the bound vault. Arguments: <title>."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+You are creating a new ADR.
+
+Steps:
+
+1. **Check config**: `test -f .projectstore/projectstore.json` — if missing, tell user to run `$projectstore-bind <path>` and stop.
+
+2. **Render draft** by running:
+
+   ```bash
+   node "${PROJECTSTORE_CORE_ROOT}/scripts/draft.mjs" adr "<user-arguments>"
+   ```
+
+   The script outputs JSON with shape `{ kind, path, content, index, collision, warnings, vars }`. Capture stdout.
+
+3. **Show user a preview**: print the target `path`, then the first ~30 lines of `content` in a code block. State the slug (it IS the identity — ADR-010). If `index` is non-null, print `index.line` — the exact row that will appear in the folder index (rendered by the regeneration's own rules, so it is what lands, not an approximation), unless the index step reports a failure and no row lands at all. Render every entry in `warnings` as a `⚠️` line. If `collision` is non-null, surface it as a **topic collision**: `⚠️ "<identity>" already exists as <with> — same topic, two artifacts.` Ask whether to open/extend the existing artifact, pick a genuinely different slug (a deliberate `-2` suffix is a distinct identity and stays legal), or cancel. Do not write over a collision without an explicit user decision.
+
+4. **Approval**: use the harness's user-input mechanism with options:
+   - **Yes** — write the file as-is
+   - **Edit before saving** — let the user describe a change; you regenerate accordingly (e.g., adjust title, status, add tags) and re-preview
+   - **No** — abort
+
+   This is the only gate: **Yes** covers both the artifact and its index row.
+   Disclose in the question that the folder's whole managed index table is
+   regenerated from vault state at write time, so the update may also repair
+   a stale row for another artifact.
+
+5. **Post-approval race re-check** (Layer 1 — multi-session safety): re-run `draft.mjs adr "<user-arguments>"` and re-read `collision` — a plain `test -e` cannot see normalized cross-era collisions, and another session may have created the same topic while you waited on approval. If `collision` is now non-null (or changed), show it as in step 3 and re-ask. The slug is derived from the title, so the re-render is byte-identical otherwise — never expect a "fresh number".
+
+6. **On Yes** (path free): use the file-writing tool to write `content` to `path`.
+
+7. **Index update** (only if `index` field is non-null — skip silently otherwise):
+   apply through the core — never the Write/file-editing tools, and do not ask again:
+
+   ```bash
+   node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" reconcile --write --only indexes=<index.folder>
+   ```
+
+   The index row is derived state: the regeneration renders it in canonical
+   order (date, then number/slug), replaces the file atomically, and preserves
+   manual prose outside the managed table. Never substitute the class-wide
+   `indexes` selector — that would regenerate every folder index.
+
+   The artifact is already on disk, so a failure here is a warning, never a
+   failed creation. Two shapes, both reported naming the folder:
+   - **stderr, no stdout JSON** — the named target was rejected before any
+     write (README absent, or its index header matches no registered form).
+     Suggest fixing the header (`$projectstore-doctor`) or restoring the
+     README; the row lands on the next reconcile.
+   - **JSON with a per-target `error`, nonzero exit** — an I/O failure during
+     the write. Suggest `$projectstore-reconcile`.
+
+8. **Final message**: print the file path, a reminder to fill `Context`, `Decision`, `Rationale`, and a hint to commit the new ADR if the vault is git-tracked.

package/skills/projectstore-agents/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: projectstore-agents
+description: "Register or remove ProjectStore's shared agents block, inspect its Codex model overlay, or configure per-role models. Arguments: <register | unregister | status | configure>."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+You are managing ProjectStore's Codex agent integration. Require a bound project.
+
+## register / unregister
+
+Preview the requested change and ask for explicit approval. On approval, run the
+core's `install` or `uninstall` verb with `--harness codex --surface
+agents_block --project "$PWD"`. Print its output verbatim. Never edit the
+managed block by hand.
+
+## status
+
+Run `plan --json --harness codex --surface agents_block --project "$PWD"`,
+then `agents show --json --project "$PWD"`. Report the block state and each
+role's resolved model and source. The active overlay path returned by the core
+is authoritative.
+
+## configure
+
+Ask for a default model and optional per-role model ids. Use actual Codex model
+ids supplied by the user or visible in the current host; do not translate model
+names from another harness. Preview the exact argv, ask for approval, then run
+`agents configure --harness codex [--default <model>] [--agent
+<role>=<model> ...] --project "$PWD"`. The core is the only writer. Do not pass
+an effort override: per-role effort is outside this integration's current
+contract. A configured model is consumed by the role-orchestration skills on
+their next spawn; no restart is needed.

package/skills/projectstore-archaeologist/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: projectstore-archaeologist
+description: "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."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+## Codex orchestration
+
+This is a role-orchestration skill, not a native agent registration. Resolve the
+role model by running:
+
+```bash
+node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" agents model archaeologist --json --project "$PWD"
+```
+
+Spawn a collaboration agent for the bounded task. If the result names a model,
+pass that model and use an empty or bounded context fork; otherwise inherit the
+current model. Do not pass a reasoning-effort override: per-role effort belongs
+to a separate accepted story. Give the spawned agent the role contract below
+and the exact artifact/diff it must inspect. Wait for its final result.
+
+## Role contract
+
+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/skills/projectstore-bind/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: projectstore-bind
+description: "Bind this project to an existing ProjectStore vault, or initialize and bind a new vault, using the harness-neutral core. Arguments: [vault-path]."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+Bind the current project through the core; never write the binding by
+hand.
+
+1. Resolve the requested vault path. If it exists, use `bind`; if the user
+   explicitly asks to create it, use `init`. Ask for layout and language only
+   when the user has not supplied them.
+2. Show the resolved project, vault, verb, layout and language. Ask for explicit
+   approval. Naming the vault is the core's non-interactive confirmation.
+3. Run `node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" <bind|init>
+   "<vault-path>" --layout <layout> --language <language> --project "$PWD"
+   --json` and report the result. Use `--rebind` only when the user explicitly
+   approved replacing an existing binding.
+4. Run `status --json` to verify the stored path and policies. Offer
+   `$projectstore-scaffold` only for a newly initialized empty vault.
+
+Codex plugin updates are performed with the `projectstore-codex upgrade`
+installer command; this skill never sends the user to another harness's plugin
+UI. Codex has no ProjectStore status-line surface, so binding does not offer or
+write one. Model choices, when requested, go through `$projectstore-agents
+configure` and the Codex overlay.

package/skills/projectstore-clerk/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: projectstore-clerk
+description: "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."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+## Codex orchestration
+
+This is a role-orchestration skill, not a native agent registration. Resolve the
+role model by running:
+
+```bash
+node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" agents model clerk --json --project "$PWD"
+```
+
+Spawn a collaboration agent for the bounded task. If the result names a model,
+pass that model and use an empty or bounded context fork; otherwise inherit the
+current model. Do not pass a reasoning-effort override: per-role effort belongs
+to a separate accepted story. Give the spawned agent the role contract below
+and the exact artifact/diff it must inspect. Wait for its final result.
+
+## Role contract
+
+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
+   file-writing 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 "${PROJECTSTORE_CORE_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 "${PROJECTSTORE_CORE_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.

package/skills/projectstore-codemap/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: projectstore-codemap
+description: "Regenerate code-map.md (epic ↔ code overview) from frontmatter code_refs, or set an artifact's code_refs. The command is the write path — planner/reviewer only propose refs. Arguments: [set <epic-id | story-path> <ref> [ref…]]."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+You are managing the epic↔code mapping (ADR-004).
+
+## Bare `codemap` — regenerate the view
+
+1. **Check config**; stop if missing.
+2. Compute (read-only, the unified reconcile path):
+
+   ```bash
+   node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" reconcile --only codemap
+   ```
+
+   The `codemap` entry carries `{ path, changed, content?, stats }`.
+3. Show `stats` (epics, epics_with_refs, story_rows) + first ~15 lines of
+   `content` when changed.
+4. **Approval** via the harness's user-input mechanism: Yes / No (disclose: content is recomputed
+   from frontmatter at write time; the preview is advisory). On Yes → apply
+   through the core, never the file-writing tool:
+
+   ```bash
+   node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" reconcile --write --only codemap
+   ```
+
+   Explicit selection writes the map even on a vault with no `code_refs` yet.
+   Render the report's `codemap` entry; nonzero exit — surface the `error`.
+5. Suggest: "Refs are set via `codemap set`; reviewer proposes updates at story completion."
+
+## `codemap set <target> <ref…>` — update frontmatter (the write path)
+
+1. **Resolve target**: an epic id (`PS-AGENTS` → `epics/PS-AGENTS/epic.md`) or a
+   story path relative to the vault. Stop with a clear error if not found.
+2. **Read the file**, show current `code_refs` vs proposed (`["src/auth/", …]`).
+   Validate: repo-relative paths/globs; warn (don't block) on paths that don't
+   exist yet — planning-time refs are legitimate (doctor is status-aware).
+3. **Approval** via the harness's user-input mechanism (diff preview). On Yes → Edit the frontmatter
+   `code_refs` line only; also bump `updated:` if the artifact has it.
+4. **Offer regen**: "Refresh the view? (runs bare `codemap`)" — on Yes, run the
+   bare flow above.
+
+## Notes
+
+- Story `code_refs` = files that story touched; epic `code_refs` = the epic's
+  overall footprint. Doctor checks story ⊆ epic and path existence
+  (status-aware). `reconcile` also regenerates the view.
+- Never write refs without approval; never let an agent edit them directly —
+  planner/reviewer *propose*, this command *writes*.

package/skills/projectstore-concept/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: projectstore-concept
+description: "Create a new concept note (definition, mental model, glossary entry). Arguments: <title>."
+---
+
+## Runtime path
+
+Resolve paths from this skill's own directory, never from the checkout or a
+remembered cache path. The plugin root is two directories above this SKILL.md;
+the bundled core is `<plugin-root>/node_modules/projectstore`. Before running
+any ProjectStore command, export `PROJECTSTORE_CORE_ROOT` to that bundled-core
+path in its own shell statement, then use `node "${PROJECTSTORE_CORE_ROOT}/…"`.
+Do not prefix the command with the assignment: a shell expands the quoted path
+before that inline assignment takes effect. If the bundled core is missing, stop
+and report a broken plugin install; do not fetch a different version from npm.
+
+## User arguments
+
+The source command's host-substituted argument token is rendered here as
+`<user-arguments>` (or `<user-arguments-without-fix>`). Before executing a
+shown command, replace that token with the actual arguments from the user's
+request and shell-quote values safely. Never pass the angle-bracket token
+literally and never treat it as a shell variable.
+
+You are creating a concept note.
+
+Steps:
+
+1. Check config; stop if missing.
+2. Run `node "${PROJECTSTORE_CORE_ROOT}/scripts/draft.mjs" concept "<user-arguments>"`.
+3. Preview path + first ~15 lines. When `index` is non-null, print `index.line` too — the exact row that will appear in the folder index, unless the index step reports a failure and no row lands at all.
+4. the harness's user-input mechanism: Yes / Edit / No. This is the only gate: **Yes** covers the artifact and its index row. Disclose in the question that the folder's whole managed index table is regenerated from vault state at write time, so the update may also repair a stale row for another artifact.
+5. Pre-write race check (Layer 1): `test -e "<path>"`. If exists, ask: **Overwrite**, **Use new slug** (`-2`), or **Cancel**.
+6. On Yes (path free or overwrite confirmed): Write file.
+7. Index row, if `index` is non-null — apply through the core, never Write/Edit, no second gate (step 4 covers it): `node "${PROJECTSTORE_CORE_ROOT}/bin/projectstore.mjs" reconcile --write --only indexes=<index.folder>`. The row is derived state: canonical order, atomic write, manual prose preserved. The file is already on disk, so a nonzero exit is a warning naming the folder (stderr with no JSON = rejected before any write, fix the header or restore the README; `error` in JSON = I/O failure, suggest `$projectstore-reconcile`), never a failed creation.
+8. Suggest: "Define `What is it` first, then `How it works`. Link from ADRs/research that reference this concept."