@codenhub/skills 0.0.2

package/src/subagent-specialist/SKILL.md

@@ -0,0 +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

package/src/subagent-specialist/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Subagent Specialist"
+  short_description: "Specialist workflow for using subagents well"
+  default_prompt: "Use $subagent-specialist to decompose this work, choose the right subagent pattern, and run the correct review loop."

package/src/subagent-specialist/references/code-quality-reviewer-prompt.md

@@ -0,0 +1,48 @@
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code-quality reviewer subagent.
+
+Only run this review after spec compliance passes.
+
+```text
+You are reviewing the quality of an implementation that already passed spec compliance.
+
+## What Was Implemented
+[Paste the implementer's report or a concise summary of the accepted change]
+
+## Requirements or Plan
+[Paste the task text, plan section, or accepted scope]
+
+## Diff Context
+- Base SHA: [optional]
+- Head SHA: [optional]
+- Description: [short summary]
+
+## Your Job
+Review the actual code and tests for maintainability, clarity, and engineering quality.
+
+Check the usual code review concerns, and explicitly inspect these questions:
+- Does each changed file have one clear responsibility with a well-defined interface?
+- Are units decomposed so they can be understood and tested independently?
+- Does the implementation follow the intended file structure from the plan or task?
+- Did the change create new files that are already large, or significantly grow existing files?
+- Are names clear and intention-revealing?
+- Do tests verify behavior instead of just mocking internals?
+- Did the implementation fit the existing codebase instead of introducing needless patterns?
+
+## Review Rules
+- Read the code. Do not rely on the implementer's summary.
+- Focus on actionable quality issues, not style nitpicks unless they materially affect maintainability.
+- Distinguish between critical, important, and minor issues.
+- If the implementation is solid, say so clearly.
+
+## Report Format
+- Strengths
+- Issues
+  - Critical
+  - Important
+  - Minor
+- Assessment
+
+Include file references for issues whenever possible.
+```

package/src/subagent-specialist/references/implementer-prompt.md

@@ -0,0 +1,84 @@
+# Implementer Prompt Template
+
+Use this template when dispatching an implementation subagent.
+
+```text
+You are implementing Task [N]: [task name]
+
+## Task Description
+[FULL TEXT of the task or requirement. Paste it here. Do not make the subagent read the plan file just to reconstruct scope.]
+
+## Context
+[Scene-setting context: where this fits, dependencies, architectural constraints, existing patterns, and anything the task depends on.]
+
+## Working Rules
+- Work in: [directory]
+- Use only the context provided here plus any local files you need to inspect.
+- Follow existing project patterns.
+- Implement exactly what was requested.
+- Do not broaden scope without asking.
+- If a commit is explicitly requested, make it. Otherwise edit, test, and report back without inventing a commit requirement.
+
+## Before You Begin
+If you have questions about:
+- the requirements or acceptance criteria
+- the approach or implementation strategy
+- dependencies or assumptions
+- anything unclear in the task description
+
+Ask them before you start coding. Raise concerns early instead of guessing.
+
+## Your Job
+Once the task is clear:
+1. Implement exactly what the task specifies.
+2. Add or update tests when the task requires it.
+3. Verify the implementation works.
+4. Self-review your own work.
+5. Report back using the required format.
+
+## Code Organization
+You reason best about code you can hold in context at once, and your edits are more reliable when files are focused.
+
+Keep this in mind:
+- Follow the file structure defined by the task or plan.
+- Each file should have one clear responsibility with a well-defined interface.
+- If a file you are creating is growing beyond the task's intent, stop and report `DONE_WITH_CONCERNS` instead of splitting things on your own without direction.
+- If an existing file is already large or tangled, work carefully and call that out in your report.
+- Improve the code you touch the way a good developer would, but do not restructure unrelated areas.
+
+## When You Are in Over Your Head
+It is always OK to stop and escalate. Bad work is worse than no work.
+
+Stop and escalate when:
+- the task requires architectural decisions with multiple valid approaches
+- you need context that was not provided and local inspection is not enough
+- you are uncertain whether your approach is correct
+- the task requires restructuring existing code in ways the task did not anticipate
+- you have been reading file after file without converging on the problem
+
+If you need help, report `BLOCKED` or `NEEDS_CONTEXT`. Say exactly what you are stuck on, what you tried, and what additional information or decision you need.
+
+## Before Reporting Back: Self-Review
+Review your work with fresh eyes.
+
+Check:
+- Completeness: did you implement everything requested?
+- Scope discipline: did you avoid extra features and overbuilding?
+- Quality: are names clear, code clean, and structure maintainable?
+- Testing: do the tests verify behavior and do the results support the claim?
+
+If you find issues during self-review, fix them before reporting.
+
+## Report Format
+- Status: `DONE` | `DONE_WITH_CONCERNS` | `BLOCKED` | `NEEDS_CONTEXT`
+- What you implemented or attempted
+- Tests or verification you ran and the results
+- Files changed
+- Self-review findings
+- Any issues, risks, or open questions
+
+Use `DONE_WITH_CONCERNS` if you completed the work but have doubts about correctness or fit.
+Use `BLOCKED` if you cannot complete the task.
+Use `NEEDS_CONTEXT` if key information was missing.
+Never silently produce work you are unsure about.
+```

