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

feat(hermes): mvp-coverage — 9 skills converted to Hermes format

Browse Source 
- mapping.yaml: 7 pending → auto (setup-tasks, using-tasks, setup-wiki,
  using-wiki, using-projects-meta, using-context7, project-bootstrap,
  recommend-dont-menu). pending count now 0.

- dist-hermes/ populated:
  software-development: project-bootstrap (+ assets)
  productivity: recommend-dont-menu, setup-tasks, using-tasks
  research: setup-wiki, using-wiki
  mcp: using-context7, using-projects-meta

- active-platform replace-rule verified: Windows+PowerShell → Linux+bash
  in body SKILL.md (frontmatter description unchanged by design).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
vitya
2026-05-07 09:21:56 +03:00
parent 27026c5e0e
commit 82f82a2036
19 changed files with 2738 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
dist-hermes/SKIPPED.md
View File

@@ -16,11 +16,4 @@ Do not edit by hand — edit the mapping and re-run the build.
## Pending (deferred to follow-up tasks)
- **project-bootstrap** — Pending hermes-mvp-coverage. Orchestrator — adapts last; CLAUDE.md trigger-lines drop (Hermes auto-discovers). → intended: `mode: auto, category: software-development`
- **recommend-dont-menu** — Added 2026-05-06 after the original audit. Cross-agent applicability claimed (response-style rule) — Hermes-side audit not yet done. → intended: `mode: auto, category: productivity`
- **setup-tasks** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: productivity`
- **setup-wiki** — Pending hermes-mvp-coverage. Hermes ships research/llm-wiki — our schema is preserved via override-precedence. → intended: `mode: auto, category: research`
- **using-context7** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: mcp`
- **using-projects-meta** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: mcp`
- **using-tasks** — Pending hermes-mvp-coverage. → intended: `mode: auto, category: productivity`
- **using-wiki** — Pending hermes-mvp-coverage. Hermes ships research/llm-wiki — our schema is preserved via override-precedence. → intended: `mode: auto, category: research`
(none)

119
dist-hermes/mcp/using-context7/SKILL.md Normal file
View File

@@ -0,0 +1,119 @@
---
name: using-context7
version: 1.0.0
description: Use when answering questions about a specific library, framework, SDK, API, or CLI tool — including setup/install, config, API syntax, version-specific behavior, migration between versions, or library-specific errors. Training data is often stale; context7 returns current docs. Skip for general programming concepts, refactoring, business-logic debugging, or when the codebase already answers the question.
---
# Using the context7 MCP server
## Overview
`context7` is an MCP server that fetches **current** documentation for named libraries and frameworks. Two tools: `mcp__context7__resolve-library-id` (name → library ID) and `mcp__context7__query-docs` (library ID + question → doc snippets).
Your training data has a cutoff. Library APIs change. If a question names a library, **reach for context7 before answering from memory**, even for libraries you "know" — your recall may be one or two majors behind.
## Prerequisites
This skill assumes `mcp__context7__resolve-library-id` and `mcp__context7__query-docs` are available. If they aren't (the tools are missing from the session, or calls fail with a connection error), the context7 MCP server isn't running for this session. Trigger the **`setup-context7`** skill to install/configure the official plugin (`context7@claude-plugins-official`) and inject the user's API key. It's a one-time procedure with confirmation gates.
## When to use
Use when the user asks about any of these in the context of a specific library:
- Install / setup / init commands
- Config file shape (`nuxt.config.ts`, `next.config.mjs`, `tsconfig.json` extends, `vite.config`, etc.)
- API / component / hook / composable syntax
- Migration between versions (v3 → v4, v14 → v15)
- Library-specific errors / warnings
- CLI flags
- Feature availability ("does X support Y?")
- Plugin / module ecosystem questions
Common triggers: "how do I …", "what's the right way to … in <lib>", "is there a <lib> way to …", any error message containing a library's name, any config file snippet.
**Prefer context7 over WebSearch / WebFetch for library docs** — it returns curated snippets, not rendered marketing pages.
## When NOT to use
- General programming concepts (closures, concurrency, algorithms)
- Refactoring / code review / business-logic debugging
- Writing new code from scratch where the stack isn't named
- Questions the current codebase answers (read the repo first)
- Your own prior-conversation context (use wiki / memory instead)
## Workflow
```
1. Identify the library (and version, if the user mentioned one)
2. resolve-library-id → pick best match by name + reputation + snippet count
3. query-docs with the ID + a specific question
4. Cite what you found; fall back only if context7 returned nothing useful
```
**Budget: 3 calls per question, max.** After 3, use what you have — don't loop.
If the user already gave a library ID in `/org/project` or `/org/project/version` form, skip step 2 and go straight to `query-docs`.
## Tool quick reference
| Tool | Required args | Purpose |
|---|---|---|
| `mcp__context7__resolve-library-id` | `libraryName`, `query` | Name → `/org/project` ID. Use official casing ("Next.js", not "nextjs"). |
| `mcp__context7__query-docs` | `libraryId`, `query` | ID → doc snippets. `query` must be specific. |
Library ID format: `/org/project` (e.g. `/vercel/next.js`) or `/org/project/version` (e.g. `/vercel/next.js/v14.3.0`).
## Good vs bad queries
**`resolve-library-id` — pick official names:**
```
libraryName: "Nuxt" query: "Nuxt 4 config and route rules" ✅
libraryName: "nuxt4" query: "nuxt" ❌ (wrong casing, vague query)
```
**`query-docs` — be specific:**
```
query: "How to set up @nuxtjs/i18n with prefix_except_default and ru default locale in Nuxt 4" ✅
query: "i18n" ❌
query: "How to configure YooKassa payment provider in Medusa v2 core flows" ✅
query: "payments" ❌
```
A specific query returns targeted snippets; a vague one returns a grab bag you'll ignore.
## Example
User: "How do `routeRules` work in Nuxt 4?"
```
1. mcp__context7__resolve-library-id
libraryName: "Nuxt"
query: "Nuxt 4 routeRules hybrid rendering"
→ /nuxt/nuxt (or /nuxt/nuxt/v4.x.x if version known)
2. mcp__context7__query-docs
libraryId: "/nuxt/nuxt"
query: "routeRules for hybrid rendering: ssr, prerender, isr, swr — syntax and examples"
→ doc snippets
3. Answer using the snippets. Cite the library + version.
```
## Common mistakes
| Mistake | Fix |
|---|---|
| Answering from memory on a library question | Run `resolve-library-id` first. Your training data is stale. |
| Calling `query-docs` without resolving first | Required unless user already gave `/org/project` ID. |
| Vague queries ("auth", "hooks", "config") | Include the specific task, version, and constraints. |
| Looping until you find the "perfect" answer | 3-call hard cap. Take the best result and move on. |
| Using context7 for codebase questions | Read the code. context7 doesn't know your repo. |
| Using context7 for general concepts | Answer from training data. context7 is for libraries. |
## Red flags
- "I already know this library" → your recall may be one major behind. Resolve anyway if the user is about to act on your answer.
- "This will take too many calls" → you have 3. Use them.
- "The error message looks obvious" → error messages that include a library name are a strong context7 signal.

170
dist-hermes/mcp/using-projects-meta/README.md Normal file
View File

@@ -0,0 +1,170 @@
# 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` → `sources/<slug>.md` |
`type` ∈ `entities` / `concepts` / `packages` / `sources` / `raw`.
`target_project` = Gitea repo name, or `_meta` (meta-tasks / meta-wiki repos
from `auth.toml`).
## Common mistakes
- **Reading current project's tasks via `tasks_get`.** Read `.tasks/STATUS.md`
on disk; the MCP cache is for *other* projects.
- **Inlining `confirm: true` on first call.** Always preview first; show user;
only then `confirm: true`.
- **Confusing the local `.wiki/` with the shared `projects-wiki`.** They are
two different stores. `using-wiki` operates on the local one;
`using-projects-meta` queries / ingests the shared one.
- **Acting on stale `tasks_aggregate`.** If `meta_status.age_seconds` > 3600,
either run `node dist/sync.js` (in `~/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.

236
dist-hermes/mcp/using-projects-meta/SKILL.md Normal file
View File

@@ -0,0 +1,236 @@
---
name: using-projects-meta
version: 1.1.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 / sources / 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 / sources / raw |
| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Move `raw/<slug>.md` → `sources/<slug>.md` with auto `raw_path` link |
`target_project` is either a Gitea repo name, or `_meta` (the dedicated meta-tasks / meta-wiki repos from `auth.toml`).
## 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: "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 claude-skills"
```
1. mcp__projects-meta__tasks_close
target_project: "claude-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` / `sources` / `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. |
## 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.

32
dist-hermes/productivity/recommend-dont-menu/README.md Normal file
View File

@@ -0,0 +1,32 @@
# recommend-dont-menu
One recommendation, not a menu. When the user asks "what should we do?", give your best choice with reasoning and trade-offs — don't enumerate A/B/C/D options.
## What it does
Overrides the `superpowers:brainstorming` default of presenting multiple options. Instead, respond with:
```
Я рекомендую X, потому что Y₁, Y₂. Trade-off: Z. Возражения?
```
Only mention alternatives when they're genuinely competitive or carry an important trade-off.
## When to use
During design discussions, architecture reviews, brainstorming, or any "what should we do" question.
## Installation
```bash
bash scripts/install.sh recommend-dont-menu
```
## Trigger line
Add to `CLAUDE.md`:
```
prefer single recommendations
```
Or use `project-bootstrap` (v1.9.0+) which includes this trigger in its template.

60
dist-hermes/productivity/recommend-dont-menu/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
---
name: recommend-dont-menu
version: 0.1.0
description: >
Use during design discussions, brainstorming, architecture reviews, or any
"what should we do" question — give one argued recommendation with explicit
trade-offs, not a multiple-choice menu. Override of superpowers:brainstorming
default. Works on any agent — pure response-style rule, no tool mappings needed.
---
# recommend-dont-menu
> One recommendation, not a menu. When the user asks "what should we do?" or "which is better?", give your best choice with reasoning and trade-offs. Don't enumerate A/B/C/D options — menus slow down decision-making when one option is clearly better.
## When this runs
**At session start** — when `CLAUDE.md` contains any trigger line:
- `prefer single recommendations`
- `recommend, don't menu`
- `argued recommendations`
- `give me your best shot`
**On explicit reference** — when user says "give me a recommendation", "don't menu", "what do you think?", or close variants.
## Default mode
For design questions, architecture choices, "what should we do" queries:
```
Я рекомендую X, потому что Y₁, Y₂. Trade-off: Z. Возражения?
```
**Only mention alternatives if:**
- They're genuinely close to the recommended option, OR
- They carry an important trade-off the user should weigh
Then, briefly:
```
Если важно W — лучше X', но добавляет сложность; иначе X.
```
**Don't enumerate options** for the sake of appearing comprehensive. Menus are noise when one option dominates — they force the user to read through losing choices and bury your reasoning behind an oblique list instead of a responsible recommendation.
## Override
This skill **overrides** `superpowers:brainstorming` where that skill prefers multiple-choice options. User instructions > skill defaults.
If `superpowers:brainstorming` is active in the session, this skill's response style takes precedence for design/brainstorming questions.
## Cross-agent applicability
This skill is **pure response-style** — it works on any agent (Claude, Gemini, Copilot) without tool mappings. No `references/copilot-tools.md` or equivalent needed.
## Why this exists
The pattern emerged from iterative refinement across `claude-skills` brainstorm sessions and `.meeting-room/` discussions. When agents dump 4-option menus for every question, users skim or disengage. A single argued recommendation with clear trade-offs leads to faster convergence and better decisions. When alternatives are genuinely competitive, mention them — but don't manufacture variants.
## Reference
Original rule lived in `~/.claude/CLAUDE.md` as a per-machine instruction. Moving to a skill makes it portable: all machines bootstrapped with `project-bootstrap` inherit it, and cross-agent compatibility is explicit.

108
dist-hermes/productivity/setup-tasks/README.md Normal file
View File

@@ -0,0 +1,108 @@
# setup-tasks
One-time skill that creates or migrates a project's `.tasks/` board to the
canonical layout — `STATUS.md` (the board, with emoji status legend) plus
per-task `<task-slug>.md` files for each active or paused task. The runtime
policy for working *with* the board lives in
[`using-tasks`](../using-tasks/) — `setup-tasks` is the only place that
creates the structure.
## When it triggers
- User says: "set up tasks", "init tasks", "create task tracking",
"migrate tasks to canon", "tasks broken", or the Russian equivalents
("настрой таски", "инициализируй таски").
- [`using-tasks`](../using-tasks/) detects a missing or non-canonical
`.tasks/` and delegates here via its Prerequisites section.
- [`project-bootstrap`](../project-bootstrap/) Step 4 delegates here when
initializing a new project.
## Modes
`setup-tasks` picks one of three modes after a discovery scan:
| Mode | Trigger | Action |
|---|---|---|
| **greenfield** | No `.tasks/` exists | Write `.tasks/STATUS.md` from the canonical template. No per-task files yet — they're created on demand. |
| **noop** | `.tasks/STATUS.md` already canon (emoji status legend + at least one per-task file) | Report and exit. |
| **migrate** | `.tasks/STATUS.md` is flat (plain `## Done` / `## In Progress` / `## Backlog`, no emoji legend, no per-task files) | Back up, then drive an interactive migration — one task at a time, asking the user for the canonical fields. |
A "placeholder" STATUS.md (just the bootstrap default with no real tasks) is
treated as `greenfield` — no migration needed.
## What canon means
```
.tasks/
├── STATUS.md ← board, with emoji status legend + one block per task
└── <task-slug>.md ← per-task deep context (one file per active/paused task)
```
Status legend: 🔴 active / 🟡 paused / ⚪ ready / 🟢 done / 🔵 blocked.
`STATUS.md` block format (one per task):
```
## 🔴 [task-slug] — short description
**Status:** active
**Where I stopped:** one sentence — the exact thought or action interrupted
**Next action:** one concrete step to resume immediately
**Blocker:** (only if blocked) what is preventing progress
**Branch:** git branch name
```
Per-task file sections: Goal, Key files, Decisions log, Open questions,
Completed steps, Notes.
## 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 write.
- **Never auto-parse a flat STATUS.md.** Old layouts vary; agent heuristics
mangle real work. Migration is interactive — the agent asks the user for
each task's canonical fields.
- **Never invent task slugs / branches / "where you stopped" values.** The
whole point is *real* preserved context, not hallucinated context.
- **No empty per-task files at greenfield.** Wait until the user adds a
real task.
- **Never edit the `.bak` file.** It's the rollback artifact.
## Procedure (high-level)
1. **Phase 0** — environment sanity (project root).
2. **Phase 1** — discovery (greenfield / noop / migrate).
3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
4. **Phase 3** — backup (migrate only) → `STATUS.md.bak-YYYYMMDD-HHMMSS`.
5. **Phase 4a/4b** — greenfield create or interactive migrate.
6. **Phase 5** — verify (canon `STATUS.md`, per-task files for active/paused
only, no required content lost).
7. **Phase 6** — final report; if invoked from `project-bootstrap`, return
silently.
Full procedure with templates and the migration script lives in
[`SKILL.md`](SKILL.md).
## Rollback
- Greenfield: `rm -rf .tasks/`.
- Migrate: `mv .tasks/STATUS.md.bak-<ts> .tasks/STATUS.md` plus `rm` for any
newly created per-task files; `git reset HEAD .tasks/`.
## Install
From the repo root:
```bash
bash scripts/install.sh setup-tasks
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`using-tasks`](../using-tasks/) — runtime policy for working with `.tasks/`.
- [`project-bootstrap`](../project-bootstrap/) — orchestrator that delegates
here for new projects.
- Source pattern: `.wiki/raw/setup-task-status-wiki.md` in this repo —
extended documentation, decisions log format, agent operations.

202
dist-hermes/productivity/setup-tasks/SKILL.md Normal file
View File

@@ -0,0 +1,202 @@
---
name: setup-tasks
version: 1.0.0
description: Creates or migrates a project's `.tasks/` board to the canonical layout — `STATUS.md` (the board, with emoji status legend) plus per-task `<task-slug>.md` files for each active or paused task. Use when the user says "set up tasks", "init tasks", "настрой таски", "инициализируй таски", "create task tracking", "migrate tasks to canon", "tasks broken", or whenever `using-tasks` detects a missing or non-canonical `.tasks/`. Two modes — greenfield (no `.tasks/`) and migrate (existing flat STATUS.md without per-task files). Confirmation gate before writing. Cross-platform.
---
# setup-tasks
> Creates or migrates a `.tasks/` board to canon. The canonical layout is enforced by `using-tasks` and described in `.wiki/raw/setup-task-status-wiki.md` (the original idea file from which this skill is derived). This skill is the *only* place that creates the board structure.
## When to use
- User explicitly asks: set up / init / migrate / create tasks.
- `using-tasks` runs and detects a missing or non-canonical `.tasks/` — its Prerequisites delegate here.
- `project-bootstrap` Step 4 delegates here when initializing a new project.
## Out of scope
- Editing existing task content during normal work (that's `using-tasks`).
- Anything outside `.tasks/`.
## Hard rule: don't auto-mutate
The procedure mutates `.tasks/`. **Pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan).** A trigger phrase is permission to inspect, not to write.
## Procedure
### Phase 0 — Environment sanity
- Confirm current working directory is a project root (preferably with `.git/`; otherwise it's still OK to bootstrap, just note it).
- Tasks paths are POSIX-style (`.tasks/...`) on every OS.
### Phase 1 — Discovery
Inspect `.tasks/`:
- **No `.tasks/`** → mode = `greenfield`.
- **`.tasks/STATUS.md` exists with canonical signals** — has emoji status (🔴 / 🟡 / ⚪ / 🟢 / 🔵) AND at least one per-task `.tasks/<slug>.md` exists for any active/paused entry → mode = `noop`.
- **`.tasks/STATUS.md` exists but flat** — no emoji legend, no per-task files, just plain `## Done` / `## In Progress` / `## Backlog` sections (or similar) → mode = `migrate`.
Report findings:
```
Mode: greenfield | noop | migrate
STATUS.md: exists | missing
Per-task files: <count>
Format: canon | flat | mixed
```
### Phase 2 — Plan + confirm
Show the plan in one block.
**Greenfield:**
```
Will create .tasks/STATUS.md with the canonical board template.
Per-task files will be created on demand by using-tasks when actual tasks are added.
```
**Migrate:**
```
Will:
• back up existing STATUS.md → STATUS.md.bak-<ts>
• for each task entry I can identify in the old STATUS.md, ask you for:
- task-slug (kebab-case, latin)
- current status (active / paused / ready / done / blocked)
- branch
- where you stopped (one sentence)
- next action (one sentence)
then write `.tasks/<slug>.md` and a canonical STATUS.md block.
• leave the .bak file as a fallback reference.
```
If existing `STATUS.md` is purely a placeholder (just the bootstrap-default comment block, no real tasks), treat as `greenfield` — no migration needed, just overwrite with the template.
Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.
### Phase 3 — Backup (migrate only)
```bash
TS=$(date +%Y%m%d-%H%M%S)
cp .tasks/STATUS.md ".tasks/STATUS.md.bak-$TS"
```
### Phase 4a — Greenfield create
Write `.tasks/STATUS.md`:
```markdown
# Task Board
_Updated: <today>_
<!--
Add one block per task, sorted by priority. Use the emoji status legend below.
Per-task deep context lives in .tasks/<task-slug>.md (created on demand by using-tasks).
Block format:
## 🔴 [task-slug] — short description
**Status:** active
**Where I stopped:** one sentence — the exact thought or action interrupted
**Next action:** one concrete step to resume immediately
**Blocker:** (only if blocked) what is preventing progress
**Branch:** git branch name
---
Status legend:
🔴 Active — only one at a time
🟡 Paused — in progress, resumable
⚪ Ready — defined, not started
🟢 Done — kept until merged
🔵 Blocked — waiting on external input
-->
```
No per-task files at greenfield — they're created when actual tasks are added.
### Phase 4b — Migrate
In migrate mode, do *not* try to auto-parse the old flat STATUS.md. The old layout is too varied — agent-driven heuristics will mangle real work. Instead, drive the migration interactively:
1. Show the user the old STATUS.md content (or a summary).
2. Ask: "Which of these are real, in-flight tasks you want to keep?" Get a list.
3. For each task, ask the four canonical fields (slug, status, branch, where-stopped, next-action). The skill never invents these.
4. Build a fresh canonical `.tasks/STATUS.md` from those answers.
5. Create `.tasks/<task-slug>.md` for each active or paused task using the per-task template (Goal, Key files, Decisions log, Open questions, Completed steps, Notes).
6. Leave the `.bak-<ts>` file in place — historical record.
Per-task template:
```markdown
# <task-slug>
## Goal
One paragraph. What this achieves and why it matters.
## Key files
- `path/to/file.ts` — role in this task
## Decisions log
- <today>: migrated from flat STATUS.md via setup-tasks@<version>
## Open questions
- [ ] (fill in)
## Completed steps
- [x] (fill in)
## Notes
```
### Phase 5 — Verify
After writes:
- `.tasks/STATUS.md` exists and has the emoji status legend (or template comment block in greenfield).
- For migrate: each task referenced in STATUS.md has its `<task-slug>.md` file (active and paused only).
- No required content was lost (the `.bak` file is the safety net).
If verification fails → restore from `.bak-<ts>` and report.
### Phase 6 — Report
Print final state:
```
✅ Tasks board ready at .tasks/.
Mode: greenfield | migrate
STATUS.md: <created | rewritten + .bak-<ts>>
Per-task files: <count>
Next steps for the user:
• Add or edit task entries in .tasks/STATUS.md
• Read using-tasks SKILL.md if unfamiliar with the workflow
```
If invoked from `project-bootstrap`, return control silently.
## Rollback
1. `rm -rf .tasks/` (greenfield rollback)
or
`mv .tasks/STATUS.md.bak-<ts> .tasks/STATUS.md` (migrate rollback) and `rm .tasks/<task-slug>.md` for any newly created per-task files.
2. `git reset HEAD .tasks/` if a git repo.
3. Tell user what failed.
## Common mistakes
- **Auto-parsing existing flat STATUS.md.** Don't. The format varies, real work is at stake — drive migration through the user, one task at a time.
- **Inventing task slugs / branches / "where you stopped" values.** Never. Ask the user. The whole point of `.tasks/` is *real* preserved context, not hallucinated context.
- **Skipping confirmation on greenfield.** Yes, even greenfield needs the gate — the user might be running this in the wrong directory.
- **Creating per-task files at bootstrap.** Don't pre-generate empty `<slug>.md` files in greenfield mode — wait until the user adds actual tasks.
- **Editing the `.bak` file.** It's the rollback artifact; leave it alone.
## Cross-platform notes
The procedure is platform-agnostic. Wiki-style paths (`.tasks/...`) work the same on Windows / Linux / macOS. The only platform-conditional command is the timestamp generator (`date +%Y%m%d-%H%M%S` in bash; equivalent in PowerShell), and our scripts use bash via git-bash on Windows.
## Source
The canonical pattern (extended documentation, decisions log format, agent operations) lives in this repo at `.wiki/raw/setup-task-status-wiki.md`. Refer to it when designing project-specific extensions.

169
dist-hermes/productivity/using-tasks/README.md Normal file
View File

@@ -0,0 +1,169 @@
# using-tasks
Runtime policy for keeping compressed working context across parallel tasks
in a monorepo. The agent reads and updates `.tasks/` so every session starts
oriented and every switch costs seconds, not minutes.
`using-tasks` governs *usage* of an existing `.tasks/`. Initial creation and
migration to canon are owned by [`setup-tasks`](../setup-tasks/).
> Renamed from `task-status-wiki` at v1.0.0.
## When it triggers
- User is switching between tasks, resuming a paused task, starting a new
one, or asks "where were we" / "what's the status".
- User says: "use task management system", "pause", "switch to X",
"update status".
- Any context-switching or multi-task coordination question in a code
project.
- If `.tasks/` is missing or non-canonical, this skill delegates to
[`setup-tasks`](../setup-tasks/) before doing anything else.
## Structure
```
<monorepo-root>/
└── .tasks/
├── STATUS.md ← board: one block per task, sorted by priority
└── <task-slug>.md ← deep context per task, one file each
```
Commit `.tasks/` to git — decision history is valuable, diffs show how
thinking evolved.
## STATUS.md format
```markdown
# Task Board
_Updated: YYYY-MM-DD_
## 🔴 [task-slug] — short description
**Status:** active | paused | blocked | done
**Where I stopped:** one sentence — the exact thought or action interrupted
**Next action:** one concrete step to resume immediately
**Blocker:** (only if blocked) what is preventing progress
**Branch:** git branch name
---
```
Status legend:
| Emoji | State | Notes |
|---|---|---|
| 🔴 | Active | Currently worked on. **Only one at a time.** |
| 🟡 | Paused | In progress, resumable. |
| ⚪ | Ready | Defined, not started. |
| 🟢 | Done | Kept until merged. |
| 🔵 | Blocked | Waiting on external input. |
## Per-task file format (`<task-slug>.md`)
Sections, in order: **Goal** (one paragraph — what this achieves and why),
**Key files** (`path/to/file.ts:42` style — specific lines when relevant),
**Decisions log** (reverse-chronological, append-only — past entries are
immutable), **Open questions**, **Completed steps**, **Notes** (temporary
hypotheses, links).
## Operations
### Session start
1. Check `.tasks/STATUS.md`. If missing → invoke
[`setup-tasks`](../setup-tasks/) and stop until it returns.
2. Read `STATUS.md`.
3. If user names a task, read its `<task-slug>.md`.
4. Confirm in one sentence: "We're in the middle of X, next step is Y."
5. Ask if the plan is still correct before doing anything.
6. If `_Updated` is more than 3 days old, flag it and ask the user to
confirm current state.
### Session end / pause / switch
1. Update `STATUS.md`: set the current task to 🟡, refresh "Where I stopped"
and "Next action".
2. Append non-obvious decisions to `<task-slug>.md` Decisions log.
3. Move finished items to "Completed steps".
4. Commit: `git add .tasks/ && git commit -m "chore: update task status [<task-slug>]"`.
### Task switch
1. Run session-end ops for the current task.
2. Read the target `<task-slug>.md`.
3. Set the target to 🔴 in `STATUS.md` (demote previous active to 🟡).
4. Confirm orientation before starting work.
### New task
1. Ask: slug, goal, known key files, branch.
2. Create `<task-slug>.md` with Goal and Key files populated.
3. Add a ⚪ block to `STATUS.md`.
4. Create / checkout the branch if missing.
### Task completion
1. **Pre-close coverage check** — list acceptance criteria, locate
evidence (tests, smoke-test artefacts, manual checklist ticks, design
doc refs). Missing evidence → ask the user before closing; never auto-close.
2. Resolve or drop all open questions.
3. Set status to 🟢 in `STATUS.md`.
4. Append a final summary line to the Decisions log.
5. Remind the user to delete the branch after merge.
### Post-commit task closure prompt
After a `feat:` / `fix:` commit the agent prompts:
"эта работа закрывает таску `<slug>`?". Slug candidates: commit-message
scope, current branch, most recent `Where I stopped`. If yes → run the
coverage check above. Skips `chore:` / `meta:` / `docs:` commits.
Forces a fresh-while-fresh decision, instead of letting shipped code sit
under a stale ⚪ block.
### Recommendations / "what's next" trigger
When the user asks «что дальше», «срочные», «куда копаем», "what next",
"status", or on session-start — recommend in this order:
1. **Local cwd-project board** ranked 🔴 → 🟡 → ⚪. Cite slugs.
2. **One footnote line** if relevant: `Cross-project: N 🔴 in other repos
(см. mcp__projects-meta__tasks_aggregate).` Only if N>0 and no local 🔴.
Explicit "по всем проектам" / "across all projects" flips the order.
Pairs with `using-projects-meta`'s local-first rule (which covers reads;
this one covers recommendations).
## Rules
- **Never lose "Where I stopped".** Most critical field. If unclear, ask
before ending the session.
- **One sentence per `STATUS.md` field.** Compress, don't write prose.
- **Key files must be specific** — not "auth module" but
`packages/auth/src/useAuth.ts:87`.
- **Decisions log is append-only.** Past entries are immutable.
- **Commit after every session end.** `git log` is the history of thinking.
- **Always confirm orientation at session start.** State understanding
before acting.
- **One active task at a time** — only one 🔴 in `STATUS.md`.
- **Never close without coverage check.** See "### Task completion"
step 1.
- **Local-first recommendations.** cwd-project first; cross-project at
most one footnote line.
## Install
From the repo root:
```bash
bash scripts/install.sh using-tasks
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` creation and
canon migration.
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-tasks` for
new projects.

174
dist-hermes/productivity/using-tasks/SKILL.md Normal file
View File

@@ -0,0 +1,174 @@
---
name: using-tasks
version: 1.1.0
description: >
Policy skill for working with an existing `.tasks/` board (per-task files + STATUS.md).
Use whenever the user is switching between tasks, resuming a paused task, starting a new
task, asking "where were we", says "use task management system", "pause", "switch to X",
"what's the status", "update status", or wants to track progress across parallel workstreams.
Trigger on any context-switching or multi-task coordination question in a code project.
If `.tasks/` is missing or non-canonical (no per-task `<task-slug>.md` files, no emoji
status legend in STATUS.md), delegate to `setup-tasks` first — it has its own confirmation
gate. Renamed from `task-status-wiki` at v1.0.0.
---
# using-tasks
> Policy for maintaining compressed working context across parallel tasks in a monorepo.
> The agent reads and updates `.tasks/` so every session starts oriented and every switch
> costs seconds, not minutes. This skill governs *usage* of an existing `.tasks/` — initial
> creation and migration to canon are owned by `setup-tasks`.
## Prerequisites
This skill assumes the project has a canonical `.tasks/` layout:
- `.tasks/STATUS.md` — the board, with per-task blocks using emoji status (🔴 active / 🟡 paused / ⚪ ready / 🟢 done / 🔵 blocked).
- `.tasks/<task-slug>.md` — one deep-context file per active or paused task.
If `.tasks/` is **missing**, or `STATUS.md` exists but is non-canonical (e.g. flat sections like "## Done" / "## In Progress" without the emoji + per-task block format, or no per-task files exist alongside STATUS.md) — invoke `setup-tasks` first. It detects greenfield vs migrate, has its own confirmation gate, and creates / migrates the structure. Only after `setup-tasks` finishes should this skill operate on `.tasks/`.
## Structure
```
<monorepo-root>/
.tasks/
STATUS.md ← board: one block per task, sorted by priority
<task-slug>.md ← deep context per task, one file each
```
Commit `.tasks/` to git. Decision history is valuable; diffs show how thinking evolved.
---
## STATUS.md format
```markdown
# Task Board
_Updated: YYYY-MM-DD_
## 🔴 [task-slug] — short description
**Status:** active | paused | blocked | done
**Where I stopped:** one sentence — the exact thought or action interrupted
**Next action:** one concrete step to resume immediately
**Blocker:** (only if blocked) what is preventing progress
**Branch:** git branch name
---
```
**Emoji convention:**
- 🔴 Active — currently worked on (only one at a time)
- 🟡 Paused — in progress, resumable
- ⚪ Ready — not started, fully defined
- 🟢 Done — completed, kept until merged
- 🔵 Blocked — waiting on external input
---
## Per-task file format (`<task-slug>.md`)
```markdown
# <task-slug>
## Goal
One paragraph. What this achieves and why it matters in the monorepo.
## Key files
- `path/to/file.ts` — role in this task
- `path/to/other.ts:42` — specific line if relevant
## Decisions log
Reverse-chronological. Append only — never rewrite past entries.
- YYYY-MM-DD: Why X was chosen over Y
- YYYY-MM-DD: Constraint Z discovered, approach adjusted
## Open questions
- [ ] unresolved design or dependency questions
## Completed steps
- [x] steps finished this or previous sessions
## Notes
Temporary hypotheses, links, names of people to consult.
```
---
## Agent operations
### Session start
1. Check if `.tasks/STATUS.md` exists. If not → invoke `setup-tasks` and stop here until it returns.
2. Read `STATUS.md`.
3. If user names a task, read its `<task-slug>.md`.
4. Confirm in one sentence: "We're in the middle of X, next step is Y."
5. Ask if the plan is still correct before doing anything.
6. If STATUS.md `_Updated` date is >3 days ago, flag it and ask user to confirm current state.
### Session end / pause / switch
1. Update `STATUS.md`: set current task to 🟡, update "Where I stopped" and "Next action".
2. Append to `<task-slug>.md` Decisions log any non-obvious choices made this session.
3. Move finished items to "Completed steps".
4. Commit: `git add .tasks/ && git commit -m "chore: update task status [<task-slug>]"`
### Task switch
1. Perform session-end operations for the current task.
2. Read the target `<task-slug>.md`.
3. Set it to 🔴 in STATUS.md (demote previous active to 🟡).
4. Confirm orientation before starting work.
### New task creation
1. Ask: task name (slug), goal, known key files, branch name.
2. Create `<task-slug>.md` with Goal and Key files populated.
3. Add ⚪ block to `STATUS.md`.
4. Create and checkout branch if it doesn't exist.
### Task completion
1. **Pre-close coverage check.** Before setting 🟢:
- List acceptance criteria from the per-task `<slug>.md` (or the STATUS block if no per-task file).
- For each criterion, locate evidence: a test name in the diff, a smoke-test artefact, a manual-checklist tick in the per-task file, or a design-doc reference.
- Missing evidence on any criterion → flag to user and ask "закрывать или подождать coverage'а?". Never silently close.
- If acceptance criteria are policy / docs-only and have no testable shape, an explicit user "ok, closed by inspection" is required (record this in the close-note).
2. Resolve or drop all open questions.
3. Set status to 🟢 in STATUS.md.
4. Append final summary line to Decisions log.
5. Remind user to delete the branch after merge.
### Post-commit task closure prompt
After any implementation commit (`feat:` / `fix:` / similar), prompt the user once:
> Эта работа закрывает таску `<slug>`?
Slug candidates, in priority: (a) commit message scope, (b) current branch name, (c) the most recent `Where I stopped` field that mentions a now-shipped artefact. If user says yes → run the pre-close coverage check from "### Task completion". If no → silent.
Skip on `chore:` / `meta:` / `docs:` / `style:` commits — they rarely close work.
This exists because shipped code can sit while the task block stays ⚪ ready (e.g. `extend-project-discipline-brainstorm-workspaces` lived as ⚪ for a day after `215afdd` shipped Rule 5). The prompt forces a one-line decision while the work is fresh.
### Recommendations / "what's next" trigger
When the user asks «что дальше», «срочные», «куда копаем», «status», «what next», or session-start lands on a project — recommend in this order:
1. **Local cwd-project board** ranked 🔴 → 🟡 → ⚪. Group by status, summarize one line each. Cite slugs.
2. **One footnote line** if cross-project state is relevant: `Cross-project: N 🔴 active in other repos (см. mcp__projects-meta__tasks_aggregate).` Only when N>0 and there is no active 🔴 in the current cwd. Never bury local recommendations under it.
Cross-project urgents are *information*, not the driver of "what to do here". The user chose this cwd; that's the implicit scope.
If the user explicitly asks "across all projects" / "по всем проектам" / "cross-project status" — flip the order: cross-project first, local as footnote.
Pair: `using-projects-meta` declares local-first for **reads**; this rule extends local-first to the **recommendation phase**.
---
## Rules
- **Never lose "Where I stopped"** — most critical field. If unclear, ask before ending session.
- **One sentence per STATUS.md field** — compress, don't write prose.
- **Key files must be specific** — not "auth module" but `packages/auth/src/useAuth.ts:87`.
- **Decisions log is append-only** — past entries are immutable.
- **Commit after every session end** — git log is the history of thinking.
- **Always confirm orientation at session start** — state understanding before acting.
- **One active task at a time** — only one 🔴 in STATUS.md.
- **Never close a task without a coverage check** — see "### Task completion" step 1. Acceptance criteria with no evidence → ask, don't auto-close.
- **Local-first recommendations** — cwd-project board comes first; cross-project urgents are at most one footnote line.

101
dist-hermes/research/setup-wiki/README.md Normal file
View File

@@ -0,0 +1,101 @@
# setup-wiki
One-time skill that creates or migrates a project's `.wiki/` to the
canonical Karpathy LLM Wiki layout. The runtime policy for working *inside*
that wiki lives in [`using-wiki`](../using-wiki/) — `setup-wiki` is the only
place that creates or rearranges the file structure.
Canonical layout reference:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
## When it triggers
- User says: "set up wiki", "init wiki", "create wiki", "migrate wiki to canon",
"wiki layout broken", or the Russian equivalents ("настрой вики",
"инициализируй вики", "wiki сломана").
- [`using-wiki`](../using-wiki/) detects a missing or non-canonical `.wiki/`
and delegates here via its Prerequisites section.
- [`project-bootstrap`](../project-bootstrap/) Step 3 delegates here when
initializing a new project.
## Modes
`setup-wiki` chooses one of three modes after a discovery scan:
| Mode | Trigger | Action |
|---|---|---|
| **greenfield** | No `.wiki/` exists | Create the canonical layout from scratch. |
| **noop** | `.wiki/` already canon (all five canon files + four content dirs) | Report and exit — no writes. |
| **migrate** | `.wiki/` exists with non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`) or missing canon files | Move legacy files (e.g. `source/*.md` → `concepts/*.md` via `git mv`), create missing canon files, drop a timestamped `.backup-*/` next to it. |
Migration **does not auto-rewrite** existing concept content — it only moves
files and prepends minimal frontmatter when missing. Real edits stay your
job.
## What canon means
```
.wiki/
├── CLAUDE.md ← schema: project-specific wiki conventions
├── index.md ← catalog of pages by type
├── log.md ← append-only op log
├── overview.md ← single project overview
├── raw/
│ └── README.md ← raw/ is immutable; this file documents that
├── entities/ ← entity pages (people, services, modules)
├── concepts/ ← design decisions, recurring ideas
├── packages/ ← code packages
└── sources/ ← one summary per ingested source
```
The four content directories each get a `.gitkeep` so git tracks them.
## 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 write.
- **Never touch `raw/` content during migration.** `raw/` is immutable; only
the `.gitkeep` placeholder may be removed when `raw/README.md` replaces it.
- **No re-runs that overwrite a canon wiki.** Phase 1 detection guards
this — `noop` mode bails out cleanly.
- **No invented domain conventions.** The schema's "Domain conventions"
section stays a stub for the user to fill in.
## Procedure (high-level)
1. **Phase 0** — environment sanity (project root, platform check).
2. **Phase 1** — discovery (greenfield / noop / migrate).
3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
4. **Phase 3** — backup (migrate only) → `.wiki/.backup-YYYYMMDD-HHMMSS/`.
5. **Phase 4a/4b** — greenfield create or migrate.
6. **Phase 5** — verify (canon files present, dirs exist, no leftover
non-canon, frontmatter on migrated pages).
7. **Phase 6** — final report; if invoked from `project-bootstrap`, return
silently.
Full procedure with templates and the migration shell snippet lives in
[`SKILL.md`](SKILL.md).
## Rollback
- Greenfield: `rm -rf .wiki/`.
- Migrate: `cp -r .wiki/.backup-<ts>/* .wiki/` and `git reset HEAD .wiki/`.
## Install
From the repo root:
```bash
bash scripts/install.sh setup-wiki
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`.
- [`project-bootstrap`](../project-bootstrap/) — orchestrator that delegates
here for new projects.
- Karpathy's LLM Wiki gist:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>

