diff --git a/README.md b/README.md index 5e07180..cd12bd4 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,17 @@ # Skills -A collection of agent skills (slash commands and behaviors) loaded into my agent. +Agent skills (slash commands and behaviors) loaded into my agent. ## User-invoked - [agent-handoff](common/in-progress/agent-handoff/SKILL.md) — Hand the current conversation off to a fresh background agent that picks up the work immediately. -- [audio-product-dsp](common/deprecated/audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs. - [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. -- [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. +- [implement-isolation](common/engineering/implement-isolation/SKILL.md) — Implement a piece of work based on a spec or set of tickets in isolation. +- [implement-isolation-tmux](common/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. - [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. +- [project-context-pack](common/engineering/project-context-pack/SKILL.md) — Build a bounded repo context pack (project map, codebase index, cached memory file) so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing. - [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. @@ -22,8 +19,5 @@ A collection of agent skills (slash commands and behaviors) loaded into my agent ## Model-invoked -- [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. +- [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 links, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick. diff --git a/common/README.md b/common/README.md index bb1460a..a97ef90 100644 --- a/common/README.md +++ b/common/README.md @@ -5,16 +5,13 @@ Skills that work in all CLI agents. ## User-invoked - [agent-handoff](in-progress/agent-handoff/SKILL.md) — Hand the current conversation off to a fresh background agent that picks up the work immediately. -- [audio-product-dsp](deprecated/audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs. - [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. -- [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. +- [implement-isolation](engineering/implement-isolation/SKILL.md) — Implement a piece of work based on a spec or set of tickets in isolation. +- [implement-isolation-tmux](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. - [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. +- [project-context-pack](engineering/project-context-pack/SKILL.md) — Build a bounded repo context pack (project map, codebase index, cached memory file) so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing. - [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. @@ -22,8 +19,5 @@ Skills that work in all CLI agents. ## Model-invoked -- [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. +- [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 links, extract atomic notes. Use when curating, batch-processing, reviewing, or doing a serendipity pick. diff --git a/common/deprecated/README.md b/common/deprecated/README.md deleted file mode 100644 index 74d784a..0000000 --- a/common/deprecated/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# 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. - -## 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. -- [forge-preferences](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. diff --git a/common/deprecated/audio-production-dispatcher/SKILL.md b/common/deprecated/audio-production-dispatcher/SKILL.md deleted file mode 100644 index 4478210..0000000 --- a/common/deprecated/audio-production-dispatcher/SKILL.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -disable-model-invocation: true -name: audio-product-dsp -description: Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs ---- - -Role: You are a dispatcher skill for audio product DSP research and engineering. You route requests to the right specialist path(s), enforce product constraints, and return one decision-ready answer. - -Primary objectives: -- Classify audio product requests across algorithm, embedded implementation, hardware integration, tuning, and validation. -- Route to the best specialist workflow(s) using explicit scoring. -- Deliver outputs tied to user-perceived quality, latency, power, and manufacturable constraints. -- Keep recommendations testable and release-oriented. - -Scope: -- In scope: speech/audio enhancement, ANC, beamforming, AEC/NS/AGC, codec pipelines, loudness/tuning, fixed-point deployment, RT embedded audio, product validation plans. -- Out of scope: medical diagnosis claims, regulatory/legal sign-off, unsafe hearing-level recommendations, fabricated bench/listening data. - -Non-goals: -- Do not claim audible improvements without metric or listening-test basis. -- Do not suggest architecture changes that violate hard latency/power/platform constraints without calling out tradeoffs. -- Do not present lab verification as completed if only conceptual. - -Inputs expected: -- User request text -- Conversation context -- Available specialist agents/skills -- Product constraints (if available): - - device type (earbuds, headset, speakerphone, soundbar, hearing-assist, etc.) - - mic/speaker topology - - sample rate/frame size - - end-to-end latency budget - - CPU/MIPS, RAM/flash - - battery/power target - - codec/transport constraints (BT, USB, VoIP, etc.) - - target metrics and UX goals - -Required output contract: -- Always provide: - 1) Selected route - 2) Why route fits product goals - 3) Final recommendation - 4) Assumptions and open risks - 5) Verification plan (objective + subjective) - 6) Confidence level - -Dispatch taxonomy (audio product specific): -- Voice Quality Path: AEC/NS/AGC, double-talk robustness, far-end preservation, speech intelligibility. -- Playback Quality Path: EQ/DRC/loudness, distortion management, clipping avoidance, tonal balance. -- Spatial/Array Path: beamforming, DOA, mic calibration sensitivity, wind/noise robustness. -- ANC Path: feedforward/feedback/hybrid ANC stability, leakage robustness, fit variance strategy. -- Embedded RT Path: buffering, ISR/DMA, frame deadlines, SIMD acceleration, memory bandwidth. -- Hardware Integration Path: codec clocks, interfaces, mic bias/noise floor, amp/headroom, thermal limits. -- Validation Path: objective metrics, golden references, listening tests, production regression. -- Research Synthesis Path: state-of-the-art comparison, feasibility/risk, phased experiment plan. - -Routing policy: -1. Parse request into one or more intents. -2. Extract success criteria and hard product constraints. -3. Score candidate routes: - - Relevance (0-5) - - Product-fit (0-5) - - Feasibility/safety (0-5) - - Evidence readiness (0-5) - - Implementation cost (0-5, lower is better) -4. Select single-route or multi-route orchestration. -5. Dispatch structured task packets. -6. Reconcile into one release-oriented recommendation. - -Confidence rules: -- High: clear winner and all critical constraints known. -- Medium: winner exists but one non-critical constraint unknown; proceed with explicit assumptions. -- Low: tied routes or missing critical constraint; ask exactly one targeted question. - -Critical constraints checklist: -- Product form factor and acoustic topology -- Sample rate, frame size, channel count -- End-to-end latency budget (capture->process->render) -- CPU/MIPS and memory budgets -- Power target and thermal envelope -- Numeric format (float/fixed word lengths) -- UX priority (call clarity, music fidelity, ANC depth, wake-word reliability, etc.) -- Acceptance metrics and pass/fail thresholds - -Audio product metrics catalog: -- Voice/call: PESQ/POLQA, STOI, ERLE, double-talk performance, barge-in robustness. -- Playback: THD+N, frequency response error, max SPL before limiting artifacts, crest-factor handling. -- ANC: attenuation vs frequency, residual noise spectra, stability margin, fit-leak sensitivity. -- System: RTL latency, glitch/dropout rate, CPU load, memory headroom, battery impact. -- Subjective: MUSHRA/AB preference tests, panel notes, artifact taxonomy. - -Safety and integrity gates: -- Never fabricate measurements, listening outcomes, or citations. -- If hearing safety could be impacted, require explicit level limits and verification steps. -- If irreversible hardware actions are requested, require explicit confirmation and safe fallback path. -- Protect credentials and proprietary parameters. - -Specialist route mapping: -- "Improve call quality" -> Voice Quality + Validation paths -- "Reduce earbud power while keeping ANC" -> ANC + Embedded RT + Hardware Integration -- "Fix audio glitches" -> Embedded RT + Hardware Integration + Validation -- "Compare beamforming methods" -> Spatial/Array + Research Synthesis -- "Ship-ready tuning plan" -> Playback/Voice/ANC (as relevant) + Validation - -Task packet format for downstream specialists: -```json -{ - "objective": "", - "constraints": { - "latency_ms": "", - "cpu_budget": "", - "power_budget": "", - "platform": "", - "sample_rate_hz": "", - "frame_size": " -" - }, - "required_output": [ - "Recommended approach", - "Why it fits product goals", - "Tradeoffs", - "Top 3 risks", - "Objective metrics to track", - "Subjective listening checks", - "Implementation next steps" - ], - "limits": [ - "No fabricated data", - "State assumptions explicitly" - ] -} -``` - -Orchestration rules: -- Split only when subproblems are independent and interfaces are clear. -- Normalize units (ms, dB, Hz, mW, MIPS) and definitions across outputs. -- Resolve conflicts by preferring measured evidence > validated simulation > reasoned estimate. -- If conflict remains, present it as a decision fork with verification to break the tie. - -Fallback behavior: -- If selected specialist fails, retry once with narrower objective and stricter output schema. -- If retry fails, route to a generalist technical path and lower confidence. -- If critical constraints are missing, provide best-effort baseline + one blocking question. - -Response template: -```text -Route Selected: -- - -Why This Route: -- <1-3 product-focused bullets> - -Recommendation: - - -Assumptions and Risks: -- - -Verification Plan: -- Objective: <3-7 checks with metrics and thresholds> -- Subjective: <2-5 listening test checks> - -Confidence: -- with one-line rationale -``` - -Clarification template (only when blocked): -```text -I can dispatch this accurately, but I need one detail: -- - -Default I will assume for speed: -- -``` - -Quality bar: -- Product impact over algorithm novelty. -- Verifiable claims over qualitative promises. -- Fast experiment loops over broad rewrites. -- Explicit uncertainty over false precision. diff --git a/common/deprecated/dsp-research-dispatcher/SKILL.md b/common/deprecated/dsp-research-dispatcher/SKILL.md deleted file mode 100644 index 7deb90d..0000000 --- a/common/deprecated/dsp-research-dispatcher/SKILL.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -disable-model-invocation: true -name: research-engineering -description: Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output ---- - -Role: You are a dispatcher skill for DSP hardware and software research engineering. You triage requests, select the right specialist path(s), enforce safety and reproducibility constraints, and return one coherent response. - -Primary objectives: -- Identify technical intent across algorithms, embedded implementation, hardware architecture, tooling, and validation. -- Route work to the most appropriate specialist workflow(s) with explicit assumptions. -- Produce practical, testable outputs for research engineering decisions. -- Minimize unnecessary handoffs and avoid over-engineering. - -Scope: -- In scope: signal analysis, DSP algorithm design, fixed-point strategy, embedded audio/DSP implementation, architecture tradeoffs, measurement plans, benchmarking, verification strategy, literature-grounded research synthesis. -- Out of scope: legal/compliance claims, medical claims, fabrication process sign-off, irreversible production actions. - -Non-goals: -- Do not pretend to run lab measurements that were not run. -- Do not claim numerical performance without source, simulation, or measurement basis. -- Do not bypass hardware safety, power, thermal, EMC, or hearing-safety constraints. - -Inputs expected: -- User request text -- Current conversation context -- Available specialist agents/skills -- Environment/tooling constraints -- Optional project constraints (sample rate, latency budget, CPU target, memory budget, power target, BOM constraints) - -Required output contract: -- Always provide: - 1) Selected route - 2) Why this route - 3) Final user-facing result - 4) Assumptions and unknowns - 5) Verification plan (how to confirm correctness/performance) - -Dispatch taxonomy: -- Algorithm Design: filters, adaptive processing, beamforming, detection/classification front-ends, denoising, dynamics, time-frequency methods. -- Numerical Implementation: fixed-point, quantization noise, saturation behavior, scaling, coefficient sensitivity, stability under finite precision. -- Embedded Software: RT constraints, DMA/ISR design, buffering, scheduling, memory layout, SIMD/accelerators, portability. -- Hardware/Platform: MCU/DSP/FPGA partitioning, codec/interface constraints, clocking, throughput, latency, power/thermal tradeoffs. -- Validation and Measurement: objective metrics, stimulus design, golden references, regression tests, bench/lab measurement plans. -- Research Synthesis: literature scan, method comparison, risk/novelty assessment, experiment roadmap. - -Routing policy: -1. Parse request into one or more intents. -2. Extract hard constraints and success criteria. -3. Score candidate routes on: - - Relevance (0-5) - - Capability fit (0-5) - - Safety/feasibility (0-5) - - Evidence availability (0-5) - - Execution cost (0-5, lower is better) -4. Select route: - - Single-route if one clear winner. - - Multi-route if subproblems are separable and independent. -5. Dispatch with structured task packets. -6. Reconcile outputs into a single final response. - -Confidence rules: -- High: top route exceeds second by >= 3 and all hard constraints are known. -- Medium: top route exceeds second by 1-2 or one non-critical constraint missing; proceed with explicit assumptions. -- Low: tie score or missing critical constraint (platform, sample rate, latency, safety limit); ask exactly one targeted question. - -Critical constraints checklist: -- Target platform (e.g., Cortex-M4/M7, SHARC, FPGA family) -- Sample rate and channel count -- End-to-end latency budget -- CPU/memory budget -- Power/thermal envelope (if embedded/portable) -- Numeric format (float/fixed, word lengths) -- Required performance metrics (SNR, THD+N, PESQ/STOI, detection F1, etc.) - -Safety and integrity gates (must run before dispatch): -- If safety-critical or human-impacting audio claims are requested, include explicit uncertainty and verification requirements. -- If destructive hardware actions are requested, require explicit confirmation and safe fallback. -- Never expose secrets, proprietary keys, or internal credentials. -- Never fabricate measurement data or citations. - -Specialist route mapping: -- Signal characterization question -> Signal Analysis specialist -- Embedded DSP implementation/debug -> Embedded DSP specialist -- Hardware/software partitioning -> Embedded hardware architect path -- Literature-heavy "state of the art" request -> Research Assistant or literature path -- Cross-domain request (algorithm + embedded + validation) -> Multi-route orchestration with unified recommendation - -Task packet format for downstream specialists: -```json -{ - "objective": "", - "context": ["", ""], - "required_output": [ - "Approach", - "Tradeoffs", - "Risks", - "Verification steps", - "Confidence" - ], - "limits": ["No fabricated data", "State unknowns explicitly"] -} -``` - -Multi-route orchestration rules: -- Split only when interfaces between subproblems are clear. -- Normalize units and terminology across outputs. -- Resolve disagreements by preferring: measured evidence > validated simulation > reasoned estimate. -- If unresolved conflict remains, surface it as a decision risk. - -Fallback behavior: -- If selected specialist fails, retry once with narrowed objective and stricter output format. -- If retry fails, route to a generalist technical path and label confidence reduced. -- If key constraints are missing, provide a best-effort scaffold plus one blocking question. - -Response template: -```text -Route Selected: -- - -Why This Route: -- <1-3 concise bullets> - -Result: - - -Assumptions and Unknowns: -- - -Verification Plan: -- <3-7 concrete checks/tests/measurements> - -Confidence: -- with one-line rationale -``` - -Clarification template (only when blocked): -```text -I can dispatch this precisely, but I need one detail: -- - -Default I will assume if you prefer speed: -- -``` - -Quality bar: -- Actionable over theoretical. -- Reproducible over vague. -- Explicit uncertainty over false precision. -- Deliver the smallest valid plan that can be tested quickly. diff --git a/common/deprecated/forge-gitea/SKILL.md b/common/deprecated/forge-gitea/SKILL.md deleted file mode 100644 index a202a7e..0000000 --- a/common/deprecated/forge-gitea/SKILL.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -name: forge-gitea ---- - -# Gitea Forge Interaction - -Use this skill for Gitea forge work when the user wants to interact with Gitea repositories, issues, pull requests, releases, or CI. - -## Purpose - -Choose the correct Gitea CLI (`tea`) and use it to interact with Gitea issues, pull requests, releases, CI, and repository state. - -This skill is intended to perform Gitea forge actions, including mutating actions, when the user asks for them. Do not turn every requested forge action into a confirmation loop; if the user clearly asks to create, edit, comment, publish, or release, do the requested action after selecting the correct CLI. - -## Strict Decision Tree - -Follow this order every time. - -### 1. Determine the target remote - -1. If the user explicitly says which remote or forge to use, use that. -2. Else, if user/project memory or repo guidance states where to find the forge, use that. -3. Else, if a remote named `forge` exists, use `forge`. -4. Else, if the user has configured a default remote, use that. -5. Else, use `origin`. - -Useful inspection commands: - -```bash -git remote -v -git config --get checkout.defaultRemote -git config --get clone.defaultRemoteName -git config --get branch.$(git branch --show-current).remote -``` - -Interpretation: - -- A remote named `forge` is the preferred convention for the canonical forge remote. -- If no `forge` remote exists, `origin` is the fallback. -- If the current branch has an upstream remote and no stronger rule applies, treat that as the user's configured default for the current work. - -Only mention this selection if there is ambiguity or a conflict. - -### 2. Choose the CLI - -Use `tea` for Gitea interactions. - -Check whether the chosen CLI is available: - -```bash -command -v tea >/dev/null 2>&1 && tea --version -``` - -If the needed CLI is missing: - -- Tell the user which CLI is required: `tea` for Gitea. -- Tell the user to install it. -- If it may already be installed but not discoverable, tell the user to add it to their `PATH`. -- Do not use the wrong CLI as a fallback. - -### 3. Check authentication/context - -Use read-only checks for the selected tool: - -```bash -tea login list -tea repos ls -``` - -If authentication is missing, tell the user which CLI needs login/configuration. Do not ask the user to paste tokens or secrets. - -### 4. Do the requested forge task - -Perform the requested action with `tea` commands such as: - -```bash -tea issues list -tea issues create -tea issues comment -tea pulls list -tea pulls create -tea pulls view -tea pulls comment -tea pulls merge -tea releases list -tea releases create -``` - -Use exact command syntax supported by the installed CLI version; inspect help when needed: - -```bash -tea help -``` - -## Mutating Actions - -Mutating forge actions are allowed when clearly requested by the user, including: - -- create an issue; -- modify an issue; -- comment on an issue; -- create a pull request; -- modify a pull request; -- comment on a pull request; -- push a branch; -- publish changes; -- create a release. - -Still be careful with destructive or high-impact actions: - -- Ask before deleting branches, tags, releases, issues, or repositories. -- Ask before force-pushing. -- Ask before merging a PR unless the user explicitly asked to merge it. -- Ask before overwriting existing release assets or tags. - -## Branch and PR Preparation - -Before creating or updating a PR: - -1. Select the remote using the strict decision tree. -2. Inspect branch state and upstream tracking. -3. Inspect the diff against the target branch. -4. Read the PR template if one exists. -5. Push the branch if needed and requested by the workflow. -6. Create or update the PR. - -Useful local inspection: - -```bash -git status --short --branch -git branch -vv -git diff --stat -git diff --check -``` - -## Output Style - -Normally, do not over-explain. If the remote/tool selection is straightforward, just complete the task and summarize the result. - -Report detection details only when there is ambiguity, conflict, missing tooling, or failure. In those cases include: - -- selected remote; -- detected forge; -- selected CLI; -- reason for the choice; -- what the user needs to fix, if anything. \ No newline at end of file diff --git a/common/deprecated/forge-github/SKILL.md b/common/deprecated/forge-github/SKILL.md deleted file mode 100644 index 9ead27c..0000000 --- a/common/deprecated/forge-github/SKILL.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -name: forge-github ---- - -# GitHub Forge Interaction - -Use this skill for GitHub forge work when the user wants to interact with GitHub repositories, issues, pull requests, releases, or CI. - -## Purpose - -Choose the correct GitHub CLI (`gh`) and use it to interact with GitHub issues, pull requests, releases, CI, and repository state. - -This skill is intended to perform GitHub forge actions, including mutating actions, when the user asks for them. Do not turn every requested forge action into a confirmation loop; if the user clearly asks to create, edit, comment, publish, or release, do the requested action after selecting the correct CLI. - -## Strict Decision Tree - -Follow this order every time. - -### 1. Determine the target remote - -1. If the user explicitly says which remote or forge to use, use that. -2. Else, if user/project memory or repo guidance states where to find the forge, use that. -3. Else, if a remote named `forge` exists, use `forge`. -4. Else, if the user has configured a default remote, use that. -5. Else, use `origin`. - -Useful inspection commands: - -```bash -git remote -v -git config --get checkout.defaultRemote -git config --get clone.defaultRemoteName -git config --get branch.$(git branch --show-current).remote -``` - -Interpretation: - -- A remote named `forge` is the preferred convention for the canonical forge remote. -- If no `forge` remote exists, `origin` is the fallback. -- If the current branch has an upstream remote and no stronger rule applies, treat that as the user's configured default for the current work. - -Only mention this selection if there is ambiguity or a conflict. - -### 2. Choose the CLI - -Use `gh` for GitHub interactions. - -Check whether the chosen CLI is available: - -```bash -command -v gh >/dev/null 2>&1 && gh --version -``` - -If the needed CLI is missing: - -- Tell the user which CLI is required: `gh` for GitHub. -- Tell the user to install it. -- If it may already be installed but not discoverable, tell the user to add it to their `PATH`. -- Do not use the wrong CLI as a fallback. - -### 3. Check authentication/context - -Use read-only checks for the selected tool: - -```bash -gh auth status -gh repo view -``` - -If authentication is missing, tell the user which CLI needs login/configuration. Do not ask the user to paste tokens or secrets. - -### 4. Do the requested forge task - -Perform the requested action with `gh` commands such as: - -```bash -gh issue list -gh issue create -gh issue comment -gh pr list -gh pr create -gh pr view -gh pr comment -gh pr edit -gh pr merge -gh run list -gh run view -gh release list -gh release create -``` - -Use exact command syntax supported by the installed CLI version; inspect help when needed: - -```bash -gh help -``` - -## Mutating Actions - -Mutating forge actions are allowed when clearly requested by the user, including: - -- create an issue; -- modify an issue; -- comment on an issue; -- create a pull request; -- modify a pull request; -- comment on a pull request; -- push a branch; -- publish changes; -- create a release. - -Still be careful with destructive or high-impact actions: - -- Ask before deleting branches, tags, releases, issues, or repositories. -- Ask before force-pushing. -- Ask before merging a PR unless the user explicitly asked to merge it. -- Ask before overwriting existing release assets or tags. - -## Branch and PR Preparation - -Before creating or updating a PR: - -1. Select the remote using the strict decision tree. -2. Inspect branch state and upstream tracking. -3. Inspect the diff against the target branch. -4. Read the PR template if one exists. -5. Push the branch if needed and requested by the workflow. -6. Create or update the PR. - -Useful local inspection: - -```bash -git status --short --branch -git branch -vv -git diff --stat -git diff --check -``` - -## Output Style - -Normally, do not over-explain. If the remote/tool selection is straightforward, just complete the task and summarize the result. - -Report detection details only when there is ambiguity, conflict, missing tooling, or failure. In those cases include: - -- selected remote; -- detected forge; -- selected CLI; -- reason for the choice; -- what the user needs to fix, if anything. \ No newline at end of file diff --git a/common/deprecated/forge-interaction/SKILL.md b/common/deprecated/forge-interaction/SKILL.md deleted file mode 100644 index 299f0f0..0000000 --- a/common/deprecated/forge-interaction/SKILL.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -name: forge-interaction -description: 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 Interaction (Router) - -This skill has been refactored into specialized skills for better predictability and maintainability: - -- **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 - -## Purpose - -This router skill delegates to the appropriate specialized forge interaction skill based on the target forge. Each specialized skill handles one forge type completely, making them more predictable and easier to maintain. - -## When to use: - -- If you're unsure which forge you're working with, use this skill and it will guide you -- For general forge work without specifying the forge type -- When you want the system to figure out which specialized skill to use - -## Delegation Logic - -The router analyzes your request and determines whether to delegate to: - -1. **GitHub skill** (`/forge-github`) - for GitHub repositories and workflows -2. **Gitea skill** (`/forge-gitea`) - for Gitea repositories and workflows - -Each specialized skill contains the complete decision tree and implementation for its respective forge type. - -## Recommendation - -For most predictable results, use the specialized skills directly: -- `/forge-github` when working with GitHub -- `/forge-gitea` when working with Gitea - -This separation follows the principle of single responsibility and makes each skill more focused and reliable. - -## Strict Decision Tree - -Follow this order every time. - -### 1. Determine the target remote - -1. If the user explicitly says which remote or forge to use, use that. -2. Else, if user/project memory or repo guidance states where to find the forge, use that. -3. Else, if a remote named `forge` exists, use `forge`. -4. Else, if the user has configured a default remote, use that. -5. Else, use `origin`. - -Useful inspection commands: - -```bash -git remote -v -git config --get checkout.defaultRemote -git config --get clone.defaultRemoteName -git config --get branch.$(git branch --show-current).remote -``` - -Interpretation: - -- A remote named `forge` is the preferred convention for the canonical forge remote. -- If no `forge` remote exists, `origin` is the fallback. -- If the current branch has an upstream remote and no stronger rule applies, treat that as the user's configured default for the current work. - -Only mention this selection if there is ambiguity or a conflict. - -### 2. Determine the forge type from the chosen remote - -Inspect the selected remote URL: - -```bash -git remote get-url -``` - -Classify it: - -- URLs containing `github.com` are GitHub. -- URLs containing `gitea`, or a known Gitea host from memory/project guidance, are Gitea. -- If the remote is self-hosted and ambiguous, inspect repo guidance, memory, and web/API/tool configuration before asking. - -Do not choose based on which CLI is installed. The remote determines the forge; the forge determines the CLI. - -### 3. Choose the CLI - -- If the forge is GitHub, use `gh`. -- If the forge is Gitea, use `tea`. - -Check whether the chosen CLI is available: - -```bash -command -v gh >/dev/null 2>&1 && gh --version -command -v tea >/dev/null 2>&1 && tea --version -``` - -If the needed CLI is missing: - -- Tell the user which CLI is required: `gh` for GitHub, `tea` for Gitea. -- Tell the user to install it. -- If it may already be installed but not discoverable, tell the user to add it to their `PATH`. -- Do not use the wrong CLI as a fallback. - -### 4. Check authentication/context - -Use read-only checks for the selected tool: - -```bash -# GitHub -gh auth status -gh repo view - -# Gitea -tea login list -tea repos ls -``` - -If authentication is missing, tell the user which CLI needs login/configuration. Do not ask the user to paste tokens or secrets. - -### 5. Do the requested forge task - -Perform the requested action with the selected CLI. - -For GitHub, use `gh` commands such as: - -```bash -gh issue list -gh issue create -gh issue comment -gh pr list -gh pr create -gh pr view -gh pr comment -gh pr edit -gh pr merge -gh run list -gh run view -gh release list -gh release create -``` - -For Gitea, use `tea` commands such as: - -```bash -tea issues list -tea issues create -tea issues comment -tea pulls list -tea pulls create -tea pulls view -tea pulls comment -tea pulls merge -tea releases list -tea releases create -``` - -Use exact command syntax supported by the installed CLI version; inspect help when needed: - -```bash -gh help -tea help -``` - -## Mutating Actions - -Mutating forge actions are allowed when clearly requested by the user, including: - -- create an issue; -- modify an issue; -- comment on an issue; -- create a pull request; -- modify a pull request; -- comment on a pull request; -- push a branch; -- publish changes; -- create a release. - -Still be careful with destructive or high-impact actions: - -- Ask before deleting branches, tags, releases, issues, or repositories. -- Ask before force-pushing. -- Ask before merging a PR unless the user explicitly asked to merge it. -- Ask before overwriting existing release assets or tags. - -## Branch and PR Preparation - -Before creating or updating a PR: - -1. Select the remote using the strict decision tree. -2. Select the CLI from the remote's forge type. -3. Inspect branch state and upstream tracking. -4. Inspect the diff against the target branch. -5. Read the PR template if one exists. -6. Push the branch if needed and requested by the workflow. -7. Create or update the PR. - -Useful local inspection: - -```bash -git status --short --branch -git branch -vv -git diff --stat -git diff --check -``` - -## Output Style - -Normally, do not over-explain. If the remote/tool selection is straightforward, just complete the task and summarize the result. - -Report detection details only when there is ambiguity, conflict, missing tooling, or failure. In those cases include: - -- selected remote; -- detected forge; -- selected CLI; -- reason for the choice; -- what the user needs to fix, if anything. - -## Companion Personal Skill - -Personal forge preferences should live in a separate skill or memory entry, not in this general skill. That companion skill/memory may specify things like: - -- preferred default remote conventions; -- known personal Gitea or GitHub hosts; -- preferred issue/PR/release styles; -- project-specific forge rules. - -This general skill should consume that memory/guidance when present, but keep the generic decision tree above as the fallback. diff --git a/common/deprecated/forge-preferences/SKILL.md b/common/deprecated/forge-preferences/SKILL.md deleted file mode 100644 index 0e1fc76..0000000 --- a/common/deprecated/forge-preferences/SKILL.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -name: forge-preferences -description: Use with forge-interaction to apply Steve's personal or project-specific GitHub/Gitea remote, CLI, issue, PR, and release preferences. ---- - -# Forge Preferences - -Use this companion skill with `/forge-interaction` when personal or project-specific forge preferences are relevant. - -## Purpose - -Store personal conventions that should not live in the generic forge interaction skill. - -## Current Preferences - -- If a remote named `forge` exists, treat it as the canonical forge remote. -- If no `forge` remote exists, use the user's configured default remote when available. -- If no default remote is configured, use `origin`. -- Use the forge type of the selected remote to choose the CLI: - - GitHub → `gh` - - Gitea → `tea` -- If the correct CLI is missing, tell the user to install it or add it to `PATH`. -- Do not use the wrong CLI as a fallback. - -## Derived Preferences (auto-detected at runtime) - -- Canonical forge remote: prefer `forge`, then default remote, then `origin`. -- Forge CLI: determined from remote URL (GitHub → `gh`, Gitea → `tea`). -- Known personal Gitea hosts and GitHub usernames/orgs are collected from the remote URL and git CLI at time of use — no hardcoded list. - -## Issue Labels - -See `triage-labels.md` in this directory for the canonical-to-actual label mapping. - -## PR Conventions - -- PR titles follow Conventional Commits: `type(scope): description`. - - Common types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`. -- PR body is freeform but should summarise the change and any breaking or noteworthy details. - -## Release Conventions - -- Tags follow semver: `v{major}.{minor}.{patch}` (e.g. `v1.2.3`). -- Releases are created from the tag with auto-generated or manually curated notes. diff --git a/common/deprecated/forge-preferences/triage-labels.md b/common/deprecated/forge-preferences/triage-labels.md deleted file mode 100644 index b716855..0000000 --- a/common/deprecated/forge-preferences/triage-labels.md +++ /dev/null @@ -1,15 +0,0 @@ -# Triage Labels - -The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. - -| Label in mattpocock/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 | -| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | -| `ready-for-human` | `ready-for-human` | Requires human implementation | -| `wontfix` | `wontfix` | Will not be actioned | - -When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. - -Edit the right-hand column to match whatever vocabulary you actually use. diff --git a/common/deprecated/forge-router/SKILL.md b/common/deprecated/forge-router/SKILL.md deleted file mode 100644 index 98401be..0000000 --- a/common/deprecated/forge-router/SKILL.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: forge-router -disable-model-invocation: true ---- - -# Forge Router - -Choose the right forge interaction skill for your task. - -## When to use: - -- **GitHub**: Use `/forge-github` when working with GitHub repositories, issues, pull requests, releases, or CI. -- **Gitea**: Use `/forge-gitea` when working with Gitea repositories, issues, pull requests, releases, or CI. - -## How it works: - -The router delegates to specialized skills that handle each forge type separately. This keeps each skill focused and predictable. - -**GitHub skill** (`/forge-github`): -- Handles GitHub-specific interactions using the `gh` CLI -- Follows GitHub's API patterns and conventions -- Optimized for GitHub's feature set - -**Gitea skill** (`/forge-gitea`): -- Handles Gitea-specific interactions using the `tea` CLI -- Follows Gitea's API patterns and conventions -- Optimized for Gitea's feature set - -## Why separate: - -- **Predictability**: Each skill knows exactly one forge type -- **Maintainability**: Changes to GitHub or Gitea logic stay isolated -- **Clarity**: Users can see which forge a skill handles at a glance -- **Testing**: Each skill can be tested independently - -## Usage examples: - -``` -# For GitHub work -/forge-github create an issue in this repo -/forge-github list pull requests -/forge-github check CI status - -# For Gitea work -/forge-gitea create an issue in this repo -/forge-gitea list pull requests -/forge-gitea check CI status -``` - -The router ensures you always use the right tool for the right forge. \ No newline at end of file diff --git a/common/deprecated/forge-skills/README.md b/common/deprecated/forge-skills/README.md deleted file mode 100644 index c56158b..0000000 --- a/common/deprecated/forge-skills/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# Forge Skills - -These skills have been deprecated. See [../README.md](../README.md) for the current list. - -## Overview - -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.