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:
72
.wiki/concepts/projects-meta-skills.md
Normal file
72
.wiki/concepts/projects-meta-skills.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: "projects-meta-skills: setup + using pair for projects-meta-mcp"
|
||||
type: concept
|
||||
updated: 2026-04-29
|
||||
---
|
||||
|
||||
# projects-meta-skills: setup + using pair for projects-meta-mcp
|
||||
|
||||
_2026-04-29._
|
||||
|
||||
## What got built
|
||||
|
||||
A split skill pair for the local `projects-meta-mcp` stdio server (cross-project task aggregation + shared Gitea wiki):
|
||||
|
||||
- [`skills/setup-projects-meta/`](../../skills/setup-projects-meta/) — one-time install: clones the server repo, builds it, writes `~/.config/projects-mcp/auth.toml`, clones the shared wiki to `~/projects/projects-wiki/` (canon path; legacy `~/projects/.wiki` is migrated), registers `mcpServers.projects-meta` in `~/.claude.json`. Eight phases, confirmation gates between Phase 1↔2 and before Phase 3.
|
||||
- [`skills/using-projects-meta/`](../../skills/using-projects-meta/) — runtime policy: read tools (`tasks_aggregate`, `knowledge_search`, `meta_status`, …) and mutation tools (`tasks_create`, `knowledge_ingest`, …) 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.
|
||||
|
||||
Both skills v1.0.0, build artifacts in `dist/`, installed to `~/.claude/skills/`.
|
||||
|
||||
## Why split (recap)
|
||||
|
||||
Same reason as [context7-setup.md](context7-setup.md):
|
||||
|
||||
- **Setup** is intrusive (writes secrets, edits `~/.claude.json`, clones repos), one-time per machine, never auto-trigger.
|
||||
- **Using** is daily policy, auto-triggers on cross-project / shared-wiki phrases.
|
||||
|
||||
Mixing them dilutes the policy skill's description (worse triggering) and pulls install procedure into context every time the user asks "what's on the boards".
|
||||
|
||||
## Pattern reference
|
||||
|
||||
`mcp__projects-meta__knowledge_get slug=concepts/setup-using-skill-pair` — full pattern doc in the shared wiki, written by another machine in the fleet ahead of this build. The 8-phase setup-X structure documented there is exactly what `setup-projects-meta/SKILL.md` follows; the using-X structure is exactly what `using-projects-meta/SKILL.md` follows.
|
||||
|
||||
The pattern is now used in claude-skills three times: `context7`, `wiki`, `tasks`, `projects-meta`. Templated enough that the next setup-X / using-X pair can be produced from these four exemplars in one pass.
|
||||
|
||||
## Local-first rule (decision)
|
||||
|
||||
Concept page calls it out, but it's load-bearing enough to put inline in `using-projects-meta/SKILL.md`:
|
||||
|
||||
| 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` |
|
||||
|
||||
Without this rule, the agent burns latency on a stale MCP cache for state that's six lines away on disk.
|
||||
|
||||
## Mutation pattern (decision)
|
||||
|
||||
All five mutation tools (`tasks_create / update / close`, `knowledge_ingest / promote`) follow strict two-step:
|
||||
|
||||
1. Call without `confirm: true` → dry-run preview.
|
||||
2. Show preview to user; wait for "ok" / "go" / "поехали".
|
||||
3. Re-call with `confirm: true` → committed to Gitea.
|
||||
|
||||
Documented in `using-projects-meta/SKILL.md` "Mutate (always two-step)" + "Common mistakes" rows. Forbidden inlining of `confirm: true` is the same hard rule as setup-X's "no auto-mutate of user config".
|
||||
|
||||
## Cross-platform
|
||||
|
||||
Skills are platform-agnostic. Only auxiliary tooling (JSON validate, timestamp gen, `chmod 600` on auth.toml — Linux/macOS only) differs. POSIX paths (`~/.local/...`, `~/.config/...`, `~/projects/...`) work identically under git-bash on Windows.
|
||||
|
||||
## Path canon (caught after first draft)
|
||||
|
||||
Initial draft used `~/projects/.wiki` for the shared wiki clone — the path the wiki anchor still documented. A fresh `git pull` of `projects-wiki` (after the user pointed out we'd skipped pull on session start) revealed [wiki-path-mismatch-resolution](https://git.kzntsv.site/OpeItcLoc03/projects-wiki) — the canon is now `~/projects/projects-wiki/` (clone root), with content at `~/projects/projects-wiki/.wiki/`. Reason: the MCP writer wrote to `<clone>/.wiki/<type>/<slug>.md` while the reader walked `<clone>/<type>/...` — under the old `~/projects/.wiki` clone the writer's output was invisible to reads. Fixed in upstream commit `621a69f` (branch `fix/wiki-path-mismatch`).
|
||||
|
||||
Both `setup-projects-meta` and `using-projects-meta` now write the canon path. `setup-projects-meta` Phase 1 detects a legacy clone; Phase 4 re-clones to canon and leaves the legacy dir for the user to inspect / delete.
|
||||
|
||||
This is a meta-lesson: **always pull shared/multi-machine resources before relying on cached anchors**. Saved as a feedback memory.
|
||||
|
||||
## Round-trip note
|
||||
|
||||
The task `[projects-meta-skills]` was created on a different machine (`OpeItcLoc03@DESKTOP-NSEF0UK`) via `mcp__projects-meta__tasks_create target_project=claude-skills`. Closing it on this machine via `mcp__projects-meta__tasks_close target_project=claude-skills slug=projects-meta-skills` round-trips back to the same Gitea board — both sides see the 🟢 done state. First end-to-end multi-machine task lifecycle in the fleet.
|
||||
@@ -16,6 +16,7 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever
|
||||
- [build-notes.md](concepts/build-notes.md) — why `build.ps1` exists alongside `build.sh`; PS 5.1 backslash-in-zip gotcha; how to extract a `.skill`
|
||||
- [install-portability.md](concepts/install-portability.md) — `install.sh` / `build.sh` rewritten to drop `mapfile` (bash 4+) and `find -printf` (GNU only) so stock macOS (bash 3.2 + BSD find) works
|
||||
- [context7-setup.md](concepts/context7-setup.md) — switched context7 from manual MCP entries to the official plugin; API key in `.mcp.json` as `--api-key`; now also captured as `setup-context7` skill (one-time install/migrate flow with key discovery)
|
||||
- [projects-meta-skills.md](concepts/projects-meta-skills.md) — `setup-projects-meta` + `using-projects-meta` skill pair for the local `projects-meta-mcp` stdio server (cross-project tasks + shared Gitea wiki); local-first rule + two-step mutation pattern
|
||||
- [repo-layout.md](concepts/repo-layout.md) — flat `skills/`, committed `dist/`, bash + PowerShell scripts; install model
|
||||
- [skill-versioning.md](concepts/skill-versioning.md) — why infra skills carry `version: <semver>` in frontmatter and how `project-bootstrap` records them in a per-project manifest
|
||||
- [skill-vs-plugin.md](concepts/skill-vs-plugin.md) — when a bare SKILL.md is enough vs when you actually need a plugin (slash commands, hooks, sub-agents, MCP servers); concrete breakdown of `superpowers`
|
||||
|
||||
@@ -28,5 +28,7 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
|
||||
## [2026-04-28] refactor | this repo's `.tasks/` migrated to canonical layout — flat `## Done`/`## Backlog` replaced by emoji-status board (7 ⚪ Ready blocks); historical Done entries dropped (preserved in git log); `.bak` ignored via .gitignore
|
||||
## [2026-04-28] cleanup | removed stale `~/.claude/skills/{wiki-maintainer,task-status-wiki}/` installs (replaced by `using-wiki`/`using-tasks`); 16 skills installed, no duplicates; context7 plugin (mcp__plugin_context7_context7__*) confirmed live after restart
|
||||
## [2026-04-28] decision | install-portability — `install.sh`/`build.sh` patched to drop `mapfile`+`find -printf`; stock macOS (bash 3.2 + BSD find) now works; verified on git-bash (16 skills discovered, sorted, installed; build.sh produces archive)
|
||||
## [2026-04-29] decision | projects-meta-skills — built `setup-projects-meta` (8-phase install of projects-meta-mcp + auth.toml + MCP registration) and `using-projects-meta` (runtime policy with local-first rule and two-step mutation); skill pair pattern applied for the 4th time (context7 / wiki / tasks / projects-meta); both built + installed; visible to the harness
|
||||
## [2026-04-30] refactor | projects-meta-skills — wiki path canon corrected: `~/projects/.wiki` → `~/projects/projects-wiki/` (clone root), content at `~/projects/projects-wiki/.wiki/`. Old path caused write/read mismatch bug (fixed upstream in commit `621a69f` of `projects-meta-mcp`). Setup-projects-meta Phase 1 now detects legacy clone, Phase 4 re-clones to canon. Lesson: pull shared resources before relying on cached anchors
|
||||
## [2026-04-28] decision | project-bootstrap@1.1.0 — added Step 5.6: detects `superpowers@claude-plugins-official` via `~/.claude/plugins/installed_plugins.json` and prints install command + upstream link if missing; chat-only, never auto-installs (slash commands aren't callable from a skill, and silent plugin install is overreach)
|
||||
## [2026-04-28] doc | README.md + README.ru.md — new "Using skills in projects" / "Использование в проектах" section after install quick-start; describes project-bootstrap workflow (git, .gitignore, README, .wiki/, .tasks/, CLAUDE.md, manifest, superpowers-plugin check) and the init/upgrade modes
|
||||
|
||||
Reference in New Issue
Block a user