# projects-meta-skills

## Goal
Ship a `setup-projects-meta` + `using-projects-meta` skill pair that wraps the local `projects-meta-mcp` server (cross-project task aggregation + shared Gitea-backed wiki). Mirrors the validated `setup-context7` / `using-context7` split: setup is one-time intrusive (clones repo, builds, writes `~/.config/projects-mcp/auth.toml`, clones shared wiki to `~/projects/projects-wiki/`, registers `mcpServers.projects-meta` in `~/.claude.json`), using is daily policy with auto-trigger on cross-project / shared-wiki questions and delegates to setup if `mcp__projects-meta__*` tools are missing.

## Key files
- `skills/setup-projects-meta/SKILL.md` — 8-phase install (model: `skills/setup-context7/SKILL.md`)
- `skills/setup-projects-meta/README.md` — human-facing doc (model: `skills/setup-wiki/README.md`)
- `skills/using-projects-meta/SKILL.md` — runtime policy (model: `skills/using-context7/SKILL.md`)
- `skills/using-projects-meta/README.md` — human-facing doc (model: `skills/using-wiki/README.md`)
- `scripts/build.sh` — packages skills into `dist/<name>.skill`
- `scripts/install.sh` — copies `skills/<name>/` → `~/.claude/skills/<name>/`

## Wiki anchors (already in shared wiki)
- `packages/projects-meta-mcp` — full reference: paths, auth.toml, tools list, mutation pattern, sync runner
- `concepts/setup-using-skill-pair` — pattern: 8-phase setup-X structure, using-X structure, hard rules

## Decisions log
- 2026-04-29: Use `setup-context7` as the structural template for `setup-projects-meta` — same 8-phase shape, same confirmation gates, same rollback section. Reason: pattern already validated end-to-end on context7 (see `feedback_split_policy_from_setup` memory).
- 2026-04-29: Use `setup-wiki/README.md` and `using-wiki/README.md` as the README templates — they're more thorough than the context7 pair (which has no READMEs). Adding READMEs upfront avoids re-opening the [skill-readmes] task later.
- 2026-04-29: `auth.toml` is the secret-bearing file; never echo `gitea_token` in chat. Edit/Write tool calls inevitably contain it (transcript) — that's OK; chat output must not.
- 2026-04-29: `~/.claude.json` `mcpServers.projects-meta` registration uses absolute path to `dist/server.js` (Win path: `C:/Users/<USER>/.local/projects-meta-mcp/dist/server.js`). Forward slashes work on all three platforms.
- 2026-04-29: Smoke test in setup phase 7 = `mcp__projects-meta__meta_status` (read-only, returns sync diagnostics). Caveat: in-session smoke only proves "MCP still alive", not "new registration is what's serving" — same caveat as context7.
- 2026-04-29: Mutation tools (`tasks_*`, `knowledge_*`) follow two-step preview→confirm pattern; `using-projects-meta` documents the pattern and forbids inlining `confirm: true` without explicit user "ok".
- 2026-04-29: Both skills shipped v1.0.0; `setup-projects-meta` description carries Russian + English triggers ("install/set up/configure projects-meta", "настрой/установи projects-meta", "...не работает / isn't working") same shape as setup-context7; `using-projects-meta` description prioritizes cross-project / shared-wiki triggers and explicitly tells the harness to skip for current-project state.
- 2026-04-30: After user prodded "почему ты pull не сделал в самом начале?", explicit `git pull` on `~/projects/projects-wiki` revealed `wiki-path-mismatch-resolution.md` — canon path changed from `~/projects/.wiki` (write/read mismatch bug) to `~/projects/projects-wiki/` (clone root) with content at `~/projects/projects-wiki/.wiki/`. Fixed all six places in the new skills (setup SKILL+README, using SKILL+README, concept page, this task file). Phase 1 of setup-projects-meta now detects legacy clone; Phase 4 re-clones to canon. Lesson saved as feedback memory `pull_shared_wiki_explicitly`.

## Open questions
- [ ] `project-bootstrap` Step for `setup-projects-meta`? — concept page says "may be added later as 'recommend installing projects-meta'". Decision: defer, separate task.
- [ ] Should `using-projects-meta` carry its own `Local-first rule` or just point to the wiki anchor? Decision: carry it inline — concept page says "for the **current** project read locally; MCP cache is for **other** projects". Critical enough to repeat.

## Completed steps
- [x] Read `setup-context7` + `using-context7` SKILL.md as templates
- [x] Fetch `packages/projects-meta-mcp` + `concepts/setup-using-skill-pair` via `knowledge.get`
- [x] Inspect `scripts/build.sh` + `scripts/install.sh` + skill folder layouts (setup-context7 = SKILL.md only; setup-wiki = SKILL.md + README.md)
- [x] Promote task to 🔴 in STATUS.md
- [x] Draft `skills/setup-projects-meta/SKILL.md` (8-phase, model setup-context7)
- [x] Draft `skills/using-projects-meta/SKILL.md` (model using-context7, local-first rule + two-step mutation)
- [x] Write README.md for both skills (model: setup-wiki / using-wiki)
- [x] `bash scripts/build.sh setup-projects-meta using-projects-meta` → both archives in `dist/`
- [x] `bash scripts/install.sh ...` → both installed to `~/.claude/skills/`
- [x] Smoke: both skills visible in `Skill` tool listing in this session
- [x] Wiki: `concepts/projects-meta-skills.md` added; `index.md` + `log.md` updated
- [x] Closed task in STATUS.md (🟢 done); next step is round-trip close via `mcp__projects-meta__tasks_close target_project=claude-skills` to mirror state to Gitea

## Notes
- Wiki anchors live in shared `projects-wiki` Gitea repo (`https://git.kzntsv.site/OpeItcLoc03/projects-wiki`), cloned to `~/projects/projects-wiki/.wiki` on this machine.
- Original task created from another workstation (`OpeItcLoc03@DESKTOP-NSEF0UK`) via `mcp__projects-meta__tasks_create` — closing it should use `mcp__projects-meta__tasks_close target_project=claude-skills` to round-trip back to the same Gitea board.
- After install, restart Claude Code is required for the new MCP tool registrations to bind to a fresh stdio session — same caveat as setup-context7.