OpeItcLoc03/claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(hermes): mvp-coverage — 9 skills converted to Hermes format

Browse Source 
- mapping.yaml: 7 pending → auto (setup-tasks, using-tasks, setup-wiki,
  using-wiki, using-projects-meta, using-context7, project-bootstrap,
  recommend-dont-menu). pending count now 0.

- dist-hermes/ populated:
  software-development: project-bootstrap (+ assets)
  productivity: recommend-dont-menu, setup-tasks, using-tasks
  research: setup-wiki, using-wiki
  mcp: using-context7, using-projects-meta

- active-platform replace-rule verified: Windows+PowerShell → Linux+bash
  in body SKILL.md (frontmatter description unchanged by design).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
vitya
2026-05-07 09:21:56 +03:00
parent 27026c5e0e
commit 82f82a2036
19 changed files with 2738 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
dist-hermes/productivity/recommend-dont-menu/README.md Normal file
View File

@@ -0,0 +1,32 @@
# recommend-dont-menu
One recommendation, not a menu. When the user asks "what should we do?", give your best choice with reasoning and trade-offs — don't enumerate A/B/C/D options.
## What it does
Overrides the `superpowers:brainstorming` default of presenting multiple options. Instead, respond with:
```
Я рекомендую X, потому что Y₁, Y₂. Trade-off: Z. Возражения?
```
Only mention alternatives when they're genuinely competitive or carry an important trade-off.
## When to use
During design discussions, architecture reviews, brainstorming, or any "what should we do" question.
## Installation
```bash
bash scripts/install.sh recommend-dont-menu
```
## Trigger line
Add to `CLAUDE.md`:
```
prefer single recommendations
```
Or use `project-bootstrap` (v1.9.0+) which includes this trigger in its template.

60
dist-hermes/productivity/recommend-dont-menu/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
---
name: recommend-dont-menu
version: 0.1.0
description: >
Use during design discussions, brainstorming, architecture reviews, or any
"what should we do" question — give one argued recommendation with explicit
trade-offs, not a multiple-choice menu. Override of superpowers:brainstorming
default. Works on any agent — pure response-style rule, no tool mappings needed.
---
# recommend-dont-menu
> One recommendation, not a menu. When the user asks "what should we do?" or "which is better?", give your best choice with reasoning and trade-offs. Don't enumerate A/B/C/D options — menus slow down decision-making when one option is clearly better.
## When this runs
**At session start** — when `CLAUDE.md` contains any trigger line:
- `prefer single recommendations`
- `recommend, don't menu`
- `argued recommendations`
- `give me your best shot`
**On explicit reference** — when user says "give me a recommendation", "don't menu", "what do you think?", or close variants.
## Default mode
For design questions, architecture choices, "what should we do" queries:
```
Я рекомендую X, потому что Y₁, Y₂. Trade-off: Z. Возражения?
```
**Only mention alternatives if:**
- They're genuinely close to the recommended option, OR
- They carry an important trade-off the user should weigh
Then, briefly:
```
Если важно W — лучше X', но добавляет сложность; иначе X.
```
**Don't enumerate options** for the sake of appearing comprehensive. Menus are noise when one option dominates — they force the user to read through losing choices and bury your reasoning behind an oblique list instead of a responsible recommendation.
## Override
This skill **overrides** `superpowers:brainstorming` where that skill prefers multiple-choice options. User instructions > skill defaults.
If `superpowers:brainstorming` is active in the session, this skill's response style takes precedence for design/brainstorming questions.
## Cross-agent applicability
This skill is **pure response-style** — it works on any agent (Claude, Gemini, Copilot) without tool mappings. No `references/copilot-tools.md` or equivalent needed.
## Why this exists
The pattern emerged from iterative refinement across `claude-skills` brainstorm sessions and `.meeting-room/` discussions. When agents dump 4-option menus for every question, users skim or disengage. A single argued recommendation with clear trade-offs leads to faster convergence and better decisions. When alternatives are genuinely competitive, mention them — but don't manufacture variants.
## Reference
Original rule lived in `~/.claude/CLAUDE.md` as a per-machine instruction. Moving to a skill makes it portable: all machines bootstrapped with `project-bootstrap` inherit it, and cross-agent compatibility is explicit.

