feat: add setup skill/hooks and update shadow (task 0018) #19

alexion · 2026-07-14T11:27:31-04:00

alexion commented

2026-07-14 11:27:31 -04:00

Task: .claude/tasks/0018-setup-skill-and-hooks.md

Summary

Distributes gitea-axi's ambient context through explicit user actions (ADRs 0009 and 0013) — no postinstall script.

Bundled Agent Skill at skills/gitea-axi/SKILL.md, shipped via a new "skills" entry in package.json's files. It is a minimal pointer (trigger description, when-to-use over tea/raw API/git, command-group one-liners, and dashboard/--help discovery pointers), not a command reference.
gitea-axi setup installs the skill into ~/.claude/skills/ idempotently, reporting installed / updated / unchanged.
gitea-axi setup hooks registers a SessionStart hook (running the bare dashboard) for Claude Code, Codex, and OpenCode via the SDK's installSessionStartHooks(), updating managed entries in place on re-run.
gitea-axi update shadows the SDK's built-in self-update: it fails with VALIDATION_ERROR and a help line pointing at npm install -g gitea-axi@latest, so the SDK's UPDATE_ERROR never surfaces and the ten-code error list stays intact.

Integration tests drive all three at the CLI seam against a temporary HOME, asserting the real skill file and the three managed hook configs are written and updated in place. These commands make no Gitea API calls, so there is no live-Gitea e2e case.

Deviations

The implementation was written before this cycle's tests, then tests were authored test-first-style by a sub-agent from the public interface only; the RED step confirmed green (code already existed) rather than a genuine failure. Expected values were derived from the spec/ADRs as independent literals.
setup hooks passes shouldInstall: () => true to installSessionStartHooks(): the SDK's auto-install safety gate is tuned for an inferred dist/bin/<name>.js entrypoint that gitea-axi does not use (its entrypoint is dist/main.js), and this is an explicit user command, so gating on the entrypoint layout is inappropriate.
Follow-up (out of scope): ADR 0009 mentions the dashboard suggestion table hinting at setup for discoverability. That is not in this task's acceptance criteria and would touch task 0017's dashboard.ts, so it is left as a follow-up; setup is currently discoverable via the top-level --help.

Review

Risk

Overall: Medium

Blast radius: Low — two new isolated commands plus a five-line wiring change in cli.ts; no existing behavior modified.
Reversibility: Low — all-additive (new files, one package.json files entry); trivially revertible, no migrations or published-schema changes.
Test coverage: Low — setup idempotency, hook installation for all three integrations, dispatch errors, skill markdown, and the shadowed update are all covered.
Sensitive domain: Medium — no auth/permissions, but setup/setup hooks write into ~/.claude, ~/.codex, and ~/.config/opencode, modifying user agent config outside the repo.
Size & complexity: Low — ~180 lines of straightforward control flow; no tangled logic.
Runtime criticality: Medium — explicit user-invoked dev tooling, not a hot path, but it mutates real home-directory config files that other agents load at session start.

Standards / Spec findings left unaddressed

Standards (judgement — Duplicated Code): the unknown-subcommand / unexpected-argument axiError(..., "VALIDATION_ERROR", ...) throw shape recurs across setup.ts and label.ts. Left as-is: it is a pre-existing repo-wide dispatch pattern, not a diff-local defect, so it should be addressed repo-wide if at all.
Standards (judgement — Primitive Obsession): setupHooks uses an inline status: "installed" string while the skill path has a SkillStatus union type. Left as-is: the hooks status is an always-fixed literal, not a computed enum, so a shared type would be unwarranted ceremony.
Spec (soft gap): the dashboard setup discovery hint from ADR 0009 — see the out-of-scope follow-up above.

