You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Status: `hack tickets status T-00001 in_progress`
81
-
- Sync: `hack tickets sync`
82
-
83
-
Recommended body template (Markdown):
84
-
```md
85
-
## Context
86
-
## Goals
87
-
## Notes
88
-
## Links
89
-
```
90
-
91
-
Tip: use `--body-stdin` for multi-line markdown.
92
-
93
-
Data lives in `.hack/tickets/` (gitignored on the main branch) and syncs to hidden ref `refs/hack/tickets` by default.
94
-
<!-- hack:tickets:end -->
95
-
96
69
## Landing the Plane (Session Completion)
97
70
**When ending a work session**, you MUST complete ALL steps below.
98
71
@@ -230,17 +203,19 @@ Most formatting and common issues are automatically fixed by Biome. Run `bun x u
230
203
<!-- hack:agent-docs:start -->
231
204
## hack CLI (local dev + MCP)
232
205
233
-
Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, persistent project workspaces, and optional local tickets).
206
+
Use `hack` as the single interface for local-first runtime orchestration (compose, DNS/TLS, logs, env, and persistent project workspaces).
234
207
235
208
Product boundary:
236
-
- Supported v3 surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, daemon, and optional local tickets.
- Removed surfaces: hosted auth/account/org/team flows, web dashboard, built-in GitHub workflows, and built-in Linear sync.
238
-
-Unsupported experimental: remote/gateway/node/dispatch. Do not use these as the default path unless explicitly requested.
211
+
-Experimental and unsupported: remote/gateway/node/dispatch commands. They are hidden from default help (list with `hack help --all`) and warn on use; do not use them unless explicitly requested.
239
212
240
213
Operating rules:
241
214
- Prefer `hack` over raw `docker` / `docker compose` for project workflows.
242
215
- Do not start/stop services from Docker Desktop UI for `hack`-managed projects.
243
216
- Treat `.hack/.internal` and `.hack/.branch` as hack-managed artifacts; do not hand-edit generated files there.
217
+
- 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.
218
+
- 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.
244
219
- Use MCP only when shell access is unavailable.
245
220
- If runtime state looks wrong, run `hack doctor`, then `hack doctor --fix` before manual repair.
246
221
@@ -273,11 +248,15 @@ Project files (managed vs generated):
273
248
- Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
274
249
- Worktree-local env override files: `.hack/hack.env.local.yaml` and `.hack/hack.env.<overlay>.local.yaml`.
- Linked worktrees can inherit secret decryption through the git common dir; use `HACK_ENV_SECRET_KEY` in CI/managed containers.
277
251
- Generated (do not hand-edit): `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
- Secret key inherits from the primary checkout automatically through the shared git common dir; set `HACK_ENV_SECRET_KEY` for CI or detached environments.
257
+
-`hack up` in a linked worktree defaults to a branch instance named after the worktree's git branch; opt out with config `worktree.auto_branch=false` or an explicit `--branch`.
258
+
-`hack doctor` flags divergent secret keys and dev_host collisions across checkouts.
259
+
281
260
Advanced networking (extra_hosts + local proxies/tunnels):
282
261
- Static host mappings: set `internal.extra_hosts` in `.hack/hack.config.json`.
- One-off command in a fresh service container (deps started as needed): `hack run <service> <cmd...>`.
276
+
- Command inside an already-running service container: `hack exec <service> -- <cmd...>`.
277
+
- Host script that needs hack-stored env: `hack host exec --env <overlay> --scope <service> -- <cmd...>` — this is THE way to run repo scripts; never read .env files directly.
- Call a service over HTTP (from the host or between containers): use its Caddy hostname `https://<sub>.<dev_host>`; discover routable URLs with `hack open --json`.
- You need two versions running at once (PR review, experiments, migrations).
346
-
- You want to keep a stable environment while testing another branch.
347
-
- Use `--branch <name>` on `hack up/open/logs/down` to target it.
312
+
Branch instances (parallel envs):
313
+
- 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.
314
+
- Target one with `--branch <name>` on up/open/logs/down (for example: `hack up --branch <name> --detach`).
315
+
- Linked worktrees pick a branch instance automatically (see Linked git worktrees).
348
316
349
317
Run commands inside services:
350
318
- One-off: `hack run <service> <cmd...>` (uses `docker compose run --rm`)
@@ -357,6 +325,11 @@ Project targeting:
357
325
- Else use `--project <name>` (registry) or `--path <repo-root>`.
358
326
- List projects: `hack projects --json`
359
327
328
+
Global infra:
329
+
- Bootstrap once: `hack global install`
330
+
- Start/stop/status: `hack global up`, `hack global down`, `hack global status`
331
+
- Use `hack global up` before Loki/Grafana queries if global logging is offline.
332
+
360
333
Daemon (optional):
361
334
- Start for faster JSON status/ps: `hack daemon start`
362
335
- Check status: `hack daemon status`
@@ -377,12 +350,14 @@ Agent setup (CLI-first):
377
350
- Cursor rules: `hack setup cursor`
378
351
- Claude hooks: `hack setup claude`
379
352
- Codex skill: `hack setup codex`
380
-
- Tickets skill: `hack setup tickets`
381
353
- Refresh all local agent integrations: `hack setup sync --all-scopes`
0 commit comments