108
dist-hermes/productivity/setup-tasks/README.md Normal file
View File

@@ -0,0 +1,108 @@
# setup-tasks
One-time skill that creates or migrates a project's `.tasks/` board to the
canonical layout — `STATUS.md` (the board, with emoji status legend) plus
per-task `<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.

202
dist-hermes/productivity/setup-tasks/SKILL.md Normal file
View File

@@ -0,0 +1,202 @@
---
name: setup-tasks
version: 1.0.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/<task-slug>.md (created on demand by using-tasks).
Block format:
## 🔴 [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
---
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.
### 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 four 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/<task-slug>.md` for each active or paused task using the per-task template (Goal, Key files, Decisions log, Open questions, Completed steps, Notes).
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 5 — Verify
After writes:
- `.tasks/STATUS.md` exists and has the emoji status legend (or template comment block in greenfield).
- For migrate: each task referenced in STATUS.md has its `<task-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.
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.
- **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.

169
dist-hermes/productivity/using-tasks/README.md Normal file
View File

@@ -0,0 +1,169 @@
# using-tasks
Runtime policy for keeping compressed working context across parallel tasks
in a monorepo. The agent reads and updates `.tasks/` so every session starts
oriented and every switch costs seconds, not minutes.
`using-tasks` governs *usage* of an existing `.tasks/`. Initial creation and
migration to canon are owned by [`setup-tasks`](../setup-tasks/).
> Renamed from `task-status-wiki` at v1.0.0.
## When it triggers
- User is switching between tasks, resuming a paused task, starting a new
one, or asks "where were we" / "what's the status".
- User says: "use task management system", "pause", "switch to X",
"update status".
- Any context-switching or multi-task coordination question in a code
project.
- If `.tasks/` is missing or non-canonical, this skill delegates to
[`setup-tasks`](../setup-tasks/) before doing anything else.
## Structure
```
<monorepo-root>/
└── .tasks/
├── STATUS.md ← board: one block per task, sorted by priority
└── <task-slug>.md ← deep context per task, one file each
```
Commit `.tasks/` to git — decision history is valuable, diffs show how
thinking evolved.
## STATUS.md format
```markdown
# Task Board
_Updated: YYYY-MM-DD_
## 🔴 [task-slug] — short description
**Status:** active | paused | blocked | done
**Where I stopped:** one sentence — the exact thought or action interrupted
**Next action:** one concrete step to resume immediately
**Blocker:** (only if blocked) what is preventing progress
**Branch:** git branch name
---
```
Status legend:
| Emoji | State | Notes |
|---|---|---|
| 🔴 | Active | Currently worked on. **Only one at a time.** |
| 🟡 | Paused | In progress, resumable. |
| ⚪ | Ready | Defined, not started. |
| 🟢 | Done | Kept until merged. |
| 🔵 | Blocked | Waiting on external input. |
## Per-task file format (`<task-slug>.md`)
Sections, in order: **Goal** (one paragraph — what this achieves and why),
**Key files** (`path/to/file.ts:42` style — specific lines when relevant),
**Decisions log** (reverse-chronological, append-only — past entries are
immutable), **Open questions**, **Completed steps**, **Notes** (temporary
hypotheses, links).
## Operations
### Session start
1. Check `.tasks/STATUS.md`. If missing → invoke
[`setup-tasks`](../setup-tasks/) and stop until it returns.
2. Read `STATUS.md`.
3. If user names a task, read its `<task-slug>.md`.
4. Confirm in one sentence: "We're in the middle of X, next step is Y."
5. Ask if the plan is still correct before doing anything.
6. If `_Updated` is more than 3 days old, flag it and ask the user to
confirm current state.
### Session end / pause / switch
1. Update `STATUS.md`: set the current task to 🟡, refresh "Where I stopped"
and "Next action".
2. Append non-obvious decisions to `<task-slug>.md` Decisions log.
3. Move finished items to "Completed steps".
4. Commit: `git add .tasks/ && git commit -m "chore: update task status [<task-slug>]"`.
### Task switch
1. Run session-end ops for the current task.
2. Read the target `<task-slug>.md`.
3. Set the target to 🔴 in `STATUS.md` (demote previous active to 🟡).
4. Confirm orientation before starting work.
### New task
1. Ask: slug, goal, known key files, branch.
2. Create `<task-slug>.md` with Goal and Key files populated.
3. Add a ⚪ block to `STATUS.md`.
4. Create / checkout the branch if missing.
### Task completion
1. **Pre-close coverage check** — list acceptance criteria, locate
evidence (tests, smoke-test artefacts, manual checklist ticks, design
doc refs). Missing evidence → ask the user before closing; never auto-close.
2. Resolve or drop all open questions.
3. Set status to 🟢 in `STATUS.md`.
4. Append a final summary line to the Decisions log.
5. Remind the user to delete the branch after merge.
### Post-commit task closure prompt
After a `feat:` / `fix:` commit the agent prompts:
"эта работа закрывает таску `<slug>`?". Slug candidates: commit-message
scope, current branch, most recent `Where I stopped`. If yes → run the
coverage check above. Skips `chore:` / `meta:` / `docs:` commits.
Forces a fresh-while-fresh decision, instead of letting shipped code sit
under a stale ⚪ block.
### Recommendations / "what's next" trigger
When the user asks «что дальше», «срочные», «куда копаем», "what next",
"status", or on session-start — recommend in this order:
1. **Local cwd-project board** ranked 🔴 → 🟡 → ⚪. Cite slugs.
2. **One footnote line** if relevant: `Cross-project: N 🔴 in other repos
(см. mcp__projects-meta__tasks_aggregate).` Only if N>0 and no local 🔴.
Explicit "по всем проектам" / "across all projects" flips the order.
Pairs with `using-projects-meta`'s local-first rule (which covers reads;
this one covers recommendations).
## Rules
- **Never lose "Where I stopped".** Most critical field. If unclear, ask
before ending the session.
- **One sentence per `STATUS.md` field.** Compress, don't write prose.
- **Key files must be specific** — not "auth module" but
`packages/auth/src/useAuth.ts:87`.
- **Decisions log is append-only.** Past entries are immutable.
- **Commit after every session end.** `git log` is the history of thinking.
- **Always confirm orientation at session start.** State understanding
before acting.
- **One active task at a time** — only one 🔴 in `STATUS.md`.
- **Never close without coverage check.** See "### Task completion"
step 1.
- **Local-first recommendations.** cwd-project first; cross-project at
most one footnote line.
## Install
From the repo root:
```bash
bash scripts/install.sh using-tasks
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` creation and
canon migration.
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-tasks` for
new projects.

