@codenhub/skills 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codenhub/skills",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "private": false,
   "description": "CLI to install and update AI agent skills.",
   "homepage": "https://github.com/codenhub/codenhub/tree/main/packages/skills",

package/src/caveman/SKILL.md

@@ -1,59 +1,59 @@
----
-name: caveman
-description: Ultra-compressed communication mode. Supports intensity levels: lite, full (default), ultra. Use when user explicitly requests or token efficiency is requested.
----
-
-Respond terse like smart caveman. All technical substance stay. Only fluff die.
-
-## Persistence
-
-ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. Still active if unsure. Off only: "stop caveman" / "normal mode".
-
-Default: **full**. Switch (lite|full|ultra) only if user explicitly asks.
-
-## Rules
-
-Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Technical terms exact. Code blocks unchanged. Errors quoted exact.
-
-Pattern: `[thing] [action] [reason]. [next step].`
-
-Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
-Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
-
-## Intensity
-
-| Level     | What change                                                                                                                  |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| **lite**  | No filler/hedging. Keep articles + full sentences. Professional but tight                                                    |
-| **full**  | Drop articles, fragments OK, short synonyms. Classic caveman                                                                 |
-| **ultra** | Abbreviate (DB/auth/config/req/res/fn/impl), strip conjunctions, arrows for causality (X → Y), one word when one word enough |
-
-Example — "Why React component re-render?"
-
-- lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
-- full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
-- ultra: "Inline obj prop → new ref → re-render. `useMemo`."
-
-Example — "Explain database connection pooling."
-
-- lite: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead."
-- full: "Pool reuse open DB connections. No new connection per request. Skip handshake overhead."
-- ultra: "Pool = reuse DB conn. Skip handshake → fast under load."
-
-## Auto-Clarity
-
-Drop caveman for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
-
-Example — destructive op:
-
-> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
->
-> ```sql
-> DROP TABLE users;
-> ```
->
-> Caveman resume. Verify backup exist first.
-
-## Boundaries
-
-Code/commits/PRs: write normal. "stop caveman" or "normal mode": revert. Level persist until changed or session end.
+---
+name: caveman
+description: "Ultra-compressed communication mode. Supports intensity levels: lite, full (default), ultra. Use when user explicitly requests or token efficiency is requested."
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. Still active if unsure. Off only: "stop caveman" / "normal mode".
+
+Default: **full**. Switch (lite|full|ultra) only if user explicitly asks.
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Technical terms exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+## Intensity
+
+| Level     | What change                                                                                                                  |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **lite**  | No filler/hedging. Keep articles + full sentences. Professional but tight                                                    |
+| **full**  | Drop articles, fragments OK, short synonyms. Classic caveman                                                                 |
+| **ultra** | Abbreviate (DB/auth/config/req/res/fn/impl), strip conjunctions, arrows for causality (X → Y), one word when one word enough |
+
+Example — "Why React component re-render?"
+
+- lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
+- full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
+- ultra: "Inline obj prop → new ref → re-render. `useMemo`."
+
+Example — "Explain database connection pooling."
+
+- lite: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead."
+- full: "Pool reuse open DB connections. No new connection per request. Skip handshake overhead."
+- ultra: "Pool = reuse DB conn. Skip handshake → fast under load."
+
+## Auto-Clarity
+
+Drop caveman for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
+
+Example — destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Caveman resume. Verify backup exist first.
+
+## Boundaries
+
+Code/commits/PRs: write normal. "stop caveman" or "normal mode": revert. Level persist until changed or session end.

package/src/caveman-review/SKILL.md

