Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/meowsigma/stickyfingers

Repo-local workflow state, receipts, and AI coding CLI skills for Codex, Claude Code, and Qwen Code.
https://github.com/meowsigma/stickyfingers

agent-workflow ai-coding claude-code cli codex qwen-code skills

Last synced: about 1 month ago
JSON representation

Repo-local workflow state, receipts, and AI coding CLI skills for Codex, Claude Code, and Qwen Code.

Awesome Lists containing this project

README 

          
# Stickyfingers



[![CI](https://github.com/meowsigma/stickyfingers/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/meowsigma/stickyfingers/actions/workflows/ci.yml)

![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)

![License: MIT](https://img.shields.io/badge/license-MIT-green)



Stickyfingers is a Strict GSD fork baseline for AI coding CLIs: GSD planning

quality, Stickyfingers source-of-truth receipts, and Sticky-branded

Superpowers workflow overlays. The user-facing cockpit is `$sticky-where`, the

cold-resume dashboard for returning after breaks, context churn, or repo switches.



It gives Codex, Qwen Code, Claude Code, and human maintainers one shared place

to answer:



```text

Where are we?

What is blocked?

What proof exists?

What should happen next?

```



Plans guide execution. Receipts record reality. Requirements decide completion.

Canonical new planning state lives in GSD `.planning/`: project identity,

requirements, roadmap, phase plans, current state, and receipts. The forked GSD

source lives in `vendor/gsd/upstream/`. Stickyfingers additions live outside

that upstream tree as bridge code, cockpit rendering, receipts, imports, and

skill overlays.



## Commands Are Workflows



Stickyfingers commands are workflow launchers, like GSD or Maestro commands.

The command names choose a working mode; the agent handles the internal state

machinery.



You should be able to say:



```text

$sticky-where

what now?

plan this

do it

is it actually done?

```



The agent is responsible for translating that into Stickyfingers state:

milestones, phases, reqs, receipts, parked work, review findings, proof

commands, and `sticky audit`. You should not need to invent IDs, choose low-level

CLI flags, or understand the source-of-truth schema.



Use these workflow launchers first:



- `$sticky-where` - cold-resume cockpit: status, blockers, proof gap, and next move

- `$sticky-milestone` - start or reshape the project epic and prerequisite-ordered roadmap

- `$sticky-wonder` - step back and reassess direction

- `$sticky-discuss` - clarify ambiguous requirements or scope

- `$sticky-plan` - run GSD phase planning and checker loops

- `$sticky-execute` - do the next useful task and record reality

- `$sticky-verification-before-completion` - prove completion claims



The larger skill catalog is still available. It is an expert-mode palette, not

a prerequisite for normal use.



## Strict GSD Fork Workflow



Stickyfingers starts from GSD's `.planning/` workflow instead of old

flag-heavy milestone YAML. The normal path is:



1. Start or reshape a project with `$sticky-milestone`.

2. Let the agent ask the GSD milestone questions and create `.planning/`

   project, requirements, roadmap, and state files.

3. Resume with `$sticky-where`; it renders a Sticky cockpit from GSD planning

   state plus receipts.

4. Plan a phase with `$sticky-plan`; it is the Sticky version of GSD

   `plan-phase`, so it creates execution-grade `*-PLAN.md` files under

   `.planning/phases/`.

5. Execute with `$sticky-execute` or Sticky's Superpowers wrappers while

   recording receipts and proof.



Users should not manually type long `--id --phase --req` setup commands.

Sticky commands are agent workflows; the files are the durable truth.



## Workflow Substance



Stickyfingers borrows the useful parts of GSD, Maestro, and Superpowers without

making the user manage flags or state files. The agent should:



- ground discussion in `sticky where`, repo state, reqs, receipts, and dirty git

  status before asking the user anything

- convert `$sticky-where` into a readable cockpit routing report: project

  brief, roadmap, recent work, plan quality, proof gap, risk radar, questions

  to ask, workflow routing, do-not-touch boundaries, and exact next move

- draft a milestone brief before state changes: identity, outcome,

  existing baseline, dirty repo ownership, direction checkpoint,

  prerequisite-ordered phase roadmap, first-phase hard reqs, requirement

  coverage, proof plan, deferred work, and failure modes

- require every hard req to map to exactly one roadmap phase with observable

  success criteria before milestone state is created

- use `$sticky-wonder` for a direction brief when the goal itself may be wrong:

  identity, worthiness, alternatives, best path, tradeoffs, and state impact

- surface concrete gray areas and ask one question at a time when decisions are

  unclear

- run the `$sticky-plan` / GSD `plan-phase` context gate before writing phase detail, especially

  when existing docs, `.lovable/plan.md`, or active Stickyfingers state point in

  different directions

- make `$sticky-plan` write rich GSD phase plans under `.planning/`,

  not just a chat summary or thin receipt

- use gray-area detection for phase-specific decisions that repo inspection

  cannot answer and that would change reqs, proof, or phase placement

- create a context handoff for non-trivial `$sticky-discuss` sessions so later

  planning does not depend on chat memory

- turn approved decisions into reqs, receipts, review findings, or parked work

  instead of chat-only summaries

- run a req coverage matrix before execution so hard reqs, proof, wiring,

  regression risk, ownership, and deferred scope are covered

- run a plan checker pass for requirement coverage, task completeness,

  dependency correctness, key links, scope sanity, proof derivation, and context

  compliance

- fail `sticky audit` when an active hard-req phase has no execution-grade rich

  plan, stale rendered `PLAN.md`, missing active-phase goals/gates, or missing

  acceptance contracts

- treat quick work as lightweight but still source-of-truth tracked

- make `$sticky-execute` produce an execution report receipt with changed files,

  proof result, drift, and next action

- make `$sticky-execute` run execution preflight, follow deviation rules,

  checkpoint architecture/scope/product-direction changes, and use goal verification before completion claims

- make review/audit commands produce severity-ranked reports whose accepted

  blockers become Stickyfingers review findings

- use `sticky verify` as the command-backed quality gate before completion

  claims



The benchmark notes live in:



- [`docs/research/2026-05-05-gsd-maestro-substance-audit.md`](docs/research/2026-05-05-gsd-maestro-substance-audit.md)

- [`docs/research/2026-05-06-gsd-plan-milestone-execute-deep-dive.md`](docs/research/2026-05-06-gsd-plan-milestone-execute-deep-dive.md)

- [`docs/research/2026-05-06-rich-plan-artifact-audit.md`](docs/research/2026-05-06-rich-plan-artifact-audit.md)



Historical workflow proof lives in:



- [`docs/stickyfingers/dogfood/2026-05-06-m14-core-workflow-transcript.md`](docs/stickyfingers/dogfood/2026-05-06-m14-core-workflow-transcript.md)

- [`docs/stickyfingers/dogfood/2026-05-06-wrapper-usability-proof.md`](docs/stickyfingers/dogfood/2026-05-06-wrapper-usability-proof.md)

- [`docs/stickyfingers/dogfood/2026-05-06-first-time-user-proof.md`](docs/stickyfingers/dogfood/2026-05-06-first-time-user-proof.md)

- [`docs/stickyfingers/dogfood/2026-05-06-checkshot-real-project-dogfood.md`](docs/stickyfingers/dogfood/2026-05-06-checkshot-real-project-dogfood.md)



Practical examples live in:



- [`docs/stickyfingers/examples/first-run-existing-repo.md`](docs/stickyfingers/examples/first-run-existing-repo.md)

- [`docs/stickyfingers/examples/milestone-to-plan.md`](docs/stickyfingers/examples/milestone-to-plan.md)

- [`docs/stickyfingers/examples/wonder-pivot.md`](docs/stickyfingers/examples/wonder-pivot.md)

- [`docs/stickyfingers/examples/execute-review-verify.md`](docs/stickyfingers/examples/execute-review-verify.md)



## Quickstart



The 60-second version:



1. Install once.

2. Restart your AI coding CLI.

3. Open any repo.

4. Say `$sticky-where`.

5. Let the agent inspect, ask, draft, wait for approval, then maintain truth.



Install Stickyfingers for Codex from GitHub:



```bash

curl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | bash

```



Install or reinstall Stickyfingers for every supported local agent from GitHub:



```bash

curl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | STICKYFINGERS_AGENT_TARGET=all bash

```



Or install all supported agent skill folders from a checkout:



```bash

git clone https://github.com/meowsigma/stickyfingers.git

cd stickyfingers

python3 -m pip install -e .

scripts/install-agent-skills.sh all

```



Restart Codex, Qwen Code, or Claude Code. Then, inside the repo you want the

agent to work on, tell the coding agent:



```text

$sticky-where

```



The agent should take it from there. It will:



- inspect the repo, git status, and current Stickyfingers state

- explain what is active, blocked, proven, and next

- route itself to `$sticky-milestone`, `$sticky-wonder`, `$sticky-plan`,

  `$sticky-execute`, or another Stickyfingers skill when the situation calls

  for it

- ask 3-6 concrete project-epic milestone questions if source-of-truth state is

  missing or the milestone boundary is unclear

- draft the proposed milestone, prerequisite-ordered phase roadmap,

  first-phase req, and parked-work shape

- name dirty repo paths before approval, classify likely ownership, and state

  what the agent will not touch without approval

- ask a direction checkpoint question before writing state when existing plans,

  docs, or Stickyfingers state conflict with the proposed milestone or phase

- wait for explicit approval before creating or reshaping `.planning/`

- keep Sticky cockpit receipts and proof outside `vendor/gsd/upstream/` so the

  forked GSD source stays auditable

- after approval, run `sticky audit` and report the active reqs, proof needed,

  and next step



You should not need to hand-type long setup commands or memorize flags.



### Reinstall and repair if the CLI surface gets stale



If a CLI skill stops appearing in your agent after updates, run:



```bash

curl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | bash

```



For Codex, Qwen Code, and Claude Code together:



```bash

curl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | STICKYFINGERS_AGENT_TARGET=all bash

```



For a local checkout:



```bash

python3 -m pip install -e . --force-reinstall

scripts/install-agent-skills.sh all

scripts/check-agent-skill-visibility.sh all

```



Restart your AI coding CLI again and re-run:



```text

$sticky-where

```



Core first-time commands are:



- `$sticky-where` - run the cold-resume cockpit and get the next action

- `$sticky-milestone` - capture project-epic outcome and map the roadmap

- `$sticky-wonder` - run a direction reset when goals look wrong

- `$sticky-discuss` - clarify constraints, scope, and tradeoffs

- `$sticky-plan` - build an execution-grade phase plan

- `$sticky-execute` - do next-task work with receipts and proof

- `$sticky-verification-before-completion` - claim completion only with proof



## Existing Repos



Stickyfingers should not pretend an existing project is blank. In a repo with

`.planning/`, `$sticky-where` uses GSD progress inputs first, then overlays

Sticky cockpit receipts and proof. Without `.planning/`, it uses repo intake so

the agent can draft `$sticky-milestone` state from:



- repo signals such as README, package files, tests, docs, and planning files

- git dirtiness and sample changed paths

- likely baseline: existing repo versus empty/minimal repo

- agent guidance to summarize what already exists before drafting state



The agent should then ask about the next outcome, not the whole universe:



```text

What project-epic outcome should Stickyfingers track first, and what is already

done that should count as baseline instead of new work?

```



After that, the agent drafts the milestone and waits for explicit approval

before creating `.planning/`.



### Cold-Resume Cockpit (`$sticky-where`)



Use `$sticky-where` as the first command in any repo. It is the shared resume

surface for both empty and active workspaces:



- existing-repo intake when `.planning/` is not present

- active roadmap with phase progression and dependencies

- blockers, risk hints, and proof gap

- `next` routing to the right workflow command

- receipts and required commands already run



When state is missing, it should describe what was found, then guide toward

`$sticky-milestone` with a concise project-epic question.



## Everyday Workflow



Use `$sticky-*` commands as workflow launchers:



- "Where are we?"

- "What should we do next?"

- "This feels messy; help me organize it."

- "Implement the current plan and keep the source of truth updated."

- "Review this and record the findings."



Typical first move:



```text

$sticky-where

```



The agent reads Stickyfingers state first, then chooses the right internal

workflow. You can also name a mode directly when you know what kind of help you

want:



```text

$sticky-milestone

$sticky-wonder

$sticky-plan

$sticky-execute

$sticky-code-review

```



The agent uses low-level `sticky` CLI commands internally. Humans normally work

through the `$sticky-*` skills.



For quick fixes or one-session patches, keep using the same surface. The agent

should identify the req, receipt, review finding, or parked-work target, make

the change, record reality, attach proof when applicable, and run `sticky audit`

before claiming done.



For a local workflow smoke, run:



```bash

scripts/smoke-dogfood-workflow.sh

```



This creates a temporary repo, verifies missing-state routing, creates approved

state, records a receipt, runs command-backed proof through `sticky verify`, and

checks `sticky audit`.



Minimum user-facing workflow check list:



```bash

python3 -m pytest -q

scripts/install-agent-skills.sh all

scripts/check-agent-skill-visibility.sh all

scripts/smoke-dogfood-workflow.sh

```



After these pass, open any target repo and ask:



```text

$sticky-where

```



If that return is incomplete, this is the repair path before changing anything.



## Planning Artifacts



`$sticky-plan` is not a lightweight checklist. It is the Stickyfingers version

of GSD `plan-phase`: context gate, optional research, planner, plan checker,

bounded revision loop, requirement coverage gate, and execution handoff.



Canonical phase planning lives in GSD `.planning/`:



- `.planning/PROJECT.md`

- `.planning/REQUIREMENTS.md`

- `.planning/ROADMAP.md`

- `.planning/STATE.md`

- `.planning/phases/*`

- `.planning/receipts/*`



A good GSD phase plan records exact files, concrete actions, automated or

explicit proof, done criteria, requirement IDs, goal-backward `must_haves`,

dependencies, waves, threat model when needed, and verification criteria. The

plan checker rejects vague files, missing requirement coverage, broken

dependencies, missing key links, scope creep, scope reduction, ignored context,

and weak proof.



Humans usually should not run this by hand. The agent should use `$sticky-plan`

and handle the internal GSD planning workflow, `.planning/` file writes,

checker loop, and Sticky receipt itself. `sticky plan import/show/check` is

state-mode aware: `show/check` read GSD `.planning/phases/*-PLAN.md` files when

`.planning/` exists, while `import` remains legacy compatibility for older

`.stickyfingers` rich-plan YAML. Older legacy compatibility commands remain

for migration and auditability, not as the recommended first-use workflow.



## Advanced Skill Catalog



Most users can start with `$sticky-where` and let the agent route. These skills

are available when you want to force a specific workflow mode. More commands

are fine; the important rule is that each command should make the agent take

responsibility, not make the user manage Stickyfingers internals.



Core Stickyfingers skills:



- `$sticky-where` - show current milestone, blockers, receipts, proof, and next action

- `$sticky-milestone` - start or reshape the project epic and prerequisite-ordered phase roadmap

- `$sticky-discuss` - clarify goals, constraints, requirements, blockers, and evidence

- `$sticky-wonder` - reassess the project, goal, direction, milestone path, or pivot options

- `$sticky-plan` - GSD phase planning: context, research, PLAN.md files, checker loops, and handoff

- `$sticky-execute` - implement while recording receipts and proof

- `$sticky-code-review` - formal review with findings recorded into Stickyfingers state

- `$sticky-security-audit` - security review with source-of-truth findings

- `$sticky-seo-audit` - SEO review with source-of-truth findings



Use `$sticky-wonder` when you are not just brainstorming ideas inside a goal,

but questioning the goal itself: whether the project is coherent, whether the

current path is worth continuing, whether an external repo changes the plan, or

whether to pivot, simplify, continue, or stop.



Stickyfingers-native Superpowers wrappers:



These wrappers run the original Superpowers workflows 1:1. Stickyfingers does

not replace their hard gates, checklists, design docs, TDD rules, debugging

discipline, review loops, or verification rules. It adds a small prelude for

`sticky where` context and a small epilogue for receipts, req/proof updates,

parked work, and `sticky audit`.



- `$sticky-using-superpowers` - choose the right Stickyfingers workflow skill

- `$sticky-brainstorming` - explore options before creative work

- `$sticky-writing-plans` - write detailed implementation-plan documents

- `$sticky-executing-plans` - execute written plans task by task

- `$sticky-test-driven-development` - enforce failing-test-first behavior work

- `$sticky-subagent-driven-development` - execute plans with subagent task/review gates

- `$sticky-dispatching-parallel-agents` - coordinate independent parallel agents

- `$sticky-systematic-debugging` - debug from reproduced failures and evidence

- `$sticky-verification-before-completion` - prove claims before completion

- `$sticky-requesting-code-review` - prepare review requests with proof/state

- `$sticky-receiving-code-review` - turn review feedback into fixes/findings/decisions

- `$sticky-using-git-worktrees` - isolate work without losing source-of-truth state

- `$sticky-finishing-a-development-branch` - final branch proof and merge readiness

- `$sticky-writing-skills` - create/update skills with packaging and audit proof



## Workflow Scale



This vocabulary is mostly for agents and advanced review:



- **Milestone** - project epic, often multi-week.

- **Phase** - week-scale slice inside a milestone.

- **Req** - proof-backed requirement inside a phase.

- **Receipt** - small work event, patch, test run, decision, or session note.



Agents should not create milestones for quick fixes, copy changes, single

implementation sessions, or command-smoke followups. Those belong in reqs,

receipts, review findings, or phase work inside an approved milestone.



Project note: this repo's `M1`-`M13` history is legacy dogfood state from before

the milestone scale was corrected. Keep it for auditability; do not use it as

the model for future project planning.



## Install Details



The Python package installs the internal `sticky` command:



```bash

git clone https://github.com/meowsigma/stickyfingers.git

cd stickyfingers

python3 -m pip install -e .

sticky --help

```



For development:



```bash

python3 -m venv .venv

. .venv/bin/activate

python -m pip install -e '.[test]'

python -m pytest -q

```



Python 3.11 or newer is required.



Install AI coding CLI skills from the checkout:



```bash

scripts/install-agent-skills.sh all

```



Install or reinstall Codex directly from GitHub:



```bash

curl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | bash

```



For all supported agents from the same GitHub installer:



```bash

curl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | STICKYFINGERS_AGENT_TARGET=all bash

```



Install one target when needed:



```bash

scripts/install-agent-skills.sh codex

scripts/install-agent-skills.sh claude

scripts/install-agent-skills.sh qwen

```



Codex installs portable skills into `${CODEX_HOME:-$HOME/.codex}/skills`.

Claude Code installs portable skills into `$HOME/.claude/skills` as a fallback

and installs Stickyfingers as a local Claude plugin through

`.claude-plugin/marketplace.json`.

Qwen Code installs direct skill fallbacks into `$HOME/.qwen/skills` and, when

`qwen` is available, links this repo as a native Qwen extension.



Qwen Code can also install from GitHub:



```bash

qwen extensions install https://github.com/meowsigma/stickyfingers.git --ref main --consent

```



Pinning `--ref main` makes Qwen install the source tree directly. Without a

ref, Qwen may prefer release-download behavior that does not preserve this

repo's extension root layout.



For local Qwen development:



```bash

qwen extensions link /path/to/stickyfingers

qwen extensions list

```



If `$sticky-*` commands are not visible after this repo is linked, run:



```bash

scripts/install-agent-skills.sh qwen

scripts/check-agent-skill-visibility.sh qwen

```



Then restart Qwen Code before re-running:



```text

$sticky-where

```



## Agent Visibility Checks



Verify the installed skill pack:



```bash

scripts/check-agent-skill-visibility.sh codex

scripts/check-agent-skill-visibility.sh qwen

scripts/check-agent-skill-visibility.sh claude

```



Codex checks `codex debug prompt-input` so stale or invisible skills fail.

Qwen checks `qwen extensions list` and a debug startup log to prove Qwen's skill

manager parsed the Stickyfingers skills. Claude checks the fallback skill files,

the installed `stickyfingers@stickyfingers` plugin cache, and a Claude debug

startup log proving the plugin skills loaded.



Visibility checks prove installation and parsing. They do not prove that a model

selected the right skill in a real task. For that, inspect receipts for

`skills_used`, proof commands, changed files, and `sticky audit`.



## Source Of Truth



Canonical new planning state lives in GSD `.planning/`:



- `.planning/PROJECT.md`

- `.planning/REQUIREMENTS.md`

- `.planning/ROADMAP.md`

- `.planning/STATE.md`

- `.planning/phases/*`

- `.planning/receipts/*`



The forked GSD source lives in:



- `vendor/gsd/upstream/`



Stickyfingers additions live outside that upstream tree:



- `stickyfingers/gsd_bridge.py`

- `stickyfingers/gsd_cockpit.py`

- Sticky receipt/import/proof commands

- `skills/sticky-*/` overlays



Legacy compatibility truth remains readable as fallback only:



- `.stickyfingers/config.yaml`

- `.stickyfingers/milestones/*/milestone.yaml`

- `.stickyfingers/milestones/*/requirements.yaml`

- `.stickyfingers/milestones/*/plan.yaml`

- `.stickyfingers/milestones/*/context.yaml`

- `.stickyfingers/milestones/*/research.yaml`

- `.stickyfingers/milestones/*/inserts.yaml`

- `.stickyfingers/milestones/*/reviews.yaml`

- `.stickyfingers/ledger.jsonl`

- `.stickyfingers/archive/milestones/*/summary.json`

- `.stickyfingers/archive/compact/latest.json`



Legacy rendered output lives in:



- `.stickyfingers/STATE.md`

- `.stickyfingers/WORKMAP.md`

- `.stickyfingers/PLAN.md`

- `.stickyfingers/CONTEXT.md`

- `.stickyfingers/RESEARCH.md`

- `.stickyfingers/state.json`



Do not hand-edit canonical state unless repairing corruption. Prefer the AI

skills; agents should use the internal CLI so receipts and rendered state stay

consistent.



## Legacy Compatibility



Older Stickyfingers dogfood repos may still contain `.sticky/` or

`.stickyfingers/` state. Treat those paths as migration or compatibility

evidence, not the canonical first-use workflow for new projects.



Legacy v2 state can include:



- `.sticky/PROJECT.md`

- `.sticky/REQUIREMENTS.md`

- `.sticky/ROADMAP.md`

- `.sticky/STATE.md`

- `.sticky/state.json`



Older internal automation may also show exact `sticky v2 ...` and

flag-heavy `sticky milestone ...` commands. Those commands are compatibility

evidence for old dogfood history, not instructions for new users.



Do not lead new users with those commands. Use `$sticky-where` and the GSD

`.planning/` path first.



## Advanced: Internal CLI



The `sticky` terminal command is the state API used by agents, tests, and

debugging. It is intentionally lower-level than the `$sticky-*` product surface.



Useful diagnostics:



```bash

sticky where --no-color --width 80

sticky plan show

sticky plan check

sticky context show

sticky context check

sticky research show

sticky research check

sticky next --json

sticky verify --claim "tests pass" --command "pytest -q"

sticky verify --claim "REQ-1 is proven" --command "pytest -q" --req REQ-1

sticky verify --claim "ready" --suggest

sticky doctor --json

sticky doctor --fix

sticky audit

```



Optional local commit guard:



```bash

scripts/install-git-quality-guard.sh

```



It installs a git `pre-commit` hook that blocks commits when Stickyfingers is

initialized but `sticky audit` fails. Uninitialized repos are allowed with a

warning so first-time adoption does not block normal commits. Bypass

intentionally with `SKIP_STICKY_GUARD=1 git commit ...`.



Internal state mutation commands exist for agents, tests, and repair work, but

they are not the normal user workflow. A coding agent should translate plain

language into the right mutation, attach receipts/proof, and preserve GSD

`.planning/` truth. If you need to debug that layer directly, inspect

`sticky --help` and the focused command help for the exact operation.



If you are using Stickyfingers through an AI coding CLI, do not start here.

Start with `$sticky-where`.



## Verify The Install



Run the full repo suite:



```bash

cd /path/to/stickyfingers

python3 -m pytest -q

```



Run a black-box AI workflow smoke by asking the agent:



```text

$sticky-where

```



Expected behavior:



- missing state routes into a 3-6 question project-epic milestone interview

- the agent drafts `.planning/` state and waits for approval before

  creating it

- receipts record the relevant `$sticky-*` skill with `--skill`

- `sticky audit` passes before completion is claimed

- after closeout, `$sticky-where` reports the closed milestone and next action



For a terminal-only diagnostic smoke, use the advanced internal CLI commands

above.



## Troubleshooting



If `sticky` is missing:



```bash

cd /path/to/stickyfingers

python3 -m pip install -e .

```



If a target repo has no state, ask the agent for `$sticky-where`. It should

route itself into milestone setup, interview you, draft the initial state, and

wait for approval before creating it.



If rendered files are stale:



```bash

sticky doctor --json

sticky doctor --fix

sticky audit

```



If `audit` reports dirty files without receipts, tell the agent to record a

Stickyfingers receipt for the work. The internal form is:



```bash

sticky note "Recorded current change" --file path/to/file --skill sticky-execute --next "run audit"

```



If an AI coding CLI does not see the skills, reinstall them and restart the

agent:



```bash

scripts/install-agent-skills.sh codex

scripts/check-agent-skill-visibility.sh codex

scripts/install-agent-skills.sh qwen

scripts/check-agent-skill-visibility.sh qwen

scripts/install-agent-skills.sh claude

scripts/check-agent-skill-visibility.sh claude

```



If a skill feels slow to start, measure the agent prompt path before blaming the

Stickyfingers command count:



```bash

scripts/measure-agent-skill-load.sh

```



The benchmark compares an empty isolated Codex home, a `sticky-wonder`-only

home, an all-Stickyfingers home, and your current Codex home. A slow current

home with fast isolated homes usually points at broader Codex/plugin/session

latency, not Stickyfingers skill count. `$sticky-wonder` is designed to

respond first and inspect files lazily after the reassessment question is clear.



## Publish To GitHub



For a release-readiness pass:



```bash

cd /path/to/stickyfingers

python3 -m pytest -q

scripts/smoke-dogfood-workflow.sh

STICKY_BIN='python3 -m stickyfingers.cli' bash scripts/simulate-stickyfingers-mixed-workflow.sh

STICKY_BIN='python3 -m stickyfingers.cli' bash scripts/simulate-stickyfingers-webapp-hard-workflow.sh

STICKY_BIN='python3 -m stickyfingers.cli' bash scripts/simulate-stickyfingers-edge-cases.sh

STICKY_BIN='python3 -m stickyfingers.cli' STICKY_REAL_REPO=/home/sigma/checkshot bash scripts/simulate-stickyfingers-real-project-bakeoff.sh

scripts/simulate-stickyfingers-github-install-smoke.sh

scripts/install-agent-skills.sh all

scripts/check-agent-skill-visibility.sh all

python3 -m stickyfingers.cli where --no-color --width 100

git status --short

git add .

git commit -m "prepare stickyfingers release"

git push origin main

scripts/production-readiness-check.sh

git tag -a v0.5.3 -m "Stickyfingers v0.5.3"

git push origin v0.5.3

gh release create v0.5.3 --title "Stickyfingers v0.5.3" --notes-file CHANGELOG.md

```



The current hostile limit evaluation is recorded in

[`docs/stickyfingers/dogfood/2026-05-10-limit-evaluation.md`](docs/stickyfingers/dogfood/2026-05-10-limit-evaluation.md).



## Project Status



Stickyfingers v0.5.3 is production-ready for GitHub-distributed AI coding CLI

use. The production gate covers the Python package build, the `sticky` CLI,

Codex/Qwen/Claude skill installation and visibility, strict GSD `.planning`

routing, real-project bakeoff, hostile simulations, clean GitHub install, and

Sticky audit/plan/doctor gates.



The supported production install path is the GitHub installer. PyPI publishing

is not the primary distribution channel for the skill bundle because the agent

skills and plugin manifests are repo assets as well as Python code.



See [`CHANGELOG.md`](CHANGELOG.md) for release notes.