Fresh Agent Rules

The Deno web framework built on Preact.

Overview

More than half of Fresh's file explains architecture: how a request becomes HTML, how islands hydrate, and how its two build paths differ. Repository rules take up less space.

Architecture as narrative Hard prohibitions

Documents

└──

Techniques in this file

01 / Architecture as narrative

The request lifecycle, numbered

Nine steps from handler to response, naming the file at each hop: routing, context creation, the middleware chain built as nested closures, layout composition, render, the boot script, and the response headers.

The island mechanism, both halves

On the server, a diff hook wraps island components in HTML comments and collects their props. On the client, boot finds those markers and hydrates each island. The documented marker format is their shared contract.

87  comment markers: `<!--frsh:island:NAME:PROPSIDX:KEY-->...<!--/frsh:island-->`

03 / Hard prohibitions

Three git rules covering irreversible operations

Never amend, never force push, always create new commits. Lockfile changes are not committed unless the PR is about dependencies, with the reason given as noisy and environment-specific diffs.

Source excerpt starting at line 42.
42- **Never amend commits or force push.** Always create new commits.

One command standing in for CI

A single task runs formatting, linting, type checking and tests, and is named as the thing to run before pushing. The CI section below lists the eight steps the pipeline runs, so the coverage of the shortcut is visible.

A known-bad situation with its upstream issue

Lockfile hashes pointing at a moving branch go stale, and the normal reload command cannot fix them. The file states that the hash is edited by hand in that case and links the upstream issue.

Ideas for your repo

Write the request lifecycle as numbered steps with the owning file at each hop.
Give the agent one command that stands in for CI, and list what it covers.
State the irreversible git operations as absolute prohibitions.
Where a normal command cannot fix a known problem, say so and link the upstream issue.