284
dist-hermes/research/setup-wiki/SKILL.md Normal file
View File

@@ -0,0 +1,284 @@
---
name: setup-wiki
version: 1.0.0
description: Creates or migrates a project's `.wiki/` to the canonical Karpathy LLM Wiki layout — `CLAUDE.md` schema, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus empty `entities/`, `concepts/`, `packages/`, `sources/`. Use when the user says "set up wiki", "init wiki", "настрой вики", "инициализируй вики", "create wiki", "migrate wiki to canon", "wiki сломана", "wiki layout broken", or whenever `using-wiki` detects a missing or non-canonical `.wiki/`. Two modes — greenfield (no wiki) and migrate (existing non-canonical layout). Confirmation gate before writing. Cross-platform.
---
# setup-wiki
> Creates or migrates a `.wiki/` to canon. The canonical layout is documented at https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f and enforced by `using-wiki`. This skill is the *only* place that creates or rearranges those files.
## When to use
- User explicitly asks: set up / init / migrate / create wiki.
- `using-wiki` runs and detects a missing or non-canonical `.wiki/` — its Prerequisites delegate here.
- `project-bootstrap` Step 3 delegates here when initializing a new project.
## Out of scope
- Editing existing wiki *content* (that's `using-wiki`'s job).
- Anything outside `.wiki/`.
## Hard rule: don't auto-mutate
The procedure mutates the project's `.wiki/`. **Pause for explicit confirmation between Phase 1 (discovery) and Phase 2 (plan).** A trigger phrase is permission to inspect, not to write.
## Procedure
### Phase 0 — Environment sanity
- Confirm current working directory is a project root (has `.git/` ideally, or at minimum is a place the user wants a wiki).
- Detect platform; pick file paths accordingly. Wiki paths are POSIX-style (`.wiki/...`) on every OS.
### Phase 1 — Discovery
Inspect `.wiki/`:
- **No `.wiki/`** → mode = `greenfield`.
- **`.wiki/` exists AND has all of:** `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus directories `entities/`, `concepts/`, `packages/`, `sources/` → mode = `noop` (already canon; report and exit).
- **`.wiki/` exists but missing some canon files OR has non-canon files** (`SUMMARY.md`, `WORKFLOW.md`, `source/`) → mode = `migrate`.
Report findings to the user as a short summary:
```
Mode: greenfield | noop | migrate
Has: <list of canon files present>
Missing: <list>
Non-canon: <list>
```
### Phase 2 — Plan + confirm
Show the plan in one block:
**Greenfield:**
```
Will create .wiki/ with canonical layout:
CLAUDE.md (schema), index.md, log.md, overview.md
raw/README.md
entities/, concepts/, packages/, sources/ (with .gitkeep)
```
**Migrate:**
```
Will rename:
source/*.md → concepts/*.md (via git mv when in a git repo, plain mv otherwise)
Will create:
CLAUDE.md, index.md, log.md, overview.md, raw/README.md
entities/, packages/, sources/ (with .gitkeep)
Will delete:
SUMMARY.md, WORKFLOW.md, raw/.gitkeep, source/ (after moves)
Will not touch existing files in raw/ — they're immutable sources.
```
Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop.
### Phase 3 — Backup (migrate only)
In migrate mode only, copy each file we will rename/delete to `.wiki/.backup-YYYYMMDD-HHMMSS/`. (Greenfield has nothing to back up.)
If git is available, the rename history is also recoverable via `git reflog`, but a filesystem backup is belt-and-suspenders.
### Phase 4a — Greenfield create
Create the canonical layout. Each file gets the content shown below; the project name comes from the parent directory's basename.
**`.wiki/CLAUDE.md`** (schema):
```markdown
# Wiki Schema — <project>
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 `using-wiki` skill enforces the workflow and file formats. This file overrides the skill where they conflict.
## Page types
- `entities/` — discrete things this project tracks (people, services, modules).
- `concepts/` — recurring ideas, design decisions, gotchas.
- `packages/` — code packages this project produces or consumes.
- `sources/` — one summary page per ingested external doc; carries `ingested:` and `raw_path:`.
- `overview.md` — single project-wide overview.
## Naming
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter.
## Domain conventions
<!-- Fill in as the project takes shape — what counts as an entity here, which packages exist, naming idioms specific to this codebase. -->
```
**`.wiki/index.md`** (catalog):
```markdown
# 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) — project overview
## Entities
<!-- (none yet) -->
## Concepts
<!-- (none yet) -->
## Packages
<!-- (none yet) -->
## Sources
<!-- (none yet) -->
```
**`.wiki/log.md`** (op log; backfill an `init` line dated today):
```markdown
# Wiki Log
Append-only operation log. Format:
\`\`\`
## [YYYY-MM-DD] <op> | <one-line description>
\`\`\`
Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`.
Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
---
## [<today>] init | wiki bootstrapped via setup-wiki@<version>
```
**`.wiki/overview.md`**:
```markdown
---
title: <project> overview
type: overview
updated: <today>
---
# <project> — overview
<!-- Replace with a high-level description: what this project does, who it's for, the main components. -->
```
**`.wiki/raw/README.md`**:
```markdown
# Raw Sources
**Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit.
Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files.
For large or path-sensitive sources outside the repo, register them here:
\`\`\`
- short-name → /absolute/path/to/source
\`\`\`
```
**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/` so git tracks the dirs.
### Phase 4b — Migrate
If migrate mode: combine creation (for missing canon files) with file moves (for non-canon).
```bash
# 1. Create missing directories
mkdir -p .wiki/concepts .wiki/entities .wiki/packages .wiki/sources
# 2. Move source/* → concepts/* (use git mv if in a git repo)
if git rev-parse --git-dir >/dev/null 2>&1; then
for f in .wiki/source/*.md; do
[ -e "$f" ] && git mv "$f" ".wiki/concepts/$(basename "$f")"
done
git rm -f .wiki/SUMMARY.md .wiki/WORKFLOW.md .wiki/source/.gitkeep .wiki/raw/.gitkeep 2>/dev/null
else
mv .wiki/source/*.md .wiki/concepts/ 2>/dev/null
rm -f .wiki/SUMMARY.md .wiki/WORKFLOW.md .wiki/source/.gitkeep .wiki/raw/.gitkeep
fi
rmdir .wiki/source 2>/dev/null
# 3. Create missing canon files (CLAUDE.md, index.md, log.md, overview.md, raw/README.md)
# using the templates from Phase 4a, but skip files that already exist.
# 4. Add .gitkeep to entities/, packages/, sources/
touch .wiki/entities/.gitkeep .wiki/packages/.gitkeep .wiki/sources/.gitkeep
```
For migrated `concepts/*.md` pages, **do not rewrite their content** — just prepend a minimal frontmatter if missing:
```yaml
---
title: <derived from existing H1>
type: concept
updated: <today>
---
```
Build `index.md` with one entry per migrated `concepts/<file>.md`, derived from the file's H1 and any one-liner the agent can extract.
Append a line to `log.md`:
```
## [<today>] refactor | wiki migrated to canon via setup-wiki@<version>
```
### Phase 5 — Verify
After writes, confirm:
- All canon files exist: `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`.
- Four content directories exist (with at least `.gitkeep` or content).
- No leftover non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`).
- For migrate mode: every migrated page has frontmatter with `type: concept`.
If anything's off — restore from `.wiki/.backup-*` and report.
### Phase 6 — Report
Print final state:
```
✅ Wiki ready at .wiki/.
Mode: greenfield | migrate
Files: 5 canon + 4 dirs + N migrated concept pages
Backup (if migrate): .wiki/.backup-<ts>/
Next steps for the user:
• Edit .wiki/overview.md to describe the project
• Edit .wiki/CLAUDE.md "Domain conventions" with project-specific rules
• Read using-wiki SKILL.md if unfamiliar with the workflow
```
If invoked from `project-bootstrap`, return control silently — bootstrap continues with its remaining steps.
## Rollback
1. `rm -rf .wiki/` (greenfield rollback) OR `cp -r .wiki/.backup-<ts>/* .wiki/` (migrate rollback).
2. If a git repo, `git reset HEAD .wiki/` to unstage moves.
3. Tell user what failed.
## Common mistakes
- **Touching `raw/` content during migration.** `raw/` is immutable — only the `.gitkeep` placeholder may be removed (and that only because `raw/README.md` replaces it).
- **Skipping confirmation on greenfield.** Yes, even greenfield needs the gate — the user might be running this skill in the wrong directory.
- **Re-running on already-canon wiki and rewriting files.** Phase 1 detection guards this; bail out at `noop` mode.
- **Inventing project-specific Domain conventions in `CLAUDE.md`.** The schema's "Domain conventions" section is intentionally a stub — let the user fill it as they accumulate domain knowledge.
## Cross-platform notes
The procedure is platform-agnostic. `mkdir -p`, `mv`, `git mv`, `cp -r`, `rm -rf`, `touch` work in git-bash on Windows the same as on Linux/macOS. Wiki paths use forward slashes throughout.

179
dist-hermes/research/using-wiki/README.md Normal file
View File

@@ -0,0 +1,179 @@
# using-wiki
Runtime policy for an LLM Wiki built on the
[Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
Knowledge is **compiled once and kept current** across three layers, via
three named operations, with strict file formats that keep the wiki
parseable and grep-friendly.
`using-wiki` governs *usage* of an existing `.wiki/`. Initial creation and
migration to canon are owned by [`setup-wiki`](../setup-wiki/).
> Renamed from `wiki-maintainer` at v1.0.0.
## When it triggers
- User says: "use project wiki", "query the wiki", "ingest this", or the
Russian equivalents ("обнови вики", "проверь вики", "запроси вики",
"заингесть").
- Any time the agent modifies a file under `.wiki/` — the workflow and
formats below are mandatory.
- If `.wiki/` is missing or non-canonical, this skill delegates to
[`setup-wiki`](../setup-wiki/) before doing anything else.
## Three layers (do not blur)
1. **Raw sources** — `.wiki/raw/` (or external paths registered in
`raw/README.md`). **Immutable.** Read, never edit. The only exception is
appending a `> Status` blockquote when the user explicitly asks for a
status audit.
2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept /
package / source summary pages.
3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what
entities, what packages, naming). Always read it first; it overrides this
skill on conflict.
## Three operations
### Ingest
«заингесть X» — pull a raw source into the wiki.
1. Read the raw source fully.
2. Extract: entities, concepts, packages, cross-cutting patterns.
3. Create `sources/<slug>.md` (one summary page per source, ~50–150 lines).
4. For each affected entity / concept / package page: update if exists,
create if not. Flag contradictions explicitly with
`> **Противоречие:** источник A говорит X, источник B — Y`.
**Never silently overwrite.**
5. Update `index.md`.
6. Append one line to `log.md`.
7. Report: what was created, updated, contradicted.
One ingest may touch 10–15 pages. That's normal — that's why an LLM does it.
### Query
A question answered from the wiki.
1. Read `index.md` first, drill into relevant pages.
2. Answer with citations as markdown links.
3. **Compound the wiki.** If the answer is a real synthesis, ask the user:
"Сохранить как страницу wiki?" Good queries become durable pages under
`concepts/` or `analyses/`.
4. Append one line to `log.md`.
### Lint
«проверь wiki» — health check.
Scan for:
- Contradictions between pages.
- Orphans (pages with no inbound links).
- Stale claims (raw source updated after the summary's `ingested:` date —
check via `git log -p`).
- Concepts mentioned in prose but missing their own page.
- Empty / TODO sections.
Report as a punch list. Don't delete anything automatically. Append one
line to `log.md` with the findings.
## File formats (mandatory)
### Page frontmatter
```yaml
---
title: Человекочитаемое имя
type: entity | concept | package | source | overview
tags: [short, tokens]
sources: [../sources/foo.md, ../sources/bar.md]
updated: 2026-04-21
---
```
Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
### File naming
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / non-Latin in
filenames; keep the original title in H1 + frontmatter.
- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md`
(no `@org/` prefix), `sources/<slug>.md`.
### `log.md` — append-only, grep-parseable
Every entry must start with:
```
## [YYYY-MM-DD] <operation> | <short description>
```
Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`.
Parse with: `grep "^## \[" .wiki/log.md | tail -20`.
### `index.md`
Catalog, not narrative. One line per page: `- [Title](path) — hook.`
Sections by type. Update on every ingest.
### Cross-references
- Wiki → wiki: relative markdown links — `[Name](../entities/x.md)`.
- Wiki → code: relative path from repo root — `[foo.js](../../packages/api/foo.js)`.
- Wiki → raw: `../raw/<file>`.
- URL-encode spaces (`%20`) and Cyrillic when needed.
## Quick reference
| Situation | Files touched |
|---|---|
| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
| Query | (read only) + optionally a new wiki page + `log.md` |
| Lint | (read only) + `log.md` |
| Bootstrap / migrate | (delegated to [`setup-wiki`](../setup-wiki/)) |
## Common mistakes
- **Editing `raw/`.** Don't. Only allowed change: status blockquote on
explicit request.
- **Dumping raw content into `sources/`.** Summaries are summaries. Link to
raw, don't copy.
- **Silent overwrites on contradictions.** Flag them with a `> **Противоречие:**`
block.
- **Narrative `log.md`.** "Today I added…" is wrong. Use
`## [YYYY-MM-DD] ingest | <what>`.
- **Non-ASCII filenames.** Breaks greppability and cross-platform. Transliterate.
- **Forgetting `index.md`.** Pages not listed there are invisible to future
queries.
- **Improvising layout when canon files are missing.** Hand off to
[`setup-wiki`](../setup-wiki/) instead of patching ad-hoc.
## When NOT to use
- The project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular
documentation, not an LLM Wiki.
- The user wants a single-file README or ADR — this skill is for persistent,
interlinked knowledge bases.
- One-off questions about code — read files directly, no wiki workflow needed.
## Install
From the repo root:
```bash
bash scripts/install.sh using-wiki
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` creation and
canon migration.
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-wiki` for
new projects.
- Karpathy's LLM Wiki gist:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>

134
dist-hermes/research/using-wiki/SKILL.md Normal file
View File

@@ -0,0 +1,134 @@
---
name: using-wiki
version: 1.0.0
description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wiki pattern). Use when the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "use project wiki", "обнови вики", "проверь вики", "запроси вики", "заингесть", "query the wiki". Also use when modifying any file under `.wiki/` — the workflow and formats below are mandatory, and project-specific conventions live in `.wiki/CLAUDE.md`. If `.wiki/` is missing or non-canonical, delegate to `setup-wiki` first (it has its own confirmation gate). Renamed from `wiki-maintainer` at v1.0.0.
---
# using-wiki
> Policy for maintaining an LLM Wiki (Karpathy pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Knowledge is **compiled once and kept current** across three layers, via three named operations, with strict file formats that make the wiki parseable and grep-friendly. This skill governs *usage* of an existing wiki — initial creation and migration to canon are owned by `setup-wiki`.
## Prerequisites
This skill assumes the project has a canonical `.wiki/` layout: `CLAUDE.md` (schema), `index.md` (catalog), `log.md` (op log), `overview.md`, `raw/README.md`, and the four content directories `entities/`, `concepts/`, `packages/`, `sources/`.
If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`) — invoke the `setup-wiki` skill first. It detects the situation (greenfield vs migrate) and creates or migrates the structure with its own confirmation gate. Only after `setup-wiki` finishes should this skill proceed with the operations below.
## Three layers (do not blur)
1. **Raw sources** — `.wiki/raw/` (or external paths registered in `raw/README.md`). **Immutable.** Read, never edit. The only exception is appending a `> Status` blockquote when the user explicitly asks for a status audit.
2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept / package / source summary pages.
3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what entities, what packages, naming). Always read it first if present; it overrides this skill when it conflicts.
## First step on every operation
1. Read `.wiki/CLAUDE.md` if it exists.
2. Read `.wiki/index.md` to locate relevant pages.
3. Only then act.
If `.wiki/CLAUDE.md` is missing, the layout is incomplete — invoke `setup-wiki` rather than improvising.
## Three operations
### Ingest — «заингесть X»
1. Read the raw source fully.
2. Extract: entities, concepts, packages, cross-cutting patterns.
3. Create `sources/<slug>.md` (one summary page per source, ~50–150 lines).
4. For each affected entity/concept/package page:
- If it exists → update it. **Flag contradictions explicitly** with `> **Противоречие:** источник A говорит X, источник B — Y`. Don't silently overwrite.
- If not → create it.
5. Update `index.md` — add or move entries.
6. Append one line to `log.md` (format below).
7. Report to the user: what created, what updated, what contradictions found.
**One ingest may touch 10–15 pages. This is normal — that's why LLMs do it.**
### Query — вопрос по wiki
1. Read `index.md` first, then drill into relevant pages.
2. Answer with citations as markdown links to wiki pages.
3. **Compound the wiki.** If the answer is a real synthesis (comparison, analysis, new connection) — ask the user: "Сохранить как страницу wiki?" Good queries become durable pages under `concepts/`, `analyses/`, or similar.
4. Append one line to `log.md`.
### Lint — «проверь wiki»
Scan for:
- **Contradictions** between pages.
- **Orphans** — pages with no inbound links.
- **Stale claims** — git `log -p` on the raw source shows it was updated after the summary's `ingested:` date.
- **Missing entities** — concepts mentioned in prose but without their own page.
- **Empty/TODO sections.**
Report as a punch list. Don't delete anything automatically.
Append one line to `log.md` summarizing the findings.
## File formats (MANDATORY)
### Page frontmatter
```yaml
---
title: Человекочитаемое имя
type: entity | concept | package | source | overview
tags: [short, tokens]
sources: [../sources/foo.md, ../sources/bar.md]
updated: 2026-04-21
---
```
Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
### File naming
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / other scripts in filenames (`план переписывания` → `ozon-client-rewrite.md`). Keep the original title in the H1 and frontmatter.
- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md` (no `@org/` prefix), `sources/<slug>.md`.
### `log.md` — append-only, grep-parseable
Every entry **must** start with:
```
## [YYYY-MM-DD] <operation> | <short description>
```
Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`.
Parseable with: `grep "^## \[" .wiki/log.md | tail -20`.
### `index.md`
Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources). Update on every ingest.
### Cross-references
- Wiki → wiki: relative markdown links, `[Name](../entities/x.md)`.
- Wiki → code: relative path from repo root: `[foo.js](../../packages/api/foo.js)`.
- Wiki → raw: `../raw/<file>`.
- URL-encode spaces in paths (`%20`) and Cyrillic when needed.
## Quick reference
| Situation | Files touched |
|---|---|
| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
| Query | (read only) + optionally new wiki page + `log.md` |
| Lint | (read only) + `log.md` |
| Bootstrap / migrate to canon | (delegated to `setup-wiki`) |
## Common mistakes
- **Editing `raw/`.** Don't. Only allowed: status blockquote when user explicitly asks.
- **Dumping raw content into `sources/`.** Summaries are summaries. Link to raw, don't copy it.
- **Silent overwrites.** When a new source contradicts an existing page, flag it with a `> **Противоречие:**` block; don't just overwrite.
- **Narrative `log.md`.** `Today I added…` is wrong. Use `## [YYYY-MM-DD] ingest | <what>`.
- **Non-ASCII file names.** Breaks greppability and cross-platform. Transliterate.
- **Forgetting `index.md`.** Pages not listed there are effectively invisible for future queries.
- **Skipping contradictions in lint.** The wiki's value grows from surfaced tensions, not from false consensus.
- **Improvising layout when canon files are missing.** If the wiki is missing or partial, hand off to `setup-wiki` instead of patching ad hoc.
## When NOT to use this skill
- Project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular project documentation, not an LLM Wiki.
- User wants a single-file README or ADR — this skill is for persistent interlinked knowledge bases.
- One-off questions about code — use regular file reading, not wiki workflow.

117
dist-hermes/software-development/project-bootstrap/README.md Normal file
View File

@@ -0,0 +1,117 @@
# project-bootstrap
Initializes or upgrades a project workspace in one pass: git, `.gitignore`,
`README.md`, `.wiki/` (Karpathy's LLM Wiki layout), `.tasks/` (per-task board),
and `CLAUDE.md` with skill triggers.
Operates in two modes, picked automatically:
- **init** — empty or near-empty folder. Creates everything from scratch.
- **upgrade** — existing project. Detects what's already there, only fills the
gaps. Never overwrites without explicit confirmation.
## When it triggers
The skill auto-activates on phrases like:
- "initialize project", "bootstrap", "setup project"
- "upgrade project", "add wiki", "add tasks"
- "start project", "set everything up"
- "let's start a project", "init"
It also triggers when an agent is launched in a fresh folder that the user
clearly intends to turn into a workspace.
## Prerequisites
`project-bootstrap` does not lay out `.wiki/` or `.tasks/` by itself — it
delegates to two companion skills, which must be installed on the machine
running it:
- [`setup-wiki`](../setup-wiki/) — creates the canonical `.wiki/` layout.
- [`setup-tasks`](../setup-tasks/) — creates the canonical `.tasks/` layout.
If either is missing, `project-bootstrap` stops with a clear error rather
than falling back to ad-hoc creation. This keeps layout drift between
projects bootstrapped at different times debuggable.
## What it creates
| Path | Source | Notes |
|---|---|---|
| `.git/` | `git init` | Skipped if repo already initialized. |
| `.gitignore` | `assets/.gitignore.template` | Skipped if file exists. |
| `README.md` | minimal stub | Skipped if file exists. |
| `.wiki/` | delegated to `setup-wiki` | Karpathy LLM Wiki layout — `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/`, `entities/`, `concepts/`, `packages/`, `sources/`. |
| `.tasks/` | delegated to `setup-tasks` | Canonical board — `STATUS.md` plus per-task `<task-slug>.md` files. |
| `CLAUDE.md` | `assets/CLAUDE.md.template` | Skill triggers (`use superpowers`, `use project wiki`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. On upgrade, the template is treated as a canonical set and merged idempotently — only missing trigger lines are appended after user confirm. Re-runs are no-ops. |
| `.wiki/concepts/bootstrap-manifest.md` | generated | Records which skill versions initialized the project, so cross-project layout drift is debuggable. |
## Workflow
1. **Detect mode.** Inspect the current directory — git, `.wiki/`, `.tasks/`,
`CLAUDE.md`, `README.md` — and print a single summary block: what was
found, what will be created, what will be skipped.
2. **Confirm.** One question, one confirmation. Nothing is written before the
user agrees.
3. **Steps 1–5.** Create or skip each piece in order — git, README, `.wiki/`,
`.tasks/`, `CLAUDE.md`. Steps 3 and 4 delegate to the setup-skills.
4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of
`project-bootstrap`, `setup-wiki`, `setup-tasks`, `project-discipline`,
`setup-interns`, and `using-interns` used.
5. **Step 5.6.** Skill dependencies check. Walk the canonical trigger list
in `CLAUDE.md`, look each up in an embedded `trigger → fulfiller` map,
detect what's missing on this host (`~/.claude/skills/<name>/SKILL.md`
for skills, `~/.claude/plugins/installed_plugins.json` for plugins),
and print one chat-only block listing every missing fulfiller with a
copy-pasteable install command. Prints a single ✅ line when nothing
is missing. Never auto-installs, never modifies project files.
6. **Commit.** `chore: bootstrap project structure` for fresh repos, or
`chore: upgrade project structure` adding only the new files for existing
ones. Pushes only on explicit user request.
7. **Summary.** Final report — what was created, what was skipped, suggested
next step.
## Rules
- Never overwrite an existing file without explicit user confirmation.
- Always show the plan before touching the filesystem.
- Never invent project details — read what's already there.
- Commit only files just created — never touch the rest of the tree.
- Push only after the user explicitly says so.
## Install
From the repo root:
**Windows (PowerShell):**
```powershell
bash scripts/install.sh project-bootstrap
```
**Linux / macOS (bash):**
```bash
bash scripts/install.sh project-bootstrap
```
`install.sh` works on Windows under git-bash. A native `install.ps1` is
[planned](../../.tasks/STATUS.md) but not required.
The skill installs to `~/.claude/skills/project-bootstrap/`. Override the
target with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh …`.
## See also
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` layout.
- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` layout.
- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`.
- [`using-tasks`](../using-tasks/) — runtime policy for working with `.tasks/`.
- [`project-discipline`](../project-discipline/) — cross-project rules
activated by the `follow project discipline` trigger.
- [`setup-interns`](../setup-interns/), [`using-interns`](../using-interns/) —
pair behind the `delegate to interns when allowed` trigger; cheap-LLM
delegation under a per-session permission grant.
- Karpathy's LLM Wiki gist:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>

593
dist-hermes/software-development/project-bootstrap/SKILL.md Normal file
View File

@@ -0,0 +1,593 @@
---
name: project-bootstrap
version: 1.10.0
description: >
Initializes or upgrades a project in the current folder: git, .gitignore, README.md,
.wiki/ using Karpathy's method, .tasks/ for task tracking, CLAUDE.md with skill triggers.
Creates remote Gitea repo and syncs projects-meta cache for greenfield projects.
Use this skill when the user says "initialize project", "bootstrap", "setup project",
"upgrade project", "add wiki", "add tasks", "start project", "set everything up",
"create new project", or launches the agent in a new folder and wants a full setup.
Trigger even if the user just says "let's start a project" or "set it all up".
---
# Project Bootstrap
Sets up a complete working environment for a monorepo project in one pass.
Operates in three modes: **greenfield-full** (new project + remote create), **add-remote**
(existing git without remote), and **upgrade** (existing project).
---
## Step 0 — Detect mode
Check what already exists in the current directory:
```bash
ls -la
git rev-parse --git-dir 2>/dev/null && echo "git:yes" || echo "git:no"
git remote get-url origin 2>/dev/null && echo "remote:yes" || echo "remote:no"
ls -A 2>/dev/null | grep -q . && echo "empty:no" || echo "empty:yes"
[ -d .wiki ] && echo "wiki:yes" || echo "wiki:no"
[ -d .tasks ] && echo "tasks:yes" || echo "tasks:no"
[ -f CLAUDE.md ] && echo "claude:yes" || echo "claude:no"
[ -f README.md ] && echo "readme:yes" || echo "readme:no"
```
Determine mode:
- **greenfield-full**: `git:no` + `empty:yes` — new project, will create remote
- **add-remote**: `git:yes` + `remote:no` — existing git, offer to create remote
- **upgrade**: otherwise — existing project, upgrade only
Show the user a summary in one block — what was found, what will be created:
```
Mode: greenfield-full (new project + remote create)
Found: (empty directory)
Create: git .wiki .tasks CLAUDE.md .gitignore README.md remote
```
Ask one question: "Looks right? Shall we proceed?" — and wait for confirmation.
**Create nothing before confirmation.**
---
## Step 1 — Git
If git is not initialized:
```bash
git init
```
If `.gitignore` does not exist — create from template `assets/.gitignore.template`.
If it exists — leave it untouched.
---
## Step 1.5 — Remote create (greenfield-full / add-remote modes)
Only in **greenfield-full** or **add-remote** mode. Skip for upgrade mode.
### Prerequisites
Read `~/.config/projects-mcp/auth.toml` to get Gitea credentials:
```bash
# POSIX (Linux/macOS/git-bash):
source ~/.config/projects-mcp/auth.toml 2>/dev/null || true
# Windows PowerShell:
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.
### Validate project name
Current folder name becomes the repo name. Must be:
- **Latin only** — a-z, 0-9, hyphens
- **kebab-case** — lowercase, hyphens between words
- **Not a duplicate** — check via Gitea API
```bash
PROJECT_NAME=$(basename "$PWD")
# Validate: only latin alnum + hyphen, no leading/trailing hyphen
echo "$PROJECT_NAME" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$' || {
echo "❌ Invalid project name: '$PROJECT_NAME'. Use latin kebab-case (e.g. 'my-project')."
exit 1
}
```
### Create repo via Gitea API
```bash
# Extract base_url and token from auth.toml (POSIX):
BASE_URL=$(grep "^base_url" ~/.config/projects-mcp/auth.toml | cut -d'"' -f2)
TOKEN=$(grep "^token" ~/.config/projects-mcp/auth.toml | cut -d'"' -f2)
# Create repo:
curl -X POST "$BASE_URL/api/v1/user/repos?token=$TOKEN" \
-H "Content-Type: application/json" \
-d "{\"name\":\"$PROJECT_NAME\",\"private\":false,\"auto_init\":false}"
```
On failure → stop and show error. Duplicate name = suggest rename or delete existing.
### Add remote and push
```bash
git remote add origin "$BASE_URL/$USER/$PROJECT_NAME.git"
git branch -M master
git push -u origin master
```
For **add-remote** mode (git exists, push local commits after adding remote):
```bash
git push -u origin master # or main if that's the current branch
```
---
## Step 2 — README.md
If it does not exist — create a minimal one:
```markdown
# <project folder name>
## About
<!-- Describe the project here -->
## Quick start
<!-- Instructions for running the project -->
```
If it exists — leave it untouched.
---
## Step 3 — .wiki/
**Delegate to the `setup-wiki` skill.** It handles greenfield creation, canon migration, and the no-op case (already canon) uniformly, with its own confirmation gate. Don't recreate the layout inline here — that's how drift happens.
If `setup-wiki` is not installed on this machine, **stop** and tell the user: project-bootstrap requires `setup-wiki` (and `setup-tasks`) installed. Don't fall back to ad-hoc creation.
**Reference (for context only — `setup-wiki` is the source of truth):** the canonical layout per Karpathy (gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) and `using-wiki`:
```
.wiki/
CLAUDE.md ← schema: project-specific wiki conventions
index.md ← catalog of all pages (by type), updated on every ingest
log.md ← append-only op log: ## [YYYY-MM-DD] op | desc
overview.md ← single human-readable project overview
raw/
README.md ← raw/ is immutable; this file documents that
entities/ ← entity pages (people, services, modules) — empty .gitkeep
concepts/ ← concept / design decision pages — empty .gitkeep
packages/ ← package pages — empty .gitkeep
sources/ ← one summary per ingested source — empty .gitkeep
```
Page-level workflow (ingest, query, lint) and file formats are owned by the
`wiki-maintainer` skill. Bootstrap only lays the skeleton; the skill takes
over from there.
### `.wiki/CLAUDE.md` (schema)
```markdown
# Wiki Schema — <project name>
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
- `entities/` — discrete things the project tracks (people, services, modules).
- `concepts/` — recurring ideas, design decisions, gotchas.
- `packages/` — code packages this project produces or consumes.
- `sources/` — one summary page per ingested external doc; frontmatter carries `ingested:` and `raw_path:`.
- `overview.md` — single project-wide overview.
## Naming
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter.
## Domain conventions
<!-- Fill in as the project takes shape — what counts as an entity here, which packages exist, naming idioms specific to this codebase. -->
```
### `.wiki/index.md`
```markdown
# Wiki Index
Catalog of all wiki pages. One line per page, organized by type. The agent updates this on every ingest.
## Overview
- [overview.md](overview.md) — project overview
## Entities
<!-- (none yet) -->
## Concepts
<!-- (none yet) -->
## Packages
<!-- (none yet) -->
## Sources
<!-- (none yet) -->
```
### `.wiki/log.md`
```markdown
# 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`.
---
## [<today's date>] init | bootstrap empty wiki via project-bootstrap
```
### `.wiki/overview.md`
```markdown
# <project name> — overview
<!-- Replace with a high-level description: what this project does, who it's for, the main components. -->
```
### `.wiki/raw/README.md`
```markdown
# Raw Sources
**Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit.
Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files.
For large or path-sensitive sources that live outside the repo, register them here:
\`\`\`
- short-name → /absolute/path/to/source
\`\`\`
```
The empty subdirectories (`entities/`, `concepts/`, `packages/`, `sources/`)
each get a `.gitkeep` so git tracks them.
---
## Step 4 — .tasks/
**Delegate to the `setup-tasks` skill.** It handles greenfield creation, migration from flat STATUS.md, and the no-op case uniformly, with its own confirmation gate. Don't recreate the layout inline.
If `setup-tasks` is not installed, **stop** and tell the user — same rule as Step 3.
**Reference (for context only — `setup-tasks` is the source of truth):** the canonical layout is `.tasks/STATUS.md` (the board, with emoji status 🔴/🟡/⚪/🟢/🔵) plus `.tasks/<task-slug>.md` per active or paused task. The full pattern is documented in this repo at `.wiki/raw/setup-task-status-wiki.md`.
---
## Step 5 — CLAUDE.md
Two paths, picked by file presence:
### Init (file does not exist)
Create `CLAUDE.md` from `assets/CLAUDE.md.template`. Substitute the platform line
on non-Windows hosts (`we're on Linux` / `we're on macOS` instead of
`we're on Windows`).
### Upgrade (file exists) — idempotent merge
Treat the template as the canonical trigger set and reconcile the existing file
against it. Re-runs are no-ops once the file is in canon.
1. Read the existing `CLAUDE.md`.
2. For each non-empty, non-comment line in the template, decide whether it's
already present:
- **Trigger lines** (everything except the platform line) — present iff any
existing line, after `trim` + `tolower`, contains the template line's
trigger text. Substring match, not equality — tolerates user rewording or
trailing punctuation.
- **Platform line** (`we're on Windows`) — present iff any existing line
matches `we're on (windows|linux|macos)` case-insensitively. If the user
pinned a different platform on purpose, **leave it alone**. Only append
the host-appropriate platform line when none of the three is present.
3. Collect missing lines. If none → print `CLAUDE.md already canon — no changes`
and skip to Step 5.5.
4. Show the user the diff (N lines, exact text to append) and ask one question:
"Append these N missing canonical triggers to the end of CLAUDE.md?" Wait
for explicit confirmation before writing.
5. On confirm: append a single newline (if the file doesn't end with one) and
then the missing lines, one per line. Don't rewrite the file — only append.
Don't reorder existing lines. Don't dedupe within the existing file.
Template contents (`assets/CLAUDE.md.template` — source of truth):
```markdown
# CLAUDE.md
# Agent instructions. Each line is a trigger for an installed skill.
talk like a caveman
use superpowers
use project wiki
use task management system
check across all projects
pull remote before work
follow project discipline
delegate to interns when allowed
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 `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
requests like "sync"). It's a no-op outside git repos and skips with a one-line
warning if the working tree is dirty, HEAD is detached, or the branch has no
upstream — never auto-merges, stashes, or pushes. Install the skill on the host
if `pulling-before-work` is not in `~/.claude/skills/`; otherwise the trigger is
silently dead like any other absent skill.
The `follow project discipline` line activates the `project-discipline` skill,
which codifies four cross-project rules: (1) project CLAUDE.md / .wiki/CLAUDE.md
/ .tasks/ override defaults from any other skill; (2) all work on master/main,
no feature branches without explicit user approval; (3) version bump on every
edit of versioned artifacts per semver, recorded in commit; (4) commit freely,
push only after explicit per-session approval. Install the skill on the host
if `project-discipline` is not in `~/.claude/skills/`; otherwise the trigger is
silently dead like any other absent skill.
The `delegate to interns when allowed` line activates the `using-interns` skill,
which lets Claude offload predictable bulk I/O and summarization tasks
(reading 3+ files, distilling long transcripts) to cheap intern LLMs via the
local `interns` MCP server (`mcp__interns__bulk_text_read`,
`mcp__interns__transcript_distill`, etc.) — saves Anthropic quota at ~125× the
per-call cost reduction on bulk reads. Per-session permission grant mirrors
`project-discipline` Rule 4: ask-mode default, conversational grant / revoke,
always-ask paths for `.env` / secrets / keys / SSH credentials even with an
active grant, session-end reset. The skill is a no-op until the `interns` MCP
server is registered — install via `setup-interns` on a fresh machine if
`mcp__interns__*` tools are missing. Full design at
`.wiki/concepts/interns-design.md` in the `claude-skills` repo.
The `we're on Windows` line activates the `active-platform` skill and pins the
project's default platform to Windows / PowerShell — so generated commands and
README quick-starts use PS-native syntax. Bootstrapping on a Linux or macOS
host? Substitute `we're on Linux` or `we're on macOS` instead.
---
## Step 5.5 — Bootstrap manifest
Write `.wiki/concepts/bootstrap-manifest.md`. The manifest records which skills (and at which versions) initialized this project's `.wiki/` and `.tasks/` layout, so layout drift between projects bootstrapped at different times is debuggable.
Read each delegated skill's `SKILL.md` frontmatter to pick up the live `version:` value (don't hardcode):
```markdown
---
title: Bootstrap Manifest
type: concept
updated: <today's date>
generator: project-bootstrap@<version>
---
# Bootstrap Manifest
Skills used to initialize this project's `.wiki/` and `.tasks/` layout, with their versions at install time.
| Skill | Version | Role |
|---|---|---|
| `project-bootstrap` | <version> | orchestrator |
| `setup-wiki` | <version> | wiki canonical layout |
| `setup-tasks` | <version> | tasks canonical layout |
| `project-discipline` | <version> | cross-project policy |
| `setup-interns` | <version> | interns MCP server install (one-time, per machine) |
| `using-interns` | <version> | interns runtime policy + per-session permission grant |
This file is overwritten if `project-bootstrap` is re-run on the same project. For history, use `git log .wiki/concepts/bootstrap-manifest.md`.
```
If a delegated setup-skill is unavailable on this machine (e.g. user installed only a subset), record the missing skill as `unknown` in the version column so the gap is visible.
---
## Step 5.6 — Skill dependencies check (chat-only, never auto-install)
The `CLAUDE.md` template just written contains canonical trigger lines.
Each one is a no-op unless the corresponding skill or plugin is installed
on the host. On a fresh machine these are often absent, and the user
won't know the trigger is silently dead. Detect what's missing on this
machine and print one informational block in chat — never write into any
project file, never auto-install.
### Trigger → fulfiller map
Source of truth for this map is the canonical `assets/CLAUDE.md.template`.
When a new trigger is added there, also add a row here in the same commit.
Mismatch between template and map → silent gaps in the recommendation.
| Trigger line in `CLAUDE.md` | Fulfiller | Kind | Detection path | Install command |
|---|---|---|---|---|
| `talk like a caveman` | `caveman` | skill | `~/.claude/skills/caveman/SKILL.md` | `bash scripts/install.sh caveman` |
| `use superpowers` | `superpowers@claude-plugins-official` | plugin | key `plugins["superpowers@claude-plugins-official"]` in `~/.claude/plugins/installed_plugins.json` | `/plugin install superpowers@claude-plugins-official` |
| `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` |
| `pull remote before work` | `pulling-before-work` | skill | `~/.claude/skills/pulling-before-work/SKILL.md` | `bash scripts/install.sh pulling-before-work` |
| `follow project discipline` | `project-discipline` | skill | `~/.claude/skills/project-discipline/SKILL.md` | `bash scripts/install.sh project-discipline` |
| `follow tdd-criteria` | `tdd-criteria` | skill | `~/.claude/skills/tdd-criteria/SKILL.md` | `bash scripts/install.sh tdd-criteria` |
| `delegate to interns when allowed` | `using-interns` | skill | `~/.claude/skills/using-interns/SKILL.md` | `bash scripts/install.sh using-interns` |
| `recommend, don't menu` | `recommend-dont-menu` | skill | `~/.claude/skills/recommend-dont-menu/SKILL.md` | `bash scripts/install.sh recommend-dont-menu` |
| `we're on Windows` / `we're on Linux` / `we're on macOS` | `active-platform` | skill | `~/.claude/skills/active-platform/SKILL.md` | `bash scripts/install.sh active-platform` |
### Algorithm
1. Read the project's `CLAUDE.md` (just-written or pre-existing). Extract
every non-empty, non-comment line — these are the active triggers for
THIS project. The user may have removed canonical lines on purpose;
respect that — only check what's actually in the file.
2. Match each line against the trigger column above using `trim` + `tolower`
substring (same matching as Step 5 idempotent merge). Lines that don't
match any row are user-custom — skip silently. The platform line matches
the `active-platform` row regardless of which platform is pinned.
3. For each matched canonical line, check the detection path:
- `kind: skill` → does `~/.claude/skills/<name>/SKILL.md` exist?
- `kind: plugin` → does `~/.claude/plugins/installed_plugins.json` contain
the plugin key under `plugins`? (Treat malformed JSON as "missing" and
continue — don't crash the bootstrap over a detection edge case.)
4. Collect every fulfiller that's missing. Two outcomes:
- **All present** — print one line:
```
✅ all skill dependencies satisfied — every CLAUDE.md trigger has its fulfiller on this host.
```
Skip to Step 6.
- **Some missing** — print one block in chat exactly once. Do **not**
write it into any project file:
```
ℹ️ Recommended: install the following to fulfill CLAUDE.md triggers
The triggers below are present in CLAUDE.md but their fulfillers are
missing on this machine — they're silently no-ops until installed:
trigger fulfiller (kind)
<trigger-line> <fulfiller> (<kind>)
<trigger-line> <fulfiller> (<kind>)
…
Install (run inside Claude Code or terminal):
<install command 1>
<install command 2>
…
After install + (for plugins) a Claude Code restart, the triggers pick
them up.
```
### Notes
- **MCP-server-backed skills** (`using-context7`, `using-projects-meta`,
`using-interns`) — only the `using-X` policy skill is checked here. If
the MCP isn't registered, the `using-X` Prerequisites pointer fires
`setup-X` at first use; bootstrap doesn't duplicate that detection.
- The `~/.claude/skills/` and `~/.claude/plugins/` paths resolve identically
on Windows / Linux / macOS — `~` works under git-bash too.
- **Hard rule — never auto-install.** Slash commands aren't callable from a
skill, and silently mutating user-level skill / plugin state without
consent is overreach. The recommendation is informational. The user can
install some / all / none of the recommendations, or remove canonical
lines from `CLAUDE.md` to lean the project's trigger set down.
## Step 6 — Commit
```bash
git add .
git commit -m "chore: bootstrap project structure"
```
If the repo already had commits — commit only the files just created:
```bash
git add .wiki/ .tasks/ CLAUDE.md .gitignore README.md
git commit -m "chore: upgrade project structure"
```
---
## Step 7 — Summary
Print a final report:
```
✅ Done! Created:
.wiki/ — project wiki (Karpathy method)
.tasks/ — task tracking system
CLAUDE.md — skill triggers
.gitignore — standard template
README.md — starter file
remote — Gitea repo created and pushed
Skipped (already existed):
git — left untouched
Next step: describe the project in README.md and start your first task —
say "use task management system".
```
For **greenfield-full** mode, append to summary:
```
Remote: <Gitea URL>
```
---
## Step 8 — projects-meta sync (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.
```bash
# POSIX:
node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js
# Windows PowerShell:
node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js
```
Verify the project is now visible:
```bash
# Via MCP (if available in current session):
# mcp__projects-meta__meta_status
# Or manually check the cache file exists:
ls -la ~/projects/.common/lib/projects-meta-mcp/cache/projects.json
```
If the sync script doesn't exist → skip with informational message:
```
ℹ️ projects-meta sync script not found at ~/projects/.common/lib/projects-meta-mcp/dist/sync.js
Run /setup-projects-meta to install it. The new repo is already created in Gitea.
```
---
## Rules
- **Never overwrite** existing files without explicit user confirmation
- **Always show the plan first** — one question, one confirmation
- **Never invent details** — if the project already exists, read what's there
- **Commit only what was just created** — do not touch the rest of the file tree
- **Commit automatically** after each successful step, no extra questions
- **Push only after explicit user confirmation** — ask "Push to remote?" and wait for "yes"

29
dist-hermes/software-development/project-bootstrap/assets/.gitignore.template Normal file
View File

@@ -0,0 +1,29 @@
# Dependencies
node_modules/
.venv/
__pycache__/
*.pyc
# Build outputs
dist/
build/
*.egg-info/
# Environment
.env
.env.local
.env.*.local
# IDE
.idea/
.vscode/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
# Logs
*.log
logs/

14
dist-hermes/software-development/project-bootstrap/assets/CLAUDE.md.template Normal file
View File

@@ -0,0 +1,14 @@
# CLAUDE.md
# Agent instructions. Each line is a trigger for an installed skill.
talk like a caveman
use superpowers
use project wiki
use task management system
check across all projects
pull remote before work
follow project discipline
follow tdd-criteria
delegate to interns when allowed
recommend, don't menu
we're on Windows

24
hermes/mapping.yaml
View File

@@ -93,30 +93,18 @@ skills:
# ─── pending (10 — deferred to follow-up tasks) ──────────────────────
setup-tasks:
mode: pending
reason: "Pending hermes-mvp-coverage."
intended:
mode: auto
category: productivity
using-tasks:
mode: pending
reason: "Pending hermes-mvp-coverage."
intended:
mode: auto
category: productivity
setup-wiki:
mode: pending
reason: "Pending hermes-mvp-coverage. Hermes ships research/llm-wiki — our schema is preserved via override-precedence."
intended:
mode: auto
category: research
using-wiki:
mode: pending
reason: "Pending hermes-mvp-coverage. Hermes ships research/llm-wiki — our schema is preserved via override-precedence."
intended:
mode: auto
category: research
@@ -126,9 +114,6 @@ skills:
category: mcp
using-projects-meta:
mode: pending
reason: "Pending hermes-mvp-coverage."
intended:
mode: auto
category: mcp
@@ -138,22 +123,13 @@ skills:
category: mcp
using-context7:
mode: pending
reason: "Pending hermes-mvp-coverage."
intended:
mode: auto
category: mcp
project-bootstrap:
mode: pending
reason: "Pending hermes-mvp-coverage. Orchestrator — adapts last; CLAUDE.md trigger-lines drop (Hermes auto-discovers)."
intended:
mode: auto
category: software-development
recommend-dont-menu:
mode: pending
reason: "Added 2026-05-06 after the original audit. Cross-agent applicability claimed (response-style rule) — Hermes-side audit not yet done."
intended:
mode: auto
category: productivity