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
parent fa7619bfde
commit 5a6d1fccb0
8 changed files with 30 additions and 100 deletions
@@ -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
@@ -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._