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 умер.
This commit is contained in:
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
@@ -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>
|
|
||||||
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
|
|||||||
@@ -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".
|
|
||||||
|
|||||||
Reference in New Issue
Block a user