diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 84 |
1 files changed, 61 insertions, 23 deletions
@@ -3,28 +3,30 @@ Fidget Spinner is a local-first, agent-first experimental DAG for autonomous program optimization and research. -The current MVP is built around four ideas: +It is aimed at the ugly, practical problem of replacing sprawling experiment +markdown in worktree-heavy optimization projects such as `libgrid` with a +structured local system of record. + +The current shape is built around four ideas: - the DAG is canonical truth - frontier state is a derived projection - project payload schemas are local and flexible - core-path experiment closure is atomic -The immediate target is not open-ended science in the abstract. It is the ugly, -practical problem of replacing gigantic freeform experiment markdown in -worktree-heavy optimization projects such as `libgrid`. - -## Current MVP +## Current Scope Implemented today: - typed Rust core model - per-project SQLite store under `.fidget_spinner/` - project-local schema file +- light-touch project field types: `string`, `numeric`, `boolean`, `timestamp` - hidden and visible node annotations - core-path and off-path node classes -- CLI for bootstrap and repair +- CLI for local project work - hardened stdio MCP host via `mcp serve` +- minimal web navigator via `ui serve` - replay-aware disposable MCP worker runtime - MCP health and telemetry tools - bundled `fidget-spinner` base skill @@ -33,7 +35,7 @@ Implemented today: Not implemented yet: - long-lived daemon -- web UI +- full web UI - remote runners - strong markdown migration - cross-project indexing @@ -64,28 +66,54 @@ cargo run -p fidget-spinner-cli -- frontier init \ Record low-ceremony off-path work: ```bash +cargo run -p fidget-spinner-cli -- tag add \ + --project . \ + --name dogfood/mvp \ + --description "Self-hosted MVP dogfood notes" +``` + +```bash cargo run -p fidget-spinner-cli -- research add \ --project . \ --title "next feature slate" \ --body "Investigate pruning, richer projections, and libgrid schema presets." ``` +```bash +cargo run -p fidget-spinner-cli -- note quick \ + --project . \ + --title "first tagged note" \ + --body "Tag-aware note capture is live." \ + --tag dogfood/mvp +``` + Serve the local MCP surface in unbound mode: ```bash cargo run -p fidget-spinner-cli -- mcp serve ``` +Serve the minimal local navigator: + +```bash +cargo run -p fidget-spinner-cli -- ui serve --project . --bind 127.0.0.1:8913 +``` + Then bind the session from the client with: ```json {"name":"project.bind","arguments":{"path":"<project-root-or-nested-path>"}} ``` +If the target root is an existing empty directory, `project.bind` now +bootstraps `.fidget_spinner/` automatically instead of requiring a separate +`init` step. Non-empty uninitialized directories still fail rather than being +guessed into existence. + Install the bundled skills into Codex: ```bash -./scripts/install-codex-skill.sh +cargo run -p fidget-spinner-cli -- skill install ``` ## Store Layout @@ -101,7 +129,12 @@ Each initialized project gets: ``` `schema.json` is the model-facing contract for project-local payload fields and -their validation tiers. +their validation tiers. Fields may now optionally declare a light-touch +`value_type` of `string`, `numeric`, `boolean`, or `timestamp`; mismatches are +diagnostic warnings rather than ingest blockers. + +`.fidget_spinner/` is local state. In git-backed projects it usually belongs in +`.gitignore` or `.git/info/exclude`. ## Model-Facing Surface @@ -112,6 +145,8 @@ The current MCP tools are: - `project.bind` - `project.status` - `project.schema` +- `tag.add` +- `tag.list` - `frontier.list` - `frontier.status` - `frontier.init` @@ -132,32 +167,35 @@ JSON-RPC session and delegates tool execution to an internal worker subprocess. Safe replay is only allowed for explicitly read-only operations and resources. Mutating tools are never auto-replayed after worker failure. +Notes now require an explicit `tags` list. Tags are repo-local registry entries +created with `tag.add`, each with a required human description. `note.quick` +accepts `tags: []` when no existing tag applies, but the field itself is still +mandatory so note classification is always conscious. + The intended flow is: 1. inspect `system.health` 2. `project.bind` to the target project root or any nested path inside it -3. read the schema and frontier -4. pull context from the DAG -5. use cheap off-path writes liberally -6. record a `change` before core-path work -7. seal core-path work with one atomic `experiment.close` +3. read `project.status`, `tag.list`, and `frontier.list` +4. read `project.schema` only when payload rules are actually relevant +5. pull context from the DAG +6. use cheap off-path writes liberally +7. record a `change` before core-path work +8. seal core-path work with one atomic `experiment.close` -## Dogfood Reality +## Git-Backed Vs Plain Local Projects -This repository is suitable for off-path dogfood even though it is not -currently a git repo. - -That means: +Off-path work does not require git. You can initialize a local project and use: - `research add` +- `tag add` - `note quick` - `node annotate` - `mcp serve` -all work here today. - Full core-path experiment closure needs a real git-backed project, such as the -target `libgrid` worktree. +target `libgrid` worktree, because checkpoints and champion capture are git +backed. ## Workspace Layout |