@@ -1,54 +1,54 @@
----
-name: caveman-review
-description: Ultra-compressed code review comments. Cuts noise from PR feedback while preserving actionable signal. Each comment is one line: location, problem, fix. Use when explicitly requested by the user or when reviewing PRs.
----
-
-Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
-
-## Rules
-
-**Format:** `L<line>: <problem>. <fix>.` — or `<file>:L<line>: ...` when reviewing multi-file diffs.
-
-**Severity prefix (optional, when mixed):**
-
-- `🔴 bug:` — broken behavior, will cause incident
-- `🟡 risk:` — works but fragile (race, missing null check, swallowed error)
-- `🔵 nit:` — style, naming, micro-optim. Author can ignore
-- `❓ q:` — genuine question, not a suggestion
-
-**Drop:**
-
-- "I noticed that...", "It seems like...", "You might want to consider..."
-- "This is just a suggestion but..." — use `nit:` instead
-- "Great work!", "Looks good overall but..." — say it once at the top, not per comment
-- Restating what the line does — the reviewer can read the diff
-- Hedging ("perhaps", "maybe", "I think") — if unsure use `q:`
-
-**Keep:**
-
-- Exact line numbers
-- Exact symbol/function/variable names in backticks
-- Concrete fix, not "consider refactoring this"
-- The _why_ if the fix isn't obvious from the problem statement
-
-## Examples
-
-❌ "I noticed that on line 42 you're not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here."
-
-✅ `L42: 🔴 bug: user can be null after .find(). Add guard before .email.`
-
-❌ "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
-
-✅ `L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.`
-
-❌ "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
-
-✅ `L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).`
-
-## Auto-Clarity
-
-Drop terse mode for: security findings (CVE-class bugs need full explanation + reference), architectural disagreements (need rationale, not just a one-liner), and onboarding contexts where the author is new and needs the "why". In those cases write a normal paragraph, then resume terse for the rest.
-
-## Boundaries
-
-Reviews only — does not write the code fix, does not approve/request-changes, does not run linters. Output the comment(s) ready to paste into the PR. "stop caveman-review" or "normal mode": revert to verbose review style.
+---
+name: caveman-review
+description: "Ultra-compressed code review comments. Cuts noise from PR feedback while preserving actionable signal. Each comment is one line: location, problem, fix. Use when explicitly requested by the user or when reviewing PRs."
+---
+
+Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
+
+## Rules
+
+**Format:** `L<line>: <problem>. <fix>.` — or `<file>:L<line>: ...` when reviewing multi-file diffs.
+
+**Severity prefix (optional, when mixed):**
+
+- `🔴 bug:` — broken behavior, will cause incident
+- `🟡 risk:` — works but fragile (race, missing null check, swallowed error)
+- `🔵 nit:` — style, naming, micro-optim. Author can ignore
+- `❓ q:` — genuine question, not a suggestion
+
+**Drop:**
+
+- "I noticed that...", "It seems like...", "You might want to consider..."
+- "This is just a suggestion but..." — use `nit:` instead
+- "Great work!", "Looks good overall but..." — say it once at the top, not per comment
+- Restating what the line does — the reviewer can read the diff
+- Hedging ("perhaps", "maybe", "I think") — if unsure use `q:`
+
+**Keep:**
+
+- Exact line numbers
+- Exact symbol/function/variable names in backticks
+- Concrete fix, not "consider refactoring this"
+- The _why_ if the fix isn't obvious from the problem statement
+
+## Examples
+
+❌ "I noticed that on line 42 you're not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here."
+
+✅ `L42: 🔴 bug: user can be null after .find(). Add guard before .email.`
+
+❌ "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
+
+✅ `L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.`
+
+❌ "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
+
+✅ `L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).`
+
+## Auto-Clarity
+
+Drop terse mode for: security findings (CVE-class bugs need full explanation + reference), architectural disagreements (need rationale, not just a one-liner), and onboarding contexts where the author is new and needs the "why". In those cases write a normal paragraph, then resume terse for the rest.
+
+## Boundaries
+
+Reviews only — does not write the code fix, does not approve/request-changes, does not run linters. Output the comment(s) ready to paste into the PR. "stop caveman-review" or "normal mode": revert to verbose review style.

package/src/frontend-design/SKILL.md

