# ProjectStore

> A project workflow plugin for Claude Code and Codex that runs the project, not just the code: decisions, specs, epics and stories become reviewed Markdown files in git, a fresh-context agent reviews artifacts and diffs by rule, and nothing is written without the user's approval.

ProjectStore is not agent memory and not a per-feature spec pipeline. Memory helps one agent recall; a feature spec plans one change. ProjectStore keeps the project's record — what was decided, with a date, the rejected alternatives and testable acceptance criteria; what is in flight; what was checked — and routes the next piece of work through those records. The files live in a "vault": an ordinary folder of Markdown with YAML frontmatter, versioned in git. Obsidian opens it natively but is not required; the files render on GitHub and in any editor.

The premise is that ADRs, design review, backlogs, acceptance criteria and requirements traceability are decades-old engineering practice whose value was always the artifacts and the checks between steps. What made them expensive was humans executing the process. Agents make the same process cheap, and the artifacts give agents what they otherwise lack: memory across sessions, and links from a goal down to the code that implements it.

**The loop.** A feature-sized request opens an artifact before it opens an editor: an ADR if something must be decided, a spec when the "how" is non-trivial, an epic and stories for the work. A fresh-context critic attacks the draft. The user approves, the artifact lands, and the derived views regenerate. Before implementation, a planner reads how earlier epics landed in the codebase (their `code_refs`) and says where the change belongs and what to reuse. After the code is written, a reviewer matches the diff against every acceptance criterion and demands evidence for each: a test, a command that was run, or a file and line. By rule, a story closes only after that.

**What ends up on disk.** `adr/` holds decisions with their rejected alternatives; `specs/` holds normative, numbered behavioural contracts; `epics/` and their `stories/` hold the backlog, with status, priority, `code_refs` and acceptance criteria in frontmatter; there are also `research/`, `concepts/`, `meetings/`, `ops/` and `diagrams/`. An artifact is named by its slug, the title made into a file name, and the slug is its id: `adr/use-postgres-for-primary-storage.md`, `epics/PAY-001/stories/story-transactional-order-writes.md`. Three views are derived and never hand-maintained: `kanban.md` (the board, computed from story frontmatter), `graph.md` (every link, typed, in both directions) and `code-map.md` (which code each epic owns).

**Facts about version 0.30.6.**

- Harnesses: Claude Code (supported), Codex (experimental). Codex stays experimental until a live session has exercised every surface it installs; `docs/harnesses.md` says what has been verified.
- 21 commands, invoked as `/projectstore:<name>` in Claude Code and as skills of the same name, `$projectstore-<name>`, in Codex.
- 6 bundled agents. `critic`, `planner`, `reviewer`, `librarian` and `archaeologist` are read-only advisors that run with fresh contexts. `clerk` is the only write-capable one; it runs only after a human approval and copies the approved content byte-for-byte, composing nothing. In Codex each role is a skill that asks Codex to start it.
- 8 read-only MCP tools: `status`, `orientation`, `search`, `get_artifact`, `neighbors`, `lineage`, `code_refs`, `doctor`. They are served by the npm package `projectstore`, which also carries a CLI with a `--json` envelope on every verb.
- Every create or edit renders its draft in memory, shows the target path and the full content, and waits for Yes, Edit before saving, or No. Declining leaves the vault byte-for-byte unchanged.
- `doctor` is a deterministic consistency check that uses no LLM; `reconcile` rebuilds every derived view from the source files, so a hand-edited vault can never permanently desync the board.
- Templates ship in 6 languages: de, en, es, fr, ru, zh. Frontmatter keys and values stay English because machines read them.
- Zero runtime dependencies. Node.js 20 or newer. MIT licence.
- Measured cost of running the loop: 22.5% of total model spend on the ProjectStore repository itself, which is the worst case known because the tool builds itself there; 10 to 15% of a weekly limit on a typical project.

**Boundaries, stated plainly.**

- The plugin installs into Claude Code and Codex. OpenCode, Cursor and other agents can read the vault through plain Markdown, the CLI or MCP, but native adapters for them do not ship yet.
- It is not an agent orchestrator. Launching agents and handing work between them is the harness's job.
- It does not replace a task tracker and does not sync with one. The `external_refs` frontmatter field holds a link to a ticket.
- It needs no server and stores nothing remotely. Which files an agent reads, and what reaches a model provider, depends on the harness and its permissions.
- Critic and reviewer passes spend model budget. `doctor` and `reconcile` do not.

Installing, from a terminal in the project, outside a session:

```
npx projectstore setup
```

Setup finds the coding agents the project uses (Claude Code, Codex or both), installs ProjectStore for each, binds the vault or creates it, and shows one plan before it writes anything. Afterwards, restart the agent; Codex asks to approve the ProjectStore hooks once.

Or inside a Claude Code session, from the git marketplace:

