opencode-agenthub 0.1.0

package/dist/skills/hr-assembly/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: hr-assembly
+description: "Adapt approved candidates into staged Agent Hub packages for test and promote"
+audience: "HR adapter subagent"
+license: MIT
+compatibility: "opencode >= 0.1"
+metadata:
+  domain: agent-assembly
+  version: "1.0"
+---
+
+# HR Assembly Protocol
+
+## Purpose
+
+Generate a staged package under `$HR_HOME/staging/<package-id>/` without mutating imported home assets.
+
+## Required Package Layout
+
+```text
+$HR_HOME/staging/<package-id>/
+  handoff.json
+  promotion-memo.md
+  worker-card.json
+  agenthub-home/
+    bundles/
+    profiles/
+    souls/ or skills/
+    mcp/
+    mcp-servers/
+```
+
+## Staging Rules
+
+- For **pure-soul agents**, stage a soul file plus bundle and profile.
+- For **mixed soul+skill agents**, preserve specialized scope and prefer `subagent` mode unless the user explicitly wants otherwise.
+- For **skill assets**, stage a skill directory plus a bundle/profile that preserves host selection requirements.
+- If a staged bundle references a skill, stage that skill directory under `agenthub-home/skills/<skill-name>/` unless the package is explicitly documented as depending on a separately imported prerequisite package.
+- If a staged bundle references an MCP tool, stage the matching `agenthub-home/mcp/<name>.json` registration file and the referenced `agenthub-home/mcp-servers/` implementation files. If the command relies on `mcp-servers/node_modules/...`, also stage `mcp-servers/package.json` so dependencies can be installed on import/promote.
+- Do **not** invent runtime semantics in bundle `metadata`. Keys such as `optional_skills` or `runtime_conditional_skills` are notes only and are not valid substitutes for staged skills or real platform behavior.
+- Prefer namespaced bundle/soul/profile names for adapted teams or rewrites so the package does not overwrite shared starter assets like `plan`, `build`, or `explore` unless the human explicitly requests replacement.
+- If a staged profile sets `defaultAgent`, it must use the staged bundle's `agent.name` value, not the bundle filename. This matters when bundle filenames are namespaced but `agent.name` is shorter.
+- Before final assembly, confirm whether the operator wants to keep default opencode agents such as `general`, `explore`, `plan`, and `build`. If not, the staged profile must set `"nativeAgentPolicy": "team-only"`. This suppresses host native agent merges and emits `disable: true` overrides for default opencode agents that are not supplied by the staged team itself.
+- Before final assembly, confirm whether the promoted profile should become the default personal profile for future bare `agenthub start` runs. Record that choice in `handoff.json` under `promotion_preferences.set_default_profile`.
+- If the operator specifies a model variant such as `xhigh`, `high`, or `thinking`, store it canonically as `agent.model: "provider/model"` plus `agent.variant: "..."`. For backward compatibility, combined strings like `"provider/model xhigh"` may still be accepted on read, but staged output should prefer the split form.
+- The package must be promotable by:
+
+```bash
+agenthub promote <package-id>
+```
+
+- Advanced/manual fallback remains:
+
+```bash
+agenthub hub-import --source <package_root>/agenthub-home
+```
+
+- Standard handoff must tell the operator to test the staged team before promote with:
+
+```bash
+agenthub hr <profile-name>
+```
+
+- That test path must be described as a workspace runtime test that does not modify the operator's personal home.
+- Standard handoff must also say that the same staged profile can be used in another workspace before promote by running the same command there.
+- Promote must be described as the step that imports the package into the personal home so future bare `agenthub start` runs can use it.
+
+## Required Handoff Fields
+
+- `schema_version`
+- `promotion_id`
+- `worker_id`
+- `asset_kind`
+- `agent_class`
+- `deployment_role`
+- `target_profile`
+- `proposed_profile`
+- `package_layout_version`
+- `artifacts`
+- `generated_at`
+- `promotion_preferences`
+- `operator_instructions`
+- `host_requirements` when MCP tools or other host-side dependencies exist
+
+## Required Handoff Structure
+
+`operator_instructions` must include:
+
+- `test_current_workspace`
+- `use_in_another_workspace`
+- `promote`
+- `advanced_import`
+
+If MCP tools are referenced, `artifacts` must also include:
+
+- `mcp_configs`
+- `mcp_servers`
+
+If MCP tools are referenced, `host_requirements` must explicitly state whether MCP servers are bundled and what runtime/environment dependencies remain on the host.
+
+## Soul Adaptation Rule
+
+When staging a **pure-soul** agent, the adapted soul must explicitly list:
+
+- the intended skill set
+- the intended tool set
+- the agent's boundaries
+
+This prevents vague souls that only describe personality.
+
+## Mandatory Validation
+
+Before you present a staged package as ready, run all of the following from the workspace root:
+
+```bash
+python3 $HR_HOME/bin/vendor_stage_skills.py $HR_HOME/staging/<package-id>
+python3 $HR_HOME/bin/vendor_stage_mcps.py $HR_HOME/staging/<package-id>
+python3 $HR_HOME/bin/validate_staged_package.py $HR_HOME/staging/<package-id>
+```
+
+If validation fails, the package is not ready.

