chore: reorganize READMEs with sorted entries and bucket descriptions

Clean up all skill bucket READMEs — sort entries alphabetically within user/model sections, add category descriptions to each bucket, simplify the deprecated forge-skills doc to a bare notice, update triage label count (5→7) in AGENTS.md, and add a Project Context Pack section.
docs: refresh project context and fix agent docs typos
2026-07-19 10:13:37 -04:00 · 2026-07-19 10:10:51 -04:00 · 2026-07-19 09:52:18 -04:00 · 2026-07-19 09:51:00 -04:00 · 2026-07-15 17:19:57 -04:00 · 2026-07-15 17:18:36 -04:00
18 changed files with 277 additions and 197 deletions
@@ -1,26 +1,31 @@
 # Project Context Pack
-Generated: 2026-06-25
+Generated: 2026-07-16
-Root: /home/sjb/Documents/ai-workflows/skills
+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 forge interaction.
+
 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.
 ## Project type
 - **Agent skill repository** — markdown-defined agent instructions
- Languages: Markdown (100%)
+- 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
 ```
 .
 ├── AGENTS.md                    # Top-level agent instructions for this repo
 ├── README.md                    # Project overview, lists user-invoked and model-invoked skills
 ├── .gitignore                   # Excludes docs/adr/
 ├── .agent/
 │   └── project-context.md       # This file
 ├── docs/
 │   ├── invocation.md            # Model-invoked vs user-invoked definitions
 │   ├── agents/
@@ -31,36 +36,39 @@ A collection of agent skills (slash commands and behaviors) loaded into Steve Be
 │   └── adr/                     # ADR wiki clone (gitignored)
 └── common/
    ├── README.md                # Lists all common skills by invocation type
-    ├── engineering/             # Model-invoked: forge-interaction, project-context-pack; also sub-skills for codebase-design, domain-modeling, tdd, triage, etc.
+    ├── engineering/             # Model-invoked: lsp-code-analysis, pkm-curation; User-invoked: commit-staged, implement-issue, project-context-pack, setup-skills
-    ├── productivity/            # User-invoked: grill-me, handoff, writing-great-skills; Model-invoked: grilling
+    ├── productivity/            # (currently only README.md)
-    ├── pkm/                     # User-invoked: conversation-summary, crit, knowledge-gardener, research-vault
+    ├── pkm/                     # User-invoked: conversation-summary, crit, research-vault, youtube-video-capture; Model-invoked: pkm-curation
-    ├── personal/                # User-invoked: pkm-curation; Model-invoked: forge-preferences
+    ├── personal/                # (currently only README.md)
-    └── deprecated/              # Deprecated skills (audio-production-dispatcher, dsp-research-dispatcher, forge-*)
+    ├── misc/                    # User-invoked: tmux-launch-agent
    ├── in-progress/             # User-invoked: agent-handoff, knowledge-gardener
    └── deprecated/              # Deprecated forge-* and dsp-* skills
 ```
 ## Important files
 - `AGENTS.md` — Agent entry point that describes structure, categories, and references docs
- `README.md` — Index of all skills divided into user-invoked and model-invoked (recently updated to fix broken links, add missing skills, correct invocation classification)
+- `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 currently running skill
+- `common/engineering/project-context-pack/SKILL.md` — The skill that generated this file
- `common/engineering/codebase-design/SKILL.md` — Deep module design vocabulary (referenced by other skills)
+- `common/misc/tmux-launch-agent/SKILL.md` — Fork agent CLI into new tmux window (user-invoked)
- `common/engineering/domain-modeling/SKILL.md` — Domain modeling with ADRs and CONTEXT files
+- `common/misc/tmux-launch-agent/tmux-open` — Reusable script that opens a command in a new tmux window/session
 - `common/engineering/tdd/SKILL.md` — Test-driven development discipline
 - `common/productivity/grilling/SKILL.md` — Relentless plan/design interview (model-invoked, triggers)
 - `common/productivity/writing-great-skills/SKILL.md` — Reference for writing/editing skills
 ## Commands
 - Build: none
 - Test: none
 - Lint/typecheck: none
 - Run/dev: skills are invoked by AI agents — no server or dev command
 ## Entry points
 - `AGENTS.md` — loaded by the AI agent as project instructions (referred to in pi's agent config)
 - 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)
@@ -68,25 +76,25 @@ A collection of agent skills (slash commands and behaviors) loaded into Steve Be
 - 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 — updated (all links fixed, missing skills added, invocation corrected)
+- `README.md` — project overview and skill index — fresh
 - `docs/invocation.md` — invocation model definitions — fresh
 - `.gitignore` — excludes docs/adr/ — fresh
- `common/engineering/README.md` — engineering bucket index — updated (all engineering skills added, misclassified skills corrected)
+- `common/README.md` — common bucket index — fresh
- `common/README.md` — common bucket index — updated (links fixed, missing skills added)
+- `common/misc/README.md` — misc bucket index — fresh
- `common/productivity/README.md` — productivity bucket index — fresh (was already correct)
+- `.agent/project-context.md` — this file (refreshed from stale 2026-06-25 version)
 - `common/pkm/README.md` — pkm bucket index — updated (pkm-curation added)
 - `common/personal/README.md` — personal bucket index — updated (noted both skills moved elsewhere)
 - `common/deprecated/README.md` — deprecated bucket index — updated (all forge skills added)
 - All `SKILL.md` files — frontmatter checked for invocation status
 ## 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`
