agentleFS
joelhooksjoelhooks/uncomplect/AGENTS.md

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

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
  1. Very specific:

    Run pnpm fix only when you intend to rewrite files.

    line 67
  2. Very specific:

    Run pnpm turbo run check test build --concurrency=1 before deployment.

    line 71
  3. Very specific:

    Only updates and no-ops pass by default.

    line 80
  4. Distinctive:

    If a hook fails, fix the failure.

    line 100
  5. Very specific:

    Before writing, reviewing, or refactoring Effect or XState code, read the installed Effect package's AGENTS.md first, for example …

    line 104
  6. Distinctive:

    Every quote cites a source in the bibliography.

    line 135
  7. Common:

    Read-only. No auth, writes, visitor storage, or runtime secrets without owner sign-off.

    line 141
  8. Very specific:

    No comments in code. Lint and diagnostic overrides are targeted and carry a reason after --.

    line 143
  9. Distinctive:

    Put one idea in each sentence.

    line 174
  10. Distinctive:

    Use the same glossary term for the same thing.

    line 175
  11. Distinctive:

    Prefer lists to paragraphs.

    line 176
  12. Distinctive:

    Keep lore titles as claims.

    line 177
  13. Distinctive:

    Write for a person first. Avoid hedged 'X, not Y' asides and narration about sources.

    line 182
  14. Very specific:

    When a call is unclear, get a second opinion from a Pi session on openai-codex/gpt-6-astra:xhigh before asking the owner.

    line 189

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.0 and pnpm 11.3.0; do not replace pnpm with Bun or npm for installs
  • Effect 4.0.0 and @effect/platform-node 4.0.0, matched to the rat-stack template pin.
  • XState 6.0.0-alpha.70 for finite lifecycles, retries, cancellation, and resumability (today only the deploy driver's machine)
  • @xstate/effect 1.0.0-alpha.9 bridges the two: machines run as scoped Effects via createEffectActor, side effects are declared createEffectLogic actors. vendor/README.md keeps the rules for the next unpublished pin
  • Alchemy 2.0.0-beta.83 (Infrastructure as Effects) for every cloud resource; declared in apps/infra/alchemy.run.ts, authenticated through Alchemy profiles, never through env vars in this repo
  • TypeScript 7.0.2 in strict mode, patched by @effect/tsgo 0.54.0 in prepare so the Effect language service diagnostics in tsconfig.base.json fail tsc, not just the editor. Escape hatch for a real boundary: // @effect-diagnostics-next-line <rule>:off with a reason
  • @effect/vitest 4.0.0 for every Effect test: it.effect and it.layer(layer); Effect.run* and ManagedRuntime.make in test files are a lint error
  • @oxlint/plugins 1.88.0 for the two typed lint rules in scripts/oxlint-plugin-*.ts and the vendored anti-slop rules in tools/oxlint/anti-slop/ (all generic rules plus the Effect group, at error). The copy is ours; UPSTREAM.md there says where it came from and how to take upstream fixes
  • Oxlint 1.88.0 with Ultracite 8.0.1, Oxfmt 0.73.0, and Turborepo 2.11.9
  • varlock 1.23.0: declare every env var in .env.schema, never read .env.local directly, run pnpm env:check after 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

PackagePathRole
@uncomplect/capabilitypackages/capabilitydefineContract, implement, and the toCommand and toToolkit projections. HTTP, RPC, and code-mode projections are cut.
@uncomplect/corepackages/coreThe corpus: schemas, validation, search, Markdown rendering, the five MCP contracts and their handlers, and corpusArbitrary for property tests
@uncomplect/check-harnesspackages/check-harnessVerdict shape and check runner used by the deploy driver
@uncomplect/deploypackages/deployTyped deploy driver: plan classification, apply, post-deploy checks, and rollback
@uncomplect/siteapps/siteContent build (scripts/) and the Cloudflare Worker Site that serves pages, Markdown twins, raw skills, agent indexes, and /mcp
@uncomplect/infraapps/infraAlchemy Stack Uncomplect: the adopted, retained uncomplect.com zone and the Site Worker

Nouns

NounHomeRuntime job
Corpuscontent/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
Quotecontent/corpus.yaml quotesA short verbatim quotation with its source. Every blockquote on a published page must match one
Entry idcontent/corpus.yamlStable kebab-case id, unique across every kind and never reused
Contractpackages/core/src/contracts.tsShared name, schemas, failure, and annotations for one MCP tool
Capabilitypackages/core/src/capabilities.tsBinds one contract to its handler with implement
Projectionpackages/capability/src/to-<surface>.tsExposes implemented capabilities on one surface
Site contentapps/site/src/content.generated.tsBuild output: every page as HTML and Markdown, plus raw files; generated, never edited

Commands

CommandPurpose
pnpm installInstall workspace dependencies
pnpm devRun the Stack under alchemy dev; the Worker listens on port 1337
pnpm --filter @uncomplect/site generateValidate the corpus and write apps/site/src/content.generated.ts and apps/site/dist/content/manifest.json
pnpm checkTypecheck, verify formatting, and run type-aware linting
pnpm lintType-aware lint plus format check only; turbo run check runs this once at the root as //#lint
pnpm fixApply Oxfmt and safe Oxlint fixes
pnpm testBuild and run the Vitest suite once
pnpm buildCompile package outputs
pnpm typecheckturbo run typecheck
pnpm vendor:agent-sourcesShallow-clone Effect, effect-solutions, xstate, alchemy, better-auth, and Foldkit mirrors
pnpm infra:planPreview the Alchemy Stack diff without applying
pnpm infra:deploy / pnpm infra:destroyApply or tear down the Stack (asks for approval)
pnpm exec lefthook installInstall git hooks (also via prepare)
pnpm turbo run check test buildRequired 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=1 before deployment.
  • pnpm deploy:plan --profile <profile> reads and classifies the production plan without applying it.
  • pnpm deploy:prod --profile <profile> --yes applies that exact plan, then runs typed checks and a bounded watch.
  • pnpm deploy:rollback --profile <profile> --yes restores 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_MS sets a bounded override; verdicts retain failed attempts.
  • Application-secret resolvers belong in gitignored .env.production.local, under .env.schema keys. The root schema imports apps/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_PROFILE explicitly. It must match --profile. The driver refuses environment provider credentials.
  • .env.schema owns required production inputs. Missing inputs stop before planning. Verdicts record key names only.
  • Only updates and no-ops pass by default. Use --allow with 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 --ownerApproved as well as exact allow entries. A refused plan names the resources in the verdict.
  • --expectSha <full sha> refuses to plan or apply unless HEAD is that commit and the tree is clean.
  • DEPLOY_QUIET_WINDOWS lists UTC windows when deployProd must not apply: HH:MM times repeat daily, :MM times repeat hourly. Inside one, the driver waits up to DEPLOY_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 its verdictPath.
  • 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 read https://uncomplect.com: content generation on /, /index.md, and /terms/complect; every agent route; negotiation; MCP tools/list and search_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 check and pnpm 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 --refresh

Inventory: .agent_sources/README.md is generated in the local source mirror and is not part of this repository.

NeedPath
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 in packages/core/src/capabilities.ts, and projected with toToolkit. 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 from content/corpus.yaml and 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/uncomplect is synced from joelhooks/skills at the sourceRevision recorded in content/corpus.yaml; edit upstream, then sync. content/skills/durability is imported from the rat-stack drafts. The root skills/ 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. validateCorpus and buildSite collect 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/html above text/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 port
  • rat-stack-boundaries/no-cross-layer-imports enforces direction: apps → packages/core → packages/capability → Effect. packages/capability never imports core.
  • packages/core is runtime-safe: no Node built-ins, no Markdown parser. Build-only code (YAML, remark, crypto) lives in apps/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 from corpusArbitrary output.
  • entryMarkdown in core renders a term or principle once. The .md twin, llms-full.txt, and the MCP markdown field 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.json and checks it against etag and x-content-generation headers.

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:xhigh before 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 in tsconfig.base.json, lefthook.yml, scripts/vcs-command-policy.js).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.