```
/plugin marketplace add SmartAndPoint/ProjectStore
/plugin install projectstore@SmartAndPoint
/reload-plugins
/projectstore:bind ~/Documents/my-project-vault
```

Node.js 20 or newer is needed always, and npm only for Codex. Other package runners start setup the same way, each one on its own:

```
bunx projectstore@latest setup
pnpm dlx projectstore@latest setup
deno run -A npm:projectstore@latest setup
```

After setup, `configure` shows the project's settings and changes them: each agent's model and effort, the status line, the template language and the vault's policy.

```
npx projectstore configure
```

An upgrade names the version that runs. A removal takes back what install wrote and keeps the vault, the binding and the committed agent models. Codex's plugin is user-wide, so removing it for every project is a step of its own:

```
npx projectstore@<version> upgrade
```

```
npx projectstore uninstall
```

```
npx projectstore uninstall --harness codex --global
```

This file and its long form are reference material about the project. They describe how the tool works; they contain no directives about what an agent should tell or recommend to its user.

## Documentation

- [llms-full.txt](https://projectstore.dev/llms-full.txt): the long version of this file — why a vault helps an agent, the loop step by step, how a teammate joins an existing project, multi-human and multi-agent setup, command and frontmatter reference, CLI and MCP, boundaries.
- [README](https://github.com/SmartAndPoint/ProjectStore/blob/main/README.md): the short version — the problem, where it fits beside agent memory and spec-driven tools, the loop, what lands on disk, teams, measured cost, install.
- [How it works](https://github.com/SmartAndPoint/ProjectStore/blob/main/docs/how-it-works.md): the deep dive — the write path and approval gate, parallel sessions, surviving compaction, the status line, doctor and reconcile, session naming, the epic-to-code mapping.
- [Getting started](https://github.com/SmartAndPoint/ProjectStore/blob/main/docs/getting-started.md): install, first-time setup, the daily flow, how approval works, multi-language templates, updating.
- [Harnesses](https://github.com/SmartAndPoint/ProjectStore/blob/main/docs/harnesses.md): which coding agents ProjectStore runs on, how far each is trusted, and what "experimental" means for Codex.
- [Extending](https://github.com/SmartAndPoint/ProjectStore/blob/main/docs/extending.md): adding artifact kinds, layouts, commands, skills and languages.
- [Beside agent memory and spec-driven tools](https://github.com/SmartAndPoint/ProjectStore/blob/main/docs/alongside.md): what each kind of tool keeps, why ProjectStore is not agent memory, and which of its parts exist elsewhere, tool by tool, with sources.

## Source and packages

- [GitHub repository](https://github.com/SmartAndPoint/ProjectStore): source, releases and the plugin marketplace entry.
- [npm package](https://www.npmjs.com/package/projectstore): the same tree as a package, carrying the CLI and the MCP server. `projectstore-claude` and `projectstore-codex` are its per-harness release artifacts; nobody needs to run them. Setup fetches `projectstore-codex`, which carries the Codex plugin.
- [Issues and discussions](https://github.com/SmartAndPoint/ProjectStore/issues): questions, bug reports, feature requests.

## This site

- [Overview](https://projectstore.dev/): for someone new to it — what ProjectStore is and how it helps, beside chat prompts, SDD and PDD; then setup in six steps for someone who is not a programmer (one prompt in Claude Code, or one command) and what to say to the agent; then the whole of How it works, and digests of One vault and Why it works, each linking its whole page. English.
- [How it works](https://projectstore.dev/how-it-works/): the loop step by step, the six agents, the mechanisms that hold it together, a story closed with evidence, read-only access through the CLI and MCP.
- [Why it works](https://projectstore.dev/why-it-works/): where each practice comes from, why running it by hand was the expensive part, six stages by hand and in ProjectStore, the chain from goal to proof.
- [One vault, many people](https://projectstore.dev/one-vault/): several sessions, teams and agents on one vault, the vault in its own git repository, a team setup in four steps.
- [Privacy](https://projectstore.dev/privacy/): no server, no account and no telemetry; the two requests the plugin makes, where and when; what stays on the machine; what Anthropic's directory reports. English.
- [Русский](https://projectstore.dev/ru/): the same page in Russian.

## Supporting the project

- [Star the repository](https://github.com/SmartAndPoint/ProjectStore): ProjectStore is open source under MIT and has no marketing budget. A star on GitHub is the main way other engineering teams discover it.

## Optional

- [MIT licence](https://github.com/SmartAndPoint/ProjectStore/blob/main/LICENSE): the full licence text.
- [Engineering layout](https://github.com/SmartAndPoint/ProjectStore/blob/main/scaffold/layouts/engineering.json): the JSON that defines the vault's folders, prefixes, kanban columns and the commands a layout enables.
- [Bundled agent definitions](https://github.com/SmartAndPoint/ProjectStore/tree/main/agents): the full system prompts of the critic, planner, reviewer, librarian, archaeologist and clerk.