Task: `.claude/tasks/0018-setup-skill-and-hooks.md` ## Summary Distributes gitea-axi's ambient context through explicit user actions (ADRs 0009 and 0013) — no postinstall script. - **Bundled Agent Skill** at `skills/gitea-axi/SKILL.md`, shipped via a new `"skills"` entry in `package.json`'s `files`. It is a minimal pointer (trigger description, when-to-use over `tea`/raw API/`git`, command-group one-liners, and dashboard/`--help` discovery pointers), not a command reference. - **`gitea-axi setup`** installs the skill into `~/.claude/skills/` idempotently, reporting `installed` / `updated` / `unchanged`. - **`gitea-axi setup hooks`** registers a SessionStart hook (running the bare dashboard) for Claude Code, Codex, and OpenCode via the SDK's `installSessionStartHooks()`, updating managed entries in place on re-run. - **`gitea-axi update`** shadows the SDK's built-in self-update: it fails with `VALIDATION_ERROR` and a help line pointing at `npm install -g gitea-axi@latest`, so the SDK's `UPDATE_ERROR` never surfaces and the ten-code error list stays intact. Integration tests drive all three at the CLI seam against a temporary HOME, asserting the real skill file and the three managed hook configs are written and updated in place. These commands make no Gitea API calls, so there is no live-Gitea e2e case. ## Deviations - The implementation was written before this cycle's tests, then tests were authored test-first-style by a sub-agent from the public interface only; the RED step confirmed green (code already existed) rather than a genuine failure. Expected values were derived from the spec/ADRs as independent literals. - `setup hooks` passes `shouldInstall: () => true` to `installSessionStartHooks()`: the SDK's auto-install safety gate is tuned for an inferred `dist/bin/<name>.js` entrypoint that gitea-axi does not use (its entrypoint is `dist/main.js`), and this is an explicit user command, so gating on the entrypoint layout is inappropriate. - **Follow-up (out of scope):** ADR 0009 mentions the dashboard suggestion table hinting at `setup` for discoverability. That is not in this task's acceptance criteria and would touch task 0017's `dashboard.ts`, so it is left as a follow-up; `setup` is currently discoverable via the top-level `--help`. ## Review ### Risk **Overall: Medium** - Blast radius: Low — two new isolated commands plus a five-line wiring change in `cli.ts`; no existing behavior modified. - Reversibility: Low — all-additive (new files, one `package.json` `files` entry); trivially revertible, no migrations or published-schema changes. - Test coverage: Low — setup idempotency, hook installation for all three integrations, dispatch errors, skill markdown, and the shadowed `update` are all covered. - Sensitive domain: Medium — no auth/permissions, but `setup`/`setup hooks` write into `~/.claude`, `~/.codex`, and `~/.config/opencode`, modifying user agent config outside the repo. - Size & complexity: Low — ~180 lines of straightforward control flow; no tangled logic. - Runtime criticality: Medium — explicit user-invoked dev tooling, not a hot path, but it mutates real home-directory config files that other agents load at session start. ### Standards / Spec findings left unaddressed - **Standards (judgement — Duplicated Code):** the unknown-subcommand / unexpected-argument `axiError(..., "VALIDATION_ERROR", ...)` throw shape recurs across `setup.ts` and `label.ts`. Left as-is: it is a pre-existing repo-wide dispatch pattern, not a diff-local defect, so it should be addressed repo-wide if at all. - **Standards (judgement — Primitive Obsession):** `setupHooks` uses an inline `status: "installed"` string while the skill path has a `SkillStatus` union type. Left as-is: the hooks status is an always-fixed literal, not a computed enum, so a shared type would be unwarranted ceremony. - **Spec (soft gap):** the dashboard `setup` discovery hint from ADR 0009 — see the out-of-scope follow-up above.

alexion added 1 commit 2026-07-14 11:27:32 -04:00

feat: add setup skill/hooks and update shadow (task 0018)

CI / test (pull_request) Successful in 52s

Details

CI / test (push) Successful in 51s

Details

be7226b321

Distribute gitea-axi's ambient context via explicit user actions (ADRs
0009, 0013), with no postinstall script:

- Bundle the Agent Skill markdown at skills/gitea-axi/SKILL.md (a
  minimal pointer, not a command reference) and ship it via package.json
  files.
- Add `setup`, which installs the skill into ~/.claude/skills/
  idempotently (installed/updated/unchanged).
- Add `setup hooks`, which registers a SessionStart hook running the
  bare dashboard for Claude Code, Codex, and OpenCode via the SDK's
  installSessionStartHooks(), updating managed entries in place.
- Shadow the SDK's built-in `update` so it fails with VALIDATION_ERROR
  and points at the npm update command, keeping the ten-code error list
  intact.

Integration tests drive all three at the CLI seam against a temporary
HOME; these commands make no Gitea API calls, so there is no live-Gitea
e2e case.

alexion merged commit be7226b321 into main

2026-07-14 11:31:00 -04:00

alexion deleted branch task-0018-setup-skill-and-hooks

2026-07-14 11:31:00 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: alexion/gitea-axi#19