basicly

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

Run these commands as written.

Setup:

uv sync --group dev
uv run python src/basicly/lefthook_artifacts.py --download
uv run basicly hooks-build

While editing, run the affected test file (example):

uv run pytest tests/test_cli.py -q

Before a local commit, verify the staged changes:

uv run basicly verify --mode staged --affected

Full verification runs in CI only. Do not run the full suite locally on routine edits or integration.

The staged command includes lint, format and type checks. Do not repeat repository-wide lint or format checks for the same changes.

Projection gates (after editing catalog sources):

uv run basicly check
uv run basicly skills-check
uv run basicly styles-check
uv run basicly agents-check
uv run basicly hooks-check
uv run basicly permissions-check

Always do

Project Overview

• basicly distributes a harness for coding agents. One YAML catalog is projected into agent instruction files, skills and git hooks. Other repositories install it with basicly install.
• Stack: Python 3.14 or later, managed with uv. The version lives only in src/basicly/__init__.py. Platforms: Linux runs full CI; Windows and macOS run focused hook and wheel consumer checks.
• The basicly CLI is src/basicly/cli.py. This repository authors the catalog in .basicly/core/; its own overrides are in .basicly-local/. Scripts and CI helpers are in .scripts/.
• docs/architecture/architecture.md is the authoritative design reference.
• A change under .basicly/core/kit/ must work for a consumer with no engine. Name where that consumer gets the capability.

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.

External Review

• Before a research or design document recommends a third-party project, establish its licence, shipped mechanism and independent evidence. Read .agents/skills/falsify-first/SKILL.md before proceeding.

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.

Ownership

• Own the approved outcome and necessary harness fixes; fix demonstrated causes with the smallest effective regression or control.
• Use current vendor and expert practice unless it makes install, use or upgrade less safe for a person who makes a mistake.

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.

Model Tier Routing

• Before specialist dispatch, use tier-injection and this repository's tier-only routing (e.g. tier: high).

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.

Rendered Surfaces

• For rendered pages, use validate-as-consumer; inspect screenshots against each acceptance criterion with real data at every claimed viewport.

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.

Release Fragments

• Include changelog.d/<record-id>.<category>.md with each consumer-visible change before closing: one bullet under 400 characters, e.g. basicly-a3ab.4.changed.md.
• Releases read the tagged commit. A closed shipped record without its fragment blocks the next main commit.