{"id":49782029,"url":"https://github.com/meowsigma/stickyfingers","last_synced_at":"2026-05-11T22:01:06.102Z","repository":{"id":355735079,"uuid":"1229371099","full_name":"meowsigma/stickyfingers","owner":"meowsigma","description":"Repo-local workflow state, receipts, and AI coding CLI skills for Codex, Claude Code, and Qwen Code.","archived":false,"fork":false,"pushed_at":"2026-05-05T01:33:58.000Z","size":254,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-05T03:30:48.432Z","etag":null,"topics":["agent-workflow","ai-coding","claude-code","cli","codex","qwen-code","skills"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meowsigma.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-05T01:17:46.000Z","updated_at":"2026-05-05T01:34:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"251ba65f-36b5-4bc7-ad82-9634774fdfcc","html_url":"https://github.com/meowsigma/stickyfingers","commit_stats":null,"previous_names":["meowsigma/stickyfingers"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/meowsigma/stickyfingers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meowsigma%2Fstickyfingers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meowsigma%2Fstickyfingers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meowsigma%2Fstickyfingers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meowsigma%2Fstickyfingers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meowsigma","download_url":"https://codeload.github.com/meowsigma/stickyfingers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meowsigma%2Fstickyfingers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32914533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"ssl_error","status_checked_at":"2026-05-11T17:08:45.420Z","response_time":120,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-workflow","ai-coding","claude-code","cli","codex","qwen-code","skills"],"created_at":"2026-05-11T22:00:38.515Z","updated_at":"2026-05-11T22:01:06.081Z","avatar_url":"https://github.com/meowsigma.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stickyfingers\n\n[![CI](https://github.com/meowsigma/stickyfingers/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/meowsigma/stickyfingers/actions/workflows/ci.yml)\n![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)\n![License: MIT](https://img.shields.io/badge/license-MIT-green)\n\nStickyfingers is a Strict GSD fork baseline for AI coding CLIs: GSD planning\nquality, Stickyfingers source-of-truth receipts, and Sticky-branded\nSuperpowers workflow overlays. The user-facing cockpit is `$sticky-where`, the\ncold-resume dashboard for returning after breaks, context churn, or repo switches.\n\nIt gives Codex, Qwen Code, Claude Code, and human maintainers one shared place\nto answer:\n\n```text\nWhere are we?\nWhat is blocked?\nWhat proof exists?\nWhat should happen next?\n```\n\nPlans guide execution. Receipts record reality. Requirements decide completion.\nCanonical new planning state lives in GSD `.planning/`: project identity,\nrequirements, roadmap, phase plans, current state, and receipts. The forked GSD\nsource lives in `vendor/gsd/upstream/`. Stickyfingers additions live outside\nthat upstream tree as bridge code, cockpit rendering, receipts, imports, and\nskill overlays.\n\n## Commands Are Workflows\n\nStickyfingers commands are workflow launchers, like GSD or Maestro commands.\nThe command names choose a working mode; the agent handles the internal state\nmachinery.\n\nYou should be able to say:\n\n```text\n$sticky-where\nwhat now?\nplan this\ndo it\nis it actually done?\n```\n\nThe agent is responsible for translating that into Stickyfingers state:\nmilestones, phases, reqs, receipts, parked work, review findings, proof\ncommands, and `sticky audit`. You should not need to invent IDs, choose low-level\nCLI flags, or understand the source-of-truth schema.\n\nUse these workflow launchers first:\n\n- `$sticky-where` - cold-resume cockpit: status, blockers, proof gap, and next move\n- `$sticky-milestone` - start or reshape the project epic and prerequisite-ordered roadmap\n- `$sticky-wonder` - step back and reassess direction\n- `$sticky-discuss` - clarify ambiguous requirements or scope\n- `$sticky-plan` - run GSD phase planning and checker loops\n- `$sticky-execute` - do the next useful task and record reality\n- `$sticky-verification-before-completion` - prove completion claims\n\nThe larger skill catalog is still available. It is an expert-mode palette, not\na prerequisite for normal use.\n\n## Strict GSD Fork Workflow\n\nStickyfingers starts from GSD's `.planning/` workflow instead of old\nflag-heavy milestone YAML. The normal path is:\n\n1. Start or reshape a project with `$sticky-milestone`.\n2. Let the agent ask the GSD milestone questions and create `.planning/`\n   project, requirements, roadmap, and state files.\n3. Resume with `$sticky-where`; it renders a Sticky cockpit from GSD planning\n   state plus receipts.\n4. Plan a phase with `$sticky-plan`; it is the Sticky version of GSD\n   `plan-phase`, so it creates execution-grade `*-PLAN.md` files under\n   `.planning/phases/`.\n5. Execute with `$sticky-execute` or Sticky's Superpowers wrappers while\n   recording receipts and proof.\n\nUsers should not manually type long `--id --phase --req` setup commands.\nSticky commands are agent workflows; the files are the durable truth.\n\n## Workflow Substance\n\nStickyfingers borrows the useful parts of GSD, Maestro, and Superpowers without\nmaking the user manage flags or state files. The agent should:\n\n- ground discussion in `sticky where`, repo state, reqs, receipts, and dirty git\n  status before asking the user anything\n- convert `$sticky-where` into a readable cockpit routing report: project\n  brief, roadmap, recent work, plan quality, proof gap, risk radar, questions\n  to ask, workflow routing, do-not-touch boundaries, and exact next move\n- draft a milestone brief before state changes: identity, outcome,\n  existing baseline, dirty repo ownership, direction checkpoint,\n  prerequisite-ordered phase roadmap, first-phase hard reqs, requirement\n  coverage, proof plan, deferred work, and failure modes\n- require every hard req to map to exactly one roadmap phase with observable\n  success criteria before milestone state is created\n- use `$sticky-wonder` for a direction brief when the goal itself may be wrong:\n  identity, worthiness, alternatives, best path, tradeoffs, and state impact\n- surface concrete gray areas and ask one question at a time when decisions are\n  unclear\n- run the `$sticky-plan` / GSD `plan-phase` context gate before writing phase detail, especially\n  when existing docs, `.lovable/plan.md`, or active Stickyfingers state point in\n  different directions\n- make `$sticky-plan` write rich GSD phase plans under `.planning/`,\n  not just a chat summary or thin receipt\n- use gray-area detection for phase-specific decisions that repo inspection\n  cannot answer and that would change reqs, proof, or phase placement\n- create a context handoff for non-trivial `$sticky-discuss` sessions so later\n  planning does not depend on chat memory\n- turn approved decisions into reqs, receipts, review findings, or parked work\n  instead of chat-only summaries\n- run a req coverage matrix before execution so hard reqs, proof, wiring,\n  regression risk, ownership, and deferred scope are covered\n- run a plan checker pass for requirement coverage, task completeness,\n  dependency correctness, key links, scope sanity, proof derivation, and context\n  compliance\n- fail `sticky audit` when an active hard-req phase has no execution-grade rich\n  plan, stale rendered `PLAN.md`, missing active-phase goals/gates, or missing\n  acceptance contracts\n- treat quick work as lightweight but still source-of-truth tracked\n- make `$sticky-execute` produce an execution report receipt with changed files,\n  proof result, drift, and next action\n- make `$sticky-execute` run execution preflight, follow deviation rules,\n  checkpoint architecture/scope/product-direction changes, and use goal verification before completion claims\n- make review/audit commands produce severity-ranked reports whose accepted\n  blockers become Stickyfingers review findings\n- use `sticky verify` as the command-backed quality gate before completion\n  claims\n\nThe benchmark notes live in:\n\n- [`docs/research/2026-05-05-gsd-maestro-substance-audit.md`](docs/research/2026-05-05-gsd-maestro-substance-audit.md)\n- [`docs/research/2026-05-06-gsd-plan-milestone-execute-deep-dive.md`](docs/research/2026-05-06-gsd-plan-milestone-execute-deep-dive.md)\n- [`docs/research/2026-05-06-rich-plan-artifact-audit.md`](docs/research/2026-05-06-rich-plan-artifact-audit.md)\n\nHistorical workflow proof lives in:\n\n- [`docs/stickyfingers/dogfood/2026-05-06-m14-core-workflow-transcript.md`](docs/stickyfingers/dogfood/2026-05-06-m14-core-workflow-transcript.md)\n- [`docs/stickyfingers/dogfood/2026-05-06-wrapper-usability-proof.md`](docs/stickyfingers/dogfood/2026-05-06-wrapper-usability-proof.md)\n- [`docs/stickyfingers/dogfood/2026-05-06-first-time-user-proof.md`](docs/stickyfingers/dogfood/2026-05-06-first-time-user-proof.md)\n- [`docs/stickyfingers/dogfood/2026-05-06-checkshot-real-project-dogfood.md`](docs/stickyfingers/dogfood/2026-05-06-checkshot-real-project-dogfood.md)\n\nPractical examples live in:\n\n- [`docs/stickyfingers/examples/first-run-existing-repo.md`](docs/stickyfingers/examples/first-run-existing-repo.md)\n- [`docs/stickyfingers/examples/milestone-to-plan.md`](docs/stickyfingers/examples/milestone-to-plan.md)\n- [`docs/stickyfingers/examples/wonder-pivot.md`](docs/stickyfingers/examples/wonder-pivot.md)\n- [`docs/stickyfingers/examples/execute-review-verify.md`](docs/stickyfingers/examples/execute-review-verify.md)\n\n## Quickstart\n\nThe 60-second version:\n\n1. Install once.\n2. Restart your AI coding CLI.\n3. Open any repo.\n4. Say `$sticky-where`.\n5. Let the agent inspect, ask, draft, wait for approval, then maintain truth.\n\nInstall Stickyfingers for Codex from GitHub:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | bash\n```\n\nInstall or reinstall Stickyfingers for every supported local agent from GitHub:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | STICKYFINGERS_AGENT_TARGET=all bash\n```\n\nOr install all supported agent skill folders from a checkout:\n\n```bash\ngit clone https://github.com/meowsigma/stickyfingers.git\ncd stickyfingers\npython3 -m pip install -e .\nscripts/install-agent-skills.sh all\n```\n\nRestart Codex, Qwen Code, or Claude Code. Then, inside the repo you want the\nagent to work on, tell the coding agent:\n\n```text\n$sticky-where\n```\n\nThe agent should take it from there. It will:\n\n- inspect the repo, git status, and current Stickyfingers state\n- explain what is active, blocked, proven, and next\n- route itself to `$sticky-milestone`, `$sticky-wonder`, `$sticky-plan`,\n  `$sticky-execute`, or another Stickyfingers skill when the situation calls\n  for it\n- ask 3-6 concrete project-epic milestone questions if source-of-truth state is\n  missing or the milestone boundary is unclear\n- draft the proposed milestone, prerequisite-ordered phase roadmap,\n  first-phase req, and parked-work shape\n- name dirty repo paths before approval, classify likely ownership, and state\n  what the agent will not touch without approval\n- ask a direction checkpoint question before writing state when existing plans,\n  docs, or Stickyfingers state conflict with the proposed milestone or phase\n- wait for explicit approval before creating or reshaping `.planning/`\n- keep Sticky cockpit receipts and proof outside `vendor/gsd/upstream/` so the\n  forked GSD source stays auditable\n- after approval, run `sticky audit` and report the active reqs, proof needed,\n  and next step\n\nYou should not need to hand-type long setup commands or memorize flags.\n\n### Reinstall and repair if the CLI surface gets stale\n\nIf a CLI skill stops appearing in your agent after updates, run:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | bash\n```\n\nFor Codex, Qwen Code, and Claude Code together:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | STICKYFINGERS_AGENT_TARGET=all bash\n```\n\nFor a local checkout:\n\n```bash\npython3 -m pip install -e . --force-reinstall\nscripts/install-agent-skills.sh all\nscripts/check-agent-skill-visibility.sh all\n```\n\nRestart your AI coding CLI again and re-run:\n\n```text\n$sticky-where\n```\n\nCore first-time commands are:\n\n- `$sticky-where` - run the cold-resume cockpit and get the next action\n- `$sticky-milestone` - capture project-epic outcome and map the roadmap\n- `$sticky-wonder` - run a direction reset when goals look wrong\n- `$sticky-discuss` - clarify constraints, scope, and tradeoffs\n- `$sticky-plan` - build an execution-grade phase plan\n- `$sticky-execute` - do next-task work with receipts and proof\n- `$sticky-verification-before-completion` - claim completion only with proof\n\n## Existing Repos\n\nStickyfingers should not pretend an existing project is blank. In a repo with\n`.planning/`, `$sticky-where` uses GSD progress inputs first, then overlays\nSticky cockpit receipts and proof. Without `.planning/`, it uses repo intake so\nthe agent can draft `$sticky-milestone` state from:\n\n- repo signals such as README, package files, tests, docs, and planning files\n- git dirtiness and sample changed paths\n- likely baseline: existing repo versus empty/minimal repo\n- agent guidance to summarize what already exists before drafting state\n\nThe agent should then ask about the next outcome, not the whole universe:\n\n```text\nWhat project-epic outcome should Stickyfingers track first, and what is already\ndone that should count as baseline instead of new work?\n```\n\nAfter that, the agent drafts the milestone and waits for explicit approval\nbefore creating `.planning/`.\n\n### Cold-Resume Cockpit (`$sticky-where`)\n\nUse `$sticky-where` as the first command in any repo. It is the shared resume\nsurface for both empty and active workspaces:\n\n- existing-repo intake when `.planning/` is not present\n- active roadmap with phase progression and dependencies\n- blockers, risk hints, and proof gap\n- `next` routing to the right workflow command\n- receipts and required commands already run\n\nWhen state is missing, it should describe what was found, then guide toward\n`$sticky-milestone` with a concise project-epic question.\n\n## Everyday Workflow\n\nUse `$sticky-*` commands as workflow launchers:\n\n- \"Where are we?\"\n- \"What should we do next?\"\n- \"This feels messy; help me organize it.\"\n- \"Implement the current plan and keep the source of truth updated.\"\n- \"Review this and record the findings.\"\n\nTypical first move:\n\n```text\n$sticky-where\n```\n\nThe agent reads Stickyfingers state first, then chooses the right internal\nworkflow. You can also name a mode directly when you know what kind of help you\nwant:\n\n```text\n$sticky-milestone\n$sticky-wonder\n$sticky-plan\n$sticky-execute\n$sticky-code-review\n```\n\nThe agent uses low-level `sticky` CLI commands internally. Humans normally work\nthrough the `$sticky-*` skills.\n\nFor quick fixes or one-session patches, keep using the same surface. The agent\nshould identify the req, receipt, review finding, or parked-work target, make\nthe change, record reality, attach proof when applicable, and run `sticky audit`\nbefore claiming done.\n\nFor a local workflow smoke, run:\n\n```bash\nscripts/smoke-dogfood-workflow.sh\n```\n\nThis creates a temporary repo, verifies missing-state routing, creates approved\nstate, records a receipt, runs command-backed proof through `sticky verify`, and\nchecks `sticky audit`.\n\nMinimum user-facing workflow check list:\n\n```bash\npython3 -m pytest -q\nscripts/install-agent-skills.sh all\nscripts/check-agent-skill-visibility.sh all\nscripts/smoke-dogfood-workflow.sh\n```\n\nAfter these pass, open any target repo and ask:\n\n```text\n$sticky-where\n```\n\nIf that return is incomplete, this is the repair path before changing anything.\n\n## Planning Artifacts\n\n`$sticky-plan` is not a lightweight checklist. It is the Stickyfingers version\nof GSD `plan-phase`: context gate, optional research, planner, plan checker,\nbounded revision loop, requirement coverage gate, and execution handoff.\n\nCanonical phase planning lives in GSD `.planning/`:\n\n- `.planning/PROJECT.md`\n- `.planning/REQUIREMENTS.md`\n- `.planning/ROADMAP.md`\n- `.planning/STATE.md`\n- `.planning/phases/*`\n- `.planning/receipts/*`\n\nA good GSD phase plan records exact files, concrete actions, automated or\nexplicit proof, done criteria, requirement IDs, goal-backward `must_haves`,\ndependencies, waves, threat model when needed, and verification criteria. The\nplan checker rejects vague files, missing requirement coverage, broken\ndependencies, missing key links, scope creep, scope reduction, ignored context,\nand weak proof.\n\nHumans usually should not run this by hand. The agent should use `$sticky-plan`\nand handle the internal GSD planning workflow, `.planning/` file writes,\nchecker loop, and Sticky receipt itself. `sticky plan import/show/check` is\nstate-mode aware: `show/check` read GSD `.planning/phases/*-PLAN.md` files when\n`.planning/` exists, while `import` remains legacy compatibility for older\n`.stickyfingers` rich-plan YAML. Older legacy compatibility commands remain\nfor migration and auditability, not as the recommended first-use workflow.\n\n## Advanced Skill Catalog\n\nMost users can start with `$sticky-where` and let the agent route. These skills\nare available when you want to force a specific workflow mode. More commands\nare fine; the important rule is that each command should make the agent take\nresponsibility, not make the user manage Stickyfingers internals.\n\nCore Stickyfingers skills:\n\n- `$sticky-where` - show current milestone, blockers, receipts, proof, and next action\n- `$sticky-milestone` - start or reshape the project epic and prerequisite-ordered phase roadmap\n- `$sticky-discuss` - clarify goals, constraints, requirements, blockers, and evidence\n- `$sticky-wonder` - reassess the project, goal, direction, milestone path, or pivot options\n- `$sticky-plan` - GSD phase planning: context, research, PLAN.md files, checker loops, and handoff\n- `$sticky-execute` - implement while recording receipts and proof\n- `$sticky-code-review` - formal review with findings recorded into Stickyfingers state\n- `$sticky-security-audit` - security review with source-of-truth findings\n- `$sticky-seo-audit` - SEO review with source-of-truth findings\n\nUse `$sticky-wonder` when you are not just brainstorming ideas inside a goal,\nbut questioning the goal itself: whether the project is coherent, whether the\ncurrent path is worth continuing, whether an external repo changes the plan, or\nwhether to pivot, simplify, continue, or stop.\n\nStickyfingers-native Superpowers wrappers:\n\nThese wrappers run the original Superpowers workflows 1:1. Stickyfingers does\nnot replace their hard gates, checklists, design docs, TDD rules, debugging\ndiscipline, review loops, or verification rules. It adds a small prelude for\n`sticky where` context and a small epilogue for receipts, req/proof updates,\nparked work, and `sticky audit`.\n\n- `$sticky-using-superpowers` - choose the right Stickyfingers workflow skill\n- `$sticky-brainstorming` - explore options before creative work\n- `$sticky-writing-plans` - write detailed implementation-plan documents\n- `$sticky-executing-plans` - execute written plans task by task\n- `$sticky-test-driven-development` - enforce failing-test-first behavior work\n- `$sticky-subagent-driven-development` - execute plans with subagent task/review gates\n- `$sticky-dispatching-parallel-agents` - coordinate independent parallel agents\n- `$sticky-systematic-debugging` - debug from reproduced failures and evidence\n- `$sticky-verification-before-completion` - prove claims before completion\n- `$sticky-requesting-code-review` - prepare review requests with proof/state\n- `$sticky-receiving-code-review` - turn review feedback into fixes/findings/decisions\n- `$sticky-using-git-worktrees` - isolate work without losing source-of-truth state\n- `$sticky-finishing-a-development-branch` - final branch proof and merge readiness\n- `$sticky-writing-skills` - create/update skills with packaging and audit proof\n\n## Workflow Scale\n\nThis vocabulary is mostly for agents and advanced review:\n\n- **Milestone** - project epic, often multi-week.\n- **Phase** - week-scale slice inside a milestone.\n- **Req** - proof-backed requirement inside a phase.\n- **Receipt** - small work event, patch, test run, decision, or session note.\n\nAgents should not create milestones for quick fixes, copy changes, single\nimplementation sessions, or command-smoke followups. Those belong in reqs,\nreceipts, review findings, or phase work inside an approved milestone.\n\nProject note: this repo's `M1`-`M13` history is legacy dogfood state from before\nthe milestone scale was corrected. Keep it for auditability; do not use it as\nthe model for future project planning.\n\n## Install Details\n\nThe Python package installs the internal `sticky` command:\n\n```bash\ngit clone https://github.com/meowsigma/stickyfingers.git\ncd stickyfingers\npython3 -m pip install -e .\nsticky --help\n```\n\nFor development:\n\n```bash\npython3 -m venv .venv\n. .venv/bin/activate\npython -m pip install -e '.[test]'\npython -m pytest -q\n```\n\nPython 3.11 or newer is required.\n\nInstall AI coding CLI skills from the checkout:\n\n```bash\nscripts/install-agent-skills.sh all\n```\n\nInstall or reinstall Codex directly from GitHub:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | bash\n```\n\nFor all supported agents from the same GitHub installer:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/meowsigma/stickyfingers/main/scripts/install-codex.sh | STICKYFINGERS_AGENT_TARGET=all bash\n```\n\nInstall one target when needed:\n\n```bash\nscripts/install-agent-skills.sh codex\nscripts/install-agent-skills.sh claude\nscripts/install-agent-skills.sh qwen\n```\n\nCodex installs portable skills into `${CODEX_HOME:-$HOME/.codex}/skills`.\nClaude Code installs portable skills into `$HOME/.claude/skills` as a fallback\nand installs Stickyfingers as a local Claude plugin through\n`.claude-plugin/marketplace.json`.\nQwen Code installs direct skill fallbacks into `$HOME/.qwen/skills` and, when\n`qwen` is available, links this repo as a native Qwen extension.\n\nQwen Code can also install from GitHub:\n\n```bash\nqwen extensions install https://github.com/meowsigma/stickyfingers.git --ref main --consent\n```\n\nPinning `--ref main` makes Qwen install the source tree directly. Without a\nref, Qwen may prefer release-download behavior that does not preserve this\nrepo's extension root layout.\n\nFor local Qwen development:\n\n```bash\nqwen extensions link /path/to/stickyfingers\nqwen extensions list\n```\n\nIf `$sticky-*` commands are not visible after this repo is linked, run:\n\n```bash\nscripts/install-agent-skills.sh qwen\nscripts/check-agent-skill-visibility.sh qwen\n```\n\nThen restart Qwen Code before re-running:\n\n```text\n$sticky-where\n```\n\n## Agent Visibility Checks\n\nVerify the installed skill pack:\n\n```bash\nscripts/check-agent-skill-visibility.sh codex\nscripts/check-agent-skill-visibility.sh qwen\nscripts/check-agent-skill-visibility.sh claude\n```\n\nCodex checks `codex debug prompt-input` so stale or invisible skills fail.\nQwen checks `qwen extensions list` and a debug startup log to prove Qwen's skill\nmanager parsed the Stickyfingers skills. Claude checks the fallback skill files,\nthe installed `stickyfingers@stickyfingers` plugin cache, and a Claude debug\nstartup log proving the plugin skills loaded.\n\nVisibility checks prove installation and parsing. They do not prove that a model\nselected the right skill in a real task. For that, inspect receipts for\n`skills_used`, proof commands, changed files, and `sticky audit`.\n\n## Source Of Truth\n\nCanonical new planning state lives in GSD `.planning/`:\n\n- `.planning/PROJECT.md`\n- `.planning/REQUIREMENTS.md`\n- `.planning/ROADMAP.md`\n- `.planning/STATE.md`\n- `.planning/phases/*`\n- `.planning/receipts/*`\n\nThe forked GSD source lives in:\n\n- `vendor/gsd/upstream/`\n\nStickyfingers additions live outside that upstream tree:\n\n- `stickyfingers/gsd_bridge.py`\n- `stickyfingers/gsd_cockpit.py`\n- Sticky receipt/import/proof commands\n- `skills/sticky-*/` overlays\n\nLegacy compatibility truth remains readable as fallback only:\n\n- `.stickyfingers/config.yaml`\n- `.stickyfingers/milestones/*/milestone.yaml`\n- `.stickyfingers/milestones/*/requirements.yaml`\n- `.stickyfingers/milestones/*/plan.yaml`\n- `.stickyfingers/milestones/*/context.yaml`\n- `.stickyfingers/milestones/*/research.yaml`\n- `.stickyfingers/milestones/*/inserts.yaml`\n- `.stickyfingers/milestones/*/reviews.yaml`\n- `.stickyfingers/ledger.jsonl`\n- `.stickyfingers/archive/milestones/*/summary.json`\n- `.stickyfingers/archive/compact/latest.json`\n\nLegacy rendered output lives in:\n\n- `.stickyfingers/STATE.md`\n- `.stickyfingers/WORKMAP.md`\n- `.stickyfingers/PLAN.md`\n- `.stickyfingers/CONTEXT.md`\n- `.stickyfingers/RESEARCH.md`\n- `.stickyfingers/state.json`\n\nDo not hand-edit canonical state unless repairing corruption. Prefer the AI\nskills; agents should use the internal CLI so receipts and rendered state stay\nconsistent.\n\n## Legacy Compatibility\n\nOlder Stickyfingers dogfood repos may still contain `.sticky/` or\n`.stickyfingers/` state. Treat those paths as migration or compatibility\nevidence, not the canonical first-use workflow for new projects.\n\nLegacy v2 state can include:\n\n- `.sticky/PROJECT.md`\n- `.sticky/REQUIREMENTS.md`\n- `.sticky/ROADMAP.md`\n- `.sticky/STATE.md`\n- `.sticky/state.json`\n\nOlder internal automation may also show exact `sticky v2 ...` and\nflag-heavy `sticky milestone ...` commands. Those commands are compatibility\nevidence for old dogfood history, not instructions for new users.\n\nDo not lead new users with those commands. Use `$sticky-where` and the GSD\n`.planning/` path first.\n\n## Advanced: Internal CLI\n\nThe `sticky` terminal command is the state API used by agents, tests, and\ndebugging. It is intentionally lower-level than the `$sticky-*` product surface.\n\nUseful diagnostics:\n\n```bash\nsticky where --no-color --width 80\nsticky plan show\nsticky plan check\nsticky context show\nsticky context check\nsticky research show\nsticky research check\nsticky next --json\nsticky verify --claim \"tests pass\" --command \"pytest -q\"\nsticky verify --claim \"REQ-1 is proven\" --command \"pytest -q\" --req REQ-1\nsticky verify --claim \"ready\" --suggest\nsticky doctor --json\nsticky doctor --fix\nsticky audit\n```\n\nOptional local commit guard:\n\n```bash\nscripts/install-git-quality-guard.sh\n```\n\nIt installs a git `pre-commit` hook that blocks commits when Stickyfingers is\ninitialized but `sticky audit` fails. Uninitialized repos are allowed with a\nwarning so first-time adoption does not block normal commits. Bypass\nintentionally with `SKIP_STICKY_GUARD=1 git commit ...`.\n\nInternal state mutation commands exist for agents, tests, and repair work, but\nthey are not the normal user workflow. A coding agent should translate plain\nlanguage into the right mutation, attach receipts/proof, and preserve GSD\n`.planning/` truth. If you need to debug that layer directly, inspect\n`sticky --help` and the focused command help for the exact operation.\n\nIf you are using Stickyfingers through an AI coding CLI, do not start here.\nStart with `$sticky-where`.\n\n## Verify The Install\n\nRun the full repo suite:\n\n```bash\ncd /path/to/stickyfingers\npython3 -m pytest -q\n```\n\nRun a black-box AI workflow smoke by asking the agent:\n\n```text\n$sticky-where\n```\n\nExpected behavior:\n\n- missing state routes into a 3-6 question project-epic milestone interview\n- the agent drafts `.planning/` state and waits for approval before\n  creating it\n- receipts record the relevant `$sticky-*` skill with `--skill`\n- `sticky audit` passes before completion is claimed\n- after closeout, `$sticky-where` reports the closed milestone and next action\n\nFor a terminal-only diagnostic smoke, use the advanced internal CLI commands\nabove.\n\n## Troubleshooting\n\nIf `sticky` is missing:\n\n```bash\ncd /path/to/stickyfingers\npython3 -m pip install -e .\n```\n\nIf a target repo has no state, ask the agent for `$sticky-where`. It should\nroute itself into milestone setup, interview you, draft the initial state, and\nwait for approval before creating it.\n\nIf rendered files are stale:\n\n```bash\nsticky doctor --json\nsticky doctor --fix\nsticky audit\n```\n\nIf `audit` reports dirty files without receipts, tell the agent to record a\nStickyfingers receipt for the work. The internal form is:\n\n```bash\nsticky note \"Recorded current change\" --file path/to/file --skill sticky-execute --next \"run audit\"\n```\n\nIf an AI coding CLI does not see the skills, reinstall them and restart the\nagent:\n\n```bash\nscripts/install-agent-skills.sh codex\nscripts/check-agent-skill-visibility.sh codex\nscripts/install-agent-skills.sh qwen\nscripts/check-agent-skill-visibility.sh qwen\nscripts/install-agent-skills.sh claude\nscripts/check-agent-skill-visibility.sh claude\n```\n\nIf a skill feels slow to start, measure the agent prompt path before blaming the\nStickyfingers command count:\n\n```bash\nscripts/measure-agent-skill-load.sh\n```\n\nThe benchmark compares an empty isolated Codex home, a `sticky-wonder`-only\nhome, an all-Stickyfingers home, and your current Codex home. A slow current\nhome with fast isolated homes usually points at broader Codex/plugin/session\nlatency, not Stickyfingers skill count. `$sticky-wonder` is designed to\nrespond first and inspect files lazily after the reassessment question is clear.\n\n## Publish To GitHub\n\nFor a release-readiness pass:\n\n```bash\ncd /path/to/stickyfingers\npython3 -m pytest -q\nscripts/smoke-dogfood-workflow.sh\nSTICKY_BIN='python3 -m stickyfingers.cli' bash scripts/simulate-stickyfingers-mixed-workflow.sh\nSTICKY_BIN='python3 -m stickyfingers.cli' bash scripts/simulate-stickyfingers-webapp-hard-workflow.sh\nSTICKY_BIN='python3 -m stickyfingers.cli' bash scripts/simulate-stickyfingers-edge-cases.sh\nSTICKY_BIN='python3 -m stickyfingers.cli' STICKY_REAL_REPO=/home/sigma/checkshot bash scripts/simulate-stickyfingers-real-project-bakeoff.sh\nscripts/simulate-stickyfingers-github-install-smoke.sh\nscripts/install-agent-skills.sh all\nscripts/check-agent-skill-visibility.sh all\npython3 -m stickyfingers.cli where --no-color --width 100\ngit status --short\ngit add .\ngit commit -m \"prepare stickyfingers release\"\ngit push origin main\nscripts/production-readiness-check.sh\ngit tag -a v0.5.3 -m \"Stickyfingers v0.5.3\"\ngit push origin v0.5.3\ngh release create v0.5.3 --title \"Stickyfingers v0.5.3\" --notes-file CHANGELOG.md\n```\n\nThe current hostile limit evaluation is recorded in\n[`docs/stickyfingers/dogfood/2026-05-10-limit-evaluation.md`](docs/stickyfingers/dogfood/2026-05-10-limit-evaluation.md).\n\n## Project Status\n\nStickyfingers v0.5.3 is production-ready for GitHub-distributed AI coding CLI\nuse. The production gate covers the Python package build, the `sticky` CLI,\nCodex/Qwen/Claude skill installation and visibility, strict GSD `.planning`\nrouting, real-project bakeoff, hostile simulations, clean GitHub install, and\nSticky audit/plan/doctor gates.\n\nThe supported production install path is the GitHub installer. PyPI publishing\nis not the primary distribution channel for the skill bundle because the agent\nskills and plugin manifests are repo assets as well as Python code.\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for release notes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeowsigma%2Fstickyfingers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeowsigma%2Fstickyfingers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeowsigma%2Fstickyfingers/lists"}