package/dist/skills/hr-final-check/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: hr-final-check
+description: "Final package QA checklist for clarity, safety, and import readiness"
+audience: "HR verifier subagent"
+license: MIT
+compatibility: "opencode >= 0.1"
+metadata:
+  domain: agent-qa
+  version: "1.0"
+---
+
+# HR Final Check Protocol
+
+## Purpose
+
+Verify that a staged package is understandable and safe before the human operator approves it.
+
+## Required Checklist Sections
+
+1. package completeness
+2. provenance completeness
+3. bundle/profile coherence
+4. soul clarity
+5. skill clarity
+6. MCP completeness and host-runtime clarity
+7. deployment role correctness
+8. unresolved risks / open decisions
+9. import-root and assemble-only validation
+10. runtime/default-profile confirmation
+11. protocol-compliance checkpoints
+
+## Clarity Definitions
+
+### Subagent description clear
+
+All of the following must be true:
+
+- the description states what the subagent does
+- the description states its scope or boundary
+- the description does not overlap ambiguously with another staged subagent
+
+### Skill description clear
+
+All of the following must be true:
+
+- the description states when to use the skill
+- the description states what procedure it performs
+- the description states what output or result the user/operator should expect
+
+## Final Output
+
+Write `final-checklist.md` and end with a human-facing status:
+
+- `READY FOR HUMAN CONFIRMATION`
+- `READY WITH CAVEATS`
+- `NOT READY`
+
+## Compact Checklist Shape
+
+Keep `final-checklist.md` compact and explicit. Use this shape:
+
+```text
+## Final Checklist - <package-id>
+| Check | Result |
+|---|---|
+| import root is agenthub-home/ | pass/fail |
+| no unsupported concepts | pass/fail |
+| soul skill/tool sets declared | pass/fail |
+| descriptions are operator-readable | pass/fail |
+| MCP registrations resolve to staged servers or blocker | pass/fail |
+| handoff clearly separates test/use/promote | pass/fail |
+| model preferences were explicitly collected | pass/fail |
+| final names were user-confirmed | pass/fail |
+| specialized work was delegated | pass/fail |
+| staged model ids validated against synced catalog | pass/fail |
+| profile defaultAgent matches bundle agent.name | pass/fail |
+| default opencode agent policy confirmed | pass/fail |
+| default profile on promote confirmed | pass/fail |
+| no host project mutations | pass/fail |
+overall: READY FOR HUMAN CONFIRMATION | READY WITH CAVEATS | NOT READY
+blocker: <description or none>
+```
+
+## Hard Validation Rule
+
+The package cannot be marked ready unless the verifier confirms:
+
+1. the handoff shows: (a) staging path, (b) test command `agenthub hr <profile>`, (c) promote command `agenthub promote <package-id>`
+2. the manual import fallback points to `<package-root>/agenthub-home` and is described as advanced/manual only
+3. all referenced skills either exist inside the staged `skills/` directory or are explicitly rejected as missing blockers
+4. `python3 $HR_HOME/bin/validate_staged_package.py $HR_HOME/staging/<package-id>` passes
+5. the package explicitly records whether default opencode agents are kept or hidden, and whether the promoted profile should become the default profile
+6. staged model ids either match the synced catalog exactly or are called out as blockers/caveats for human review
+7. if any bundle references MCP tools, the staged package includes the referenced `mcp/*.json` files, the required `mcp-servers/` implementation files, and `mcp-servers/package.json` when runtime dependencies are needed
+8. the handoff clearly shows how to test/use the staged profile in a workspace before promote, and promote is not described as mandatory for workspace use
+9. if a profile sets `defaultAgent`, that value exactly matches one of the staged bundles' `agent.name` values (not just the bundle filename)
+
+If bundle metadata contains fake runtime keys such as `optional_skills` or `runtime_conditional_skills`, mark the package `NOT READY` until they are removed or rewritten as plain documentation outside runtime bundle semantics.

