handily

Never do

Code Is Authoritative

IMPORTANT: never defeat a gate to make it pass. Do not skip or weaken a test, a lint or a type check, and do not bypass a hook (--no-verify, --no-gpg-sign) unless the user explicitly requests observer repair. Fix the cause.

• For observer repair, work outside the harness controller; run affected checks directly and report bypasses and unfinished verification. Describe bypassed checks as bypassed, never as passing.
• Never add prose to code: no comment and no docstring. Keep tool directives (example: noqa) and licence headers. The no-comments hook enforces the ban. Use no-comments for enforcement details.

Secure Coding

• Never admit unvalidated external input past a trust boundary.
• Never concatenate input into shell syntax or queries; pass arguments and values as parameters.
• Never put secrets in the repository or logs; use environment variables or a secret manager.
• Never expose internal details in returned errors. Log the detail and return a generic message.
• Never commit machine paths, user names or host names. Only the tracker's holder field may record the name chosen with git config basicly.holder.

Ask first

Require Explicit Confirmation

These actions need explicit approval. Reuse it only for the same action and scope. Identify that approval. A new phase or agent needs no repeat approval.

• force-push, rewrite history, or discard uncommitted work: git reset --hard, git checkout -- <path>, git restore, git stash, git clean, rm -rf;
• read or write a .env* file;
• delete files, branches or data outside the task;
• edit CI/CD, deployment, infrastructure, ignore or secrets files;
• add, remove or upgrade a dependency;
• make a network call outside the task.

Tool access does not grant approval. Apply this list even when commands run unblocked. Undo your edit from a prior copy.

Commands

Commands in code fences are exact - run them verbatim instead of improvising variants.

Setup:

npm ci
npm run types

All gates (validate, typecheck, lint, test) over every mod:

npm run check

One gate over every mod:

npm run validate
npm run typecheck
npm run lint
npm test

One mod:

claude plugin validate --strict mods/<name>
claude plugin test mods/<name>

Format:

npm run format

Load a mod in a session for a manual check:

claude --plugin-dir mods/<name>

Always do

Project Overview

• Purpose: handily is a public repository of Claude Code mods (plugins of function hooks) and a Claude plugin marketplace. The mods show work items, tasks and sessions for any tracker. No mod needs basicly.
• Boundary: mods show and ask. Mods never enforce. Enforcement belongs in git hooks or a harness, because a git hook holds for every agent.
• Stack: TypeScript 6.0 (pinned below 6.1 for typescript-eslint), ESLint with typescript-eslint strict type-checked rules, Prettier, Node.js 22 or later. The Claude Code CLI version is pinned in .github/workflows/basicly-gates.yml.
• Layout: one mod per folder in mods/<name>/, listed in .claude-plugin/marketplace.json with source ./mods/<name>. scripts/mods.mjs runs every gate over every mod.
• Design: docs/design.md is the authority for the mods, the decisions and the open questions. Read it before you start a mod.

Lane Dispatch Quirks

