chore(hermes/readme): cleanup after mappa-skill-suite — mapping.yaml: drop 10 stale entries (deleted skills), add 7 mappa-* as pending; dist-hermes orphans + SKIPPED.md stale lines removed; README install examples → current skills [skip-tdd: visual]
This commit is contained in:
@@ -26,7 +26,7 @@ git clone <repo> skills
|
||||
cd skills
|
||||
bash scripts/install.sh # copies every skills/* into ~/.claude/skills/
|
||||
# or only specific ones:
|
||||
bash scripts/install.sh using-wiki caveman
|
||||
bash scripts/install.sh mappa-knowledge caveman
|
||||
```
|
||||
|
||||
**Linux / macOS (bash):**
|
||||
@@ -36,7 +36,7 @@ git clone <repo> skills
|
||||
cd skills
|
||||
bash scripts/install.sh # copies every skills/* into ~/.claude/skills/
|
||||
# or only specific ones:
|
||||
bash scripts/install.sh using-wiki caveman
|
||||
bash scripts/install.sh mappa-knowledge caveman
|
||||
```
|
||||
|
||||
The install target can be overridden with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`.
|
||||
@@ -141,7 +141,7 @@ skills/
|
||||
│ ├── mapping.yaml ← per-skill Hermes-rollout config
|
||||
│ └── skills/ ← `mode: manual` overrides (Hermes-flavour rewrites)
|
||||
├── dist-hermes/ ← pre-converted Hermes-flavour tree (committed)
|
||||
│ ├── <category>/<name>/ ← e.g. software-development/pulling-before-work/
|
||||
│ ├── <category>/<name>/ ← e.g. software-development/diagnosing-bugs/
|
||||
│ └── SKIPPED.md ← skip + pending log (auto-generated)
|
||||
├── scripts/
|
||||
│ ├── build.sh / build.ps1
|
||||
|
||||
@@ -22,7 +22,7 @@ git clone <repo> claude-skills
|
||||
cd claude-skills
|
||||
bash scripts/install.sh # копирует все skills/* в ~/.claude/skills/
|
||||
# или конкретные:
|
||||
bash scripts/install.sh using-wiki caveman
|
||||
bash scripts/install.sh mappa-knowledge caveman
|
||||
```
|
||||
|
||||
Цель установки можно переопределить переменной `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`.
|
||||
|
||||
@@ -17,16 +17,11 @@ Do not edit by hand — edit the mapping and re-run the build.
|
||||
|
||||
## Pending (deferred to follow-up tasks)
|
||||
|
||||
- **delegate-task** — Calls mcp__projects-meta__tasks_create to create tasks in other projects/agents (Gitea commit, cross-project side-effect). Behavioral audit via delegate-task-test-trigger required before promotion to auto. → intended: `mode: auto, category: mcp`
|
||||
- **meta-host-routing** — Resolves WHERE a project's meta lives before tasks_create / knowledge_ingest / brainstorm-promotion (meta-out-of-repo). Touches projects-meta MCP (tasks_create / knowledge_ingest / meta_status) and routes writes across repos. Review PASS (meta-host-routing-review) but the -install baseline is still open and a tool-side audit (cross-repo MCP writes) is required before auto. Mapping executes task meta-host-routing-hermes-mapping. → intended: `mode: auto, category: meta`
|
||||
- **private-dev-public-publish** — Steps shell out to git / gh / Gitea-API, handle tokens, force-push, and repo deletion/privacy toggles — not a purely stylistic skill. Behavioral audit via private-dev-public-publish-test-trigger required before promotion to auto. → intended: `mode: auto, category: software-development`
|
||||
- **ralph-loop-execution** — Behavioral oracle-loop skill (Verifier / Attempts / Max-Attempts retry loop). NB: source SKILL.md currently lacks YAML frontmatter (no name/description) — cannot auto-convert cleanly until that is fixed. Mapped pending as a placeholder; needs frontmatter + a behavioral audit before any mode decision.
|
||||
- **session-handoff** — Writes .tasks/NEXT_SESSION.md (project-scope, sliding overwrite) and reads it on session start. Bidirectional file-system side-effect, opt-in via CLAUDE.md trigger-line. Behavioral audit via session-handoff-test-trigger required before promotion to auto. → intended: `mode: auto, category: productivity`
|
||||
- **session-inbox-monitor** — Paired SessionStart hook registers itself in ~/.claude/settings.json and sweeps orphaned monitor OS processes (Get-CimInstance | Stop-Process by sentinel+inbox-path); the skill then raises an in-session Monitor on .claude-inbox/. Primary activation is the CLAUDE.md trigger-line `inbox monitor: raise on start` + the injector, not a hermes-trigger. Behavioral gate CLEARED 2026-06-17 — test-trigger + review BOTH VERDICT PASS (activation 3/3 monitor + neg clean; structural hook audit 5 PASS/1 CONCERN, the CONCERN fixed in v0.2.2). STAYS pending on two independent tool-side blockers, NOT on behavioral verification: (1) the SessionStart hook is Windows-PowerShell and needs a Linux port for Hermes factory machines; (2) machine-level side-effects (user-config mutation of ~/.claude/settings.json + Get-CimInstance|Stop-Process kills) need a tool-side audit before auto. Promotion blocked on those two, not on test-trigger/review. → intended: `mode: auto, category: productivity`
|
||||
- **setup-agents-task-runner** — L2 installer — installs the standing-duty stack (agents-task-runner + watchdog + appeals-inbox) as platform-native OS services (systemd/launchd/winsw), fetches a pinned binary, writes poller-scope.json. Heavy infra side-effects (OS services + binary fetch); mode decision (skip vs manual vs auto) deferred — needs an explicit Hermes-factory applicability audit. Placeholder pending to keep the build green.
|
||||
- **task-format** — Documentational skill — how to write a .tasks/STATUS.md task block the autonomous poller will claim/route/report (block header, status emoji, Weight/Notify/Requirements fields). No tool-side effects; pending a behavioral test-trigger before auto. → intended: `mode: auto, category: productivity`
|
||||
- **task-loop** — Orchestrates the board claim/close/update/heartbeat cycle via mcp__projects-meta__tasks_claim_next / tasks_close / tasks_update / tasks_heartbeat (cross-session claim ownership, irreversible close, Gitea side-effects) and may arm a single long ScheduleWakeup for the explicit long-watch opt-in. Critical-infra-adjacent — touches the same claim/close machinery the unattended poller relies on. Behavioral audit via task-loop-test-trigger required before promotion to auto. → intended: `mode: auto, category: mcp`
|
||||
- **using-system-snapshot** — Calls mcp__projects-meta__meta_system_snapshot (read-only whole-machine ops snapshot: poller / docker / cross-project task load). Read-only, same class as using-vds-ops / using-wiki-graph; pending a behavioral test-trigger before auto. → intended: `mode: auto, category: mcp`
|
||||
- **using-vds-ops** — Calls mcp__vds-ops__* tools (read-only, but touches infrastructure). Behavioral audit via using-vds-ops-test-trigger required before promotion to auto. → intended: `mode: auto, category: mcp`
|
||||
- **using-wiki-graph** — Calls mcp__wiki-graph__* tools (read-only, parses a .wiki/ corpus server-side). Behavioral audit via using-wiki-graph-test-trigger required before promotion to auto. → intended: `mode: auto, category: mcp`
|
||||
- **using-yt-tools** — Shells out to yt-dlp + ffmpeg and writes ./yt-cache/ in cwd. Behavioral audit via using-yt-tools-test-trigger required before promotion to auto. → intended: `mode: auto, category: research`
|
||||
|
||||
@@ -1,169 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,251 +0,0 @@
|
||||
---
|
||||
name: using-tasks
|
||||
version: 1.4.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 ← active board: 🔴 / 🟡 / ⚪ / 🔵 blocks, sorted by priority
|
||||
<task-slug>.md ← deep context per task, one file each
|
||||
.lock ← runtime session lock; **gitignored** (never committed)
|
||||
archive/
|
||||
YYYY-MM.md ← 🟢 done blocks moved off the board, one file per month
|
||||
```
|
||||
|
||||
Commit `.tasks/` to git. Decision history is valuable; diffs show how thinking evolved.
|
||||
|
||||
`STATUS.md` is the **active** board — it must stay lean so orientation reads stay cheap. Closed 🟢 tasks are archived to `archive/YYYY-MM.md` once they pile up; see "### Archiving done tasks".
|
||||
|
||||
> **`.tasks/.lock` must be listed in `.gitignore`** (add `.tasks/.lock` to your project's `.gitignore`). The lock file is ephemeral runtime state, not project history — it must never be committed.
|
||||
|
||||
---
|
||||
|
||||
## STATUS.md format
|
||||
|
||||
```markdown
|
||||
# Task Board
|
||||
_Updated: YYYY-MM-DD_
|
||||
|
||||
## 🔴 [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
|
||||
**Session break:** (optional) `true` — or a hint string for the next track. Marks this task as a session boundary.
|
||||
**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 on the board until merged, then archived (see "### Archiving done tasks")
|
||||
- 🔵 Blocked — waiting on external input
|
||||
|
||||
### `session_break` marker
|
||||
|
||||
A task may carry a `session_break` marker — set by whoever defines the task (e.g. the delegating workshop) when its completion is a natural place to stop and start a fresh session. It signals an autonomous agent: *finish this task, then pause instead of immediately claiming the next one.*
|
||||
|
||||
- **Type:** boolean or string.
|
||||
- `session_break: true` — pause after close; the next track is "see STATUS.md".
|
||||
- `session_break: "<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.
|
||||
- **Absent →** behaviour is unchanged: close the task and continue as usual.
|
||||
|
||||
The check is enforced in the **Task completion** flow below (after close, before claiming the next task).
|
||||
|
||||
---
|
||||
|
||||
## Per-task file format (`<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. **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.
|
||||
```
|
||||
⚠️ поллер ведёт <slug> — нельзя работать параллельно
|
||||
```
|
||||
(Substitute the `slug` field from the lock file if present, otherwise omit it.)
|
||||
- **Stale lock** — any type whose TTL has expired (`type:"agent"` with `heartbeat` > 10 min ago; `type:"interactive"` with `started_at` > 2 h ago): silently overwrite.
|
||||
- **Absent or stale lock** (including after user confirmation): write `.tasks/.lock`:
|
||||
```json
|
||||
{"type":"interactive","started_at":"<ISO8601>","ttl_minutes":120}
|
||||
```
|
||||
2. Check if `.tasks/STATUS.md` exists. If not → invoke `setup-tasks` and stop here until it returns.
|
||||
3. Read `STATUS.md` — this is the orientation read (see note below on why it's a local read, not an MCP call).
|
||||
4. If user names a task, read its `<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. 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.
|
||||
6. **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.
|
||||
7. **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 7), 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/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/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/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 6.
|
||||
- **Local-first recommendations** — cwd-project board comes first; cross-project urgents are at most one footnote line.
|
||||
@@ -1,182 +0,0 @@
|
||||
# using-wiki
|
||||
|
||||
Runtime policy for an LLM Wiki built on the
|
||||
[Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
|
||||
Knowledge is **compiled once and kept current** across three layers, via
|
||||
three named operations, with strict file formats that keep the wiki
|
||||
parseable and grep-friendly.
|
||||
|
||||
`using-wiki` governs *usage* of an existing `.wiki/`. Initial creation and
|
||||
migration to canon are owned by [`setup-wiki`](../setup-wiki/).
|
||||
|
||||
> Renamed from `wiki-maintainer` at v1.0.0.
|
||||
|
||||
## When it triggers
|
||||
|
||||
- User says: "use project wiki", "query the wiki", "ingest this", or the
|
||||
Russian equivalents ("обнови вики", "проверь вики", "запроси вики",
|
||||
"заингесть").
|
||||
- Any time the agent modifies a file under `.wiki/` — the workflow and
|
||||
formats below are mandatory.
|
||||
- If `.wiki/` is missing or non-canonical, this skill delegates to
|
||||
[`setup-wiki`](../setup-wiki/) before doing anything else.
|
||||
|
||||
## Three layers (do not blur)
|
||||
|
||||
1. **Raw sources** — `.wiki/raw/` (or external paths registered in
|
||||
`raw/README.md`). **Immutable.** Read, never edit. The only exception is
|
||||
appending a `> Status` blockquote when the user explicitly asks for a
|
||||
status audit.
|
||||
2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept /
|
||||
package / source summary pages.
|
||||
3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what
|
||||
entities, what packages, naming). Always read it first; it overrides this
|
||||
skill on conflict.
|
||||
|
||||
## Three operations
|
||||
|
||||
### Ingest
|
||||
|
||||
«заингесть X» — pull a raw source into the wiki.
|
||||
|
||||
1. Read the raw source fully.
|
||||
2. Extract: entities, concepts, packages, cross-cutting patterns.
|
||||
3. Create `sources/<slug>.md` (one summary page per source, ~50–150 lines).
|
||||
4. For each affected entity / concept / package page: update if exists,
|
||||
create if not. Flag contradictions explicitly with
|
||||
`> **Противоречие:** источник A говорит X, источник B — Y`.
|
||||
**Never silently overwrite.**
|
||||
5. Update `index.md`.
|
||||
6. Append one line to `log.md`.
|
||||
7. Report: what was created, updated, contradicted.
|
||||
|
||||
One ingest may touch 10–15 pages. That's normal — that's why an LLM does it.
|
||||
|
||||
### Query
|
||||
|
||||
A question answered from the wiki.
|
||||
|
||||
1. Read `index.md` first, drill into relevant pages.
|
||||
2. Answer with citations as markdown links.
|
||||
3. **Compound the wiki.** If the answer is a real synthesis, ask the user:
|
||||
"Сохранить как страницу wiki?" Good queries become durable pages under
|
||||
`concepts/` or `analyses/`.
|
||||
4. Append one line to `log.md`.
|
||||
|
||||
### Lint
|
||||
|
||||
«проверь wiki» — health check.
|
||||
|
||||
Scan for:
|
||||
|
||||
- Contradictions between pages.
|
||||
- Orphans (pages with no inbound links).
|
||||
- Stale claims (raw source updated after the summary's `ingested:` date —
|
||||
check via `git log -p`).
|
||||
- Concepts mentioned in prose but missing their own page.
|
||||
- Empty / TODO sections.
|
||||
|
||||
Report as a punch list. Don't delete anything automatically. Append one
|
||||
line to `log.md` with the findings.
|
||||
|
||||
## File formats (mandatory)
|
||||
|
||||
### Page frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Человекочитаемое имя
|
||||
type: entity | concept | package | source | contradiction | open-question | overview
|
||||
tags: [short, tokens]
|
||||
sources: [../sources/foo.md, ../sources/bar.md]
|
||||
updated: 2026-04-21
|
||||
---
|
||||
```
|
||||
|
||||
Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
|
||||
Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`.
|
||||
Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`.
|
||||
|
||||
### File naming
|
||||
|
||||
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / non-Latin in
|
||||
filenames; keep the original title in H1 + frontmatter.
|
||||
- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md`
|
||||
(no `@org/` prefix), `sources/<slug>.md`, `contradictions/<slug>.md`,
|
||||
`open-questions/<slug>.md`.
|
||||
|
||||
### `log.md` — append-only, grep-parseable
|
||||
|
||||
Every entry must start with:
|
||||
|
||||
```
|
||||
## [YYYY-MM-DD] <operation> | <short description>
|
||||
```
|
||||
|
||||
Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`.
|
||||
|
||||
Parse with: `grep "^## \[" .wiki/log.md | tail -20`.
|
||||
|
||||
### `index.md`
|
||||
|
||||
Catalog, not narrative. One line per page: `- [Title](path) — hook.`
|
||||
Sections by type. Update on every ingest.
|
||||
|
||||
### Cross-references
|
||||
|
||||
- Wiki → wiki: relative markdown links — `[Name](../entities/x.md)`.
|
||||
- Wiki → code: relative path from repo root — `[foo.js](../../packages/api/foo.js)`.
|
||||
- Wiki → raw: `../raw/<file>`.
|
||||
- URL-encode spaces (`%20`) and Cyrillic when needed.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Situation | Files touched |
|
||||
|---|---|
|
||||
| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
|
||||
| Query | (read only) + optionally a new wiki page + `log.md` |
|
||||
| Lint | (read only) + `log.md` |
|
||||
| Bootstrap / migrate | (delegated to [`setup-wiki`](../setup-wiki/)) |
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **Editing `raw/`.** Don't. Only allowed change: status blockquote on
|
||||
explicit request.
|
||||
- **Dumping raw content into `sources/`.** Summaries are summaries. Link to
|
||||
raw, don't copy.
|
||||
- **Silent overwrites on contradictions.** Flag them with a `> **Противоречие:**`
|
||||
block.
|
||||
- **Narrative `log.md`.** "Today I added…" is wrong. Use
|
||||
`## [YYYY-MM-DD] ingest | <what>`.
|
||||
- **Non-ASCII filenames.** Breaks greppability and cross-platform. Transliterate.
|
||||
- **Forgetting `index.md`.** Pages not listed there are invisible to future
|
||||
queries.
|
||||
- **Improvising layout when canon files are missing.** Hand off to
|
||||
[`setup-wiki`](../setup-wiki/) instead of patching ad-hoc.
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- The project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular
|
||||
documentation, not an LLM Wiki.
|
||||
- The user wants a single-file README or ADR — this skill is for persistent,
|
||||
interlinked knowledge bases.
|
||||
- One-off questions about code — read files directly, no wiki workflow needed.
|
||||
|
||||
## Install
|
||||
|
||||
From the repo root:
|
||||
|
||||
```bash
|
||||
bash scripts/install.sh using-wiki
|
||||
```
|
||||
|
||||
Works on Windows under git-bash, Linux, macOS.
|
||||
|
||||
## See also
|
||||
|
||||
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` creation and
|
||||
canon migration.
|
||||
- [`project-bootstrap`](../project-bootstrap/) — invokes `setup-wiki` for
|
||||
new projects.
|
||||
- Karpathy's LLM Wiki gist:
|
||||
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
|
||||
@@ -1,138 +0,0 @@
|
||||
---
|
||||
name: using-wiki
|
||||
version: 1.1.0
|
||||
description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wiki pattern). Use when the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "use project wiki", "обнови вики", "проверь вики", "запроси вики", "заингесть", "query the wiki". Also use when modifying any file under `.wiki/` — the workflow and formats below are mandatory, and project-specific conventions live in `.wiki/CLAUDE.md`. If `.wiki/` is missing or non-canonical, delegate to `setup-wiki` first (it has its own confirmation gate). Renamed from `wiki-maintainer` at v1.0.0.
|
||||
---
|
||||
|
||||
# using-wiki
|
||||
|
||||
> Policy for maintaining an LLM Wiki (Karpathy pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Knowledge is **compiled once and kept current** across three layers, via three named operations, with strict file formats that make the wiki parseable and grep-friendly. This skill governs *usage* of an existing wiki — initial creation and migration to canon are owned by `setup-wiki`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This skill assumes the project has a canonical `.wiki/` layout: `CLAUDE.md` (schema), `index.md` (catalog), `log.md` (op log), `overview.md`, `raw/README.md`, and the six content directories `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`.
|
||||
|
||||
If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`, or `contradictions/`/`open-questions/` directories are absent) — invoke the `setup-wiki` skill first. It detects the situation (greenfield vs migrate) and creates or migrates the structure with its own confirmation gate. Only after `setup-wiki` finishes should this skill proceed with the operations below.
|
||||
|
||||
## Three layers (do not blur)
|
||||
|
||||
1. **Raw sources** — `.wiki/raw/` (or external paths registered in `raw/README.md`). **Immutable.** Read, never edit. The only exception is appending a `> Status` blockquote when the user explicitly asks for a status audit.
|
||||
2. **Wiki** — everything else under `.wiki/`. Agent-owned. Entity / concept / package / source summary pages.
|
||||
3. **Schema** — `.wiki/CLAUDE.md`. Project-specific conventions (what entities, what packages, naming). Always read it first if present; it overrides this skill when it conflicts.
|
||||
|
||||
## First step on every operation
|
||||
|
||||
1. Read `.wiki/CLAUDE.md` if it exists.
|
||||
2. Read `.wiki/index.md` to locate relevant pages.
|
||||
3. Only then act.
|
||||
|
||||
If `.wiki/CLAUDE.md` is missing, the layout is incomplete — invoke `setup-wiki` rather than improvising.
|
||||
|
||||
## Three operations
|
||||
|
||||
### Ingest — «заингесть X»
|
||||
|
||||
1. Read the raw source fully.
|
||||
2. Extract: entities, concepts, packages, cross-cutting patterns.
|
||||
3. Create `sources/<slug>.md` (one summary page per source, ~50–150 lines).
|
||||
4. For each affected entity/concept/package page:
|
||||
- If it exists → update it. **Flag contradictions explicitly** with `> **Противоречие:** источник A говорит X, источник B — Y`. Don't silently overwrite.
|
||||
- If not → create it.
|
||||
5. Update `index.md` — add or move entries.
|
||||
6. Append one line to `log.md` (format below).
|
||||
7. Report to the user: what created, what updated, what contradictions found.
|
||||
|
||||
**One ingest may touch 10–15 pages. This is normal — that's why LLMs do it.**
|
||||
|
||||
### Query — вопрос по wiki
|
||||
|
||||
1. Read `index.md` first, then drill into relevant pages.
|
||||
2. Answer with citations as markdown links to wiki pages.
|
||||
3. **Compound the wiki.** If the answer is a real synthesis (comparison, analysis, new connection) — ask the user: "Сохранить как страницу wiki?" Good queries become durable pages under `concepts/`, `analyses/`, or similar.
|
||||
4. Append one line to `log.md`.
|
||||
|
||||
### Lint — «проверь wiki»
|
||||
|
||||
Scan for:
|
||||
- **Contradictions** between pages.
|
||||
- **Orphans** — pages with no inbound links.
|
||||
- **Stale claims** — git `log -p` on the raw source shows it was updated after the summary's `ingested:` date.
|
||||
- **Missing entities** — concepts mentioned in prose but without their own page.
|
||||
- **Empty/TODO sections.**
|
||||
|
||||
Report as a punch list. Don't delete anything automatically.
|
||||
Append one line to `log.md` summarizing the findings.
|
||||
|
||||
## File formats (MANDATORY)
|
||||
|
||||
### Page frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Человекочитаемое имя
|
||||
type: entity | concept | package | source | contradiction | open-question | overview
|
||||
tags: [short, tokens]
|
||||
sources: [../sources/foo.md, ../sources/bar.md]
|
||||
updated: 2026-04-21
|
||||
---
|
||||
```
|
||||
|
||||
Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`.
|
||||
|
||||
Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`.
|
||||
|
||||
Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`.
|
||||
|
||||
### File naming
|
||||
|
||||
- `kebab-case.md`, **Latin only**. Transliterate Cyrillic / other scripts in filenames (`план переписывания` → `ozon-client-rewrite.md`). Keep the original title in the H1 and frontmatter.
|
||||
- `entities/<name>.md`, `concepts/<name>.md`, `packages/<name>.md` (no `@org/` prefix), `sources/<slug>.md`, `contradictions/<slug>.md`, `open-questions/<slug>.md`.
|
||||
|
||||
### `log.md` — append-only, grep-parseable
|
||||
|
||||
Every entry **must** start with:
|
||||
|
||||
```
|
||||
## [YYYY-MM-DD] <operation> | <short description>
|
||||
```
|
||||
|
||||
Operations: `ingest`, `query`, `lint`, `refactor`, `decision`, `init`.
|
||||
|
||||
Parseable with: `grep "^## \[" .wiki/log.md | tail -20`.
|
||||
|
||||
### `index.md`
|
||||
|
||||
Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources / contradictions / open-questions). Update on every ingest.
|
||||
|
||||
### Cross-references
|
||||
|
||||
- Wiki → wiki: relative markdown links, `[Name](../entities/x.md)`.
|
||||
- Wiki → code: relative path from repo root: `[foo.js](../../packages/api/foo.js)`.
|
||||
- Wiki → raw: `../raw/<file>`.
|
||||
- URL-encode spaces in paths (`%20`) and Cyrillic when needed.
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Situation | Files touched |
|
||||
|---|---|
|
||||
| Ingest one doc | `sources/<slug>.md` (new) + 3–15 entity/concept/package pages + `index.md` + `log.md` |
|
||||
| Query | (read only) + optionally new wiki page + `log.md` |
|
||||
| Lint | (read only) + `log.md` |
|
||||
| Bootstrap / migrate to canon | (delegated to `setup-wiki`) |
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **Editing `raw/`.** Don't. Only allowed: status blockquote when user explicitly asks.
|
||||
- **Dumping raw content into `sources/`.** Summaries are summaries. Link to raw, don't copy it.
|
||||
- **Silent overwrites.** When a new source contradicts an existing page, flag it with a `> **Противоречие:**` block; don't just overwrite.
|
||||
- **Narrative `log.md`.** `Today I added…` is wrong. Use `## [YYYY-MM-DD] ingest | <what>`.
|
||||
- **Non-ASCII file names.** Breaks greppability and cross-platform. Transliterate.
|
||||
- **Forgetting `index.md`.** Pages not listed there are effectively invisible for future queries.
|
||||
- **Skipping contradictions in lint.** The wiki's value grows from surfaced tensions, not from false consensus.
|
||||
- **Improvising layout when canon files are missing.** If the wiki is missing or partial, hand off to `setup-wiki` instead of patching ad hoc.
|
||||
|
||||
## When NOT to use this skill
|
||||
|
||||
- Project has CLAUDE.md / AGENTS.md docs but no `.wiki/` — that's regular project documentation, not an LLM Wiki.
|
||||
- User wants a single-file README or ADR — this skill is for persistent interlinked knowledge bases.
|
||||
- One-off questions about code — use regular file reading, not wiki workflow.
|
||||
@@ -1,29 +0,0 @@
|
||||
# pulling-before-work
|
||||
|
||||
Policy skill that pulls the current branch from `origin` once at session start
|
||||
and on explicit re-sync requests. Designed to remove the "edited on stale base"
|
||||
footgun without trampling dirty work-trees or auto-merging.
|
||||
|
||||
## When it triggers
|
||||
|
||||
- **Session start** — when `CLAUDE.md` contains the line `pull remote before work` (added by `project-bootstrap` v1.4.0+).
|
||||
- **In-chat** — when the user says `sync`, `resync`, `pull`, `обнови репо`, `git pull please`, or close variants.
|
||||
|
||||
Stays silent in non-git folders. Prints one informational line and exits in:
|
||||
no `origin` remote, no upstream tracking, dirty work-tree, detached HEAD.
|
||||
|
||||
## What it does
|
||||
|
||||
`git pull --ff-only` against the configured upstream — never auto-merges, never
|
||||
auto-rebases, never stashes, never commits, never pushes. On divergence it prints
|
||||
a warning with manual-resolution hints and exits.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
None. The skill is a no-op outside git repos and folders without an `origin`
|
||||
remote, so it's safe to leave activated everywhere.
|
||||
|
||||
## Related
|
||||
|
||||
- `project-bootstrap` (v1.4.0+) — adds the trigger line to new and existing projects' `CLAUDE.md`.
|
||||
- `.wiki/concepts/pulling-before-work-design.md` (in projects bootstrapped from this repo: this design lives in `claude-skills`) — full design rationale.
|
||||
@@ -1,153 +0,0 @@
|
||||
---
|
||||
name: pulling-before-work
|
||||
version: 1.0.0
|
||||
description: >
|
||||
Pulls the current branch from origin once at session start and on explicit
|
||||
re-sync requests. Use when CLAUDE.md contains the trigger line "pull remote
|
||||
before work", or when the user says "sync", "resync", "pull", "обнови репо",
|
||||
"git pull please", or close variants asking to refresh from the remote.
|
||||
Runs `git pull --ff-only` — never auto-merges or rebases. Stays silent in
|
||||
non-git folders. Prints one informational line and exits when there is no
|
||||
origin remote, no upstream tracking, the working tree is dirty, or HEAD is
|
||||
detached. Does not stash, commit, or push. Activated by `project-bootstrap`
|
||||
v1.4.0+ via the canonical CLAUDE.md template.
|
||||
---
|
||||
|
||||
# pulling-before-work
|
||||
|
||||
> Pull from `origin` once when work starts. Don't auto-merge. Don't trample dirty work-trees. Don't ask twice in the same session unless asked.
|
||||
|
||||
## When this runs
|
||||
|
||||
**At session start** — once, when the skill is activated by the `pull remote before work` line in `CLAUDE.md`. The cycle below runs immediately.
|
||||
|
||||
**On explicit re-sync** — when the user says any of: `sync`, `resync`, `pull`, `обнови репо`, `pull please`, `git pull`, `подтяни`, `pull from origin`. Re-runs the full cycle. There is no per-session counter; the user is always allowed to ask.
|
||||
|
||||
**Never** before each commit, before each tool call, on every message, or in any other implicit cadence. Mode-3 ("start + on-demand") was the explicit design choice — see `.wiki/concepts/pulling-before-work-design.md`.
|
||||
|
||||
## The pull cycle
|
||||
|
||||
Run these checks in order. Print at most one line of chat output per run.
|
||||
|
||||
### 1. Inside a git work-tree?
|
||||
|
||||
```bash
|
||||
git rev-parse --is-inside-work-tree 2>/dev/null
|
||||
```
|
||||
|
||||
If the command fails or prints anything other than `true` → **exit silently, no chat output.** This is the not-a-git-repo case; the skill must not be noisy in random folders.
|
||||
|
||||
### 2. Has an `origin` remote?
|
||||
|
||||
```bash
|
||||
git remote get-url origin 2>/dev/null
|
||||
```
|
||||
|
||||
If the command fails (no such remote) → print one line and exit:
|
||||
|
||||
```
|
||||
no origin remote — skip pull
|
||||
```
|
||||
|
||||
### 3. Is the working tree clean?
|
||||
|
||||
```bash
|
||||
git status --porcelain
|
||||
```
|
||||
|
||||
If the output is non-empty → print one line and exit:
|
||||
|
||||
```
|
||||
working tree dirty — skipping pull. commit/stash, потом скажи "sync"
|
||||
```
|
||||
|
||||
Never stash automatically. Stash-pop conflicts are exactly the friction this skill exists to remove.
|
||||
|
||||
### 4. Is HEAD attached?
|
||||
|
||||
```bash
|
||||
git symbolic-ref -q HEAD
|
||||
```
|
||||
|
||||
If the command fails (empty output, exit 1) → detached HEAD. Print:
|
||||
|
||||
```
|
||||
detached HEAD — skip pull
|
||||
```
|
||||
|
||||
### 5. Does the current branch have an upstream?
|
||||
|
||||
```bash
|
||||
git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null
|
||||
```
|
||||
|
||||
Capture the upstream name (e.g. `origin/master`). If the command fails → no upstream tracking. Print:
|
||||
|
||||
```
|
||||
no upstream tracking for <branch> — skip pull
|
||||
```
|
||||
|
||||
(Where `<branch>` is `git rev-parse --abbrev-ref HEAD`.)
|
||||
|
||||
### 6. Pull, fast-forward only
|
||||
|
||||
```bash
|
||||
git pull --ff-only
|
||||
```
|
||||
|
||||
(No args — uses the configured upstream captured above.)
|
||||
|
||||
Classify by exit code and stdout:
|
||||
|
||||
| Result | Print |
|
||||
|---|---|
|
||||
| Already up to date | `✅ already up to date with <upstream>` |
|
||||
| Fast-forward, N commits | `✅ pulled N commits from <upstream>` |
|
||||
| Non-fast-forward / diverged (exit non-zero with "diverged" or "non-fast-forward" in output) | `⚠️ diverged from <upstream> — resolve manually (git pull --rebase or merge); skill never auto-merges/rebases` |
|
||||
|
||||
### Out of scope
|
||||
|
||||
The skill never:
|
||||
|
||||
- commits, stashes, or pushes
|
||||
- recurses into submodules
|
||||
- pulls from non-`origin` remotes
|
||||
- pulls on detached HEAD
|
||||
- runs auto-merge or auto-rebase
|
||||
- runs more than once per session unless the user asks
|
||||
|
||||
## Recovery hints
|
||||
|
||||
If the skill skipped because of a dirty tree:
|
||||
|
||||
```powershell
|
||||
# Windows / PowerShell
|
||||
git status # see what's dirty
|
||||
git add . ; git commit -m "wip"
|
||||
# then ask the agent: "sync"
|
||||
```
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
git status
|
||||
git add . && git commit -m "wip"
|
||||
# then say "sync"
|
||||
```
|
||||
|
||||
If the skill reported `diverged`:
|
||||
|
||||
```bash
|
||||
# Option A: rebase your local commits on top of origin
|
||||
git pull --rebase
|
||||
|
||||
# Option B: explicit merge (creates a merge commit)
|
||||
git pull --no-ff
|
||||
```
|
||||
|
||||
The skill stays out of these decisions on purpose — both options have valid use cases and the user owns the choice.
|
||||
|
||||
## Why this exists
|
||||
|
||||
Stale local branches are a silent footgun: edits land on top of yesterday's `origin`, the divergence shows up at push time, and by then there's a chunk of work to rebase or merge on the wrong base. One pull at start covers the common case; an explicit re-sync trigger handles long sessions where someone pushed mid-flight.
|
||||
|
||||
Full design rationale (mode choice, dirty-tree skip vs stash, `--ff-only` vs auto-merge, the upstream-check) lives in `.wiki/concepts/pulling-before-work-design.md`.
|
||||
@@ -36,10 +36,6 @@ skills:
|
||||
|
||||
# ─── auto (4 universals — MVP target) ────────────────────────────────
|
||||
|
||||
pulling-before-work:
|
||||
mode: auto
|
||||
category: software-development
|
||||
|
||||
active-platform:
|
||||
mode: auto
|
||||
category: software-development
|
||||
@@ -96,18 +92,10 @@ skills:
|
||||
mode: auto
|
||||
category: productivity
|
||||
|
||||
using-tasks:
|
||||
mode: auto
|
||||
category: productivity
|
||||
|
||||
setup-wiki:
|
||||
mode: auto
|
||||
category: research
|
||||
|
||||
using-wiki:
|
||||
mode: auto
|
||||
category: research
|
||||
|
||||
setup-projects-meta:
|
||||
mode: manual
|
||||
source: hermes/skills/setup-projects-meta
|
||||
@@ -140,13 +128,6 @@ skills:
|
||||
|
||||
# ─── pending (8 — behavioral audit required) ─────────────────────────
|
||||
|
||||
delegate-task:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: mcp
|
||||
reason: "Calls mcp__projects-meta__tasks_create to create tasks in other projects/agents (Gitea commit, cross-project side-effect). Behavioral audit via delegate-task-test-trigger required before promotion to auto."
|
||||
|
||||
using-yt-tools:
|
||||
mode: pending
|
||||
intended:
|
||||
@@ -161,20 +142,6 @@ skills:
|
||||
category: mcp
|
||||
reason: "Calls mcp__vds-ops__* tools (read-only, but touches infrastructure). Behavioral audit via using-vds-ops-test-trigger required before promotion to auto."
|
||||
|
||||
using-wiki-graph:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: mcp
|
||||
reason: "Calls mcp__wiki-graph__* tools (read-only, parses a .wiki/ corpus server-side). Behavioral audit via using-wiki-graph-test-trigger required before promotion to auto."
|
||||
|
||||
session-handoff:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: productivity
|
||||
reason: "Writes .tasks/NEXT_SESSION.md (project-scope, sliding overwrite) and reads it on session start. Bidirectional file-system side-effect, opt-in via CLAUDE.md trigger-line. Behavioral audit via session-handoff-test-trigger required before promotion to auto."
|
||||
|
||||
private-dev-public-publish:
|
||||
mode: pending
|
||||
intended:
|
||||
@@ -182,20 +149,6 @@ skills:
|
||||
category: software-development
|
||||
reason: "Steps shell out to git / gh / Gitea-API, handle tokens, force-push, and repo deletion/privacy toggles — not a purely stylistic skill. Behavioral audit via private-dev-public-publish-test-trigger required before promotion to auto."
|
||||
|
||||
task-loop:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: mcp
|
||||
reason: "Orchestrates the board claim/close/update/heartbeat cycle via mcp__projects-meta__tasks_claim_next / tasks_close / tasks_update / tasks_heartbeat (cross-session claim ownership, irreversible close, Gitea side-effects) and may arm a single long ScheduleWakeup for the explicit long-watch opt-in. Critical-infra-adjacent — touches the same claim/close machinery the unattended poller relies on. Behavioral audit via task-loop-test-trigger required before promotion to auto."
|
||||
|
||||
session-inbox-monitor:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: productivity
|
||||
reason: "Paired SessionStart hook registers itself in ~/.claude/settings.json and sweeps orphaned monitor OS processes (Get-CimInstance | Stop-Process by sentinel+inbox-path); the skill then raises an in-session Monitor on .agents/inbox/. Primary activation is the CLAUDE.md trigger-line `inbox monitor: raise on start` + the injector, not a hermes-trigger. Behavioral gate CLEARED 2026-06-17 — test-trigger + review BOTH VERDICT PASS (activation 3/3 monitor + neg clean; structural hook audit 5 PASS/1 CONCERN, the CONCERN fixed in v0.2.2). STAYS pending on two independent tool-side blockers, NOT on behavioral verification: (1) the SessionStart hook is Windows-PowerShell and needs a Linux port for Hermes factory machines; (2) machine-level side-effects (user-config mutation of ~/.claude/settings.json + Get-CimInstance|Stop-Process kills) need a tool-side audit before auto. Promotion blocked on those two, not on test-trigger/review."
|
||||
|
||||
inter-session-peer-discipline:
|
||||
mode: auto
|
||||
category: meta
|
||||
@@ -220,20 +173,6 @@ skills:
|
||||
category: meta
|
||||
reason: "Resolves WHERE a project's meta lives before tasks_create / knowledge_ingest / brainstorm-promotion (meta-out-of-repo). Touches projects-meta MCP (tasks_create / knowledge_ingest / meta_status) and routes writes across repos. Review PASS (meta-host-routing-review) but the -install baseline is still open and a tool-side audit (cross-repo MCP writes) is required before auto. Mapping executes task meta-host-routing-hermes-mapping."
|
||||
|
||||
using-system-snapshot:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: mcp
|
||||
reason: "Calls mcp__projects-meta__meta_system_snapshot (read-only whole-machine ops snapshot: poller / docker / cross-project task load). Read-only, same class as using-vds-ops / using-wiki-graph; pending a behavioral test-trigger before auto."
|
||||
|
||||
task-format:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: productivity
|
||||
reason: "Documentational skill — how to write a .tasks/STATUS.md task block the autonomous poller will claim/route/report (block header, status emoji, Weight/Notify/Requirements fields). No tool-side effects; pending a behavioral test-trigger before auto."
|
||||
|
||||
setup-agents-task-runner:
|
||||
mode: pending
|
||||
reason: "L2 installer — installs the standing-duty stack (agents-task-runner + watchdog + appeals-inbox) as platform-native OS services (systemd/launchd/winsw), fetches a pinned binary, writes poller-scope.json. Heavy infra side-effects (OS services + binary fetch); mode decision (skip vs manual vs auto) deferred — needs an explicit Hermes-factory applicability audit. Placeholder pending to keep the build green."
|
||||
@@ -241,3 +180,47 @@ skills:
|
||||
ralph-loop-execution:
|
||||
mode: pending
|
||||
reason: "Behavioral oracle-loop skill (Verifier / Attempts / Max-Attempts retry loop). NB: source SKILL.md currently lacks YAML frontmatter (no name/description) — cannot auto-convert cleanly until that is fixed. Mapped pending as a placeholder; needs frontmatter + a behavioral audit before any mode decision."
|
||||
|
||||
# ─── mappa-skill-suite (7, pending — behavioral audit via mappa-skill-suite-review) ───
|
||||
mappa-messaging:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: communication
|
||||
reason: "Calls mcp__mappa__* tools (board/wiki/inbox/handoff/sessions). Behavioral audit via mappa-skill-suite-review required before promotion to auto."
|
||||
mappa-knowledge:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: research
|
||||
reason: "Calls mcp__mappa__* tools (board/wiki/inbox/handoff/sessions). Behavioral audit via mappa-skill-suite-review required before promotion to auto."
|
||||
mappa-brainstorm-promote:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: meta
|
||||
reason: "Calls mcp__mappa__* tools (board/wiki/inbox/handoff/sessions). Behavioral audit via mappa-skill-suite-review required before promotion to auto."
|
||||
mappa-delegation:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: mcp
|
||||
reason: "Calls mcp__mappa__* tools (board/wiki/inbox/handoff/sessions). Behavioral audit via mappa-skill-suite-review required before promotion to auto."
|
||||
mappa-task-work:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: productivity
|
||||
reason: "Calls mcp__mappa__* tools (board/wiki/inbox/handoff/sessions). Behavioral audit via mappa-skill-suite-review required before promotion to auto."
|
||||
mappa-closing-ritual:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: productivity
|
||||
reason: "Calls mcp__mappa__* tools (board/wiki/inbox/handoff/sessions). Behavioral audit via mappa-skill-suite-review required before promotion to auto."
|
||||
mappa-session-orient:
|
||||
mode: pending
|
||||
intended:
|
||||
mode: auto
|
||||
category: productivity
|
||||
reason: "Calls mcp__mappa__* tools (board/wiki/inbox/handoff/sessions). Behavioral audit via mappa-skill-suite-review required before promotion to auto."
|
||||
|
||||
Reference in New Issue
Block a user