package/dist/skills/hr-review/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: hr-review
+description: "Review local inventory workers for security, compatibility, testing readiness, and description clarity"
+audience: "HR evaluator subagent"
+license: MIT
+compatibility: "opencode >= 0.1"
+metadata:
+  domain: agent-review
+  version: "1.0"
+---
+
+# HR Review Protocol
+
+## Purpose
+
+Update a local inventory worker card and write review notes for a single candidate.
+
+## Output Files
+
+Read and update:
+
+- `$HR_HOME/inventory/workers/<candidate-slug>.json`
+
+Write:
+
+- `$HR_HOME/inventory/workers/<candidate-slug>.review.md`
+
+## Compact Review Shape
+
+Keep `<candidate-slug>.review.md` compact and field-based. Use this shape:
+
+```text
+## <candidate-slug> Review
+fit: <high|medium|low>
+agent_class: <pure-soul|mixed-soul-skill|skill>
+deployment_role: <primary-capable|subagent-preferred|skill-attachment>
+risk_tier: <low|medium|high>
+testing_readiness: <ready|partial|unclear>
+description_clarity: <clear|needs-clarification|unclear>
+gaps: <comma list or none>
+notes: <1-2 sentences>
+```
+
+## Required Worker Card Keys
+
+- `schema_version`
+- `candidate_slug`
+- `worker_id`
+- `name`
+- `summary`
+- `source_id`
+- `source_path`
+- `source_commit`
+- `inventory_status`
+- `asset_kind`
+- `agent_class`
+- `deployment_role`
+- `type`
+- `hire_shape`
+- `host_requirement`
+- `self_contained`
+- `compatibility`
+- `risk_tier`
+- `testing_readiness`
+- `description_clarity`
+- `recommended_hosts`
+- `flags`
+- `artifacts`
+
+## Inventory Status Values
+
+- `draft`
+- `available`
+- `retired`
+
+Use `draft` when first discovered or still incomplete, `available` when reviewed and fit for staffing, and `retired` when kept for reference but excluded from staffing.
+
+## Review Dimensions
+
+1. **Provenance** — can the source be traced cleanly?
+2. **Security** — prompt injection, dangerous shell or code instructions, hidden external dependencies
+3. **Compatibility** — can this become a native Agent Hub asset without pretending it is something else?
+4. **Testing readiness** — are there enough instructions to test or verify the adapted asset?
+5. **Clarity**
+   - **subagent description clear** = the description states scope, inputs, outputs, and limits
+   - **skill description clear** = the description states trigger/use-case, procedure, and expected output
+
+Update `inventory_status` conservatively. Do not mark a worker `available` when provenance, safety, or clarity remain unresolved.
+
+## Clarity Ratings
+
+- `clear`
+- `needs-clarification`
+- `unclear`
+
+## Agent Class Rules
+
+- `pure-soul` when the candidate is primarily an identity/behavior contract and can host multiple tasks.
+- `mixed-soul-skill` when identity and specialized workflow are fused and should usually stay narrow.
+- `skill` assets are attachments and must not be upgraded into full agents without explicit adaptation work.

package/dist/skills/hr-staffing/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: hr-staffing
+description: "Build staffing plans for pure-soul agents, mixed soul+skill agents, and skill attachments"
+audience: "HR planner subagent"
+license: MIT
+compatibility: "opencode >= 0.1"
+metadata:
+  domain: agent-staffing
+  version: "1.0"
+---
+
+# HR Staffing Protocol
+
+## Purpose
+
+Produce a staffing plan that is advisory, explicit, and downstream-compatible with Agent Hub composition.
+
+## Prerequisites
+
+This skill must not be invoked until the parent HR agent has completed `Stage 1 - REQUIREMENTS` and the user has confirmed the requirements summary. If requirements are still ambiguous, return that gap to the parent instead of pretending the plan is ready.
+
+## Output Files
+
+Write the latest plan to:
+
+- `$HR_HOME/state/staffing-plans/latest.json`
+- `$HR_HOME/state/staffing-plans/latest.md`
+
+## Required Plan Structure
+
+Every staffing plan must include:
+
+- `schema_version`
+- `task_summary`
+- `recommended_team`
+- `alternatives`
+- `composition`
+- `required_skills`
+- `required_tools`
+- `suggested_model_provider`
+- `proposed_agent_models` (initial proposal only; final per-agent defaults require user confirmation later)
+- `draft_names` (draft agent names and draft profile name for user review)
+- `risks`
+- `next_action`
+
+## Compact Summary Shape
+
+Keep `latest.md` compact and field-based. Use this shape:
+
+```text
+recommended:
+- role: ... | source: ... | agent_class: ... | model: ...
+alternatives:
+- ...
+composition:
+- ...
+draft_names:
+- seat: ... | proposed_agent_name: ... | reason: ...
+- profile: ... | reason: ...
+proposed_agent_models:
+- agent: ... | model: ...
+risks:
+- ...
+next_action: ...
+```
+
+## Composition Rules
+
+For each recommended entry, specify:
+
+- `asset_kind`: `agent` or `skill`
+- `agent_class`: `pure-soul`, `mixed-soul-skill`, or `not-applicable`
+- `deployment_role`: `primary-capable`, `subagent-preferred`, or `skill-attachment`
+- `compatibility`: `native-ready`, `needs-adaptation`, or `skill-only`
+
+## Decision Rules
+
+- Prefer the smallest team that can cover planning, sourcing/exploration, implementation, audit, verification, and documentation.
+- Prefer local worker cards from `$HR_HOME/inventory/workers/` with `inventory_status = available`.
+- Treat `draft` worker cards as sourcing inputs that still need review or explicit operator acceptance.
+- Exclude `retired` worker cards from recommended staffing compositions.
+- Treat user-supplied model names as advisory until checked against `$HR_HOME/inventory/models/catalog.json` or `$HR_HOME/inventory/models/valid-model-ids.txt`. If an exact catalog match is missing, mark the proposal unresolved instead of inventing a model id.
+- If multiple valid compositions exist, present them as options rather than pretending one is certain.
+- If a skill host is unresolved, say so plainly.
+- Draft names must be treated as proposals only. The parent HR agent must show them to the user and get confirmation before adaptation starts.