• Create each lane with basicly worktree create <name>, which puts it at ../handily.worktrees/<name> on branch harness/<name> with node_modules and the git hooks in place, and start the agent there without the isolation option of the Agent tool. Commit the ledger first, because the worktree forks from the local HEAD.
• The Definition of Ready gate reads a <word> in an acceptance criterion as a placeholder and counts the criteria as absent. Write the thing by name, such as "the interpreter", not <interpreter>.
• A record id has 5 or 6 characters after handily-. Read a new id from the id field of the created event, split at #, and never with a fixed-length pattern, which cut handily-ev56ne and the commit-msg hook refused the commit.
• Run no gate in a worktree while an agent edits it. The run reads half-written tests and reports failures that are not real.
• The organization security plugin skips the classic hooks of a user mod and some function hooks with no matcher, such as session.append with no door, and prints a line in the transcript on each turn. Register no classic hook, give every session.append hook a door matcher, and check a new hook live for a hook was skipped line.
• In a tmux live check, a prompt typed while the session still starts is lost. Wait until the footer shows auto mode on on four reads in a row, press Escape on any Enter to select question, and only then type the prompt.
• zsh has no mapfile. Read lines into an array with arr=("${(@f)$(command)}"), and check the count before you use the array.
• Commit the claim on main before a lane commits. The commit-msg hook reads the committed ledger, so a claim that is only in pending-main.jsonl refuses the lane's commit. Then run git merge --ff-only main in the lane.
• The worktree-isolation guard refuses a tmux prompt in a lane. Run the live tmux check from the main session, on a copy of the lane's mods made with git archive.
• The commit-msg hook refuses merge: as a type. It also refuses an apostrophe in the description. Use chore: for a merge commit, and write the description without an apostrophe.
• The Definition of Ready trigger parser ends the situation at the first "I want". So "When I want my list, I want to" reads as an empty situation. Write the situation without "I want". A <word> in a comment that the review cites also reads as a placeholder, so write the thing by name there too.
• A new comment or dependency edge on a record makes its recorded review stale. The record then leaves the ready set. Record the review again after such an edit.
• An edit of an epic's description makes the recorded reviews of all its children stale. Edit the epic before you review its children, or record each child review again before its claim.
• Check the exit code of the ledger commit before you dispatch a lane. A refused claim commit leaves the claim only in pending-main.jsonl, and the lane's commit-msg hook then refuses its commit. A comma or a capital letter in the description is a common cause.
• A session started with --plugin-dir mods writes .claude-plugin/types into a removed mod folder. Then npm run check fails with "a folder under mods/ is a mod". Delete the regenerated folder and run the check again.
• /reload-plugins unloads an uninstalled plugin but keeps a disabled one loaded, as measured on Claude Code 2.1.296. To drop a mod from a running session, uninstall it before you reload.
• The commit-msg hook refuses a chore(release) commit unless it names a record that you hold in progress. An epic cannot be claimed. Commit the release before you close its last record, then close the record.
• Stage nothing else while a release is staged. A ledger commit with the staged CHANGELOG.md is refused by the changelog gate, because only a chore(release) commit may edit it.
• In a live tmux check, wait for the text "Enter to confirm" before you answer the folder trust prompt, then send Down and Enter apart. A wait that matches ❯ stops on the "No, exit" row, and Enter then quits the session.
• To test a mod setting in tmux without changing the user settings, start the session with --settings and a JSON object that sets pluginConfigs under both the plugin name and the name with @inline.
• basicly worktree cleanup <name> refuses a merged lane, because the untracked .basicly/ledger/redirect and the ignored generated files count as uncommitted changes. Check that the branch is merged, then the person runs it with --force.
• npm run check and the pre-commit hook take about 4 minutes. Run them with a 600 second timeout and write the output to a file, because the pipe-status hook refuses a status read after | tail.
• basicly worktree cleanup refuses a worktree whose branch is not its registered harness/<name> branch. To reuse a merged lane, switch it back to its own branch before the person cleans it up, and never hand over a cleanup command that names a worktree where an agent still works.
• Prettier does not cover docs/. npx prettier --write docs/design.md re-pads every table, and the signals test then fails because it reads a table header exactly. Run prettier only through npm run format.
• The pre-commit speed gate takes the lowest limit of every declared pattern that matches a test title, and a test registered from a helper with a title it cannot read matches every title at 5000 ms. So a timeoutMs in such a file never counts. Put a slow test that needs a declared limit in a file where every title is a string literal, such as generated.test.ts.
• A live check of a release runs a fresh tmux session with the installed plugin, not --plugin-dir on a lane copy. A running session keeps the old plugin code after claude plugin update until /reload-plugins or a restart. A long reply folds, so check one diagram per reply.

Knowledge Priming

• The current user's instruction overrides this file; path-scoped instructions override it for matching files.

Harness Loop

• Keep one responsible owner from task to completion; the tracker ledger and latest handover preserve shared history.
• Delegate only for independent work, context pressure, independent review or specialist capabilities.
• Use basicly session start when useful. Direct work needs no controller. Read harness-loop for optional owner handoffs or headless orchestration with --execution worker.
• The user task request authorizes its scope. Do not request a grant or a mandatory token budget.
• Keep verification gates and destructive-action protections enabled. Honor limits the user explicitly sets.

