sprinty-mcp 0.1.13 → 0.1.15

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "sprinty",
+  "interface": {
+    "displayName": "Sprinty"
+  },
+  "plugins": [
+    {
+      "name": "sprinty",
+      "source": {
+        "source": "local",
+        "path": "./plugins/sprinty"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "sprinty",
+  "owner": {
+    "name": "Elie Bursztein",
+    "url": "https://github.com/ebursztein"
+  },
+  "description": "Sprinty plugins for Claude Code.",
+  "plugins": [
+    {
+      "name": "sprinty",
+      "source": "./clients/claude",
+      "description": "Disciplined sprint workflow with Sprinty skills and the sprinty-mcp server.",
+      "version": "0.1.15",
+      "author": {
+        "name": "Elie Bursztein",
+        "url": "https://github.com/ebursztein"
+      },
+      "homepage": "https://github.com/ebursztein/sprinty",
+      "repository": "https://github.com/ebursztein/sprinty",
+      "license": "Apache-2.0",
+      "category": "Developer Tools",
+      "tags": ["mcp", "sprint", "workflow", "dashboard"]
+    }
+  ]
+}

package/README.md

@@ -1,191 +1,115 @@
 # Sprinty
 
-Disciplined sprint tracking for AI coding agents.
+[![npm version](https://img.shields.io/npm/v/sprinty-mcp.svg)](https://www.npmjs.com/package/sprinty-mcp)
 
-Sprinty is an MCP server that gives agents a structured way to plan, execute, verify, and close
-non-trivial coding work. It keeps the sprint record local, append-only, and tied to real git
-commits, so an agent cannot quietly lose track of work, invent ids, or mark items done without
-evidence.
+Sprinty is an MCP server for running disciplined coding sprints with AI agents. It gives agents
+server-minted sprint, subsprint, and item IDs; explicit dependencies; gate evidence; Git-backed
+change maps; SemVer changelogs; and a local dashboard so humans can watch the work while it happens.
 
-## Why Use Sprinty?
+![Sprinty dashboard](/docs/sprinty-dashboard.png)
 
-Without Sprinty, long agent sessions often drift:
+## Install
 
-- work gets tracked in loose prose that is hard to resume;
-- tasks are marked done without a real commit or passing gate evidence;
-- follow-up context disappears after a restart;
-- humans cannot easily see what the agent is doing right now.
+Sprinty is published to npm as `sprinty-mcp`. The npm package is the MCP server. Claude and Codex
+plugin installs are distributed from this Git repository through each client's marketplace system.
 
-With Sprinty, the agent gets MCP tools for:
+### Claude Code
 
-- sprint, subsprint, and item tracking with server-minted ids;
-- dependency edges, blocked work, and cycle detection;
-- item gates that require passing evidence before completion;
-- git commit validation and per-item change maps;
-- notes and artifacts attached to the sprint record;
-- compact `overview`, `next`, and `search` reads for agent token budgets;
-- a local dashboard URL returned by `sprint_new` and `sprint_resume`;
-- strict `sprint_close` checks that refuse to close while work, coverage, or gates are missing.
+MCP-only install:
 
-## Installation
+```bash
+claude mcp add sprinty -- npx -y sprinty-mcp
+```
 
-Sprinty is published as the npm package `sprinty-mcp`.
+Plugin install, with Sprinty skills plus the MCP server:
 
 ```bash
-npx -y sprinty-mcp
+claude plugin marketplace add ebursztein/sprinty
+claude plugin install sprinty@sprinty
 ```
 
-The server is usually launched by an MCP client. Sprinty works with any MCP client that can run a
-local command.
+The Claude marketplace manifest is `.claude-plugin/marketplace.json`; the plugin bundle is
+`clients/claude/`.
 
 ### Codex
 
-Add Sprinty to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.sprinty]
-command = "npx"
-args = ["-y", "sprinty-mcp"]
-```
-
-### Claude Code
+MCP-only install:
 
 ```bash
-claude mcp add sprinty -- npx -y sprinty-mcp
+codex mcp add sprinty -- npx -y sprinty-mcp
 ```
 
-The repository also includes a Claude plugin manifest in `clients/claude/`.
-
-### Gemini CLI
-
-From a repository checkout:
+Plugin install, with Sprinty skills plus the MCP server:
 
 ```bash
-gemini extensions install ./clients/gemini
+codex plugin marketplace add ebursztein/sprinty
+codex plugin add sprinty@sprinty
 ```
 
-The Gemini extension uses `clients/gemini/gemini-extension.json` and `clients/gemini/GEMINI.md`.
+The Codex marketplace manifest is `.agents/plugins/marketplace.json`; the plugin bundle is
+`plugins/sprinty/`. Codex does not currently use an OpenAI npm plugin package for this flow.
 
-### Codex Plugin From A Checkout
+### Gemini CLI
 
-For local plugin development from this repository:
+Use the MCP server directly from npm:
 
 ```bash
-codex plugin marketplace add .
-codex plugin add sprinty@sprinty-local
+npx -y sprinty-mcp
 ```
 
-The installable plugin bundle lives in `plugins/sprinty/`.
+The repository also includes a Gemini extension in `clients/gemini/` for clients that install local
+Gemini extensions.
 
-## Quick Start
+### Any MCP Client
 
-Sprinty never guesses the repository from the MCP server process cwd. Start a sprint with explicit
-paths:
+Configure a stdio MCP server with:
 
 ```json
 {
-  "goal": "Ship the dashboard lifecycle change",
-  "git_dir": "/absolute/path/to/repo",
-  "data_dir": "/absolute/path/to/repo/.sprinty",
-  "context_notes": ["optional notes for the agent"]
+  "command": "npx",
+  "args": ["-y", "sprinty-mcp"]
 }
 ```
 
-- `git_dir` is where Sprinty checks commits, runs gates, reads coverage, and builds change maps.
-- `data_dir` is where Sprinty stores the `current` pointer and JSONL ledgers.
-- Use a worktree-scoped, gitignored `data_dir`, such as `<git_dir>/.sprinty`.
-
-After a restart, inspect and resume the same sprint:
-
-```text
-sprint_list({ data_dir })
-sprint_resume({ git_dir, data_dir })
-```
-
-You can also pre-bind a read-only MCP process with both environment variables:
-
-```bash
-SPRINTY_GIT_DIR=/absolute/path/to/repo
-SPRINTY_DATA_DIR=/absolute/path/to/repo/.sprinty
-```
-
-Both `SPRINTY_GIT_DIR` and `SPRINTY_DATA_DIR` are required together.
+## Use
 
-## Basic Workflow
+Sprinty never guesses the repository from the MCP server process cwd. Start or resume with explicit
+paths:
 
 ```text
 sprint_new({ goal, git_dir, data_dir, context_notes? })
-  -> returns dashboard.url
-overview({})
-subsprint_new({ description, goals, gates, dependencies? })
-item_add({ subsprint, title, description, code_locations, gates, dependencies?, high_priority? })
-next({})
-item_done({ id, commit_id, gate_results, changelog: { verb: "added" | "fixed" | "changed" | "removed" | "deprecated" | "security", line } })
-changelog({ path? }) -> { path } // generates SemVer Markdown
-sprint_close({ coverage: { path, format: "lcov", command? } }) // after changelog generation
-```
-
-Use `item_split` when an item is too large and `item_deprecate` when an item is intentionally
-dropped. Use `sprint_detach` before switching one MCP process to a different sprint.
-
-## Dashboard
-
-`sprint_new` and `sprint_resume` automatically start a read-only local dashboard and return:
-
-```json
-{
-  "dashboard": {
-    "running": true,
-    "url": "http://127.0.0.1:60767",
-    "port": 60767
-  }
-}
+sprint_resume({ git_dir, data_dir })
 ```
 
-Open the URL in a browser to watch progress while the agent works. The dashboard shows sprint
-status, items, blocked work, gates, artifacts, changelog entries, change maps, and the ledger.
-
-Dashboard tools:
-
-- `dashboard_info` returns the current dashboard URL and port without restarting it.
-- `dashboard_restart` restarts the dashboard server and returns the new URL and port.
-- `sprint_close`, `sprint_archive`, and `sprint_detach` stop the dashboard.
-
-## Available Tools
+Use a worktree-local, gitignored `data_dir`, usually `<git_dir>/.sprinty`. When `data_dir` is
+omitted and `git_dir` is provided, Sprinty uses `<git_dir>/.sprinty`. `sprint_new` and
+`sprint_resume` return the dashboard URL. Call `info({ git_dir })` first for startup orientation and
+compact sprint rows. Use `info({ workspace_dirs: [...] })` when you need to inspect multiple Sprinty
+data dirs together, then `sprint_resume({ git_dir, data_dir })`.
 
-### Sprint Tools
+## Tools
 
-| Tool | What it does |
+| Tool | Purpose |
 | --- | --- |
+| `info` | Startup orientation before binding, including sprint rows, resume/create help, and dashboard state. |
 | `sprint_new` | Start a sprint with explicit `git_dir` and `data_dir`; returns orientation and dashboard info. |
-| `sprint_resume` | Reattach to an existing sprint after an MCP restart; returns dashboard info. |
-| `sprint_list` | List ledgers in a `data_dir` without creating a sprint. |
+| `sprint_resume` | Reattach this MCP session to an existing sprint. |
 | `sprint_detach` | Clear this MCP process binding and stop the dashboard. |
-| `sprint_close` | After `changelog({ path? })` has generated SemVer Markdown, re-run gates, require coverage evidence, and close only when all work is resolved. |
+| `sprint_close` | Close only after all work is resolved, changelog exists, gates pass, and coverage is supplied. |
 | `sprint_archive` | Archive an active sprint with a recovery reason. |
 | `overview` | Compact sprint summary for orientation. |
-| `next` | Compact active work window with available and blocked items. |
+| `next` | Compact active work window with current, next, blocked, relations, notes, and artifacts. |
 | `search` | Regex search over the immutable sprint ledger. |
-| `changelog` | Generate the SemVer Markdown changelog at `path` or the sprint data dir and return only the path. |
-
-### Work Tools
-
-| Tool | What it does |
-| --- | --- |
+| `changelog` | Generate SemVer Markdown and return the path. |
 | `subsprint_new` | Create a feature-sized unit of work. |
 | `subsprint_list` | List subsprints with compact item counts. |
 | `subsprint_get` | Read one subsprint and its item rows. |
 | `item_add` | Create one atomic, gated item. |
 | `item_get` | Read full item detail. |
-| `item_update` | Update item metadata, notes, priority, or dependency edges. |
-| `item_done` | Complete an item with a real commit, passing gate evidence, and a semver changelog verb plus line. |
-| `item_split` | Resolve an oversized item by creating a new subsprint. |
+| `item_update` | Update item metadata, priority, notes, or dependency edges. |
+| `item_done` | Complete an item with a real commit, gate evidence, and changelog entry. |
+| `item_split` | Resolve an oversized item by creating a seeded subsprint. |
 | `item_deprecate` | Drop an item with an explicit reason. |
-
-### Notes And Artifacts
-
-| Tool | What it does |
-| --- | --- |
 | `note_add` | Attach a note to an item. |
 | `note_list` | List notes for an item. |
 | `note_get` | Read one note. |
@@ -194,41 +118,21 @@ Dashboard tools:
 | `artifact_list` | List active artifacts. |
 | `artifact_get` | Read one artifact record. |
 | `artifact_update` | Update artifact metadata. |
-
-### Dashboard Tools
-
-| Tool | What it does |
-| --- | --- |
-| `dashboard_info` | Report whether the dashboard is running and, if so, its URL and port. |
+| `dashboard_info` | Report the current dashboard URL and port. |
 | `dashboard_restart` | Restart the dashboard and return the new URL and port. |
 
-## How Sprinty Stores Data
-
-Sprinty writes one append-only JSONL ledger per sprint under `data_dir`. The ledger is local state;
-keep it out of git unless you intentionally want to preserve it elsewhere. Sprinty projects that
-ledger into compact read models for agents and into the dashboard for humans.
-
-Completed items record the commit id, gate results, changelog entry, and Git-backed file change map.
-Call `changelog({ path? })` before close to generate the SemVer Markdown file from those entries.
-`sprint_close` then re-checks commits, re-runs executable gates, requires coverage evidence, and
-refuses to close while any item is still open.
-
-## More Documentation
+## Release
 
-- [How to run a sprint](skills/how-to-run-a-sprint/SKILL.md)
-- [Full Sprinty tool contract](skills/using-sprinty/SKILL.md)
-- [Codex client notes](clients/codex/README.md)
-- [Gemini client notes](clients/gemini/GEMINI.md)
+Publishing is gated by tests. The GitHub Release workflow runs `npm ci`, `npm test`, and only then
+`npm publish --access public`.
 
-## Development
+Local checks:
 
 ```bash
-npm install
 npm test
 npm run typecheck
-npm run build
 ```
 
 ## License
 
-Apache-2.0 © Elie Bursztein
+Apache-2.0

package/clients/claude/.claude-plugin/plugin.json

@@ -1,13 +1,10 @@
 {
   "name": "sprinty",
-  "version": "0.1.13",
-  "description": "Disciplined sprint workflow: dashboard-at-start, feature subsprints, artifacts, bug-id follow-ups, spike investigations, an immutable git-anchored ledger, and programmatic close gates.",
+  "version": "0.1.15",
+  "description": "Disciplined sprint workflow with dashboard-at-start, feature subsprints, artifacts, an immutable git-anchored ledger, and programmatic close gates.",
   "author": { "name": "Elie Bursztein" },
   "homepage": "https://github.com/ebursztein/sprinty",
   "repository": "https://github.com/ebursztein/sprinty",
   "license": "Apache-2.0",
-  "keywords": ["sprint", "discipline", "ledger", "mcp"],
-  "mcpServers": {
-    "sprinty": { "command": "npx", "args": ["-y", "sprinty-mcp"] }
-  }
+  "keywords": ["sprint", "discipline", "ledger", "mcp", "dashboard"]
 }

package/clients/claude/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sprinty": {
+      "command": "npx",
+      "args": ["-y", "sprinty-mcp"]
+    }
+  }
+}

package/clients/claude/README.md

@@ -0,0 +1,28 @@
+# Sprinty for Claude Code
+
+Install the MCP server directly:
+
+```bash
+claude mcp add sprinty -- npx -y sprinty-mcp
+```
+
+Install the full plugin from the Sprinty marketplace:
+
+```bash
+claude plugin marketplace add ebursztein/sprinty
+claude plugin install sprinty@sprinty
+```
+
+This plugin contains:
+
+- `.claude-plugin/plugin.json`
+- `.mcp.json`, which launches `npx -y sprinty-mcp`
+- `skills/how-to-run-a-sprint`
+- `skills/using-sprinty`
+
+Validate before release:
+
+```bash
+claude plugin validate clients/claude --strict
+claude plugin validate . --strict
+```

package/clients/claude/skills/how-to-run-a-sprint/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: how-to-run-a-sprint
+description: Use at the start of non-trivial implementation work that should be tracked in Sprinty with explicit binding, item ownership, gates, and close checks.
+---
+
+# How To Run A Sprint
+
+A Sprinty sprint is item-driven. Do not keep parallel prose trackers when tools are available.
+
+## Loop
+
+1. Orient before binding. Call `info({ git_dir })` for the default `<git_dir>/.sprinty` ledger directory, `info({ data_dir })` for an explicit ledger directory, or `info({ workspace_dirs: [...] })` for a compact workspace view. Resume with `sprint_resume({ git_dir, data_dir? })`. Start fresh only with `sprint_new({ goal, git_dir, data_dir?, context_notes })`.
+2. Share the dashboard URL returned by `sprint_new({})` or `sprint_resume({})`. Use `dashboard_info({})` to re-read it, `dashboard_restart({})` to refresh it, `overview({})` for compact orientation, and `next({})` for the active work window.
+3. Create feature-sized subsprints with `subsprint_new({ description, goals, gates, dependencies })`.
+4. Create atomic work with `item_add({ subsprint, title, description, code_locations, gates, dependencies, high_priority })`. If the work is too large, make more items; do not hide scope in notes.
+5. Work against one owning item. Use `item_update({ id, note })` for progress, `item_update({ id, title, description, high_priority })` for metadata, `item_update({ id, dependencies })` to replace graph edges, `note_add({ id, text })` only for item-scoped observations, and `artifact_add({ title, path, description, related_items })` for durable files.
+6. Resolve each item exactly once: `item_done({ id, commit_id, gate_results, changelog })`, `item_split({ id, description, goals, gates, dependencies })`, or `item_deprecate({ id, reason })`.
+7. Use `search({ pattern, context_size:512 })`, `*_list`, and focused `*_get` tools when you need detail.
+8. Generate the sprint changelog with `changelog({ path? })`; Sprinty writes SemVer Markdown and returns only the path.
+9. Close only after the changelog exists: `sprint_close({ coverage:{ path, format:"lcov", command } })`.
+
+## Rules
+
+- Never invent ids; read minted ids from tool results.
+- Use explicit `git_dir`; `data_dir` defaults to `<git_dir>/.sprinty` when omitted. Never rely on MCP cwd.
+- Keep responses compact. Prefer `next`, `overview`, `search`, and list/get pairs over full views. `next({})` returns all available high-priority items, then one normal available item per subsprint by default.
+- Notes must be bound to an item id. Work needs an item.
+- Gates prove items. `item_done` requires a real commit and passing evidence for every declared gate.
+- `item_done` records each item's SemVer changelog verb and line; `changelog({ path? })` generates the Markdown file from those entries.
+- `sprint_close` is the final gate and comes after changelog generation: it rejects open items, missing commits/changelog/coverage, and failing executable gates.

package/clients/claude/skills/using-sprinty/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: using-sprinty
+description: Use when an agent needs the exact Sprinty MCP tool contract, public tool names, compact response rules, restart recovery, or note/artifact/item semantics.
+---
+
+# Using Sprinty
+
+Prefer compact commands first. Lists are compact and say which `_get()` tool returns full detail. Mutating tools return acknowledgements plus `help`; do not expect or request full sprint dumps from mutations.
+
+## Core Tools
+
+| Tool | Input | Use |
+|---|---|---|
+| `info` | `{ git_dir?, data_dir?, workspace_dirs?[] }` | First-call orientation before binding. Returns startup workflow, resume/create help, dashboard state, and sprint rows with title, created time, and open/closed/blocked item counts. |
+| `sprint_resume` | `{ git_dir, data_dir? }` | Rebind this MCP process to an existing sprint and return the dashboard URL. `data_dir` defaults to `<git_dir>/.sprinty`. Never call `sprint_new` as a resume trick. |
+| `sprint_detach` | `{}` | Clear this process binding before resuming a different sprint. |
+| `sprint_new` | `{ goal, git_dir, data_dir?, context_notes?[] }` | Start one sprint with explicit `git_dir`; `data_dir` defaults to `<git_dir>/.sprinty`. Returns the dashboard URL. |
+| `overview` | `{}` | Compact sprint title/details/artifacts/subsprints/items. Use this to orient. |
+| `next` | `{ past?=1, future_per_subsprint?=1, include_high_priority?=true }` | Compact active work window. Returns all available high-priority items first, then normal available items per subsprint. No full graph. |
+| `search` | `{ pattern, context_size?=512 }` | Regex search. Returns `{ id, type, text, tool_call }`; use `tool_call` for full detail. |
+| `dashboard_info` | `{}` | Current localhost dashboard URL and port, or `running:false` when stopped. |
+| `dashboard_restart` | `{}` | Restart the dashboard server and return the new URL and port. |
+
+## Work Tools
+
+| Tool | Input | Use |
+|---|---|---|
+| `subsprint_new` | `{ description, goals[], gates[], dependencies?[] }` | Create a feature-sized unit. |
+| `subsprint_list` | `{}` | Compact subsprint rows. Use `subsprint_get({ id })` for full detail. |
+| `subsprint_get` | `{ id }` | Full subsprint detail and compact item rows. |
+| `item_add` | `{ subsprint, title, description, code_locations[], gates[], dependencies?[], high_priority? }` | Create an atomic item. Title 3-80 chars; description 20-500 chars. Oversized inputs mean create more than one item. |
+| `item_get` | `{ id }` | Full item detail. |
+| `item_update` | `{ id, note?, title?, description?, high_priority?, dependencies?[] }` | Mutate item metadata and/or replace dependency ids. Use `dependencies:[]` to remove all dependencies. |
+| `item_done` | `{ id, commit_id, gate_results[], changelog }` | Complete an item. Commit must resolve; every declared gate needs passing evidence, and `changelog` supplies the SemVer verb plus line. |
+| `item_split` | `{ id, description, goals[], gates[], dependencies?[] }` | Resolve an oversized item by creating a new subsprint. |
+| `item_deprecate` | `{ id, reason }` | Resolve an item as intentionally dropped. |
+
+## Notes And Artifacts
+
+| Tool | Input | Use |
+|---|---|---|
+| `note_add` | `{ id, text }` | Attach a note to an item id only. Notes do not replace items. |
+| `note_list` | `{ id }` | Compact notes for an item. Use `note_get({ id:"N001" })` for full text. |
+| `note_get` | `{ id }` | Full note detail. Note ids are `N001`, `N002`, ... |
+| `note_update` | `{ id, text }` | Replace note text by note id. |
+| `artifact_add` | `{ title, path, description?, related_items?[] }` | Attach a durable sprint file/output. |
+| `artifact_list` | `{}` | Compact artifact rows. Use `artifact_get({ id })` for full detail. |
+| `artifact_get` | `{ id }` | Full artifact detail including description. |
+| `artifact_update` | `{ id, title?, path?, description?, related_items?[] }` | Amend artifact metadata. |
+
+## Close
+
+Sprinty generates the changelog for you. First call `changelog({ path? })` to write the SemVer Markdown file with sections, item entries, commits, coverage, and change-map tables; the response returns only `{ path }`. Then call `sprint_close({ coverage:{ path, format:"lcov", command? } })`; close re-runs executable gates and refuses open items, missing commits, missing changelog entries, missing coverage, or failing gates. Use `sprint_archive({ reason })` only for recovery.
+
+## Rules
+
+- Always minimize tokens: use `next`, `overview`, `*_list`, `search`, then focused `*_get`.
+- Public id inputs are always named `id`.
+- Notes attach only to item ids. If the note describes work, create one or more `item_add` items.
+- `high_priority` is a boolean, not a ranked priority model. `next({})` promotes all available high-priority items before the per-subsprint normal window unless `include_high_priority:false`.
+- Dependencies are ids. `item_update({ id, dependencies:[...] })` replaces the item's dependency set and rejects unknown ids, duplicates, and cycles.
+- Tool responses omit timestamps and empty fields; the append-only ledger keeps audit data.

package/clients/codex/README.md

@@ -1,28 +1,35 @@
 # Sprinty for Codex CLI
 
-The supported command-line Codex plugin lives at `plugins/sprinty/`, with the repository-local
+The supported command-line Codex plugin lives at `plugins/sprinty/`, with the repository
 marketplace at `.agents/plugins/marketplace.json`. This directory is documentation only.
 
-Install from a repository checkout:
+Install from GitHub:
+
+```bash
+codex plugin marketplace add ebursztein/sprinty
+codex plugin add sprinty@sprinty
+```
+
+Install from a local checkout:
 
 ```bash
 codex plugin marketplace add .
-codex plugin add sprinty@sprinty-local
+codex plugin add sprinty@sprinty
 ```
 
 Then start a new Codex CLI thread so the plugin skills and MCP server are loaded.
 
 This marketplace layout is for Git/repo installs, not the npm tarball. The npm package provides the
-MCP server used by the plugin (`npx -y sprinty-mcp`).
+MCP server used by the plugin (`npx -y sprinty-mcp`). Codex does not currently use a standalone
+OpenAI npm plugin package for this flow.
 
 The installed plugin provides:
 
 - Sprinty MCP tools through `npx -y sprinty-mcp`
 - shared Sprinty skills from the canonical repository `skills/` directory
 
-The npm package includes the top-level `skills/` directory for MCP resource serving. Client
-directories may contain symlinks to that canonical directory in a Git checkout; npm tarballs do not
-need per-client skill copies.
+The plugin bundle contains its own `skills/` directory so Git marketplace installs remain
+self-contained.
 
 MCP-only setup without plugin skills:
 
@@ -32,13 +39,13 @@ codex mcp add sprinty -- npx -y sprinty-mcp
 
 Sprinty does not infer state from Codex's MCP launch cwd. Start every sprint with explicit
 `git_dir` and `data_dir`; `git_dir` is where commits, gates, coverage, and change maps run, while
-`data_dir` stores the `current` pointer and JSONL ledgers. After a Codex/MCP restart, call
-`sprint_list(data_dir)` and then `sprint_resume(git_dir, data_dir)` to reattach without creating a
-new sprint. Use `sprint_detach()` before switching one MCP process to another sprint. For read-only
-tools before `sprint_new`, you may pre-bind with both `SPRINTY_GIT_DIR` and `SPRINTY_DATA_DIR` or
-both `--git-dir` and `--data-dir`.
-
-Do not copy skill files into client directories; keep them in the top-level `skills/` directory.
+`data_dir` stores the `current` pointer and JSONL ledgers. When `data_dir` is omitted and `git_dir`
+is provided, Sprinty uses `<git_dir>/.sprinty`. Call `info({ git_dir })` first for startup
+orientation and compact sprint rows, or `info({ workspace_dirs: [...] })` to inspect multiple data
+dirs. Then call `sprint_resume(git_dir, data_dir?)` to reattach without creating a new sprint. Use
+`sprint_detach()` before switching one MCP process to another sprint. For read-only tools before
+`sprint_new`, you may pre-bind with both `SPRINTY_GIT_DIR` and `SPRINTY_DATA_DIR` or both
+`--git-dir` and `--data-dir`.
 
 For human visibility during a sprint, open the dashboard URL returned by `sprint_new()` or
 `sprint_resume()` in a browser. Use `dashboard_info()` to re-read it and `dashboard_restart()` to

package/clients/gemini/GEMINI.md

@@ -5,36 +5,33 @@ When a task is non-trivial, run a disciplined sprint with the sprinty MCP.
 See `skills/how-to-run-a-sprint` and `skills/using-sprinty`. The loop:
 
 ```
-sprint_list(data_dir?) -> sprint_resume(git_dir, data_dir) | sprint_detach()
-sprint_new(goal, git_dir, data_dir, context_notes?)
+info(git_dir? | data_dir? | workspace_dirs?) -> sprint_resume(git_dir, data_dir?) | sprint_detach()
+sprint_new(goal, git_dir, data_dir?, context_notes?)
   -> dashboard URL in response | dashboard_info() | dashboard_restart()
   -> subsprint_new(description, goals[], gates[], dependencies?)
-  -> spike(description, goals[], gates[], dependencies?)
   -> next(past?, future_per_subsprint?, include_high_priority?)
-  -> add(subsprint, title, description, code_locations[], gates[], dependencies?, high_priority?)
+  -> item_add(subsprint, title, description, code_locations[], gates[], dependencies?, high_priority?)
   -> item_update(id, note?, title?, description?, high_priority?, dependencies?)
-  -> artifact_add/list/amend/deprecate(...)
-  -> follow_up(target, description, bug_id|bug_ids)
-  -> done(commit_id, gate_results[], changelog) | split(...) | deprecate(reason)
-  -> spike_conclude(subsprint, conclusion) | spike_deprecate(subsprint, reason)
+  -> artifact_add/list/get/update(...)
+  -> item_done(id, commit_id, gate_results[], changelog) | item_split(...) | item_deprecate(reason)
   -> changelog()
   -> sprint_close(coverage: { path, format: "lcov", command? })
 ```
 
 Rules: IDs are minted by the server (`S01`, `S01-001`) — never invent them. Start with explicit
-absolute `git_dir` and `data_dir`; `git_dir` is where commits/gates/coverage run, and `data_dir`
-stores Sprinty's `current` pointer and JSONL ledgers. After a Codex/MCP restart, use
-`sprint_list(data_dir)` and `sprint_resume(git_dir, data_dir)` to reattach without creating a new
-sprint; use `sprint_detach()` before switching one MCP process to another sprint. Every item needs a
-description, at least one code location, and at least one gate. `done` requires a real commit,
+absolute `git_dir`; `git_dir` is where commits/gates/coverage run. `data_dir` stores Sprinty's
+`current` pointer and JSONL ledgers, and defaults to `<git_dir>/.sprinty` when omitted. After a
+Codex/MCP restart, call `info({ git_dir })` or `info({ workspace_dirs:[...] })`, then use
+`sprint_resume(git_dir, data_dir?)` to reattach without creating a new sprint; use `sprint_detach()`
+before switching one MCP process to another sprint. Every item needs a
+description, at least one code location, and at least one gate. `item_done` requires a real commit,
 passing evidence for every declared item gate, and a semver-style changelog line with a verb such as
-`added`, `fixed`, or `removed`. `split` and `deprecate` are terminal non-code exits. Each
-subsprint should be one feature; use `spike()` for feature investigations, then close the spike with
-`spike_conclude()` or `spike_deprecate()`. Use `artifact_add/list/amend/deprecate` for durable
-outputs and `follow_up()` with bug ids for bugs found while moving fast. `next()` returns the active
+`added`, `fixed`, or `removed`. `item_split` and `item_deprecate` are terminal non-code exits. Each
+subsprint should be one feature. Use `artifact_add/list/get/update` for durable
+outputs. `next()` returns the active
 work window with relevant artifacts and recent activity: all available `high_priority` items first
 by default, then normal available items per subsprint. `item_update({ id, dependencies })` replaces
-dependencies, so pass `dependencies: []` to remove a bad edge. `done` records a Git-backed change map and each item's SemVer changelog entry. `changelog({ path? })` generates the SemVer Markdown file with
+dependencies, so pass `dependencies: []` to remove a bad edge. `item_done` records a Git-backed change map and each item's SemVer changelog entry. `changelog({ path? })` generates the SemVer Markdown file with
 sections, item entries, commits, coverage, and change-map tables; run it before `sprint_close`. `sprint_close` rechecks commits, re-runs executable gates, requires
 an LCOV coverage report path, and refuses to close on any blocker. Use `search(pattern,
 context_lines)` to query the immutable ledger. Show the dashboard URL returned by `sprint_new()` or

package/clients/gemini/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "sprinty",
-  "version": "0.1.13",
-  "description": "Disciplined sprint workflow with dashboard-at-start, feature subsprints, artifacts, bug-id follow-ups, spike investigations, an immutable git-anchored ledger, and close gates.",
+  "version": "0.1.15",
+  "description": "Disciplined sprint workflow with dashboard-at-start, feature subsprints, artifacts, an immutable git-anchored ledger, and close gates.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
     "sprinty": { "command": "npx", "args": ["-y", "sprinty-mcp"] }