algal
AGENTS.md20 starsChanged 41 days agoMITArchived repositoryView on GitHub
- src/ — the contract (contract.ts, graph.ts), the scheduler (run.ts), scoped exact-context storage (agent-context.ts, mirrored in crates/algal/src/agent_context.rs) and model query/selection tools (agent-context-tools.ts, shared fixture scripts/fixtures/agent-context.json), the runtime-owned local reader (agent-context-runtime.ts, native mirror agent_context_runtime.rs, fixture scripts/fixtures/agent-local-context.json), the effect seam (effects.ts), the isolated subprocess executor profile (isolation.ts), the store (store.ts), verification (verify.ts), Vercel AI Gateway execution (gateway.ts) and portable Chat Completions execution (openai-compatible.ts, chat-completions.ts), typed external tools (tools.ts), opaque capability handles (capabilities.ts) and the bounded durable mailbox driver (mailbox.ts), the named durable…
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- site/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- site/llms.txtllms.txt
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
13 rules. About 0 are common, 4 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 75
Never export raw stores, third-party benchmark tasks, private traces, signing material, or provider accounts.
- Very specific: line 79
Use the supported hf CLI from a reviewed stage after rights review and normal repository checks.
- Very specific: line 110
Keep every public claim true and scoped to what shipped: README claims match what bun run check and the tests prove, and proposals are …
- Very specific: line 136
Keep the thesis a bet and the cumulative-skill test an open experiment.
- Very specific: line 142
Write the product name as ALGAL in prose and algal only for the command.
- Very specific: line 148
Check every command on a page against --help for the runtime the page names.
- Very specific: line 151
Never edit GENERATE_PROMPT in src/source.ts for style or casing.
- Very specific: line 241
Run bun run check:copy before handoff when the repository has it.
- Distinctive: line 252
Write a “How X uses Y” post only for a registered relation that has a description.
- Distinctive: line 255
When a product is renamed or a relation changes, update the post bodies that mention it in the same change.
- Distinctive: line 276
When a CI or policy gate scans complete Git history, check out the exact governed SHA and fetch only the fully qualified governed refs …
- Very specific: line 283
Prefer the globally installed algal-* skills for bounded git state, diffs, repository survey/search, test and release gates, CI polling, …
- Very specific: line 286
Treat ALGAL receipts as execution evidence, not provider attestation, and preserve the repository's normal verification and release gates.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- browser-automation:start -->- Ordinary owned automated browser runs use versioned Chrome for Testing or the browser provisioned for the pinned Playwright version. Reject the installed auto-updating Chrome application, including explicit executable overrides and symlinks; never fall back to it when provisioning is missing. Report the resolved executable and browser version, and close owned contexts and browsers gracefully in cleanup. Attaching to an explicitly authorized user-owned browser is a separate operation: preserve its profile and lifetime. Keep regression checks for browser selection in the existing required checks; see browser automation.
- Never start the system Chrome app directly from an agent shell; use the repository's browser tooling and respect its scheduler and browser custody controls. For owned launches, pass
--mute-audioand mergePaintHolding,MacAppCodeSignCloneinto any existing--disable-featuresvalue instead of adding a second switch. Finish owned process, context, and profile cleanup before releasing the browser lane. Never signal another holder or manipulate its lease to obtain a slot. - The sole native-runtime exception is Slopcamera’s documented signature-verified, version-bound, immutable task-owned Chrome snapshot, never a direct launch of the installed application. Its current integrity-bound launch contract must disable
MacAppCodeSignClone; retain vendor identity verification, browser custody, graceful cleanup, and regression checks. Qualify the native fix with live clone-growth and cleanup evidence before activating this exception. It is not an executable override or fallback for ordinary automation; see the native-runtime exception.
<!-- browser-automation:end -->Contents
src/— the contract (contract.ts,graph.ts), the scheduler (run.ts), scoped exact-context storage (agent-context.ts, mirrored incrates/algal/src/agent_context.rs) and model query/selection tools (agent-context-tools.ts, shared fixturescripts/fixtures/agent-context.json), the runtime-owned local reader (agent-context-runtime.ts, native mirroragent_context_runtime.rs, fixturescripts/fixtures/agent-local-context.json), the effect seam (effects.ts), the isolated subprocess executor profile (isolation.ts), the store (store.ts), verification (verify.ts), Vercel AI Gateway execution (gateway.ts) and portable Chat Completions execution (openai-compatible.ts,chat-completions.ts), typed external tools (tools.ts), opaque capability handles (capabilities.ts) and the bounded durable mailbox driver (mailbox.ts), the named durable process supervisor (process.ts), the provider-neutral typed-decision layer (decisions.ts) with the Cloudflare Clef adapter (clef.ts, nativeclef.rs) and explicit legacy Jev adapter (jev.ts), cross-platform credential custody (credentials.ts), embeddings (embeddings.ts) and the derived semantic index plus recall executor (semantic.ts), foundry evaluation and search (foundry.ts,search.ts) with the habitat-wide work account (habitat-budget.ts) and its round-robin scheduler and resumable journal (habitat-schedule.ts), the Habitat Link records and client (habitat-link.ts), signed descriptors and grants (habitat-link-authority.ts), and the caller tools plus local acceptor that bind them to processes (habitat-link-host.ts, spike notes indocs/habitat-link-spike.md), benchmark comparison (bench.ts,bench-verify.ts), the cumulative-skill experiment arm runner and report (experiment-run.ts,experiment-report.ts,experiment-verify.ts), bundles (bundle.ts), transports (transport.ts), the shared evaluation/host/promotion/lifecycle evidence records (host-contract.ts, mirrored incrates/algal/src/host_contract.rs, with the shared fixturescripts/fixtures/host-contract.json), the bounded strategy-comparison improvement loop (improve.ts), thealgal.expr.v1WASM loader (expr.ts+ committedalgal_expr.wasm), canonical values and digests, and colocated tests.crates/algal-expr/— the one expression evaluator (Rust): linked into the kernel as an rlib and compiled towasm32-unknown-unknownfor Bun.scripts/build-expr-wasm.shrebuildssrc/algal_expr.wasm(needs a rustup toolchain with the wasm target; pinsRUSTCpast Homebrew).cli.ts— the Bun CLI (run,check,verify,resume,inspect,explain,dependencies,lock,vendor,diff,foundry,bench,runs,digest,store,manifests,manifest,slots,slot,mailbox,process,pack,unpack,applicationdrain/verify-drain,librarycompare/unseen,experiment<config.json>/report/verify/inspect,example,suite,index,search,auth,doctor).index.ts— the package's public surface.examples/— bundled manifests and scripted responses used bysuite.spec/v1/organism.md,spec/v1/expr.md,spec/v1/foundry.md,spec/v1/search.md,spec/v1/bench.md,spec/v1/vendor.md,spec/v1/process.md,spec/v1/application.md,spec/v1/host-contract.md,spec/v1/improve.md— authoritative contract prose, including the bounded durable process filesystem ABI.site/— the static algal.computer source;build.tswritessite/dist. Blog posts aresite/blog/*.md; their review records live insite/blog-posts.ts.README.md,CONTRIBUTING.md,SECURITY.md— the public contract.docs/vision.md— the project thesis (software that accumulates competence) and the evidence that would justify it;docs/lineage.md— the programmable-environment traditions and research precedents.
Hugging Face experiment archive
- Maintain
hranesscom/algal-experimentsas a dataset using the runbook.hf/manifest.jsonowns the exact public artifact paths and hashes;hf/stage.pyvalidates and stages without network or inference. Update the card when adding a completed public study. - Append immutable study directories. Preserve negative findings, failures, uncertainty, model and protocol identities, and missing cost data. Receipt verification does not establish task success or model quality.
- Never export raw stores, third-party benchmark tasks, private traces, signing material, or provider accounts. Ben approved initial publication and routine reviewed syncs on 2026-09-27 within the existing dataset; follow the runbook’s recorded scope, rights review, validation, and history-preservation requirements.
- Use the supported
hfCLI from a reviewed stage after rights review and normal repository checks. Record the remote commit and verify downloaded file hashes. - Publishing is part of every study's delivery, not a separate request. When a
study closes with a public summary JSON in
docs/, the same change adds its stage pair, manifest entry, card row, and runbook rights record; after the change integrates, stage from the clean merged checkout, upload, verify the remote hashes, and record the Hub commit before closing out. Ben confirmed this standing rule on 2026-09-29: do not ask whether to publish a closed study. Ask only for a new destination, private data, or historical deletion.
Guidelines
- Bun 1.3.x, strict TypeScript, zero required runtime dependencies. Shared
foundations attach through the
StoreandExecutorseams; do not add a package dependency for something the contract can express. - Parse foreign values from
unknownand reject unknown keys. Model invalid states out rather than checking them late. - The manifest is data and carries no host code.
fncells resolve against the host registry; agent cells resolve against an executor the host supplies;exprcells carry boundedalgal.expr.v1programs that the contract-owned evaluator (crates/algal-expr, one implementation for both runtimes) interprets under fuel — data, not executables. - Receipts contain no wall-clock fields.
verifymust replay a run bit-for-bit; keep nondeterminism at the executor boundary only. capports carry host-admitted authority. Keep capability classes exact, reject widening tojson, never let manifests mint handles withconst, and make every mutable driver idempotent and replay-safe.- Bound every count, byte size, depth, and list. New contract fields need a bound and a test.
- Colocate tests with source (
src/*.test.ts); cover failure modes with a deterministic example, not a mock-heavy harness. - Keep every public claim true and scoped to what shipped: README claims match
what
bun run checkand the tests prove, and proposals are marked as proposals. This is an internal claims rule; it is not wording for public pages.
Public copy
- Public copy is the website (
site/),README.md, the mirroreddocs/andspec/v1/pages,site/llms.txt, CLI help, package metadata, release notes, and the native workbench report. It followsSTYLE.mdandWRITING.md. - The canonical ALGAL identity lines come from the portfolio messaging record
(product
algal):site/copy.tscarries them asSITE_TAGLINEandSITE_DESCRIPTION, and the home H1, README lead, CLI intros, package descriptions, andllms.txttake the same fields. Reuse those constants and record fields instead of writing another variant. - Translate this file's internal vocabulary on public pages:
- admit, admission: check and accept (a manifest); attach (an executor, tool, or capability)
- custody: ownership of a running job or process
- settled: finished and confirmed
- qualified, qualification: tested on (name the platform or provider)
- retained: kept or saved
- bounded: limited (name the limit)
- authority: permission
docs/vision.mdis the one statement of what ALGAL is for. Pages that explain purpose link to it instead of restating the thesis in new words. Keep the thesis a bet and the cumulative-skill test an open experiment; no page may claim that accumulated procedures have been shown to improve later work. Precedents and traditions belong indocs/lineage.md.organismis the spec's term for an ALGAL program. Define it at first use on each page. Use at most one biology metaphor (fossil, habitat, living) per section, next to the literal mechanism it stands for.- Write the product name as ALGAL in prose and
algalonly for the command. Page titles separate the page and site names with a middle dot and name the brand once. Do not use em dashes in titles, descriptions, alt text, or prose. - Title a limits section "Status and limits" or "Limits"; never describe a page
or caveat as honest. State each limit once, beside the feature it limits.
Text shown on more than one page lives in
site/copy.ts. - Check every command on a page against
--helpfor the runtime the page names. The native binary has nodiagnose;--appleneeds a Mac with Apple Intelligence and Xcode to build the separate bridge. - Never edit
GENERATE_PROMPTinsrc/source.tsfor style or casing. It is a digest-bearing wire constant.
ALGAL native migration
- The product is ALGAL; all wire identifiers are
algal.*.v1and manifest fixtures use*.algal.json. There is no compatibility surface for older naming. crates/algal/is the Rust kernel, native CLI, memory/context primitives, and ACP boundary. Keep the TypeScript runtime independently runnable as the reference implementation. No implicit native-to-Bun fallback.- Native checks:
cargo test --workspace --locked,cargo clippy --workspace --all-targets --locked -- -D warnings, andcargo fmt --all -- --check. Usecargo build --lockedfollowed bybun scripts/native-parity.tsto compare every bundled example and verify receipts in both directions between TypeScript and Rust (it also replays the counterfactualalgal.replay-comparison.v1cases and the boundedalgal.ordering-scenario.v1explorations through both CLIs with the revised and dispatch receipts cross-verified, and the budgeted foundry and search fixture inscripts/habitat-budget-fixture.tsthrough both CLIs, including a round-robin habitat schedule with journal resumption checked byte-for-byte), andbun scripts/application-parity.tsto replay the durable application lifecycle (create/commit including activate, propose, select, and migrate transitions, dispatch/reconcile, memory scope/observe/snapshot/query, the boundedalgal.application-experiment.v1promotion-evidence join with evaluations charged to an optional habitat budget account, the deterministicapplication lineageprojection, the structured-facts-only ablation fixture, and thealgal.application-host.v1policy host) through both runtimes with identical digests, andbun scripts/process-parity.tsfor the durable process lifecycle (create/inspect/list/tick/verify/schedule, the mailbox suspension/wake chain with shared capability records, uncertain-intent recovery throughrecover/journal, journaled dispatch,export/verify-evidenceportable bundles, agent-cell suspension and resumption through the shared EX_TEMPFAIL command-executor contract, and the.creating.jsoninterrupted-creation recovery contract). Addbun scripts/store-parity.tsfor the CAS store/slot/listing CLI surface — the only driver that spawns the referencecli.tsrather than calling the service layer, since those commands live only in the CLIs. Runbun scripts/cli-parity.tsfor public check/explain/inspect/diff, bundle calls, suspension/resume, and installed-example suite parity.bun scripts/inference-parity.tscompares all three Chat Completions formats against a loopback fixture, including exact receipt and offline replay parity; it does not qualify a real local language model.bun scripts/agent-local-context-parity.tschecks local-reader view limits, exact history after elision, rejected references, work limits, isolated tool cells, and identical receipts with replay in both runtimes. - The optional progressive history reader lives in
src/context-history.tsandcrates/algal/src/context_history.rs; its contract and mandatory current-permission join are siblingcontext-history-contractandcontext-history-accessmodules.cargo build --locked -p algal --bin algal --example context_history_parityfollowed bybun scripts/context-history-parity.tscompares synthetic outputs, bindings, refusal codes and counters. This is not live or semantic-quality evidence. Keep the host registry and current-access resolver out of an agent-facing interface. - Optional summary maintenance lives in
src/context-summary.tsand uses the existingProcessSupervisorand concreteHabitatAccount. Never useHabitatAccount.admitfor uncertain jobs: its unreceipted-error path releases the allowance. Focused coverage isbun test src/context-summary.test.ts;bun scripts/context-summary-parity.tschecks frozen record identities and portable complete/failed evidence against the built native CLI and history example. The native evidence verifier requires a regular JSON file, not/dev/stdin; temporary fixtures must be task-owned and cleaned up. - On mixed Homebrew/rustup hosts, verify
cargo clippy --versionagainstrustc --version.rustup runcan still resolve Homebrew's external Cargo subcommand. Prefix the check process with the selected rustup bin directory:PATH="$(dirname "$(rustup which cargo)"):$PATH" cargo clippy .... Keep rustc, rustdoc, rustfmt and Clippy on that same toolchain; do not clean the store or alter repository policies to repair an incompatible build cache. - The Foundation Models bridge comes from the pinned
apple-foundationcrate (hraness/apple-foundation);sh scripts/build-apple.shemits its embedded source and builds it with Xcode 26 on Apple Silicon, and the defaultalgal-applesibling auto-builds on first use.target/debug/algal doctor --applechecks availability; compilation alone is not evidence that inference works. - xcb is the current repository for AgentMixer. It owns subscription custody and settled failover. Never recreate credential copying in ALGAL or treat ACP/cwd as OS isolation. Delegated coding tasks are non-cacheable and must not be automatically retried after uncertain completion.
- Canonical receipts are execution evidence, not truth or provider attestation. Memory query proofs are positive derivations from explicitly selected facts. Compaction preserves sources; byte reduction is not a token/billing claim.
<!-- hraness-public-copy:start -->- Public copy (websites, READMEs, docs, package and GitHub descriptions, CLI help,
llms.txt, generated pages) followsSTYLE.md, synced from hraness/.github. Text a model writes for publication also followsGENERATION_STYLE.md. - The delivery vocabulary in this file (admission, qualification, custody, receipt, bounded, lane, gate, surface, projection) is internal. Translate it into what the reader gets.
- Take one-line product and sibling descriptions from the portfolio registry and versions from the release record. Tests pin facts, not prose.
- Run
bun run check:copybefore handoff when the repository has it.
<!-- hraness-public-copy:end --><!-- hraness-releases:start -->- GitHub Release pages follow
RELEASES.mdin hraness/.github: the title is the registry product name and the tag, and the body is a summary,## Changes,## Install,## Verify, then the repository's identity record as a trailing HTML comment. - The summary and changes come from the version's section of
CHANGELOG.mdin the tagged commit. Write that section in the version bump pull request. The release workflow copies it, generates Install and Verify from the release record, fails when the section is missing or empty, and never uses GitHub's generated notes.
<!-- hraness-releases:end --><!-- hraness-articles:start -->- Essays and blog posts follow the essay addendum in
GENERATION_STYLE.mdandARTICLE_COPY.mdin@hraness/design-kit. The byline is “Hraness”, every post shows the provenance note naming its recorded reviewer, and no AI-drafted post is credited to a person unless that person rewrites and adopts it. - Take product names, one-line descriptions, addresses, status labels, and relations from the portfolio facts in
@hraness/design-kit. Render versions from the release record (package.json, a published-release file), never typed by hand. - Write a “How X uses Y” post only for a registered relation that has a description. Change the relation and its post in the same change. Link between products only along registered relations, and between a technique post and product posts about the same technique.
- Every post has a review record: reader job, non-obvious answer, sources with the date checked, owner, reviewer identity, reviewer type (
aiorhuman), a score out of 12, and areassessOndate 28 to 56 days after review. The reviewer is independent of the run or person that drafted the post. An AI reviewer is recorded and shown as AI;humanReviewstays null unless a person reviewed the post. - A new post starts out of search indexes, sitemaps, and feeds. It becomes indexable only when its review record is complete, scores at least 9 of 12 with no zero score, and the page shows the provenance note.
- When a product is renamed or a relation changes, update the post bodies that mention it in the same change.
<!-- hraness-articles:end --><!-- hraness-launch:start -->- Launch posts, their social posts, product mockups, and launch films follow the launch beats and social posts addendum in
GENERATION_STYLE.mdand the beats shape under “Introducing a product” inARTICLE_COPY.mdin@hraness/design-kit. Channel limits are in the launch posts section ofMESSAGING.md. - Build them with the
product-launchagent skill, the./mockupsand./launchexports of@hraness/design-kit, andslopcamera html init --template launch-film. - Take every number in a beat, social post, film caption, or store listing from the product's launch facts module, and the status from the release record. Label mockups as illustrations.
- The social kit emits posts for X, Bluesky, Threads, and LinkedIn, and a fact sheet for the Show HN post and the Product Hunt first comment. A person writes those two.
<!-- hraness-launch:end --><!-- hraness-delivery:start -->- Treat the user's request to change this repository as standing authorization for routine task-owned commits, pushes, pull requests, merges, releases, deployments, and production verification after the gates applicable to that action pass. Do not ask for duplicate confirmation. Build confidence through relevant automated checks, bounded diagnostics, and independent review, not another human approval. Passing checks does not expand task scope or authority.
- Prefer agentic service provisioning for new infrastructure. Check Vercel Marketplace for a native product that can provision the required resource first; use Stripe Projects as a supported alternative when it better covers the service or the Marketplace route only connects an existing account. Verify the current catalog, account, region, plan, recurring cost and resource capabilities before selecting a route. Prefer supported provider CLIs or APIs over browser-only setup when neither catalog fits, and explain the concrete exception. Reuse existing owner-controlled resources where appropriate; this preference alone does not authorize migrations, duplicate accounts, paid upgrades or wider access. Continue setup already authorized by the task and budget without duplicate confirmation. Keep provider credentials and generated environment files private, complete required interactive authentication, and verify deployment, persistence and recovery separately from successful provisioning.
- Separate artifact admission from live qualification and operational activation. Use applicable automated source, security, package/install, and provenance evidence for artifact admission; live provider qualification is not a universal publication prerequisite. Preserve explicit live acceptance criteria and require relevant live evidence for claims that depend on it. If publication or an artifact's install, upgrade, or default-use path activates risky unqualified behavior, keep that behavior guarded or disabled, or obtain bounded relevant evidence before shipping or activation.
- Use the repository's documented delivery workflow and preserve the identity, target, capacity, migration, and recovery guards applicable to operational activation. Replace an obsolete gate through a reviewed source and policy change with corresponding tests, never an ad hoc skip. Preserve every runtime-enforced approval, access control, branch protection, environment rule, safety policy, and required final gate. Ask for user input only when delivery needs a material product decision, missing credentials or authority, unavoidable interactive authentication, an irreversibly destructive action outside task scope, or resolution of a failure that cannot be handled safely and autonomously.
- Preserve production and user data throughout delivery. Inspect the exact account, environment, deployment, and data target before writes. For data changes, inspect a dry run or equivalent migration plan and validate the recovery path before any effect that could lose or corrupt data. Prefer additive, backward-compatible migrations and bounded batches. Record mutation intent, use idempotency or conditional writes, and reconcile uncertain results before retrying. Verify deployed identity, health, and relevant data invariants after delivery. Routine delivery never authorizes resetting, truncating, dropping, or overwriting user data; stop the unsafe operation if preservation or recovery cannot be established.
- Prefer short-lived repository workload identities such as OIDC trusted publishing, GitHub Apps, and narrowly scoped machine identities. Use unattended stable publication and production promotion when supported by the provider and repository. Establish supported machine authority once and verify it with a non-publishing preflight where available; routine releases should not require recurring interactive authentication or conversational approval. Releases and deployments run without a human in the loop: do not add required reviewers, manual approval environments, or wait timers to release or deployment paths, and remove any you find through a reviewed change. Keep account two-factor authentication, and do not add long-lived personal tokens.
- Main delivery is unattended. Open the pull request and enable auto-merge in the same breath (
gh pr merge --auto --squash <number>), then move on; the requiredRequiredcheck is the reviewer. Until a repository's ruleset requires a check,--automerges immediately, so wait for green checks there before merging. Never request a human reviewer or add required approvals, code owners, required conversation resolution, merge queues, manual-approval environments, or wait timers, and remove any you find withscripts/apply-delivery-policy.pyfrom hraness/.github rather than by hand. Required checks run on the pull request head and are not re-required after main moves, so auto-merge never stalls behind another merge; main reruns the same gate after integration, and a red main is fixed forward by the next change. Repositories without CI use direct pushes to main. - Preserve useful reasoning fan-out, but avoid unnecessary checkout fan-out. Prefer subagents in the current task for bounded research, review, diagnosis, and focused checks when they can safely share one working tree; create a separate task or worktree only for independently deliverable divergent edits, an isolated verification tree, or a different execution environment.
- Give each expensive focused validation command and external wait one owner. The integration owner reviews that evidence and runs the repository-required aggregate or final gate once after convergence. Reuse evidence only for the exact Git tree, command, lockfiles, toolchain, relevant environment, and validity period, and never to skip a required final integration, merge, release, deployment, or production-verification gate.
- On Hraness development machines, use the installed host scheduler for heavyweight top-level commands when available. Keep ordinary work in the compute lane; give authenticated browser/dev-server/Chromium work one
browser-authowner and Mac-only validation onemac-nativeowner. - When a CI or policy gate scans complete Git history, check out the exact governed SHA and fetch only the fully qualified governed refs before scanning. Preserve the complete-history gate and reject unexpected refs instead of importing unrelated concurrent heads.
- At closeout, record applicable branch, PR, check, merge, release, deployment, and production evidence. Archive only conclusively finished tasks, never from silence alone, and reclaim only freshly revalidated clean merged worktrees through the guarded exact-path flow.
<!-- hraness-delivery:end --><!-- algal-skills:start -->ALGAL skills
- Prefer the globally installed
algal-*skills for bounded git state, diffs, repository survey/search, test and release gates, CI polling, and web fetches instead of repeated raw tool output. - At session start, if the
algalskill is unavailable, install the current skill pack for Claude Code, Codex, and Devin for Terminal withbunx skills add 0thernet/algal-skills --global --agent claude-code codex devin --skill '*' --copy --yes. - Confirm installation with
bunx skills list --global. If Bun or network access is unavailable, continue with repository-native tools instead of blocking delivery. - Treat ALGAL receipts as execution evidence, not provider attestation, and preserve the repository's normal verification and release gates.
<!-- algal-skills:end -->CI
<!-- hraness-ci:start -->- CI exists to admit a change in minutes, not to perform a ceremony. Every workflow declares
concurrency: { group: <name>-${{ github.ref }}, cancel-in-progress: true }(release and deploy workflows setcancel-in-progress: false), atimeout-minuteson every job, andpermissions: contents: readat the top with job-level widening only where needed. - One job named
Requiredcloses every check workflow:if: always(),needs:every blocking job, and a single step that fails unless eachneeds.<job>.result == 'success', orskippedbecause the change filter below reported its inputs unchanged. Branch policy requires onlyRequired(plus a provider's own automated admission status when the product depends on it). Never make CodeQL, scheduled, or advisory jobs required. - Cache by lockfile hash and restore before install:
Swatinem/rust-cache@v2(withsave-if: ${{ github.ref == 'refs/heads/main' }}) for Cargo,oven-sh/setup-bun@v2plusactions/cacheon~/.bun/install/cachefor Bun,actions/setup-nodecache oractions/cachefor npm/pnpm,actions/setup-pythonwithcache: piporastral-sh/setup-uvwith cache for Python. Playwright browsers are cached under~/.cache/ms-playwrightkeyed by the Playwright version. - Rust: install the pinned toolchain with
dtolnay/rust-toolchain(rustup toolchain installat most once per job,--profile minimal), setCARGO_INCREMENTAL: 0,CARGO_TERM_COLOR: always,CARGO_NET_RETRY: 10,RUSTFLAGS: -D warningsandRUST_BACKTRACE: shortat workflow level, usecargo nextestor onecargo test --workspace --lockedafter a sharedcargo build --all-targets --locked, runclippyandfmtonce on Linux only, install tools withtaiki-e/install-actionorcargo-binstallinstead ofcargo install, and build release binaries in one job whose artifact every later job reuses. Never build the same crate twice in one workflow. - Run the matrix Linux-first. A macOS or Windows job exists only when the product ships a native surface for that OS, runs the OS-specific tests only, and is never the only place a generic check runs. Split long serial script lists into parallel jobs that share one build artifact instead of one job that runs for twenty minutes.
- Skip work that cannot change the result inside the workflow: a change-detection job runs
dorny/paths-filter@v4(it needs job permissionpull-requests: read, andpredicate-quantifier: some-with-excludesneeds v4), and jobs whose inputs did not change skip through job-levelif:. Never putpaths,paths-ignore, orbranches-ignoreon thepull_requesttrigger of the workflow that producesRequired: a skipped workflow never reportsRequired, and the pull request can never merge. Everyuses:pins a major tag or a SHA with a version comment, and Dependabot keepsgithub-actionscurrent weekly with auto-merge. - Measure before and after: a CI change records the previous and new median wall time of the slowest workflow in its pull request body. Regressions that add more than a minute to
Requiredare reverted forward the same day.
<!-- hraness-ci:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