Decision Protocol

• Decide small, reversible actions outside the confirmation list from code. Use safe read-only checks to resolve facts first. Ask when missing facts, conflicting sources or uncheckable assumptions change the result. Name the missing fact and useful options.
• With frozen scope, finish started work and demonstrated blockers within scope. Report broader blockers and ask before expanding. Record nonblocking adjacent findings in the tracker without implementing them.
• Resolve conflicting rules in favor of safety and security. After two failed approaches, report the pattern and propose another.

External Facts

• For third-party interfaces, read our adapter and current vendor docs; use interface-facts, never memory.
• Before absence/zero claims, search for the action and run a known-match control through the same search. An empty control invalidates it; a match must increase the examined count.
• Use falsify-first before high-risk numbers, root causes or coverage claims enter a decision.

Core Rules

• Before building, search the code that would call the capability; documentation or --help alone does not establish absence.
• Read the test-discipline skill for isolation, ordering or platform-sensitive tests.

Mistake Proofing

• Prevent wrong use or refuse wrong input by name before damage; give the correct command, never a default or empty success.
• Default to safety; shared-state damage needs an explicit flag.
• Keep each rule in one place, call it from every side, and prevent recurrence with a test or gate. A warning alone is insufficient.

Catalog Authoring

• Edit generated files through catalog sources using catalog-authoring. basicly install overwrites .basicly/core/; consumer overrides belong in .basicly-local/.

Non-Interactive Shell

• Prefer cross-platform, non-interactive commands: cp -f, mv -f, rm -f, -y, ssh -o BatchMode=yes.
• Use arrays or inline lists, never for x in $LIST: zsh does not split unquoted variables. Check the processed count.
• Before a multisite scripted replacement, state the expected count; compare afterwards and stop on a mismatch.

Quality Gate

• While editing, run the tests affected by the change. Continuous integration runs the full suite.
• Keep all required gates enabled. Report what ran, what failed and what did not run.
• For a failed check, changed inputs, a tracker-only change or a release candidate, read the harness-loop skill's verification reference.

Git Discipline

• Run git commit alone; chaining push, tags or tracker writes after a refused commit leaves partial work.
• Claim the record with work-tracker; use conventional-commits for the required Conventional Commits subject and trailing record id.
• If a hook refuses, fix its named cause and commit again.

Session Completion

• At session end, use session-finish and its clean-handoff reference. Fix refusal causes within approved scope; carry unresolved facts and diagnosis into the handover.

Mod Authoring

• Load the plugin-authoring skill before you write or change a mod. The mod API is early access and changes between Claude Code releases. The generated .claude-plugin/types/claude-code/index.d.ts is the authority, not memory.
• A mod has .claude-plugin/plugin.json (with "author": { "name": "niksavis" }; the identity gate refuses a git user name), hooks/hooks.json, hooks/register.ts or .tsx, a tsconfig.json that extends ./.claude-plugin/types/tsconfig.json, and at least one *.test.ts. A mod that adds a $ noun or keeps $.state values ships types/index.d.ts and names it in plugin.json.
• The folder name, the plugin.json name and the marketplace entry name are equal. npm run validate refuses a mismatch.
• Write each mod in its folder under mods/, not in the session mods folder that the plugin-authoring skill names. Load it with claude --plugin-dir mods, because a mod that depends on another does not load alone.
• Await every promise from $ and next. Lint refuses a floating promise.
• A mod reads tracker data only through the workitems provider. A mod writes to a tracker only on an explicit action of the person, through the tracker's own CLI.
• A ui.render hook that cannot read its input returns next(e), so the engine draws its own row. It never draws a guess.
• Test every mod on the terminal and desktop surfaces.
• Drive an interactive Claude Code check yourself in tmux on a private -L server, and kill only that server. Ask the person only for a surface you cannot reach, such as the desktop app.