diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index cc62075..f883d0d 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -1,6 +1,34 @@ # Task Board _Updated: 2026-04-28_ +## In Progress + +### Versioning + setup/using split for wiki & tasks +**Goal:** version 6 infra skills (`1.0.0`), record them in a per-project bootstrap manifest, then split `wiki-maintainer`/`task-status-wiki` into `setup-X`/`using-X` pairs (mirroring context7) so bootstrap delegates to setup-skills and using-skills self-bootstrap on missing infra. + +**Three commits:** + +#### (a) Versioning + manifest +- [x] Add `version: 1.0.0` to frontmatter of all 6 infra skills +- [x] `project-bootstrap` Step 5.5 writes `.wiki/concepts/bootstrap-manifest.md` (table read live from each delegated skill's frontmatter) +- [x] `concepts/skill-versioning.md` documents the convention; index + log updated +- [x] Build + install affected skills (loop in build.sh handles 6-arg invocation cleanly) + +#### (b) Split wiki +- [ ] Rename `skills/wiki-maintainer/` → `skills/using-wiki/`; update `name:` in frontmatter +- [ ] New `skills/setup-wiki/` (canonical layout creation, gated, derived from current "Bootstrap empty wiki" section + Karpathy gist) +- [ ] Prerequisites section in `using-wiki` → invokes `setup-wiki` if `.wiki/` is missing/non-canon +- [ ] `project-bootstrap` Step 3 delegates to `setup-wiki` + +#### (c) Split tasks +- [ ] Rename `skills/task-status-wiki/` → `skills/using-tasks/`; update `name:` +- [ ] New `skills/setup-tasks/` derived from `.wiki/raw/setup-task-status-wiki.md` + existing SKILL.md +- [ ] Prerequisites in `using-tasks` → invokes `setup-tasks` +- [ ] `project-bootstrap` Step 4 delegates to `setup-tasks` + +**One-time, after all three:** +- [ ] Manual `rm -rf ~/.claude/skills/{wiki-maintainer,task-status-wiki}/` (the old names) once the renamed installs are in place + ## Done ### Create `setup-context7` skill diff --git a/.wiki/concepts/skill-versioning.md b/.wiki/concepts/skill-versioning.md new file mode 100644 index 0000000..ee7f050 --- /dev/null +++ b/.wiki/concepts/skill-versioning.md @@ -0,0 +1,48 @@ +--- +title: Skill versioning + bootstrap manifest +type: concept +updated: 2026-04-28 +--- + +# Skill versioning + bootstrap manifest + +## Why version skills + +When the canonical layout for `.wiki/` or `.tasks/` changes (as it has — see [wiki-realignment.md](wiki-realignment.md) and the upcoming task-tracking realignment), projects bootstrapped under the old version drift out of canon silently. Without a record of *which version* did the bootstrap, debugging that drift is guesswork. + +The fix is two-sided: skills carry a version, and `project-bootstrap` records which versions it used in a per-project manifest. + +## Frontmatter format + +The 6 infra skills (`project-bootstrap`, `setup-context7`, `setup-wiki`, `setup-tasks`, `using-wiki`, `using-tasks`, `using-context7`, `using-markitdown`) carry `version: ` in their frontmatter: + +```yaml +--- +name: project-bootstrap +version: 1.0.0 +description: … +--- +``` + +Semver: +- **MAJOR** — breaks the contract (renames, layout changes, trigger-phrase removals). +- **MINOR** — adds capability (new triggers, new optional steps). +- **PATCH** — wording / clarity tweaks; no behavioral change. + +Bumped manually when `SKILL.md` is edited. No CI gate — discipline-based. + +## What skills are versioned + +Currently only the **infrastructure** skills (the ones bootstrap touches and that govern project layout). Communication-mode skills (`caveman`, family) and discovery skills (`find-skills`, `active-platform`) aren't versioned — their content is "good copy-paste" and a snapshot mismatch isn't a layout problem. + +If we ever start packaging or marketplace-publishing the rest, we'll version them too. + +## The manifest + +`project-bootstrap` writes `.wiki/concepts/bootstrap-manifest.md` with a frontmatter block + a small table of skill + version + role. The file is **overwritten** on re-bootstrap (not appended) — for history, `git log` shows the changes over time. + +## Why this matters + +Concrete scenario: you discover that some old project's `.tasks/STATUS.md` doesn't follow the canon (no per-task files, no emoji status). Look at its `bootstrap-manifest.md` — if it shows `setup-tasks: 1.0.0` but the current canon is from `2.0.0`, you know exactly what happened and can re-run `setup-tasks` to migrate. + +Without the manifest: `git log` of the project's `.tasks/` folder, guess from filenames, hope. diff --git a/.wiki/index.md b/.wiki/index.md index 797679e..9260799 100644 --- a/.wiki/index.md +++ b/.wiki/index.md @@ -16,6 +16,7 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever - [build-notes.md](concepts/build-notes.md) — why `build.ps1` exists alongside `build.sh`; PS 5.1 backslash-in-zip gotcha; how to extract a `.skill` - [context7-setup.md](concepts/context7-setup.md) — switched context7 from manual MCP entries to the official plugin; API key in `.mcp.json` as `--api-key`; now also captured as `setup-context7` skill (one-time install/migrate flow with key discovery) - [repo-layout.md](concepts/repo-layout.md) — flat `skills/`, committed `dist/`, bash + PowerShell scripts; install model +- [skill-versioning.md](concepts/skill-versioning.md) — why infra skills carry `version: ` in frontmatter and how `project-bootstrap` records them in a per-project manifest - [skill-vs-plugin.md](concepts/skill-vs-plugin.md) — when a bare SKILL.md is enough vs when you actually need a plugin (slash commands, hooks, sub-agents, MCP servers); concrete breakdown of `superpowers` - [wiki-realignment.md](concepts/wiki-realignment.md) — fixing `project-bootstrap` to create the Karpathy-canonical wiki layout diff --git a/.wiki/log.md b/.wiki/log.md index a0406ab..e9654f9 100644 --- a/.wiki/log.md +++ b/.wiki/log.md @@ -22,3 +22,4 @@ Parseable: `grep "^## \[" .wiki/log.md | tail -20`. ## [2026-04-28] decision | setup-context7 skill — formalized the install/migrate algorithm; using-context7 gets a Prerequisites pointer; build.sh PS multi-arg bug fixed (loop instead of comma-joined -Names) ## [2026-04-28] verify | setup-context7 — Vitya ran using-context7 in a session that needed setup; Prerequisites pointer triggered setup-context7; full flow worked end-to-end. Pattern (policy + setup split) validated. ## [2026-04-28] decision | skill-vs-plugin — documented when a bare skill suffices vs when a plugin is required (slash commands, hooks, sub-agents, MCP via marketplace) +## [2026-04-28] decision | skill-versioning — added `version: 1.0.0` to 6 infra skills' frontmatter; project-bootstrap now writes .wiki/concepts/bootstrap-manifest.md per project diff --git a/.wiki/raw/setup-task-status-wiki.md b/.wiki/raw/setup-task-status-wiki.md new file mode 100644 index 0000000..da62141 --- /dev/null +++ b/.wiki/raw/setup-task-status-wiki.md @@ -0,0 +1,204 @@ +# task-status-wiki + +> An idea file for LLM agents. Copy-paste this into your agent (Claude Code, Cursor, Windsurf, etc.) +> and it will set up a task status tracking system in your monorepo. +> The agent builds the specifics in collaboration with you. + +--- + +## The Problem + +When working on multiple large tasks in parallel inside a monorepo, context is lost on every +switch. You have to re-explain: what was being done, why, what the current blocker is, +which files matter. This is expensive and error-prone. + +## The Pattern + +Maintain a small wiki inside the repo — a folder of plain markdown files — that an LLM agent +actively reads and updates as you work. The files store *compressed working context*, not +prose notes. When you switch tasks, you give the agent the relevant file and it is immediately +oriented without re-explanation. + +This follows the same principle as Karpathy's llm-wiki: knowledge should *accumulate* across +sessions, not be re-derived from scratch each time. + +--- + +## Structure to Create + +``` +.tasks/ + STATUS.md ← the board: one block per task, sorted by priority + .md ← deep context file per task +``` + +Place `.tasks/` at the monorepo root. Commit it to git — decision history is valuable, +and diffs show how thinking evolved. + +### Solo vs. team + +**Solo:** local commits are enough. No need to push `.tasks/` — history is preserved locally, +remote repo stays clean. + +**Team or multiple agents:** push `.tasks/` to remote. It becomes the shared source of truth. +Without it, each agent or person works from their own stale snapshot and statuses diverge. +Add a `**Owner:**` field to each STATUS.md block so it's clear who (or which agent) holds +the task at any moment. + +--- + +## STATUS.md — the board + +This is the first file you open when returning to work. One block per active task. +The agent updates it at the end of every session, or when asked. + +### Format + +```markdown +# Task Board +_Updated: YYYY-MM-DD_ + +## 🔴 [task-slug] — short description +**Status:** active | paused | blocked | done +**Owner:** person or agent name (team mode only — omit if solo) +**Where I stopped:** one sentence — the exact thought or action interrupted +**Next action:** one concrete step to resume immediately +**Blocker:** (if any) what is stopping progress +**Branch:** git branch name + +--- + +## 🟡 [task-slug] — short description +... +``` + +### Status emoji convention +- 🔴 Active — currently being worked on (only one at a time) +- 🟡 Paused — in progress, can be resumed +- ⚪ Ready — not started, fully defined +- 🟢 Done — completed, kept for reference until merged +- 🔵 Blocked — waiting on external input + +--- + +## Per-Task File — `.md` + +Created when a task starts. The agent maintains it throughout. This is the *compiled* +context — not raw notes, but synthesized understanding that would take too long to +re-derive from scratch. + +### Format + +```markdown +# + +## Goal +One paragraph. What this task achieves and why it matters in the monorepo context. + +## Key files +List of files central to this task, with one-line notes on their role. +- `path/to/file.ts` — what it does and why it matters here +- `path/to/other.ts:42` — specific line if relevant + +## Decisions log +Reverse-chronological. The agent appends here when a non-obvious decision is made. +- YYYY-MM-DD: Why we chose X over Y +- YYYY-MM-DD: Discovered constraint Z, adjusted approach + +## Open questions +- [ ] unresolved questions that block or affect design +- [ ] questions to discuss with teammates + +## Completed steps +- [x] steps that are done (agent moves items here from open questions or session notes) + +## Notes +Anything that doesn't fit above: temporary hypotheses, links to external context, +names of people to ask. +``` + +--- + +## Agent Operations + +These are the operations the agent performs. The agent should do them autonomously +without being asked each time. + +### On session start +1. If in team mode: `git pull` to sync `.tasks/` before reading anything +2. Read `STATUS.md` +3. If the user names a task, read its `.md` +4. Confirm current state 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 + +### On session end (or when user says "pause" / "switch") +1. Update `STATUS.md`: set current task to 🟡, update "Where I stopped" and "Next action" +2. Append to `.md` Decisions log any non-obvious choices made this session +3. Move completed steps to "Completed steps" +4. Commit: `git add .tasks/ && git commit -m "chore: update task status []"` +5. If in team mode: `git push` + +### On task switch +1. Perform session-end operations for the current task +2. Ask which task to switch to +3. Read the target `.md` +4. Set it to 🔴 in STATUS.md +5. Confirm orientation before starting work + +### On task creation +1. Ask: task name (becomes the slug), goal, known key files, branch name +2. Create `.md` with populated Goal and Key files sections +3. Add block to `STATUS.md` with status ⚪ +4. Create and checkout the branch if it doesn't exist + +### On task completion +1. Move all open questions to resolved or drop them +2. Set status to 🟢 in STATUS.md +3. Add a "Completed" line in Decisions log with final summary +4. Remind user to delete the branch after merge + +--- + +## Initialization Prompt (run once per project) + +When the user pastes this file into the agent for the first time, the agent should: + +1. Confirm it understands the pattern in one sentence +2. Ask: "What tasks are currently in flight? Give me their names and a one-line description." +3. For each task mentioned: ask for branch name, current status, and where work stopped +4. Create the `.tasks/` folder structure +5. Create `STATUS.md` with all tasks filled in +6. Create a `.md` for each active or paused task +7. Make an initial commit: `git add .tasks/ && git commit -m "chore: init task status wiki"` +8. Print the path to STATUS.md and say it's ready + +The agent must not invent task details — it asks for what it doesn't know. + +--- + +## Rules for the Agent + +- **Never lose "Where I stopped"** — this is the most important field. If unclear, ask before ending session. +- **One sentence per field** — STATUS.md fields are not prose. Compress. +- **Key files must be specific** — not "auth module" but `packages/auth/src/useAuth.ts:87`. +- **Decisions log is append-only** — never rewrite past entries, only add. +- **Commit after every session end** — the git log is the history of thinking. +- **Always confirm orientation** — at session start, state what you understand before acting. +- **If STATUS.md is stale** (last update > 3 days ago), flag it and ask the user to confirm current state. +- **Team mode:** always `git pull` before reading, always `git push` after committing. One 🔴 per owner — two people must not hold the same task active simultaneously. Use the `Owner:` field to make this visible. + +--- + +## Why This Works + +The key insight from Karpathy's pattern: an LLM should not re-derive context on every session. +It should read accumulated, compiled knowledge — the same way a compiler produces an artifact +you don't recompute every time. + +The `.tasks/` wiki is that artifact for engineering work. Each task file is a *compiled* +representation of: what was learned, what was decided, what remains. The agent's job is +to keep it accurate and compressed — not verbose, not a log dump, but the minimum a future +session needs to be immediately productive. + +The STATUS.md board adds fast navigation: glance at it, pick a task, load its file. +Two reads and you're back in context. diff --git a/dist/project-bootstrap.skill b/dist/project-bootstrap.skill index df80f68..a8a4bb5 100644 Binary files a/dist/project-bootstrap.skill and b/dist/project-bootstrap.skill differ diff --git a/dist/setup-context7.skill b/dist/setup-context7.skill index db6a3e2..277268d 100644 Binary files a/dist/setup-context7.skill and b/dist/setup-context7.skill differ diff --git a/dist/task-status-wiki.skill b/dist/task-status-wiki.skill index 9531555..679cfac 100644 Binary files a/dist/task-status-wiki.skill and b/dist/task-status-wiki.skill differ diff --git a/dist/using-context7.skill b/dist/using-context7.skill index 174e940..37630c7 100644 Binary files a/dist/using-context7.skill and b/dist/using-context7.skill differ diff --git a/dist/using-markitdown.skill b/dist/using-markitdown.skill index 5f8f2ef..05f271c 100644 Binary files a/dist/using-markitdown.skill and b/dist/using-markitdown.skill differ diff --git a/dist/wiki-maintainer.skill b/dist/wiki-maintainer.skill index 0e82793..4c21b21 100644 Binary files a/dist/wiki-maintainer.skill and b/dist/wiki-maintainer.skill differ diff --git a/skills/project-bootstrap/SKILL.md b/skills/project-bootstrap/SKILL.md index 8410fb6..00dba50 100644 --- a/skills/project-bootstrap/SKILL.md +++ b/skills/project-bootstrap/SKILL.md @@ -1,5 +1,6 @@ --- name: project-bootstrap +version: 1.0.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. @@ -256,6 +257,35 @@ 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: +generator: project-bootstrap@ +--- + +# Bootstrap Manifest + +Skills used to initialize this project's `.wiki/` and `.tasks/` layout, with their versions at install time. + +| Skill | Version | Role | +|---|---|---| +| `project-bootstrap` | | orchestrator | +| `setup-wiki` | | wiki canonical layout | +| `setup-tasks` | | tasks canonical layout | + +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 6 — Commit ```bash diff --git a/skills/setup-context7/SKILL.md b/skills/setup-context7/SKILL.md index 494b7b0..d27d93c 100644 --- a/skills/setup-context7/SKILL.md +++ b/skills/setup-context7/SKILL.md @@ -1,5 +1,6 @@ --- name: setup-context7 +version: 1.0.0 description: Installs and configures the official context7 MCP plugin (`context7@claude-plugins-official`), reuses the user's existing Context7 API key, and cleans out any manual `mcpServers.context7` entries from `~/.claude.json` and `~/.claude/settings.json`. Use this skill when the user says "install context7", "set up context7", "configure context7", "настрой context7", "установи context7", "context7 не работает", "context7 isn't working", or whenever the `mcp__context7__resolve-library-id` / `mcp__context7__query-docs` tools are missing in a session that needs library docs. Cross-platform — Windows / Linux / macOS. Mutates user-level config; pauses for confirmation before writing. --- diff --git a/skills/task-status-wiki/SKILL.md b/skills/task-status-wiki/SKILL.md index 53f4f1e..23eeb85 100644 --- a/skills/task-status-wiki/SKILL.md +++ b/skills/task-status-wiki/SKILL.md @@ -1,5 +1,6 @@ --- name: task-status-wiki +version: 1.0.0 description: > Manage a persistent task status wiki inside a monorepo using the .tasks/ folder pattern. Use this skill whenever the user is switching between tasks, resuming a paused task, diff --git a/skills/using-context7/SKILL.md b/skills/using-context7/SKILL.md index 1f68fc0..280c2c5 100644 --- a/skills/using-context7/SKILL.md +++ b/skills/using-context7/SKILL.md @@ -1,5 +1,6 @@ --- 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. --- diff --git a/skills/using-markitdown/SKILL.md b/skills/using-markitdown/SKILL.md index 20bcf77..1febec3 100644 --- a/skills/using-markitdown/SKILL.md +++ b/skills/using-markitdown/SKILL.md @@ -1,5 +1,6 @@ --- name: using-markitdown +version: 1.0.0 description: Use when capturing external content into a markdown-based knowledge base, wiki `raw/` directory, or any pipeline that must preserve the source's full text — for web pages, PDFs, DOCX/PPTX/XLSX, EPUB, CSV/JSON/XML, ZIP archives, images (with OCR/EXIF), audio (with transcription), or YouTube URLs. Also use when WebFetch returned an LLM-summarized version but the raw content is what's needed. --- diff --git a/skills/wiki-maintainer/SKILL.md b/skills/wiki-maintainer/SKILL.md index 26baefa..cc1f550 100644 --- a/skills/wiki-maintainer/SKILL.md +++ b/skills/wiki-maintainer/SKILL.md @@ -1,5 +1,6 @@ --- name: wiki-maintainer +version: 1.0.0 description: Use when a repo has a `.wiki/` directory following Karpathy's LLM Wiki pattern and the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "заингесть", "обнови вики", "проверь вики", "запроси вики", "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`. ---