diff --git a/skills/setup-tasks/README.md b/skills/setup-tasks/README.md deleted file mode 100644 index ff7bdae..0000000 --- a/skills/setup-tasks/README.md +++ /dev/null @@ -1,108 +0,0 @@ -# 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-tasks/SKILL.md b/skills/setup-tasks/SKILL.md deleted file mode 100644 index c21a5e4..0000000 --- a/skills/setup-tasks/SKILL.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -name: setup-tasks -author: ours -version: 1.1.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 `.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/.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: -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- - • 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/.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: _ - - -``` - -No per-task files at greenfield — they're created when actual tasks are added. - -**Task numbering (format v2).** Every task block header carries a **global task number**: `## ⚪ [#1234 task-slug] — …`. Numbers are assigned by the server (`mcp__projects-meta__tasks_create`) from the counter in `OpeItcLoc03/agenda/task-counter` — **never invent or reuse a number by hand**. The per-task file is named `yyyy-mm-dd-#####-.md` (number 5 digits with leading zeros, no `#`): `2026-06-05-00019-fix-nl-vds-reality-pq-dest.md`. In the header the number is written without leading zeros (`[#19 slug]`). Closed tasks move to `.tasks/done/` (see Phase 4c). - -### 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 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/yyyy-mm-dd-#####-.md` for each active or paused task using the per-task template (Goal, Key files, Decisions log, Open questions, Completed steps, Notes). File name format v2: date + 5-digit number (from the task's header `[#n slug]`) + slug, no `#`: `2026-05-08-00057-fbs-picking-list-pdf.md`. -6. Leave the `.bak-` file in place — historical record. - -Per-task template: - -```markdown -# - -## Goal -One paragraph. What this achieves and why it matters. - -## Key files -- `path/to/file.ts` — role in this task - -## Decisions log -- : migrated from flat STATUS.md via setup-tasks@ - -## Open questions -- [ ] (fill in) - -## Completed steps -- [x] (fill in) - -## Notes -``` - -### Phase 4c — done/ (format v2) - -Closed 🟢 tasks move their **per-task file** to `.tasks/done/` — the board keeps only 🔴 / 🟡 / ⚪ / 🔵 blocks. (The 🟢 block itself is archived from STATUS.md to `.tasks/.archive/done-YYYY-MM.md` — see `using-tasks`.) - -```bash -mkdir -p .tasks/done && git mv .tasks/yyyy-mm-dd-#####-slug.md .tasks/done/ -``` - -### Phase 5 — Verify - -After writes: - -- `.tasks/STATUS.md` exists and has the emoji status legend (or template comment block in greenfield). -- Every task block header is `## [#n slug] — …` (number present) and carries `**Created:** yyyy-mm-dd`. -- For migrate: each task referenced in STATUS.md has its `yyyy-mm-dd-#####-.md` file (active and paused only). -- No required content was lost (the `.bak` file is the safety net). - -If verification fails → restore from `.bak-` and report. - -### Phase 6 — Report - -Print final state: - -``` -✅ Tasks board ready at .tasks/. - Mode: greenfield | migrate - STATUS.md: > - Per-task files: - -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- .tasks/STATUS.md` (migrate rollback) and `rm .tasks/.md` for any newly created per-task files; if per-task files were moved to `.tasks/done/` during the migration, remove those too. -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. -- **Inventing or reusing a task number.** Never. Numbers come only from `tasks_create` (server counter). A hand-written number collides with the global counter. -- **File without 5-digit number** (`2026-06-05-19-slug.md`). Always `yyyy-mm-dd-#####-slug.md` — leading zeros, no `#`. -- **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 `.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. diff --git a/skills/setup-wiki/README.md b/skills/setup-wiki/README.md deleted file mode 100644 index 5ba64d8..0000000 --- a/skills/setup-wiki/README.md +++ /dev/null @@ -1,103 +0,0 @@ -# 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 + six 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 -├── contradictions/ ← surfaced tensions worth tracking long-term -└── open-questions/ ← unresolved questions raised during ingest/query -``` - -The six 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/setup-wiki/SKILL.md b/skills/setup-wiki/SKILL.md deleted file mode 100644 index c26ea2c..0000000 --- a/skills/setup-wiki/SKILL.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -name: setup-wiki -author: ours -version: 1.1.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/`, `contradictions/`, `open-questions/`. 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/`, `contradictions/`, `open-questions/` → 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: -Missing: -Non-canon: -``` - -### 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/, contradictions/, open-questions/ (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/, contradictions/, open-questions/ (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-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:`. -- `contradictions/` — surfaced tensions between sources or pages worth tracking long-term; each page cross-links the affected entities/concepts/sources and carries a status (`open` / `resolved` / `accepted-divergence`). -- `open-questions/` — unresolved questions raised during ingest or query that the wiki cannot answer yet; each page cross-links the pages/sources that touch the question and carries a status (`open` / `answered` / `obsolete`). -- `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 - - -``` - -**`.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 - - - -## Concepts - - - -## Packages - - - -## Sources - - - -## Contradictions - - - -## Open Questions - - -``` - -**`.wiki/log.md`** (op log; backfill an `init` line dated today): - -```markdown -# Wiki Log - -Append-only operation log. Format: - -\`\`\` -## [YYYY-MM-DD] | -\`\`\` - -Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`. - -Parseable: `grep "^## \[" .wiki/log.md | tail -20`. - ---- - -## [] init | wiki bootstrapped via setup-wiki@ -``` - -**`.wiki/overview.md`**: - -```markdown ---- -title: overview -type: overview -updated: ---- - -# — overview - - -``` - -**`.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/`, `contradictions/`, `open-questions/` 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 .wiki/contradictions .wiki/open-questions - -# 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/, contradictions/, open-questions/ -touch .wiki/entities/.gitkeep .wiki/packages/.gitkeep .wiki/sources/.gitkeep .wiki/contradictions/.gitkeep .wiki/open-questions/.gitkeep -``` - -For migrated `concepts/*.md` pages, **do not rewrite their content** — just prepend a minimal frontmatter if missing: - -```yaml ---- -title: -type: concept -updated: ---- -``` - -Build `index.md` with one entry per migrated `concepts/.md`, derived from the file's H1 and any one-liner the agent can extract. - -Append a line to `log.md`: - -``` -## [] refactor | wiki migrated to canon via setup-wiki@ -``` - -### Phase 5 — Verify - -After writes, confirm: - -- All canon files exist: `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`. -- Six content directories exist (`entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`) — 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 + 6 dirs + N migrated concept pages - Backup (if migrate): .wiki/.backup-/ - -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-/* .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. diff --git a/skills/using-tasks/README.md b/skills/using-tasks/README.md index aa560fe..95d095c 100644 --- a/skills/using-tasks/README.md +++ b/skills/using-tasks/README.md @@ -4,8 +4,9 @@ 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/). +`using-tasks` governs the task board. **Канал — mappa** (решение 14/15): борд = +сущности `type=task` в сервисе (см. SKILL.md v2.0.0). Файловый `.tasks/` — легаси; +`setup-tasks` умер. > Renamed from `task-status-wiki` at v1.0.0. @@ -17,8 +18,8 @@ migration to canon are owned by [`setup-tasks`](../setup-tasks/). "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. +- Борд читается из mappa (`entity_search(type='task', project=…)`); + файловый `.tasks/` — легаси, ничего настраивать не нужно. ## Structure @@ -70,8 +71,8 @@ hypotheses, links). ### Session start -1. Check `.tasks/STATUS.md`. If missing → invoke - [`setup-tasks`](../setup-tasks/) and stop until it returns. +1. Check the mappa board: `entity_search(type='task', project=<имя>)`. + Файлового `.tasks/STATUS.md` больше нет — setup-tasks умер. 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." @@ -163,7 +164,6 @@ 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. +- mappa — сервис-хост борда (`task_create`/`task_claim_next`/`task_close`, + per-type `t:N`). +- [`project-bootstrap`](../project-bootstrap/) — mappa-режим для новых проектов. diff --git a/skills/using-tasks/SKILL.md b/skills/using-tasks/SKILL.md index 9205ddd..324142c 100644 --- a/skills/using-tasks/SKILL.md +++ b/skills/using-tasks/SKILL.md @@ -1,289 +1,138 @@ --- name: using-tasks author: ours -version: 1.7.0 +version: 2.0.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 `.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. + Policy skill for working with the project task board in Mappa (решения 14/15: + мета в сервисе). Use whenever 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 tracking + progress across parallel workstreams. Board = сущности `type=task` в mappa + (чтение — карв-аут лиза; мутации — под лизом проекта, решение 19). Файловый + `.tasks/` — легаси; `setup-tasks` умер (нечего настраивать). --- # 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/.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 - -``` -/ - .tasks/ - STATUS.md ← active board: 🔴 / 🟡 / ⚪ / 🔵 blocks, sorted by priority - yyyy-mm-dd-#####-.md ← deep context per task, one file each (format v2) - done/ ← per-task files of closed 🟢 tasks (format v2) - .lock ← runtime session lock; **gitignored** (never committed) - .archive/ - done-YYYY-MM.md ← 🟢 done blocks moved off the board, one file per month -``` - -Commit `.tasks/` to git. Decision history is valuable; diffs show how thinking evolved. - -`STATUS.md` is the **active** board — it must stay lean so orientation reads stay cheap. Closed 🟢 tasks are archived to `.archive/done-YYYY-MM.md` once they pile up; their **per-task files** move to `.tasks/done/` (see "### Task completion" step 7). - -> **`.tasks/.lock` must be listed in `.gitignore`** (add `.tasks/.lock` to your project's `.gitignore`). The lock file is ephemeral runtime state, not project history — it must never be committed. - ---- - -## STATUS.md format - -```markdown -# Task Board -_Updated: YYYY-MM-DD_ - -## 🔴 [#1234 task-slug] — short description -**Status:** active | paused | blocked | done -**Created:** YYYY-MM-DD -**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 -**Session break:** (optional) `true` — or a hint string for the next track. Marks this task as a session boundary. -**Branch:** git branch name - ---- -``` - -**Task numbering (format v2).** Every block header carries a **global task number**: `## [#1234 slug] — …`. The number is the machine key — global, unique across the federation, encodes creation order. Numbers are assigned by the server (`mcp__projects-meta__tasks_create`) from the counter in `OpeItcLoc03/agenda/task-counter`; **never invent or reuse a number by hand** (a hand-written number collides with the counter). Per-task files are named `yyyy-mm-dd-#####-.md` — number 5 digits with leading zeros, no `#` (folder sort = numeric). References in text use the number: `#452`. - -**Emoji convention:** -- 🔴 Active — currently worked on (only one at a time) -- 🟡 Paused — in progress, resumable -- ⚪ Ready — not started, fully defined -- 🟢 Done — completed; kept on the board until merged, then archived (see "### Archiving done tasks") -- 🔵 Blocked — waiting on external input - -### `session_break` marker - -A task may carry a `session_break` marker — set by whoever defines the task (e.g. the delegating workshop) when its completion is a natural place to stop and start a fresh session. It signals an autonomous agent: *finish this task, then pause instead of immediately claiming the next one.* - -- **Type:** boolean or string. - - `session_break: true` — pause after close; the next track is "see STATUS.md". - - `session_break: ""` — pause after close; `` names the recommended next track. -- **Where it lives:** in the task's frontmatter when delivered via the task system (`session_break: true` / `session_break: ""`); mirrored on the local board as the optional `**Session break:**` field in the task's STATUS.md block. -- **Absent →** behaviour is unchanged: close the task and continue as usual. - -The check is enforced in the **Task completion** flow below (after close, before claiming the next task). - ---- - -## Per-task file format (`yyyy-mm-dd-#####-.md`) - -```markdown -# - -## 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. -``` - -The file name mirrors the header: date + 5-digit number + slug, e.g. `2026-06-05-00019-fix-nl-vds-reality-pq-dest.md` for header `[#19 fix-nl-vds-reality-pq-dest]`. - ---- - -## Agent operations - -### Session start -1. **Session lock guard.** If `.tasks/` exists, read `.tasks/.lock`. - - **Active agent lock** — `type:"agent"` with `heartbeat` ≤ 10 minutes old: print the hard warning below and **require explicit user confirmation** before proceeding. Do not touch the board until the user confirms. - ``` - ⚠️ поллер ведёт — нельзя работать параллельно - ``` - (Substitute the `slug` field from the lock file if present, otherwise omit it.) - - **Stale lock** — any type whose TTL has expired (`type:"agent"` with `heartbeat` > 10 min ago; `type:"interactive"` with `started_at` > 2 h ago): silently overwrite. - - **Absent or stale lock** (including after user confirmation): write `.tasks/.lock`: - ```json - {"type":"interactive","started_at":"","ttl_minutes":120} - ``` -2. Check if `.tasks/STATUS.md` exists. If not → invoke `setup-tasks` and stop here until it returns. -3. Read `STATUS.md` — this is the orientation read (see note below on why it's a local read, not an MCP call). -4. If user names a task, read its `.md`. -5. Confirm in one sentence: "We're in the middle of X, next step is Y." -6. Ask if the plan is still correct before doing anything. -7. If STATUS.md `_Updated` date is >3 days ago, flag it and ask user to confirm current state. -8. If `STATUS.md` holds **≥ 10** 🟢 done blocks, archive them first (see "### Archiving done tasks") so the board you orient on is lean. - -> **Orient by reading the local `STATUS.md`, not an MCP call.** It is the live board and — kept lean by archival — cheap to read. Do **not** reach for projects-meta tools to enumerate the current project's board: -> - `tasks_aggregate` is cache-based, cross-project, and does **not** index ready/done — its own docs say to read `.tasks/STATUS.md` directly for the current project. -> - `tasks_get_status(target_project, slug)` returns a **single** task's live status (`{status, found}`) by a slug you already know — it cannot list the board. Use it only to check **one** known task (e.g. confirm a delegated task's board state, or detect async-human parking), never for orientation. - -### Session end / pause / switch -1. **Release session lock.** If `.tasks/.lock` exists and contains `"type":"interactive"`: delete `.tasks/.lock`. (Stale interactive locks are cleaned up here too; silently delete any interactive lock regardless of TTL.) -2. Update `STATUS.md`: set current task to 🟡, update "Where I stopped" and "Next action". -3. Append to `.md` Decisions log any non-obvious choices made this session. -4. Move finished items to "Completed steps". -5. Commit: `git add .tasks/ && git commit -m "chore: update task status []"` - -### Task switch -1. Perform session-end operations for the current task. -2. Read the target `.md`. -3. Set it to 🔴 in STATUS.md (demote previous active to 🟡). -4. Confirm orientation before starting work. - -### New task creation - -1. **Create via the server, not by hand.** New tasks are created with `mcp__projects-meta__tasks_create` — the server assigns the global number from the counter and writes the header `[#n slug]`, the `**Created:**` field, and the per-task file `yyyy-mm-dd-#####-.md`. Hand-editing a new block into STATUS.md with an invented number collides with the counter — don't. -2. Ask: task name (slug), goal, known key files, branch name. -3. After the server create: fill `` content (Goal and Key files) into the per-task file `yyyy-mm-dd-#####-.md`. -4. Create and checkout branch if it doesn't exist. - -Exceptions (hand-edited board): migration, retro-fitting existing tasks, or a board whose project is not in the federation cache. In those cases take the next number from `OpeItcLoc03/agenda/task-counter` (read → +1 → write) before writing the block. - -### Design-derived impl tasks — review umbrella - -When creating **N≥1 implementation tasks derived from a design/spec** (not -ad-hoc), also create the review umbrella: - -- slug: `-review` -- status: `blocked` -- blocker: the impl-task slugs (`-impl-1, -impl-2, …`) -- next_action: «Дождаться 🟢 у всех blocker-тасок, затем отревьюить каждую - против acceptance criteria из дизайна. Findings → follow-up tasks.» -- **reviewer contract: не имплементер** — следующая сессия в проекте с - чистым контекстом (борьба с «я только что это написал» bias). - -The umbrella is the only mechanism that guarantees a non-implementer review: -`workshop-promote-brainstorm` generates it for the boss-flow, this rule -covers in-project designs. Skip for ad-hoc single tasks and for -self-implemented work closed with the coverage check. - -### Task completion -1. **Pre-close coverage check.** Before setting 🟢: - - List acceptance criteria from the per-task `.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. **Notify-письмо при закрытии (кросс-проектные таски).** Если закрываемая - таска пришла из другого проекта (в блоке есть `**Notify:**` или - ``) — отправить письмо - комиссионеру в его инбокс: `/.agents/inbox/Z-<своя-папка>.md`, - frontmatter `event: closed`, `slug: `, тело = итог (сделано, - acceptance, ссылки). Поллер пишет это письмо за авто-раны; **живая сессия - пишет сама** — статус 🟢 на борде ≠ комиссионер узнал. -5. Append final summary line to Decisions log. -6. Remind user to delete the branch after merge. -7. **Move the per-task file to `.tasks/done/`** (format v2): `git mv .tasks/yyyy-mm-dd-#####-.md .tasks/done/`. The board block is 🟢 (archived to `.archive/done-YYYY-MM.md` when it piles up); the deep-context file leaves the active folder. -8. **Session-break check (after close, before claiming the next task).** Once the task is 🟢 and committed — and **before** any `tasks_claim_next` or starting the next task — read the closed task's `session_break` marker (its frontmatter `session_break`, or the `**Session break:**` field in its STATUS.md block). If present: - - Print this line **verbatim**, substituting the closed task's slug for `[slug]` and the marker's string value for `[value | "см. STATUS.md"]` (use the literal `см. STATUS.md` when the marker is just `true`): - - `🔚 SESSION BOUNDARY — [slug] закрыта. Рекомендую завершить текущую сессию. Следующий трек: [value | "см. STATUS.md"]` - - - **Stop.** Do not claim or start the next task. - - If the marker is absent → behaviour is unchanged: proceed to claim / start the next task as usual. -9. **Archival check.** After the close is committed, if `STATUS.md` now holds **≥ 10** 🟢 done blocks, archive them (see "### Archiving done tasks"). This keeps the board lean for the next orientation read. - -### Archiving done tasks - -🟢 done blocks accumulate in `STATUS.md` and bloat it — and since orientation reads the whole board, a bloated file burns context on every session start (the recurring "huge STATUS.md" complaint). Keep the board lean: done blocks stay only until merged, then move to a monthly archive. - -**Threshold.** When `STATUS.md` holds **≥ 10** 🟢 done blocks, archive them. Check at two moments: (a) right after closing a task (Task completion step 9), and (b) at session start, before orienting (Session start step 7). The threshold is a ceiling, not a target — archive in batches; don't churn one block at a time. - -**Where.** Append the archived blocks to `.tasks/.archive/done-YYYY-MM.md` — one file per calendar month, keyed by the date of archival. Create `.tasks/.archive/` and the month file if absent. If the month file already exists, **append**; never overwrite. - -**Archive file format** (header written once, on file creation): - -```markdown -# Archived done tasks — YYYY-MM - -Moved out of `.tasks/STATUS.md` to keep the active board lean. -Full source is git history; this file is for grep-able historical context. - ---- -``` - -…followed by each 🟢 block **verbatim** (including its trailing `---` separator and any `` comments). - -**After archiving,** `STATUS.md` keeps only 🔴 / 🟡 / ⚪ / 🔵 blocks. Commit the move on its own: - -``` -git add .tasks/ && git commit -m "meta(tasks): archive done batch → .tasks/.archive/done-YYYY-MM.md" -``` - -Leave a just-closed 🟢 block on the board only while it's still useful at a glance (pending merge, fresh reference). Everything older goes to the archive. - -### Post-commit task closure prompt - -After any implementation commit (`feat:` / `fix:` / similar), prompt the user once: - -> Эта работа закрывает таску ``? - -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 - -- **Honour `.tasks/.lock`** — read the lock at session start before touching the board; write it after clearing the guard; delete it at session end/pause. Never skip the lock check when `.tasks/` exists. The lock file must be gitignored. -- **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. -- **Keep the board lean** — orientation reads the local `STATUS.md` whole, so archive 🟢 done blocks to `.tasks/.archive/done-YYYY-MM.md` once ≥10 pile up. Never enumerate the current project's board via `tasks_aggregate` (cross-project cache) or `tasks_get_status` (single-task, by slug). See "### Archiving done tasks". -- **Never close a task without a coverage check** — see "### Task completion" step 1. Acceptance criteria with no evidence → ask, don't auto-close. -- **Honour `session_break`** — a closed task carrying a `session_break` marker means stop after close; never chain into `tasks_claim_next`. See "### Task completion" step 8. -- **Local-first recommendations** — cwd-project board comes first; cross-project urgents are at most one footnote line. -- **Notify-письмо при закрытии** — кросс-проектная таска закрыта → письмо комиссионеру (event: closed). Поллер пишет за авто-раны; живая сессия — сама. See "### Task completion" step 4. -- **Design → impl tasks ⇒ review umbrella** — N≥1 impl tasks derived from a design get a `-review` umbrella (status=blocked, blocker=impl-slugs, reviewer = non-implementer session). See "### Design-derived impl tasks — review umbrella". +> Policy для поддержания сжатого рабочего контекста параллельных тасок. +> Борд проекта — сущности mappa: каждая таска `t:N` (per-type номер, решение 20) +> со статусом `ready|active|paused|blocked|done`, телом, owner'ом и рёбрами +> ([[refs]] → parent_of/ref, решения 4/6). Чтение — карв-аут лиза (решение 19); +> **любая мутация — под лизом проекта**. + +## MCP-поверхность + +| Операция | Тул | Примечание | +|---|---|---| +| Взять следующую ready-таску | `mcp__mappa__task_claim_next(project, owner)` | атомарно: лиз + таска; → `{ok, token, task}` | +| Продлить лиз | `mcp__mappa__task_heartbeat(project, claim_token)` | долгие таски | +| Создать таску | `mcp__mappa__task_create(project, slug, title?, description?, status?, claim_token)` | под лизом | +| Закрыть таску | `mcp__mappa__task_close(project, id, claim_token)` | под лизом | +| Прочитать таску | `mcp__mappa__entity_get(id)` | id internal из search/claim | +| Список борда | `mcp__mappa__entity_search(q, type='task', project=<имя>, limit)` | все статусы | +| Дерево parent_of | `mcp__mappa__graph_tree(root, depth?, fields?, limit?)` | зонтики/иерархия (решение 6) | +| Связанные сущности | `mcp__mappa__graph_neighbors/backlinks(id)` | рефы к таске | +| Уведомление при закрытии | `mcp__mappa__inbox_send(project=, from=<своя>, subject, body)` | письмо комиссионеру | + +**Лиз = лок на запись (решение 19).** Одна строка leases на проект: если другой +агент держит лиз — `task_claim_next` вернёт **422 busy**. Это серверный аналог +старого `.tasks/.lock`: проверять «а не поллер ли работает» руками не нужно — +сам claim скажет. Чтения лиза не требуют. + +**Рефы и id (#1037).** Таски наружу несут `ref: "t:N"` первым полем, `num` +следом, глобальный `id` — internal (последним, для addressing в тулах). +Ссылайся на таску `[[t:N]]` (в body → рёбра автоматически), никогда +`#<глобальный id>`. + +## Статусы (эмодзи для презентации) + +| Эмодзи | Статус | Значение | +|---|---|---| +| ⚪ | `ready` | не начата, полностью определена | +| 🔴 | `active` | в работе (обычно одна) | +| 🟡 | `paused` | в процессе, возобновляема | +| 🔵 | `blocked` | ждёт внешнего входа | +| 🟢 | `done` | закрыта | + +## Операции агента + +### Ориентация (session start) + +1. **Инбокс-свип** — `mcp__mappa__inbox_monitor(project=<имя>)`: непрочитанные + письма могут менять план. Обработай каждое по `inter-session-messaging`. +2. **Борд** — `mcp__mappa__entity_search(q='', type='task', project=<имя>, limit=50)`: + отсортируй по статусу (🔴 → 🟡 → ⚪), по одной строке на таску, цитируй slug. +3. Если user назвал таску — `entity_get(id)` по её рефу/номеру. +4. Подтверди одним предложением: «Мы в середине X, следующий шаг — Y». +5. Спроси, верен ли план, перед действиями. + +### Переключение / пауза / конец сессии + +1. Текущая 🔴 → `task_close` если завершена (см. закрытие), иначе пометь + `status=paused` через update-механику (owner остаётся; «where stopped» — + в body или handoff). +2. **Инбокс-свип** на границе тасок (`inbox_monitor`). +3. Возьми следующую: `task_claim_next` (лиз + таска). Прежняя остаётся 🟡. +4. Подтверди ориентацию перед стартом. + +> Примечание про «Where I stopped»: у mappa-таски нет отдельного поля — держи +> место остановки в `description` (последний абзац) или, для сессионного +> контекста, в **handoff-сущности** (`session-handoff`: summary/open_treks). +> Перед концом сессии обязательно запиши handoff — это аналог +> «Never lose Where I stopped». + +### Создание таски + +1. **Через тул, не руками** (решение 20): сначала лиз (`task_claim_next`) → + `task_create(project, slug, title, description, status='ready', claim_token)`. + Номер `t:N` назначает сервер — не выдумывай. +2. Slug: kebab-case, латиница. Description: markdown, `[[refs]]` на связанное. +3. Закрыть лиз не нужно — экспирится по TTL; мутации идут одним циклом. + +### Закрытие таски + +1. **Pre-close coverage check.** Собери acceptance criteria из description. + Для каждого — evidence: тест в диффе, артефакт, ссылка на дизайн. + Нет evidence на критерий → спроси user'а «закрывать или подождать coverage'а». +2. Resolve/drop открытые вопросы. +3. `task_close(project, id, claim_token)` → статус `done`. +4. **Notify-письмо (кросс-проектные таски).** Если таска пришла из другого + проекта (в description/meta есть `from:`/`notify:`) — `inbox_send` + комиссионеру: `project=`, `subject="[event: closed] "`, + body = итог (сделано, acceptance, ссылки). Живая сессия пишет сама. +5. Дополни summary-строку в handoff/вики при наличии. + +### Рекомендации / «что дальше» + +User спросил «что дальше», «status», «куда копаем» — рекомендую в порядке: + +1. **Локальный борд текущего проекта** (cwd): `entity_search(type='task', + project=<имя>)` — 🔴 → 🟡 → ⚪, по строке на таску, цитируй slug. +2. Одна footnote-строка если кросс-проектно релевантно: `Cross-project: N 🔴 + active (см. mcp__projects-meta__tasks_aggregate).` Только если N>0 и в cwd + нет активной 🔴. + +Кросс-проектные ургенты — информация, не драйвер «что делать здесь». + +## Правила + +- **Лиз-дисциплина.** Мутации — только под лизом; 422 busy = кто-то другой + пишет, не параллель. +- **Never lose Where I stopped** — критичное поле: в description + handoff. +- **Одна активная таска** — только одна 🔴 на проект. +- **Не выдумывай номера** — `t:N` назначает сервер. +- **Never close без coverage check** — evidence на каждый acceptance criterion, + иначе спросить. +- **Notify-письмо при закрытии** кросс-проектных тасок — статус 🟢 ≠ комиссионер + узнал. +- **Чтения — карв-аут.** `entity_search`/`entity_get`/`graph_*` не требуют лиза + и не блокируются чужим лизом. +- **Локально-первая рекомендация** — борд cwd первым; кросс-проект — футонота. +- **Ссылайся `[[t:N]]`**, не глобальным id (#1037). + +## Legacy (переходное) + +Файловый `.tasks/` (STATUS.md + per-task файлы) — легаси-канал, живёт пока +миграция/поллер не доедут. Не смешивай: новые таски — через mappa task_create; +старые борды читай напрямую (`.tasks/STATUS.md`), если они ещё в файлах. +`setup-tasks` умер — файловые борды больше не настраиваются.