Terminal Ops

---
name: terminal-ops
description: Evidence-first repo execution workflow for ECC. Use when the user wants a command run, a repo checked, a CI failure debugged, or a narrow fix pushed with exact proof of what was executed and verified.
origin: ECC
---

# Terminal Ops

Use this when the user wants real repo execution: run commands, inspect git state, debug CI or builds, make a narrow fix, and report exactly what changed and what was verified.

This skill is intentionally narrower than general coding guidance. It is an operator workflow for evidence-first terminal execution.

## Skill Stack

Pull these ECC-native skills into the workflow when relevant:

- `verification-loop` for exact proving steps after changes
- `tdd-workflow` when the right fix needs regression coverage
- `security-review` when secrets, auth, or external inputs are involved
- `github-ops` when the task depends on CI runs, PR state, or release status
- `knowledge-ops` when the verified outcome needs to be captured into durable project context

## When to Use

- user says "fix", "debug", "run this", "check the repo", or "push it"
- the task depends on command output, git state, test results, or a verified local fix
- the answer must distinguish changed locally, verified locally, committed, and pushed

## Guardrails

- inspect before editing
- stay read-only if the user asked for audit/review only
- prefer repo-local scripts and helpers over improvised ad hoc wrappers
- do not claim fixed until the proving command was rerun
- do not claim pushed unless the branch actually moved upstream

## Workflow

### 1. Resolve the working surface

Settle:

- exact repo path
- branch
- local diff state
- requested mode:
  - inspect
  - fix
  - verify
  - push

### 2. Read the failing surface first

Before changing anything:

- inspect the error
- inspect the file or test
- inspect git state
- use any already-supplied logs or context before re-reading blindly

### 3. Keep the fix narrow

Solve one dominant failure at a time:

- use the smallest useful proving command first
- only escalate to a bigger build/test pass after the local failure is addressed
- if a command keeps failing with the same signature, stop broad retries and narrow scope

### 4. Report exact execution state

Use exact status words:

- inspected
- changed locally
- verified locally
- committed
- pushed
- blocked

## Output Format

```text
SURFACE
- repo
- branch
- requested mode

EVIDENCE
- failing command / diff / test

ACTION
- what changed

STATUS
- inspected / changed locally / verified locally / committed / pushed / blocked
```

## Pitfalls

- do not work from stale memory when the live repo state can be read
- do not widen a narrow fix into repo-wide churn
- do not use destructive git commands
- do not ignore unrelated local work
- readiness markers are not enough for smoke tests: if an app logs readiness but the command times out or is killed, report `blocked/failed` until process exit code `0` is verified
- when a verification command is blocked or denied by the operator/tooling, do not retry the same command; preserve the last verified state and label the final verdict partial
- when a workflow creates agent/runtime artifacts (`.ouroboros/`, `.claude/`, logs, generated seeds), keep them out of staging by default unless the user explicitly asks to preserve them in git
- if a root-level generated helper file was copied only to satisfy a tool path/containment constraint, remove that root copy after durable artifacts are saved elsewhere and verify the file is gone

## Generated Agent Artifacts and Dirty Worktrees

When using external agents or orchestrators during repo work (Codex/Ouroboros/Claude/etc.):

1. Save prompts, outputs, and logs under an artifact directory (for example `.ouroboros/requests`, `.ouroboros/outputs`, `.ouroboros/logs`) so the run is auditable.
2. Treat generated artifact directories as local/runtime evidence by default, not source code to stage.
3. Before committing, print `git status --short --branch` and explicitly separate:
   - intended source/docs changes;
   - user-owned dirty files;
   - local runtime artifacts;
   - generated helper copies that should be deleted.
4. For docs-only release reconciliation, run stale-state greps before and after edits, then record both red/stale findings and post-edit no-match checks in the worklog.
5. If `rg` is used as a “no stale matches” check, exit code `1` is expected and should be reported as PASS only when output is empty.

Session-specific examples:

- `references/ouroboros-release-reconciliation.md` — generated agent artifacts and docs-only release reconciliation.
- `references/electron-macos-branding-smoke.md` — Electron macOS branding diagnostics across packaged/dev launch surfaces and smoke-marker pitfalls.
- `references/electron-smoke-exit-readiness.md` — Electron smoke cases where readiness markers appear but the process does not exit; includes `app.quit()` + bounded `app.exit()` fallback and blocked-rerun verdict rules.

## Verification

- the response names the proving command or test
- git-related work names the repo path and branch
- any push claim includes the target branch and exact result