Compare commits

...

3 Commits

Author SHA1 Message Date
afca818a05 chore(skills): delete setup-tasks/setup-wiki — мета в сервисе (#983)
Нечего настраивать (решение 14/15). Свип ссылок: project-bootstrap v2.1.0
(Steps 3/4 → mappa, манифест без setup-строк), project-discipline (Rule 1),
setup-projects-meta README, using-tasks/using-wiki README.
2026-08-24 16:45:59 +03:00
c5ebde174d feat(task-format): v0.3.0 — primary mappa task.create schema, legacy STATUS.md interim (#983)
Канон создания — через mcp__mappa__task_create (per-type t:N, мутация под
лизом). Legacy-блоки .tasks/STATUS.md — интерм до переключения поллера (#984).
2026-08-24 16:45:58 +03:00
21023f1bae feat(using-tasks): v2.0.0 — .tasks/ board → mappa task-сущности (#983)
Борд = сущности type=task в сервисе (t:N, решение 20). Чтение — карв-аут
(entity_search), мутации под лизом (task_claim_next → claim_token, решение 19;
422 busy = чужой лиз — серверный аналог .tasks/.lock). claim/close/create/
heartbeat, notify-письмо при закрытии, локально-первая рекомендация. Файловый
.tasks/ — легаси; setup-tasks умер.
2026-08-24 16:45:58 +03:00
12 changed files with 276 additions and 1129 deletions

View File

@@ -24,16 +24,11 @@ clearly intends to turn into a workspace.
## Prerequisites ## Prerequisites
`project-bootstrap` does not lay out `.wiki/` or `.tasks/` by itself — it Мета в сервисе (решения 14/15): вики и таски проекта живут в **mappa**
delegates to two companion skills, which must be installed on the machine (`using-wiki` / `using-tasks` v2 — mappa-тулы), файловый `.wiki/` / `.tasks/`
running it: не создаётся. `setup-wiki` / `setup-tasks` умерли (нечего настраивать);
для проектов вне mappa файловый layout создаётся ad-hoc по канону
- [`setup-wiki`](../setup-wiki/) — creates the canonical `.wiki/` layout. Karpathy / `.tasks/` (см. using-wiki/using-tasks, legacy-раздел).
- [`setup-tasks`](../setup-tasks/) — creates the canonical `.tasks/` layout.
If either is missing, `project-bootstrap` stops with a clear error rather
than falling back to ad-hoc creation. This keeps layout drift between
projects bootstrapped at different times debuggable.
## What it creates ## What it creates
@@ -42,8 +37,8 @@ projects bootstrapped at different times debuggable.
| `.git/` | `git init` | Skipped if repo already initialized. | | `.git/` | `git init` | Skipped if repo already initialized. |
| `.gitignore` | `assets/.gitignore.template` | Skipped if file exists. | | `.gitignore` | `assets/.gitignore.template` | Skipped if file exists. |
| `README.md` | minimal stub | Skipped if file exists. | | `README.md` | minimal stub | Skipped if file exists. |
| `.wiki/` | delegated to `setup-wiki` | Karpathy LLM Wiki layout — `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/`, `entities/`, `concepts/`, `packages/`, `sources/`. | | вики | mappa (`using-wiki`) | сущности `type=wiki` в сервисе; файловый layout — только вне mappa (легаси). |
| `.tasks/` | delegated to `setup-tasks` | Canonical board — `STATUS.md` plus per-task `<task-slug>.md` files. | | таски | mappa (`using-tasks`) | сущности `type=task` в сервисе; файловый `.tasks/` — только вне mappa (легаси). |
| `AGENTS.md` | `assets/AGENTS.md.template` | **Canon** — skill triggers (`use project wiki`, `use task management system`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. On upgrade, the template is treated as a canonical set and merged idempotently — only missing trigger lines are appended after user confirm. Re-runs are no-ops. | | `AGENTS.md` | `assets/AGENTS.md.template` | **Canon** — skill triggers (`use project wiki`, `use task management system`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. On upgrade, the template is treated as a canonical set and merged idempotently — only missing trigger lines are appended after user confirm. Re-runs are no-ops. |
| `CLAUDE.md` | generated pointer | `Canon is AGENTS.md. Read AGENTS.md.` — legacy pointer for tooling that looks for the old name. | | `CLAUDE.md` | generated pointer | `Canon is AGENTS.md. Read AGENTS.md.` — legacy pointer for tooling that looks for the old name. |
| `.wiki/concepts/bootstrap-manifest.md` | generated | Records which skill versions initialized the project, so cross-project layout drift is debuggable. | | `.wiki/concepts/bootstrap-manifest.md` | generated | Records which skill versions initialized the project, so cross-project layout drift is debuggable. |
@@ -55,11 +50,11 @@ projects bootstrapped at different times debuggable.
found, what will be created, what will be skipped. found, what will be created, what will be skipped.
2. **Confirm.** One question, one confirmation. Nothing is written before the 2. **Confirm.** One question, one confirmation. Nothing is written before the
user agrees. user agrees.
3. **Steps 1–5.** Create or skip each piece in order — git, README, `.wiki/`, 3. **Steps 1–5.** Create or skip each piece in order — git, README, вики/таски
`.tasks/`, `AGENTS.md` + `CLAUDE.md` pointer. Steps 3 and 4 delegate to the setup-skills. (mappa, см. using-wiki/using-tasks), `AGENTS.md` + `CLAUDE.md` pointer.
4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of 4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of
`project-bootstrap`, `setup-wiki`, `setup-tasks`, `project-discipline`, `project-bootstrap`, `project-discipline`, `setup-interns`, and
`setup-interns`, and `using-interns` used. `using-interns` used.
5. **Step 5.6.** Skill dependencies check. Walk the canonical trigger list 5. **Step 5.6.** Skill dependencies check. Walk the canonical trigger list
in `AGENTS.md`, look each up in an embedded `trigger → fulfiller` map, in `AGENTS.md`, look each up in an embedded `trigger → fulfiller` map,
detect what's missing on this host (`~/.claude/skills/<name>/SKILL.md` detect what's missing on this host (`~/.claude/skills/<name>/SKILL.md`
@@ -105,10 +100,8 @@ target with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh …`.
## See also ## See also
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` layout. - [`using-wiki`](../using-wiki/) — runtime policy for the mappa wiki (v2).
- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` layout. - [`using-tasks`](../using-tasks/) — runtime policy for the mappa task board (v2).
- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`.
- [`using-tasks`](../using-tasks/) — runtime policy for working with `.tasks/`.
- [`project-discipline`](../project-discipline/) — cross-project rules - [`project-discipline`](../project-discipline/) — cross-project rules
activated by the `follow project discipline` trigger. activated by the `follow project discipline` trigger.
- [`setup-interns`](../setup-interns/), [`using-interns`](../using-interns/) — - [`setup-interns`](../setup-interns/), [`using-interns`](../using-interns/) —

View File

@@ -1,7 +1,7 @@
--- ---
name: project-bootstrap name: project-bootstrap
author: ours author: ours
version: 2.0.1 version: 2.1.0
description: > description: >
Initializes or upgrades a project in the current folder: git, .gitignore, README.md, Initializes or upgrades a project in the current folder: git, .gitignore, README.md,
.wiki/ using Karpathy's method, .tasks/ for task tracking, AGENTS.md (canon) with .wiki/ using Karpathy's method, .tasks/ for task tracking, AGENTS.md (canon) with
@@ -178,13 +178,14 @@ If it exists — leave it untouched.
--- ---
## Step 3 — .wiki/ ## Step 3 — вики (mappa, решение 14/15)
**Delegate to the `setup-wiki` skill.** It handles greenfield creation, canon migration, and the no-op case (already canon) uniformly, with its own confirmation gate. Don't recreate the layout inline here — that's how drift happens. **Канал — mappa:** вики проекта = сущности `type=wiki` в сервисе (решения 14/15:
мета в сервисе). Ничего файлового создавать не нужно; операции — `using-wiki`
If `setup-wiki` is not installed on this machine, **stop** and tell the user: project-bootstrap requires `setup-wiki` (and `setup-tasks`) installed. Don't fall back to ad-hoc creation. v2 (mappa wiki-тулы). Файловый `.wiki/` — только для проектов вне mappa
(легаси): layout по Karpathy (gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
**Reference (for context only — `setup-wiki` is the source of truth):** the canonical layout per Karpathy (gist: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) and `using-wiki`: `setup-wiki` умер (нечего настраивать) — при необходимости создания страниц
используй `wiki.create` под лизом (см. using-wiki).
``` ```
.wiki/ .wiki/
@@ -311,13 +312,14 @@ each get a `.gitkeep` so git tracks them.
--- ---
## Step 4 — .tasks/ ## Step 4 — таски (mappa, решение 14/15)
**Delegate to the `setup-tasks` skill.** It handles greenfield creation, migration from flat STATUS.md, and the no-op case uniformly, with its own confirmation gate. Don't recreate the layout inline. **Канал — mappa:** борд проекта = сущности `type=task` в сервисе (решения
14/15: мета в сервисе). Ничего файлового создавать не нужно; операции —
If `setup-tasks` is not installed, **stop** and tell the user — same rule as Step 3. `using-tasks` v2 (mappa task-тулы). Файловый `.tasks/` — только для проектов
вне mappa (легаси: `STATUS.md` + per-task файлы). `setup-tasks` умер
**Reference (for context only — `setup-tasks` is the source of truth):** the canonical layout is `.tasks/STATUS.md` (the board, with emoji status 🔴/🟡/⚪/🟢/🔵) plus `.tasks/<task-slug>.md` per active or paused task. The full pattern is documented in this repo at `.wiki/raw/setup-task-status-wiki.md`. (нечего настраивать) — таски создаются через `task_create` под лизом
(см. using-tasks/task-format).
--- ---
@@ -474,8 +476,6 @@ Skills used to initialize this project's `.wiki/` and `.tasks/` layout, with the
| Skill | Version | Role | | Skill | Version | Role |
|---|---|---| |---|---|---|
| `project-bootstrap` | <version> | orchestrator | | `project-bootstrap` | <version> | orchestrator |
| `setup-wiki` | <version> | wiki canonical layout |
| `setup-tasks` | <version> | tasks canonical layout |
| `project-discipline` | <version> | cross-project policy | | `project-discipline` | <version> | cross-project policy |
| `setup-interns` | <version> | interns MCP server install (one-time, per machine) | | `setup-interns` | <version> | interns MCP server install (one-time, per machine) |
| `using-interns` | <version> | interns runtime policy + per-session permission grant | | `using-interns` | <version> | interns runtime policy + per-session permission grant |

View File

@@ -118,7 +118,7 @@ The skill **does not**:
- modify `AGENTS.md` (that's `project-bootstrap`'s job); - modify `AGENTS.md` (that's `project-bootstrap`'s job);
- enforce rules via git hooks / pre-commit / CI (this is agent discipline, not tooling); - enforce rules via git hooks / pre-commit / CI (this is agent discipline, not tooling);
- manage `settings.json` permissions (that's `update-config`); - manage `settings.json` permissions (that's `update-config`);
- check the existence of `.wiki/` / `.tasks/` (that's `setup-wiki` / `setup-tasks` / `project-bootstrap`); if a project doesn't have them, Rule 1 simply finds no overrides and falls back to skill defaults. - check the existence of `.wiki/` / `.tasks/` on disk (мета в mappa, решение 14/15: вики/таски — сущности сервиса через `using-wiki` / `using-tasks`; файловый layout — легаси); if a project has neither, Rule 1 simply finds no overrides and falls back to skill defaults.
## Why this exists ## Why this exists

View File

@@ -88,6 +88,6 @@ Works on Windows under git-bash, Linux, macOS.
cross-project task aggregation and shared-wiki query / ingest. cross-project task aggregation and shared-wiki query / ingest.
- [`setup-context7`](../setup-context7/) — companion pattern for the context7 - [`setup-context7`](../setup-context7/) — companion pattern for the context7
MCP plugin (similar 8-phase shape). MCP plugin (similar 8-phase shape).
- [`setup-wiki`](../setup-wiki/), [`setup-tasks`](../setup-tasks/) — - Per-project вики/таски живут в mappa (мета в сервисе, решения 14/15) —
per-project setup skills (in-repo `.wiki/` and `.tasks/`); orthogonal to setup-скилов `.wiki/`/`.tasks/` больше нет; операции — `using-wiki` /
this skill, which sets up the cross-project layer. `using-tasks`.

View File

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

View File

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

View File

@@ -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:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
## When it triggers
- User says: "set up wiki", "init wiki", "create wiki", "migrate wiki to canon",
"wiki layout broken", or the Russian equivalents ("настрой вики",
"инициализируй вики", "wiki сломана").
- [`using-wiki`](../using-wiki/) detects a missing or non-canonical `.wiki/`
and delegates here via its Prerequisites section.
- [`project-bootstrap`](../project-bootstrap/) Step 3 delegates here when
initializing a new project.
## Modes
`setup-wiki` chooses one of three modes after a discovery scan:
| Mode | Trigger | Action |
|---|---|---|
| **greenfield** | No `.wiki/` exists | Create the canonical layout from scratch. |
| **noop** | `.wiki/` already canon (all five canon files + 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-<ts>/* .wiki/` and `git reset HEAD .wiki/`.
## Install
From the repo root:
```bash
bash scripts/install.sh setup-wiki
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`.
- [`project-bootstrap`](../project-bootstrap/) — orchestrator that delegates
here for new projects.
- Karpathy's LLM Wiki gist:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>

View File

@@ -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: <list of canon files present>
Missing: <list>
Non-canon: <list>
```
### Phase 2 — Plan + confirm
Show the plan in one block:
**Greenfield:**
```
Will create .wiki/ with canonical layout:
CLAUDE.md (schema), index.md, log.md, overview.md
raw/README.md
entities/, concepts/, packages/, sources/, 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>
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
<!-- Fill in as the project takes shape — what counts as an entity here, which packages exist, naming idioms specific to this codebase. -->
```
**`.wiki/index.md`** (catalog):
```markdown
# Wiki Index
Catalog of all wiki pages. One line per page, organized by type. Updated on every ingest / new page.
## Overview
- [overview.md](overview.md) — project overview
## Entities
<!-- (none yet) -->
## Concepts
<!-- (none yet) -->
## Packages
<!-- (none yet) -->
## Sources
<!-- (none yet) -->
## Contradictions
<!-- (none yet) -->
## Open Questions
<!-- (none yet) -->
```
**`.wiki/log.md`** (op log; backfill an `init` line dated today):
```markdown
# Wiki Log
Append-only operation log. Format:
\`\`\`
## [YYYY-MM-DD] <op> | <one-line description>
\`\`\`
Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`.
Parseable: `grep "^## \[" .wiki/log.md | tail -20`.
---
## [<today>] init | wiki bootstrapped via setup-wiki@<version>
```
**`.wiki/overview.md`**:
```markdown
---
title: <project> overview
type: overview
updated: <today>
---
# <project> — overview
<!-- Replace with a high-level description: what this project does, who it's for, the main components. -->
```
**`.wiki/raw/README.md`**:
```markdown
# Raw Sources
**Immutable.** Read, never edit. The only allowed modification is appending a `> Status:` blockquote when the user explicitly asks for a status audit.
Place raw inputs here — articles, transcripts, PDFs, screenshots — exactly as they came in. The agent reads from `raw/`, writes summaries into `../sources/`, and never modifies raw files.
For large or path-sensitive sources outside the repo, register them here:
\`\`\`
- short-name → /absolute/path/to/source
\`\`\`
```
**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/`, `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: <derived from existing H1>
type: concept
updated: <today>
---
```
Build `index.md` with one entry per migrated `concepts/<file>.md`, derived from the file's H1 and any one-liner the agent can extract.
Append a line to `log.md`:
```
## [<today>] refactor | wiki migrated to canon via setup-wiki@<version>
```
### Phase 5 — Verify
After writes, confirm:
- All canon files exist: `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`.
- 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-<ts>/
Next steps for the user:
• Edit .wiki/overview.md to describe the project
• Edit .wiki/CLAUDE.md "Domain conventions" with project-specific rules
• Read using-wiki SKILL.md if unfamiliar with the workflow
```
If invoked from `project-bootstrap`, return control silently — bootstrap continues with its remaining steps.
## Rollback
1. `rm -rf .wiki/` (greenfield rollback) OR `cp -r .wiki/.backup-<ts>/* .wiki/` (migrate rollback).
2. If a git repo, `git reset HEAD .wiki/` to unstage moves.
3. Tell user what failed.
## Common mistakes
- **Touching `raw/` content during migration.** `raw/` is immutable — only the `.gitkeep` placeholder may be removed (and that only because `raw/README.md` replaces it).
- **Skipping confirmation on greenfield.** Yes, even greenfield needs the gate — the user might be running this skill in the wrong directory.
- **Re-running on already-canon wiki and rewriting files.** Phase 1 detection guards this; bail out at `noop` mode.
- **Inventing project-specific Domain conventions in `CLAUDE.md`.** The schema's "Domain conventions" section is intentionally a stub — let the user fill it as they accumulate domain knowledge.
## Cross-platform notes
The procedure is platform-agnostic. `mkdir -p`, `mv`, `git mv`, `cp -r`, `rm -rf`, `touch` work in git-bash on Windows the same as on Linux/macOS. Wiki paths use forward slashes throughout.

View File

@@ -1,27 +1,76 @@
--- ---
name: task-format name: task-format
author: ours author: ours
version: 0.2.0 version: 0.3.0
description: > description: >
Use when writing or editing a task block in a `.tasks/STATUS.md` board that an Use when creating or editing a task so it is actually claimable and routed —
autonomous task-runner ("poller") will read — so the task is actually claimed, not silently skipped. Primary channel: **mappa** — create via
routed, and reported instead of silently skipped. Covers the exact block header, `mcp__mappa__task_create` (схема ниже), не руками. Legacy: пока файловый
the status emoji, and the `**Weight:**` / `**Notify:**` / `**Requirements:**` поллер (agents-task-runner) не переключён на mappa (#984), блоки в
fields the poller parses. Triggers: «оформить таску для поллера», «формат таски», `.tasks/STATUS.md` обязаны совпадать со строгим форматом (шапка, поля
«task block format», «make a task the poller will pick up», «add Weight/Notify», Weight/Notify), иначе поллер молча пропускает. Triggers: «оформить таску для
poller / agent-runner not claiming a task you wrote by hand. поллера», «формат таски», «task block format», «make a task the poller will
pick up», «add Weight/Notify», poller / agent-runner not claiming a task.
--- ---
# task-format # task-format
The autonomous poller parses `.tasks/STATUS.md` line-by-line with **strict regexes**. A block runs only if its header and fields match exactly. Get the format wrong and the poller does not error — it silently skips the block, or claims it and then parks it. This is the canonical field reference. Канон создания задачи — **через тул**, не рукописным блоком. Поллер (автономный
раннер) разбирает задачи строгими правилами; формат задаёт, какая таска будет
взята, отмаршрутизирована и зарепорчена, а какая молча пропущена.
> Authoring a task for **another** project/agent via `mcp__projects-meta__tasks_create`? Use `delegate-task` — it drives the tool, which emits this format for you. This skill is the format itself: for **hand-edited** STATUS.md blocks and for understanding what the poller reads. For board working policy (claim/close/status), see `using-tasks`. > Создаёшь задачу для **другого** проекта/агента? См. `delegate-task` — он ведёт
> через тул + письмо. Работа с бордом (claim/close/status) — `using-tasks`.
## Canonical block (copy this) ## Primary: mappa task.create
Создание задач в mappa (решение 14/15: мета в сервисе) — только через
`mcp__mappa__task_create`, никогда руками вставляй блоки. Тул сам назначает
per-type номер (`t:N`, решение 20) и пишет сущность.
```
mcp__mappa__task_create(
project: <имя проекта>, // обязателен
slug: <kebab-case>, // обязателен, латиница
title: <одна строка>, // опционально
description: <markdown>, // тело; [[refs]] → рёбра (решение 4)
status: ready | active | paused | blocked | done, // по умолчанию ready
claim_token: <токен лиза проекта> // мутация под лизом (решение 19)
)
```
**Мутация под лизом (решение 19):** `task_create` требует `claim_token`
активного лиза проекта (берётся `mcp__mappa__task_claim_next`). Без лиза —
422 busy. (Карв-аут: чтения и инбокс-доставка лиза не требуют.)
**Per-type номер (решение 20):** номер — канонический машинный реф `t:N`
(см. ответы — поле `ref`). Глобальный id — internal, только для addressing
(#1037). Ссылки на задачу в тексте — `[[t:N]]`, не `#<глобальный id>`.
**Slug-правила:** короткий, lowercase, kebab-case, латиница
(`fix-nl-vds-reality-pq-dest`, не `Fix_this_TASK #1`).
## Status emoji ↔ state
| Emoji | State | Значение |
|---|---|---|
| ⚪ | `ready` | единственное состояние, которое поллер берёт |
| 🔴 | `active` | взято / в работе |
| 🟡 | `paused` | возобновляемо |
| 🔵 | `blocked` | ждёт (указать почему в description/where_stopped) |
| 🟢 | `done` | закрыто |
Не путай: 🟢 — это *done*, не «готово».
## Legacy: блок .tasks/STATUS.md (интерм до #984)
Пока файловый поллер (agents-task-runner) не переключён на mappa-лиз (#984),
блоки в `.tasks/STATUS.md`, создаваемые руками/миграцией, обязаны совпадать со
строгим форматом — иначе поллер молча пропускает или паркует. **Это
переходный канон; новые задачи создавай через task_create.**
```markdown ```markdown
## ⚪ [#1234 my-task-slug] — One-line description of the work. ## ⚪ [#1234 my-task-slug] — One-line description.
**Status:** ready **Status:** ready
**Created:** 2026-08-23 **Created:** 2026-08-23
@@ -35,76 +84,54 @@ The autonomous poller parses `.tasks/STATUS.md` line-by-line with **strict regex
--- ---
``` ```
## The two load-bearing rules Три load-bearing правила:
1. **Header must match exactly:** `## <emoji> [#<n> <slug>] — <description>` 1. **Шапка точно:** `## <emoji> [#<n> <slug>] — <description>` — h2, один emoji,
- `## ` (h2, two hashes) — **not** `### `, not a bullet. `[#<n> <slug>]` (глобальный номер, без ведущих нулей), разделитель
- One status **emoji**, then `[#<n> <slug>]` in square brackets — **global task number** (`#1234`, no leading zeros) + slug — then ` — ` (space, em-dash `—`, space), then the description. A `-` hyphen or `:` will not match. ` — ` (пробел + em-dash + пробел). Несовпавшая шапка = задача не видна вообще.
- **Number is the machine key.** Global, unique across the whole federation, encodes creation order. References (`#452` in letters, blocker fields, decision trails) point at the number. The slug is the human-readable part only. 2. **Поля — строки `**Label:** value`.** Буллеты и проза игнорируются.
- Slug: short, lowercase, kebab-case, Latin. 3. **`**Created:** yyyy-mm-dd` обязателен** — пишется один раз при создании.
- A header that doesn't match is **not seen as a task at all**.
2. **Fields are `**Label:** value` lines** — bold label, colon, space, value. Bullet-list fields (`- **weight:** …`) and prose ("notify workshop when done") are **ignored** — the poller never reads them. Номера legacy-блоков назначает сервер (`tasks_create` из счётчика
`OpeItcLoc03/agenda/task-counter`) — **никогда не выдумывай номер руками**.
3. **`**Created:** yyyy-mm-dd` is mandatory** — the creation date. Written once at task creation, never edited after. ### Поля, которые поллер разбирает
## Numbering
- **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 **file name** is `yyyy-mm-dd-#####-<slug>.md` — number **5 digits with leading zeros, no `#`**: `2026-06-05-00019-fix-nl-vds-reality-pq-dest.md`. Leading zeros make folder sort = numeric up to 99999. No `#` in the filename (it would break markdown links and Gitea URLs).
- In the **header and text references** the number is written **without** leading zeros: `[#19 slug]`.
## Status emoji ↔ state
| Emoji | State | |
|---|---|---|
| ⚪ | **ready** | the only state the poller claims |
| 🔴 | active | claimed / in flight |
| 🟡 | paused | resumable |
| 🔵 | blocked | waiting on a `**Blocker:**` |
| 🟢 | done | kept until merged |
`**Status:**` mirrors the emoji in words. ⚪ → `ready`. **Do not** use 🟢 for "ready" — 🟢 is *done*.
## Fields the poller parses
| Field | Format | Meaning | | Field | Format | Meaning |
|---|---|---| |---|---|---|
| `**Weight:**` | `cheap-ok` \| `needs-claude` \| `needs-human` | Routing tier. **Required for autonomous pickup** — see below. | | `**Weight:**` | `cheap-ok` \| `needs-claude` \| `needs-human` | Тир маршрутизации. **Обязателен** для авто-взятия. |
| `**Notify:**` | `<owner>/<repo>` | Inbox target. Poller writes to that project's `.agents/inbox/` on close / park / delivery-failure. Omit → no report; the steering loop never closes. | | `**Notify:**` | `<owner>/<repo>` | Инбокс-адрес для событий close/park/delivery-failure. |
| `**Requirements:**` | CSV, e.g. `needs-db, needs-secrets` | Hard capability gate. The agent must hold **all** listed capabilities or the task is skipped. | | `**Requirements:**` | CSV (`needs-db, needs-secrets`) | Capability-гейт: агент должен держать ВСЕ. |
| `**Runtime allowed:**` | CSV, e.g. `claude-opus` | Runtime whitelist. If set, only a listed runtime may claim. | | `**Runtime allowed:**` | CSV (`claude-opus`) | Runtime-whitelist. |
| `**Consult policy:**` | `auto` \| `human-only` \| `strict-human` | How a mid-run `consult` escalates. Default when absent: `human-only`. | | `**Consult policy:**` | `auto` \| `human-only` \| `strict-human` | Эскалация consult; default `human-only`. |
| `**Blocker:**` | CSV of blocker slugs | Only on 🔵 blocked. Auto-unblock flips the task to ⚪ when every blocker is 🟢. | | `**Blocker:**` | CSV blocker-slug'ов | Только на 🔵; авто-unblock при 🟢 всех. |
| `**Next action:** / **Where I stopped:** / **Branch:**` | free text | Core resumability fields. | | `**Next action:** / **Where I stopped:** / **Branch:**` | free text | Резюмируемость. |
`**Owner:** / **Claim token:** / **Claim expires at:**` are the **claim stamp** — the poller writes and clears them. Never author them by hand; a stale stamp on a ⚪ task blocks the poller. `**Owner:** / **Claim token:** / **Claim expires at:**` — claim-штамп, пишет и
чистит поллер. Не автори руками; залипший штамп на ⚪ блокирует поллер.
## Weight — the field that decides pickup **Weight — поле, решающее взятие:** без `**Weight:**` поллер берёт задачу, не
находит тир и паркует в 🔵 (`no backend for weight_tier: unknown`). Обычный код
→ `needs-claude`; критикал-инфра (поллер, MCP-серверы, деплой, CI, git-хуки) →
`needs-human` (никогда не авто).
The poller routes each claimed task to a backend by its weight tier: ## Common mistakes
- `cheap-ok` — routine work, a cheap/weak model is fine.
- `needs-claude` — needs a capable model (refactors, anything where discipline matters, review).
- `needs-human` — **never** runs autonomously. The claim gate excludes it and the runner refuses to spawn. Use for anything touching critical infra: the poller/agent-runner itself, MCP servers, claim/close/heartbeat, deploy, CI/CD, git hooks.
**No `**Weight:**` line → no backend tier matches → the poller claims the task, finds no route, and parks it to 🔵 blocked (`no backend for weight_tier: unknown`).** So a task you want run **must** carry a Weight. If in doubt and the work is ordinary code, use `needs-claude`.
## Common mistakes (from baseline failures)
| Mistake | Fix | | Mistake | Fix |
|---|---| |---|---|
| `### Title` or a `- **id:** …` bullet list | Use the exact `## <emoji> [#n slug] — desc` h2 header + `**Field:**` lines. | | Рукописный блок вместо `task_create` | Создавай через тул — номер/формат серверные. |
| 🟢 for a ready task | 🟢 is *done*. Ready is ⚪. | | `### Title` / буллеты вместо полей | `## <emoji> [#n slug] — desc` + `**Field:** value`. |
| Header `[slug]` without a number | Header is `[#n slug]` — the number is the machine key. | | 🟢 для ready | 🟢 — done. Ready — ⚪. |
| `**Created:**` missing | Add `**Created:** yyyy-mm-dd` — mandatory field. | | Шапка `[slug]` без номера | `[#n slug]` — номер машинный ключ. |
| Inventing a number by hand | Numbers come only from `tasks_create` (counter). Never invent/reuse. | | Выдуманный номер | Номер — только от сервера (task_create). |
| File named `2026-06-05-19-slug.md` (no leading zeros) | File is `yyyy-mm-dd-#####-slug.md`, number 5 digits: `00019`. | | `**Created:**` отсутствует (legacy) | Добавить — обязательное поле. |
| Inventing `risk: low`, `tier: L`, `priority`, `claimable-by` | The poller routes on `**Weight:**` with three fixed values only. | | Ссылка `#<глобальный id>` | Ссылайся `[[t:N]]` (решение 20/#1037). |
| Notification written as prose / "Done-signal" | Use a real `**Notify:** <owner>/<repo>` field line. | | Без `**Weight:**` (legacy) | Ставь всегда, или задача паркуется. |
| Omitting Weight on a task you want auto-run | Always set Weight, or the task parks. | | Дефис/двоеточие вместо ` — ` в шапке | Разделитель — пробел + em-dash + пробел. |
| Hyphen or colon instead of ` — ` in the header | The separator is space + em-dash + space. |
## Verify ## Verify
After editing, the block is correct when: header is `## <emoji> [#n slug] — …`, the emoji matches `**Status:**`, `**Created:** yyyy-mm-dd` is present, every machine-read field is a `**Label:**` line (not a bullet), and a task meant for the poller has both `**Weight:**` (not `needs-human` unless intended) and `**Notify:**`. Задача корректна, когда: создана через `task_create` (или legacy-блок: шапка
`## <emoji> [#n slug] — …`, emoji = `**Status:**`, `**Created:**` есть, поля —
`**Label:**` строки, есть `**Weight:**` и `**Notify:**`); slug kebab-case;
ссылки на неё — `[[t:N]]`.

View File

@@ -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 in a monorepo. The agent reads and updates `.tasks/` so every session starts
oriented and every switch costs seconds, not minutes. oriented and every switch costs seconds, not minutes.
`using-tasks` governs *usage* of an existing `.tasks/`. Initial creation and `using-tasks` governs the task board. **Канал — mappa** (решение 14/15): борд =
migration to canon are owned by [`setup-tasks`](../setup-tasks/). сущности `type=task` в сервисе (см. SKILL.md v2.0.0). Файловый `.tasks/` — легаси;
`setup-tasks` умер.
> Renamed from `task-status-wiki` at v1.0.0. > 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". "update status".
- Any context-switching or multi-task coordination question in a code - Any context-switching or multi-task coordination question in a code
project. project.
- If `.tasks/` is missing or non-canonical, this skill delegates to - Борд читается из mappa (`entity_search(type='task', project=…)`);
[`setup-tasks`](../setup-tasks/) before doing anything else. файловый `.tasks/` — легаси, ничего настраивать не нужно.
## Structure ## Structure
@@ -70,8 +71,8 @@ hypotheses, links).
### Session start ### Session start
1. Check `.tasks/STATUS.md`. If missing → invoke 1. Check the mappa board: `entity_search(type='task', project=<имя>)`.
[`setup-tasks`](../setup-tasks/) and stop until it returns. Файлового `.tasks/STATUS.md` больше нет — setup-tasks умер.
2. Read `STATUS.md`. 2. Read `STATUS.md`.
3. If user names a task, read its `<task-slug>.md`. 3. If user names a task, read its `<task-slug>.md`.
4. Confirm in one sentence: "We're in the middle of X, next step is Y." 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 ## See also
- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` creation and - mappa — сервис-хост борда (`task_create`/`task_claim_next`/`task_close`,
canon migration. per-type `t:N`).
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-tasks` for - [`project-bootstrap`](../project-bootstrap/) — mappa-режим для новых проектов.
new projects.

View File

@@ -1,289 +1,138 @@
--- ---
name: using-tasks name: using-tasks
author: ours author: ours
version: 1.7.0 version: 2.0.0
description: > description: >
Policy skill for working with an existing `.tasks/` board (per-task files + STATUS.md). Policy skill for working with the project task board in Mappa (решения 14/15:
Use whenever the user is switching between tasks, resuming a paused task, starting a new мета в сервисе). Use whenever switching between tasks, resuming a paused task,
task, asking "where were we", says "use task management system", "pause", "switch to X", starting a new task, asking «where were we», says «use task management system»,
"what's the status", "update status", or wants to track progress across parallel workstreams. «pause», «switch to X», «what's the status», «update status», or tracking
Trigger on any context-switching or multi-task coordination question in a code project. progress across parallel workstreams. Board = сущности `type=task` в mappa
If `.tasks/` is missing or non-canonical (no per-task `<task-slug>.md` files, no emoji (чтение — карв-аут лиза; мутации — под лизом проекта, решение 19). Файловый
status legend in STATUS.md), delegate to `setup-tasks` first — it has its own confirmation `.tasks/` — легаси; `setup-tasks` умер (нечего настраивать).
gate. Renamed from `task-status-wiki` at v1.0.0.
--- ---
# using-tasks # using-tasks
> Policy for maintaining compressed working context across parallel tasks in a monorepo. > Policy для поддержания сжатого рабочего контекста параллельных тасок.
> The agent reads and updates `.tasks/` so every session starts oriented and every switch > Борд проекта — сущности mappa: каждая таска `t:N` (per-type номер, решение 20)
> costs seconds, not minutes. This skill governs *usage* of an existing `.tasks/` — initial > со статусом `ready|active|paused|blocked|done`, телом, owner'ом и рёбрами
> creation and migration to canon are owned by `setup-tasks`. > ([[refs]] → parent_of/ref, решения 4/6). Чтение — карв-аут лиза (решение 19);
> **любая мутация — под лизом проекта**.
## Prerequisites
## MCP-поверхность
This skill assumes the project has a canonical `.tasks/` layout:
| Операция | Тул | Примечание |
- `.tasks/STATUS.md` — the board, with per-task blocks using emoji status (🔴 active / 🟡 paused / ⚪ ready / 🟢 done / 🔵 blocked). |---|---|---|
- `.tasks/<task-slug>.md` — one deep-context file per active or paused task. | Взять следующую ready-таску | `mcp__mappa__task_claim_next(project, owner)` | атомарно: лиз + таска; → `{ok, token, task}` |
| Продлить лиз | `mcp__mappa__task_heartbeat(project, claim_token)` | долгие таски |
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/`. | Создать таску | `mcp__mappa__task_create(project, slug, title?, description?, status?, claim_token)` | под лизом |
| Закрыть таску | `mcp__mappa__task_close(project, id, claim_token)` | под лизом |
## Structure | Прочитать таску | `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) |
<monorepo-root>/ | Связанные сущности | `mcp__mappa__graph_neighbors/backlinks(id)` | рефы к таске |
.tasks/ | Уведомление при закрытии | `mcp__mappa__inbox_send(project=<notify>, from=<своя>, subject, body)` | письмо комиссионеру |
STATUS.md ← active board: 🔴 / 🟡 / ⚪ / 🔵 blocks, sorted by priority
yyyy-mm-dd-#####-<slug>.md ← deep context per task, one file each (format v2) **Лиз = лок на запись (решение 19).** Одна строка leases на проект: если другой
done/ ← per-task files of closed 🟢 tasks (format v2) агент держит лиз — `task_claim_next` вернёт **422 busy**. Это серверный аналог
.lock ← runtime session lock; **gitignored** (never committed) старого `.tasks/.lock`: проверять «а не поллер ли работает» руками не нужно —
.archive/ сам claim скажет. Чтения лиза не требуют.
done-YYYY-MM.md ← 🟢 done blocks moved off the board, one file per month
``` **Рефы и id (#1037).** Таски наружу несут `ref: "t:N"` первым полем, `num`
следом, глобальный `id` — internal (последним, для addressing в тулах).
Commit `.tasks/` to git. Decision history is valuable; diffs show how thinking evolved. Ссылайся на таску `[[t:N]]` (в body → рёбра автоматически), никогда
`#<глобальный id>`.
`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.
| Эмодзи | Статус | Значение |
--- |---|---|---|
| ⚪ | `ready` | не начата, полностью определена |
## STATUS.md format | 🔴 | `active` | в работе (обычно одна) |
| 🟡 | `paused` | в процессе, возобновляема |
```markdown | 🔵 | `blocked` | ждёт внешнего входа |
# Task Board | 🟢 | `done` | закрыта |
_Updated: YYYY-MM-DD_
## Операции агента
## 🔴 [#1234 task-slug] — short description
**Status:** active | paused | blocked | done ### Ориентация (session start)
**Created:** YYYY-MM-DD
**Where I stopped:** one sentence — the exact thought or action interrupted 1. **Инбокс-свип** — `mcp__mappa__inbox_monitor(project=<имя>)`: непрочитанные
**Next action:** one concrete step to resume immediately письма могут менять план. Обработай каждое по `inter-session-messaging`.
**Blocker:** (only if blocked) what is preventing progress 2. **Борд** — `mcp__mappa__entity_search(q='', type='task', project=<имя>, limit=50)`:
**Session break:** (optional) `true` — or a hint string for the next track. Marks this task as a session boundary. отсортируй по статусу (🔴 → 🟡 → ⚪), по одной строке на таску, цитируй slug.
**Branch:** git branch name 3. Если user назвал таску — `entity_get(id)` по её рефу/номеру.
4. Подтверди одним предложением: «Мы в середине X, следующий шаг — Y».
--- 5. Спроси, верен ли план, перед действиями.
```
### Переключение / пауза / конец сессии
**Task numbering (format v2).** Every block header carries a **global task number**: `## <emoji> [#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-#####-<slug>.md` — number 5 digits with leading zeros, no `#` (folder sort = numeric). References in text use the number: `#452`.
1. Текущая 🔴 → `task_close` если завершена (см. закрытие), иначе пометь
**Emoji convention:** `status=paused` через update-механику (owner остаётся; «where stopped» —
- 🔴 Active — currently worked on (only one at a time) в body или handoff).
- 🟡 Paused — in progress, resumable 2. **Инбокс-свип** на границе тасок (`inbox_monitor`).
- ⚪ Ready — not started, fully defined 3. Возьми следующую: `task_claim_next` (лиз + таска). Прежняя остаётся 🟡.
- 🟢 Done — completed; kept on the board until merged, then archived (see "### Archiving done tasks") 4. Подтверди ориентацию перед стартом.
- 🔵 Blocked — waiting on external input
> Примечание про «Where I stopped»: у mappa-таски нет отдельного поля — держи
### `session_break` marker > место остановки в `description` (последний абзац) или, для сессионного
> контекста, в **handoff-сущности** (`session-handoff`: summary/open_treks).
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.* > Перед концом сессии обязательно запиши handoff — это аналог
> «Never lose Where I stopped».
- **Type:** boolean or string.
- `session_break: true` — pause after close; the next track is "see STATUS.md". ### Создание таски
- `session_break: "<hint>"` — pause after close; `<hint>` names the recommended next track.
- **Where it lives:** in the task's frontmatter when delivered via the task system (`session_break: true` / `session_break: "<hint>"`); mirrored on the local board as the optional `**Session break:**` field in the task's STATUS.md block. 1. **Через тул, не руками** (решение 20): сначала лиз (`task_claim_next`) →
- **Absent →** behaviour is unchanged: close the task and continue as usual. `task_create(project, slug, title, description, status='ready', claim_token)`.
Номер `t:N` назначает сервер — не выдумывай.
The check is enforced in the **Task completion** flow below (after close, before claiming the next task). 2. Slug: kebab-case, латиница. Description: markdown, `[[refs]]` на связанное.
3. Закрыть лиз не нужно — экспирится по TTL; мутации идут одним циклом.
---
### Закрытие таски
## Per-task file format (`yyyy-mm-dd-#####-<slug>.md`)
1. **Pre-close coverage check.** Собери acceptance criteria из description.
```markdown Для каждого — evidence: тест в диффе, артефакт, ссылка на дизайн.
# <slug> Нет evidence на критерий → спроси user'а «закрывать или подождать coverage'а».
2. Resolve/drop открытые вопросы.
## Goal 3. `task_close(project, id, claim_token)` → статус `done`.
One paragraph. What this achieves and why it matters in the monorepo. 4. **Notify-письмо (кросс-проектные таски).** Если таска пришла из другого
проекта (в description/meta есть `from:`/`notify:`) — `inbox_send`
## Key files комиссионеру: `project=<notify>`, `subject="[event: closed] <slug>"`,
- `path/to/file.ts` — role in this task body = итог (сделано, acceptance, ссылки). Живая сессия пишет сама.
- `path/to/other.ts:42` — specific line if relevant 5. Дополни summary-строку в handoff/вики при наличии.
## Decisions log ### Рекомендации / «что дальше»
Reverse-chronological. Append only — never rewrite past entries.
- YYYY-MM-DD: Why X was chosen over Y User спросил «что дальше», «status», «куда копаем» — рекомендую в порядке:
- YYYY-MM-DD: Constraint Z discovered, approach adjusted
1. **Локальный борд текущего проекта** (cwd): `entity_search(type='task',
## Open questions project=<имя>)` — 🔴 → 🟡 → ⚪, по строке на таску, цитируй slug.
- [ ] unresolved design or dependency questions 2. Одна footnote-строка если кросс-проектно релевантно: `Cross-project: N 🔴
active (см. mcp__projects-meta__tasks_aggregate).` Только если N>0 и в cwd
## Completed steps нет активной 🔴.
- [x] steps finished this or previous sessions
Кросс-проектные ургенты — информация, не драйвер «что делать здесь».
## Notes
Temporary hypotheses, links, names of people to consult. ## Правила
```
- **Лиз-дисциплина.** Мутации — только под лизом; 422 busy = кто-то другой
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]`. пишет, не параллель.
- **Never lose Where I stopped** — критичное поле: в description + handoff.
--- - **Одна активная таска** — только одна 🔴 на проект.
- **Не выдумывай номера** — `t:N` назначает сервер.
## Agent operations - **Never close без coverage check** — evidence на каждый acceptance criterion,
иначе спросить.
### Session start - **Notify-письмо при закрытии** кросс-проектных тасок — статус 🟢 ≠ комиссионер
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. - **Чтения — карв-аут.** `entity_search`/`entity_get`/`graph_*` не требуют лиза
``` и не блокируются чужим лизом.
⚠️ поллер ведёт <slug> — нельзя работать параллельно - **Локально-первая рекомендация** — борд cwd первым; кросс-проект — футонота.
``` - **Ссылайся `[[t:N]]`**, не глобальным id (#1037).
(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. ## Legacy (переходное)
- **Absent or stale lock** (including after user confirmation): write `.tasks/.lock`:
```json Файловый `.tasks/` (STATUS.md + per-task файлы) — легаси-канал, живёт пока
{"type":"interactive","started_at":"<ISO8601>","ttl_minutes":120} миграция/поллер не доедут. Не смешивай: новые таски — через mappa task_create;
``` старые борды читай напрямую (`.tasks/STATUS.md`), если они ещё в файлах.
2. Check if `.tasks/STATUS.md` exists. If not → invoke `setup-tasks` and stop here until it returns. `setup-tasks` умер — файловые борды больше не настраиваются.
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 `<task-slug>.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 `<task-slug>.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-slug>]"`
### Task switch
1. Perform session-end operations for the current task.
2. Read the target `<task-slug>.md`.
3. Set it to 🔴 in STATUS.md (demote previous active to 🟡).
4. Confirm orientation before starting work.
### New task creation
1. **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-#####-<slug>.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 `<slug>` content (Goal and Key files) into the per-task file `yyyy-mm-dd-#####-<slug>.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: `<topic>-review`
- status: `blocked`
- blocker: the impl-task slugs (`<topic>-impl-1, <topic>-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 `<slug>.md` (or the STATUS block if no per-task file).
- For each criterion, locate evidence: a test name in the diff, a smoke-test artefact, a manual-checklist tick in the per-task file, or a design-doc reference.
- Missing evidence on any criterion → flag to user and ask "закрывать или подождать coverage'а?". Never silently close.
- If acceptance criteria are policy / docs-only and have no testable shape, an explicit user "ok, closed by inspection" is required (record this in the close-note).
2. Resolve or drop all open questions.
3. Set status to 🟢 in STATUS.md.
4. **Notify-письмо при закрытии (кросс-проектные таски).** Если закрываемая
таска пришла из другого проекта (в блоке есть `**Notify:**` или
`<!-- created-by: … from: <другой-проект> -->`) — отправить письмо
комиссионеру в его инбокс: `<notify-проект>/.agents/inbox/<ts>Z-<своя-папка>.md`,
frontmatter `event: closed`, `slug: <task-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-#####-<slug>.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 `<!-- closed-by … -->` 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>`?
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 `<topic>-review` umbrella (status=blocked, blocker=impl-slugs, reviewer = non-implementer session). See "### Design-derived impl tasks — review umbrella".

View File

@@ -7,7 +7,8 @@ three named operations, with strict file formats that keep the wiki
parseable and grep-friendly. parseable and grep-friendly.
`using-wiki` governs *usage* of an existing `.wiki/`. Initial creation and `using-wiki` governs *usage* of an existing `.wiki/`. Initial creation and
migration to canon are owned by [`setup-wiki`](../setup-wiki/). **Канал — mappa** (решение 14/15): вики = сущности `type=wiki` в сервисе
(см. SKILL.md v2.0.0). Файловый `.wiki/` — легаси; `setup-wiki` умер.
> Renamed from `wiki-maintainer` at v1.0.0. > Renamed from `wiki-maintainer` at v1.0.0.
@@ -19,7 +20,7 @@ migration to canon are owned by [`setup-wiki`](../setup-wiki/).
- Any time the agent modifies a file under `.wiki/` — the workflow and - Any time the agent modifies a file under `.wiki/` — the workflow and
formats below are mandatory. formats below are mandatory.
- If `.wiki/` is missing or non-canonical, this skill delegates to - If `.wiki/` is missing or non-canonical, this skill delegates to
[`setup-wiki`](../setup-wiki/) before doing anything else. вики читается из mappa (`wiki_get`); ничего настраивать не нужно.
## Three layers (do not blur) ## Three layers (do not blur)
@@ -136,7 +137,7 @@ Sections by type. Update on every ingest.
| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` | | Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
| Query | (read only) + optionally a new wiki page + `log.md` | | Query | (read only) + optionally a new wiki page + `log.md` |
| Lint | (read only) + `log.md` | | Lint | (read only) + `log.md` |
| Bootstrap / migrate | (delegated to [`setup-wiki`](../setup-wiki/)) | | Новая вики проекта | первый ingest создаёт CLAUDE/index/log через wiki_create |
## Common mistakes ## Common mistakes
@@ -152,7 +153,7 @@ Sections by type. Update on every ingest.
- **Forgetting `index.md`.** Pages not listed there are invisible to future - **Forgetting `index.md`.** Pages not listed there are invisible to future
queries. queries.
- **Improvising layout when canon files are missing.** Hand off to - **Improvising layout when canon files are missing.** Hand off to
[`setup-wiki`](../setup-wiki/) instead of patching ad-hoc. (setup-wiki умер: канал — mappa, страницы создаются wiki_create).
## When NOT to use ## When NOT to use
@@ -174,9 +175,9 @@ Works on Windows under git-bash, Linux, macOS.
## See also ## See also
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` creation and - mappa — сервис-хост вики (`wiki.get`/`wiki.create`/`wiki.update`);
canon migration. canon migration.
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-wiki` for - [`project-bootstrap`](../project-bootstrap/) — invokes mappa-режим для
new projects. new projects.
- Karpathy's LLM Wiki gist: - Karpathy's LLM Wiki gist:
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f> <https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>