feat(skills): add setup-projects-meta + using-projects-meta pair
Wraps the local projects-meta-mcp stdio server with the validated split-pair pattern (setup-X / using-X), 4th application after context7 / wiki / tasks. setup-projects-meta — 8-phase install: clones server repo to ~/.local/projects-meta-mcp, builds, writes ~/.config/projects-mcp/auth.toml, clones shared wiki to ~/projects/projects-wiki/ (canon path; legacy ~/projects/.wiki is detected and migrated — old path caused the wiki-path-mismatch bug, fixed upstream in 621a69f), registers mcpServers.projects-meta in ~/.claude.json. Confirmation gates between discovery and writes. using-projects-meta — runtime policy: read tools (tasks_aggregate, knowledge_search, meta_status, ...) and mutation tools with mandatory two-step preview→confirm. Carries the local-first rule inline: for the current project read .tasks/ / .wiki/ from disk; MCP cache is for *other* projects only. Wiki concept page concepts/projects-meta-skills.md documents the design, the path-canon fix, and the round-trip task lifecycle across machines. Closes [projects-meta-skills] in claude-skills (created from DESKTOP-NSEF0UK via projects-meta-mcp). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
144
skills/using-projects-meta/README.md
Normal file
144
skills/using-projects-meta/README.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# using-projects-meta
|
||||
|
||||
Runtime policy for the local `projects-meta-mcp` stdio server. Two
|
||||
responsibilities, one server:
|
||||
|
||||
1. **Cross-project task aggregation** — reads / writes `.tasks/STATUS.md` in
|
||||
any of the user's Gitea repos.
|
||||
2. **Shared knowledge wiki** — query / ingest a single Gitea-backed wiki at
|
||||
`~/projects/projects-wiki/.wiki/` (clone root: `~/projects/projects-wiki/`,
|
||||
Gitea repo: `projects-wiki`).
|
||||
|
||||
`using-projects-meta` governs *usage* of an installed server. Initial setup
|
||||
(clone, build, `auth.toml`, MCP registration) is owned by
|
||||
[`setup-projects-meta`](../setup-projects-meta/).
|
||||
|
||||
Full server reference:
|
||||
`mcp__projects-meta__knowledge_get slug=packages/projects-meta-mcp`.
|
||||
|
||||
## When it triggers
|
||||
|
||||
- User asks for cross-project state ("what's on the boards", "across all
|
||||
projects", "что у меня на досках", "по всем проектам").
|
||||
- User wants to query / ingest the shared wiki ("check shared wiki", "search
|
||||
projects-wiki", "ingest into shared wiki", "общая вики", "заингесть в общую").
|
||||
- User wants to create / update / close a task in *another* project from the
|
||||
current cwd ("заведи в проекте X задачу", "close task Y in project Z").
|
||||
- User asks for sync diagnostics ("when did the cache last refresh", "are there
|
||||
sync errors").
|
||||
- If `mcp__projects-meta__*` tools are missing, this skill delegates to
|
||||
[`setup-projects-meta`](../setup-projects-meta/) before doing anything else.
|
||||
|
||||
## Local-first rule (critical)
|
||||
|
||||
For the **current** project — read disk directly (`.tasks/STATUS.md`,
|
||||
`.wiki/index.md`). The MCP cache:
|
||||
|
||||
- May be stale (sync runs only when triggered).
|
||||
- Hides `🟢 done` by default.
|
||||
- May not contain unpushed projects.
|
||||
|
||||
Use MCP only for **other** projects, **other** machines, or the **shared**
|
||||
wiki content. See the table below.
|
||||
|
||||
| Question | Where to read |
|
||||
|---|---|
|
||||
| "What's the status of *this* project?" | local `.tasks/STATUS.md` |
|
||||
| "What's on all my boards?" | `mcp__projects-meta__tasks_aggregate` |
|
||||
| "Has *this* project's wiki got X?" | local `.wiki/index.md` |
|
||||
| "Has the **shared** wiki got X?" | `mcp__projects-meta__knowledge_search` |
|
||||
| "Sync state across machines?" | `mcp__projects-meta__meta_status` |
|
||||
|
||||
## Two operation classes
|
||||
|
||||
### Read (no confirmation)
|
||||
|
||||
`tasks_aggregate`, `tasks_search`, `tasks_get`, `knowledge_search`,
|
||||
`knowledge_get`, `knowledge_suggest_promote`, `meta_status` — all
|
||||
side-effect-free. Call directly, cite the result.
|
||||
|
||||
### Mutate (always two-step)
|
||||
|
||||
`tasks_create`, `tasks_update`, `tasks_close`, `knowledge_ingest`,
|
||||
`knowledge_promote` — write to Gitea. Procedure:
|
||||
|
||||
1. Call **without** `confirm: true` → returns dry-run preview (proposed file
|
||||
diff + commit message).
|
||||
2. Show the preview to the user. Wait for explicit "ok" / "go" / "поехали".
|
||||
3. Re-call with `confirm: true` → committed.
|
||||
|
||||
**Never inline `confirm: true` on the first call.** A trigger phrase is
|
||||
permission to plan, not to commit.
|
||||
|
||||
## Tool quick reference
|
||||
|
||||
### Read
|
||||
|
||||
| Tool | Required args | Purpose |
|
||||
|---|---|---|
|
||||
| `mcp__projects-meta__tasks_aggregate` | — | All active tasks across cached projects |
|
||||
| `mcp__projects-meta__tasks_search` | `query` | Substring search across slug + next_action |
|
||||
| `mcp__projects-meta__tasks_get` | `project` | Raw STATUS.md of one project (cache snapshot) |
|
||||
| `mcp__projects-meta__knowledge_search` | `query`; opt `domain`, `limit` | Shared-wiki search; default domain auto-detected from cwd |
|
||||
| `mcp__projects-meta__knowledge_get` | `slug` | Full text of one wiki page |
|
||||
| `mcp__projects-meta__knowledge_suggest_promote` | — | Local `.wiki/concepts/` candidates for shared promotion |
|
||||
| `mcp__projects-meta__meta_status` | — | Sync diagnostics (cache age, project / page / error counts) |
|
||||
|
||||
### Mutate (need `write:repository` Gitea scope)
|
||||
|
||||
| Tool | Required args | Effect |
|
||||
|---|---|---|
|
||||
| `mcp__projects-meta__tasks_create` | `target_project`, `slug`, `description`, `next_action` | Append block to target's `.tasks/STATUS.md` via Gitea commit |
|
||||
| `mcp__projects-meta__tasks_update` | `target_project`, `slug` + ≥1 mutable field | Sha-based optimistic lock; 422 on conflict |
|
||||
| `mcp__projects-meta__tasks_close` | `target_project`, `slug` (+ opt `note`) | Marks task 🟢 done with identity-footer |
|
||||
| `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` | Three commits: `<type>/<slug>.md` + `index.md` + `log.md` |
|
||||
| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` | Move `raw/<slug>.md` → `sources/<slug>.md` |
|
||||
|
||||
`type` ∈ `entities` / `concepts` / `packages` / `sources` / `raw`.
|
||||
`target_project` = Gitea repo name, or `_meta` (meta-tasks / meta-wiki repos
|
||||
from `auth.toml`).
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **Reading current project's tasks via `tasks_get`.** Read `.tasks/STATUS.md`
|
||||
on disk; the MCP cache is for *other* projects.
|
||||
- **Inlining `confirm: true` on first call.** Always preview first; show user;
|
||||
only then `confirm: true`.
|
||||
- **Confusing the local `.wiki/` with the shared `projects-wiki`.** They are
|
||||
two different stores. `using-wiki` operates on the local one;
|
||||
`using-projects-meta` queries / ingests the shared one.
|
||||
- **Acting on stale `tasks_aggregate`.** If `meta_status.age_seconds` > 3600,
|
||||
either run `node dist/sync.js` (in `~/.local/projects-meta-mcp`) or warn the
|
||||
user about staleness.
|
||||
- **Vague `knowledge_search` queries.** "auth" returns noise. Multi-word,
|
||||
specific queries return targeted snippets.
|
||||
- **Wrong `type` on `knowledge_ingest`.** Mis-typed pages land in the wrong
|
||||
section and break `index.md`. Pick from the five canonical types.
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- The current project's own tasks — read `.tasks/STATUS.md`.
|
||||
- The current project's own wiki — read `.wiki/`.
|
||||
- Library / framework documentation — that's [`using-context7`](../using-context7/).
|
||||
- Repo-internal code search — that's `Glob` / `Grep`.
|
||||
- One-off git history questions — `git log`.
|
||||
|
||||
## Install
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
bash scripts/install.sh using-projects-meta
|
||||
```
|
||||
|
||||
Works on Windows under git-bash, Linux, macOS.
|
||||
|
||||
## See also
|
||||
|
||||
- [`setup-projects-meta`](../setup-projects-meta/) — companion, owns server
|
||||
install + MCP registration.
|
||||
- [`using-context7`](../using-context7/) — sister skill for library docs (same
|
||||
using-X structure).
|
||||
- [`using-tasks`](../using-tasks/), [`using-wiki`](../using-wiki/) —
|
||||
per-project policies for in-repo `.tasks/` and `.wiki/`. Orthogonal to this
|
||||
skill; together they cover both per-project and cross-project state.
|
||||
Reference in New Issue
Block a user