docs(forge-cli): note tea verb fallback and label id vs name in tea.md

docs(reflect): never edit package-installed skills, route lessons to project config
docs(orchestrate-herdr): cover collapsed planner identity and review gaps
2026-10-07 13:30:12 -04:00 · 2026-10-07 13:26:07 -04:00 · 2026-10-07 13:16:38 -04:00 · 2026-10-07 11:10:52 -04:00 · 2026-10-07 09:52:26 -04:00 · 2026-10-06 23:32:21 -04:00
50 changed files with 669 additions and 466 deletions
@@ -1,115 +1,32 @@
 # Project Context Pack
 Generated: 2026-07-16
 Root: /home/sjb/Projects/personal/ws-sjb-skills/wt-master
 Working directory: .
 Status: fresh
 ## Purpose
-A collection of agent skills (slash commands and behaviors) loaded into Steve Beaulac's AI coding agents. Each skill is a SKILL.md file that teaches the agent how to handle a specific task — from codebase design and TDD to Obsidian PKM workflows and tmux agent launching.
+Repository of agent skills: each skill is a folder with a `SKILL.md` plus optional references, scripts, or assets.
 ## Project type
 - **Agent skill repository** — markdown-defined agent instructions
 - Languages: Markdown (100%), one Bash script (detect-agent), one shell script (tmux-open)
 - Package managers: none
 - Build/test tools: none
 - Agent guidance: `AGENTS.md` at root, `docs/invocation.md` for invocation conventions, `docs/agents/` for issue tracker / triage labels / ADR wiki / domain docs
 ## Structure
-```
+- `skills/` — skills grouped by category; each bucket has a README index.
-.
+- `skills/setup-skills/` — one-time repo configuration skill and its supporting guides.
-├── AGENTS.md                    # Top-level agent instructions for this repo
+- `README.md` — complete index of skills by invocation type and category.
-├── README.md                    # Project overview, lists user-invoked and model-invoked skills
+- `AGENTS.md` — repository conventions and pointers to agent documentation.
-├── .gitignore                   # Excludes docs/adr/
+- `docs/invocation.md` — user-invoked vs model-invoked behavior.
-├── .agent/
+- `docs/agents/` — issue tracker, triage labels, ADR wiki, and domain-document conventions.
-│   └── project-context.md       # This file
+- `docs/engineering/` — reusable engineering process references.
-├── docs/
+- `docs/adr/` — ADR wiki clone; gitignored.
-│   ├── invocation.md            # Model-invoked vs user-invoked definitions
+- `.agent/project-context.md` — this context pack.
 │   ├── agents/
 │   │   ├── adr-wiki.md          # ADR wiki setup docs
 │   │   ├── domain.md            # Domain docs layout
 │   │   ├── issue-tracker.md     # Gitea issue tracker docs
 │   │   └── triage-labels.md     # Five-label triage vocabulary
 │   └── adr/                     # ADR wiki clone (gitignored)
 └── common/
    ├── README.md                # Lists all common skills by invocation type
    ├── engineering/             # Model-invoked: lsp-code-analysis, pkm-curation; User-invoked: commit-staged, implement-issue, project-context-pack, setup-skills
    ├── productivity/            # (currently only README.md)
    ├── pkm/                     # User-invoked: conversation-summary, crit, research-vault, youtube-video-capture; Model-invoked: pkm-curation
    ├── personal/                # (currently only README.md)
    ├── misc/                    # User-invoked: tmux-launch-agent
    ├── in-progress/             # User-invoked: agent-handoff, knowledge-gardener
    └── deprecated/              # Deprecated forge-* and dsp-* skills
 ```
-## Important files
+## Skill categories
- `AGENTS.md` — Agent entry point that describes structure, categories, and references docs
+`engineering`, `in-progress`, `misc`, `personal`, `pkm`, `pstack`, `productivity`, `setup-skills`, `skill-authoring`, and `thinking-and-docs`.
 - `README.md` — Index of all skills divided into user-invoked and model-invoked
 - `docs/invocation.md` — Defines the invocation model (disable-model-invocation frontmatter key, human vs model reachability, dependency rules)
 - `docs/agents/` — Agent documentation for issue tracker, triage labels, ADR wiki, domain docs
 - `common/engineering/project-context-pack/SKILL.md` — The skill that generated this file
 - `common/misc/tmux-launch-agent/SKILL.md` — Fork agent CLI into new tmux window (user-invoked)
 - `common/misc/tmux-launch-agent/tmux-open` — Reusable script that opens a command in a new tmux window/session
