feat(agents): add focused hack-branches, hack-env and hack-diagnose plugin skills

.codex/skills/hack-cli/SKILL.md

@@ -14,7 +14,7 @@ Use `hack` as the primary interface for local-first development.
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `c3c646a036aa` (version alone is not a freshness guarantee).
+- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
 
 ## Product boundary
 

.cursor/rules/hack.mdc

@@ -9,7 +9,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `c3c646a036aa` (version alone is not a freshness guarantee).
+- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
 
 ## Product boundary
 

docs/agent-guidance.md

@@ -21,7 +21,9 @@ run only `hack agent prime`. See [model-policy ownership](reference/agent-client
 | `src/agents/hack-init-skill.ts` | Thin Claude/Codex/plugin adapter that fetches onboarding guidance |
 | `src/agents/init-patterns.ts`, `init-assistant.ts` | Optional init inventory and pattern hints |
 | `src/agents/install-skill.ts`, `remote-bootstrap-skill.ts` | Plugin installation/channel selection and fresh-host/cloud setup skills |
-| `scripts/generate-agent-plugins.ts` | Portable plugin/MCP manifests, three client compatibility manifests, four skills, and Cursor rule |
+| `src/agents/focused-skills.ts` | Plugin `hack-branches`, `hack-env` and `hack-diagnose` skills, composed from canonical section ids, and the plugin `hack-cli` routing description |
+| `src/agents/error-code-reference.ts` | `hack-diagnose` error-code reference, rendered from the exported `HACK_ERROR_CODES` registry in `src/lib/cli-result.ts` |
+| `scripts/generate-agent-plugins.ts` | Portable plugin/MCP manifests, three client compatibility manifests, seven skills, and Cursor rule |
 
 The portable plugin manifest derives identity and effective OpenAI presentation
 from `.codex-plugin/plugin.json`; portable MCP derives from `.mcp.json` with an
@@ -104,6 +106,17 @@ toolchain service against its card. Every `hack` command in a fixture README
 must resolve in CLI_SPEC and name a declared service and profile. These checks
 are static: they do not start containers or qualify the runtime gates.
 
+The focused plugin skills `hack-branches`, `hack-env` and `hack-diagnose` list
+canonical section ids in `src/agents/focused-skills.ts` and carry no prose of
+their own; composition fails on an unknown id. A section with no surface tags
+renders only in the focused skills that name it. Each trigger phrase belongs to
+one plugin skill, and the plugin `hack-cli` description hands branch, env and
+diagnosis intents to them; the standalone `hack-cli` keeps broad routing because
+those installs ship no focused skills. The `hack-diagnose` error-code reference
+renders from `HACK_ERROR_CODES` in `src/lib/cli-result.ts`.
+`tests/focused-skills.test.ts` checks section ids, CLI_SPEC resolution,
+error-code parity and trigger overlap.
+
 Skill candidates and where their patterns live now:
 
 | Candidate | Decision | Patterns live in | Promotion owner and missing contract |

docs/integrations.md

@@ -68,9 +68,12 @@ trust and approval rules.
 ## Optional native plugins
 
 Hack also ships an optional native plugin for Codex, Claude Code, and Cursor in
-`plugins/hack`. It bundles four skills (`hack-cli`, `hack-init`, `hack-install`, and
-`hack-remote`), the `hack mcp serve` server, Claude primer hooks, and a Cursor rule
-that the agent can select when relevant. The
+`plugins/hack`. It bundles seven skills (`hack-cli`, the focused `hack-branches`,
+`hack-env` and `hack-diagnose`, `hack-init`, `hack-install`, and `hack-remote`), the
+`hack mcp serve` server, Claude primer hooks, and a Cursor rule that the agent can
+select when relevant. The plugin's `hack-cli` routes branch-instance, env and
+diagnosis requests to the focused skills; standalone `hack setup` installs keep the
+broad `hack-cli` skill only. The
 [agent client capability matrix](reference/agent-client-capabilities.md) records
 which of these components have been observed loading in each client.
 Install the Hack CLI first and make `hack` available on the client's PATH.
@@ -105,7 +108,7 @@ outside its local-plugin root; use a copy rather than weakening that boundary. S
 [Cursor's plugin documentation](https://cursor.com/docs/plugins) for marketplace
 and local development support in the installed client version.
 
-After installing, verify in a fresh session that all four skills are discoverable,
+After installing, verify in a fresh session that all seven skills are discoverable,
 `hack mcp serve` can initialize, and the client's hooks or rule load. A successful
 marketplace registration alone does not prove those components loaded. The plugin's
 MCP fallback is for clients without shell access; use the Hack CLI when shell is available.

docs/reference/agent-client-capabilities.md

@@ -56,7 +56,7 @@ Matrix version 1, observed 2026-10-11.
 | Capability | Meaning |
 | --- | --- |
 | Packaging | The client accepts, installs and enables the Hack plugin package in a session. |
-| Skill discovery | A fresh session discovers the plugin's bundled skills (hack-cli, hack-init, hack-install, hack-remote). |
+| Skill discovery | A fresh session discovers the plugin's bundled skills (hack-cli, hack-branches, hack-env, hack-diagnose, hack-init, hack-install, hack-remote). |
 | Hooks | The client runs plugin-shipped hooks; Hack hooks may only run `hack agent prime`. |
 | Plugin MCP | The client starts the plugin-declared `hack mcp serve` server and lists its tools. |
 | Standalone MCP | The client loads an MCP entry written by `hack mcp install` (stdio or a selected MCP bundle) without the plugin. |
@@ -117,7 +117,7 @@ owner, and none of them replaces the others. Users choose one per client.
 
 | Layout | What it contains | Authoritative owner | Installed and updated by |
 | --- | --- | --- | --- |
-| Native plugin (`plugins/hack`) | Client manifests, four skills, Claude primer hooks, Cursor rule, `hack mcp serve` declaration | `scripts/generate-agent-plugins.ts`, rendering from `src/agents/instruction-source.ts` and the skill renderers in `src/agents/` | The client's plugin manager. Hack commands never install or update it. |
+| Native plugin (`plugins/hack`) | Client manifests, seven skills, Claude primer hooks, Cursor rule, `hack mcp serve` declaration | `scripts/generate-agent-plugins.ts`, rendering from `src/agents/instruction-source.ts` and the skill renderers in `src/agents/` | The client's plugin manager. Hack commands never install or update it. |
 | Standalone setup | Project AGENTS.md/CLAUDE.md snippets, Cursor rules, shared skills, Claude primer hooks, MCP entries | `src/agents/instruction-source.ts` and its renderers, written by `hack setup` and `hack mcp install` | Explicit `hack setup` and `hack mcp install` commands in a chosen scope |
 | MCP bundle | Native MCP adapter, owner and backend executables with a content-derived identity | `src/mcp/bundle.ts` (packaging and verification) | `hack mcp install --bundle ... --cli ...` writes the client entry; the bundle is never modified after selection |
 

examples/basic/AGENTS.md

@@ -6,7 +6,7 @@ Use `hack` as the single interface for local-first runtime orchestration (compos
 Integration freshness:
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `c3c646a036aa` (version alone is not a freshness guarantee).
+- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported CLI surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.

examples/basic/CLAUDE.md

@@ -6,7 +6,7 @@ Use `hack` as the single interface for local-first runtime orchestration (compos
 Integration freshness:
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `c3c646a036aa` (version alone is not a freshness guarantee).
+- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported CLI surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.

plugins/hack/README.md

@@ -3,9 +3,12 @@
 Optional Hack integration for Codex, Claude Code, and Cursor. Install the `hack`
 executable first; the plugin uses it from PATH.
 
-The bundle contains four skills:
+The bundle contains seven skills:
 
-- `hack-cli`: services, logs, environments, worktrees and diagnostics.
+- `hack-cli`: services, logs, routed URLs, lifecycle and workspaces.
+- `hack-branches`: parallel branch instances (`--branch <name>`) and branch aliases.
+- `hack-env`: env values, overlays and worktree-local overrides without exposing secrets.
+- `hack-diagnose`: read-first diagnosis and the `--json` error-code reference.
 - `hack-init`: configure a new or existing project for Hack.
 - `hack-install`: installation, stable/prerelease selection, upgrade and rollback.
 - `hack-remote`: prepare an existing project on another machine or in Codex Cloud.
@@ -26,7 +29,7 @@ that selection and disable the bundle's MCP entry in the client configuration:
 enabled = false
 ```
 
-This keeps the four plugin skills available without launching a second bundled
+This keeps the seven plugin skills available without launching a second bundled
 server. A standalone registration remains independently configured. Preserve
 existing customized skills; resolve overlapping installation paths deliberately.
 
@@ -38,7 +41,7 @@ codex plugin add hack@hack-dance
 codex plugin list --json --marketplace hack-dance
 ```
 
-Start a fresh client, confirm all four plugin skills load, and call a harmless
+Start a fresh client, confirm all seven plugin skills load, and call a harmless
 MCP tool such as `hack.projects.list` against an isolated registry. Inspect
 actual discovered tool names first.
 The server and Claude hooks still resolve `hack` from the client's PATH; installing

plugins/hack/rules/hack.mdc

@@ -14,7 +14,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `c3c646a036aa` (version alone is not a freshness guarantee).
+- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
 
 ## Product boundary
 

plugins/hack/skills/hack-branches/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: hack-branches
+description: >
+  Run parallel branch instances of a Hack project with `--branch <name>` and manage their aliases
+  with `hack branch`. Trigger when asked to run two versions of a project side by side; start,
+  open, tail or stop a branch instance; review a pull request in its own instance; or add, list,
+  open or remove a branch alias.
+---
+
+# Hack branch instances
+
+## Branch instances (parallel envs)
+
+- Use a branch instance when you need two versions running at once (PR review, experiments, migrations) or want to keep a stable environment while testing another branch.
+- Target one with `--branch <name>` on up/open/logs/down (for example: `hack up --branch <name> --detach`).
+- Linked worktrees pick a branch instance automatically (see Linked git worktrees).
+- Containers receive `HACK_RUNTIME_METADATA` plus `HACK_DEV_URL`, `HACK_ALIAS_URL`, and current-service URL fields derived from effective Caddy routes. Use Compose DNS for internal traffic and this metadata for browser-facing links, OAuth callbacks, and webhooks.
+
+## Branch aliases
+
+- Aliases are entries in `.hack/hack.branches.json`; `hack up --branch <name>` records or refreshes its entry automatically.
+- `hack branch add <name> --note <text>` registers one ahead of time, and `hack branch list` shows each alias with its note and last use.
+- `hack branch open <name>` opens that branch's routed host; `hack branch open <name> --prefer <auto|alias|dev>` selects which host.
+- `hack branch remove <name>` deletes only the alias entry and leaves any running instance alone; stop the instance with `hack down --branch <name>`.
+
+## Linked git worktrees (optional)
+
+- Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.
+- `hack up` in a linked worktree defaults to a branch instance named after the worktree's git branch; a detached linked worktree requires an explicit `--branch`, unless config `worktree.auto_branch=false` explicitly opts into the base instance.
+- Before `hack up` or `hack restart` auto-targets a new branch instance, Hack warns when the same worktree already owns a non-terminal instance; pass `--branch <name>` to make the target explicit.
+- Implicit `hack down` retargets a uniquely owned same-checkout runtime after a Git branch rename, including Created and stopped containers; when multiple runtimes belong to the checkout, pass `--branch <name>` explicitly.
+- `hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
+
+## Integration freshness
+
+- These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
+- Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
+- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).

plugins/hack/skills/hack-cli/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: hack-cli
 description: >
-  Use the hack CLI for local runtime orchestration (compose, DNS/TLS, logs, env, persistent project workspaces) and agent setup.
-  Trigger when asked to run/start/stop services, inspect logs, manage lifecycle/workspace workflows, or update
-  agent integrations. Prefer CLI over MCP when shell access is available.
+  Use the hack CLI for local runtime orchestration (compose, DNS/TLS, routed URLs, persistent
+  project workspaces) and agent setup. Trigger when asked to run, start or stop services; tail
+  service logs; open a routed app URL; manage lifecycle or workspace workflows; or update agent
+  integrations. Use hack-branches for branch instances, hack-env for env values and hack-diagnose
+  for a failing project. Prefer CLI over MCP when shell access is available.
 ---
 
 # hack CLI
@@ -14,7 +16,7 @@ Use `hack` as the primary interface for local-first development.
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `c3c646a036aa` (version alone is not a freshness guarantee).
+- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
 
 ## Product boundary
 

plugins/hack/skills/hack-diagnose/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: hack-diagnose
+description: >
+  Diagnose a Hack-managed project by reading its state first and repairing only within the
+  request. Trigger when asked to find out why a service is unhealthy or did not start; interpret
+  an E_* error code from a JSON envelope; review hack doctor findings; or investigate routing or
+  global infrastructure failures.
+---
+
+# Diagnose a Hack project
+
+## Read-first diagnosis
+
+- Read before changing anything, in this order, and stop once the cause is clear:
+- Step 1, `hack ps --json`: which services exist and their state.
+- Step 2, `hack doctor --json`: findings and stable E_* codes.
+- Step 3, `hack logs --json --no-follow --tail 200`: a finite snapshot; add a service name to narrow it.
+- Step 4, `hack env explain <key> --service <service>`: only when a value is suspect; it reports provenance without the value.
+- Step 5, `hack global status`: shared proxy, DNS and logging infrastructure.
+- Branch on `error.code`, not on message text; the code is the stable contract and the message may change.
+- Report what each read showed before proposing a repair.
+
+## Operating rules
+
+- Prefer `hack` over raw `docker` / `docker compose` for project workflows.
+- Do not start/stop services from Docker Desktop UI for `hack`-managed projects.
+- Treat `.hack/.internal` and `.hack/.branch` as hack-managed artifacts; do not hand-edit generated files there.
+- Use `--json` for machine-readable output when available; `hack up/down/restart/doctor --json` emit an `{ok, data | error: {code, message}}` envelope with stable E_* error codes.
+- When the exit status matters, do not pipe `hack` output through `| tail` or `| grep`: the pipeline reports the filter's status, and filtered text can hide failures. Check the `hack` exit status or `--json` envelope first, and use finite reads such as `hack logs --no-follow --tail 100`.
+- Scripted/agent runs: pass `--no-interactive` (or set `HACK_NO_INTERACTIVE=1`) so commands never block on prompts — they apply documented defaults or fail fast with E_INTERACTIVE_REQUIRED.
+- Use MCP only when shell access is unavailable.
+- A task request authorizes its stated scope, not unrelated service, global config, or production changes. Preserve native credential/trust approvals and destructive-cleanup gates; do not ask again for the same authorized action.
+- Cleanup must prove resource ownership. Successful one-shot containers may exit with code 0; adopted external processes must remain running when Hack stops its own services.
+- If runtime state looks wrong, inspect with `hack doctor`; apply `hack doctor --fix` only for repairs covered by the request. Warnings do not authorize broader changes.
+
+## Integration freshness
+
+- These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
+- Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
+- Content revision: `9f26e5752230` (version alone is not a freshness guarantee).
+
+## References
+
+- [Error codes](references/error-codes.md): every stable `--json` error code with its meaning and the first read-only step.