@@ -1,60 +1,60 @@
----
-name: frontend-design
-description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
----
-
-This skill guides the coding agent in creating distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
-
-The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
-
-## Tool Compatibility
-
-- Keep instructions tool-agnostic and avoid provider-specific wording.
-- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
-
-## Design Thinking
-
-Before coding, understand the context and commit to a BOLD aesthetic direction:
-
-- **Purpose**: What problem does this interface solve? Who uses it?
-- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
-- **Constraints**: Technical requirements (framework, performance, accessibility).
-- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
-
-**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
-
-Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
-
-- Production-grade and functional
-- Visually striking and memorable
-- Cohesive with a clear aesthetic point-of-view
-- Meticulously refined in every detail
-
-## Frontend Aesthetics Guidelines
-
-Focus on:
-
-- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
-- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
-- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
-- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
-- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
-
-NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
-
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
-
-**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
-
-## Execution Guidance
-
-When applying this skill:
-
-- Build the requested interface directly instead of stopping at ideas or mock descriptions.
-- Preserve the existing design system, component patterns, and frontend architecture when working inside an established codebase.
-- Use the strongest visual direction that still fits the product and the repository's technical constraints.
-- Refine the result for both desktop and mobile instead of treating responsiveness as a follow-up.
-- Prefer modern, production-ready framework patterns already present in the codebase instead of introducing novelty for its own sake.
-- Push toward concrete design decisions, polished implementation details, and cohesive execution rather than generic safe choices.
-
-Remember: strong creative results come from a clear aesthetic direction and enough room to execute it with conviction. Do not hold back; think outside the box and commit fully to a distinctive vision.
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+---
+
+This skill guides the coding agent in creating distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Tool Compatibility
+
+- Keep instructions tool-agnostic and avoid provider-specific wording.
+- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+## Execution Guidance
+
+When applying this skill:
+
+- Build the requested interface directly instead of stopping at ideas or mock descriptions.
+- Preserve the existing design system, component patterns, and frontend architecture when working inside an established codebase.
+- Use the strongest visual direction that still fits the product and the repository's technical constraints.
+- Refine the result for both desktop and mobile instead of treating responsiveness as a follow-up.
+- Prefer modern, production-ready framework patterns already present in the codebase instead of introducing novelty for its own sake.
+- Push toward concrete design decisions, polished implementation details, and cohesive execution rather than generic safe choices.
+
+Remember: strong creative results come from a clear aesthetic direction and enough room to execute it with conviction. Do not hold back; think outside the box and commit fully to a distinctive vision.

package/src/subagent-specialist/SKILL.md