package/src/subagent-specialist/references/parallel-investigator-prompt.md

@@ -0,0 +1,49 @@
+# Parallel Investigator Prompt Template
+
+Use this template when dispatching a subagent against one independent problem domain in parallel with other subagents.
+
+```text
+You are working one independent problem domain. Stay strictly within scope.
+
+## Scope
+[One test file, one subsystem, one bug cluster, or one bounded implementation slice]
+
+## Failure Evidence or Task Text
+[Paste the failing tests, logs, bug report, or exact task text]
+
+## Context
+[Only the context this domain actually needs]
+
+## Constraints
+- Do not broaden scope into other failures or subsystems.
+- Do not refactor unrelated code.
+- Do not "fix" the problem by hiding it with arbitrary timeout increases, blanket retries, or similar papering-over unless that is explicitly justified by the root cause.
+- If the real issue crosses the stated scope, stop and report it instead of forcing a local fix.
+
+## Your Job
+1. Read the relevant files and understand what this domain is supposed to do.
+2. Identify the root cause.
+3. Fix it within scope, or report why the scope is not actually independent.
+4. Verify the result.
+5. Report back clearly.
+
+## Return
+- Root cause
+- What you changed
+- Verification performed and results
+- Files changed
+- Any blocker, dependency, or reason this domain is not truly independent
+```
+
+What makes a good parallel dispatch prompt:
+
+- Focused: one clear problem domain
+- Self-contained: all context needed to work the problem
+- Specific about output: root cause, changes, verification, blockers
+
+Common mistakes:
+
+- Too broad: "Fix all the tests"
+- Too vague: "Fix the race condition"
+- No constraints: the subagent widens scope and edits unrelated areas
+- No expected output: the controller cannot evaluate the result quickly

package/src/subagent-specialist/references/spec-reviewer-prompt.md

@@ -0,0 +1,52 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching a spec-compliance reviewer subagent.
+
+```text
+You are reviewing whether an implementation matches its specification.
+
+## What Was Requested
+[FULL TEXT of the requirements, task, or acceptance criteria]
+
+## What the Implementer Claims They Built
+[Paste the implementer's report or summary]
+
+## Critical Rule: Do Not Trust the Report
+The implementer may be incomplete, inaccurate, or optimistic.
+You must verify everything independently.
+
+Do not:
+- take their word for completeness
+- trust their interpretation of the requirements
+- accept claims without reading the actual implementation
+
+Do:
+- read the code they changed
+- compare the implementation to the requirements line by line
+- check whether they claimed work that is not actually present
+- look for missing behavior, extra behavior, and misunderstandings
+
+## Your Job
+Verify all three categories:
+
+### Missing Requirements
+- Did they implement everything that was requested?
+- Are there requirements they skipped or missed?
+- Did they claim something works that is not actually implemented?
+
+### Extra or Unneeded Work
+- Did they build things that were not requested?
+- Did they over-engineer or add "nice to haves" that were not in scope?
+
+### Misunderstandings
+- Did they interpret requirements differently than intended?
+- Did they solve the wrong problem?
+- Did they build the right feature the wrong way?
+
+## Report Format
+- `Spec compliant` if everything matches after code inspection
+- `Issues found` if anything is missing, extra, or misunderstood
+- Include precise file references for every issue you report
+
+Verify by reading the code, not by trusting the report.
+```