diff --git a/skills/setup-tasks/README.md b/skills/setup-tasks/README.md new file mode 100644 index 0000000..ff7bdae --- /dev/null +++ b/skills/setup-tasks/README.md @@ -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 `.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 +└── .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- .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. diff --git a/skills/setup-wiki/README.md b/skills/setup-wiki/README.md new file mode 100644 index 0000000..7d2cedb --- /dev/null +++ b/skills/setup-wiki/README.md @@ -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: + + +## 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-/* .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: + diff --git a/skills/using-tasks/README.md b/skills/using-tasks/README.md new file mode 100644 index 0000000..497243f --- /dev/null +++ b/skills/using-tasks/README.md @@ -0,0 +1,139 @@ +# 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 + +``` +/ +└── .tasks/ + ├── STATUS.md ← board: one block per task, sorted by priority + └── .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 (`.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 `.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 `.md` Decisions log. +3. Move finished items to "Completed steps". +4. Commit: `git add .tasks/ && git commit -m "chore: update task status []"`. + +### Task switch + +1. Run session-end ops for the current task. +2. Read the target `.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 `.md` with Goal and Key files populated. +3. Add a ⚪ block to `STATUS.md`. +4. Create / checkout the branch if missing. + +### Task completion + +1. Resolve or drop all open questions. +2. Set status to 🟢 in `STATUS.md`. +3. Append a final summary line to the Decisions log. +4. Remind the user to delete the branch after merge. + +## 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`. + +## 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. diff --git a/skills/using-wiki/README.md b/skills/using-wiki/README.md new file mode 100644 index 0000000..f859dd2 --- /dev/null +++ b/skills/using-wiki/README.md @@ -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/.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/.md`, `concepts/.md`, `packages/.md` + (no `@org/` prefix), `sources/.md`. + +### `log.md` — append-only, grep-parseable + +Every entry must start with: + +``` +## [YYYY-MM-DD] | +``` + +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/`. +- URL-encode spaces (`%20`) and Cyrillic when needed. + +## Quick reference + +| Situation | Files touched | +|---|---| +| Ingest one doc | `sources/.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 | `. +- **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: +