@b00dea/cockpit 0.0.0-stage → 0.1.1

package/surfaces/skills/cockpit-setup.skill.md

@@ -0,0 +1,39 @@
+---
+name: cockpit-setup
+description: "Use when a repository or agent tool joins or leaves an installed cockpit, cockpit is upgraded, check or doctor reports drift or a gap to repair, checkouts or stacks need updating or pruning, a repository's AGENTS.md and CLAUDE.md must reach every agent tool, a repository has never run locally, or test users and signed-in browser state need setting up. A directory with no cockpit yet is adopt-cockpit's job."
+targets: ["*"]
+cockpit:
+  tools: [shell]
+  tool-equivalences:
+    claudecode: [Bash]
+    codexcli: [shell]
+    opencode: [bash]
+  commands: [init, setup, sync, check, doctor, up, preflight, upgrade, sibling, tool, pull, use, stacks, rebuild, down]
+  changes: [cockpit configuration and generated harness surfaces after preview]
+  non-goals: [parsing registries, deciding environment policy, claiming an unproved installation]
+  procedure: procedures/setup.md
+  review: { mechanical: cockpit-skill-contract, judgment: pending }
+  entry-point-lines: 14
+claudecode:
+  allowed-tools: [Bash]
+codexcli:
+  dependencies:
+    tools: [{ type: executable, value: cockpit, description: Runs accepted cockpit CLI primitives. }]
+opencode:
+  allowed-tools: [bash]
+---
+
+<!-- cockpit:verified version=0.0.0 -->
+
+# Set up and maintain an installed cockpit
+
+{{tool-equivalence}}
+Before running any command, read [procedures/setup.md](procedures/setup.md) beside this skill: its **Running cockpit** section, then the one section the request needs, followed step by step.
+- Drift named by `check` or the session-start report: **On drift**, before anything else.
+- A repository or an agent tool joins or leaves: **Add or remove a repository**, **Add or remove an agent tool**.
+- A repository's AGENTS.md and CLAUDE.md must reach every tool: **Make a repository's instructions reach every tool**.
+- A repository that has never run locally: **Create a local setup**; secrets and `.env.schema`: **Secret handling**.
+- A new cockpit release: **After upgrading cockpit**. A gap or refusal to repair: **Diagnose**. Checkouts to update, a worktree to serve, a stale or orphaned stack: **Keep checkouts and stacks current**.
+- An interrupted or unfinished `init`: **Bootstrap**, rerun with the same root and target. A directory with no cockpit yet is the adopt-cockpit skill's job.
+- Test users, roles and signed-in browser state: `references/test-data-and-personas.md`, a product change that needs the person's permission first.
+Show the person every proposed change and get their explicit yes before writing to `cockpit.toml` or a product repository, or accepting a digest.

package/surfaces/skills/cockpit-work.skill.md

