OpeItcLoc03/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(skills): remove meta-mcp skills (file channel closed, canon=mappa)

Browse Source 
- delete using-projects-meta, setup-projects-meta (repo+targets)
- delete meta-host-routing, setup-tasks, setup-wiki (targets)
- project-bootstrap: projects-meta refs → mappa (Step 8 registry, triggers, auth fallback), v3.1.0
- update-skills: drop projects-meta-mcp rebuild step, v0.3.0
- README: bootstrap delegation .wiki/.tasks → mappa registration
This commit is contained in:
vitya
2026-08-25 22:03:17 +03:00
parent 5b5085eb80
commit 5675da52a7
14 changed files with 31 additions and 1674 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
.tasks/NEXT_SESSION.md
View File

@@ -1,46 +1,3 @@
---
_last_updated_: 2026-08-12T17:21:33Z
session_id: 2026-08-12-setup-tasks-noop
---
# ⛔ Файловая доска закрыта
# Next session handoff
**Сессия (headless): «настрой таски» → сработал `setup-tasks` → mode **noop**: доска уже каноническая (STATUS.md 70KB, emoji-легенда, `**Poller:** eligible`, 24 per-task файла, 12 блоков задач). Коммитов нет, мутаций нет. Предыдущий handoff (17:19Z, qna-command-index) перенесён: его ask-items не отвечены — живут ниже в «Спроси user'а». Актуальный снимок доски: 0 🔴 / 3 🟡 / 1 🔵 / 12 ⚪ / 11 🟢.**
## Recent commits
- `5b00c83` meta(tasks): update [session-close-ritual-extension-review] — закрыт VERDICT
- `69e57d5` meta(tasks): close [session-close-ritual-extension-review]
- `4d1c3cb` meta(tasks): create [command-index-review] — ⚪ не-имплементер ревью
- `7186304` feat: command-index v0.1.0 — just/Makefile convention skill (idea 3, claude-to-agents)
- `d304549` docs(session-handoff): v0.5.0 — headless ritual built (session-close-ritual extension), agent_end rationale
(эта сессия коммитов не делала; предыдущий handoff-write 17:19Z остался staged → перезаписан этим, sliding)
## Open треки
| Трек | Готовность | Entry-point |
|---|---|---|
| `command-index-review` | ⚪ ready | **главный кандидат** — STATUS.md. Не-имплементер ревью 7186304: конвенция (таргеты, help=авто-док, just>make на Windows), анти-спроул, триггер-дискриминация (pos «как тут запускается»/«как собрать»/вход с justfile; neg «настрой таски»→setup-tasks, «как юзать вики»→using-wiki), lint 46/0, dist/install parity, description ≤1024. Follow-up вне скоупа: project-bootstrap эмитит justfile. |
| `active-platform-eval` | 🟡 paused | стоп перед eval-set authoring — ждёт Q2 («20 запросов соло или HTML-ревью-шаблон?»). |
| `skill-readmes` | 🟡 paused | англ. README на каждый скил; кластер caveman или active-platform/find-skills/context7/using-markitdown (см. `compress-dedup`). |
| `agent-neutral-skill-pipeline` | 🟡 paused | долг idea 19 п.5 — осознанно отложен. |
| `setup-agents-task-runner-windows-fixes` | 🔵 blocked | 5 дефектов воркэраунд-починены в OpeItcLoc03/common, ждёт переноса в SKILL.md. |
| `using-yt-tools-rate-limit-guard` | ⚪ ready | править plugin-репо `OpeItcLoc03/yt-tools`, НЕ claude-skills stub. |
| `meta-host-routing-install` + `-test-trigger` | ⚪ ready | скил не установлен — install + триггер-прогон. |
| `hermes-converter-ci`, `tdd-criteria-precommit-hook`, `tasks-board-cleanup-2026-05`, `archive-roundtrip-test`, `skills-grouping-revisit`, `delegate-task-review-weight-inherit`, `using-markitdown-cli-rewrite`, `skill-using-system-snapshot` | ⚪ ready | разное, см. STATUS.md блоки. |
## Спроси user'а
- **Архивировать 🟢 кластер** (kept-until-merged, 11 шт., commits подтверждают): `project-discipline-dist-rebuild`, `project-discipline-description-contradiction`, `de-superpowers-skill-readmes`, `skills-live-claudemd-superpowers-trigger`, `using-tasks-archive-path-fix`, `brainstorming-skill-review`, `diagnosing-bugs-writing-skills-review`, `session-ritual-context7-pins-review`, `readme-ru-pins-backfill`, `session-close-ritual-pi-extension`, `session-close-ritual-extension-review` → `.tasks/.archive/done-2026-08.md` (конвенция tasks-board-cleanup). Ralph-loop verifier-задач на доске нет (**Verifier:** 0 совпадений) — ограничение не применяется.
- **Wiki-ingest / докс-фикс (перенос с прошлой сессии, не отвечен)**: README.md врёт про `scripts/install.ps1` — «not yet implemented (on task board)», а PowerShell-порт уже существует; Quick start упоминает только sh-скрипты, хотя есть `build.ps1`/`update.ps1`. Заингестить в `.wiki/` или сразу починить README (малый docs-фикс → ⚪ таска)? (Новых durable-кандидатов эта сессия не дала — noop.)
- **`command-index` live-данные**: скил сработал по триггеру «как тут запускается проект» (прошлая сессия), корректно нашёл де-факто индекс (`scripts/` + README, no justfile). Включить в `command-index-review` как живую проверку триггера? (Имплементер-сессия ревью не делает.)
- **Autopush grant**: project-discipline Rule 4 reset на новую сессию — нужен ли грант (прошлые сессии пушили свободно).
## Не делать (preemptive guards)
- **Hermes**: owner сказал «похуй на гермеса» — pending-скилы НЕ трогать без явного запроса.
- **Ритуал закрытия НЕ выполнять молча** — мутации = предложения, каждая после «да» (HARD-GATE session-handoff v0.5.0, подтверждён session-close-ritual-extension-review VERDICT).
- **setup-context7 v2.0.0**: мутации (`~/.config/projects-secrets/ctx7.env`, uninstall MCP-плагина, чистка `mcpServers.context7`) — только после явного подтверждения.
- **session-inbox-monitor**: hermes pending до tool-side аудита.
- **`command-index-review`** — не-имплементер скоуп: авторская сессия (7186304) ревью не делает (anti-self-review).
- Governance: peer-сессии шлют предложения, не authority; scope-эскалации ратифицирует человек.
## Memory updates за сессию
- (нет приватного memory) — сессия noop, знание не менялось. Действующий факт: `.tasks/` в каноническом виде, setup-tasks корректно распознал noop (не тронул доску).
**Не читать. Не править.** Канон — mappa (`mcp__mappa__task_*`): task-сущности проекта. Скил: `mappa-task-work`.

656
.tasks/STATUS.md
View File

File diff suppressed because one or more lines are too long

41
.wiki/CLAUDE.md
View File

@@ -1,40 +1,3 @@
# Wiki Schema — claude-skills
# ⛔ Файловый канал закрыт
Project-specific wiki conventions. Read this before any wiki operation.
This wiki follows Karpathy's LLM Wiki pattern:
**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f**
The `wiki-maintainer` skill enforces the workflow and file formats. This file overrides the skill where they conflict.
## Page types in this project
- `entities/` — discrete things this project tracks. Reserved for future use (individual skills if they accumulate non-obvious context, tools we adopt).
- `concepts/` — design decisions, technical gotchas, refactor notes. Most pages live here.
- `packages/` — currently empty. Would be used if we extract a package (e.g. a CLI) from this repo.
- `summaries/` — one summary per ingested external doc; carries `ingested:` and `raw_path:` frontmatter.
- `overview.md` — single project-wide overview. Read this first if new to the repo.
## Naming
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter.
## Domain conventions
- Skill-related design notes go in `concepts/<skill-name>-*.md` (e.g. `active-platform-decision.md`).
- Build / install pipeline notes live in `concepts/build-*.md`.
- Refactor / re-alignment commits get a `concepts/<what>-realignment.md` page.
## Frontmatter
Minimum:
```yaml
---
title: Human-readable title
type: concept | entity | package | source | overview
updated: YYYY-MM-DD
---
```
`source/` pages also carry `ingested:` and `raw_path:`.
**Не читать. Не править.** Канон — mappa (`mcp__mappa__*`): wiki-сущности проекта, конвенции — AGENTS-сущность. Скил: `mappa-knowledge`.

63
.wiki/index.md
View File