-## Commands
+## Conventions
- Build: none
+- Skills are user-invoked when frontmatter sets `disable-model-invocation: true`; otherwise they are model-invoked.
- Test: none
+- Keep root and bucket README indexes synchronized with `SKILL.md` frontmatter and file paths.
- Lint/typecheck: none
+- Read `docs/invocation.md` for invocation rules; read the relevant `docs/agents/` guide for tracker, triage, ADR, or domain-doc work.
- Run/dev: skills are invoked by AI agents — no server or dev command
+- Source files in this repository are authoritative; global installed copies are separate.
-## Entry points
+## Validation
- `AGENTS.md` — loaded by the AI agent as project instructions (referred to in pi's agent config)
+There is no build or test suite. For index changes, verify every `SKILL.md` appears once in the root index and its category index, links resolve, and invocation grouping matches frontmatter.
 - Each `SKILL.md` under `common/` — referenced by agents via slash commands or auto-invocation
 ## Search and symbol notes
 - All skills are `SKILL.md` files — search with `fd SKILL.md`
 - Bucket READMEs: `fd README.md common/`
 - Skills are classified as **user-invoked** (`disable-model-invocation: true` in frontmatter) or **model-invoked** (default, no frontmatter flag)
 - Dependencies between skills use prose invocation ("Run the `/grilling` skill"), not file cross-references
 - Shared reference docs live inside the owning skill's directory; other skills reach that material by invoking the skill
 ## Files inspected
 - `AGENTS.md` — root agent instructions — fresh
 - `README.md` — project overview and skill index — fresh
 - `docs/invocation.md` — invocation model definitions — fresh
 - `.gitignore` — excludes docs/adr/ — fresh
 - `common/README.md` — common bucket index — fresh
 - `common/misc/README.md` — misc bucket index — fresh
 - `.agent/project-context.md` — this file (refreshed from stale 2026-06-25 version)
 ## Exclusions
 - `.git/` — VCS data
 - `docs/adr/` — gitignored ADR wiki clone
 - `node_modules/`, `dist/`, `build/`, `target/`, `.venv/`, `__pycache__/`, `vendor/`, `coverage/` — not present, but excluded by policy
 - `/home/sjb/.agents/skills/` — global install, NOT the source of truth for this repo
 - Binary files, large artifacts, credentials, secrets, personal data
 ## Navigation rules for future agents
 - Start with `fd SKILL.md` to find all skills, then narrow by `fd SKILL.md common/<category>/`
 - To understand a skill's purpose, read its `SKILL.md` and the bucket `README.md` that indexes it
 - For invocation rules (user-invoked vs model-invoked), read `docs/invocation.md`
 - For agent-level docs (issue tracker, triage, ADR, domain), check `docs/agents/`
 - Do not browse directories file-by-file; use `fd` and `rg` first
 - Track every inspected file in this cache
 - Re-read a file only when it changed, the cache is stale, or exact details are needed
 ## Edit boundaries
 When cwd is inside this repo, all file edits MUST be scoped to paths under the repo root (`/home/sjb/Projects/personal/ws-sjb-skills/wt-master`). Do NOT touch files under `/home/sjb/.agents/skills/` or `/home/sjb/.pi/` — those are the installed/runtime copies, not the source of truth. The global install is synced separately; this repo is where source edits happen.
 ## Refresh notes
 - This is a markdown-only repo with no build artifacts; refreshes are rarely needed unless skills are added or removed
 - To refresh, re-run `tree -a -I '.git' -L 4` and re-read any changed bucket READMEs or SKILL.md files
 - The `docs/adr/` directory is gitignored — if ADR data is needed, check the Gitea wiki directly
 - If a skill is moved between buckets, update all README.md files that reference it (root, common, source bucket, destination bucket)
@@ -1,28 +1,19 @@
 # Steve Beaulac Skills
-A collection of agent skills (slash commands and behaviors) loaded into my agent.
+A collection of agent skills (slash commands and behaviors) loaded into AI coding agents. Skills live under `skills/`, grouped by purpose; each bucket README and the root README index its `SKILL.md` files by invocation type.
-# Structure
+## Skill buckets
 Skills are organized into buckets based on where they can be used and their category.
 - Use `/common/` for skills that work in all CLI agents.
 - Use `/common/misc/` for skills that work in all CLI agents and are in the misc category.
 - Use an agent-specific bucket only when a skill is intended for a specific agent.
 Skill are organized into categories based on their function. For example, `/common/misc/` is a bucket for miscellaneous skills that work in all CLI agents.
 If we have a skill that is only relevant to a specific agent, we can put it in an agent-specific bucket. For example, if we have a skill that is only relevant to the `opencode` agent, we can put it in `/opencode/misc`.
 ## list of categories
 - `engineering/` — daily code work
 - `productivity/` — daily non-code workflow tools
 - `misc/` — kept around but rarely used
 - `personal/` — tied to my own setup, not promoted
 - `pkm/` — personal knowledge management
 - `in-progress/` — drafts not yet ready to ship
- `deprecated/` — no longer used
+- `misc/` — kept around but rarely used
 - `personal/` — tied to the user's own setup, not promoted
 - `pkm/` — personal knowledge management
 - `pstack/` — personal agent workflow skills
 - `productivity/` — general workflow tools
 - `setup-skills/` — one-time repository setup skill and its references
 - `skill-authoring/` — create and maintain agent skills
 - `thinking-and-docs/` — decisions and documentation workflows
 Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**.
@@ -48,7 +39,7 @@ Gitea wiki at `git@gitea.sagacity.ca:steve/Skills.wiki.git`, cloned into `docs/a
 ## Project Context Pack
-Agent memory file that describes the repo's context, codebase, and navigation rules. See `.agents/project-context.md`.
+Agent memory file that describes the repo's context, codebase, and navigation rules. See `.agent/project-context.md`.
 ### Agent CLI
@@ -4,116 +4,136 @@ Agent skills (slash commands and behaviors) loaded into AI coding agents.
 Skills are grouped by invocation type. [User-invoked](docs/invocation.md) skills run only when a person invokes them; model-invoked skills can also be selected automatically.
-# Credits
+## Credits
 Many of these skills were created or originated by the following people and organizations:
- [mattpocock](http://mattpocock.com)
+
 - [Matt Pocock](http://mattpocock.com)
 - [poteto](https://github.com/poteto?tab=repositories)
 ## User-invoked
 ### Setup
 - [setup-skills](skills/setup-skills/SKILL.md) — Configure this repo for the engineering skills, issue tracker, triage label vocabulary, and domain doc layout.
 ### Engineering
 - [thermo-nuclear-code-quality-review](skills/engineering/code-quality-review/SKILL.md) — Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review.
 - [commit-staged](skills/engineering/commit-staged/SKILL.md) — Commit staged files with a conventional commit message.
- [grill-with-docs](skills/engineering/grill-with-docs/SKILL.md) — Interview the user to sharpen a plan or design while creating ADRs and glossary docs.
+- [grill-with-docs](skills/engineering/grill-with-docs/SKILL.md) — A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
- [implement](skills/engineering/implement/SKILL.md) — Implement a piece of work from a spec or set of tickets.
+- [implement](skills/engineering/implement/SKILL.md) — Implement a piece of work based on a spec or set of tickets.
- [implement-isolation](skills/engineering/implement-isolation/SKILL.md) — Implement a piece of work from a spec or set of tickets in isolation.
+- [implement-isolation](skills/engineering/implement-isolation/SKILL.md) — Implement a piece of work based on a spec or set of tickets in isolation.
- [implement-isolation-tmux](skills/engineering/implement-isolation-tmux/SKILL.md) — Dispatch an isolated worktree agent to implement work from a PRD or issues.
+- [implement-isolation-tmux](skills/engineering/implement-isolation-tmux/SKILL.md) — Dispatch a child agent in an isolated git worktree to implement a piece of work based on a PRD or set of issues.
- [improve-codebase-architecture](skills/engineering/improve-codebase-architecture/SKILL.md) — Find and work through opportunities to deepen a codebase's architecture.
+- [implement-spec](skills/engineering/implement-spec/SKILL.md) — Implement the result of /to-spec and /to-tickets in code.
- [orchestrate-herdr](skills/engineering/orchestrate-herdr/SKILL.md) — Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents.
+- [implementation-orchestrator](skills/engineering/implementation-orchestrator/SKILL.md) — Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets.
- [project-context-pack](skills/engineering/project-context-pack/SKILL.md) — Build a bounded project context pack for later agent work.
+- [improve-codebase-architecture](skills/engineering/improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
- [recipe-diagrams](skills/engineering/recipe-diagrams/SKILL.md) — Convert recipes into high-resolution process-flow diagrams.
+- [orchestrate-herdr](skills/engineering/orchestrate-herdr/SKILL.md) — Start or monitor a Herdr/Pi planner for a published spec ticket; re-invoke after an orchestrator outage.
- [setup-skills](skills/setup-skills/SKILL.md) — Configure engineering skills, issue tracking, triage labels, and domain docs.
+- [project-context-pack](skills/engineering/project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing.
- [to-spec](skills/engineering/to-spec/SKILL.md) — Turn the current conversation into a spec and publish it to the issue tracker.
+- [recipe-diagrams](skills/engineering/recipe-diagrams/SKILL.md) — Recipe diagrams: convert any recipe into a high-resolution Cooking for Engineers-style PNG process-flow table with aligned ingredient streams, preparation branches, joins, temperatures, timings, and finish steps. Use when the user asks for a recipe diagram.
- [to-tickets](skills/engineering/to-tickets/SKILL.md) — Break a plan or spec into tracer-bullet tickets with dependencies.
+- [security-audit](skills/engineering/security-audit/SKILL.md) — Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.
- [triage](skills/engineering/triage/SKILL.md) — Triage issues and external PRs through the project workflow.
+- [triage](skills/engineering/triage/SKILL.md) — Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
- [wayfinder](skills/engineering/wayfinder/SKILL.md) — Plan large work as decision tickets and resolve them step by step.
+- [wayfinder](skills/engineering/wayfinder/SKILL.md) — Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
-### In-progress
+### In Progress
- [agent-handoff](skills/in-progress/agent-handoff/SKILL.md) — Hand the current conversation to a fresh background agent.
+- [agent-handoff](skills/in-progress/agent-handoff/SKILL.md) — Hand the current conversation off to a fresh background agent that picks up the work immediately.
- [knowledge-gardener](skills/in-progress/knowledge-gardener/SKILL.md) — Run vault-aware search, synthesis, note creation, and linking workflows.
+- [knowledge-gardener](skills/in-progress/knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault.
-### Miscellaneous
+### Misc
- [bro](skills/misc/bro/SKILL.md) — Restate the last message in plain human language.
+- [bro](skills/misc/bro/SKILL.md) — Restate the last message in plain human language, with no jargon.
- [show-me](skills/misc/show-me/SKILL.md) — Help explain topics visually with concise diagrams and artifacts.
+- [show-me](skills/misc/show-me/SKILL.md) — Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
- [tmux-launch-agent](skills/misc/tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window.
+- [tmux-launch-agent](skills/misc/tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window, detected from the current agent.
- [visual-verification](skills/misc/visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings.
+- [visual-verification](skills/misc/visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings. Use when changing shell styling, layout, panels, menus, notifications, animations, transitions, or capture flows; inspect the artifacts before reporting completion.
 ### Personal
- [arch-maintenance](skills/personal/arch-maintenance/SKILL.md) — Keep an Arch/CachyOS system updated and healthy with status, check, and update workflows.
+- [arch-maintenance](skills/personal/arch-maintenance/SKILL.md) — Keep an Arch or CachyOS system updated and healthy with status, check, and update workflows.
- [arch-troubleshooting](skills/personal/arch-troubleshooting/SKILL.md) — Diagnose and repair Arch/CachyOS system problems.
+- [arch-troubleshooting](skills/personal/arch-troubleshooting/SKILL.md) — Diagnose and repair Arch or CachyOS system problems.
-### PKM
+### Pkm
- [conversation-summary](skills/pkm/conversation-summary/SKILL.md) — Save the current conversation as a report note in an Obsidian vault.
+- [conversation-summary](skills/pkm/conversation-summary/SKILL.md) — Save the current conversation as a comprehensive report note in your Obsidian vault, following OKF v0.1 conventions.
- [crit](skills/pkm/crit/SKILL.md) — Run the CRIT framework through context, role, interview, and task.
+- [crit](skills/pkm/crit/SKILL.md) — Run the CRIT framework — give the AI Context, assign it a Role, let it Interview you one question at a time, then issue the Task.
- [research-vault](skills/pkm/research-vault/SKILL.md) — Research a topic through a guided conversation and save a linked vault packet.
+- [research-vault](skills/pkm/research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked OKF-conformant research packet in the Obsidian vault.
- [youtube-video-capture](skills/pkm/youtube-video-capture/SKILL.md) — Capture a YouTube video's subtitles and summary in an Obsidian vault.
+- [youtube-video-capture](skills/pkm/youtube-video-capture/SKILL.md) — Fetch subtitles from a YouTube video, summarize the content, and save both the summary and raw subtitles to the Video bundle in the Obsidian vault. Use when the user wants to capture a YouTube video, mentions "summarize this video", "capture this talk", or pastes a YouTube URL wanting it saved to vault.
 ### Productivity
- [grill-me](skills/productivity/grill-me/SKILL.md) — Interview the user to sharpen a plan or design.
+- [grill-me](skills/productivity/grill-me/SKILL.md) — A relentless interview to sharpen a plan or design.
- [handoff](skills/productivity/handoff/SKILL.md) — Compact the current conversation into a handoff document.
+- [handoff](skills/productivity/handoff/SKILL.md) — Compact the current conversation into a handoff document for another agent to pick up.
- [teach](skills/productivity/teach/SKILL.md) — Teach the user a new skill or concept within the workspace.
+- [to-questionnaire](skills/productivity/to-questionnaire/SKILL.md) — Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
- [to-questionnaire](skills/productivity/to-questionnaire/SKILL.md) — Turn an unresolved decision into a questionnaire.
+- [wait-what](skills/productivity/wait-what/SKILL.md) — Stop. That last message did not land: re-pitch it.
 - [wait-what](skills/productivity/wait-what/SKILL.md) — Re-pitch the last message in clearer terms.
-### Skill authoring
+### Pstack
-No user-invoked skills.
+- [bugfix-regression-test](skills/pstack/bugfix-regression-test/SKILL.md) — Fix bugs test-first with a focused regression test when practical.
 - [interrogate](skills/pstack/interrogate/SKILL.md) — Use for "interrogate", "adversarial review", "multi-model review", "challenge this", "stress test this code", "find blind spots", or "tear this apart". Uses available subagents for independent, evidence-backed review.
-### Thinking and docs
+### Thinking And Docs
- [before-building](skills/thinking-and-docs/before-building/SKILL.md) — Surface consequential choices when the user proposes a build.
+- [before-building](skills/thinking-and-docs/before-building/SKILL.md) — Fire the moment the user proposes a build. Instantly surface the 1-3 consequential choices hidden in his idea. Can also be invoked with /before-building.
- [decisions](skills/thinking-and-docs/decisions/SKILL.md) — List choices made during the current work that remain uncertain.
+- [decisions](skills/thinking-and-docs/decisions/SKILL.md) — Ask the agent to list all choices it made during the current work that it is not confident of. Manual-only; invoke with /decisions.
- [level-up](skills/thinking-and-docs/level-up/SKILL.md) — Assess technical and product knowledge and grow a learning plan.
+- [level-up](skills/thinking-and-docs/level-up/SKILL.md) — Gauge the user''s technical + product knowledge through 7 adaptive questions, log verbatim answers with honest ratings, and grow a learning plan from the gaps found. Use when the user says "level up", "level-up session", "quiz me", "gauge my knowledge", or wants a new assessment round. Differentiator: this finds and maps gaps; the `teach` skill delivers lessons on them.
- [read-all-adrs](skills/thinking-and-docs/read-all-adrs/SKILL.md) — Read every ADR in the project's `docs/adr/` folder.
+- [read-all-adrs](skills/thinking-and-docs/read-all-adrs/SKILL.md) — Read every ADR markdown file in the project's docs/adr/ folder so you have full context on past decisions. Use only when the user explicitly calls it.
- [remind](skills/thinking-and-docs/remind/SKILL.md) — Rewrite the last response more simply and briefly.
+- [remind](skills/thinking-and-docs/remind/SKILL.md) — Rewrite the last response simpler and shorter in plain English, prefixed with a 3-5 sentence TLDR of the conversation so far. Manual-only, invoked as /remind.
- [short](skills/thinking-and-docs/short/SKILL.md) — Compress the current answer while keeping its substance.
+- [short](skills/thinking-and-docs/short/SKILL.md) — Manually-invoked skill that forces the agent to compress its current answer — strip filler, simplify wording, and cut length while keeping the substance. Use when the user says "short", "shorter", "simpler", "too long", "tl;dr", or wants a more concise version of the previous response.
- [teach](skills/thinking-and-docs/teach/SKILL.md) — Teach the user a new skill or concept within the workspace.
+- [teach](skills/thinking-and-docs/teach/SKILL.md) — Teach the user a new skill or concept, within this workspace.
 ## Model-invoked
 ### Engineering
- [code-review](skills/engineering/code-review/SKILL.md) — Review changes against repository standards and the originating specification.
+- [feedback-bundle](skills/engineering/feedback-bundle/SKILL.md) — Post a Gitea feedback issue linked to the current commit and attach logs or screenshots. Use when the user reports a problem and asks to file it with evidence, open a bug ticket, or says “feedback-bundle” or “attach the log.”
- [codebase-design](skills/engineering/codebase-design/SKILL.md) — Design and improve deep module interfaces and seams.
+- [code-review](skills/engineering/code-review/SKILL.md) — Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
- [dual-review](skills/engineering/dual-review/SKILL.md) — Run parallel correctness/security and maintainability reviews of a branch diff, then synthesize findings.
+- [codebase-design](skills/engineering/codebase-design/SKILL.md) — Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
- [diagnosing-bugs](skills/engineering/diagnosing-bugs/SKILL.md) — Diagnose hard bugs and performance regressions.
+- [diagnosing-bugs](skills/engineering/diagnosing-bugs/SKILL.md) — Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
- [domain-modeling](skills/engineering/domain-modeling/SKILL.md) — Build and sharpen a project's domain model.
+- [domain-modeling](skills/engineering/domain-modeling/SKILL.md) — Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
- [lsp-code-analysis](skills/engineering/lsp-code-analysis/SKILL.md) — Navigate code and analyze it semantically with LSP.
+- [dual-review](skills/engineering/dual-review/SKILL.md) — Run two independent, read-only reviews of a branch diff in parallel — correctness/security and maintainability — then synthesize prioritized findings. Use for a second review axis alongside code-review, a combined deep plus code-quality audit, or when the user asks for dual review. Runs both axes as parallel sub-agents so they do not pollute each other's context.
- [prototype](skills/engineering/prototype/SKILL.md) — Build a throwaway prototype to answer a design question.
+- [forge-cli](skills/engineering/forge-cli/SKILL.md) — Provides copy-paste, non-interactive tea, gh, and glab commands for issue and pull or merge request work. Use whenever a task needs tracker inspection, assignment, labels, comments, reviews, CI, or merge operations.
- [research](skills/engineering/research/SKILL.md) — Investigate a question using high-trust sources and capture the findings.
+- [lsp-code-analysis](skills/engineering/lsp-code-analysis/SKILL.md) — Semantic code analysis via LSP. Navigate code (definitions, references, implementations), search symbols, preview refactorings, and get file outlines. Use for exploring unfamiliar codebases or performing safe refactoring.
- [resolving-merge-conflicts](skills/engineering/resolving-merge-conflicts/SKILL.md) — Resolve an in-progress Git merge or rebase conflict.
+- [pr](skills/engineering/pr/SKILL.md) — Use when writing a PR body.
- [tdd](skills/engineering/tdd/SKILL.md) — Use test-driven development for features, bugs, and integration tests.
+- [prototype](skills/engineering/prototype/SKILL.md) — Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
- [wizard](skills/engineering/wizard/SKILL.md) — Generate an interactive wizard for steps only a human can perform.
+- [research](skills/engineering/research/SKILL.md) — Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
- [worktrees](skills/engineering/worktrees/SKILL.md) — Manage Git worktrees in a canonical repository root.
+- [resolving-merge-conflicts](skills/engineering/resolving-merge-conflicts/SKILL.md) — Use when you need to resolve an in-progress git merge/rebase conflict.
- [write-discoverable-code](skills/engineering/write-discoverable-code/SKILL.md) — Write code agents and humans can find through plain-text search.
+- [tdd](skills/engineering/tdd/SKILL.md) — Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
 - [to-spec](skills/engineering/to-spec/SKILL.md) — Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed. Use when the user wants a spec from the current conversation or an orchestration workflow needs to publish one from context.
 - [to-tickets](skills/engineering/to-tickets/SKILL.md) — Break a plan, spec, or the current conversation into tracer-bullet tickets with blocking edges, published to the configured tracker. Use when the user wants tickets from a plan or spec, or an orchestration workflow needs agent-grabbable tickets.
 - [wizard](skills/engineering/wizard/SKILL.md) — Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
 - [worktrees](skills/engineering/worktrees/SKILL.md) — Manage Git worktrees in a canonical `.bare` repository root. Use when creating, reusing, listing, removing, or repairing worktrees, or when setting up a repository to keep all branch checkouts under one root.
 - [write-discoverable-code](skills/engineering/write-discoverable-code/SKILL.md) — |
-### Miscellaneous
+### Misc
- [migrate-to-shoehorn](skills/misc/migrate-to-shoehorn/SKILL.md) — Migrate test assertions from `as` to `@total-typescript/shoehorn`.
+- [migrate-to-shoehorn](skills/misc/migrate-to-shoehorn/SKILL.md) — Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
- [scaffold-exercises](skills/misc/scaffold-exercises/SKILL.md) — Create linted exercise directories with problems, solutions, and explainers.
+- [scaffold-exercises](skills/misc/scaffold-exercises/SKILL.md) — Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
- [setup-pre-commit](skills/misc/setup-pre-commit/SKILL.md) — Set up Husky, lint-staged, type checking, and tests.
+- [setup-pre-commit](skills/misc/setup-pre-commit/SKILL.md) — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
-### PKM
+### Pkm
- [pkm-curation](skills/pkm/pkm-curation/SKILL.md) — Curate an Obsidian vault with classification, links, and atomic notes.
+- [pkm-curation](skills/pkm/pkm-curation/SKILL.md) — Curate an Obsidian vault — classify notes, normalize frontmatter, add links, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick.
 ### Productivity
- [grilling](skills/productivity/grilling/SKILL.md) — Grill the user relentlessly about a plan or design.
+- [grilling](skills/productivity/grilling/SKILL.md) — Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
- [writing-for-agents](skills/productivity/writing-for-agents/SKILL.md) — Write effective documents for agents.
+- [writing-for-agents](skills/productivity/writing-for-agents/SKILL.md) — Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
-### Skill authoring
+### Pstack
- [effective-agent-skills](skills/skill-authoring/effective-agent-skills/SKILL.md) — Write, review, and debug effective agent skills.
+- [fix-merge-conflicts](skills/pstack/fix-merge-conflicts/SKILL.md) — Resolve merge conflicts non-interactively, validate build and tests, and finalize conflict resolution
 - [how](skills/pstack/how/SKILL.md) — Use for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live", "which package owns this", "is this the right layer"). Explains subsystem architecture, runtime flow, onboarding mental models. Can critique architecture. Use why for motivation.
 - [reflect](skills/pstack/reflect/SKILL.md) — Review a conversation for durable learnings and propose targeted edits to existing agent skills. Use when the user says "reflect", or when a complex workflow, correction, or recoverable dead end produced a reusable lesson.
 - [unslop](skills/pstack/unslop/SKILL.md) — Cut AI writing patterns while preserving meaning and voice. Use when drafting, editing, or polishing prose, messages, or documentation.
 - [why](skills/pstack/why/SKILL.md) — Investigate why code exists or behaves this way using cited historical evidence. Use for design rationale, tradeoffs, regressions, postmortems, and data-backed thresholds. Distinguishes motivation from how the code currently works.
-### Thinking and docs
+### Skill Authoring
- [brain-to-docs](skills/thinking-and-docs/brain-to-docs/SKILL.md) — Extract project vision, decisions, and preferences into documentation.
+- [effective-agent-skills](skills/skill-authoring/effective-agent-skills/SKILL.md) — How to write effective agent skills — what to do, what not to do, anatomy, progressive disclosure, design patterns, anti-patterns, testing, security. Read this whenever a skill (Claude Skill, Agent Skill, SKILL.md) is being created, edited, reviewed, or debugged. Use when the user says "create a skill", "new skill", "update this skill", "improve a skill", "why isn't my skill triggering", or anything else involving authoring or editing SKILL.md files.
- [next-decision](skills/thinking-and-docs/next-decision/SKILL.md) — Drill into the next unresolved decision with choices and a recommendation.
+
- [prompt-me](skills/thinking-and-docs/prompt-me/SKILL.md) — Ask pointed questions to extract project priorities and concerns.
+### Thinking And Docs
- [save-idea](skills/thinking-and-docs/save-idea/SKILL.md) — Capture content ideas in the user's content backlog.
+
 - [brain-to-docs](skills/thinking-and-docs/brain-to-docs/SKILL.md) — Use when the user wants to extract project vision, decisions, and preferences from his head into clear documentation (README + ADRs) through a back-and-forth Q&A loop. Triggers on "brain-to-docs", "build out the docs", "extract the vision", "let's document this project".
 - [next-decision](skills/thinking-and-docs/next-decision/SKILL.md) — Drill open decisions one at a time — present the most important decision not yet clarified, give the top four choices, state a preference, ask the user. Use when the user says "next decision", "one decision at a time", or a plan has several unresolved choices. Differentiator: forward-looking; the decisions skill is retrospective (choices already made). Can be invoked with /next-decision.
 - [prompt-me](skills/thinking-and-docs/prompt-me/SKILL.md) — Prompt the user with pointed questions to extract what is in his head about a project — remaining work, what is being avoided, what really matters, what does not. Use when the user says "prompt me", "ask me questions", or wants the agent to figure out priorities by questioning him.
 - [save-idea](skills/thinking-and-docs/save-idea/SKILL.md) — Quickly capture a content idea into ~/code/content from any repo or chat. Video ideas go to VIDEO-IDEAS.md; smaller podcast topics, guest ideas, questions, and AI observations go to TOPICS.md. Every entry gets a source line referencing the chat and repo it came from. Use when the user says "/save-idea", "save this idea", "video idea", "add a topic", "write this down for a video/podcast". Differentiator: appends to the user''s content backlog — not a reminder, task, or general note tool.
@@ -4,33 +4,39 @@ Daily code work.
 ## User-invoked
 - [thermo-nuclear-code-quality-review](code-quality-review/SKILL.md) — Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review.
 - [commit-staged](commit-staged/SKILL.md) — Commit staged files with a conventional commit message.
- [grill-with-docs](grill-with-docs/SKILL.md) — Interview the user to sharpen a plan or design while creating ADRs and glossary docs.
+- [grill-with-docs](grill-with-docs/SKILL.md) — A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
- [implement](implement/SKILL.md) — Implement a piece of work from a spec or set of tickets.
+- [implement](implement/SKILL.md) — Implement a piece of work based on a spec or set of tickets.
- [implement-isolation](implement-isolation/SKILL.md) — Implement a piece of work from a spec or set of tickets in isolation.
+- [implement-isolation](implement-isolation/SKILL.md) — Implement a piece of work based on a spec or set of tickets in isolation.
- [implement-isolation-tmux](implement-isolation-tmux/SKILL.md) — Dispatch an isolated worktree agent to implement work from a PRD or issues.
+- [implement-isolation-tmux](implement-isolation-tmux/SKILL.md) — Dispatch a child agent in an isolated git worktree to implement a piece of work based on a PRD or set of issues.
- [improve-codebase-architecture](improve-codebase-architecture/SKILL.md) — Find and work through opportunities to deepen a codebase's architecture.
+- [implement-spec](implement-spec/SKILL.md) — Implement the result of /to-spec and /to-tickets in code.
- [orchestrate-herdr](orchestrate-herdr/SKILL.md) — Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents.
+- [implementation-orchestrator](implementation-orchestrator/SKILL.md) — Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets.
- [project-context-pack](project-context-pack/SKILL.md) — Build a bounded project context pack for later agent work.
+- [improve-codebase-architecture](improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
- [recipe-diagrams](recipe-diagrams/SKILL.md) — Convert recipes into high-resolution process-flow diagrams.
+- [orchestrate-herdr](orchestrate-herdr/SKILL.md) — Start or monitor a Herdr/Pi planner for a published spec ticket; re-invoke after an orchestrator outage.
- [setup-skills](../setup-skills/SKILL.md) — Configure engineering skills, issue tracking, triage labels, and domain docs.
+- [project-context-pack](project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing.
- [to-spec](to-spec/SKILL.md) — Turn the current conversation into a spec and publish it to the issue tracker.
+- [recipe-diagrams](recipe-diagrams/SKILL.md) — Recipe diagrams: convert any recipe into a high-resolution Cooking for Engineers-style PNG process-flow table with aligned ingredient streams, preparation branches, joins, temperatures, timings, and finish steps. Use when the user asks for a recipe diagram.
- [to-tickets](to-tickets/SKILL.md) — Break a plan or spec into tracer-bullet tickets with dependencies.
+- [security-audit](security-audit/SKILL.md) — Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.
- [triage](triage/SKILL.md) — Triage issues and external PRs through the project workflow.
+- [triage](triage/SKILL.md) — Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
- [wayfinder](wayfinder/SKILL.md) — Plan large work as decision tickets and resolve them step by step.
+- [wayfinder](wayfinder/SKILL.md) — Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
 ## Model-invoked
- [code-review](code-review/SKILL.md) — Review changes against repository standards and the originating specification.
+- [feedback-bundle](feedback-bundle/SKILL.md) — Post a Gitea feedback issue linked to the current commit and attach logs or screenshots. Use when the user reports a problem and asks to file it with evidence, open a bug ticket, or says “feedback-bundle” or “attach the log.”
- [codebase-design](codebase-design/SKILL.md) — Design and improve deep module interfaces and seams.
+- [code-review](code-review/SKILL.md) — Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes: Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
- [dual-review](dual-review/SKILL.md) — Run parallel correctness/security and maintainability reviews of a branch diff, then synthesize findings.
+- [codebase-design](codebase-design/SKILL.md) — Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
- [diagnosing-bugs](diagnosing-bugs/SKILL.md) — Diagnose hard bugs and performance regressions.
+- [diagnosing-bugs](diagnosing-bugs/SKILL.md) — Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
- [domain-modeling](domain-modeling/SKILL.md) — Build and sharpen a project's domain model.
+- [domain-modeling](domain-modeling/SKILL.md) — Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
- [lsp-code-analysis](lsp-code-analysis/SKILL.md) — Navigate code and analyze it semantically with LSP.
+- [dual-review](dual-review/SKILL.md) — Run two independent, read-only reviews of a branch diff in parallel — correctness/security and maintainability — then synthesize prioritized findings. Use for a second review axis alongside code-review, a combined deep plus code-quality audit, or when the user asks for dual review. Runs both axes as parallel sub-agents so they do not pollute each other's context.
- [prototype](prototype/SKILL.md) — Build a throwaway prototype to answer a design question.
+- [forge-cli](forge-cli/SKILL.md) — Provides copy-paste, non-interactive tea, gh, and glab commands for issue and pull or merge request work. Use whenever a task needs tracker inspection, assignment, labels, comments, reviews, CI, or merge operations.
- [research](research/SKILL.md) — Investigate a question using high-trust sources and capture the findings.
+- [lsp-code-analysis](lsp-code-analysis/SKILL.md) — Semantic code analysis via LSP. Navigate code (definitions, references, implementations), search symbols, preview refactorings, and get file outlines. Use for exploring unfamiliar codebases or performing safe refactoring.
- [resolving-merge-conflicts](resolving-merge-conflicts/SKILL.md) — Resolve an in-progress Git merge or rebase conflict.
+- [pr](pr/SKILL.md) — Use when writing a PR body.
- [tdd](tdd/SKILL.md) — Use test-driven development for features, bugs, and integration tests.
+- [prototype](prototype/SKILL.md) — Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
- [wizard](wizard/SKILL.md) — Generate an interactive wizard for steps only a human can perform.
+- [research](research/SKILL.md) — Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
- [worktrees](worktrees/SKILL.md) — Manage Git worktrees in a canonical repository root.
+- [resolving-merge-conflicts](resolving-merge-conflicts/SKILL.md) — Use when you need to resolve an in-progress git merge/rebase conflict.
- [write-discoverable-code](write-discoverable-code/SKILL.md) — Write code agents and humans can find through plain-text search.
+- [tdd](tdd/SKILL.md) — Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
 - [to-spec](to-spec/SKILL.md) — Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed. Use when the user wants a spec from the current conversation or an orchestration workflow needs to publish one from context.
 - [to-tickets](to-tickets/SKILL.md) — Break a plan, spec, or the current conversation into tracer-bullet tickets with blocking edges, published to the configured tracker. Use when the user wants tickets from a plan or spec, or an orchestration workflow needs agent-grabbable tickets.
 - [wizard](wizard/SKILL.md) — Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
 - [worktrees](worktrees/SKILL.md) — Manage Git worktrees in a canonical `.bare` repository root. Use when creating, reusing, listing, removing, or repairing worktrees, or when setting up a repository to keep all branch checkouts under one root.
 - [write-discoverable-code](write-discoverable-code/SKILL.md) — |
@@ -1,10 +1,10 @@
 ---
-name: thermo-nuclear-code-quality-review
+name: code-quality-review
-description: Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review.
+description: Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a code quality review, deep code quality audit, or especially harsh maintainability review.
 disable-model-invocation: true
 ---
-# Thermo-Nuclear Code Quality Review
+# Code Quality Review
 Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Thermo-Nuclear Code Quality Review"
  short_description: "Strict review of abstractions, large files, and condition complexity"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Dual Review"
  short_description: "Parallel correctness, security, and maintainability review"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,40 @@
 ---
 name: feedback-bundle
 description: Post a Gitea feedback issue linked to the current commit and attach logs or screenshots. Use when the user reports a problem and asks to file it with evidence, open a bug ticket, or says "feedback-bundle" or "attach the log".
 ---
 # Feedback Bundle
 Create a Gitea issue in the current repository, linked to its current `HEAD`, with optional files attached.
 ## Run
 Run from the repository the issue should belong to, using `feedback_bundle.py` beside this file:
 ```sh
 python3 <skill-dir>/feedback_bundle.py "Describe the problem" @app.log @screenshot.png
 ```
 The script requires Python `requests`. Without `--token`, it reads the matching host token from `~/.config/tea/config.yml` and requires PyYAML. The default repository is read from `git remote get-url origin`.
 Common options:
 ```sh
 python3 <skill-dir>/feedback_bundle.py "Description" @log.txt \
  --title "Short issue title" --label bug --dry-run
 ```
 - `@file` — attach an existing file; paths are resolved from the current working directory. The `@` is optional.
 - `--title` — override the default title (the description's first line).
 - `--label` — add a label; repeat to add more. Labels are resolved against the repository's Gitea labels; unknown labels are skipped with a warning.
 - `--repo` — override the remote URL. Use a full Git remote URL (SSH, SCP-style, or HTTPS), not an `owner/repo` slug.
 - `--token` — provide a Gitea token instead of reading tea config.
 - `--dry-run` — print the issue preview without creating an issue or uploading files. Authentication is still loaded; labels require an API request.
 ## What happens
 1. The script reads `HEAD`, repository host/owner/name, and authentication.
 2. It creates an issue whose body includes a link to that exact commit.
 3. It uploads each attachment to the issue and adds download links to the body.
 Gitea only accepts issue attachments after an issue exists. If uploads fail because attachments are disabled (403/404), the issue already exists without the files; enable attachments on the Gitea instance, then attach the files to that issue manually. The instance setting is `[attachment] ENABLED = true` in `app.ini` (or `ATTACHMENTS_ENABLED`), not a web UI toggle.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Feedback Bundle"
  short_description: "File Gitea issues with commit links and attached evidence"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,183 @@
 #!/usr/bin/env python3
 """Post a feedback ticket to a Gitea repo, linked to the current commit, with
 files attached to the issue.
    feedback_bundle.py [--title T] [--label L ...] [--repo REMOTE_URL] [--token T]
                       [--dry-run] <description> [@file ...]
 Flow (Gitea attaches files to an existing issue, there is no standalone upload
 endpoint): create the issue, then POST each file to
 /repos/{owner}/{repo}/issues/{number}/assets (multipart field "attachment").
 The ticket body links to `git HEAD` and lists the attached files.
 If the assets endpoint returns 403/404 the instance has attachments disabled
 (admin `[attachment] ENABLED = true` in app.ini — not a web-UI setting); the
 script reports this instead of posting a ticket with no attachments.
 """
 from __future__ import annotations
 import argparse
 import os
 import re
 import subprocess
 import sys
 try:
    import requests
 except ImportError:  # pragma: no cover
    sys.exit("requests is required: pip install requests")
 def run(*args: str) -> str:
    return subprocess.run(args, capture_output=True, text=True, check=True).stdout.strip()
 def parse_remote(remote: str | None) -> tuple[str, str, str]:
    """(host, owner, repo) from a git remote URL (scp, ssh, or https forms)."""
    url = remote or run("git", "remote", "get-url", "origin")
    u = re.sub(r"^[a-z]+://", "", url.strip(), flags=re.I)  # strip scheme
    u = u.split("@", 1)[-1]                                  # strip user@
    u = u.replace(".git", "").rstrip("/")
    host, rest = (u.split(":", 1) if ":" in u else u.split("/", 1))
    owner, repo = rest.split("/", 1)
    return host, owner, repo
 def load_token(host: str, token: str | None) -> str:
    if token:
        return token
    cfg = os.path.expanduser("~/.config/tea/config.yml")
    if not os.path.exists(cfg):
        sys.exit("no --token and no tea config found; cannot authenticate")
    import yaml
    data = yaml.safe_load(open(cfg).read())
    for login in data.get("logins", []):
        if login.get("url").rstrip("/").endswith(host) and login.get("token"):
            return login["token"]
    sys.exit(f"no stored token for host {host}; pass --token")
 def resolve_labels(host, token, owner, repo, names):
    """Gitea's issue API wants label IDs, not names. Map names to IDs; warn on
    unknown labels and drop them."""
    if not names:
        return []
    url = f"https://{host}/api/v1/repos/{owner}/{repo}/labels"
    r = requests.get(url, headers={"Authorization": f"token {token}"})
    if r.status_code >= 400:
        sys.exit(f"could not list labels ({r.status_code}): {r.text}")
    by_name = {l["name"]: l["id"] for l in r.json()}
    ids = []
    for n in names:
        if n in by_name:
            ids.append(by_name[n])
        else:
            print(f"warning: unknown label '{n}', skipping", file=sys.stderr)
    return ids
 def create_issue(host, token, owner, repo, title, body, label_ids):
    url = f"https://{host}/api/v1/repos/{owner}/{repo}/issues"
    r = requests.post(url, json={"title": title, "body": body, "labels": label_ids},
                      headers={"Authorization": f"token {token}"})
    if r.status_code >= 400:
        sys.exit(f"issue create failed ({r.status_code}): {r.text}")
    return r.json()
 def attach(host, token, owner, repo, issue_number, path):
    """Attach one file to an issue. Returns the browser_download_url, or None
    on 403/404 (attachments disabled on this instance)."""
    url = f"https://{host}/api/v1/repos/{owner}/{repo}/issues/{issue_number}/assets"
    with open(path, "rb") as f:
        r = requests.post(url, files={"attachment": f},
                          params={"name": os.path.basename(path)},
                          headers={"Authorization": f"token {token}"})
    if r.status_code in (403, 404):
        return None
    r.raise_for_status()
    return r.json().get("browser_download_url")
 def main() -> int:
    ap = argparse.ArgumentParser(description="Post a commit-linked feedback ticket with attachments.")
    ap.add_argument("description", help="ticket description (text before any @file)")
    ap.add_argument("files", nargs="*", help="files to attach (@name or name)")
    ap.add_argument("--title", help="ticket title (default: first line of description)")
    ap.add_argument("--label", action="append", default=[], help="label to add (repeatable)")
    ap.add_argument("--repo", help="Git remote URL (default: git remote origin)")
    ap.add_argument("--token", help="Gitea token (default: tea config for the host)")
    ap.add_argument("--dry-run", action="store_true", help="print the ticket without posting it")
    args = ap.parse_args()
    files = [f.lstrip("@") for f in args.files]
    for p in files:
        if not os.path.isfile(p):
            sys.exit(f"not a file: {p}")
    host, owner, repo = parse_remote(args.repo) if args.repo else (None, None, None)
    if not host:
        host, owner, repo = parse_remote(None)
    token = load_token(host, args.token)
    sha = run("git", "rev-parse", "HEAD")
    short = sha[:7]
    commit_url = f"https://{host}/{owner}/{repo}/commit/{sha}"
    desc = args.description.strip()
    title = (args.title or desc).strip().splitlines()[0] if desc else "(no description)"
    labels = resolve_labels(host, token, owner, repo, [l for l in args.label if l])
    seed = f"{desc}\n\n**Linked commit:** [{short}]({commit_url}) (`{sha}`)"
    # Preview only: no issue is created and nothing is uploaded.
    if args.dry_run:
        att_line = "\n".join(f"- {os.path.basename(p)}" for p in files) or "(none)"
        body = seed + "\n\n**Attachments:**\n" + att_line
        print("=== DRY RUN (nothing created) ===")
        print(f"repo:    {owner}/{repo}")
        print(f"commit:  {commit_url}")
        print(f"title:   {title}")
        print(f"labels:  {[l for l in args.label if l] or '(none)'}")
        print(f"attach:  {att_line}")
        print("=== body ===")
        print(body)
        return 0
    # Create the issue first (Gitea attaches files to an existing issue).
    issue = create_issue(host, token, owner, repo, title, seed, labels)
    number = issue["number"]
    attached = []
    missing = False
    for p in files:
        url = attach(host, token, owner, repo, number, p)
        if url is None:
            missing = True
        else:
            attached.append((os.path.basename(p), url))
    if missing and not attached:
        print(
            "ERROR: attachment endpoint returned 403/404 — attachments are disabled on this "
            "instance (admin setting `[attachment] ENABLED = true` in app.ini; there is no "
            "web-UI toggle). Enable it and re-run. The issue was created but has no attachments.",
            file=sys.stderr,
        )
        return 2
    if attached:
        body = seed + "\n\n**Attachments:**\n" + "\n".join(f"- [{n}]({u})" for n, u in attached)
        patch_url = f"https://{host}/api/v1/repos/{owner}/{repo}/issues/{number}"
        requests.patch(patch_url, json={"body": body},
                       headers={"Authorization": f"token {token}"})
    if missing:
        print(f"warning: {sum(1 for _ in range(0)) + (len(files) - len(attached))} file(s) could not be attached (instance may have attachments disabled)",
              file=sys.stderr)
    print(f"Created: {issue.get('html_url', '')}")
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -21,6 +21,8 @@ tea comments add ID --description "$(cat BODY_FILE)"
 tea issues close ID
 ```
 Prefer these CLI verbs over hand-rolled REST. If `tea` lacks a verb (check `tea pulls --help` for the current close and merge verbs), and you fall back to the Gitea REST API, note that the issue create/update payload takes label **IDs**, while the `/issues/{id}/labels` sub-resource takes **names**. Keep `curl` output out of the transcript by writing it to a file (`curl -s ... -o FILE`).
 ## Pull request lifecycle
 ```bash
@@ -6,7 +6,7 @@ disable-model-invocation: true
 You have been provided a spec. This spec should have tickets associated with it, describing how to implement the spec.
-The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
+The issue tracker should have been provided to you. If not, tell the user to run `/setup-skills`.
 The goal is the entire spec implemented on a single **integration branch**, with every ticket resolved the way the issue tracker closes work.
@@ -44,7 +44,7 @@ Comments are the message board. Record claims, status, evidence, questions, deci
 4. **Implement.** Launch one worker per ticket with `pi-subagents` in an isolated worktree, maximum three in flight by default. Pass the complete ticket, comments, acceptance criteria, non-goals, linked context, and validation contract. Each worker makes only ticket-scoped changes, commits them, and reports changed files and checks.
 5. **Escalate.** For missing requirements, unsafe ambiguity, credentials, unrelated scope, or a product/architecture decision, stop. For human review or judgment, assign the ticket to the configured human reviewer, apply `workflow:ready-for-human`, and comment the exact request. If no human identity is configured, ask before assigning and changing the state. Use `workflow:blocked` for non-human blockers. Preserve the worktree on failure.
 6. **PR.** Run documented local checks. Push the branch and create exactly one PR/MR for the ticket. Link the ticket's tracker ID and title in the PR/MR, set `workflow:pr-open`, and comment the PR/MR URL on the ticket. Keep the worktree.
-7. **Review.** Set `workflow:review`. Run a fresh-context `code-review` review with correctness/spec and standards axes separate. Post findings through the PR/MR comment/review function. For actionable findings, set `workflow:changes-requested`, send one fix worker, rerun checks, and repeat. Allow at most three rounds.
+7. **Review.** Set `workflow:review`. Run a fresh-context `code-review` review with correctness/spec and standards axes separate. Then run the `security-audit` and `code-quality-review` both in their own `reviewer` subagent. Post findings through the PR/MR comment/review function. For actionable findings, set `workflow:changes-requested`, send one fix worker, rerun checks, and repeat. Allow at most three rounds.
 8. **Conflict.** Set `workflow:conflict`, then follow `resolving-merge-conflicts`. Inspect both intents, preserve them where possible, never invent behavior, never abort, rerun local checks, and update the PR/MR. If judgment is needed, assign the PR/MR and ticket to the configured human reviewer, apply `workflow:ready-for-human`, and comment the request in both places. If no human identity is configured, ask before assigning.
 9. **Merge.** Merge only after independent review is clean, local checks pass, forge CI is green, the target is still the expected default branch, and no human decision or blocker remains. Comment the merge receipt and outcome, close the ticket, apply `workflow:merged` when supported, verify integration, then remove the worktree.
 10. **Finish.** Report merged tickets and PR/MR URLs, human handoffs, blocked tickets, failed checks, review rounds, and remaining eligible tickets. Report `done` only when no open implementation or human tickets remain in the selected scope. If only human tickets remain, report `waiting-on-human`.
@@ -1,87 +1,29 @@
 ---
 name: orchestrate-herdr
-description: "Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents."
+description: "Start a Herdr/Pi planner for a published spec ticket. Invocation: /skill:orchestrate-herdr ISSUE [WORKER]; omitted worker uses the current local worker."
 disable-model-invocation: true
 ---
-# Orchestrate plans to merged PRs with Herdr
+# Orchestrate a spec with Herdr
-Turn a plan into a published spec and child tickets, then drive one tracker ticket at a time through isolated implementation, independent verification, four-axis review, and merge. The worker node is the source of truth for run state, so a later orchestrator system can reconnect and resume.
+This skill takes a tracker issue number and optional Herdr worker node. It checks whether a planner is already running for that spec; if so, it reports that and exits. Otherwise it starts a planner and exits after confirming startup. The planner runs independently; there is no need to monitor it.
-This skill is a **routing and safety contract**. Operational detail lives in `references/`:
+The **planner**  runs on the worker node and coordinates the spec workflow. It delegates implementation, review, and merge work to subagents—not separate CLI agents or Herdr-launched agents. Never attach to, prompt, or resume an existing agent.
- `references/dispatcher.md` — select and validate the worker node, local or remote, and discover Herdr state before dispatch.
+When the invoking session is itself the planner — the local worker started the planner in this session, or no saved or matching machine and pane exists — the two identities collapse. Do not go looking for a planner to monitor: run the run-loop directly in this session, skip the launch-claim and monitor ceremony, and record the session as both orchestrator and planner in `run.json`.
 - `references/run-loop.md` — plan and publish, then the one-at-a-time task loop: claim, implement, verify, review, fix, merge, close.
 - `references/state.md` — the `.orchestrate/<slug>` state directory, recovery, cross-system sync, and cleanup.
-Read the reference for the phase you are in before acting in it.
+Read these references before acting:
 - `references/dispatcher.md` — discover an existing run or safely start a planner.
 - `references/run-loop.md` — implement and close the spec.
 - `references/state.md` — worker-side run metadata, event log, claims, and recovery.
 ## Prerequisites
- Herdr, Pi, Git, and a forge CLI (`tea`, `gh`, or `glab`) reachable from the worker node. Run the `forge-cli` preflight in the target repo.
+The selected worker must have Herdr, Git, the target repository and credentials, this skill, and an authenticated forge CLI (`tea`, `gh`, or `glab`). Run the `forge-cli` preflight there. If a prerequisite, machine, or run identity is missing or ambiguous, stop with actionable guidance; do not guess or dispatch.
 - This skill discoverable in the worker node's Pi session. If the worker node is remote, confirm it before dispatching.
 - The target repository, Git, and credentials on the worker node.
 - If any prerequisite is missing on the selected node, stop with actionable setup guidance. Do not dispatch to an unprepared shell.
-## Roles
+## Workflow
-Keep roles distinct. Never let one role do another's work.
+1. Validate the spec issue and worker, then follow `references/dispatcher.md` to find or start its planner.
-
+2. If a planner is already active for the spec, report that and exit. Do not attach, prompt, resume, or monitor it.
- **Orchestrator system** — the machine where this skill is invoked. Invokes and observes the workflow.
+3. If starting a planner, confirm it reaches `working`, then report the run identity and exit. The planner owns the workflow from there; retain run metadata and logs unless the user explicitly asks to delete them.
 - **Worker node** — the user-selected machine that runs the planner and worker agents and owns repository work. Local or remote, chosen at invocation. It is authoritative for run state.
 - **Worker agent** — a subagent (or remote Herdr pane running Pi) that implements or verifies a scoped task.
 - **Planner** — the agent that runs this loop. Coordinates and verifies state; does not edit product code or merge. Workers do not merge unless assigned an explicit merge task.
 ## Phase 0 — Select and validate the worker node
 The worker node is authoritative for run state, so pick it before anything else.
 1. Select the worker node: the current machine for a local run, or a remote machine the user names. If the user did not select one and the environment is ambiguous, ask.
 2. If the node is remote, follow `references/dispatcher.md`: discover the Herdr session and pane, inspect the exact target and its repository/ref before dispatch, and confirm the node has this skill, Git, and a forge CLI. Never infer a pane ID, target a pane by display label alone, or touch unrelated panes.
 3. If the node, session, or repository is missing, ambiguous, or not ready, stop and say exactly what is missing. Do not guess.
 The worker node is ready when its checkout identifies the target repository, its forge CLI authenticates, and Herdr can reach the same named session.
 ## Phase 1 — Plan and publish
 Work from the current conversation or an `@file` the user passes. If a reference is passed, fetch its full body and comments first.
 1. **Spec.** Run the `to-spec` skill to synthesize the current conversation into a spec and publish it to the current repository's tracker. Apply the `ready-for-agent` label. This is the durable record of the goal and acceptance criteria.
 2. **Tickets.** Run the `to-tickets` skill to break the spec into tracer-bullet tickets, each declaring its blocking edges, published to the same tracker in dependency order. Apply `ready-for-agent`. Each ticket is a complete, verifiable slice with acceptance criteria.
 Do not modify the spec after publishing except to record decisions. The spec and tickets are the scope; the loop below never widens it.
 ## Phase 2 — Run one task at a time
 Process **one** in-scope, open, unblocked ticket at a time. See `references/run-loop.md` for the full loop. The loop, in order:
 1. **Select the frontier.** Only in-scope, open, unblocked tickets. Claim it before implementing; re-query tracker state as work advances.
 2. **Isolate.** Give the task one Git worktree and branch per `worktrees`. Never parallel-write a shared checkout.
 3. **Implement.** Dispatch a worker with the full ticket, acceptance criteria, scope boundaries, and any upstream handoffs. The worker works without access to another agent's conversation.
 4. **Verify.** For meaningful behavior changes, run an independent verifier that reports evidence; a worker's self-report is not enough.
 5. **Review.** Run all four axes — `dual-review` (correctness/security, maintainability) and `code-review` (spec, standards) — before merge.
 6. **Fix.** Send actionable findings to a scoped fix worker and recheck. Cap at **three** fix rounds; unresolved findings stop for human judgment.
 7. **Merge.** Only after all four axes pass, required local checks pass, CI is green when available, the target branch is still correct, and no human decision remains. Link the ticket in the PR.
 8. **Close.** Close the task ticket with a recorded outcome.
 Cross-cutting rules that apply through the loop (full detail in `references/run-loop.md`):
 - **Retries.** Retry transient infrastructure failures only, at most two after the first attempt (three total). Keep this budget separate from the three fix rounds. Never blindly retry semantic failures, failed checks, or rejected reviews — correct the cause first.
 - **Uncertain side effects.** Reconcile the tracker, Git, worker node, or Herdr state before repeating an operation. If the outcome stays uncertain, stop and escalate; do not blindly replay non-idempotent operations.
 - **Escalate** immediately for authentication/permission failures, unresolved state mismatches, exhausted retry or fix limits, unsafe ambiguity, or any decision requiring human judgment. Preserve state and evidence at every escalation.
 ### Finish
 Close the parent spec ticket only when every in-scope task is complete, merged, verified, and run state is safely persisted. Leave it open when any work is blocked, failed, or unresolved.
 ## Recovery
 On restart, follow `references/state.md`: inspect the persisted `.orchestrate/<slug>` state and native Herdr status before creating or restarting agents. A new orchestrator system syncs state from the worker node before resuming; a local copy is not authoritative. Never duplicate work solely because a planner session restarted.
 ## Cleanup
 At completion, follow `references/state.md`: remove only clean task worktrees and close only run-owned Herdr panes. Preserve dirty or unresolved worktrees and the retained state. Retained state is deleted only by explicit user action.
 ## Reporting
 Report merged work, PR links, verification evidence, human handoffs, blockers, and remaining work. Report `done` only when every in-scope task is merged, verified, and state is persisted.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Start a spec with Herdr"
  short_description: "Start its planner and exit after startup confirmation"
 policy:
  allow_implicit_invocation: false
@@ -1,45 +1,27 @@
-# Dispatcher: select and validate the worker node
+# Dispatcher: find or start the planner
-The dispatcher is one-shot. It selects the worker node, discovers and validates Herdr state, and kicks off the planner. It does not run the loop afterward.
+Invocation is `/skill:orchestrate-herdr <spec-ticket> [worker]` (for example, `/skill:orchestrate-herdr 34 obelix`). The spec issue is required. A named worker is the preferred node for a new planner; if omitted or blank, use the current local worker. Never silently select a different machine.
-## Local vs remote
+## Find an existing run first
- **Local worker node** — the orchestrator system is the worker node. Use the current repository checkout. Skip the Herdr discovery below and run the planner in this session.
+1. Confirm the issue exists, is the parent/spec ticket, and is open. If closed, report completion and do not launch anything.
- **Remote worker node** — the user names another machine. Discover its Herdr session, workspace, and pane, confirm the repository/ref, then start the planner there.
+2. Resolve the named worker with `herdr machine list`; it is the target for a new run. To find an existing run, inspect enabled saved machines using their exact labels/IDs and `herdr --machine <machine> agent list`.
 3. Read the issue's `in-progress` label and locate its `.orchestrate/<slug>/run.json` on candidate worker checkouts. Match exact recorded Herdr workspace/pane/agent IDs. Agent listings show runtime identity and status, not the spec issue; use a working directory only to locate a candidate checkout, never as proof of ownership. If the recorded pane no longer exists, match the live `herdr agent list` entry and rewrite `run.json` to it, logging the reconciliation; a stale ID is a reconciliation event, not a mismatch. `herdr machine list` reporting no saved machines means the local session is the worker.
 4. If a matching planner is active, monitor it; do not start another. If that planner is this session, the identities have collapsed: continue the run loop here instead of monitoring. If the matching run exists but the label is missing, verify the run identity, add `in-progress`, comment on the reconciliation, and monitor.
 5. If `in-progress` is set but no matching agent can be found, do not start a planner. Refresh Herdr and run state to account for propagation delay; if still unmatched, comment on the parent issue with the mismatch and evidence, then stop for human direction. Do not clear the label automatically.
 6. If there is no matching agent and no `in-progress` label, reconcile any existing run metadata, issue comments, and Git state. If there is no active or ambiguous work, proceed to start a planner. If anything is uncertain, stop rather than risk duplicate work.
-If the user did not select a node and the environment does not make it obvious, ask. Do not default to a guess.
+For an untracked agent, do not attach to it or assume it belongs to this spec. Flag it for human review if it appears relevant; otherwise leave it untouched.
-## Preconditions
+## Start a new planner
- Check Herdr access on the node: `HERDR_ENV=1`, `HERDR_WORKSPACE_ID`, and that the `herdr` CLI can reach the same named session.
+1. On the selected worker, acquire a per-spec launch claim using an atomic exclusive create under `.orchestrate/`. If another invocation holds the claim, reconcile its owner and run state; never steal an uncertain claim.
- Resolve the explicit session from `HERDR_SESSION`; if unset, inspect `herdr session list` and ask if more than one plausible session exists. Pass `--session <name>` to every Herdr command; the environment variable alone can fall back to another server.
+2. Create a new sibling pane in the confirmed repository checkout and start a fresh Pi planner agent there. Never use an existing agent pane as the planner. Give the planner the issue number, worker identity, repository path, and references to `run-loop.md` and `state.md`.
- Confirm the node has this skill discoverable, plus Git and a working forge CLI (run the `forge-cli` preflight). If not, explain the setup needed; do not dispatch to an unprepared shell.
+3. The planner's first action is to set/verify the spec's `in-progress` label, before reading tickets or dispatching agents. It then records its Herdr IDs in `run.json` and begins the run loop.
 4. Confirm the planner reaches `working` and the label is set. Release the launch claim only after confirmed startup. If startup failure is confirmed, release the claim and report the failure. If the outcome is uncertain, retain the claim and stop; do not retry blindly.
-## Discover, do not guess
+## Start confirmation and failures
-Never infer a pane ID, an agent status, or a repository path. Discover and inspect them first. Do not close, rename, move, or reconfigure unrelated panes.
+After launching, confirm the planner reaches `working` and the `in-progress` label is set. Then report its run identity and exit; do not wait for later state changes or monitor its agents. If the machine is unreachable, check it with `herdr machine status`; when authentication is needed, run `herdr machine reconnect <label-or-id>` and verify connectivity. Retry transient connection failures at most twice after the first attempt. If the run cannot be safely identified, comment with the blocker and stop; do not dispatch to a different worker.
-```bash
+Herdr machine commands require an enabled saved machine and reachable, API-compatible Herdr server. A failed connection does not prove a mutation failed; reconcile remote state before retrying.
 herdr --session "$SESSION" session list
 herdr --session "$SESSION" pane list --workspace "$HERDR_WORKSPACE_ID"
 herdr --session "$SESSION" pane read <pane-id> --source recent-unwrapped --lines 200
 ```
 Before dispatching, confirm the target pane is the intended remote Pi pane and that its repository/ref is correct. Inspect the exact target and repository/ref before dispatch — work starts in the intended environment, never a guessed one.
 ## Kick off the planner
 Confirm the node has `orchestrate-herdr` available. If not, stop and explain that this skill must be installed or discoverable in the remote Pi session.
 Send the root kickoff as a separate text action followed by Enter; a TUI paste burst can swallow Enter. Use the exact pane ID returned by Herdr, never a guessed ID.
 ```bash
 herdr --session "$SESSION" pane send-text <pane-id> "/skill:orchestrate-herdr You are the root planner for: <goal>"
 # After the text is present in the pane:
 herdr --session "$SESSION" pane send-keys <pane-id> enter
 herdr --session "$SESSION" agent wait <pane-id> --until working --timeout 120000
 ```
 If the text was not submitted, inspect the pane and dismiss any slash-command popup with `escape`; do not blindly resend and create duplicate runs. Never claim kickoff succeeded on changed pane text alone: confirm native status became `working`.
 Wait for Herdr's native `working` status, then report the root pane/session and stop. Do not wait for the whole orchestration tree.
@@ -1,73 +1,53 @@
-# Run loop: one ticket at a time
+# Run loop: implement a spec ticket
-The loop drives one tracker ticket through implementation, verification, review, and merge, then moves to the next. The tracker is the source of truth; read the spec, the current ticket, and its comments before acting.
+The spec and linked tickets define scope; the tracker is the source of truth. The planner's first action is to set/verify the parent issue's `in-progress` label. Then read the spec, every associated ticket, blockers, and relevant comments. If the spec has no linked implementation tickets forming an actionable frontier, invoke `/to-tickets` and follow its approval and publishing process before implementation. If tickets are blocked, don't invent extra work.
-## Scope control
+The issue tracker should have been provided. If not, tell the user to run `/setup-skills`.
-The spec and tickets are the scope. Never widen it. For a supplied ticket, inspect only that ticket; do not process its siblings, parent, or descendants. Re-query tracker state as work advances; a ticket's status or blockers may have changed since it was selected.
+The goal is the entire spec implemented on one **integration branch**, with each ticket resolved according to tracker semantics. Treat tickets as a dependency graph; re-query the tracker as the ready frontier changes. If no ticket is actionable, report the blocker rather than guessing.
-## 1. Select the frontier
+## Communication
-Select only in-scope, open, unblocked tickets. Use native blocker/dependency relationships; otherwise require explicit blocker markers or linked URLs. Never infer order from titles. Claim the selected ticket before implementing.
+All agent communication and handoffs go through tracker or PR comments; `.orchestrate/<slug>/events.jsonl` is only the operational event log. Keep comments concise and link to context rather than copying ticket bodies or pane output.
-## 2. Isolate
+- Implementers post their completion handoff or blocker on the task issue, including branch/commit, changed files, acceptance evidence, checks, and concerns.
 - Reviewers put review discussion on the PR. Record the review outcome on the task issue.
 - The planner posts parent-spec comments at meaningful milestones: implementation ready, review outcome, merge, actionable blocker, and completion. Don't repeat comments already posted by a worker.
-Give the task one Git worktree and branch. Use the current checkout when the worker node is local; when remote, use the canonical `.bare` worktree layout and the agreed owner/repository worktree location. Create a branch such as `issue-<N>-<slug>` on a clean base; never reuse a dirty worktree. Never parallel-write a shared checkout.
+## 1. Read and establish the integration branch
-## 3. Implement
+- Confirm the supplied issue is the parent/spec ticket and identify linked implementation tickets.
 - Understand the task graph and current frontier. Re-query tracker state as work advances.
 - When tickets require codebase or external-documentation exploration, use a subagent and put concise findings in the relevant tracker comment for later subagents to reference.
 - Create one integration branch from the intended target branch. If a PR is required, open a draft after the first implementation merge and link it to close the spec and tickets.
 - If a ticket or its dependencies are ambiguous, stop and ask rather than infer.
-Dispatch one worker per task with a self-contained prompt: its role and one scoped outcome, the overall goal for context, allowed/forbidden paths and acceptance checks, its worktree path and starting branch, any upstream handoffs, and instructions to run focused checks, commit on the task branch, and not merge/rebase/open a PR unless the task explicitly requires it. The worker receives the full ticket, acceptance criteria, scope boundaries, and required upstream handoffs — no access to another agent's conversation.
+## 2. Implement the frontier
-## 4. Verify
+Use the `subagents` skill and native subagent workflow for every child role. Do not use Herdr agent commands or launch separate CLI processes for implementers, reviewers, fixers, or mergers.
-For meaningful behavior changes, run an independent verifier that runs the checks and reports evidence. The verifier must not modify the target source; its evidence overrides a worker's self-report. Name the target, branch, acceptance criteria, and an exact recipe — concrete commands or repro steps, not "test it."
+For each open, unblocked ticket, start a **worker subagent** from the planner using the native subagent workflow, with its own worktree and branch. Independent frontier tickets may run concurrently; never parallel-write a shared checkout. Do not launch implementers, reviewers, fixers, or mergers as separate CLI or Herdr agents; the planner is the only full CLI agent. Start a fresh worker subagent for each merge.
-## 5. Review — four axes
+Start each implementer with its role, task-issue URL, worktree path, and starting branch; the issue itself holds scope and acceptance criteria. Put any later clarification or handoff in tracker/PR comments, not agent-to-agent chat. Require the implementer to:
-Run all four axes before merge. `code-review` covers **spec** (does the code match the originating issue?) and **standards** (does it follow the repo's documented standards?). `dual-review` covers **correctness/security** and **maintainability**. All four must pass before merge.
+- confirm its worktree starts from the current integration branch (reset/rebase onto it if needed);
 - use the `tdd` skill and run focused checks;
 - commit its ticket work on its task branch;
 - merge the latest integration branch into its task branch before reporting done;
 - post its handoff on the task issue; do not merge to the integration branch or open a PR.
-Run the review against the base branch and the task's diff. Post findings through the tracker/PR comment or review function and link them from the ticket.
+When an implementer finishes, have a **new independent reviewer subagent** run the `code-review`, `security-audit`, and `code-quality-review` skills against that task branch, using the current integration branch as the base. Put review discussion on the PR and summarize its outcome on the task issue. Resolve actionable findings in a fresh scoped worker subagent and rerun review until clear. Only then use a fresh worker subagent to merge the task branch into the integration branch. Before dispatching the merger, confirm the task worktree is clean (`git status --porcelain` empty) and the task branch is fully pushed; recover unpushed or uncommitted work rather than merging around it. Verify the merge and update tracker state before dispatching newly unblocked tickets. Reconcile uncertain Git or tracker outcomes before retrying.
-## 6. Fix rounds
+When a check spans tickets — for example one coverage threshold covering several modules — an individual task branch can be red because it owns only part of the check, not because of a defect. Review still runs against the task branch, but assert the shared check after merge, on the integration branch; merge-then-fix is the allowed order in that case. Before deviating from green-before-merge, decide whether the check or the branch is mis-scoped, and record that decision.
-Send actionable findings to a scoped fix worker and recheck. Cap at **three** fix rounds; unresolved findings stop for human judgment rather than guessing. Keep this budget separate from the retry budget below.
+## 3. Final review and completion
-## 7. Merge
+After all tickets are implemented and merged, have a **reviewer subagent** run `code-review` against the entire integration branch as a final integration review. Have a fresh worker subagent fix actionable findings in a scoped worktree; merge the fixes and rerun review until clear. Do not report completion until this review is clear and final checks pass; do not merge around unresolved findings or failed checks.
-Merge only after every gate passes:
+If a draft PR exists, mark it `needs-review` after final checks. Otherwise, resolve each ticket according to tracker close semantics and report the integration branch. Close the parent spec ticket only when all work is complete, verified, and merged. As part of closing it, remove the `in-progress` label. Clean only confirmed-clean implementer worktrees and issue branch that have been merged successfully in draft PR; retain unresolved work and the worker-side run log.
- all four review axes pass and findings are resolved;
+## Retry and escalation rules
 - required local checks pass;
 - CI is green when available (the current Gitea host has no CI; this gate is silent when CI is absent);
 - the target branch is still the expected default branch;
 - no human decision or blocker remains.
-Create exactly one PR per task and link the ticket's number and title in it. Do not use auto-merge, admin/bypass, or force. Merge after every gate passes; never merge around a failed check, unresolved finding, or missing decision.
+- Retry transient infrastructure failures at most twice after the first attempt. Never blindly retry semantic failures, failed checks, or rejected reviews.
-
+- If an operation's outcome is uncertain, reconcile tracker, Git, worker, and Herdr state before repeating it.
-## 8. Close
+- Stop and preserve state/evidence for auth or permission failures, unresolved state mismatches, exhausted retries, ambiguity, or decisions requiring human judgment.
 Close the task ticket with a recorded outcome once its PR is merged and completion is verified. Leave it open when any in-scope work is blocked, failed, or unresolved.
 ## Retries
 Retry transient infrastructure failures only, at most two retries after the first attempt (three total). Keep this budget separate from the three fix rounds. Never blindly retry semantic failures, failed checks, or rejected reviews — correct the cause first. Cap retries; do not respawn indefinitely.
 ## Uncertain side effects
 For an uncertain side effect, reconcile the tracker, Git, worker node, or Herdr state before repeating the operation. If the outcome stays uncertain, stop and escalate; do not blindly replay non-idempotent operations. Reconciliation prevents duplicate agents, worktrees, comments, PRs, merges, or state transitions.
 ## Escalation
 Escalate immediately, preserving state and evidence:
 - authentication or permission failures;
 - unresolved state mismatches;
 - exhausted retry or fix limits;
 - unsafe ambiguity;
 - any decision requiring human judgment.
 For a human decision or judgment call, assign the ticket to the configured human reviewer, mark it for human review, and comment the exact request. If no human identity is configured, ask before assigning; never invent one.
 ## Finish
 When every in-scope task is complete, merged, and verified, close the parent spec ticket and record that run state is safely persisted. Report merged work, PR links, verification evidence, human handoffs, blockers, and remaining work. Report `done` only when no in-scope work remains.
@@ -1,48 +1,33 @@
-# State, recovery, and cleanup
+# Worker-side run state and recovery
-Run state lives under a run-scoped `.orchestrate/<slug>` directory in the worker node's repository checkout. The worker node is the source of truth. Keep this state out of product commits and PRs.
+The worker node is the source of truth. Keep state under `.orchestrate/<slug>/` in the target repository checkout, outside product commits and PRs. Use a stable issue-derived slug such as `spec-34`; do not mirror state on the orchestrator node.
-## State directory
+## Files
-Create `.orchestrate/<slug>/` on the worker node:
+- `run.json` — minimal recovery metadata: spec issue ID/URL, repository identity, worker label/ID, planner's Herdr agent/pane/workspace IDs, and each tracked child subagent's role, issue ID, subagent run ID, branch, and worktree.
 - `events.jsonl` — append-only structured operational events: timestamp, actor/task, action, outcome, and relevant Herdr/Git/tracker IDs. No pane transcripts, copied ticket bodies, plans, or handoff prose. Record a start and finish event for every phase (worktree created, implementer handoff, review dispatched, review completed, merge completed); a phase with only one of the pair is a detectable gap, whereas a silent absence is not.
- `plan.json` — the original goal, repo path/URL, base ref, acceptance criteria, and task definitions (name, type, scoped goal, dependencies, path boundaries, acceptance, verification recipe, retry cap).
+The issue tracker is canonical for ticket status, acceptance criteria, decisions, and communication. Keep agent handoffs and blockers in comments on the relevant task issue; use PR comments for review discussion; use parent-spec comments for milestone rollups. Do not create local handoff files or duplicate tracker content in `run.json`.
 - `state.json` — each task's status, attempt count, worktree path, branch, Herdr session/workspace/pane IDs, and handoff path.
 - `handoffs/<task>.md` — each agent's final response, saved verbatim with task, branch, and execution metadata.
 - `recovery.log` — spawns, recovery, reconciliation, and operator decisions.
-Use kebab-case task names. Validate that dependencies and verifier targets exist and that the dependency graph has no cycles before starting work.
+## Claim and label
-## Persist immediately
+Before creating a planner, acquire a per-spec launch claim under `.orchestrate/` with an atomic exclusive create. The claim only serializes startup; it is not a second progress record. Record its owner and issue ID. Never steal an uncertain claim.
-Persist state immediately after every side effect and record enough Herdr, branch, worktree, and task identity to reconcile execution after interruption. On restart, inspect persisted state and native Herdr status before creating or restarting agents. Never duplicate work solely because a planner session restarted.
+The new planner's first action is to set/verify the parent's `in-progress` label, before reading tickets or dispatching work. After confirmed startup and recording the planner's Herdr IDs, release the launch claim. Release a claim after startup failure only when failure and absence of a running planner are confirmed. Keep it and escalate when the result is uncertain.
-A new orchestrator system reconnects to the worker node and syncs from it before resuming; a local copy is not authoritative. Do not create a separate Git branch solely to transfer this state.
+If the parent has `in-progress` but no matching agent is found, do not start a replacement or clear the label. Comment with the mismatch and wait for the user's explicit retry decision. If a matching agent exists but the label is missing, verify the run record, add the label, and comment on the repair.
-## Recovery
+## Persist and recover
-On restart, in order:
+Append a structured event after each consequential side effect and enough identity data to match the run to Herdr. The worker log records activity while the orchestrator is unavailable; agents continue posting comments to the tracker.
-1. Read `plan.json`, `state.json`, and `handoffs/`.
+On every invocation or restart:
 2. Discover native Herdr state and reconcile stored IDs with what Herdr actually reports.
 3. Reconcile tracker and Git state.
 4. Reattach to running agents; never duplicate a task just because the session restarted.
-If reconciliation cannot resolve a state mismatch, stop and escalate rather than guessing.
+1. Read the parent issue, labels, and relevant comments.
 2. Inspect the worker's `run.json` and event log.
 3. Query Herdr agent state and match exact recorded IDs; do not infer ownership from a matching working directory. If the recorded pane was recreated or removed between sessions, match the live entry, rewrite `run.json` to it, and log the reconciliation.
 4. Reconcile tracker and Git state before deciding to start a planner. If the worker is unreachable or identities/state disagree, report the blocker and stop rather than guessing.
-## Handoffs
+If a matching live planner exists, report that it is already running and exit; do not attach to, prompt, or resume it. The planner manages its own subagents. If there is no matching agent and no `in-progress` label, reconcile any stale run record; start a fresh planner only when no active or ambiguous work remains and a new atomic claim is acquired.
-Handoffs are the only information channel between workers and planners. Save each final response verbatim; add a short metadata comment above it with task, branch, worktree, and Herdr identifiers. Do not paraphrase the evidence.
+Retain `run.json` and `events.jsonl` after completion. The planner removes `in-progress` while closing the parent spec only after all tickets are complete, verified, and merged. Delete retained run state only at the user's explicit request.
 - **Worker** — status (`success`/`partial`/`blocked`), actual branch, what it did, acceptance with evidence, verification tier, commands run, concerns, suggested follow-ups. A worker commits to its task branch and does not merge/rebase/open a PR unless the task requires it. Do not accept `success` if stated acceptance is unmet or evidence is absent.
 - **Verifier** — verification tier, target, execution, findings per criterion (met/not met/n/a) with severity, and environment limits. `verifier-blocked` means the environment prevented a meaningful check; `verifier-failed` means the check ran and the target did not pass. Do not downgrade a failure to a blocked verdict.
 - **Planner** — an aggregated handoff to the parent: status, actual deliverable branch, one bullet per meaningful slice, strongest evidence actually produced, risks, and parent-scope follow-ups.
 ## Cleanup
 At completion, remove only what this run owns and leave everything else untouched.
 - **Remove** clean task worktrees (via `git worktree remove`, after accounting for every staged, unstaged, and untracked change) and close only Herdr panes created by this run.
 - **Preserve** dirty or unresolved worktrees — cleanup cannot destroy unfinished work or recovery evidence.
 - **Retain** the worker node's canonical checkout, `.orchestrate/<slug>` state, handoffs, and logs. Never delete retained state automatically. Cleanup of retained state requires an explicit user action.
 - Leave unrelated Herdr panes, tickets, repositories, branches, and PRs untouched.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Recipe Diagrams"
  short_description: "Turn recipes into process-flow diagrams"
 policy:
  allow_implicit_invocation: false
@@ -1,7 +1,6 @@
 ---
 name: security-audit
 description: Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.
 disable-model-invocation: true
 ---
 # Security Audit Skill
@@ -0,0 +1,5 @@
 interface:
  display_name: "Security Audit Skill"
  short_description: "Audit diffs for security and correctness risks"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Git Worktrees"
  short_description: "Manage worktrees under a canonical repository root"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Write Discoverable Code"
  short_description: "Write searchable identifiers, comments, and file names"
 policy:
  allow_implicit_invocation: false
@@ -1,12 +1,12 @@
-# In-Progress Skills
+# In Progress Skills
 Drafts not yet ready to ship.
 ## User-invoked
- [agent-handoff](agent-handoff/SKILL.md) — Hand the current conversation to a fresh background agent.
+- [agent-handoff](agent-handoff/SKILL.md) — Hand the current conversation off to a fresh background agent that picks up the work immediately.
- [knowledge-gardener](knowledge-gardener/SKILL.md) — Run vault-aware search, synthesis, note creation, and linking workflows.
+- [knowledge-gardener](knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault.
 ## Model-invoked
-No model-invoked skills.
+No skills.
@@ -1,16 +1,16 @@
-# Miscellaneous Skills
+# Misc Skills
 Kept around but rarely used.
 ## User-invoked
- [bro](bro/SKILL.md) — Restate the last message in plain human language.
+- [bro](bro/SKILL.md) — Restate the last message in plain human language, with no jargon.
- [show-me](show-me/SKILL.md) — Help explain topics visually with concise diagrams and artifacts.
+- [show-me](show-me/SKILL.md) — Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
- [tmux-launch-agent](tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window.
+- [tmux-launch-agent](tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window, detected from the current agent.
- [visual-verification](visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings.
+- [visual-verification](visual-verification/SKILL.md) — Verify running desktop UI changes with screenshots and recordings. Use when changing shell styling, layout, panels, menus, notifications, animations, transitions, or capture flows; inspect the artifacts before reporting completion.
 ## Model-invoked
- [migrate-to-shoehorn](migrate-to-shoehorn/SKILL.md) — Migrate test assertions from `as` to `@total-typescript/shoehorn`.
+- [migrate-to-shoehorn](migrate-to-shoehorn/SKILL.md) — Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
- [scaffold-exercises](scaffold-exercises/SKILL.md) — Create linted exercise directories with problems, solutions, and explainers.
+- [scaffold-exercises](scaffold-exercises/SKILL.md) — Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. Use when user wants to scaffold exercises, create exercise stubs, or set up a new course section.
- [setup-pre-commit](setup-pre-commit/SKILL.md) — Set up Husky, lint-staged, type checking, and tests.
+- [setup-pre-commit](setup-pre-commit/SKILL.md) — Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Bro"
  short_description: "Restate messages in plain language"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Show Me"
  short_description: "Explain topics with diagrams and concise artifacts"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Visual Verification"
  short_description: "Verify desktop UI changes with screenshots and recordings"
 policy:
  allow_implicit_invocation: false
@@ -4,5 +4,9 @@ Skills tied to the user's own setup and not promoted as general-purpose workflow
 ## User-invoked
- [arch-maintenance](arch-maintenance/SKILL.md) — Keep an Arch/CachyOS system updated and healthy with status, check, and update workflows.
+- [arch-maintenance](arch-maintenance/SKILL.md) — Keep an Arch or CachyOS system updated and healthy with status, check, and update workflows.
- [arch-troubleshooting](arch-troubleshooting/SKILL.md) — Diagnose and repair Arch/CachyOS system problems.
+- [arch-troubleshooting](arch-troubleshooting/SKILL.md) — Diagnose and repair Arch or CachyOS system problems.
 ## Model-invoked
 No skills.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Arch Maintenance"
  short_description: "Keep Arch and CachyOS systems updated and healthy"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Arch Troubleshooting"
  short_description: "Diagnose and repair Arch and CachyOS problems"
 policy:
  allow_implicit_invocation: false
@@ -1,14 +1,14 @@
-# PKM Skills
+# Pkm Skills
 Personal knowledge management.
 ## User-invoked
- [conversation-summary](conversation-summary/SKILL.md) — Save the current conversation as a report note in an Obsidian vault.
+- [conversation-summary](conversation-summary/SKILL.md) — Save the current conversation as a comprehensive report note in your Obsidian vault, following OKF v0.1 conventions.
- [crit](crit/SKILL.md) — Run the CRIT framework through context, role, interview, and task.
+- [crit](crit/SKILL.md) — Run the CRIT framework — give the AI Context, assign it a Role, let it Interview you one question at a time, then issue the Task.
- [research-vault](research-vault/SKILL.md) — Research a topic through a guided conversation and save a linked vault packet.
+- [research-vault](research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked OKF-conformant research packet in the Obsidian vault.
- [youtube-video-capture](youtube-video-capture/SKILL.md) — Capture a YouTube video's subtitles and summary in an Obsidian vault.
+- [youtube-video-capture](youtube-video-capture/SKILL.md) — Fetch subtitles from a YouTube video, summarize the content, and save both the summary and raw subtitles to the Video bundle in the Obsidian vault. Use when the user wants to capture a YouTube video, mentions "summarize this video", "capture this talk", or pastes a YouTube URL wanting it saved to vault.
 ## Model-invoked
- [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian vault with classification, links, and atomic notes.
+- [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian vault — classify notes, normalize frontmatter, add links, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick.
@@ -4,13 +4,12 @@ General workflow tools, not code-specific.
 ## User-invoked
- [grill-me](grill-me/SKILL.md) — Interview the user to sharpen a plan or design.
+- [grill-me](grill-me/SKILL.md) — A relentless interview to sharpen a plan or design.
- [handoff](handoff/SKILL.md) — Compact the current conversation into a handoff document.
+- [handoff](handoff/SKILL.md) — Compact the current conversation into a handoff document for another agent to pick up.
- [teach](teach/SKILL.md) — Teach the user a new skill or concept within the workspace.
+- [to-questionnaire](to-questionnaire/SKILL.md) — Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
- [to-questionnaire](to-questionnaire/SKILL.md) — Turn an unresolved decision into a questionnaire.
+- [wait-what](wait-what/SKILL.md) — Stop. That last message did not land: re-pitch it.
 - [wait-what](wait-what/SKILL.md) — Re-pitch the last message in clearer terms.
 ## Model-invoked
- [grilling](grilling/SKILL.md) — Grill the user relentlessly about a plan or design.
+- [grilling](grilling/SKILL.md) — Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
- [writing-for-agents](writing-for-agents/SKILL.md) — Write effective documents for agents.
+- [writing-for-agents](writing-for-agents/SKILL.md) — Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
@@ -0,0 +1,16 @@
 # Pstack Skills
 Personal agent workflow skills.
 ## User-invoked
 - [bugfix-regression-test](bugfix-regression-test/SKILL.md) — Fix bugs test-first with a focused regression test when practical.
 - [interrogate](interrogate/SKILL.md) — Use for "interrogate", "adversarial review", "multi-model review", "challenge this", "stress test this code", "find blind spots", or "tear this apart". Uses available subagents for independent, evidence-backed review.
 ## Model-invoked
 - [fix-merge-conflicts](fix-merge-conflicts/SKILL.md) — Resolve merge conflicts non-interactively, validate build and tests, and finalize conflict resolution
 - [how](how/SKILL.md) — Use for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live", "which package owns this", "is this the right layer"). Explains subsystem architecture, runtime flow, onboarding mental models. Can critique architecture. Use why for motivation.
 - [reflect](reflect/SKILL.md) — Review a conversation for durable learnings and propose targeted edits to existing agent skills. Use when the user says "reflect", or when a complex workflow, correction, or recoverable dead end produced a reusable lesson.
 - [unslop](unslop/SKILL.md) — Cut AI writing patterns while preserving meaning and voice. Use when drafting, editing, or polishing prose, messages, or documentation.
 - [why](why/SKILL.md) — Investigate why code exists or behaves this way using cited historical evidence. Use for design rationale, tradeoffs, regressions, postmortems, and data-backed thresholds. Distinguishes motivation from how the code currently works.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Bug-Fix Regression Test"
  short_description: "Fix bugs test-first with focused regression tests"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Fix Merge Conflicts"
  short_description: "Resolve merges and validate the resulting code"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "How"
  short_description: "Explain code behavior, flow, and architectural ownership"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Interrogate"
  short_description: "Challenge code and plans with independent reviews"
 policy:
  allow_implicit_invocation: false
@@ -42,6 +42,7 @@ Show the complete Accepted / Rejected / Backlog output and wait for explicit use
 For each approved item, follow its Routing field:
 - Package-installed skill (for example under `node_modules` or a marketplace directory): do not edit it — the change is lost on update. Route the lesson to project-level config or a project skill, or report it as a backlog item instead.
 - Trivial edit to an existing skill: edit it directly.
 - Substantive edit to an existing skill: use the harness's established skill-authoring workflow, if available; otherwise draft and validate the smallest clear change.
 - Description needs tuning: improve the target skill's routing description using its supported metadata format.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Reflect"
  short_description: "Turn durable learnings into targeted skill improvements"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Unslop"
  short_description: "Edit prose to remove AI patterns while preserving meaning"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Why"
  short_description: "Investigate code rationale using historical evidence"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,11 @@
 # Setup Skills
 One-time repository configuration workflows.
 ## User-invoked
 - [setup-skills](SKILL.md) — Configure this repo for the engineering skills, issue tracker, triage label vocabulary, and domain doc layout.
 ## Model-invoked
 No model-invoked skills.
@@ -1,11 +1,11 @@
-# Skill Authoring
+# Skill Authoring Skills
 Create and maintain effective agent skills.
 ## User-invoked
-No user-invoked skills.
+No skills.
 ## Model-invoked
- [effective-agent-skills](effective-agent-skills/SKILL.md) — Write, review, and debug effective agent skills.
+- [effective-agent-skills](effective-agent-skills/SKILL.md) — How to write effective agent skills — what to do, what not to do, anatomy, progressive disclosure, design patterns, anti-patterns, testing, security. Read this whenever a skill (Claude Skill, Agent Skill, SKILL.md) is being created, edited, reviewed, or debugged. Use when the user says "create a skill", "new skill", "update this skill", "improve a skill", "why isn't my skill triggering", or anything else involving authoring or editing SKILL.md files.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Agent Skills: A Complete Guide"
  short_description: "Write and improve effective agent skills"
 policy:
  allow_implicit_invocation: false
@@ -1,20 +1,20 @@
-# Thinking and Docs Skills
+# Thinking And Docs Skills
 Clarify decisions, capture ideas, and improve project documentation.
 ## User-invoked
- [before-building](before-building/SKILL.md) — Surface consequential choices when the user proposes a build.
+- [before-building](before-building/SKILL.md) — Fire the moment the user proposes a build. Instantly surface the 1-3 consequential choices hidden in his idea. Can also be invoked with /before-building.
- [decisions](decisions/SKILL.md) — List choices made during the current work that remain uncertain.
+- [decisions](decisions/SKILL.md) — Ask the agent to list all choices it made during the current work that it is not confident of. Manual-only; invoke with /decisions.
- [level-up](level-up/SKILL.md) — Assess technical and product knowledge and grow a learning plan.
+- [level-up](level-up/SKILL.md) — Gauge the user''s technical + product knowledge through 7 adaptive questions, log verbatim answers with honest ratings, and grow a learning plan from the gaps found. Use when the user says "level up", "level-up session", "quiz me", "gauge my knowledge", or wants a new assessment round. Differentiator: this finds and maps gaps; the `teach` skill delivers lessons on them.
- [read-all-adrs](read-all-adrs/SKILL.md) — Read every ADR in the project's `docs/adr/` folder.
+- [read-all-adrs](read-all-adrs/SKILL.md) — Read every ADR markdown file in the project's docs/adr/ folder so you have full context on past decisions. Use only when the user explicitly calls it.
- [remind](remind/SKILL.md) — Rewrite the last response more simply and briefly.
+- [remind](remind/SKILL.md) — Rewrite the last response simpler and shorter in plain English, prefixed with a 3-5 sentence TLDR of the conversation so far. Manual-only, invoked as /remind.
- [short](short/SKILL.md) — Compress the current answer while keeping its substance.
+- [short](short/SKILL.md) — Manually-invoked skill that forces the agent to compress its current answer — strip filler, simplify wording, and cut length while keeping the substance. Use when the user says "short", "shorter", "simpler", "too long", "tl;dr", or wants a more concise version of the previous response.
- [teach](teach/SKILL.md) — Teach the user a new skill or concept within the workspace.
+- [teach](teach/SKILL.md) — Teach the user a new skill or concept, within this workspace.
 ## Model-invoked
- [brain-to-docs](brain-to-docs/SKILL.md) — Extract project vision, decisions, and preferences into documentation.
+- [brain-to-docs](brain-to-docs/SKILL.md) — Use when the user wants to extract project vision, decisions, and preferences from his head into clear documentation (README + ADRs) through a back-and-forth Q&A loop. Triggers on "brain-to-docs", "build out the docs", "extract the vision", "let's document this project".
- [next-decision](next-decision/SKILL.md) — Drill into the next unresolved decision with choices and a recommendation.
+- [next-decision](next-decision/SKILL.md) — Drill open decisions one at a time — present the most important decision not yet clarified, give the top four choices, state a preference, ask the user. Use when the user says "next decision", "one decision at a time", or a plan has several unresolved choices. Differentiator: forward-looking; the decisions skill is retrospective (choices already made). Can be invoked with /next-decision.
- [prompt-me](prompt-me/SKILL.md) — Ask pointed questions to extract project priorities and concerns.
+- [prompt-me](prompt-me/SKILL.md) — Prompt the user with pointed questions to extract what is in his head about a project — remaining work, what is being avoided, what really matters, what does not. Use when the user says "prompt me", "ask me questions", or wants the agent to figure out priorities by questioning him.
- [save-idea](save-idea/SKILL.md) — Capture content ideas in the user's content backlog.
+- [save-idea](save-idea/SKILL.md) — Quickly capture a content idea into ~/code/content from any repo or chat. Video ideas go to VIDEO-IDEAS.md; smaller podcast topics, guest ideas, questions, and AI observations go to TOPICS.md. Every entry gets a source line referencing the chat and repo it came from. Use when the user says "/save-idea", "save this idea", "video idea", "add a topic", "write this down for a video/podcast". Differentiator: appends to the user''s content backlog — not a reminder, task, or general note tool.
@@ -0,0 +1,5 @@
 interface:
  display_name: "Brain to Docs"
  short_description: "Extract project vision and decisions into README and ADRs"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Next Decision"
  short_description: "Drill the next open decision with choices and a recommendation"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Prompt Me"
  short_description: "Ask pointed questions to surface project priorities"
 policy:
  allow_implicit_invocation: false
@@ -0,0 +1,5 @@
 interface:
  display_name: "Save Idea"
  short_description: "Capture video and podcast ideas in the content backlog"
 policy:
  allow_implicit_invocation: false
Author	SHA1	Message	Date
gitadmin	d6c2cb083d	docs(forge-cli): note tea verb fallback and label id vs name in tea.md	2026-10-07 13:30:12 -04:00
gitadmin	4293880737	docs(reflect): never edit package-installed skills, route lessons to project config	2026-10-07 13:26:07 -04:00
gitadmin	17acb1eab1	docs(orchestrate-herdr): cover collapsed planner identity and review gaps When the invoking session is the planner, skip the launch-claim and monitor ceremony and run the loop in place. Reconcile stale pane IDs instead of treating them as mismatches. Require clean/pushed task worktrees before merge, review with one independent subagent, and assert cross-ticket checks on the integration branch. Pair start/finish events so silent phase gaps are detectable.	2026-10-07 13:16:38 -04:00
gitadmin	8f451d3b88	refactor(orchestrate-herdr): fire-and-forget planner with native subagents The orchestrator no longer monitors a running planner; it confirms startup and exits. The planner is the only full CLI agent and delegates implementer, reviewer, fixer, and merger roles to native Pi subagents instead of Herdr- or CLI-launched agents. Update dispatcher, run-loop, state, and agent interface copy to match.	2026-10-07 11:10:52 -04:00
gitadmin	09232e0c9a	docs(orchestrate-herdr): rename implementer/reviewer agents to subagents	2026-10-07 09:52:26 -04:00
gitadmin	8238d5a283	refactor(orchestrate-herdr): orchestrator finds or starts planner Rewrote the skill so the invoking session only discovers an existing run or launches a fresh planner, then monitors via Herdr read-only commands. Workers keep state in .orchestrate/<slug>/ with run.json and events.jsonl; the tracker holds all handoffs and decisions. Re-invoking the same command recovers monitoring after an orchestrator outage, and an in-progress label plus atomic launch claims prevent duplicate planners.	2026-10-06 23:32:21 -04:00
gitadmin	fcdd3f7a8c	refactor(skills): wire code-quality-review and security-audit into reviews Rename thermo-nuclear-code-quality-review to code-quality-review and drop the dramatic wording; allow security-audit model invocation. Both now run as extra axes in the implementation-orchestrator and orchestrate-herdr review steps.	2026-10-06 18:47:42 -04:00
gitadmin	abf9b8e7ec	refactor(orchestrate-herdr): scope skill to spec-ticket implementation on a named worker Rewrite SKILL.md, dispatcher and run-loop references: the skill now takes <spec-ticket> [worker], always starts fresh agents, and follows the implement-spec flow (integration branch, frontier tickets, per-task review and merge) instead of the old plan-and-publish-to-merged-PR pipeline. Update the engineering README description to match.	2026-10-06 15:59:06 -04:00
gitadmin	fa9813daa4	feat(skills): add openai agent interface configs for all skills Declare display_name, short_description, and disable implicit invocation for each skill via agents/openai.yaml. Also fix stale /setup-matt-pocock-skills reference in implement-spec to /setup-skills.	2026-10-06 14:16:57 -04:00
gitadmin	71525bc349	feat(feedback-bundle): commit-linked Gitea tickets with file attachments New model-invoked skill + feedback_bundle.py: creates a Gitea issue whose body links the current HEAD commit and uploads logs/screenshots as issue assets. Handles label-name-to-ID resolution, tea-config token lookup, and the disabled-attachments (403/404) case. Index updated in root and engineering READMEs.	2026-10-06 14:06:01 -04:00
gitadmin	01c488157d	docs: rewrite repo indexes and context pack for skills/ layout Replace the stale common/ structure docs with the current skills/ bucket layout. Root and bucket READMEs now index every SKILL.md by invocation type, AGENTS.md lists the ten actual buckets, and the project context pack is condensed to purpose, structure, conventions, and validation.	2026-10-06 14:00:45 -04:00