@@ -0,0 +1,34 @@
+---
+name: cockpit-work
+description: "Use when someone names a work order, or a change must be held to criteria someone else set, graded by something other than you, or carried across sessions, in a cockpit with work orders. Ordinary fixes use cockpit-fix."
+targets: ["*"]
+cockpit:
+  tools: [shell]
+  tool-equivalences:
+    claudecode: [Bash]
+    codexcli: [shell]
+    opencode: [bash]
+  commands: [work status, work accept, work check, work note, work decide, work answer, work acknowledge, work grade, work signoff, work recover, docs check, test-run]
+  changes: [the files the accepted work order's scope names]
+  non-goals: [grading its own work under independent grading, passing a gate the policy gives a person, editing the policy in cockpit.toml]
+  procedure: procedures/work.md
+  review: { mechanical: cockpit-skill-contract, judgment: pending }
+  entry-point-lines: 9
+claudecode:
+  allowed-tools: [Bash]
+codexcli:
+  dependencies:
+    tools: [{ type: executable, value: cockpit, description: Runs accepted cockpit CLI primitives. }]
+opencode:
+  allowed-tools: [bash]
+---
+
+<!-- cockpit:verified version=0.0.0 -->
+
+# Work an order
+
+{{tool-equivalence}}
+Read [procedures/work.md](procedures/work.md) beside this skill and follow **Work** from step 0, which resumes an existing order at the step its state names.
+Under independent grading another agent tool grades the order; never grade your own work.
+When a command answers `WORK_PERSON_REQUIRED`, stop and ask the person to run the same command with `--interactive` in a terminal: never type a digest for them.
+If `check` or the session-start report names drift, follow *On drift* in the cockpit-setup skill's procedure, `../cockpit-setup/procedures/setup.md`, first.

package/surfaces/skills/collection.json

@@ -0,0 +1,5 @@
+{
+  "skills": ["cockpit-setup", "cockpit-explain", "cockpit-fix", "cockpit-work"],
+  "metric": "frontmatter_bytes",
+  "caps": { "claudecode": 8192, "codexcli": 8192, "opencode": 8192, "cursor": 8192, "grokcli": 8192 }
+}

package/surfaces/skills/procedures/explain.md

@@ -0,0 +1,66 @@
+---
+loading: pull
+budget: uncapped
+---
+
+<!-- cockpit:verified version=0.0.0 -->
+
+# Explain a cockpit
+
+## Running cockpit
+
+- Run every command from the cockpit root, the directory holding `cockpit.toml`, through the
+  project-local binary, for example `./node_modules/.bin/cockpit check --config cockpit.toml`.
+  `npx --no cockpit <command>` starts the same binary, but the path form still runs where the
+  guard cannot prove what npx starts. If the binary is missing, stop and ask the person to install cockpit; a
+  runner that downloads a package is never a substitute.
+- Take flags from each command's `--help`. With `--json`, read `result`, `diagnostics[].code` and
+  `invocation.exitCode`. Every diagnostic names its fix, and
+  `./node_modules/@b00dea/cockpit/docs/troubleshooting.md` covers the codes that need more; the
+  other user-guide pages cited here sit beside it.
+- When the guard asks before a command, the person decides in Claude Code; Codex and OpenCode deny
+  instead, so hand the person the exact command to run in a terminal. A refusal that holds every
+  tool call (a guard message saying so, `GUARD_AUTHORITY_UNAVAILABLE` or `GUARD_CONFIG_UNSYNCED`)
+  follows any edit to `cockpit.toml` or reinstall of cockpit or Node. `GUARD_CONFIG_UNSYNCED` means
+  the edit does not widen what agents may do, so run
+  `./node_modules/.bin/cockpit sync --config cockpit.toml` yourself where `[autonomy] sync =
+  "agent"`; any other hold clears only when a person runs it in a terminal. A refused command is the
+  person's to run: never reword, wrap or re-spell it to get past the guard.
+- In Codex's sandbox only `check`, `sync --dry-run` and `--help` work. Every other cockpit command
+  there cannot read cockpit's state or the Docker socket, so a failure it reports is not evidence:
+  ask the person to approve running it outside the sandbox, or to run it in a terminal. Under
+  `codex exec`, which cannot ask, a person runs it.
+- Ask, never invent. A port, image, command, host, purpose, name, version, role or credential comes
+  from a file you read or from the person; with neither, name the gap and ask.
+
+## Explain
+
+You answer a question about this cockpit from what its commands report now, and change nothing.
+
+1. **Pick the command that answers the question**, and only that one:
+   `./node_modules/.bin/cockpit doctor --config cockpit.toml --json` for environment health, wiring
+   and readiness gaps; `./node_modules/.bin/cockpit check --config cockpit.toml --json` for generated
+   files that drift from `cockpit.toml`; `./node_modules/.bin/cockpit preflight --config cockpit.toml --json`
+   for whether the environment passes the gate work needs;
+   `./node_modules/.bin/cockpit ps --config cockpit.toml --json` for which services of this
+   checkout's stack run; `./node_modules/.bin/cockpit stacks --config cockpit.toml --json` for every
+   stack on the machine. Run two only when the question spans them.
+   A question about one diagnostic code, or a refusal the person pasted, may need no command: read
+   what `./node_modules/@b00dea/cockpit/docs/troubleshooting.md` says about the code, and for a guard
+   refusal, `./node_modules/@b00dea/cockpit/docs/safety-and-autonomy.md`. Done when you have the
+   output, or the page, the answer rests on.
+2. **Answer from that output.** Name each relevant diagnostic code, what it means, and the fix it
+   names; say which wired repositories, agent tools and gates are involved, and what is still a
+   gap. Quote the output for every claim instead of describing the configuration from memory.
+   Done when every claim in your answer points at a line of output or a page.
+3. **Give the next command** that changes the state, and who runs it: the agent, or a person in a
+   terminal when the guard or a gate gives the step to a person. Done when the person can act on it
+   without asking you again.
+
+When explaining drift, say what each command does: `check` repairs nothing; `sync` rewrites a
+hand-edited generated artifact such as `compose.cockpit.yml`, and refuses a hand-edited skill,
+agent settings file or cockpit-owned region with `SURFACE_STATE_CONFLICT`; the fix for each case is
+in *On drift* of the cockpit-setup skill's procedure, `../../cockpit-setup/procedures/setup.md` from
+this file. For a secret question, follow its *Secret handling* section and distinguish the tracked
+schema, the encrypted or provider source, the redacted status, injection into a trusted child
+process, and the same-user read confinement that is unavailable.

package/surfaces/skills/procedures/fix.md

@@ -0,0 +1,95 @@
+---
+loading: pull
+budget: uncapped
+---
+
+<!-- cockpit:verified version=0.0.0 -->
+
+# Fix a defect
+
+## Running cockpit
+
+- Run every command from the cockpit root, the directory holding `cockpit.toml`, through the
+  project-local binary, for example `./node_modules/.bin/cockpit check --config cockpit.toml`.
+  `npx --no cockpit <command>` starts the same binary, but the path form still runs where the
+  guard cannot prove what npx starts. If the binary is missing, stop and ask the person to install cockpit; a
+  runner that downloads a package is never a substitute.
+- Take flags from each command's `--help`. With `--json`, read `result`, `diagnostics[].code` and
+  `invocation.exitCode`. Every diagnostic names its fix, and
+  `./node_modules/@b00dea/cockpit/docs/troubleshooting.md` covers the codes that need more; the
+  other user-guide pages cited here sit beside it.
+- When the guard asks before a command, the person decides in Claude Code; Codex and OpenCode deny
+  instead, so hand the person the exact command to run in a terminal. A refusal that holds every
+  tool call (a guard message saying so, `GUARD_AUTHORITY_UNAVAILABLE` or `GUARD_CONFIG_UNSYNCED`)
+  follows any edit to `cockpit.toml` or reinstall of cockpit or Node. `GUARD_CONFIG_UNSYNCED` means
+  the edit does not widen what agents may do, so run
+  `./node_modules/.bin/cockpit sync --config cockpit.toml` yourself where `[autonomy] sync =
+  "agent"`; any other hold clears only when a person runs it in a terminal. A refused command is the
+  person's to run: never reword, wrap or re-spell it to get past the guard.
+- In Codex's sandbox only `check`, `sync --dry-run` and `--help` work. Every other cockpit command
+  there cannot read cockpit's state or the Docker socket, so a failure it reports is not evidence:
+  ask the person to approve running it outside the sandbox, or to run it in a terminal. Under
+  `codex exec`, which cannot ask, a person runs it.
+- Ask, never invent. A port, image, command, host, purpose, name, version, role or credential comes
+  from a file you read or from the person; with neither, name the gap and ask.
+
+## Fix
+
+A fix is a change you make and prove yourself. It needs no intake, draft, source audit or
+work-order file. Use the cockpit-work skill instead when someone else must certify the result, or
+the work must carry on in a later session or belongs to a programme. Ask that again whenever the
+scope changes, not at hand-back.
+
+1. **Name the defect.** Write down the expected behavior, the observed behavior and the repository
+   that owns it. Done when a reader could tell the fix worked from those two sentences alone.
+2. **Find the gate.** The *Testing tiers* section of the cockpit's root `AGENTS.md` lists the
+   declared gates and which change each proves; pick the narrowest that covers this one. If it says
+   no gate is declared, follow it instead: prove the fix with the product's own test runner, and
+   report that no gate graded it. Done when you hold one gate ID, or know there is none.
+3. **Record the baseline before you edit**:
+   `./node_modules/.bin/cockpit test-run --config cockpit.toml --gate declared-gate-id --json`, with
+   the ID from step 2. Any verdict but PASS exits with `TEST_GATE_UNSATISFIED`, and its fix says
+   what FAIL, DEGRADED, VOID and PARTIAL each need. Done when you know what already passed and what
+   already failed.
+4. **Reproduce at the narrowest real boundary.** Extend the nearest behavior test through its
+   public surface so it fails on this defect, and run it with the narrowest selector the gate takes.
+   Start the stack with `./node_modules/.bin/cockpit up --config cockpit.toml` only when the
+   behavior needs a live process or integration, adding `--profile <name>` for a service behind a
+   Compose profile. Read `./node_modules/.bin/cockpit ps --config cockpit.toml --json` for each
+   service's state, `./node_modules/.bin/cockpit logs --config cockpit.toml --service service-id`,
+   naming the declared service, and `./node_modules/.bin/cockpit doctor --config cockpit.toml --json`
+   only for the runtime output the defect needs; a `STACK_INPUTS_CHANGED` warning there goes to
+   *Keep checkouts and stacks current* in the cockpit-setup skill's procedure first. A command inside
+   a service, such as a migration or a query, runs through
+   `./node_modules/.bin/cockpit exec --config cockpit.toml --service service-id -- <command>`; the
+   guard asks unless a `[guards] allow` rule or a declared build or test command admits it. When the
+   stack will not start (no Docker, another holder, an unmeasured runtime), report the code `up`
+   gives and its fix rather than proving the fix some other way. Done when a test goes red on
+   exactly the observed behavior.
+5. **Then change the repository that owns the defect**, and nothing else. Leave uncommitted changes
+   that were already in the checkout as you found them. If you change it in a worktree rather than
+   the checkout `cockpit.toml` declares, first run
+   `./node_modules/.bin/cockpit use sibling-slug /absolute/path/to/worktree --config cockpit.toml`
+   so the stack, the guard and the gates use that worktree, and `use sibling-slug --clear` at step 8. For an environment or credential defect,
+   follow the *Secret handling* section of the cockpit-setup skill's procedure,
+   `../../cockpit-setup/procedures/setup.md` from this file, before running the declared product
+   command. When the running stack must pick the change up, run
+   `./node_modules/.bin/cockpit rebuild --config cockpit.toml --service service-id` for a change baked
+   into its image, or `restart --service service-id` for one its process loads at start. Done when
+   the test from step 4 passes.
+6. **Prove it**: run the gate from step 3 again, complete and without a selector. Done when it
+   reports PASS, or you can name the failure and its cause.
+7. **Review.** Once the change is stable, simplify it, then review it independently, with security
+   emphasis when the changed boundary warrants it. Reuse an installed code-review or security-review
+   skill; otherwise apply that sequence directly. Fix blocking findings and rerun the gate. Done
+   when no blocking finding is open and the gate result is current.
+8. **Clean up.** List the files, temporary files, processes and stack claims this task created.
+   Remove only the temporary files this task created; keep earlier uncommitted changes, other
+   agents' files, claims other holders hold and the review results. Release a stack claim only
+   with the cockpit lifecycle command (`./node_modules/.bin/cockpit sleep --config cockpit.toml`),
+   following any approval it asks for; when cockpit cannot confirm that release is safe, keep the
+   claim and report who holds it, the refusal and its output. Done when every item is removed or
+   reported with the reason you kept it.
+
+Report the defect, the files you changed, the gate results before and after, and every item you
+kept.