@@ -1,226 +1,226 @@
----
-name: subagent-specialist
-description: Specialist workflow for planning, dispatching, reviewing, and integrating delegated workers. Use for parallelizable work, independent implementation tasks, multiple unrelated bug investigations, or quality-focused implementer + spec-review + code-review workflows.
----
-
-# Subagent Specialist
-
-## Overview
-
-Use fresh subagents as isolated workers while the main agent stays responsible for decomposition, context curation, coordination, and integration. This skill merges two patterns into one operating guide: structured per-task execution with review gates, and parallel dispatch for independent domains.
-
-## Core Principles
-
-- Default to isolated context. Give each subagent only the task-local context it needs.
-- Keep the controller responsible for planning, sequencing, tool strategy, and final integration.
-- Use one subagent per task or per independent problem domain.
-- Prefer explicit scope, constraints, and deliverables over open-ended prompts.
-- Review actual artifacts, not just the subagent's report.
-- Preserve the controller's context window for orchestration work.
-
-## Tool Compatibility
-
-- Keep instructions tool-agnostic and avoid provider-specific wording.
-- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
-
-## Delegation Lifecycle
-
-- Use the host environment's delegation mechanism to start a fresh worker when isolated execution is helpful.
-- Prefer isolated, task-local context over copying the full session unless the task genuinely depends on broader context.
-- Reuse the same worker for follow-up work only when it already holds the right local context and reuse reduces setup cost.
-- Wait for worker results only when the next critical-path step depends on them.
-- End or discard workers that are no longer useful, according to the host environment's workflow.
-- Respect the host environment's delegation policy. If the environment only allows delegated workers after explicit user permission, do not bypass that rule.
-- Adapt to the host's actual capabilities. Do not assume support for background workers, message passing, context forking, or explicit worker shutdown unless the environment provides them.
-
-## Choose the Pattern
-
-Use the structured per-task workflow when:
-
-- you already have a plan or a clearly bounded task list
-- tasks can be executed one at a time in the current session
-- you want strong quality gates after each implementation step
-
-Use parallel dispatch when:
-
-- 2 or more tasks, failures, or investigations are truly independent
-- each workstream can be understood without hidden context from the others
-- the agents will not collide on the same files, resources, or unresolved design decisions
-
-Do local exploration first instead of dispatching immediately when:
-
-- the problem is still ambiguous
-- failures are probably symptoms of the same root cause
-- the work depends on one shared architectural decision that has not been made yet
-- multiple agents would compete for the same write scope
-
-## Workflow A: Structured Task Execution
-
-### 1. Prepare Once
-
-- Read the plan once.
-- Extract each task's full text, acceptance criteria, dependencies, and scene-setting context.
-- Track the tasks in the session plan tracker so the controller, not the subagents, owns the global picture.
-- Do not make each subagent rediscover the plan from scratch.
-
-### 2. Dispatch One Implementer
-
-- Give the full task text directly.
-- Include architectural context, constraints, working directory, and expected report format.
-- Tell the implementer to ask questions before coding if anything is unclear.
-- Prefer reusing the same implementer for follow-up fixes if the review loop stays on the same task.
-
-For the prompt structure, read [references/implementer-prompt.md](references/implementer-prompt.md).
-
-### 3. Handle Implementer Status Correctly
-
-Implementers should report one of four statuses:
-
-- `DONE`: Proceed to spec compliance review.
-- `DONE_WITH_CONCERNS`: Read the concerns before review. Resolve correctness or scope doubts before moving on.
-- `NEEDS_CONTEXT`: Provide the missing information and re-dispatch.
-- `BLOCKED`: Change something real before retrying. Add context, break up the task, choose a stronger execution profile, or escalate to the user.
-
-Never ignore a subagent that says it is stuck. If it reported `BLOCKED`, the setup, context, or task shape needs to change.
-
-### 4. Run Spec Compliance Review First
-
-- Verify what was requested against the actual code.
-- Check for missing requirements.
-- Check for over-building and extra features.
-- Check for misunderstandings of the requested behavior.
-
-Do not start code quality review until spec compliance is clear.
-
-For the reviewer template, read [references/spec-reviewer-prompt.md](references/spec-reviewer-prompt.md).
-
-### 5. Run Code Quality Review Second
-
-- Review maintainability, decomposition, test quality, and fit with the codebase.
-- Check whether the change created unnecessarily large or tangled files.
-- Check whether the implementation followed the intended structure.
-
-For the reviewer template, read [references/code-quality-reviewer-prompt.md](references/code-quality-reviewer-prompt.md).
-
-### 6. Fix and Re-Review in Loops
-
-- If a reviewer finds issues, send the findings back to the implementer.
-- Re-run the same review after the fixes land.
-- Do not move to the next task while review issues are still open.
-- Do not let implementer self-review replace an actual reviewer pass.
-
-### 7. Close the Task Only When Both Gates Pass
-
-- Mark the task complete only after spec compliance and code quality are both clear.
-- After all tasks are done, run one final holistic review or verification pass across the full change.
-
-## Workflow B: Parallel Dispatch for Independent Domains
-
-### 1. Group Work by Independent Domain
-
-Good candidates:
-
-- different failing test files with unrelated root causes
-- separate subsystems
-- bounded implementation slices with disjoint write scopes
-
-Bad candidates:
-
-- failures likely caused by one shared bug
-- tasks touching the same core files or the same unresolved design decision
-- work that depends on shared mutable state or one ordered sequence of changes
-
-### 2. Give Each Agent One Domain Only
-
-Each parallel prompt should include:
-
-- exact scope
-- raw failure evidence or task text
-- constraints on what not to change
-- expected output
-
-For a reusable template, read [references/parallel-investigator-prompt.md](references/parallel-investigator-prompt.md).
-
-### 3. Dispatch Concurrently
-
-- Run one subagent per independent domain.
-- Keep the scopes narrow.
-- While the subagents run, continue with non-overlapping controller work instead of waiting by reflex.
-
-### 4. Review and Integrate Carefully
-
-When results come back:
-
-- read each summary
-- inspect file overlap or conceptual conflicts
-- integrate the changes carefully
-- run the combined verification
-
-If the domains turn out not to be independent, stop treating them as parallel work and recombine the investigation.
-
-## Hybrid Pattern
-
-Use parallel dispatch at the top level and the structured review loop inside each workstream when the work is large enough to justify it. A typical example is three unrelated bug clusters investigated in parallel, where each accepted fix still goes through spec review and code quality review before final integration.
-
-## Execution Profile Selection
-
-- Use a lightweight execution profile for mechanical, well-specified tasks touching 1 or 2 files.
-- Use a standard execution profile for debugging, integration work, or multi-file implementation.
-- Use the strongest available execution profile for architecture, task decomposition, and critical reviews.
-
-Signals that you should increase execution depth:
-
-- ambiguous requirements
-- many interacting files
-- cross-cutting architectural impact
-- repeated failures after a reasonable attempt
-
-## Prompt Construction Rules
-
-- Be specific about scope.
-- Paste the relevant task text or failure evidence.
-- Provide enough context to avoid blind guessing.
-- State constraints explicitly.
-- Tell the subagent what to return.
-- Prefer raw artifacts over your diagnosis when asking for validation or review.
-- Do not leak the intended answer into reviewer prompts.
-
-## Advantages and Costs
-
-Advantages:
-
-- fresh context per task keeps subagents focused
-- the controller keeps the big picture instead of drowning in implementation detail
-- questions surface early, before the subagent builds the wrong thing
-- review gates catch under-building, over-building, and maintainability problems sooner
-- parallel investigations can collapse multi-hour debugging into one coordination pass
-
-Costs:
-
-- more setup work from the controller
-- more subagent invocations
-- more review iterations
-- more integration discipline required when multiple workstreams return together
-
-The cost is usually worth paying when the alternative is broad context pollution, slow sequential debugging, or late discovery of quality problems.
-
-## Red Flags
-
-- Do not start implementation on `main` or `master` without explicit user consent.
-- Do not skip spec compliance review.
-- Do not run code quality review before spec compliance passes.
-- Do not move to the next task while review issues are still open.
-- Do not tell a subagent to "fix everything."
-- Do not dispatch multiple coding subagents against the same write scope unless the integration plan is explicit.
-- Do not ignore a subagent that reports `BLOCKED`.
-- Do not replace actual review with implementer self-review.
-- Do not trust an implementer or reviewer claim without checking the artifacts they produced.
-
-## Reference Templates
-
-Read these only when needed:
-
-- [references/implementer-prompt.md](references/implementer-prompt.md): implementation-worker prompt
-- [references/spec-reviewer-prompt.md](references/spec-reviewer-prompt.md): spec-compliance review prompt
-- [references/code-quality-reviewer-prompt.md](references/code-quality-reviewer-prompt.md): maintainability and quality review prompt
-- [references/parallel-investigator-prompt.md](references/parallel-investigator-prompt.md): focused prompt for independent parallel investigations
+---
+name: subagent-specialist
+description: Specialist workflow for planning, dispatching, reviewing, and integrating delegated workers. Use for parallelizable work, independent implementation tasks, multiple unrelated bug investigations, or quality-focused implementer + spec-review + code-review workflows.
+---
+
+# Subagent Specialist
+
+## Overview
+
+Use fresh subagents as isolated workers while the main agent stays responsible for decomposition, context curation, coordination, and integration. This skill merges two patterns into one operating guide: structured per-task execution with review gates, and parallel dispatch for independent domains.
+
+## Core Principles
+
+- Default to isolated context. Give each subagent only the task-local context it needs.
+- Keep the controller responsible for planning, sequencing, tool strategy, and final integration.
+- Use one subagent per task or per independent problem domain.
+- Prefer explicit scope, constraints, and deliverables over open-ended prompts.
+- Review actual artifacts, not just the subagent's report.
+- Preserve the controller's context window for orchestration work.
+
+## Tool Compatibility
+
+- Keep instructions tool-agnostic and avoid provider-specific wording.
+- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
+
+## Delegation Lifecycle
+
+- Use the host environment's delegation mechanism to start a fresh worker when isolated execution is helpful.
+- Prefer isolated, task-local context over copying the full session unless the task genuinely depends on broader context.
+- Reuse the same worker for follow-up work only when it already holds the right local context and reuse reduces setup cost.
+- Wait for worker results only when the next critical-path step depends on them.
+- End or discard workers that are no longer useful, according to the host environment's workflow.
+- Respect the host environment's delegation policy. If the environment only allows delegated workers after explicit user permission, do not bypass that rule.
+- Adapt to the host's actual capabilities. Do not assume support for background workers, message passing, context forking, or explicit worker shutdown unless the environment provides them.
+
+## Choose the Pattern
+
+Use the structured per-task workflow when:
+
+- you already have a plan or a clearly bounded task list
+- tasks can be executed one at a time in the current session
+- you want strong quality gates after each implementation step
+
+Use parallel dispatch when:
+
+- 2 or more tasks, failures, or investigations are truly independent
+- each workstream can be understood without hidden context from the others
+- the agents will not collide on the same files, resources, or unresolved design decisions
+
+Do local exploration first instead of dispatching immediately when:
+
+- the problem is still ambiguous
+- failures are probably symptoms of the same root cause
+- the work depends on one shared architectural decision that has not been made yet
+- multiple agents would compete for the same write scope
+
+## Workflow A: Structured Task Execution
+
+### 1. Prepare Once
+
+- Read the plan once.
+- Extract each task's full text, acceptance criteria, dependencies, and scene-setting context.
+- Track the tasks in the session plan tracker so the controller, not the subagents, owns the global picture.
+- Do not make each subagent rediscover the plan from scratch.
+
+### 2. Dispatch One Implementer
+
+- Give the full task text directly.
+- Include architectural context, constraints, working directory, and expected report format.
+- Tell the implementer to ask questions before coding if anything is unclear.
+- Prefer reusing the same implementer for follow-up fixes if the review loop stays on the same task.
+
+For the prompt structure, read [references/implementer-prompt.md](references/implementer-prompt.md).
+
+### 3. Handle Implementer Status Correctly
+
+Implementers should report one of four statuses:
+
+- `DONE`: Proceed to spec compliance review.
+- `DONE_WITH_CONCERNS`: Read the concerns before review. Resolve correctness or scope doubts before moving on.
+- `NEEDS_CONTEXT`: Provide the missing information and re-dispatch.
+- `BLOCKED`: Change something real before retrying. Add context, break up the task, choose a stronger execution profile, or escalate to the user.
+
+Never ignore a subagent that says it is stuck. If it reported `BLOCKED`, the setup, context, or task shape needs to change.
+
+### 4. Run Spec Compliance Review First
+
+- Verify what was requested against the actual code.
+- Check for missing requirements.
+- Check for over-building and extra features.
+- Check for misunderstandings of the requested behavior.
+
+Do not start code quality review until spec compliance is clear.
+
+For the reviewer template, read [references/spec-reviewer-prompt.md](references/spec-reviewer-prompt.md).
+
+### 5. Run Code Quality Review Second
+
+- Review maintainability, decomposition, test quality, and fit with the codebase.
+- Check whether the change created unnecessarily large or tangled files.
+- Check whether the implementation followed the intended structure.
+
+For the reviewer template, read [references/code-quality-reviewer-prompt.md](references/code-quality-reviewer-prompt.md).
+
+### 6. Fix and Re-Review in Loops
+
+- If a reviewer finds issues, send the findings back to the implementer.
+- Re-run the same review after the fixes land.
+- Do not move to the next task while review issues are still open.
+- Do not let implementer self-review replace an actual reviewer pass.
+
+### 7. Close the Task Only When Both Gates Pass
+
+- Mark the task complete only after spec compliance and code quality are both clear.
+- After all tasks are done, run one final holistic review or verification pass across the full change.
+
+## Workflow B: Parallel Dispatch for Independent Domains
+
+### 1. Group Work by Independent Domain
+
+Good candidates:
+
+- different failing test files with unrelated root causes
+- separate subsystems
+- bounded implementation slices with disjoint write scopes
+
+Bad candidates:
+
+- failures likely caused by one shared bug
+- tasks touching the same core files or the same unresolved design decision
+- work that depends on shared mutable state or one ordered sequence of changes
+
+### 2. Give Each Agent One Domain Only
+
+Each parallel prompt should include:
+
+- exact scope
+- raw failure evidence or task text
+- constraints on what not to change
+- expected output
+
+For a reusable template, read [references/parallel-investigator-prompt.md](references/parallel-investigator-prompt.md).
+
+### 3. Dispatch Concurrently
+
+- Run one subagent per independent domain.
+- Keep the scopes narrow.
+- While the subagents run, continue with non-overlapping controller work instead of waiting by reflex.
+
+### 4. Review and Integrate Carefully
+
+When results come back:
+
+- read each summary
+- inspect file overlap or conceptual conflicts
+- integrate the changes carefully
+- run the combined verification
+
+If the domains turn out not to be independent, stop treating them as parallel work and recombine the investigation.
+
+## Hybrid Pattern
+
+Use parallel dispatch at the top level and the structured review loop inside each workstream when the work is large enough to justify it. A typical example is three unrelated bug clusters investigated in parallel, where each accepted fix still goes through spec review and code quality review before final integration.
+
+## Execution Profile Selection
+
+- Use a lightweight execution profile for mechanical, well-specified tasks touching 1 or 2 files.
+- Use a standard execution profile for debugging, integration work, or multi-file implementation.
+- Use the strongest available execution profile for architecture, task decomposition, and critical reviews.
+
+Signals that you should increase execution depth:
+
+- ambiguous requirements
+- many interacting files
+- cross-cutting architectural impact
+- repeated failures after a reasonable attempt
+
+## Prompt Construction Rules
+
+- Be specific about scope.
+- Paste the relevant task text or failure evidence.
+- Provide enough context to avoid blind guessing.
+- State constraints explicitly.
+- Tell the subagent what to return.
+- Prefer raw artifacts over your diagnosis when asking for validation or review.
+- Do not leak the intended answer into reviewer prompts.
+
+## Advantages and Costs
+
+Advantages:
+
+- fresh context per task keeps subagents focused
+- the controller keeps the big picture instead of drowning in implementation detail
+- questions surface early, before the subagent builds the wrong thing
+- review gates catch under-building, over-building, and maintainability problems sooner
+- parallel investigations can collapse multi-hour debugging into one coordination pass
+
+Costs:
+
+- more setup work from the controller
+- more subagent invocations
+- more review iterations
+- more integration discipline required when multiple workstreams return together
+
+The cost is usually worth paying when the alternative is broad context pollution, slow sequential debugging, or late discovery of quality problems.
+
+## Red Flags
+
+- Do not start implementation on `main` or `master` without explicit user consent.
+- Do not skip spec compliance review.
+- Do not run code quality review before spec compliance passes.
+- Do not move to the next task while review issues are still open.
+- Do not tell a subagent to "fix everything."
+- Do not dispatch multiple coding subagents against the same write scope unless the integration plan is explicit.
+- Do not ignore a subagent that reports `BLOCKED`.
+- Do not replace actual review with implementer self-review.
+- Do not trust an implementer or reviewer claim without checking the artifacts they produced.
+
+## Reference Templates
+
+Read these only when needed:
+
+- [references/implementer-prompt.md](references/implementer-prompt.md): implementation-worker prompt
+- [references/spec-reviewer-prompt.md](references/spec-reviewer-prompt.md): spec-compliance review prompt
+- [references/code-quality-reviewer-prompt.md](references/code-quality-reviewer-prompt.md): maintainability and quality review prompt
+- [references/parallel-investigator-prompt.md](references/parallel-investigator-prompt.md): focused prompt for independent parallel investigations