174
dist-hermes/productivity/using-tasks/SKILL.md Normal file
View File

@@ -0,0 +1,174 @@
---
name: using-tasks
version: 1.1.0
description: >
Policy skill for working with an existing `.tasks/` board (per-task files + STATUS.md).
Use whenever the user is switching between tasks, resuming a paused task, starting a new
task, asking "where were we", says "use task management system", "pause", "switch to X",
"what's the status", "update status", or wants to track progress across parallel workstreams.
Trigger on any context-switching or multi-task coordination question in a code project.
If `.tasks/` is missing or non-canonical (no per-task `<task-slug>.md` files, no emoji
status legend in STATUS.md), delegate to `setup-tasks` first — it has its own confirmation
gate. Renamed from `task-status-wiki` at v1.0.0.
---
# using-tasks
> Policy for maintaining compressed working context across parallel tasks in a monorepo.
> The agent reads and updates `.tasks/` so every session starts oriented and every switch
> costs seconds, not minutes. This skill governs *usage* of an existing `.tasks/` — initial
> creation and migration to canon are owned by `setup-tasks`.
## Prerequisites
This skill assumes the project has a canonical `.tasks/` layout:
- `.tasks/STATUS.md` — the board, with per-task blocks using emoji status (🔴 active / 🟡 paused / ⚪ ready / 🟢 done / 🔵 blocked).
- `.tasks/<task-slug>.md` — one deep-context file per active or paused task.
If `.tasks/` is **missing**, or `STATUS.md` exists but is non-canonical (e.g. flat sections like "## Done" / "## In Progress" without the emoji + per-task block format, or no per-task files exist alongside STATUS.md) — invoke `setup-tasks` first. It detects greenfield vs migrate, has its own confirmation gate, and creates / migrates the structure. Only after `setup-tasks` finishes should this skill operate on `.tasks/`.
## Structure
```
<monorepo-root>/
.tasks/
STATUS.md ← board: one block per task, sorted by priority
<task-slug>.md ← deep context per task, one file each
```
Commit `.tasks/` to git. Decision history is valuable; diffs show how thinking evolved.
---
## STATUS.md format
```markdown
# Task Board
_Updated: YYYY-MM-DD_
## 🔴 [task-slug] — short description
**Status:** active | paused | blocked | done
**Where I stopped:** one sentence — the exact thought or action interrupted
**Next action:** one concrete step to resume immediately
**Blocker:** (only if blocked) what is preventing progress
**Branch:** git branch name
---
```
**Emoji convention:**
- 🔴 Active — currently worked on (only one at a time)
- 🟡 Paused — in progress, resumable
- ⚪ Ready — not started, fully defined
- 🟢 Done — completed, kept until merged
- 🔵 Blocked — waiting on external input
---
## Per-task file format (`<task-slug>.md`)
```markdown
# <task-slug>
## Goal
One paragraph. What this achieves and why it matters in the monorepo.
## Key files
- `path/to/file.ts` — role in this task
- `path/to/other.ts:42` — specific line if relevant
## Decisions log
Reverse-chronological. Append only — never rewrite past entries.
- YYYY-MM-DD: Why X was chosen over Y
- YYYY-MM-DD: Constraint Z discovered, approach adjusted
## Open questions
- [ ] unresolved design or dependency questions
## Completed steps
- [x] steps finished this or previous sessions
## Notes
Temporary hypotheses, links, names of people to consult.
```
---
## Agent operations
### Session start
1. Check if `.tasks/STATUS.md` exists. If not → invoke `setup-tasks` and stop here until it returns.
2. Read `STATUS.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."
5. Ask if the plan is still correct before doing anything.
6. If STATUS.md `_Updated` date is >3 days ago, flag it and ask user to confirm current state.
### Session end / pause / switch
1. Update `STATUS.md`: set current task to 🟡, update "Where I stopped" and "Next action".
2. Append to `<task-slug>.md` Decisions log any non-obvious choices made this session.
3. Move finished items to "Completed steps".
4. 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. Ask: task name (slug), goal, known key files, branch name.
2. Create `<task-slug>.md` with Goal and Key files populated.
3. Add ⚪ block to `STATUS.md`.
4. Create and checkout branch if it doesn't exist.
### 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. Append final summary line to Decisions log.
5. Remind user to delete the branch after merge.
### 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
- **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.
- **Never close a task without a coverage check** — see "### Task completion" step 1. Acceptance criteria with no evidence → ask, don't auto-close.
- **Local-first recommendations** — cwd-project board comes first; cross-project urgents are at most one footnote line.