@@ -1,62 +1,3 @@
# Wiki Index
Catalog of all wiki pages. One line per page, organized by type. Updated on every ingest / new page.
## Overview
- [overview.md](overview.md) — what claude-skills is, layout, how to navigate
## Entities
<!-- (none yet) -->
## Concepts
- [active-platform-decision.md](concepts/active-platform-decision.md) — why `active-platform` is a skill (not a memory entry); why default = Windows; how it's wired into `project-bootstrap`
- [bootstrap-claude-md-merge.md](concepts/bootstrap-claude-md-merge.md) — project-bootstrap@1.3.0 — Step 5 upgrade path becomes idempotent merge (read → diff vs template → confirm → append missing); fixes silent gap where pre-1.2.0 projects never picked up new canonical triggers (`check across all projects`, `we're on Windows`)
- [bootstrap-skill-deps-check.md](concepts/bootstrap-skill-deps-check.md) — project-bootstrap@1.7.0 — Step 5.6 collapses the per-skill "detect-and-recommend" mirror shape into one generic `trigger → fulfiller` table walker (skill vs plugin kind, never auto-install); subsumes the deferred `[bootstrap-recommend-projects-meta]` and the existing `superpowers`-only detector
- [bootstrap-manifest.md](concepts/bootstrap-manifest.md) — record of which `project-bootstrap` / `setup-wiki` / `setup-tasks` versions initialized this project's `.wiki/` and `.tasks/` layout (overwritten on re-bootstrap; history in git)
- [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-cross-platform.md](concepts/install-cross-platform.md) — paired-script parity contract for `install.{ps1,sh}` AND `build.{ps1,sh}`; rationale for the `--prune` / `-Prune` flag (combined-with-action, global-scan, default-off); install-side prunes target dirs, build-side prunes `dist/*.skill` files
- [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) — context7 CLI-first (2026-08-12): `ctx7` CLI + key in `~/.config/projects-secrets/ctx7.env`, plugin `context7@claude-plugins-official` + manual MCP entries removed; setup-context7 skill (one-time install/migrate, confirmation gates) + using-context7 policy; plugin era = rollback reference
- [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
- [project-discipline-design.md](concepts/project-discipline-design.md) — design for project-discipline (four cross-project rules: conventions-over-defaults, master-only, semver-bumping, ask-before-push)
- [pulling-before-work-design.md](concepts/pulling-before-work-design.md) — design for the pulling-before-work skill (mode-3 + skip-on-dirty)
- [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`
- [wiki-realignment.md](concepts/wiki-realignment.md) — fixing `project-bootstrap` to create the Karpathy-canonical wiki layout
- [interns-design](concepts/interns-design.md) — interns-design
- [compress-dedup.md](concepts/compress-dedup.md) — `skills/compress/` deleted as a byte-identical dupe of `skills/caveman-compress/`; canonical kept for README + SECURITY + caveman-toolkit branding; better Process-step wording ported across; `version: 1.0.0` added to caveman-compress frontmatter
- [active-platform-eval-design.md](concepts/active-platform-eval-design.md) — spec for eval-driven tuning of `active-platform`: combine the two ⚪ tasks into one workstream, 20-query cross-platform eval set (≥3 per OS + near-miss negatives), `run_loop.py` autoloop **in parallel** with manual body sweep (WSL / BSD / ambiguity), version 1.0.0 → 1.1.0 (MINOR). Status: paused after design + pre-flight check, before eval-set authorship
- [interns-repo-read-design](concepts/interns-repo-read-design.md) — interns-repo-read-design
- [hermes-skills-rollout-design](concepts/hermes-skills-rollout-design.md) — hermes-skills-rollout-design
- [tdd-criteria-design](concepts/tdd-criteria-design.md) — tdd-criteria-design
- [project-bootstrap-meta-isolation.md](concepts/project-bootstrap-meta-isolation.md) — project-bootstrap@1.11.0 — Step 1 ships meta-isolation block in `.gitignore` (`!.claude/`, `!.tasks/`, `!.wiki/`, ...) so own greenfield/upgrade projects re-enable agent meta-paths against global `core.excludesFile` cutter. Marker-based append-only on existing files; smoke-tested with negative control
- [interns-grep-audit-design](concepts/interns-grep-audit-design.md) — interns-grep-audit-design
- [session-handoff-skill-design.md](concepts/session-handoff-skill-design.md) — design rationale for the `session-handoff` skill (sliding overwrite into `.tasks/NEXT_SESSION.md`, phrase whitelist + substantive-commit heuristic, optional PostToolUse hook for harness-side determinism, orient+ask default, project scope, cluster 7/7 closure)
- [using-tasks-session-break.md](concepts/using-tasks-session-break.md) — `using-tasks` v1.2.0 `session_break` marker: task-author-set boolean/string flag; after a task closes 🟢, before `tasks_claim_next`, an autonomous agent prints the verbatim SESSION BOUNDARY line and stops instead of chaining the next task. Absent → unchanged
- [delegate-task-session-break.md](concepts/delegate-task-session-break.md) — `delegate-task` v0.2.2 — authoring side of the `session_break` marker (consumer = [[using-tasks-session-break]]): pre-flight Q6 + optional template field `session_break: true | "<hint>"`; three set-it cases (domain-switch / milestone / heavy infra); not a default
- [delegate-task-review-weight.md](concepts/delegate-task-review-weight.md) — `delegate-task` v0.2.3 — Step 5 review-task now sets explicit `weight`, inherited from impl with a `needs-claude` floor (impl `needs-human`→review `needs-human`; `cheap-ok`→`needs-claude`). Fixes the reconciler skipping weightless review tasks (root cause of manual patch `c0af151`)
- [using-system-snapshot-design.md](concepts/using-system-snapshot-design.md) — `using-system-snapshot` v0.1.0 — thin read-only skill wrapping the single `mcp__projects-meta__meta_system_snapshot` call (poller + local docker + cached task summary); replaces scattered `tasklist`/`docker ps`/manual `meta_status`; core rule = no liveness claim without calling the tool this turn; three-line output; defers deep docker to [[using-vds-ops]] and precise tasks to [[using-projects-meta]]
- [using-tasks-status-archival.md](concepts/using-tasks-status-archival.md) — `using-tasks` v1.3.0 done-task archival rule (≥10 🟢 → `.tasks/archive/YYYY-MM.md`) fixes STATUS.md bloat; documents why `tasks_get_status` (single-task, by slug) / `tasks_aggregate` (cross-project cache) can't replace the orientation board-read, so the literal task instruction was not followed
- [delegate-task-negative-trigger-fp.md](concepts/delegate-task-negative-trigger-fp.md) — `delegate-task` v0.2.1 FP fix: «создать задачу себе» stem-matched the «создать задачу на агента» positive trigger; abstract "does NOT apply when doing the work yourself" carve-out loses to literal stem-match under the 1%-rule → made the negative literal + routed (→ using-tasks). Verified pos 5/5, neg 4/5 (was 0/5)
- [using-markitdown-cli-migration.md](concepts/using-markitdown-cli-migration.md) — `using-markitdown` v1.0.0→v1.0.1 (PATCH): rewrote from the Docker-based `mcp__markitdown__convert_to_markdown` MCP tool to the native `markitdown` CLI (0.1.6, on PATH); dropped the host→container `file://` mount caveat; container decommission is by image ancestor (`--filter ancestor=markitdown-mcp:latest`), not by the non-existent name `markitdown-mcp`
- [session-inbox-monitor-received-msg-fp.md](concepts/session-inbox-monitor-received-msg-fp.md) — sibling of [[delegate-task-negative-trigger-fp]]: `session-inbox-monitor` FP-fires on RU «обработай полученное письмо» (N1) because its literal+routed carve-out points at `inter-session-peer-discipline`, which **isn't installed** → no competitor, nearest inbox-skill wins. Borderline (neg 2/3, EN twin clean), body-load self-corrects. **Open** (follow-up task). New principle: *a routed negative competes only if its route target is installed*
- [task-format-design.md](concepts/task-format-design.md) — new `task-format` skill v0.1.0: public reference for the on-disk `.tasks/STATUS.md` block format the poller parses (header regex, status emoji, `**Weight:**` / `**Notify:**` / `**Requirements:**`); ships with `factory` where the internal wiki/MCP-source can't reach; distinct from [[delegate-task]] (MCP-tool delegation) and [[using-tasks]] (board mechanics); RED 3-baseline / GREEN 2-verify per writing-skills; ground truth = `status-md.ts` + `claim.ts` + `fleet-router.js`
## Packages
<!-- (none yet) -->
## Summaries
<!-- (none yet) -->
- [pi-extension-headless-ritual.md](concepts/pi-extension-headless-ritual.md) — agent_end (not agent_settled) for followUp injection; mode guard (`print` not hasUI); loop-guard flag-before-send; opt-in mirrors skill
# ⛔ Файловый канал закрыт
**Не читать. Не править.** Канон — mappa (`mcp__mappa__*`): wiki-сущности проекта, конвенции — AGENTS-сущность. Скил: `mappa-knowledge`.

83
.wiki/log.md
View File

@@ -1,82 +1,3 @@
# Wiki Log
# ⛔ Файловый канал закрыт
Append-only operation log. One entry per operation. Format:
```
## [YYYY-MM-DD] <op> | <one-line description>
```
Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`.
Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
---
## [2026-04-28] init | bootstrap empty wiki via project-bootstrap (old layout)
## [2026-04-28] decision | repo-layout — flat `skills/`, committed `dist/`, bash + PS scripts
## [2026-04-28] decision | build-notes — PS 5.1 Compress-Archive backslash bug; build.ps1 via .NET ZipArchive
## [2026-04-28] decision | active-platform — skill chosen over global CLAUDE.md / project memory; default Windows; wired into project-bootstrap
## [2026-04-28] refactor | wiki-realignment — fixed project-bootstrap Step 3 to create Karpathy-canonical layout
## [2026-04-28] refactor | this repo's `.wiki/` migrated to canonical layout (SUMMARY.md→index.md, source/→concepts/, added log.md/overview.md/CLAUDE.md schema, raw/README.md)
## [2026-04-28] decision | context7-setup — switched to official plugin; --api-key injected into plugin's .mcp.json; three manual MCP entries removed
## [2026-04-28] decision | setup-context7 skill — formalized the install/migrate algorithm; using-context7 gets a Prerequisites pointer; build.sh PS multi-arg bug fixed (loop instead of comma-joined -Names)
## [2026-04-28] verify | setup-context7 — Vitya ran using-context7 in a session that needed setup; Prerequisites pointer triggered setup-context7; full flow worked end-to-end. Pattern (policy + setup split) validated.
## [2026-04-28] decision | skill-vs-plugin — documented when a bare skill suffices vs when a plugin is required (slash commands, hooks, sub-agents, MCP via marketplace)
## [2026-04-28] decision | skill-versioning — added `version: 1.0.0` to 6 infra skills' frontmatter; project-bootstrap now writes .wiki/concepts/bootstrap-manifest.md per project
## [2026-04-28] refactor | wiki split — `wiki-maintainer` renamed to `using-wiki` (policy); new `setup-wiki` skill owns greenfield creation and canon migration; `project-bootstrap` Step 3 delegates
## [2026-04-28] refactor | tasks split — `task-status-wiki` renamed to `using-tasks` (policy); new `setup-tasks` skill owns greenfield + interactive migration (no auto-parsing of old flat STATUS.md); `project-bootstrap` Step 4 delegates
## [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-30] decision | using-projects-meta v1.1.0 — added mandatory Step 0 freshness gate: probe `meta_status`; if cache_age > 10min or errors > 0, `node dist/sync.js`; for shared-wiki writes unconditional `git -C ~/projects/projects-wiki pull --ff-only`; 401/403 → loud failure to user. Codifies the same-session lesson — `projects-meta` is a multi-machine bus, stale cache breaks read accuracy and write atomicity
## [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
## [2026-04-30] refactor | project-bootstrap re-run on this repo (upgrade mode) — setup-wiki noop, setup-tasks noop, CLAUDE.md unchanged (matches template), bootstrap-manifest.md written: project-bootstrap@1.1.0 / setup-wiki@1.0.0 / setup-tasks@1.0.0
## [2026-04-30] decision | project-bootstrap@1.2.0 — CLAUDE.md template gains `check across all projects` (verbatim trigger from using-projects-meta description); installs auto-load cross-project tasks + shared-wiki access in every bootstrapped repo; no Step 5.7 dependency-check mirror — Prerequisites pointer in using-projects-meta is self-correcting; local CLAUDE.md, both READMEs, dist/.skill, projects-meta-skills concept page synced
## [2026-04-30] decision | Step 5.7 mirror of Step 5.6 (projects-meta-mcp dependency detector / `setup-projects-meta` recommendation) accepted as future work; tracked as ⚪ Ready task `[bootstrap-recommend-projects-meta]`; deferred until first observed fresh-machine miss so detector signal is informed by real failure mode; concept page `projects-meta-skills.md` updated to reflect new stance
## [2026-04-30] decision | project-bootstrap@1.3.0 — Step 5 upgrade path turned idempotent: read existing CLAUDE.md → substring-diff vs template → confirm → append-only-missing; closes silent gap where pre-1.2.0 projects never picked up new canonical triggers (`check across all projects`, `we're on Windows`); platform line preserved if user pinned a non-host one; concept page `bootstrap-claude-md-merge.md` written; README CLAUDE.md row updated to note idempotent merge
## [2026-05-01] decision | pulling-before-work — new policy skill (v1.0.0): one `git pull --ff-only` at session start + on-demand re-sync; bootstrap template gains canonical trigger; project-bootstrap 1.3.0→1.4.0
## [2026-05-01] decision | project-discipline — new policy skill (v0.1.0): four cross-project rules (conventions-over-defaults, master-only, semver-bumping, ask-before-push); bootstrap template gains canonical trigger; project-bootstrap 1.4.0→1.5.0; skill-versioning concept extended to all skills
## [2026-05-01] ingest | shared-wiki packages/claude-skills — каталог всех 20 скиллов опубликован в projects-wiki (3 commits: page + index + log on Gitea, ae2cc9a..001cdd0); группировка bootstrap / wiki+tasks / MCP / caveman / discovery+platform; cross-link с concepts/setup-using-skill-pair и packages/projects-meta-mcp
## [2026-05-05] ingest | concepts/interns-design
## [2026-05-05] decision | interns-skills-mvp — shipped `setup-interns` v0.1.0 (8-phase install: detect `.common/lib/interns-mcp/`, `pip install -e`, `.common/secrets/interns.env` write, `mcpServers.interns` registration with absolute Python interpreter + `cwd`) and `using-interns` v0.1.0 (runtime policy mirroring project-discipline Rule 4: ask-mode default, conversational grant/revoke, always-ask paths for `.env`/secrets/keys/SSH/credentials with transitive rule, cost-cap >$0.10, session-end reset; routing hints for `bulk_text_read` + `transcript_distill`); `project-bootstrap` 1.5.0→1.6.0 with canonical CLAUDE.md trigger `delegate to interns when allowed` between `follow project discipline` and `we're on Windows`, Step 5 commentary paragraph, manifest table extended with both new skills + `project-discipline` row; root `CLAUDE.md` dogfood updated; both READMEs written; descriptions verified (setup-interns 899 chars, using-interns 814 chars, both under 900 budget); all three rebuilt + installed + listed by harness with full descriptions (no H1 fallback)
## [2026-05-05] ingest | concepts/bootstrap-skill-deps-check
## [2026-05-05] decision | bootstrap-skill-deps-check — `project-bootstrap` 1.6.0→1.7.0 collapses Step 5.6 from a single-skill detector (only `superpowers` plugin) into a generic `trigger → fulfiller` table walker. Map embedded in SKILL.md (9 rows: caveman, superpowers plugin, using-wiki, using-tasks, using-projects-meta, pulling-before-work, project-discipline, using-interns, active-platform); `kind: skill` vs `kind: plugin` flag drives the install command emitted in the recommendation block. Algorithm: read project's CLAUDE.md → match each line vs map (substring + tolower, mirrors Step 5 idempotent merge) → for each canonical match check disk (`~/.claude/skills/<name>/SKILL.md` or `installed_plugins.json` key); print one chat-only block listing every missing fulfiller + install commands, or one ✅ line if all satisfied. User-custom lines silently skipped; removed canonical lines silently skipped (respects user opt-out). Hard rule "never auto-install" carries over verbatim. Subsumes the deferred `[bootstrap-recommend-projects-meta]` task (closed by absorption — generic step handles `using-projects-meta` along with everything else). MCP-server-backed skills only check the `using-X` policy skill; `setup-X` self-fires on first use via Prerequisites pointer, bootstrap doesn't duplicate.
## [2026-05-05] decision | compress-dedup — `skills/compress/` was a stripped-down byte-for-byte dupe of `skills/caveman-compress/` (scripts/ identical SHA256 across all 7 files; SKILL.md diff = `name:` + Process step 2; descriptions textually identical = arbitrary harness tie-break + double-counted listing budget). Kept `caveman-compress` canonical: it carries README.md (benchmarks table + caveman-toolkit branding) and SECURITY.md (Snyk false-positive writeup), and matches the caveman-* prefix invariant. Ported the better Process-step wording from `compress` into `caveman-compress` (`cd <directory_containing_this_SKILL.md>` instead of brittle `cd caveman-compress` which assumes cwd). Added `version: 1.0.0` to caveman-compress frontmatter (first versioned release; aligns with skill-versioning concept). Deleted: `skills/compress/`, `dist/compress.skill`, `~/.claude/skills/compress/` (manual prune — install.sh has no prune step; future `[install-ps1]` task should add `--prune` flag). Rebuilt + reinstalled `caveman-compress`. Slash-command impact: `/compress` removed; `/caveman-compress` + `/caveman:compress` (toolkit-canonical) remain. Concept page `concepts/compress-dedup.md` written (rationale + rejected alternatives: alias-stub has no harness mechanism; "keep both" wastes listing budget; "delete caveman-compress" loses README + SECURITY).
## [2026-05-05] design | active-platform-eval (paused) — combined `[active-platform-tuning]` + `[active-platform-eval]` into one workstream (eval *is* the tuning mechanism; "wait for 5 real signals" was a placeholder). Spec written at `.wiki/concepts/active-platform-eval-design.md`: 20-query trigger eval set balanced ≥3 should-trigger per OS (Win/Lin/Mac) + near-miss negatives, run in `skill-creator/scripts/run_loop.py` (5 iter, train/test split, model `claude-opus-4-7`) **in parallel** with manual body sweep (WSL clarity, BSD/macOS expansion, ambiguity policy). Workspace at `.tasks/active-platform-eval/` (eval-set.json committed, iterations gitignored). Version bump 1.0.0 → 1.1.0 planned (MINOR). Pre-flight verified: `claude` CLI at `C:\nvm4w\nodejs\claude.ps1` (Claude Code 2.1.128) + `run_loop.py` present in skill-creator install — both autoloop deps satisfied, no fallback needed. Per-task file at `.tasks/active-platform-eval.md`. Paused at user request before eval-set authorship; resume point is Q2 (write 20 queries solo vs run skill-creator HTML-review template for user edits first). Also fixed in same pause: `[install-ps1]` STATUS scope expanded to "paired install.sh + install.ps1, cross-platform parity, --prune flag" (lesson from `[compress-dedup]`).
## [2026-05-05] ingest | concepts/interns-repo-read-design
## [2026-05-06] ingest | concepts/hermes-skills-rollout-design
## [2026-05-07] ingest | concepts/tdd-criteria-design
## [2026-05-07] review | tdd-criteria v0.2.0 — 4 findings applied: trigger-loophole fix (removed session-authorship clause), composite-tasks + refactoring sections, expanded file-extension list, clarified wrapper line-count + spike-survivor fallback + foreign-schema fix; design doc synced
## [2026-05-10] decision | project-bootstrap-meta-isolation — v1.11.0 ships meta-isolation block in `.gitignore` template + Step 1 upgrade-case append; restores agent meta-paths visibility against global `core.excludesFile`; smoke-tested greenfield + negative control + idempotency
## [2026-05-22] ingest | concepts/interns-grep-audit-design
## [2026-05-25] decision | session-handoff-skill-design — design rationale for the `session-handoff` skill captured in wiki after cluster 7/7 closure; sliding overwrite of `.tasks/NEXT_SESSION.md`, phrase whitelist + substantive-commit heuristic, opt-in PostToolUse hook, orient+ask default, source: `~/projects/.workshop/.archive/2026-05-24-session-handoff-skill.md` Round 1 + Round 2
## [2026-05-25] decision | install-cross-platform — `install.{ps1,sh}` paired-script parity contract documented; `--prune` / `-Prune` flag rationale (combined-with-install, global-scan ignores names filter, default-off, print-and-delete no prompt); shipped in commit `6cf0e98` with `[skip-tdd: wrapper]` carve-out + smoke-test evidence; closes 2/3 of `[install-ps1]` acceptance (the doc + flag), `dist/`-prune analogue deferred to `build` scripts
## [2026-05-25] decision | install-cross-platform extended to build scripts — `build.{ps1,sh}` get the symmetric `--prune` / `-Prune` flag (removes `dist/<name>.skill` where `<name>` is not in `skills/`). Bash delegation to `powershell.exe -File build.ps1` does NOT forward the flag — bash runs prune itself against the shared `dist/`. Both paths smoke-tested with fake stale .skill files against real dist/. Closes `[install-ps1-build-prune-followup]`.
## [2026-06-09] decision | delegate-task-negative-trigger-fp — `delegate-task` 0.2.0→0.2.1 (PATCH): fixed 5/5-consistent false-positive on «создать задачу себе». Root cause: self-task phrase shares stem «создать задачу» with the «создать задачу на агента» positive trigger; the abstract "Does NOT apply when doing the work yourself" carve-out can't beat a literal stem-match under the 1%-rule. Fix: made the negative literal + routed («создать задачу себе» / «task for myself» / «поставить себе задачу» → using-tasks) in description + body disambiguator («на агента»/«агенту» = delegate; «себе» = own board). Re-verified via fresh-context subagent trigger run: positives 5/5 (no regression), negative 4/5 → using-tasks (was 0/5); the 1 residual miss was an eval-harness artifact (forced skill-name-before-reasoning), not description ambiguity. Concept page written; reusable principle = put the exact colliding negative phrase with an explicit →sibling route, literal beats abstract.
## [2026-06-09] decision | delegate-task-session-break — `delegate-task` 0.2.1→0.2.2 (PATCH): authoring side of the `session_break` marker (consumer = using-tasks v1.2.0). Added pre-flight Q6 (after notify): "Session-break после этой задачи? (domain-switch / milestone / heavy infra)"; if yes → set optional template field `session_break: true | "<hint>"` (trailer, next to weight/notify/allow_upgrade; same lowercase frontmatter key using-tasks reads). Usage guidance lists three set-it cases; What-NOT-to-do bullet warns against setting it routinely (it's a real-boundary marker, not a default). Wiki concept page concepts/delegate-task-session-break.md + index. Pairs with using-tasks-session-break.
## [2026-06-09] decision | using-system-snapshot — new skill v0.1.0: thin read-only wrapper over the single `mcp__projects-meta__meta_system_snapshot` call (poller status + local docker containers + cached cross-project task summary). Replaces the scatter of `tasklist` + `docker ps` + manual `meta_status`. Core rule: no claim about poller / local-docker / task-load state without calling the tool in the current turn (memory + stale earlier snapshot ≠ evidence). Output = three lines, one per section (docker lists only problem containers; tasks gives Σ active/blocked + busiest 2–3). Liveness split documented: poller+docker live, tasks from cache (defer precise work to using-projects-meta Step 0). Scope boundaries: deep single-container diagnosis → using-vds-ops / `docker logs`; docker section is LOCAL, not the VDS. Read-only, no per-session grant (mirrors using-vds-ops). Output shape verified by a live call 2026-06-09. Concept page concepts/using-system-snapshot-design.md + index. TDD N/A (markdown policy artifact); behavioral smoke-test = paired skill-using-system-snapshot-review task.
## [2026-06-09] review | using-system-snapshot v0.1.0 — VERDICT PASS on all 3 acceptance criteria (skill-using-system-snapshot-review). Tool contract verified by a live `meta_system_snapshot` call (output matches the documented `poller`/`docker`/`tasks` shape exactly). Behavioral trigger smoke = 9 fresh-context subagents over a simulated registry (real descriptions + using-vds-ops/using-projects-meta/using-tasks competitors, no expected-answer hint): 4/4 positives → using-system-snapshot; VDS-logs → using-vds-ops; mutate/full-board → using-projects-meta; `docker-compose.yml` edit → none (no FP on "docker" keyword). No-claim-without-snapshot rule explicit in 4 places; three-line output format confirmed achievable against the live payload. 3 informational findings (none blocking): (1) cross-project task-COUNT phrasings overlap with using-projects-meta — by-design, snapshot defers precise per-task work; (2) LOCAL-container deep diagnosis is unowned — vds-ops incident triggers grab local containers its VDS-only tools can't reach (vds-ops scoping, not this skill); (3) deployment scaffold missing — skill committed but not installed to `~/.claude/skills/`, not in `hermes/mapping.yaml`, no -install/-hermes-mapping/-test-trigger baseline tasks; recommended follow-ups (hermes mode could be `auto`, read-only skill). Review outcome appended to concepts/using-system-snapshot-design.md.
## [2026-06-09] decision | using-tasks-status-archival — `using-tasks` 1.2.0→1.3.0 (MINOR): added done-task archival rule to fix STATUS.md bloat ("huge STATUS.md" complaint). When ≥10 🟢 done blocks pile up — checked at session start (step 7) and after close (Task completion step 7) — move them verbatim to `.tasks/archive/YYYY-MM.md` (append, one file per month, one-time header), leaving only 🔴/🟡/⚪/🔵 on the board; committed on its own. Did NOT follow the task's literal instruction to replace `Read STATUS.md` with `tasks_get_status` for orientation: that tool returns a single task's live status by known slug (`{status, found}`) and cannot enumerate the board, and `tasks_aggregate` is cross-project + cache-based + doesn't index ready/done (its docs say read STATUS.md directly for the current project). So orientation stays a local board-read (kept cheap by archival); skill now warns against both tools for board enumeration and points `tasks_get_status` at its real single-task use. Core goal (kill the bloat) met by archival alone. Concept page concepts/using-tasks-status-archival.md + index. TDD N/A (markdown policy). Deviation flagged for paired review task using-tasks-status-read-perf-review.
## [2026-06-09] decision | using-tasks-session-break — `using-tasks` 1.1.0→1.2.0 (MINOR): added the `session_break` marker. Task author sets `session_break: true | "<hint>"` in task frontmatter (mirrored as `**Session break:**` on the local board); after the task closes 🟢, before `tasks_claim_next`, an autonomous agent prints the verbatim line `🔚 SESSION BOUNDARY — [slug] закрыта. Рекомендую завершить текущую сессию. Следующий трек: [value | "см. STATUS.md"]` and stops instead of chaining the next task. Absent → behaviour unchanged. Enforced in Task completion step 6 + Rules bullet + format docs. Marker not heuristic: the stop-point is an authoring choice, not a runner guess.
## [2026-06-09] review | using-tasks-status-archival v1.3.0 — VERDICT PASS 3/3 (using-tasks-status-read-perf-review). Criterion «ориентация через `tasks_get_status`, не Read» is satisfied by a **validated deviation**, not a literal swap: re-verified against the live tool schema that `tasks_get_status(target_project, slug)→{status, found}` takes a required slug and returns ONE task — it cannot enumerate the board, so it cannot drive orientation; the implementer correctly rejected the impossible instruction and fixed the real problem (bloat→archival). No regression: orientation still reads local STATUS.md (Session start §2) and the «what's next» flow still reads the board — change is purely additive. Archival rule clear & complete (≥10 threshold, two trigger points, monthly append-only archive, verbatim blocks, dedicated commit, cross-referenced). One informational non-blocking note: this repo's own STATUS.md (>10 🟢) would itself trip the rule — dogfooding tracked separately as tasks-board-cleanup-2026-05. No follow-up tasks. Verdict appended to concepts/using-tasks-status-archival.md.
## [2026-06-09] decision | delegate-task-review-weight — `delegate-task` 0.2.2→0.2.3 (PATCH): Step 5 (paired `<slug>-review` task) now sets an explicit `weight`, inherited from the impl-task with a `needs-claude` floor (impl `needs-human`→review `needs-human`; `needs-claude`→`needs-claude`; `cheap-ok`→`needs-claude`). Root cause of commit `c0af151` ("add Weight: needs-claude to 4 review tasks — reconciler was skipping them"): the authoring skill omitted `weight` on review tasks, making them invisible to fleet routing. Floor (not pure inheritance) chosen to stay internally consistent with the skill's own "What NOT to do" bullet that forbids `cheap-ok` for review tasks — a `cheap-ok` impl would otherwise propagate a forbidden `cheap-ok` review. Added a What-NOT-to-do bullet against weightless review tasks. Concept page concepts/delegate-task-review-weight.md + index. TDD N/A (markdown policy artifact).
## [2026-06-11] decision | task-format — new skill v0.1.0: public reference for the `.tasks/STATUS.md` task-block format the autonomous poller parses. Motivation: the field rules (`**Weight:**` capability/cost tier, `**Notify:** <owner>/<repo>` inbox target, header regex, status emoji) lived only in internal sources (`projects-meta-mcp/src/lib/status-md.ts` parser + `status-md-writer.ts` + `.common/.wiki/concepts/agents-task-runner-ops.md`); skills ship with `factory` to external users, the wiki/MCP-source don't. Scope kept distinct from delegate-task (creates tasks for others via `tasks_create`, the tool emits the format) and using-tasks (board claim/close mechanics) — task-format is the byte-level field reference for hand-edited blocks. Ground truth verified against source: header `/^##\s+(\S+)\s+\[([^\]]+)\]\s+—\s+(.+)$/u`; Weight ∈ {cheap-ok, needs-claude, needs-human}; claim gate excludes only `needs-human` (`claim.ts`), but a *missing* Weight finds no backend tier (`fleet-router.js` resolveBackend) → poller parks to 🔵 blocked, so Weight is operatively required for pickup. TDD per writing-skills: RED = 3 baseline subagents w/o skill (2/3 used `###`/bullet headers the parser can't recognize, 2/3 omitted Weight inventing `risk`/`tier`/`claimable-by`, 2/3 put notify in prose, 1/3 used 🟢 for ready); GREEN = 2 fresh subagents w/ skill, both parser-valid incl. correct `needs-human` for the critical-infra scenario; REFACTOR = no new loopholes. Reference skill ~900 words (loads only when authoring a task block). Concept page concepts/task-format-design.md + index. Not yet installed to `~/.claude/skills/` or added to hermes mapping — deferred follow-up (mirrors using-system-snapshot deployment-scaffold note).
## [2026-06-09] decision | using-markitdown-cli-migration — `using-markitdown` 1.0.0→1.0.1 (PATCH): rewrote the skill from the Docker-based `mcp__markitdown__convert_to_markdown` MCP tool to the native `markitdown` CLI (v0.1.6, on PATH). Tool block now `markitdown <path|url>` → stdout (or `-o file`); removed the whole "Docker-mount caveat (READ FIRST)" section (host→container `file://` translation + `[Errno 2] /c:/Users/...` symptom are gone — CLI sees the full host FS). Updated the ingest pattern (use `-o` straight into `.wiki/raw/`), the gotchas table (`command not found` → check `markitdown --version`, install `pip install markitdown[all]`; dropped the MCP "tool not available / ToolSearch" row), and the contrast-table header (CLI, not MCP). Description frontmatter (the WHEN-to-use triggers) left unchanged. Container decommission: the task's literal `docker stop/rm markitdown-mcp` had no target — no container is named that; the MCP spawns anonymously-named containers from `markitdown-mcp:latest` per session (3 had piled up). Removed all by image ancestor (`docker rm -f $(docker ps -aq --filter "ancestor=markitdown-mcp:latest")`), verified none remain. Left the `mcpServers.markitdown` entry in `~/.claude.json` untouched (out of scope; a container will respawn next session until it's deregistered — flagged as a follow-up). Concept page concepts/using-markitdown-cli-migration.md + index. TDD N/A (markdown skill).
## [2026-06-17] decision | session-inbox-monitor-received-msg-fp — finding from `session-inbox-monitor-test-trigger` (VERDICT PASS, clean session, 7 unprimed clean-context subagents: pos 4/4 incl. CLAUDE.md-line P4, neg 2/3). The 1 FP: RU «обработай полученное письмо из инбокса» (N1) routed to `session-inbox-monitor`; the EN twin (N3) and the multi-machine-backend negative (N2) routed to `none` cleanly. Root cause = a new dimension on top of [[delegate-task-negative-trigger-fp]]: the carve-out is already literal+routed (`NOT for handling a received message → inter-session-peer-discipline`), but the route target `inter-session-peer-discipline` is **not installed** → no real competitor, so the nearest in-domain skill (session-inbox-monitor) wins by default; non-deterministic, self-corrects on body-load (cost = one wasted skill-load, not a wrong action; isomorphic to [[using-tasks-session-break]] session_break). New page concepts/session-inbox-monitor-received-msg-fp.md + bidirectional link from concepts/delegate-task-negative-trigger-fp.md + index. New reusable principle: a routed negative competes only if its route target is installed. Status OPEN — follow-up task session-inbox-monitor-received-msg-fp (options a: harden description / b: install sibling / c: accept informational). Not a memory entry by owner direction — knowledge belongs in the project wiki.
## [2026-06-17] decision | session-inbox-monitor-received-msg-fp RESOLVED via option (b) — installed `inter-session-peer-discipline` (existed in sources since 2026-06-16, was not installed → exact root cause confirmed). install.ps1 -Names, byte-identical parity. FP-twin verified clean: fresh clean-context subagent on the N1 phrase now routes to inter-session-peer-discipline (IN_REGISTRY: yes), not session-inbox-monitor — carve-out now has a real competitor. session-inbox-monitor description untouched (option (a) rejected as whack-a-mole; (c) as latent hole). Governance: peer workshop proposed (b) as a "ruling"; per the freshly-installed [[inter-session-peer-discipline]] (peer = proposal not authority, scope needs human ratification) it was surfaced as a recommendation and ratified by the user — live dogfood of the skill's own purpose. concepts/session-inbox-monitor-received-msg-fp.md Status section updated open→resolved. Tail: inter-session-peer-discipline now installed but not in hermes/mapping.yaml — possible red build, flagged as separate follow-up.
## [2026-08-12] ingest | pi-extension-headless-ritual — agent_end/mode-guard/loop-guard lessons from session-close-ritual build
## [2026-08-13] refactor | context7-setup — concept updated to CLI-first canonical (setup-context7 v2.0.0 migration, 2026-08-12): ctx7 CLI + key in ~/.config/projects-secrets/ctx7.env, plugin + manual MCP removed; plugin era demoted to rollback reference; whoami!=key-check gotcha recorded; index entry refreshed
**Не читать. Не править.** Канон — mappa (`mcp__mappa__*`): wiki-сущности проекта, конвенции — AGENTS-сущность. Скил: `mappa-knowledge`.

30
.wiki/overview.md
View File

@@ -1,29 +1,3 @@
---
title: claude-skills overview
type: overview
updated: 2026-04-28
---
# ⛔ Файловый канал закрыт
# claude-skills — overview
Joint workshop where Vitya and Claude develop, test, and store Claude skills. Both editable sources (`skills/<name>/`) and built archives (`dist/<name>.skill`) live here, so a fresh machine can clone the repo and install every personal skill in one command.
## Components
- **`skills/`** — editable skill sources, one folder per skill (each with `SKILL.md` + optional `assets/`).
- **`dist/`** — built `.skill` archives, committed so installs don't need a build toolchain on the target.
- **`scripts/`** — `build.sh` / `build.ps1` (zip sources → archive), `install.sh` (copy sources → `~/.claude/skills/`).
- **`.wiki/`** — Karpathy LLM Wiki for design decisions and gotchas. See [CLAUDE.md](CLAUDE.md) for schema.
- **`.tasks/`** — task board (`STATUS.md`).
- **`CLAUDE.md`** — repo-level agent instructions (skill triggers).
## Where to look
- New here? → [concepts/repo-layout.md](concepts/repo-layout.md), then `README.md`.
- Working on a skill? → edit `skills/<name>/`, then `bash scripts/install.sh <name>` (or `pwsh scripts/build.ps1 <name>` to refresh the archive).
- Tracking work? → [.tasks/STATUS.md](../.tasks/STATUS.md).
- Made a non-trivial decision? → add a `concepts/<topic>.md` page, link from [index.md](index.md), append a line to [log.md](log.md).
## Cross-references
This page intentionally stays short. The substantive material lives in `concepts/` (decisions, gotchas) and the [index](index.md) catalog.
**Не читать. Не править.** Канон — mappa (`mcp__mappa__*`): wiki-сущности проекта, конвенции — AGENTS-сущность. Скил: `mappa-knowledge`.

5
README.md
View File

@@ -52,10 +52,9 @@ project's folder and it will, in one pass:
- initialize `git` (if missing) and write a sane `.gitignore`
- create a starter `README.md`
- lay out `.wiki/` per the [Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (delegated to [`setup-wiki`](skills/setup-wiki/))
- lay out `.tasks/` with the canonical task board (delegated to [`setup-tasks`](skills/setup-tasks/))
- register the project meta in **mappa** (wiki/task-сущности проекта; file-based `.wiki/`/`.tasks/` closed 2026-08-25)
- write `AGENTS.md` (canon) with skill triggers (`use project wiki`, `use task management system`, `check across all projects`, `we're on Windows`) plus a `CLAUDE.md` legacy pointer
- record the skill versions used in `.wiki/concepts/bootstrap-manifest.md` so cross-project layout drift stays debuggable
- record the skill versions used in a mappa wiki entity (`concepts/bootstrap-manifest`) so cross-project layout drift stays debuggable
Two modes, picked automatically: **init** for an empty folder, **upgrade**
for an existing project (the skill only fills the gaps and never overwrites

5
README.ru.md
View File

@@ -36,10 +36,9 @@ bash scripts/install.sh mappa-knowledge caveman
- инициализирует `git` (если ещё нет) и положит вменяемый `.gitignore`
- создаст стартовый `README.md`
- развернёт `.wiki/` по [паттерну Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (делегируется в [`setup-wiki`](skills/setup-wiki/))
- развернёт `.tasks/` с канонической доской задач (делегируется в [`setup-tasks`](skills/setup-tasks/))
- зарегистрирует мету проекта в **mappa** (wiki/task-сущности; файловые `.wiki/`/`.tasks/` закрыты 2026-08-25)
- запишет `AGENTS.md` (канон) со скилл-триггерами + `CLAUDE.md`-указатель (`use project wiki`, `use task management system`, `check across all projects`, `we're on Windows`)
- зафиксирует версии использованных скиллов в `.wiki/concepts/bootstrap-manifest.md`, чтобы дрифт раскладки между проектами оставался отлаживаемым
- зафиксирует версии использованных скиллов в mappa wiki-сущности `concepts/bootstrap-manifest`, чтобы дрифт раскладки оставался отлаживаемым
Два режима, выбирается автоматически: **init** для пустой папки и **upgrade**
для существующего проекта (скилл только дозаполняет пробелы и ничего не

21
skills/project-bootstrap/SKILL.md
View File

@@ -114,7 +114,7 @@ source ~/.config/projects-mcp/auth.toml 2>/dev/null || true
Get-Content ~/.config/projects-mcp/auth.toml | Select-String "base_url|token"
```
If auth file missing → stop and tell user: run `/setup-projects-meta` first.
If auth file missing → stop and tell the user (нужны Gitea-креды; скил `setup-projects-meta` удалён 2026-08-25).
### Validate project name
@@ -398,11 +398,12 @@ recommend, don't menu
we're on Windows
```
The `check across all projects` line activates the `using-projects-meta` skill
so cross-project task aggregation and the shared `projects-wiki` are available
without an explicit verbal trigger. The skill is a no-op until the
`projects-meta-mcp` server is registered — install via `setup-projects-meta`
on a fresh machine if `mcp__projects-meta__*` tools are missing.
The `check across all projects` trigger activates the **mappa** tooling
(`mcp__mappa__*`) — cross-project boards, shared wiki and the project
registry live in mappa. The file-based `projects-meta-mcp` and its skills
(`using-projects-meta`, `setup-projects-meta`, `meta-host-routing`, `setup-wiki`,
`setup-tasks`) were removed 2026-08-25; the shared `projects-wiki` files are
stubs «не читать, не править» — канон mappa shared-scope.
The `pull remote before work` line activates the `pulling-before-work` skill,
which runs one `git pull --ff-only` at session start (and on explicit re-sync
@@ -515,7 +516,7 @@ Mismatch between template and map → silent gaps in the recommendation.
| `talk like a caveman` | `caveman` | skill | `~/.claude/skills/caveman/SKILL.md` | `bash scripts/install.sh caveman` |
| `use project wiki` | `using-wiki` | skill | `~/.claude/skills/using-wiki/SKILL.md` | `bash scripts/install.sh using-wiki` |
| `use task management system` | `using-tasks` | skill | `~/.claude/skills/using-tasks/SKILL.md` | `bash scripts/install.sh using-tasks` |
| `check across all projects` | `using-projects-meta` | skill | `~/.claude/skills/using-projects-meta/SKILL.md` | `bash scripts/install.sh using-projects-meta` |
| `check across all projects` | mappa (`mcp__mappa__*`) | MCP | `mcpServers.mappa` in `~/.claude.json` | — |
| `pull remote before work` | `pulling-before-work` | skill | `~/.claude/skills/pulling-before-work/SKILL.md` | `bash scripts/install.sh pulling-before-work` |
| `session handoff: read on start, write on end` | `session-handoff` | skill | `~/.claude/skills/session-handoff/SKILL.md` | `bash scripts/install.sh session-handoff` |
| `follow project discipline` | `project-discipline` | skill | `~/.claude/skills/project-discipline/SKILL.md` | `bash scripts/install.sh project-discipline` |
@@ -734,10 +735,10 @@ Remote: <Gitea URL>
---
## Step 8 — projects-meta sync (greenfield-full mode)
## Step 8 — mappa registry (greenfield-full mode)
Only in **greenfield-full** mode. Re-sync the projects-meta cache so the new
project becomes visible to `mcp__projects-meta__*` tools.
Only in **greenfield-full** mode. Register the new project in mappa
(`mcp__mappa__projects_register`) so it becomes visible in the registry.
```bash
# POSIX:

93
skills/setup-projects-meta/README.md
View File

@@ -1,93 +0,0 @@
# setup-projects-meta
One-time skill that brings up the local `projects-meta-mcp` stdio server on a
new (or freshly broken) machine. Clones the server repo, builds it, writes
`~/.config/projects-mcp/auth.toml` with the user's Gitea token, clones the
shared wiki to `~/projects/.wiki`, and registers `mcpServers.projects-meta`
in `~/.claude.json`.
The runtime policy for *using* the resulting tools lives in
[`using-projects-meta`](../using-projects-meta/) — `setup-projects-meta` is the
only place that touches user-level config or installs the server.
`projects-meta-mcp` reference (full):
`mcp__projects-meta__knowledge_get slug=packages/projects-meta-mcp`
## When it triggers
- User says: "install projects-meta", "set up projects-meta", "configure projects-meta",
"настрой projects-meta", "установи projects-meta", "projects-meta не работает",
"projects-meta isn't working".
- [`using-projects-meta`](../using-projects-meta/) detects missing
`mcp__projects-meta__*` tools and delegates here via its Prerequisites
section.
- A new machine in the multi-machine fleet — install once per machine.
## What it installs
| Path | Role |
|---|---|
| `~/projects/.common/lib/projects-meta-mcp/` | server repo (cloned from Gitea) |
| `~/projects/.common/lib/projects-meta-mcp/dist/server.js` | built stdio entry point |
| `~/.config/projects-mcp/auth.toml` | Gitea credentials (token-bearing) |
| `~/.cache/projects-mcp/tasks.json` | aggregated tasks cache |
| `~/projects/.wiki/` | shared wiki clone (Gitea repo `projects-wiki`, content in root) |
| `~/.claude.json` (`mcpServers.projects-meta`) | MCP registration |
## Hard rules
- **Never auto-mutate.** Phase 1 (discovery) and Phase 2 (plan) always pause
for explicit confirmation. A trigger phrase grants permission to inspect,
not to clone or write secrets.
- **Never echo the Gitea token in chat.** Edit / Write tool calls inevitably
contain it (that's how it lands in `auth.toml`); chat output must not.
- **Never clone over an unrelated `~/projects/.wiki/`.**
If it exists with a non-matching `origin`, stop and ask — the user
may have an unrelated wiki there.
- **Always `chmod 600` `auth.toml` on Linux / macOS.** Token leak otherwise.
## Procedure (high-level)
1. **Phase 0** — environment sanity (Node ≥ 18, git, npm, network to Gitea).
2. **Phase 1** — discovery (token / repo / wiki clone / MCP registration / cache).
3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
4. **Phase 3** — backup (`~/.claude.json`, existing `auth.toml`).
5. **Phase 4** — clone / pull repo + `npm install && npm run build`; clone
shared wiki if absent.
6. **Phase 5** — write `~/.config/projects-mcp/auth.toml` with `gitea_token`.
7. **Phase 6** — register `mcpServers.projects-meta` in `~/.claude.json` with
absolute path to `dist/server.js`.
8. **Phase 7** — smoke test (`mcp__projects-meta__meta_status`) + `node dist/sync.js`
to populate the cache.
9. **Phase 8** — restart guidance + final report.
Full procedure with shell snippets and templates lives in [`SKILL.md`](SKILL.md).
## Rollback
1. Stop. Don't fix forward.
2. `cp <file>.bak-<ts> <file>` for `~/.claude.json` and `~/.config/projects-mcp/auth.toml`.
3. Optional: `rm -rf ~/projects/.common/lib/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`.
Keep `~/projects/.wiki/` — it's a useful clone regardless of MCP state.
4. Restart Claude Code.
5. Confirm `mcp__projects-meta__*` tools are gone (or back to the prior version).
## Install
From the repo root:
```bash
bash scripts/install.sh setup-projects-meta
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`using-projects-meta`](../using-projects-meta/) — runtime policy for
cross-project task aggregation and shared-wiki query / ingest.
- [`setup-context7`](../setup-context7/) — companion pattern for the context7
MCP plugin (similar 8-phase shape).
- Per-project вики/таски живут в mappa (мета в сервисе, решения 14/15) —
setup-скилов `.wiki/`/`.tasks/` больше нет; операции — `using-wiki` /
`using-tasks`.

244
skills/setup-projects-meta/SKILL.md
View File

@@ -1,244 +0,0 @@
---
name: setup-projects-meta
author: ours
version: 1.1.0
description: Installs and configures the local `projects-meta-mcp` stdio server — clones the repo to `~/projects/.common/lib/projects-meta-mcp`, builds it, writes `~/.config/projects-mcp/auth.toml` with the user's Gitea token, clones the shared wiki to `~/projects/.wiki/` (content lives in root), and registers `mcpServers.projects-meta` in `~/.claude.json`. Use this skill when the user says "install projects-meta", "set up projects-meta", "configure projects-meta", "настрой projects-meta", "установи projects-meta", "projects-meta не работает", "projects-meta isn't working", or whenever the `mcp__projects-meta__*` tools are missing in a session that needs cross-project task aggregation or the shared Gitea wiki. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write.
---
# setup-projects-meta
> One-time skill that gets the local `projects-meta-mcp` server running with the user's Gitea credentials. Stops at confirmation gates because the procedure clones a repo, writes a secret-bearing TOML file, and edits `~/.claude.json`.
Reference: full `projects-meta-mcp` docs live in the shared wiki at `packages/projects-meta-mcp` (fetch via `mcp__projects-meta__knowledge_get` once the server is up).
## When to use
- User explicitly asks: install / set up / configure projects-meta.
- A `using-projects-meta`-driven task fails because `mcp__projects-meta__*` tools aren't available.
- Migrating a stale install (token expired, repo moved, broken cache) — same procedure, Phase 1 detects what's already in place.
- New machine in the user's multi-machine fleet (recall: this is a cross-machine workflow).
## Out of scope
- Issuing or rotating Gitea tokens. This skill *uses* a token the user already has; if there's no token, point them at Gitea's settings page (`https://git.kzntsv.site/user/settings/applications`) and stop until they paste one.
- Running `projects-meta-mcp` itself (the MCP harness spawns it).
- Editing `.tasks/STATUS.md` or wiki content — that's `using-projects-meta` / `using-tasks` / `using-wiki`.
- Any other MCP server.
## Hard rule: don't auto-mutate config
The procedure clones a repo, writes `~/.config/projects-mcp/auth.toml` (carries the Gitea token), and edits `~/.claude.json`. **Always pause for explicit confirmation between Phase 1 (discovery, read-only) and Phase 2 (plan), and again before Phase 3 (backup + writes).** A trigger phrase is permission to run discovery, not permission to clone or write secrets.
## Procedure
### Phase 0 — Environment sanity
- Confirm Claude Code is the current harness (need `mcpServers` registration in `~/.claude.json`).
- Confirm `git`, `node`, `npm` are on `PATH`. Node ≥ 18 (the server uses ES modules).
- Confirm network reachability to `https://git.kzntsv.site` (the Gitea host). On HTTP 401/403 later, the token is dead — stop and ask for a new one.
- Pick paths: `~/projects/.common/lib/projects-meta-mcp`, `~/.config/projects-mcp/`, `~/.cache/projects-mcp/`, `~/projects/.wiki/` (shared wiki clone). POSIX-style `~/...` resolves correctly under git-bash on Windows.
### Phase 1 — Discovery (read-only)
Search, in order. Report only "found at <path>", never echo token values.
**Existing Gitea token.** Look in priority order:
1. `~/.config/projects-mcp/auth.toml` → `gitea_token = "..."`
2. Env var `PROJECTS_META_GITEA_TOKEN`
3. Existing `~/.claude.json` → `mcpServers.projects-meta` block (rare; legacy installs sometimes inline `env.GITEA_TOKEN`)
The first hit wins. Capture internally for Phase 5; **never echo it in chat**.
**Repo install state.** Check whether `~/projects/.common/lib/projects-meta-mcp/.git` exists. If yes, `git -C ~/projects/.common/lib/projects-meta-mcp rev-parse HEAD` → record the SHA so Phase 4 can decide *clone* vs *pull*.
**Build artifact.** Check `~/projects/.common/lib/projects-meta-mcp/dist/server.js`. If absent, Phase 4 will run `npm install && npm run build`.
**Shared wiki clone.** Check if `~/projects/.wiki/.git` exists and `origin` matches `https://git.kzntsv.site/OpeItcLoc03/projects-wiki(.git)?`. If non-matching `origin`, stop and ask — the user may have an unrelated wiki there.
**MCP registration.** Read `~/.claude.json` and check `mcpServers.projects-meta`. Note the command + args. If args point at a stale path, Phase 6 will fix it.
**Cache state.** List `~/.cache/projects-mcp/` (if it exists). Just for the report — don't rely on it.
### Phase 2 — Plan + confirm
Present a single-block plan to the user:
```
Token: <found at <path> | NOT FOUND — will ask>
Repo: <installed at ~/projects/.common/lib/projects-meta-mcp@<sha> | will clone>
Build artifact: <present | will run npm install && npm run build>
Wiki clone: <present at ~/projects/.wiki | will clone | wrong remote — STOP>
MCP entry: <present in ~/.claude.json | will add | will fix path>
Backups: ~/.claude.json.bak-<ts>, ~/.config/projects-mcp/auth.toml.bak-<ts> (if exists)
```
Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.
If no token was found in Phase 1 — first ask: "Paste a Gitea personal access token (scope: `read:repository` for read-only, `write:repository` to enable mutations), or open `https://git.kzntsv.site/user/settings/applications` to create one." Don't proceed past Phase 2 without a token.
### Phase 3 — Backup
Copy each file we will modify to `<file>.bak-YYYYMMDD-HHMMSS`:
```bash
TS=$(date +%Y%m%d-%H%M%S)
[ -f ~/.claude.json ] && cp ~/.claude.json ~/.claude.json.bak-$TS
[ -f ~/.config/projects-mcp/auth.toml ] && cp ~/.config/projects-mcp/auth.toml ~/.config/projects-mcp/auth.toml.bak-$TS
```
Confirm both backups exist (when their source existed) before any further edit. The repo and wiki clones don't need backup — git is the backup.
### Phase 4 — Clone + build
```bash
# Server
if [ -d ~/projects/.common/lib/projects-meta-mcp/.git ]; then
git -C ~/projects/.common/lib/projects-meta-mcp pull --ff-only
else
git clone https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp ~/projects/.common/lib/projects-meta-mcp
fi
cd ~/projects/.common/lib/projects-meta-mcp
npm install
npm run build
# Shared wiki
mkdir -p ~/projects
if [ -d ~/projects/.wiki/.git ]; then
git -C ~/projects/.wiki pull --ff-only
else
git clone https://git.kzntsv.site/OpeItcLoc03/projects-wiki ~/projects/.wiki
fi
```
Verify `~/projects/.common/lib/projects-meta-mcp/dist/server.js` exists after build. If not — abort, the build failed; ask the user to run `npm run build` manually and paste the output.
### Phase 5 — Write `auth.toml`
```bash
mkdir -p ~/.config/projects-mcp
```
If `~/.config/projects-mcp/auth.toml` already exists and Phase 1 found a valid `gitea_token` line — skip the write. Otherwise, write the file with the token captured in Phase 1 (or freshly pasted in Phase 2):
```toml
gitea_url = "https://git.kzntsv.site"
gitea_user = "OpeItcLoc03" # acting identity (commit author)
gitea_token = "<TOKEN>"
gitea_owners = ["victor", "cancel_music"] # additional Gitea owners to sync
agenda_tasks_repo = "OpeItcLoc03/agenda" # cross-project meta-board (qualified)
# gitea_aggregate_skip_owners = ["OpeItcLoc03"] # opt: sync but hide from `tasks_aggregate`
```
**Schema notes (v2.x server):**
- `gitea_owners` is an array of owners whose repos are scanned by `sync.js` and surfaced in aggregation views. `gitea_user` is acting identity only (commit author footer), not necessarily aggregated.
- `agenda_tasks_repo` is **qualified** (`<owner>/<repo>`). The literal `agenda` in `target_project` resolves through this field.
- `gitea_aggregate_skip_owners` (optional, v2.2.0+) — visited by sync (so mutations work via cache lookup) but hidden from `tasks_aggregate` / `tasks_search`. Useful for keeping infra repos write-able without polluting the dashboard.
- Backwards-compat: legacy installs with only `gitea_user = "X"` and no `gitea_owners` → server reads as `gitea_owners = ["X"]`.
- Legacy `meta_tasks_repo` / `meta_wiki_repo` → renamed to `agenda_tasks_repo` / built-in `projects-wiki`. Old keys ignored on v2.x.
Permissions: on Linux / macOS run `chmod 600 ~/.config/projects-mcp/auth.toml`. On Windows the default ACL is per-user, no extra step.
### Phase 6 — Register in `~/.claude.json`
Edit `~/.claude.json`. Add or update the `mcpServers.projects-meta` block:
```json
{
"mcpServers": {
"projects-meta": {
"command": "node",
"args": ["<ABSOLUTE_PATH_TO>/dist/server.js"]
}
}
}
```
Absolute path resolution:
| Platform | `<ABSOLUTE_PATH_TO>` |
|---|---|
| Windows | `C:/Users/<USER>/projects/.common/lib/projects-meta-mcp` (forward slashes; works in JSON without escaping) |
| Linux | `/home/<USER>/projects/.common/lib/projects-meta-mcp` |
| macOS | `/Users/<USER>/projects/.common/lib/projects-meta-mcp` |
After each edit, validate JSON:
```bash
# Windows (git-bash)
powershell.exe -NoProfile -c "Get-Content '<file>' -Raw | ConvertFrom-Json | Out-Null"
# Linux / macOS
jq empty <file>
# fallback
python -c "import json; json.load(open('<file>'))"
```
If validation fails → restore from `.bak-*` and abort.
### Phase 7 — Smoke test (best-effort) + run initial sync
Best-effort: call `mcp__projects-meta__meta_status`. If it returns a JSON blob with `synced_at` / `wiki_pages_count` — the server is reachable in *this* session.
Then run a one-shot sync to populate the cache:
```bash
cd ~/projects/.common/lib/projects-meta-mcp
node dist/sync.js
```
Expect a non-zero `projects_count` and a fresh `~/.cache/projects-mcp/tasks.json`. On 401 / 403 → token is wrong scope or expired; rotate via `https://git.kzntsv.site/user/settings/applications` and re-edit `auth.toml`.
**Important caveat to relay to the user:** in the *same* session that just ran setup, the MCP server you're talking to is whatever was bound at session start. So a passing `meta_status` only proves "some projects-meta is alive" — not "the registration we just wrote is what's serving it". The real test is after Claude Code restart.
### Phase 8 — Restart guidance + final report
Tell the user:
```
✅ Setup complete. Restart Claude Code so the new mcpServers.projects-meta
registration binds to a fresh stdio session.
After restart:
• mcp__projects-meta__* tools serve from ~/projects/.common/lib/projects-meta-mcp/dist/server.js
• Cache lives at ~/.cache/projects-mcp/tasks.json (refresh: node dist/sync.js)
• Shared wiki clone at ~/projects/.wiki/ — `git -C ~/projects/.wiki pull --ff-only` for fresh anchors
• Backups saved at ~/.claude.json.bak-<ts> (and auth.toml.bak-<ts> if it existed before)
If something breaks after restart:
• Restore from .bak-* and tell me — we'll roll back together.
```
## Rollback procedure
If a problem surfaces (now or after restart):
1. Stop. Don't try to fix forward.
2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to `~/.claude.json` (and `~/.config/projects-mcp/auth.toml` if applicable).
3. `cp <file>.bak-<ts> <file>` for each.
4. Optional: `rm -rf ~/projects/.common/lib/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`. Keep `~/projects/.wiki/` — it's a useful clone regardless of MCP state.
5. Restart Claude Code.
6. Confirm `mcp__projects-meta__*` is gone (or back to the pre-existing version).
7. Report what went wrong so we can fix the procedure.
## Cross-platform notes
The procedure is platform-agnostic. Only auxiliary tooling differs:
| | JSON validate | Backup | Permissions on auth.toml |
|---|---|---|---|
| Windows (git-bash) | `powershell.exe -NoProfile -c "Get-Content '<f>' -Raw \| ConvertFrom-Json \| Out-Null"` | `cp` | per-user ACL by default |
| Linux | `jq empty <f>` (or `python -c "import json; json.load(open('<f>'))"`) | `cp` | `chmod 600` |
| macOS | same as Linux | `cp` | `chmod 600` |
Path forms (`~/.local/...`, `~/.config/...`, `~/projects/...`) are identical on all three.
## Common mistakes
- **Skipping Phase 1.** "User just said 'install projects-meta' — let's go." No — find existing token / repo / wiki first; re-cloning over an existing install loses any local commits in the wiki.
- **Echoing the token.** It's a secret. Edit / Write tool calls inevitably contain it (that's how it gets into `auth.toml`), but no chat output should.
- **Cloning over an unrelated `~/projects/.wiki/`.** If it exists with a different `origin`, stop. The user may have an unrelated wiki there.
- **Writing `auth.toml` with `0644` perms on Linux/macOS.** Token leak. Always `chmod 600` after write.
- **Treating in-session `meta_status` as proof.** Same as the context7 caveat — the active MCP connection was bound at session start.
- **Auto-running on every "use projects-meta".** This skill is intrusive. Trigger only on explicit "install/setup/configure projects-meta", or when MCP tools are missing and the user is blocked.
- **Forgetting `node dist/sync.js`.** Without an initial sync, the cache is empty and `tasks_aggregate` returns nothing — the user thinks setup failed.

9
skills/update-skills/SKILL.md
View File

@@ -85,11 +85,10 @@ setup; pi loads `~/.agents/skills` by default. Verify with `pi --help` / a fresh
The update scripts (`scripts/update.sh` and `scripts/update.ps1`) handle:
1. **git pull --ff-only** in `~/projects/skills/` (stash if dirty, pop after).
2. **Conditionally rebuild projects-meta-mcp** — if `~/projects/.common/lib/projects-meta-mcp/` has a `.git` directory and source changed (`git pull` fetched new commits), run `npm run build`.
3. **Conditionally rebuild interns-mcp** — same pattern, `pip install -e .`.
4. **Install all skills** via `install.sh` / `install.ps1`.
5. **Show version diff** — before/after `version:` frontmatter for each skill.
6. **Print reload hints** — `/reload-mcp` if MCP changed, new session otherwise.
2. **Conditionally rebuild interns-mcp** — same pattern, `pip install -e .`.
3. **Install all skills** via `install.sh` / `install.ps1`.
4. **Show version diff** — before/after `version:` frontmatter for each skill.
5. **Print reload hints** — `/reload-mcp` if MCP changed, new session otherwise.
## Out of scope

170
skills/using-projects-meta/README.md
View File

@@ -1,170 +0,0 @@
# 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` |
## Step 0 — Freshness gate (v1.1.0, mandatory pre-flight)
`projects-meta` is a bus between machines — another host may have pushed
minutes ago. Without this gate, reads return stale data and writes hit
sha-based optimistic-lock 422s with no explanation.
Before **any** `tasks_*` or `knowledge_*` call:
1. `mcp__projects-meta__meta_status` — probe cache age + errors.
2. If `cache_age_minutes` > 10 OR `errors_count` > 0 →
`node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js`.
3. For shared-wiki **writes** (`knowledge_ingest`, `knowledge_promote`) →
**also** `git -C ~/projects/projects-wiki pull --ff-only`. Unconditional.
The MCP server uses sha-based optimistic locking on the wiki repo;
without an up-to-date local SHA the commit is rejected with a 422.
4. For tasks-mutations (`tasks_create`/`update`/`close`) → sync via
`dist/sync.js` is enough; there's no local clone of the target tasks repo.
5. If sync returns **401 / 403** → STOP. Token is dead. Send the user to
`~/.config/projects-mcp/auth.toml` to rotate `gitea_token`. Don't
pretend success, don't retry silently.
**Don't sync unconditionally** on every call — overhead + 401-risk for
casual reads. The 10-minute window is the chosen threshold.
**Don't apply Step 0 to `meta_status` itself** — it's the probe.
## 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` → `summaries/<slug>.md` |
`type` ∈ `entities` / `concepts` / `packages` / `summaries` / `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 `~/projects/.common/lib/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.

238
skills/using-projects-meta/SKILL.md
View File

@@ -1,238 +0,0 @@
---
name: using-projects-meta
author: ours
version: 1.3.0
description: Use when working across multiple projects on one or many machines — cross-project task aggregation (`mcp__projects-meta__tasks_*`), shared Gitea-backed wiki query / ingest (`mcp__projects-meta__knowledge_*`), or sync diagnostics (`mcp__projects-meta__meta_status`). Triggers on phrases like "across all projects", "what's on the boards", "check shared wiki", "search projects-wiki", "ingest into shared wiki", "что у меня на досках", "по всем проектам", "общая вики", "cross-project status", or any time the user wants to see / mutate state in another repo than the current cwd. v1.1.0 mandates a Step 0 freshness gate (probe `meta_status`, sync if stale, pull `projects-wiki` before shared-wiki writes) — see SKILL body. Mutation tools require two-step preview → confirm. Skip for the **current** project's tasks/wiki — those live on disk in `.tasks/` / `.wiki/`.
---
# Using the projects-meta MCP server
## Overview
`projects-meta-mcp` is a local stdio MCP server. Two responsibilities:
1. **Cross-project task aggregation** — parses `.tasks/STATUS.md` from every repo on the user's Gitea, caches them in `~/.cache/projects-mcp/tasks.json`. Read tools (`tasks_aggregate`, `tasks_search`, `tasks_get`) hit the cache. Mutations (`tasks_create`, `tasks_update`, `tasks_close`) commit back to Gitea with sha-based optimistic lock.
2. **Shared knowledge wiki** — single Gitea repo (`projects-wiki`) cloned at `~/projects/projects-wiki/` with content at `~/projects/projects-wiki/.wiki/`, structured as packages / concepts / entities / summaries / raw. `knowledge_search` + `knowledge_get` for queries, `knowledge_ingest` + `knowledge_promote` for writes.
Source of truth: Gitea (`https://git.kzntsv.site`, owner `OpeItcLoc03`). Cache and clone are local convenience.
Full reference: `mcp__projects-meta__knowledge_get slug=packages/projects-meta-mcp`.
## Prerequisites
This skill assumes `mcp__projects-meta__*` tools are available. If they aren't (tools missing from the session, or calls fail with a connection error), the server isn't running for this session. Trigger the **`setup-projects-meta`** skill to clone, build, write `auth.toml`, and register `mcpServers.projects-meta` in `~/.claude.json`. It's a one-time procedure with confirmation gates.
## Local-first rule
**For the current project — read disk directly.** `.tasks/STATUS.md` and `.wiki/` files in cwd are always fresher than the MCP cache. The cache:
- May be stale (default sync runs only when triggered).
- Hides 🟢 done by default.
- May not contain locally-developed projects that aren't pushed to Gitea yet.
Use MCP only for **other** projects, **other** machines, or **shared** wiki content.
| 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 a page on X?" | local `.wiki/index.md` + relevant file |
| "Has the **shared** wiki got a page on X?" | `mcp__projects-meta__knowledge_search` |
| "Sync state across machines?" | `mcp__projects-meta__meta_status` |
## When to use
- Cross-project task overview ("what am I working on across projects", "по всем проектам", "across the board").
- Hopping into another repo's task state without cloning it ("what's the status of project X").
- Querying the shared wiki for cross-cutting concepts (patterns, package references, design notes that apply to several repos).
- Ingesting a finished design / decision into the shared wiki so other machines / projects can see it.
- Creating a task in another project's `.tasks/STATUS.md` from the current repo (cross-project handoff).
- Sync diagnostics (when did the cache last refresh, are there errors, how many projects).
## When NOT to use
- The current project's own tasks or wiki — read disk.
- Anything inside a single project — `.tasks/<task>.md` and `.wiki/<page>.md` are always closer.
- One-off questions answered by `git log` or a single file.
- Library / framework documentation — that's `using-context7`.
- Code search — that's `Glob` / `Grep`.
## Step 0 — Freshness gate (run before any tool)
`projects-meta` is a bus between machines. Another host may have pushed minutes ago. Without this gate, reads return stale data and writes hit sha-based optimistic-lock 422s with no explanation. Mandatory pre-flight, every session, every workflow:
```
1. Call mcp__projects-meta__meta_status.
2. Branch on cache freshness:
• If cache_age_minutes > 10 OR errors_count > 0:
run `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js`
(or `npm run sync` from ~/projects/.common/lib/projects-meta-mcp).
• Else: cache is fresh enough — skip sync, no need to hit the network.
3. For shared-wiki WRITES (knowledge_ingest, knowledge_promote):
ALWAYS additionally run `git -C ~/projects/projects-wiki pull --ff-only`
regardless of cache age. The MCP server uses sha-based optimistic locking;
without an up-to-date local file SHA, the commit will be rejected (422)
and the failure mode is opaque to the user.
4. For tasks-mutations (tasks_create, tasks_update, tasks_close):
sync via dist/sync.js is enough — there's no local clone of the target
tasks repo, mutations go straight through Gitea API. Sync only refreshes
the local view so you reason from current state.
5. If sync returns 401 or 403:
STOP. The Gitea token in ~/.config/projects-mcp/auth.toml is dead or
wrong-scoped. Tell the user explicitly:
"Gitea sync failed with <401|403>. Rotate gitea_token in
~/.config/projects-mcp/auth.toml (Gitea: settings/applications)
and rerun."
Do not pretend sync succeeded. Do not retry silently.
```
**Don't sync unconditionally on every call.** Network overhead + risk of 401 even on a casual "what's on my boards". The 10-minute cache window is the right balance — catches multi-machine drift without burning Gitea round-trips for back-to-back questions.
**Don't apply Step 0 to `meta_status` itself** — it's the freshness probe, not a downstream read.
## Workflow
### Read (no confirmation needed)
```
0. Run Step 0 — Freshness gate (above) first.
1. Identify what you need: cross-project tasks? shared wiki page? sync state?
2. Pick the right read tool (table below).
3. Cite the result with the source slug / project name.
```
### Mutate (always two-step)
```
0. Run Step 0 — Freshness gate (above) first.
For shared-wiki writes (knowledge_ingest, knowledge_promote): unconditional
`git -C ~/projects/projects-wiki pull --ff-only` is part of Step 0.
1. Identify the mutation: tasks_create / tasks_update / tasks_close / knowledge_ingest / knowledge_promote.
2. Call the tool WITHOUT `confirm: true` → returns a dry-run preview (the proposed file diff and the Gitea commit message).
3. Show the preview to the user. Wait for explicit "ok" / "go" / "поехали".
4. Re-call with `confirm: true` to commit.
```
**Never inline `confirm: true` on the first call.** A trigger phrase ("create a task in project X") is permission to *plan*, not to *commit*.
## Tool quick reference
### Read tools
| Tool | Required args | Purpose |
|---|---|---|
| `mcp__projects-meta__tasks_aggregate` | — | All active tasks across all 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 (cached snapshot) |
| `mcp__projects-meta__knowledge_search` | `query`; opt `domain`, `limit` | Shared-wiki search; auto-detects domain from cwd, pass `domain="all"` to disable |
| `mcp__projects-meta__knowledge_get` | `slug` | Full text of one wiki page (e.g. `packages/projects-meta-mcp`) |
| `mcp__projects-meta__knowledge_suggest_promote` | — | Local `.wiki/concepts/` candidates for shared-wiki promotion |
| `mcp__projects-meta__meta_status` | — | Sync diagnostics: cache age, project count, error count, page count |
### Mutation tools (need `write:repository` Gitea scope; preview → confirm)
| Tool | Required args | Effect |
|---|---|---|
| `mcp__projects-meta__tasks_create` | `target_project`, `slug`, `description`, `next_action` (+ opt `where_stopped`, `status`, `blocker`, `branch`, `source_project`) | Append block to `<target>/.tasks/STATUS.md` via Gitea commit |
| `mcp__projects-meta__tasks_update` | `target_project`, `slug` + ≥1 of `where_stopped` / `next_action` / `blocker` / `branch` / `description` / `status` | Sha-based optimistic lock; 422 on conflict |
| `mcp__projects-meta__tasks_close` | `target_project`, `slug` (+ opt `note`) | Sets task to 🟢 done; appends identity-footer |
| `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Three commits: `<type>/<slug>.md` + `index.md` + `log.md`. `type` ∈ entities / concepts / packages / summaries / raw |
| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Move `raw/<slug>.md` → `summaries/<slug>.md` with auto `raw_path` link |
`target_project` is **qualified** `<owner>/<repo>` (e.g. `victor/books`, `OpeItcLoc03/skills`), or the literal `agenda` for the cross-project meta-board (resolves via `agenda_tasks_repo` in `auth.toml`). Bare names (`books`) are rejected with a hint to use the qualified form. Cross-cutting design: shared wiki → `concepts/projects-meta-multi-owner`.
## Examples
### Read example: cross-project status
User: "что у меня на досках?"
```
1. mcp__projects-meta__tasks_aggregate
→ 7 projects, 12 active tasks
2. Group by project, summarize 1 line per active task.
Cite project name; if a task is stale (cache age > 1h), flag it.
```
### Read example: shared wiki query
User: "есть ли в общей вики что-то про setup-using паттерн?"
```
1. mcp__projects-meta__knowledge_search
query: "setup-using skill pair pattern"
domain: "all"
→ hits include concepts/setup-using-skill-pair
2. mcp__projects-meta__knowledge_get
slug: "concepts/setup-using-skill-pair"
→ full text
3. Summarize, link with markdown to the slug.
```
### Mutation example: create cross-project task
User: "заведи в проекте books задачу на миграцию `settings.json`"
```
1. mcp__projects-meta__tasks_create
target_project: "victor/books"
slug: "settings-json-migration"
description: "<...>"
next_action: "<...>"
(no `confirm`)
→ preview: proposed STATUS.md diff + commit message
2. Show preview to user.
3. User: "ok, go"
4. mcp__projects-meta__tasks_create
(same args + confirm: true)
→ committed to Gitea
```
### Mutation example: closing a cross-project task
User: "close `[projects-meta-skills]` in skills"
```
1. mcp__projects-meta__tasks_close
target_project: "OpeItcLoc03/skills"
slug: "projects-meta-skills"
note: "<one-line summary>"
(no `confirm`)
→ preview
2. User confirms.
3. Re-call with confirm: true.
```
## Common mistakes
| Mistake | Fix |
|---|---|
| Reading current project's tasks via `tasks_get` instead of disk | Read `.tasks/STATUS.md` directly. MCP is for *other* projects. |
| Inlining `confirm: true` on the first mutation call | Always preview first; show user; only then `confirm: true`. |
| Using `knowledge_search` for the project's own wiki | The shared wiki is a separate Gitea repo. Local `.wiki/` is in cwd. |
| Acting on a stale `tasks_aggregate` without checking `meta_status` | Step 0 — Freshness gate is mandatory. If `cache_age_minutes` > 10 (or errors > 0), run `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js` first. |
| Skipping `git -C ~/projects/projects-wiki pull` before `knowledge_ingest` / `knowledge_promote` | sha-based optimistic lock will reject the commit (422) and the failure is opaque. Pull is unconditional for shared-wiki writes — fast-forward is a no-op when current. |
| Treating sync 401/403 as "MCP is fine, the page just doesn't exist yet" | 401/403 means the Gitea token is dead. Stop, tell the user to rotate `gitea_token` in `~/.config/projects-mcp/auth.toml`. Never guess on stale data. |
| Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `summaries` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. |
| Vague `knowledge_search` queries ("auth", "config") | Specific multi-word queries return targeted snippets; vague ones return noise. |
| Forgetting `domain="all"` when searching across families | Default `domain` is auto-detected from cwd; use `"all"` if the wiki page lives in a different family. |
| Passing bare project name (`target_project: "books"`) to mutation tools | v2.x rejects bare names. Use qualified `<owner>/<repo>` (e.g. `victor/books`, `OpeItcLoc03/skills`). Literal `agenda` is the only exception (cross-project meta-board). |
## Red flags
- "I'll just commit it directly" → no. Mutation tools have a preview step for a reason — silent writes to another repo are a recipe for drift.
- "The cache is fresh enough" → run Step 0. The 10-minute window is the threshold; below it skip sync, above it sync. Don't eyeball this — the bus moves fast in cross-machine sessions.
- "I'll skip the pull, my last write was 30 seconds ago" → another machine pushed in between. Always pull before shared-wiki writes; the sha-lock check is your only safety net.
- "I'll skip the wiki page" → if you're answering a cross-cutting question and there's no wiki page, that's a `knowledge_ingest` candidate. Surface it to the user.