uncomplect
AGENTS.md2 starsChanged 36 days agoMITView on GitHub
For a non-trivial task, start with skills/rat-stack-mode. This file is the repo law for agents and contributors working on uncomplect.com, a child project of rat-stack. It holds commands, validation rules, architecture constraints, and project stop rules. Read VISION.md for intent before planning substantial work. VISION.md does not override this file. Pi sessions also load .pi/APPEND_SYSTEM.md and the repo-local extension .pi/extensions/project.ts. Workspace package.json files declare the pinned stack. README.md summarizes it. Keep dependencies exact. Repo-local config wins. Record drift instead of…
- Reads credentials
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 repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-a-capabilitySkill
- add-a-lifecycle-machineSkill
- add-a-storeSkill
- gardenerSkill
- investigate-a-failureSkill
- keep-or-cutSkill
- learn-alchemySkill
- profile-a-workerSkill
- query-designSkill
- rat-stack-modeSkill
- shipSkill
- test-behaviourSkill
- uncomplectSkill
- write-a-wiki-pageSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
14 rules. About 1 is common, 7 are distinctive, and 6 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 67
Run pnpm fix only when you intend to rewrite files.
- Very specific: line 71
Run pnpm turbo run check test build --concurrency=1 before deployment.
- Very specific: line 80
Only updates and no-ops pass by default.
- Distinctive: line 100
If a hook fails, fix the failure.
- Very specific: line 104
Before writing, reviewing, or refactoring Effect or XState code, read the installed Effect package's AGENTS.md first, for example …
- Distinctive: line 135
Every quote cites a source in the bibliography.
- Common: line 141
Read-only. No auth, writes, visitor storage, or runtime secrets without owner sign-off.
- Very specific: line 143
No comments in code. Lint and diagnostic overrides are targeted and carry a reason after --.
- Distinctive: line 174
Put one idea in each sentence.
- Distinctive: line 175
Use the same glossary term for the same thing.
- Distinctive: line 176
Prefer lists to paragraphs.
- Distinctive: line 177
Keep lore titles as claims.
- Distinctive: line 182
Write for a person first. Avoid hedged 'X, not Y' asides and narration about sources.
- Very specific: line 189
When a call is unclear, get a second opinion from a Pi session on openai-codex/gpt-6-astra:xhigh before asking the owner.
≈ “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
Agent instructions
For a non-trivial task, start with skills/rat-stack-mode.
This file is the repo law for agents and contributors working on uncomplect.com, a child project of rat-stack. It holds commands, validation rules, architecture constraints, and project stop rules. Read VISION.md for intent before planning substantial work. VISION.md does not override this file. Pi sessions also load .pi/APPEND_SYSTEM.md and the repo-local extension .pi/extensions/project.ts.
Stack contract
Workspace package.json files declare the pinned stack. README.md summarizes it. Keep dependencies exact. Repo-local config wins. Record drift instead of silently migrating the project.
- pnpm workspaces + Turborepo (
apps/*,packages/*) - Node
>=24.18.0and pnpm11.3.0; do not replace pnpm with Bun or npm for installs - Effect
4.0.0and@effect/platform-node4.0.0, matched to the rat-stack template pin. - XState
6.0.0-alpha.70for finite lifecycles, retries, cancellation, and resumability (today only the deploy driver's machine) @xstate/effect1.0.0-alpha.9bridges the two: machines run as scoped Effects viacreateEffectActor, side effects are declaredcreateEffectLogicactors.vendor/README.mdkeeps the rules for the next unpublished pin- Alchemy
2.0.0-beta.83(Infrastructure as Effects) for every cloud resource; declared inapps/infra/alchemy.run.ts, authenticated through Alchemy profiles, never through env vars in this repo - TypeScript
7.0.2in strict mode, patched by@effect/tsgo0.54.0inprepareso the Effect language service diagnostics intsconfig.base.jsonfailtsc, not just the editor. Escape hatch for a real boundary:// @effect-diagnostics-next-line <rule>:offwith a reason @effect/vitest4.0.0for every Effect test:it.effectandit.layer(layer);Effect.run*andManagedRuntime.makein test files are a lint error@oxlint/plugins1.88.0for the two typed lint rules inscripts/oxlint-plugin-*.tsand the vendored anti-slop rules intools/oxlint/anti-slop/(all generic rules plus the Effect group, aterror). The copy is ours;UPSTREAM.mdthere says where it came from and how to take upstream fixes- Oxlint
1.88.0with Ultracite8.0.1, Oxfmt0.73.0, and Turborepo2.11.9 - varlock
1.23.0: declare every env var in.env.schema, never read.env.localdirectly, runpnpm env:checkafter schema edits
The base Effect plugin owns diagnostic severity. Child configs may add exact allowedUnstableApis only for modules warned about in that scope. Do not use subtree prefixes, copy severity maps, or set ignoreEffectWarningsInTscExitCode to true.
Packages
| Package | Path | Role |
@uncomplect/capability | packages/capability | defineContract, implement, and the toCommand and toToolkit projections. HTTP, RPC, and code-mode projections are cut. |
@uncomplect/core | packages/core | The corpus: schemas, validation, search, Markdown rendering, the five MCP contracts and their handlers, and corpusArbitrary for property tests |
@uncomplect/check-harness | packages/check-harness | Verdict shape and check runner used by the deploy driver |
@uncomplect/deploy | packages/deploy | Typed deploy driver: plan classification, apply, post-deploy checks, and rollback |
@uncomplect/site | apps/site | Content build (scripts/) and the Cloudflare Worker Site that serves pages, Markdown twins, raw skills, agent indexes, and /mcp |
@uncomplect/infra | apps/infra | Alchemy Stack Uncomplect: the adopted, retained uncomplect.com zone and the Site Worker |
Nouns
| Noun | Home | Runtime job |
| Corpus | content/ | The public source of truth. corpus.yaml holds sources, quotes, terms, short principles, skill metadata, and retired ids. principles/<id>.md holds long principle pages; the filename is the id. skills/<id>/ holds each published skill and its reference files |
| Quote | content/corpus.yaml quotes | A short verbatim quotation with its source. Every blockquote on a published page must match one |
| Entry id | content/corpus.yaml | Stable kebab-case id, unique across every kind and never reused |
| Contract | packages/core/src/contracts.ts | Shared name, schemas, failure, and annotations for one MCP tool |
| Capability | packages/core/src/capabilities.ts | Binds one contract to its handler with implement |
| Projection | packages/capability/src/to-<surface>.ts | Exposes implemented capabilities on one surface |
| Site content | apps/site/src/content.generated.ts | Build output: every page as HTML and Markdown, plus raw files; generated, never edited |
Commands
| Command | Purpose |
pnpm install | Install workspace dependencies |
pnpm dev | Run the Stack under alchemy dev; the Worker listens on port 1337 |
pnpm --filter @uncomplect/site generate | Validate the corpus and write apps/site/src/content.generated.ts and apps/site/dist/content/manifest.json |
pnpm check | Typecheck, verify formatting, and run type-aware linting |
pnpm lint | Type-aware lint plus format check only; turbo run check runs this once at the root as //#lint |
pnpm fix | Apply Oxfmt and safe Oxlint fixes |
pnpm test | Build and run the Vitest suite once |
pnpm build | Compile package outputs |
pnpm typecheck | turbo run typecheck |
pnpm vendor:agent-sources | Shallow-clone Effect, effect-solutions, xstate, alchemy, better-auth, and Foldkit mirrors |
pnpm infra:plan | Preview the Alchemy Stack diff without applying |
pnpm infra:deploy / pnpm infra:destroy | Apply or tear down the Stack (asks for approval) |
pnpm exec lefthook install | Install git hooks (also via prepare) |
pnpm turbo run check test build | Required validation before claiming a change is ready |
Run pnpm fix only when you intend to rewrite files. Finish with pnpm turbo run check test build.
Deploy
- Run
pnpm turbo run check test build --concurrency=1before deployment. pnpm deploy:plan --profile <profile>reads and classifies the production plan without applying it.pnpm deploy:prod --profile <profile> --yesapplies that exact plan, then runs typed checks and a bounded watch.pnpm deploy:rollback --profile <profile> --yesrestores prior Worker versions from a local apply receipt. It requires explicit approval; no automatic rollback runs.- Recovery evidence lives in gitignored
.rat/deploy/. Rollback writes separate progress receipts and preserves its source. - Content-version mismatches retry for 120 seconds by default.
DEPLOY_CONTENT_VERSION_DEADLINE_MSsets a bounded override; verdicts retain failed attempts. - Application-secret resolvers belong in gitignored
.env.production.local, under.env.schemakeys. The root schema importsapps/site/.env.schema, so deploy commands type the Worker's keys too; the root owns the keys it omits. The root commands run varlock in production mode; provider credentials remain profile-only. - Set
ALCHEMY_PROFILEexplicitly. It must match--profile. The driver refuses environment provider credentials. .env.schemaowns required production inputs. Missing inputs stop before planning. Verdicts record key names only.- Only updates and no-ops pass by default. Use
--allowwith a JSON array of exact{resource, action}pairs for other actions. - An allow-list does not grant approval. Replacements and deletions still need owner sign-off, recorded with
--ownerApprovedas well as exact allow entries. A refused plan names the resources in the verdict. --expectSha <full sha>refuses to plan or apply unlessHEADis that commit and the tree is clean.DEPLOY_QUIET_WINDOWSlists UTC windows whendeployProdmust not apply:HH:MMtimes repeat daily,:MMtimes repeat hourly. Inside one, the driver waits up toDEPLOY_QUIET_WINDOW_MAX_WAIT_MS(default 0), then refuses.- Deploy commands write the full verdict to
.rat/deploy/<profile>/and print one summary line with itsverdictPath. - Classification reads Alchemy Plan values, including binding and task changes. Retention is a physical-resource backstop, not a delete guard: it removes state rows and leaves cloud objects. Apply receipts list confirmed retained orphans. Alchemy confirmations use the capability approval service; unattended input prompts fail typed.
- Partial apply exits 4 and names completed and incomplete resources. A crash exits 5. Unknown evidence never establishes health.
- The driver refuses Alchemy state-store bootstrap during planning. Bootstrap needs separate authorization.
- The deploy profile is
ratstack(same Cloudflare account as ratstack.sh). Post-deploy checks readhttps://uncomplect.com: content generation on/,/index.md, and/terms/complect; every agent route; negotiation; MCPtools/listandsearch_terms. - Procedure: ship, with project commands in
skills/ship/references/project.md.
Fence (cheating is uncomfortable)
Why lives in AGENTS.md / VISION.md. The stack and hooks are the enforceable fence. Fence wins over prose.
- Lefthook pre-commit runs
pnpm checkandpnpm test - Agents must not use
git … --no-verify(or equivalent hook bypass) - Blocked by: Pi
.pi/extensions/git-interceptor, Cursor.cursor/hooks.json, Claude Code.claude/settings.json - Policy source:
scripts/vcs-command-policy.js
If a hook fails, fix the failure. Do not disable the fence.
Source-first Effect / XState work
Before writing, reviewing, or refactoring Effect or XState code, read the installed Effect package's AGENTS.md first, for example packages/core/node_modules/effect/AGENTS.md. It ships with the installed version, so it is never stale. Then inspect vendored source for the pinned versions. Populate mirrors:
pnpm vendor:agent-sources
# or
./scripts/vendor-agent-sources.sh --refreshInventory: .agent_sources/README.md is generated in the local source mirror and is not part of this repository.
| Need | Path |
| Effect Schema, Context.Service, CLI | .agent_sources/github.com/Effect-TS/effect/ |
| Idiomatic Effect | .agent_sources/github.com/kitlangton/effect-solutions/ |
| XState | .agent_sources/github.com/statelyai/xstate/ |
@xstate/effect (v6 Effect bridge) | .agent_sources/github.com/statelyai/xstate/packages/xstate-effect/ (README.md, docs/, src/*.test.ts) |
| Alchemy resources, Cloudflare, AWS | .agent_sources/github.com/alchemy-run/alchemy/ and https://alchemy.run/llms.txt |
Refs are derived from the workspace pins, so bumping a package and re-running the script keeps them matched. The pi-effect tool reads the Effect mirror in place; it needs no link.
Mirrors are reference material, not runtime dependencies. Exclude them from typecheck, test, lint, and format. Do not vendor product-specific corpora in this template.
Source control
Preserve existing work. Inspect status before editing, stage only files changed for the current task, and do not commit generated output, secrets, or populated .agent_sources/github.com/ trees. Use the repository's existing source-control tool; do not initialize or migrate one without approval. Never pass --no-verify to git.
Project law
- One contract, every surface. Every MCP tool is a contract in
packages/core/src/contracts.ts, implemented inpackages/core/src/capabilities.ts, and projected withtoToolkit. Do not hand-roll a tool, route, or schema that repeats a contract. - The corpus is the source of truth. Pages, Markdown twins,
llms.txt,llms-full.txt, the agent-skills index, and MCP results are all derived fromcontent/corpus.yamland the skill files. Never hand-edit generated output. - Ids are forever. Every term, principle, skill, and source has a kebab-case id unique across every kind. To remove an entry, move its id to
retired; the build refuses a retired id. - Every quote cites a source in the bibliography. Quotes stay short and verbatim. Do not add a factual claim or quote you cannot point at. The build refuses a blockquote that does not match a recorded quote.
- Published skills are copies.
content/skills/uncomplectis synced fromjoelhooks/skillsat thesourceRevisionrecorded incontent/corpus.yaml; edit upstream, then sync.content/skills/durabilityis imported from the rat-stack drafts. The rootskills/folder holds agent skills for working on this repo and is not published. - Imported text loses internal lines before publishing: "Exact source:" lines, library citation records, and links to private hosts.
- The build fails closed and complete.
validateCorpusandbuildSitecollect every independent issue (duplicate ids, dangling related ids, missing sources, dangling internal links, unsupported Markdown) before failing, and each issue says how to fix it. - Markdown is the default machine representation. A page returns HTML only when the client ranks
text/htmlabovetext/markdown. - Public boundary: no private Brain, machine topology, secrets, or transcripts in
content/,skills/, or any served file. - Read-only. No auth, writes, visitor storage, or runtime secrets without owner sign-off.
- Schemas are the contract; errors are part of the interface; prefer property and model tests (
it.prop,corpusArbitrary); plant a bug before trusting a new property. - No comments in code. Lint and diagnostic overrides are targeted and carry a reason after
--. - Pins stay exact.
Architecture
content/corpus.yaml ──┐
content/principles/ ──┤ apps/site/scripts/generate-content.ts
content/skills/<id>/ ─┤ loadCorpus → buildSite (validate, render,
▼ link and anchor check, quote check)
apps/site/src/content.generated.ts
▼
apps/site/src/worker.ts (Cloudflare Worker "Site")
├─ content-routes.ts pages, .md twins, raw files, 404, redirects
└─ site-routes.ts toToolkit(capabilities) → McpServer at /mcp
▲
packages/core contracts, handlers, CorpusSource portrat-stack-boundaries/no-cross-layer-importsenforces direction: apps →packages/core→packages/capability→ Effect.packages/capabilitynever imports core.packages/coreis runtime-safe: no Node built-ins, no Markdown parser. Build-only code (YAML, remark, crypto) lives inapps/site/scripts/and never reaches the Worker graph.- Handlers read the corpus through
CorpusSource. The Worker provides it from the generated module; tests provide it fromcorpusArbitraryoutput. entryMarkdownin core renders a term or principle once. The.mdtwin,llms-full.txt, and the MCPmarkdownfield all use it.- MCP speaks the stateless 2026-07-28 protocol only. Older protocols need a session store; that is an open decision in
VISION.md. - The deploy driver reads the generation from
apps/site/dist/content/manifest.jsonand checks it againstetagandx-content-generationheaders.
Wiki writing
Lore and system pages use low prose, about 80% ASD-STE100 Simplified Technical English. This is a house style, not certification.
- Aim for sentences of 20 words or fewer. Descriptive sentences may use up to 25 words.
- Put one idea in each sentence. Use active voice and present tense.
- Use the same glossary term for the same thing. Remove idioms and filler.
- Prefer lists to paragraphs. Put one instruction in each step.
- Keep lore titles as claims. Keep Joel's voice unchanged inside quotes.
- Be plain and strict, not robotic.
Use a visual only when it explains the point. Choose a fenced box-drawing diagram for flow or topology, a table for trade-offs or state, pseudocode for logic, or a shallow file tree. Keep diagrams below 80 columns. Give each visual one or two nearby sentences. Add a What to notice line only when the point is not obvious from those sentences. Do not add decorative visuals.
Write for a person first. Avoid hedged 'X, not Y' asides and narration about sources.
The content generator warns on sentences above 25 words and paragraphs above four sentences in lore and systems pages. It also warns on history wording, contrast hedges, and em dashes. It reads parsed Markdown prose. The style rules skip quoted spans, blockquotes, code, links, tables, and frontmatter. Length rules still count link labels. Warnings show file:line and a total count. They never fail the build. Fix new warnings or explain why they remain.
Boundaries and sign-off
- Safe by default: new terms, principles, and sources that pass the content build; skill text synced from the skills source; new or tighter tests and lint rules; README, AGENTS.md, VISION.md, and
.brain/edits;pnpm deploy:plan. - When a call is unclear, get a second opinion from a Pi session on
openai-codex/gpt-6-astra:xhighbefore asking the owner. - Needs owner sign-off: any deploy (
pnpm deploy:prod,pnpm infra:deploy); retiring an id; adding or changing a dependency version; anything that writes, stores visitor data, or needs a runtime secret; a plan that replaces or deletes a resource; loosening the fence (oxlint.config.ts, the diagnostics map intsconfig.base.json,lefthook.yml,scripts/vcs-command-policy.js).
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.

