173 lines
8.3 KiB
Markdown
173 lines
8.3 KiB
Markdown
# Higgsfield pack: design
|
|
|
|
Date: 2026-09-30. Contract: `.claude/tasks/contracts/2026-09-30-higgsfield-pack-1412.md`
|
|
(binding: request, clarifications, 14 acceptance criteria).
|
|
Revision 2, after the three-lens plan challenge: changes marked `[r2]`.
|
|
|
|
## Goal
|
|
|
|
Generate images, video, audio and brand media from Claude Code through the
|
|
Higgsfield CLI, and have `make plugin` reproduce the setup on any machine.
|
|
The pack costs nothing when unused: it is installed on disk, linked on demand.
|
|
|
|
## Decisions (validated by the user)
|
|
|
|
- Two toggles in `lib/toggle-external.sh`, both off by default, additive on
|
|
any profile: `higgsfield` (7 media skills) and `higgsfield-websites` (one
|
|
skill).
|
|
- `higgsfield-websites` is an aid for landing pages inside the existing
|
|
Design work stack and site rules: assets and references. Never
|
|
`higgsfield website create|deploy|publish`.
|
|
- Skills come from a git clone of `higgsfield-ai/skills` (tracks `main`),
|
|
not from `npx skills add`, which re-links every skill on each refresh.
|
|
- CLI `@higgsfield/cli` at `latest` (21st precedent).
|
|
- Routing lines in `CLAUDE.global.md`: explicit ask → enable the toggle →
|
|
follow the skill.
|
|
- The two dead login offers already in `install-plugins.sh` (ctx7, 21st) are
|
|
fixed here: they test stdout, which is the `tee` pipe.
|
|
- `settings.json` denies the `npm i -g` aliases (done by hand, outside the
|
|
installer).
|
|
|
|
## Units
|
|
|
|
### `lib/higgsfield-skills.sh` (new, sourced)
|
|
|
|
Owns everything the installers and the doctor share.
|
|
|
|
- `HIGGSFIELD_SKILLS_URL`: defaults to
|
|
`https://github.com/higgsfield-ai/skills.git`; an env value wins (tests
|
|
point it at a local fixture repo).
|
|
- `higgsfield_sync_skills <repo>`: `git clone --depth 1` into a stage
|
|
created inside `<repo>/skills-external/` `[r2]`, so each replacement is a
|
|
rename on one filesystem. Every real `higgsfield-*/` directory of the
|
|
clone that holds a `SKILL.md` replaces `<repo>/skills-external/<name>`;
|
|
symlinked entries are skipped `[r2]`; a skill counts only once its move
|
|
succeeded `[r2]`. Prints the number of skills synced. Returns non-zero,
|
|
leaving the existing copies untouched, when the clone fails or yields no
|
|
skill. The clone never prompts for credentials `[r2]`. Always removes the
|
|
stage. Nothing else from upstream is kept (`setup`, `scripts/`, plugin
|
|
manifests, `.git`).
|
|
- `higgsfield_cli_ok` `[r2]`: the binary answers (`higgsfield version`).
|
|
`command -v` alone only proves the npm shim: the binary is vendored by a
|
|
postinstall script that npm may hold back, on a first install or on any
|
|
later update.
|
|
- `higgsfield_signed_in`: `higgsfield auth token` succeeds.
|
|
- Both probes run silently and for 15 s at most. The CLI is closed source,
|
|
so its output never reaches a terminal or a log.
|
|
|
|
Depends on: `git`, `mktemp`, optionally `timeout`. No dependency on the
|
|
repo's other libs.
|
|
|
|
### `install-plugins.sh`: Step 8.6, between 8.5 and 8.7
|
|
|
|
1. CLI: `higgsfield_cli_ok` → `ok`. Otherwise `npm install -g` the lock
|
|
version, then the probe again as the proof; failure prints the manual
|
|
command with `--allow-scripts=@higgsfield/cli`.
|
|
2. Skills: only when the CLI answers, `higgsfield_sync_skills "$REPO"`. A
|
|
failed sync is one `warn` (existing copies kept) `[r2]`.
|
|
3. Sign-in: signed in → `ok`. Otherwise, stdin is a terminal → offer
|
|
`higgsfield auth login` (default no). Else an `info` line with the
|
|
command.
|
|
4. Nothing is linked. The summary block lists the pack and both toggles.
|
|
|
|
Step 8.6 runs before the `apply_effort_pins` call of Step 8.7, so the
|
|
"pins after the last vendoring step" order holds (BDR-108).
|
|
|
|
The ctx7 (Step 6) and 21st (Step 8.7) login offers change from
|
|
`[ -t 0 ] && [ -t 1 ]` to `[ -t 0 ]`.
|
|
|
|
### `update-all.sh`: block before 7.4
|
|
|
|
CLI absent → `info`, skip. Else `npm install -g` the lock version, then the
|
|
probe: a shim left without its binary gets a `warn` with the remedy, never a
|
|
success line `[r2]`. Then `higgsfield_sync_skills "$REPO"`. A parked skill is
|
|
a symlink in `skills-disabled/` pointing at `skills-external/<name>`:
|
|
replacing the source keeps the parked state.
|
|
|
|
### `lib/toggle-external.sh`
|
|
|
|
- `MANAGED_TOOLS` gains `higgsfield` and `higgsfield-websites`.
|
|
- `HIGGSFIELD_MEDIA_SKILLS` `[r2]`: the seven media skill names, an explicit
|
|
allowlist. Upstream is unpinned, so a skill it adds or renames is never
|
|
linked without an edit here (default deny).
|
|
- `higgsfield_skills()`: the allowlisted names synced under
|
|
`skills-external/`. `higgsfield_unlisted()` `[r2]`: synced `higgsfield-*`
|
|
skills that no tool owns.
|
|
- The three pack arms (status, disable, enable) serve `21st|higgsfield`
|
|
through `pack_skills <tool>`. Messages use the tool name. Status is
|
|
`enabled` when any member is linked.
|
|
- `pack_hints <tool>`, after a pack enable and after
|
|
`enable higgsfield-websites` `[r2]`: warns (never blocks) when the CLI is
|
|
missing, does not answer, or is signed out, and names each unlisted
|
|
skill. Its probes go through `bounded`, a local twin of the helper's
|
|
probe `[r2]`: this script takes no new `source` (four fixture suites copy
|
|
it alone).
|
|
- `higgsfield-websites` joins the single-symlink arm, source
|
|
`skills-external/higgsfield-websites`.
|
|
- Header: two tool lines after `21st`; `usage()` prints them.
|
|
|
|
### `doctor.sh`: section 4
|
|
|
|
CLI answers → `pass` with its version, then signed in → `pass`, else `info`
|
|
naming `higgsfield auth login`. Shim on PATH without its binary → `info`
|
|
with the remedy `[r2]`. Absent → `info`. Never `warn`, never `fail`.
|
|
|
|
### Config and docs
|
|
|
|
- `plugins.lock.json`: `higgsfield` entry (source, version, note naming the
|
|
skills repo and the toggles; no `managed_by`).
|
|
- `.gitignore`: `skills/higgsfield-*`, `skills-external/higgsfield-*/` and
|
|
the sync stage `skills-external/.higgsfield-stage.*/` `[r2]`.
|
|
- `CLAUDE.global.md`, Skill routing, 6 lines `[r2]` (306 → 312, guard 320):
|
|
|
|
```
|
|
- Media generation (image, video, audio, brand kit), explicit ask →
|
|
Higgsfield pack, off by default: `bash ~/.claude/lib/toggle-external.sh
|
|
enable higgsfield`, then Read the skill under `~/.claude/skills/`;
|
|
`higgsfield generate cost` before a paid run. Landing page "with
|
|
Higgsfield", named ask → `enable higgsfield-websites`: an aid inside
|
|
Design work and the site rules, never `website create|deploy|publish`.
|
|
```
|
|
- `README.md`: `### Higgsfield CLI` after the 21st section.
|
|
- `CHANGELOG.md`: `[Unreleased]` bullets under Added, Security, Fixed.
|
|
|
|
## Not changed, on purpose
|
|
|
|
`link.sh`, `lib/profile.sh`, every `lib/profiles/*.profile`,
|
|
`lib/effort-pins.txt`, hooks. Listing the pack in any of them would either
|
|
re-enable it on every `make link` or pull it into the profile census.
|
|
|
|
## Error handling
|
|
|
|
| Case | Behaviour |
|
|
|---|---|
|
|
| npm install fails, or the binary is not vendored | `err` with the `--allow-scripts` command; the step goes on, skills skipped |
|
|
| an update leaves the shim without its binary | `warn` with the remedy; doctor says so at info level; the toggle names that cause |
|
|
| clone fails, or upstream holds no skill | copies kept, one `warn` |
|
|
| upstream adds or renames a skill | synced, reported by the toggle, not linked |
|
|
| toggle enabled, CLI missing, mute or signed out | links created, `warn` |
|
|
| `enable` with no source | `err` naming the path checked, rc 1 |
|
|
|
|
## Tests: `lib/tests/higgsfield.test.sh`
|
|
|
|
Hermetic: a mktemp repo holding copies of `toggle-external.sh` and
|
|
`gstack-removed.sh`; a local git repo as the skills source; fake
|
|
`higgsfield` and `21st` first on PATH; a clean PATH built from symlinks for
|
|
the no-CLI cases, so the suite behaves the same whatever is installed.
|
|
|
|
Named cases (the contract's oracle greps them): `SYNC_MOVES_PACK_ONLY`,
|
|
`SYNC_REFRESH_DROPS_STALE`, `SYNC_KEEPS_PARKED`, `SYNC_FAIL_KEEPS_COPY`,
|
|
`PROBES_SILENT`, `STATUS_STATES`, `ENABLE_PACK_EXCLUDES_WEBSITES`,
|
|
`UNLISTED_NOT_LINKED`, `ENABLE_WEBSITES_ALONE`, `DISABLE_PARKS`,
|
|
`SIGNED_OUT_WARNS`, `ENABLE_MISSING_ERRS`, `PACK_21ST_UNCHANGED`,
|
|
`OFF_BY_DEFAULT_WIRING`, `INSTALL_WIRING`, `UPDATE_WIRING`.
|
|
|
|
## Known limits
|
|
|
|
- Upstream prompts change with no diff to review (same trade-off as 21st).
|
|
- A skill that upstream removes or renames keeps its last local copy.
|
|
- Each upstream skill reinstalls the CLI through `curl | sh` when
|
|
`higgsfield` is off PATH. With the CLI installed by npm this never fires,
|
|
and the deny rule on `* | sh` blocks it anyway.
|
|
- `higgsfield auth token` locality is unverified, hence the 15 s bound.
|