OpeItcLoc03/factory
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): bundle minimum skill set from claude-skills into factory/skills/

Browse Source 
Copies 8 standalone skills (active-platform, caveman, project-discipline,
pulling-before-work, setup-tasks, setup-wiki, using-tasks, using-wiki) from
~/projects/claude-skills/skills/ and all 14 superpowers sub-skills from the
installed plugin cache into factory/skills/superpowers/.

Adds skills install step to bootstrap.ps1: copies all factory/skills/
directories to ~/.claude/skills/ so users get the skill set automatically
without manual plugin install for the baseline set.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
vitya
2026-06-11 13:24:38 +03:00
parent 62b94034f4
commit dcf4077e82
61 changed files with 10441 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
skills/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.

251
skills/using-tasks/SKILL.md Normal file
View File

@@ -0,0 +1,251 @@
---
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.