feat: add openspec CLI to code image and /fullsend skill

durandom · claude · durandom · commit ed718cc4d3f6 · 2026-06-10T14:10:39.000+02:00
Image: install @fission-ai/openspec globally so agents can run
openspec commands (list, change, archive) inside the sandbox.

Skill: add /fullsend router with two subcommands:
- validate: diffs customized harness/env files against upstream scaffold
- inspect: investigates a fullsend agent run (status, timing, artifacts, logs)

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.claude/skills/fullsend/SKILL.md b/.claude/skills/fullsend/SKILL.md
@@ -0,0 +1,40 @@
+---
+description: "Fullsend harness validation, drift checking, sandbox debugging, and fullsend setup"
+---
+
+# /fullsend
+
+Tooling for managing fullsend sandbox configurations — validating customized harness/env files against the upstream scaffold, debugging sandbox issues, and managing fullsend setup.
+
+## Essential Principles
+
+1. **Customized files are full replacements.** When a repo places a file in `.fullsend/customized/harness/`, fullsend uses it *instead of* the scaffold version — not merged, not overlaid. Any field omitted from the customized file is silently dropped.
+2. **Upstream scaffold is source of truth.** The canonical harness and env definitions live in the scaffold repo. Customizations must track upstream changes or they drift.
+3. **Always diff before deploying.** Never commit a customized harness without comparing it field-by-field against the current upstream version.
+
+## Setup Gates
+
+**Scaffold directory** (required by `validate`):
+
+1. Environment variable `FULLSEND_SCAFFOLD_DIR` (if set)
+2. Default relative path: `../asdlc-lab/resources/fullsend-ai/fullsend/internal/scaffold/fullsend-repo/`
+
+If neither resolves to a readable directory, stop and ask the user to set `FULLSEND_SCAFFOLD_DIR` or clone `asdlc-lab`.
+
+**Target repo** (used by `validate` and `inspect`):
+
+1. Explicit argument (repo path or `--repo` flag)
+2. Default: `../rhdh-agentic`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `validate [repo-path]` | Diff customized harness/env files against upstream scaffold |
+| `inspect <run-id \| #issue>` | Investigate a fullsend agent run — status, timing, output, logs |
+
+## Routing
+
+1. Parse the first word after `/fullsend` as the subcommand.
+2. If it matches a command above, read the corresponding reference file from `references/<command>.md` and follow its procedure.
+3. If no arguments are given, display the commands table above and ask which the user wants.
diff --git a/.claude/skills/fullsend/references/inspect.md b/.claude/skills/fullsend/references/inspect.md
@@ -0,0 +1,181 @@
+# inspect
+
+Investigate a fullsend agent run — pull together status, timing, agent output, and logs into a single report.
+
+## Usage
+
+```
+/fullsend inspect <run-id>
+/fullsend inspect #<issue-number>
+/fullsend inspect
+```
+
+- `<run-id>`: GitHub Actions run ID (numeric)
+- `#<issue-number>`: find the latest fullsend run triggered by this issue
+- No argument: inspect the most recent fullsend run
+
+Default repo: `../rhdh-agentic`. Override with `FULLSEND_REPO` env var or `--repo <owner/name>`.
+
+## Procedure
+
+### 1. Resolve the run
+
+Determine the GitHub repo owner/name and the run ID.
+
+**If run ID given** (bare number):
+```bash
+gh run view <run-id> --repo <owner/name> --json databaseId,status 2>&1
+```
+Verify it exists. If not, abort with "Run not found."
+
+**If `#N` given** (issue number):
+```bash
+gh run list --repo <owner/name> --limit 10 --json databaseId,event,status,conclusion,createdAt \
+  --jq '[.[] | select(.event == "issue_comment" or .event == "issues")] | .[0].databaseId'
+```
+Then cross-reference: fetch issue N's comments for `fullsend:agent-status:<run-id>` anchors. Use the latest matching run ID.
+
+**If no argument**:
+```bash
+gh run list --repo <owner/name> --limit 5 --json databaseId,event,status,conclusion,createdAt \
+  --jq '[.[] | select(.event == "issue_comment" or .event == "issues")] | .[0]'
+```
+Use the most recent fullsend-triggered run.
+
+### 2. Gather run overview
+
+```bash
+gh run view <run-id> --repo <owner/name> \
+  --json databaseId,status,conclusion,event,createdAt,updatedAt,jobs,url
+```
+
+Extract:
+- **Status/conclusion**: `completed/success`, `completed/failure`, `in_progress`, etc.
+- **Duration**: compute from `createdAt` → `updatedAt`
+- **Trigger event**: `issue_comment`, `issues`, `pull_request`
+- **Jobs table**: for each job, extract name, status, conclusion, duration (startedAt → completedAt). Skip jobs with conclusion `skipped` from the duration calculation.
+
+Identify the **agent job** — the one that is NOT `Route` and NOT `stop-fix` and has conclusion != `skipped`. Its name (e.g., `dispatch / Code / Code`) tells you which agent ran.
+
+### 3. Gather agent status comment
+
+Find the triggering issue number. Strategy:
+1. If the user passed `#N`, use that.
+2. Otherwise, extract from the run's event payload — check the run's `headBranch` or use `gh api repos/<owner/name>/actions/runs/<run-id> --jq '.event'` combined with searching recent issue comments.
+
+Then fetch the status comment:
+```bash
+gh api repos/<owner/name>/issues/<N>/comments \
+  --jq '.[] | select(.body | test("fullsend:agent-status:<run-id>")) | {body, created_at}'
+```
+
+Parse from the comment body:
+- Agent name and result (Success / Failure)
+- Commit SHA (from the `Commit:` backtick)
+- Timestamps
+
+If no status comment found, note: "No agent status comment — the run may have failed before posting."
+
+### 4. Check for PR or branch
+
+If a commit SHA was found in step 3:
+
+```bash
+# Find branches containing the commit (in the local clone)
+cd <repo-path> && git fetch --quiet && git branch -r --contains <sha> 2>/dev/null
+```
+
+```bash
+# Check for PRs from that branch
+gh pr list --repo <owner/name> --state all --head <branch-name> \
+  --json number,title,state,url --jq '.[] | "\(.number) \(.state) \(.title)"'
+```
+
+Report:
+- Branch name and whether it was pushed
+- PR number, state (OPEN/CLOSED/MERGED), title, URL
+- If no PR exists despite a successful commit: flag as `⚠️ No PR created`
+
+### 5. Download and summarize artifact
+
+```bash
+gh api repos/<owner/name>/actions/runs/<run-id>/artifacts \
+  --jq '.artifacts[] | {name, size_in_bytes, expired, archive_download_url}'
+```
+
+If an artifact exists and `expired == false`:
+
+```bash
+# Download to temp dir
+TMPDIR=$(mktemp -d)
+gh run download <run-id> --repo <owner/name> --name <artifact-name> --dir "$TMPDIR"
+```
+
+**Parse `output.jsonl`** (at `$TMPDIR/iteration-1/output.jsonl` or similar):
+- Count total conversation turns
+- Count tool_use calls by tool name
+- Find any `error` or `failure` messages
+- Extract the model ID used
+
+**Check sandbox logs** (at `$TMPDIR/logs/`):
+- `openshell-sandbox.log`: look for ERROR, FATAL, OOM, timeout
+- `openshell-gateway.log`: look for TLS errors, connection failures
+
+Clean up: `rm -rf "$TMPDIR"` after reading.
+
+If artifact expired or missing, note it and skip. If the run is still `in_progress`, artifacts won't be available yet — note this.
+
+### 6. Report
+
+Output a structured report:
+
+```
+## Fullsend Run Inspection: <run-id>
+
+### Overview
+| Field | Value |
+|-------|-------|
+| Run | [<run-id>](<url>) |
+| Trigger | issue_comment on #<N> |
+| Status | <status> / <conclusion> |
+| Duration | <Xm Ys> |
+| Agent | <agent-name> |
+
+### Jobs
+| Job | Status | Duration |
+|-----|--------|----------|
+| Route | success | 12s |
+| Code | success | 2m 42s |
+| Review | skipped | — |
+| ... | ... | ... |
+
+### Agent Output
+- Commit: `<sha>` — <commit message>
+- Branch: <branch-name>
+- PR: #<N> (<state>) / none
+- Status comment: ✅ Success / ❌ Failure
+
+### Artifact Summary
+- Turns: <N> | Tool calls: <N> | Errors: <N>
+- Model: <model-id>
+- Sandbox logs: clean / ⚠️ <issue summary>
+
+### Issues Found
+- ⚠️ <any anomalies detected>
+```
+
+### Issue detection heuristics
+
+Flag these automatically:
+
+| Condition | Flag |
+|-----------|------|
+| Run succeeded but no commit SHA in status comment | ⚠️ Success with no output |
+| Commit exists but no PR was created | ⚠️ No PR created |
+| Run duration > `timeout_minutes` from harness | ⚠️ May have hit timeout |
+| Sandbox log contains ERROR/FATAL | ⚠️ Sandbox errors (show excerpts) |
+| Artifact is expired | ℹ️ Artifact expired, no transcript available |
+| Run is still in progress | ℹ️ Run still in progress, partial data |
+| Multiple agent jobs ran (not just one + Route) | ℹ️ Multiple agents dispatched |
+
+If no issues found, end with: **No anomalies detected.**
diff --git a/.claude/skills/fullsend/references/validate.md b/.claude/skills/fullsend/references/validate.md
@@ -0,0 +1,110 @@
+# validate
+
+Diff customized harness and env files against the upstream scaffold to catch drift.
+
+## Usage
+
+```
+/fullsend validate [repo-path]
+```
+
+- `repo-path`: path to the repo with `.fullsend/customized/` overrides. Default: `../rhdh-agentic`
+
+## Procedure
+
+### 1. Resolve paths
+
+```
+SCAFFOLD_DIR = $FULLSEND_SCAFFOLD_DIR or ../asdlc-lab/resources/fullsend-ai/fullsend/internal/scaffold/fullsend-repo/
+TARGET_DIR   = <repo-path>/.fullsend/customized/
+```
+
+Verify both directories exist. Abort with a clear message if either is missing.
+
+### 2. Validate harness files
+
+For each `*.yaml` in `TARGET_DIR/harness/`:
+
+1. Read the customized file.
+2. Read the upstream file at `SCAFFOLD_DIR/harness/<same-name>.yaml`.
+   - If the upstream file does not exist, report it as **WARNING: no upstream counterpart** (may be a repo-specific harness).
+3. Run a structured diff. Classify each difference:
+
+#### Error (blocks deployment)
+
+- **Missing top-level field**: a field present in upstream but absent in the customized file. Because customized files are full replacements, this means the field is silently dropped at runtime.
+  - Known critical fields: `policy`, `agent`, `pre_script`, `post_script`
+- **Stale paths**: any `host_files[].dest` containing `/tmp/workspace/` — this was replaced by `/sandbox/workspace/` in OpenShell 0.0.54.
+
+#### Review (needs human judgement)
+
+- **Changed paths**: `host_files[].dest` values that differ from upstream but are not stale (may be intentional).
+- **Changed values**: fields like `image`, `timeout_minutes`, `model` that differ from upstream — these are often intentional overrides but should be confirmed.
+- **Missing list items**: entries in upstream `host_files`, `skills`, or `plugins` arrays that are absent in the customized version.
+
+#### Info (expected differences)
+
+- **Intentional overrides**: fields that differ but are clearly repo-specific customizations (e.g., different `image` tag, different `timeout_minutes` for debugging).
+- **Added fields**: fields in the customized file that don't exist in upstream (repo-specific extensions).
+- **Comment differences**: comment-only changes.
+
+### 3. Validate env files
+
+For each file in `TARGET_DIR/env/`:
+
+1. Read the customized file.
+2. Read the upstream file at `SCAFFOLD_DIR/env/<same-name>`.
+   - If no upstream counterpart exists, report as **INFO: repo-specific env file**.
+3. Compare exported variable names:
+   - Variables in upstream but missing from customized → **ERROR: missing variable**.
+   - Variables in customized but not in upstream → **INFO: repo-specific variable**.
+4. For shared variables, flag value differences as **REVIEW** (may be intentional overrides like different `GIT_AUTHOR_NAME`).
+
+### 4. Cross-check for orphaned customizations
+
+List any files in `TARGET_DIR/harness/` or `TARGET_DIR/env/` that have no upstream counterpart — these may be leftover from a renamed or removed upstream file.
+
+### 5. Report
+
+Output a structured report grouped by severity:
+
+```
+## Fullsend Validation: <repo-name>
+
+### Errors (must fix before deploying)
+- harness/code.yaml: missing field `doc` (present in upstream)
+- harness/code.yaml: missing field `plugins` (present in upstream)
+
+### Review (confirm these are intentional)
+- harness/code.yaml: `timeout_minutes` changed: 35 → 5
+- harness/code.yaml: `image` changed: ghcr.io/fullsend-ai/... → ghcr.io/redhat-developer/...
+
+### Info
+- harness/code.yaml: comment added at line 1 (repo-specific)
+
+### Summary
+- Files checked: 2 harness, 0 env
+- Errors: 2 | Review: 2 | Info: 1
+```
+
+If there are zero errors, end with: **All customizations are consistent with upstream.**
+
+## Special Checks
+
+These are run regardless of whether a field is classified above:
+
+| Check | Condition | Severity |
+|-------|-----------|----------|
+| Stale workspace path | Any `dest` containing `/tmp/workspace/` | ERROR |
+| Missing policy | `policy` field absent from harness | ERROR |
+| Missing agent | `agent` field absent from harness | ERROR |
+| Dropped plugins | `plugins` list shorter than upstream | REVIEW |
+| Dropped skills | `skills` list shorter than upstream | REVIEW |
+| host_files dest changed | `dest` differs from upstream | REVIEW |
+| runner_env subset | Customized `runner_env` keys are subset of upstream | REVIEW |
+
+## Implementation Notes
+
+- Use `diff -u` for a quick visual diff, but also do field-level YAML comparison for the structured report. Read both files and compare key-by-key.
+- YAML keys are unordered — don't flag reordering as drift.
+- When in doubt about whether a difference is intentional, classify as REVIEW, not ERROR.
diff --git a/images/code/Containerfile b/images/code/Containerfile
@@ -36,4 +36,10 @@ RUN mkdir -p "$COREPACK_HOME" \
     && corepack prepare yarn@stable --activate \
     && yarn --version
 
+# ---------------------------------------------------------------------------
+# openspec CLI — spec-driven development tooling.
+# Used by agents working on repos with openspec/ directories.
+RUN npm install -g @fission-ai/openspec \
+    && openspec --version
+
 USER sandbox