@@ -95,9 +103,13 @@ A collection of agent skills (slash commands and behaviors) loaded into Steve Be
 - 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
 - All README.md files were updated on 2026-06-25 to fix broken links, add missing skills, and correct invocation classification
 - If a skill is moved between buckets, update all README.md files that reference it (root, common, source bucket, destination bucket)
@@ -14,8 +14,8 @@ Skill are organized into categories based on their function. For example, `/comm
 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
@@ -36,7 +36,7 @@ Issues are tracked in Gitea on gitea.sagacity.ca. See `docs/agents/issue-tracker
 ### Triage labels
-Five-label vocabulary with default names (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See `docs/agents/triage-labels.md`.
+Seven-label vocabulary with default names (needs-triage, needs-info, needs-review, ready-for-agent, ready-for-human, in-progress, wontfix). See `docs/agents/triage-labels.md`.
 ### Domain docs
@@ -44,7 +44,11 @@ Single-context layout. See `docs/agents/domain.md`.
 ### ADR wiki
-Gitea wiki at git@gitea.sagacity.ca:steve/Skills.wiki.git, cloned into docs/adr/, SSH key auth. See `docs/agents/adr-wiki.md`.
+Gitea wiki at `git@gitea.sagacity.ca:steve/Skills.wiki.git`, cloned into `docs/adr/`, SSH key auth. See `docs/agents/adr-wiki.md`.
 ## Project Context Pack
 Agent memory file that describes the repo's context, codebase, and navigation rules. See `.agents/project-context.md`.
 ### Agent CLI
@@ -9,21 +9,21 @@ A collection of agent skills (slash commands and behaviors) loaded into my agent
 - [commit-staged](common/engineering/commit-staged/SKILL.md) — Commit staged files with a conventional commit message.
 - [conversation-summary](common/pkm/conversation-summary/SKILL.md) — Save the current conversation as a comprehensive report note in your Obsidian vault, following OKF v0.1 conventions.
 - [crit](common/pkm/crit/SKILL.md) — Brainstorm with AI using the CRIT framework to generate and evaluate ideas.
 - [dsp-research-engineering](common/deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output.
 - [forge-router](common/deprecated/forge-router/SKILL.md) — High-level guidance for choosing the right forge skill.
 - [implement](common/engineering/implement/SKILL.md) — Implement a piece of work based on a spec or set of tickets in isolation.
 - [implement-issue](common/engineering/implement-issue/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.
 - [knowledge-gardener](common/in-progress/knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault.
 - [project-context-pack](common/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.
 - [research-engineering](common/deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output.
 - [research-vault](common/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.
 - [setup-skills](common/engineering/setup-skills/SKILL.md) — Configure this repo for the engineering skills, set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
 - [tmux-launch-agent](common/misc/tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window, detected from the current agent.
 - [youtube-video-capture](common/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.
 ## Model-invoked
 - [lsp-code-analysis](common/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.
 - [pkm-curation](common/pkm/pkm-curation/SKILL.md) — Curate an Obsidian vault — classify notes, normalize frontmatter, add wikilinks, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick.
 - [youtube-video-capture](common/pkm/youtube-video-capture/SKILL.md) — Fetch subtitles from a YouTube video, summarize the content, and save the summary and raw subtitles to the Video bundle.
 - [forge-gitea](common/deprecated/forge-gitea/SKILL.md) — Use the Gitea CLI (`tea`) to interact with Gitea issues, pull requests, releases, CI, and repository state.
 - [forge-github](common/deprecated/forge-github/SKILL.md) — Use the GitHub CLI (`gh`) to interact with GitHub issues, pull requests, releases, CI, and repository state.
 - [forge-interaction](common/deprecated/forge-interaction/SKILL.md) — Use when the user wants forge work such as opening a PR, creating or listing issues, checking CI, looking at the repo, pushing a branch, publishing changes, or making a release on GitHub or Gitea. This skill now delegates to specialized skills for better predictability.
 - [forge-preferences](common/deprecated/forge-preferences/SKILL.md) — Use with forge-interaction to apply Steve's personal or project-specific GitHub/Gitea remote, CLI, issue, PR, and release preferences.
 - [pkm-curation](common/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.
@@ -9,20 +9,21 @@ Skills that work in all CLI agents.
 - [commit-staged](engineering/commit-staged/SKILL.md) — Commit staged files with a conventional commit message.
 - [conversation-summary](pkm/conversation-summary/SKILL.md) — Save the current conversation as a comprehensive report note in your Obsidian vault, following OKF v0.1 conventions.
 - [crit](pkm/crit/SKILL.md) — Brainstorm with AI using the CRIT framework to generate and evaluate ideas.
 - [dsp-research-engineering](deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output.
 - [forge-router](deprecated/forge-router/SKILL.md) — High-level guidance for choosing the right forge skill.
 - [implement](engineering/implement/SKILL.md) — Implement a piece of work based on a spec or set of tickets in isolation.
 - [implement-issue](engineering/implement-issue/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.
 - [knowledge-gardener](in-progress/knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault.
 - [project-context-pack](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.
 - [research-engineering](deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output.
 - [research-vault](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.
 - [setup-skills](engineering/setup-skills/SKILL.md) — Configure this repo for the engineering skills, set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
 - [tmux-launch-agent](misc/tmux-launch-agent/SKILL.md) — Fork a new agent CLI session into a new tmux window, detected from the current agent.
 - [youtube-video-capture](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.
 ## Model-invoked
 - [lsp-code-analysis](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.
 - [pkm-curation](pkm/pkm-curation/SKILL.md) — Curate an Obsidian vault — classify notes, normalize frontmatter, add wikilinks, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick.
 - [forge-gitea](deprecated/forge-gitea/SKILL.md) — Work with Gitea repositories, issues, pull requests, releases, and CI.
 - [forge-github](deprecated/forge-github/SKILL.md) — Work with GitHub repositories, issues, pull requests, releases, and CI.
 - [forge-interaction](deprecated/forge-interaction/SKILL.md) — Use when the user wants forge work such as opening a PR, creating or listing issues, checking CI, looking at the repo, pushing a branch, publishing changes, or making a release on GitHub or Gitea. This skill now delegates to specialized skills for better predictability.
 - [forge-preferences](deprecated/forge-preferences/SKILL.md) — Use with forge-interaction to apply Steve's personal or project-specific GitHub/Gitea remote, CLI, issue, PR, and release preferences.
 - [pkm-curation](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.
@@ -1,14 +1,15 @@
 # Deprecated Skills
 No longer used.
 ## User-invoked
 - [audio-product-dsp](audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs.
 - [research-engineering](dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output.
 - [forge-router](forge-router/SKILL.md) — High-level guidance for choosing the right forge skill.
-**Deprecated / user-invoked:**
+## Model-invoked
 - [audio-product-dsp](audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs.
 - [dsp-research-engineering](dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output.
 **Deprecated / model-invoked:**
 - [forge-gitea](forge-gitea/SKILL.md) — Work with Gitea repositories, issues, pull requests, releases, and CI.
 - [forge-github](forge-github/SKILL.md) — Work with GitHub repositories, issues, pull requests, releases, and CI.
 - [forge-interaction](forge-interaction/SKILL.md) — Use when the user wants forge work such as opening a PR, creating or listing issues, checking CI, looking at the repo, pushing a branch, publishing changes, or making a release on GitHub or Gitea. This skill now delegates to specialized skills for better predictability.
@@ -1,86 +1,7 @@
 # Forge Skills
-A collection of specialized forge interaction skills for GitHub and Gitea.
+These skills have been deprecated. See [../README.md](../README.md) for the current list.
 ## Overview
-This directory contains focused skills for interacting with different code hosting platforms:
+This directory previously hosted specialized forge interaction skills for GitHub and Gitea. The individual forge skills (`forge-gitea`, `forge-github`, `forge-interaction`, `forge-preferences`, `forge-router`) have been moved to the parent [deprecated](../) bucket.
 - **GitHub**: Use `/forge-github` for GitHub repositories, issues, pull requests, releases, or CI
 - **Gitea**: Use `/forge-gitea` for Gitea repositories, issues, pull requests, releases, or CI
 - **Router**: Use `/forge-interaction` to let the system choose the right skill automatically
 ## Skill Structure
 Each forge-specific skill is designed with:
 1. **Single Responsibility**: Handles only one forge type (GitHub or Gitea)
 2. **Predictable Behavior**: Clear decision tree and completion criteria
 3. **Complete Coverage**: All requested forge actions are supported
 4. **Error Handling**: Specific guidance for missing tools or authentication
 ## Choosing the Right Skill
 ### Use `/forge-github` when:
 - Working with GitHub repositories (`github.com` URLs)
 - Using the `gh` CLI tool
 - Interacting with GitHub-specific features (issues, PRs, releases, CI)
 ### Use `/forge-gitea` when:
 - Working with Gitea repositories (`gitea.com` or self-hosted Gitea)
 - Using the `tea` CLI tool  
 - Interacting with Gitea-specific features (issues, PRs, releases, CI)
 ### Use `/forge-interaction` when:
 - You're unsure which forge you're working with
 - You want the system to automatically choose the right skill
 - You prefer a unified interface that handles both platforms
 ## Skill Comparison
 | Feature | GitHub Skill | Gitea Skill |
 |---------|--------------|-------------|
 | CLI Tool | `gh` | `tea` |
 | Platform | GitHub | Gitea |
 | Focus | GitHub-specific | Gitea-specific |
 | Predictability | High | High |
 | Maintenance | Isolated | Isolated |
 ## Usage Examples
 ```
 # For GitHub work
 /forge-github create an issue in this repo
 /forge-github list pull requests
 /forge-github check CI status
 /forge-github publish a new release
 # For Gitea work  
 /forge-gitea create an issue in this repo
 /forge-gitea list pull requests
 /forge-gitea check CI status
 /forge-gitea publish a new release
 # Let the system decide
 /forge-interaction create a PR for this feature
 ```
 ## Why Separate Skills?
 1. **Predictability**: Each skill knows exactly one forge type
 2. **Maintainability**: Changes to GitHub or Gitea logic stay isolated
 3. **Clarity**: Users can see which forge a skill handles at a glance
 4. **Testing**: Each skill can be tested independently
 5. **Cognitive Load**: Users remember fewer skills and their specific purposes
 ## Related Skills
 - `/forge-router` - High-level guidance for choosing the right forge skill
 - `/forge-preferences` - Personal or project-specific forge configurations
 ## Next Steps
 1. Choose the appropriate skill based on your forge platform
 2. Ensure the required CLI tool (`gh` or `tea`) is installed
 3. Configure authentication for your forge platform
 4. Start with simple actions and build up to more complex workflows
@@ -4,8 +4,6 @@ description: Commit staged files with a conventional commit message.
 disable-model-invocation: true
 ---
 Commit staged files with a conventional commit message.
 ## Process
 1. **Check the staging area** — Run `git diff --cached --stat`. If empty, report "nothing staged" and stop.
@@ -18,17 +18,17 @@ disable-model-invocation: true
 #### a. Label the issue `in-progress`
-Change the issue triage label to `in-progress`.
+Change the issue triage label to `in-progress`, remove all other labels.
 Completion criterion: The issue label is confirmed as `in-progress`.
 #### b. Create the worktree
 ```bash
-git worktree add -b <branch-name> ../<repo-name>-issue-<N> <base>
+git worktree add -b <branch-name> ../issue-<N>-<repo-slug> <base>
 ```
-Completion criterion: The worktree exists at `../<repo-name>-issue-<N>` and the new branch is checked out.
+Completion criterion: The worktree exists at `../issue-<N>-<repo-slug>` and the new branch is checked out.
 ### 2. Compose the child prompt
@@ -36,16 +36,15 @@ Assemble a single prompt that the child agent will receive. Include:
 - **Issue body** — the full markdown body of the issue.
 - **Comments** — all comments, if any
- **Standing instruction**: "Implement using /tdd where possible, at the pre-agreed seam. Run typechecking regularly, run single test files regularly, and run the full test suite once at the end. Once done, use /code-review to review the work. Commit your work and push the new branch and create a PR with a link to the issue, one-sentence summary, and short key-changes list. Comment on the issue with the PR link: `PR opened: <url>`. Change the issue triage label to needs-review when done."
+- **Standing instruction**: "Implement using tdd skill where possible, at the pre-agreed seam. Run typechecking regularly, run single test files regularly, and run the full test suite once at the end. Once done, use code-review skill to review the work. Commit your work and push the new branch and create a PR with a link to the issue, one-sentence summary, and short key-changes list. Comment on the issue with the PR link: `PR opened: <url>`. Change the issue triage label to needs-review when done. Remove all other labels"
 - **Failure instruction**: "If any step fails, report where you stopped and what remains for manual recovery. Print the exact commands needed."
-(The prompt is passed as arguments to tmux-launch-agent in step 3, which handles writing it to a temp file if needed.)
+- **Failure instruction**: "If any step fails, report where you stopped and what remains for manual recovery. Print the exact commands needed."
 Completion criterion: The prompt is composed with all required sections (issue body, comments, standing instruction, failure instruction).
 ### 3. Launch the child via tmux-launch-agent
-Use the [`tmux-launch-agent`](../../../../.agents/skills/tmux-launch-agent/SKILL.md) skill to fork the child agent into a new tmux window. Tmux-launch-agent handles agent detection, config lookup, command building (prompt-file or stdin-pipe), mise/SHELL wrapping, and `tmux new-window` creation.
+Use the `tmux-launch-agent` skill to fork the child agent into a new tmux window. Tmux-launch-agent handles agent detection, config lookup, command building (prompt-file or stdin-pipe), mise/SHELL wrapping, and `tmux new-window` creation.
 Pass these parameters:
@@ -65,6 +64,7 @@ Completion criterion: `tmux new-window` exits 0 and a new tmux window appears wi
 ### 4. Print summary
 After launching, print:
 - Issue number and title
 - Worktree path
 - Branch name
@@ -72,5 +72,3 @@ After launching, print:
 - Agent used (detected by tmux-launch-agent)
 - Tmux window name (so the user can find it)
 - Cleanup command: `git worktree remove <worktree-path> && git worktree prune`
 The parent's turn ends here. The user can dispatch another issue immediately.
@@ -0,0 +1,47 @@
 ---
 name: implement-isolation
 description: "Implement a piece of work based on a spec or set of tickets in isolation."
 disable-model-invocation: true
 ---
 ## Invocation
 /skill:implement <N> [--base <branch>] [--force]
 - `<N>` — required, the ticket/issue number
 - `--base <branch>` — optional, target base branch (default: repo default branch)
 - `--force` — optional, allow overwriting an existing `worktree`
 Triage labels follow the vocabulary in `docs/agents/triage-labels.md`.
 ## Process
 ### 1. Claim the ticket
 Label the issue `in-progress`, remove all other labels.
 ### 2. Isolate the workspace
 ```bash
 git worktree add -b <branch-name> ../issue-<N>-<repo-slug> <base>
 ```
 Change into the new worktree directory.
 ### 3. Implement
 Drive every acceptance criterion through **red-green-refactor**: write the test first (red), make it pass (green), clean up (refactor). No code without a failing test first.
 ### 4. Verify
 Run the full test suite. Every test must pass.
 ### 5. Review
 Run /code-review against the base branch. Fix every finding before proceeding.
 ### 6. Ship
 Push the branch, open a PR. The PR description must include a link to the ticket and a key-changes list.
 Comment on the issue: `PR opened: <url>`. Label the issue `needs-review`, remove all other labels.
@@ -8,11 +8,11 @@ Architecture Decision Records live on the forge wiki and are cloned into `docs/a
 <wiki-url>
 ```
-Derived from the forge remote during `/setup-matt-pocock-skills`.
+Derived from the forge remote during `/setup-skills`.
 ## Bootstrap
-On first setup, `/setup-matt-pocock-skills` clones the wiki:
+On first setup, `/setup-skills` clones the wiki:
 ```bash
 git clone <wiki-url> docs/adr/
@@ -6,52 +6,26 @@ disable-model-invocation: true
 ## Agent CLI Seed Data
-The agent config (binary, `args` convention per agent) and field meanings are in [`agents-seed.md`](agents-seed.md). Step 2 reads it to find the calling agent's entry.
+Agent config (binary, `args`, `modelflag`) is in [`agents-seed.md`](agents-seed.md). Step 2 reads it by `name`.
 ## Dispatch
-## Process
+1. **Detect agent** — Run `./detect-agent` (sibling). On success, the agent name is known. On failure (exit 1), stop.
-1. **Detect the calling agent** — Run `./detect-agent` (sibling to this skill). If it exits 1 (agent unknown), report the failure and stop — the agent name is required.
+2. **Look up config** — Find the agent's entry in [`agents-seed.md`](agents-seed.md) by `name`. Extract `binary`, `args`, and `modelflag`.
-   Completion criterion: The agent name is known and non-empty.
+3. **Parse flags** — Scan user arguments for flags (before prompt text). For each flag, extract its value and remove both the flag and value from the argument list:
   - `--name <title>` / `-n <title>` — tmux window title
   - `-c <path>` — working directory (default: project directory)
   - `--model <name>` / `-m <name>` — model for child session
-2. **Look up the agent config** — Find the agent's entry in [`agents-seed.md`](agents-seed.md) by `name`. Extract its `binary` and `args` fields.
+   Remaining text is the prompt. If `--name` is absent, tmux auto-names the window.
-   Completion criterion: The agent's entry is found and its `binary` and `args` are known.
+4. **Build command** — Assemble the inner command:
-
+   - Start with `<binary>`.
-3. **Parse flags** — Scan the user's arguments for optional flags (which must come before the prompt text):
+   - If model specified: append `<modelflag> <model-name>`.
-   - `--name <title>` or `-n <title>` — the tmux window title. Extract the title and remove the flag and its value from the arguments list.
+   - If prompt exists and `args` contains `{prompt}`: write to `/tmp/`, substitute path for `{prompt}`.
-   - `-c <path>` — the working directory for the new window. Extract the path and remove the flag and its value from the arguments list.
+   - If prompt exists and `args` is empty: pipe via `echo`.
-
+   - If no prompt: launch bare.
   The remaining text after stripping both flags is the prompt for the child agent.
   If `--name`/`-n` is absent, tmux auto-names the window.
   If `-c` is absent, the new window inherits the current pane's working directory.
   Completion criterion: The arguments are split into an optional window name, an optional directory path, and the remaining prompt text.
 4. **Build the inner command** — Combine the agent config with the remaining user-supplied prompt arguments. The `args` template determines how the prompt is delivered:
   - **Prompt-file agents** (`args` contains `{prompt}`) — Write the prompt text to a temporary file under `/tmp/` and substitute the file path for `{prompt}` in the args template. For example, an agent with `args: "@{prompt}"` becomes `<binary> @/tmp/tmux-launch-XXXX.md`.
   - **Stdin-pipe agents** (`args` is empty) — Pipe the prompt text via `echo` into the binary.
   - **No prompt** — If the user passed no arguments (after removing flags), launch the binary bare (interactive start) with no prompt file or pipe.
   Completion criterion: The inner command is correctly built per the target agent's `args` convention (prompt-file, stdin-pipe, or bare).
 5. **Wrap with the environment runner** — Detect whether `mise` is available via `command -v mise`:
   - **mise available** — Wrap the inner command as `mise x --allow-env='*' -- <inner-command>`.
   - **mise absent** — Wrap the inner command as `$SHELL -c '<inner-command>'`.
   Completion criterion: A valid shell command string is ready.
 6. **Fork into a new tmux window** — Build and run:
   ```
   tmux new-window <name-flag> <dir-flag> "<shell-command>"
   ```
   - `<shell-command>` — the wrapped command from step 5.
   - `<name-flag>` — `-n "<title>"` if a window name was parsed in step 3, omitted otherwise.
   - `<dir-flag>` — `-c <path>` if a directory was parsed in step 3, omitted otherwise.
   Completion criterion: `tmux new-window` exits 0 and a new tmux window appears with the agent CLI session active.
 5. **Open window** — Call `./tmux-open <window-name> <start-dir> <inner-command>` where `<inner-command>` is the assembled command from step 4 as separate arguments. On success, a new tmux window appears with the agent session active.
@@ -7,28 +7,33 @@ agents:
  - name: pi
    binary: pi
    args: "@{prompt}"
    modelflag: "--model"
    description: "My primary agent harness. Accepts prompt file via {prompt}."
  - name: opencode
    binary: opencode
    args: ""
    modelflag: "-m"
    description: "OpenCode agent. Pipes stdin via cat."
    note: "Uses stdin piping: args must be empty, prompt via pipe."
  - name: goose
    binary: goose
    args: ""
    modelflag: "--model"
    description: "Goose agent. Accepts prompt file via -i flag."
    note: "Uses stdin piping: args must be empty, prompt via pipe."
  - name: codex
    binary: codex
    args: "@{prompt}"
    modelflag: "-m"
    description: "OpenAI Codex. Accepts prompt file via {prompt}."
  - name: claude
    binary: claude
    args: ""
    modelflag: "--model"
    description: "Anthropic Claude CLI. Pipes stdin via cat."
    note: "Uses stdin piping: args must be empty, prompt via pipe."
 ```
@@ -36,9 +41,10 @@ agents:
 ## Field meanings
 | Field | Description |
-|-------|-------------|
+| ------- | ------------- |
 | `name` | Display name used in menus and `--agent` flag |
 | `binary` | Command name expected on PATH |
 | `args` | Static arguments appended after the binary. May include `{prompt}` which is substituted at invocation time with the absolute path to the prompt file. Empty string means stdin piping (prompt is piped via `cat`). |
 | `description` | Short human-readable description for the setup menu |
 | `modelflag` | CLI flag used to select a model (e.g. `--model`, `-m`). Injected into the inner command when `--model <name>` is passed by the user. |
 | `note` | Optional additional context |
@@ -0,0 +1,115 @@
 #!/usr/bin/env bash
 set -euo pipefail
 # tmux-open — open a new tmux window (or session) and run a command
 # Usage: tmux-open [-k|--keep] [-h|--help] <window-name> <start-dir> <cmd> [args...]
 usage() {
    cat <<'EOF'
 Usage: tmux-open [-k|--keep] [-h|--help] <window-name> <start-dir> <cmd> [args...]
 Open a new tmux window in the current session and run a command.
 If not inside tmux, create a new session named after the window and attach.
 Positional arguments:
  window-name   Name for the new tmux window (and session, if creating one)
  start-dir     Working directory for the new window
  cmd [args...] Command to run (variadic)
 Options:
  -k, --keep    After the command exits, keep the pane visible (remain-on-exit)
                so you can inspect output. Default: pane closes when command exits.
  -h, --help    Show this help message
 If `mise` is on PATH, the command runs under `mise x`.
 Errors:
  - tmux not installed
  - fewer than 3 positional args
  - start-dir does not exist
  - a window with the same name already exists in the current session
 EOF
 }
 # --- Flag parsing ---
 keep_shell=0
 while (( $# > 0 )); do
    case "$1" in
        -k|--keep)  keep_shell=1; shift ;;
        -h|--help)  usage; exit 0 ;;
        --)         shift; break ;;
        -*)         echo "error: unknown option: $1" >&2; usage >&2; exit 1 ;;
        *)          break ;;
    esac
 done
 # --- Positional arg validation ---
 if (( $# < 3 )); then
    echo "error: expected at least 3 positional arguments (window-name, start-dir, cmd)" >&2
    usage >&2
    exit 1
 fi
 window_name="$1"; shift
 start_dir="$1"; shift
 cmd_args=("$@")
 # --- Pre-flight checks ---
 if ! command -v tmux >/dev/null 2>&1; then
    echo "error: tmux is not installed or not on PATH" >&2
    exit 1
 fi
 if [[ ! -d "$start_dir" ]]; then
    echo "error: directory does not exist: $start_dir" >&2
    exit 1
 fi
 if (( ${#cmd_args[@]} == 0 )); then
    echo "error: no command specified" >&2
    exit 1
 fi
 # Duplicate window name check (only relevant inside tmux)
 if [[ -n "${TMUX:-}" ]]; then
    if tmux list-windows -F '#{window_name}' | grep -Fxq "$window_name"; then
        echo "error: a window named '$window_name' already exists in the current session" >&2
        exit 1
    fi
 fi
 # --- Detect mise ---
 has_mise=0
 if command -v mise >/dev/null 2>&1; then
    has_mise=1
 fi
 # --- Build the command for the new window ---
 # We need to construct a single shell command string for tmux.
 # The command runs; pane closes on exit (or stays visible with --keep via remain-on-exit).
 # Build the inner command based on mode and mise availability
 # For argv mode, quote each argument
 quoted_args=()
 for arg in "${cmd_args[@]}"; do
    quoted_args+=("$(printf '%q' "$arg")")
 done
 if (( has_mise )); then
    inner_cmd="mise x -- ${quoted_args[*]}"
 else
    inner_cmd="${quoted_args[*]}"
 fi
 # --- Create window or session ---
 if [[ -n "${TMUX:-}" ]]; then
    tmux new-window -n "$window_name" -c "$start_dir" "$inner_cmd"
    if (( keep_shell )); then
        tmux set-option remain-on-exit on
    fi
 else
    tmux new-session -d -n "$window_name" -s "$window_name" -c "$start_dir" "$inner_cmd"
    if (( keep_shell )); then
        tmux set-option -t "$window_name" remain-on-exit on
    fi
    tmux attach-session -t "$window_name"
 fi
@@ -1,6 +1,5 @@
 # Personal Skills
-_No skills currently live in this bucket._
+Tied to my own setup, not promoted.
- `pkm-curation` has been moved to [pkm/pkm-curation](../pkm/pkm-curation/SKILL.md).
+_No skills currently live in this bucket._
 - `forge-preferences` has been moved to [deprecated/forge-preferences](../deprecated/forge-preferences/SKILL.md).
@@ -1,12 +1,14 @@
 # PKM Skills
 Personal knowledge management.
 ## User-invoked
 - [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) — Brainstorm with AI using the CRIT framework to generate and evaluate ideas.
 - [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) — 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.
 ## Model-invoked
- [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian vault — classify notes, normalize frontmatter, add wikilinks, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick.
+- [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.
 - [youtube-video-capture](youtube-video-capture/SKILL.md) — Fetch subtitles from a YouTube video, summarize the content, and save the summary and raw subtitles to the Video bundle.
@@ -1,3 +1,5 @@
 # Productivity Skills
 Daily non-code workflow tools.
 _No skills currently live in this bucket._
@@ -15,12 +15,12 @@ Infer the repo from git remote -v — `tea` does this automatically when run ins
 ## Pull requests as a triage surface
-**PRs as a request surface: no.**
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
 When set to `yes`, PRs run through the same labels and states as issues, using the `tea pr` equivalents:
 - **Read a PR**: `tea pr <number> --comments` and `tea api /repos/{owner}/{repo}/pulls/<number>.diff` for the diff.
- **List external PRs for triage**: `tea pr list --state open -o json` then keep only PRs whose author is not a project member/owner.
+- **List external PRs for triage**: `tea pr list --state open -o json` then keep only PRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
 - **Comment / label / close**: `tea comment <number> "..."`, `tea pr edit --add-label`/`--remove-label`, `tea pr close`.
 Gitea shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `tea pr 42` and fall back to `tea issue 42`.
@@ -39,7 +39,7 @@ Used by `/wayfinder`. The **map** is a single issue with **child** issues as tic
 - **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `tea issue create --label wayfinder:map`.
 - **Child ticket**: an issue linked to the map as a GitHub sub-issue (`tea api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `tea api --method POST /repos/{owner}/{repo}/issues/<child>/dependencies -F index=<blocker-issue-number> -F repo=<blocker-repo-name> -F owner=<bocker-owner-name>`, where `<blocker-usse-number>` is the blocker's numeric **issue number** (`tea api repos/{owner}/{repo}/issues/<n> --jq ".number. .repository.name, .repository.owner"`, where `.number` is the `<blocker-issue-number>`, `.repository.name` is the `<blocker-repo-name>` and `.repository.owner` is the `<blocker-repo-owner>`. Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `tea api --method POST /repos/{owner}/{repo}/issues/<child>/dependencies -F index=<blocker-issue-number> -F repo=<blocker-repo-name> -F owner=<bocker-owner-name>`, where `<blocker-issue-number>` is the blocker's numeric **issue number** (`tea api repos/{owner}/{repo}/issues/<n> --jq ".number. .repository.name, .repository.owner"`, where `.number` is the `<blocker-issue-number>`, `.repository.name` is the `<blocker-repo-name>` and `.repository.owner` is the `<blocker-repo-owner>`. Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
- **Frontier query**: list the map's open dependencies (`tea api /repos/{owner}/{repo}/issues/<n>/dependencies | jq '.[] | select(.state = "open") .number'`, scoped to the map's sub-issues / task list), drop any with an open blocker (`list of dependencies is not empty`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Frontier query**: list the map's open dependencies (`tea api /repos/{owner}/{repo}/issues/<n>/dependencies | jq '.[] | select(.state == "open") | .number'`, scoped to the map's sub-issues / task list), drop any with an open blocker (`list of dependencies is not empty`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
 - **Claim**: `tea issue edit <n> --add-assignees @me` — the session's first write.
- **Resolve**: `tea comments <n> "<answer>"`, then `tea issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
+- **Resolve**: `tea comment <n> "<answer>"`, then `tea issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
@@ -3,10 +3,10 @@
 The skills speak in terms of seven canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
 | Label in skills   | Label in our tracker | Meaning                                  |
-| -------------------------- | -------------------- | ---------------------------------------- |
+| ----------------- | -------------------- | ---------------------------------------- |
 | `needs-triage`    | `needs-triage`       | Maintainer needs to evaluate this issue  |
 | `needs-info`      | `needs-info`         | Waiting on reporter for more information |
-| `needs-review` | `needs-review` | Waiting for reviewed by a human |
+| `needs-review`    | `needs-review`       | Waiting for review by a human            |
 | `ready-for-agent` | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
 | `ready-for-human` | `ready-for-human`    | Requires human implementation            |
 | `in-progress`     | `in-progress`        | Being actively worked on by a human or agents |
Author	SHA1	Message	Date
gitadmin	5a6d1fccb0	chore: reorganize READMEs with sorted entries and bucket descriptions Clean up all skill bucket READMEs — sort entries alphabetically within user/model sections, add category descriptions to each bucket, simplify the deprecated forge-skills doc to a bare notice, update triage label count (5→7) in AGENTS.md, and add a Project Context Pack section.	2026-07-19 10:13:37 -04:00
gitadmin	fa7619bfde	docs: refresh project context and fix agent docs typos - Update .agent/project-context.md with new paths, structure, edit boundaries - Fix typo in issue-tracker.md: tea comments -> tea comment - Fix jq syntax: select(.state = "open") -> select(.state == "open") - Clean up triage-labels.md table formatting	2026-07-19 10:10:51 -04:00
gitadmin	0daa11851d	refactor(tmux-launch-agent): extract tmux-open helper, add modelflag	2026-07-19 09:52:18 -04:00
gitadmin	22c3b3e45f	docs(adr-wiki): rename setup-command reference to /setup-skills	2026-07-19 09:51:00 -04:00
gitadmin	102b163fc5	docs(commit-staged): remove redundant description line from SKILL.md	2026-07-15 17:19:57 -04:00
gitadmin	2a87789523	feat(engineering): add implement-isolation skill, refine implement-issue - Add /skill:implement (implement-isolation) — ticket claim, worktree isolation, tdd, verify, code-review, ship loop - Fix implement-issue: worktree path to issue-<N>-<repo-slug>, label semantics (remove-others), skill ref formatting, drop stale closing note	2026-07-15 17:18:36 -04:00