attraverso 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,98 @@
1
+ # attraverso
2
+
3
+ Durable, structured project memory for AI coding agents, over [MCP](https://modelcontextprotocol.io).
4
+
5
+ An agent is good at working on a project and bad at remembering it three weeks later. The usual workaround is
6
+ a `CLAUDE.md` file that grows unmaintainably, cannot be queried, and rots. Attraverso moves that state into a
7
+ real store: the plan, the reasoning behind it, and the record of what was decided - retrieved as a
8
+ budget-bounded slice rather than dumped into context wholesale.
9
+
10
+ The plan lives as version-controlled YAML committed alongside your code, so it is reviewable in a pull request
11
+ like any other file, and is rebuilt into an in-memory Postgres ([PGlite](https://pglite.dev)) on load.
12
+
13
+ ## Using it
14
+
15
+ Requires Node 22 or newer.
16
+
17
+ ### In Claude Code
18
+
19
+ Add it to the `.mcp.json` at the root of your repo:
20
+
21
+ ```json
22
+ {
23
+ "mcpServers": {
24
+ "attraverso": {
25
+ "command": "npx",
26
+ "args": ["-y", "attraverso"]
27
+ }
28
+ }
29
+ }
30
+ ```
31
+
32
+ The plan, `attraverso.yaml`, is created at the root of the repo on first run. Commit it: it is the source of
33
+ truth, and its diffs are the history of the plan. Readings and attachments go in an `.attraverso/` folder
34
+ beside it, committed too.
35
+
36
+ Then ask the agent to call `get_project`, or just to create a project and start planning. The tools describe
37
+ themselves, and `get_project` returns the project's protocol - its operating manual - first.
38
+
39
+ ### Where the plan lives
40
+
41
+ In order of precedence:
42
+
43
+ 1. `--store <path>` (repeatable: a plan can span several files), or `APM_STORE_PATH`.
44
+ 2. The nearest `attraverso.yaml` found walking up from the working directory, like `tsconfig.json`. Inside a git
45
+ repo the search stops at the repo's root.
46
+ 3. In a git repo with no plan yet, `attraverso.yaml` at the repo's root, created on first run.
47
+ 4. Outside any repo, `~/.ai-project-manager/attraverso.yaml`, for a personal project with no repo to live in.
48
+
49
+ To keep the plan somewhere else - under another name, in a subfolder, or one file shared by several repos -
50
+ name it with `--store`. A relative path is resolved from the repo root, where Claude Code starts the server:
51
+
52
+ ```json
53
+ "args": ["-y", "attraverso", "--store", "../plans/shared.yaml"]
54
+ ```
55
+
56
+ Repeat `--store` to load a plan split across files; the first one named is where new projects go.
57
+
58
+ **Plan files from before 0.1.2 are named `*.apm.yaml`**, with their data in `.apm/`. They are still found and
59
+ loaded, and always will be. To move one over, rename both: `git mv roadmap.apm.yaml attraverso.yaml` and
60
+ `git mv .apm .attraverso`.
61
+
62
+ ### Seeing it
63
+
64
+ Ask the agent to open the viewer (the `open_viewer` tool). It serves the plan as a dependency graph on a
65
+ `127.0.0.1` address, so it only opens on the machine running the server.
66
+
67
+ ### Claude Desktop
68
+
69
+ Claude Desktop starts servers without your shell's `PATH`, so a bare `npx` or `node` is often not found. See
70
+ [docs/claude-desktop.md](docs/claude-desktop.md) for the setup and the three ways it silently breaks.
71
+
72
+ ## Developing
73
+
74
+ ```sh
75
+ yarn install
76
+ yarn verify # typecheck, viewer build, unit tests
77
+ yarn verify:all # plus the end-to-end suite (once: npx playwright install chromium)
78
+ yarn viewer # the graph on http://localhost:5176
79
+ ```
80
+
81
+ `yarn test:pg` runs the same suite against a server Postgres (`yarn pg:up` starts one in Docker).
82
+
83
+ To try a change against a real plan, run the server from source over any store: `yarn mcp:dev --store
84
+ <path>`, or point a `.mcp.json` at `node_modules/.bin/vite-node src/mcp/server.ts`.
85
+
86
+ Releasing is `yarn release` (`--dry-run` to rehearse), from an up-to-date checkout of this repo: it verifies,
87
+ builds, checks the build starts with clean stdout, publishes to npm and tags the version. The published package
88
+ is a single self-contained build that needs nothing installed but Node.
89
+
90
+ ## How this repo is maintained
91
+
92
+ Attraverso is developed in a private repository alongside a hosted version, and the open core is mirrored here
93
+ automatically. Issues and pull requests are welcome here; a merged pull request is carried across to the
94
+ private repository with its authorship kept, and comes back out in the next export.
95
+
96
+ ## Licence
97
+
98
+ [Apache-2.0](LICENSE).
@@ -0,0 +1,3 @@
1
+ ALTER TABLE "items" ADD COLUMN "start_on" text;--> statement-breakpoint
2
+ ALTER TABLE "items" ADD COLUMN "due_on" text;--> statement-breakpoint
3
+ CREATE INDEX "items_project_due" ON "items" USING btree ("project_id","due_on");