agnix-fix

Files (1)

• SKILL.md

SKILL.md (first lines)

**MANDATORY: Follow the complete shared lifecycle contract in `${CLAUDE_PLUGIN_ROOT}/skills/shared/run-lifecycle.md` with declared skill `agnix-fix`.**

# Agnix-Fix Skill

**MANDATORY: READ ENTIRE FILE before composing user-facing prose: `$PWD/skills/shared/readability-style.md`.**

Private convenience alias for fixing `agent-sh/agnix` issues from a fork clone. Goes beyond `larch:alias` flag-forwarding by (a) fetching the upstream issue body so `/implement` does not have to research it, (b) provisioning the `skip-changelog` label on the fork (idempotent), and (c) baking CI-monitoring guidance into the prompt so the orchestrator interprets the fork's deterministic `add-to-project` failure correctly.

Not shipped to other plugin consumers — placed under `.claude/skills/agnix-fix/` (dev-only).

## CI-monitoring contract

Forks of `agent-sh/agnix` cannot access org-level secrets. The `add` check (run by `add-to-project.yml` via `pull_request_target`) requires `secrets.PROJECT_TOKEN` and **always fails** on fork PRs in ~2s with `Input required and not supplied: github-token` (the action's parameter name, not the auto-provided `GITHUB_TOKEN`). The orchestrator MUST treat this as expected-to-fail and not loop on it.

**A green run on the fork** means: `ci` (`agnix` + `test`) green, `claude-review` green, `Build docs site` green, `Verify Changelog` skipped (via `[skip changelog]` title token or `skip-changelog` label). If any of those four fail, that is a real failure to fix. The `add` failure is ignored. The upstream PR (later opened by the operator against `agent-sh/agnix`) runs on `agent-sh`'s runners with all secrets, so `add-to-project` succeeds there.

For issues touching only `knowledge-base/`, `crates/agnix-rules/`, or `website/docs/rules/generated/` (rule-metadata or generated-docs corrections), prefix the PR title with `[skip changelog]`. For issues materially changing behavior or user-facing surfaces, do NOT add the prefix and author a `CHANGELOG.md` entry as part of the implementation.

### `/implement` exit routing (delegated runs)

This skill forwards to `/implement` (`skills/implement/SKILL.md`). Parse exit codes like the implement orchestrator:

| Code | Meaning |
|------|---------|
| **0** | Normal completion of the scripted path for that attempt. |
| **2** | Operator-visible hard errors (argv, missing/malformed `larch:plan`, `gh` / plan helpers, etc.). |
| **3** | **Preflight audit refused** — terminal for this attempt until upstream work resolves the plan/clarify state. On the normal clarify path, the operator must run `/design <N>` before retrying `/implement`. When `STATE=ambiguous` from `"${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" clarify state`, Preflight exits **3** **before** posting or labeling; the thread must be repaired manually — exit **3** does **not** imply a new clarify request was posted. |

Do not treat every non-zero exit as a blind retry; route **3** back through `/design` / manual clarify repair, not generic re-invocation of `/implement` with the same inputs.

<!-- step:1 — Parse Arguments -->

Parse `$ARGUMENTS` as: first whitespace-separated token is the upstream issue number; any remaining tokens are passed through verbatim as extra flags to `/implement`.

```bash
read -r ISSUE_NUMBER EXTRA <<< "$ARGUMENTS"
if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
  echo "**ERROR: Usage: /agnix-fix <upstream-issue-number> [extra-flags...]**"
  exit 1
fi
```

<!-- step:2 — Verify Upstream Remote and Fetch Issue -->

Before touching the fork, confirm the current clone is wired to upstream `agent-sh/agnix` (matches `larch:set-up-forked-open-source-repo`'s output: `origin` is the fork, `upstream` is the canonical repo). Without this guard the skill would happily apply an agnix issue body to a wrong repository.

Strict owner/repo match — substring-style globs would silently accept `agent-sh/agnix-experimental`, `notagent-sh/agnix`, etc.

The typed GitHub command emits the exact JSON stream that `jq` parses; diagnostics remain on stderr.

```bash
UPSTREAM_REPO=agent-sh/agnix
UPSTREAM_NWO=$("${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" gh remote-repo upstream 2>/dev/null) || UPSTREAM_NWO=""
if [[ "$UPSTREAM_NWO" != "$UPSTREAM_REPO" ]]; then
  echo "**ERROR: 'upstream' remote resolves to '$UPSTREAM_NWO', not '$UPSTREAM_REPO'. /agnix-fix only runs from a clone whose upstream is agent-sh/agnix.**"
  exit 1
fi
if ! ISSUE_JSON=$("${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" gh agnix-issue \
  --issue "$ISSUE_NUMBER" --repo "$UPSTREAM_REPO"); then
  echo "**ERROR: typed issue read failed for $UPSTREAM_REPO#$ISSUE_NUMBER. Check authentication and that the issue exists.**"
  exit 1
fi

URL=$(echo "$ISSUE_JSON" | jq -r '.url')
STATE=$(echo "$ISSUE_JSON" | jq -r '.state')
TITLE=$(echo "$ISSUE_JSON" | jq -r '.title')
BODY=$(echo "$ISSUE_JSON" | jq -r '.body')

# PR detection by URL form (issue URLs are .../issues/<N>; PR URLs are .../pull/<N>).
if [[ "$URL" == *"/pull/"* ]]; then
  echo "**ERROR: $URL is a pull request, not an issue.**"
  exit 1
fi

if [[ "$STATE" != "OPEN" ]]; then
  echo "**ERROR: $URL is $STATE; only OPEN issues are accepted.**"
  exit 1
fi
```

<!-- step:3 — Provision skip-changelog Label on the Fork (Best-Effort) -->

The typed command lists the label state, creates the exact label only when absent, and re-reads after a concurrent-create response.

```bash
FORK_REPO=$("${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" gh resolve-repo 2>/dev/null) || FORK_REPO=""
if [[ -n "$FORK_REPO" ]]; then
  "${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" gh agnix-ensure-label --repo "$FORK_REPO" \
    >/dev/null 2>&1 || true
fi
```

Failure is non-fatal — the operator can add `[skip changelog]` to the PR title without the label.

<!-- step:4 — Operator briefing (no FEATURE_FILE handoff to /implement) -->

`/implement` Preflight reads the `larch:plan` block from GitHub via `scripts/larch.sh plan-block read` and wraps issue title/body/plan in the `<reviewer_issue_title>` / `<reviewer_issue_body>` / `<reviewer_plan>` trust-boundary envelope for the adequacy audit (`skills/implement/references/preflight-plan-audit.md`). Step 1 then re-fetches the full upstream issue into `$IMPLEMENT_TMPDIR/feature-description.txt` through its typed GitHub owner (with `--repo "$UPSTREAM_REPO"` under `--forked`). **Do not** compose a separate delimiter-wrapped `FEATURE_FILE` expecting `/implement` to consume it — the implementer path overwrites feature text from GitHub and does not treat ad-hoc local files as authoritative.

Before invoking `/implement`, keep the CI-monitoring and changelog guidance from this skill's **CI-monitoring contract** section in orchestrator context (and in PR titles / `CHANGELOG.md` as appropriate). The upstream issue body was already fetched in Step 2 for your own verification; `/implement` repeats the read against the same upstream issue number.

<!-- step:5 — Delegate to /implement -->

Invoke the Skill tool:

- Try skill `"implement"` first (bare name). On `Unknown skill`, try `"larch:implement"` (fully-qualified plugin name).
- args: --lifecycle-parent-context "$CONTEXT_FILE" --forked --coder=codex, then one ASCII space, then the upstream issue number `$ISSUE_NUMBER` as the **positional** `<issue-N>` tail, then optional `$EXTRA` tokens that `/implement` supports; omit `--auto` and verbal feature tails.

`--coder=codex` is passed explicitly so the auto-route to the main agent for small surgical plans (per issue #1481) does NOT fire on agnix work — agnix is a Rust codebase and Codex is the appropriate implementer regardless of plan size. Issue #1475 (the protected-path-modified false-positive) has landed, so the older `--coder=claude` workaround is no longer needed.

**Prerequisite**: `/design $ISSUE_NUMBER` must have written a valid `larch:plan` block to the upstream issue body before delegation — `/implement` rejects verbal feature argv and reads the plan from GitHub.

From character-ai/larch, MIT.

More from character-ai/larch