@flickercloud/agent-skills

Flicker Agent Skills

First-party Flicker workflow skills for Pi, Claude Code, and Codex. They use the public flicker CLI/API and keep all durable work state in Flicker Tickets, current document heads, events, and memory.

Six-stage lifecycle

The public catalog is deliberately limited to six adjacent stages:

• flicker-plan — research, clarify, scope, define evidence, and select approved work.
• flicker-implement — code an approved contract with baseline/worktree/implementation evidence.
• flicker-test — independently regress and review the current head; issue PASS or REQUEST CHANGES.
• flicker-release — adversarial readiness review and explicitly authorized release actions.
• flicker-ship — one explicit ticket through implement/test/release and authorized normal-path merge; danger zones stop.
• flicker-recall — retrieve existing tickets, document heads, history, and memory with provenance.

Frontmatter descriptions are selection contracts: each says when to use the stage and which adjacent intent it must reject. Uncommon lifecycle detail is disclosed through the shared contract rather than repeated in every adapter.

Install

npx @flickercloud/agent-skills install all .
# or one host:
npx @flickercloud/agent-skills install claude-code
npx @flickercloud/agent-skills install pi . # project .pi/skills/
npx @flickercloud/agent-skills install pi   # global ~/.pi/agent/skills/
npx @flickercloud/agent-skills install codex .

Then:

flicker auth login <api-key>
flicker project use <project-slug>

The installer exposes the same six boundaries and copies the canonical contract for every host. Pi receives the shared workflow and all six canonical Agent Skill documents (not prompt-only adapters). See Pi, Claude Code, and Codex.

Update an existing installation

Updates are announced in the Flicker dashboard and by an interactive, once-daily CLI check. The check is suppressed for --json, cached for 24 hours, and never installs anything. flicker doctor reports the embedded, installed, and latest published workflow state explicitly.

Update through the Flicker CLI:

curl -fsSL https://flicker.run/install.sh | sh
flicker skill update --workflow --global
flicker doctor

Or update a Pi installation directly from npm:

npx @flickercloud/agent-skills@latest install pi
flicker doctor

Restart Pi, Claude Code, or Codex after installation so the harness reloads its skills. The global Pi installer disables only byte-exact, known Flicker 0.1.x prompt adapters by renaming them with .disabled-by-flicker-0.2.0; user-edited prompts and active/backup conflicts are preserved.

Workflow behavior

Planning inspects current ticket/document heads, memory, repository evidence, prior art, callers/contracts/tests, and authoritative sources before asking answerable questions. Consequential ambiguity is presented as choices with consequences and a recommendation. Planning itself is non-writing; an executable spike requires an explicitly approved child ticket entering implement/worktree/evidence.

Delivery preserves dedicated-worktree/one-writer behavior, green baselines, original-failure-first bug proof, vertical slices, changed-area regression, current-head review, bounded no-progress circuit breakers, additive risk checks, danger-zone escalation, merge-to-done, and explicit current-turn release authority. The shared contract contains the complete document/evidence schemas.

Flicker Tickets remain the only workflow ledger. This package adds no local state machine, alternate tracker, or model-runtime dependency.

Canonical source and generated projections

Editable sources:

shared/flicker-workflow.md     # single lifecycle/evidence/safety contract
skills/flicker-*/SKILL.md      # six canonical selection/stage adapters

Generated, checked-in projections:

prompts/flicker-*.md           # generated compatibility prompt adapters (not Pi install surface)
commands/flicker-*.md          # Claude Code commands
codex/AGENTS.md                # Codex instructions
../../cli/skill/workflow/*.md  # workflow embedded in the public CLI

After editing a canonical file, run:

npm --prefix packages/flicker-agent run sync
npm --prefix packages/flicker-agent test

sync --check and package validation fail on drift; do not hand-edit generated projections. scripts/publish-workflow-mirror.sh consumes the synchronized CLI projection.

Trigger metadata lint and behavioral evaluation

eval/routing-fixtures.json is deliberately a trigger-metadata lint, not proof of host routing. It rejects malformed/unknown fields, ranks positive and hostile adjacent-stage negatives, and requires ambiguity candidates to be the leading pair within the catalog's declared margin with expected: "clarify". Mutation proofs cover a degraded description, a third-skill/invalid ambiguity outcome, and malformed fields. Actual six-skill catalog selection and adjacent-stage clarification are validation scenarios in the live evaluation.

eval/behavior-scenarios.json has visible train and validation coverage for every skill; it does not call co-edited fixtures blind or held out. Live arms are scenario-seeded and counterbalanced. Candidate output must be one JSON object with exact deterministic fields, while an independent rubric command grades the declared semantic criteria. Reports retain exact prompts, candidate/rubric stdout and stderr, statuses, order, model/revision/harness/settings/seed/commands, full-byte fixture/workflow/stage/projection hashes, and per-split/per-scenario/per-skill paired summaries.

Validation gates run per scenario and per skill, so aggregate gains cannot hide a regression. Negative validation delta fails. Zero means neutral non-regression—not improvement—and passes only when every with-skill validation repeat passes. Positive means improvement. --baseline=<report> pins a compatible prior report by fixture/model/revision/harness/surface/settings/repeat and records its report/projection hashes; --verify-report=<report> rejects stale hashes, altered raw grades/summaries, or false-green gates.

Deterministic proof (no model or result claim):

npm --prefix packages/flicker-agent run eval:dry -- --surface=canonical # also pi|claude|codex
npm --prefix packages/flicker-agent run eval:degraded
npm --prefix packages/flicker-agent run eval:mutations

Live paired run (candidate and independent rubric commands read stdin):

FLICKER_SKILL_EVAL_COMMAND='your-agent --print' \
FLICKER_SKILL_EVAL_RUBRIC_COMMAND='independent-rubric-agent --print' \
FLICKER_SKILL_EVAL_MODEL='provider/model' \
FLICKER_SKILL_EVAL_MODEL_REVISION='revision' \
FLICKER_SKILL_EVAL_HARNESS='host/version' \
FLICKER_SKILL_EVAL_SURFACE='canonical' \
FLICKER_SKILL_EVAL_SETTINGS='temperature=0, seed=123 where supported' \
FLICKER_SKILL_EVAL_SEED='recorded-seed' \
FLICKER_SKILL_EVAL_REPEAT=4 \
npm --prefix packages/flicker-agent run eval:live -- \
  --output=/absolute/path/to/flicker-skill-eval.json \
  --baseline=/absolute/path/to/pinned-baseline.json

Model credentials/execution are external. A dry-run is never represented as a behavioral result.

Stocktakes

npm --prefix packages/flicker-agent run stocktake:changed
npm --prefix packages/flicker-agent run stocktake:preflight
npm --prefix packages/flicker-agent run stocktake:release -- --release-report=/absolute/path/to/live-report.json

Changed and preflight stocktakes are deterministic and make no behavioral release claim. Release stocktake is separate and requires a retained live report whose raw outcomes, gates, and current fixture/projection hashes verify.

Layout

shared/                      canonical contract + profile schema
skills/                      six canonical stage adapters
prompts/, commands/, codex/  generated host projections
eval/                        routing and paired behavior fixtures
scripts/sync.mjs             projection generator/checker
scripts/validate.mjs         deterministic package validator
scripts/evaluate.mjs         paired benchmark harness
scripts/stocktake.mjs        changed/full maintenance gates
docs/provenance.md           donor/reference attribution

Safety and provenance

Current ticket fields/document heads override history. On HTTP 409, re-read and ask before replacing concurrent work. Never write the default branch or merge/deploy/publish/upload/release without the authority required by the shared contract.

Bigpowers was reviewed as an MIT-licensed donor/reference, not installed or copied as a lifecycle. See workflow provenance.