Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/fork-ci-tests.txt
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@
.github/scripts/fork-vitest-gc-check.test.cjs
.github/scripts/fork-workflow-triggers.test.cjs
fork-ci/actions/ci-demand/ci_demand.test.py ~17s
fork-ci/actions/doc-check/doc_check.test.py
fork-ci/actions/docs-scope/docs-scope.test.py ~12s
fork-ci/actions/fleet-route/fleet_route.test.py
fork-ci/actions/fleet-watch/fleet_watch.test.py
Expand Down
2 changes: 1 addition & 1 deletion FORK_CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ These change only how this repository is built, tested and released, not the app
| Pull requests from outside run nothing; four outside-started upstream workflows and `issue-vouch.yml` are deleted and kept deleted. | No code from an outside pull request runs with this repository's runners or tokens. | none | always | [#12](https://github.com/scuttletoby/t3code/pull/12), [#14](https://github.com/scuttletoby/t3code/pull/14), [#23](https://github.com/scuttletoby/t3code/pull/23) |
| A weekly check that the repository's interaction limit never lapses. | Outsiders cannot post while the limit holds. | none | always | [#30](https://github.com/scuttletoby/t3code/pull/30) |
| Secret scan on every push and pull request. Known false alarm: a new pre-release version of a package with "key" in its name, in `pnpm-lock.yaml`, is a finding until its exact value is allowed in `.gitleaks.toml`. | The fork is public: no token or key may land in it. | none | always | [#75](https://github.com/scuttletoby/t3code/pull/75), [#206](https://github.com/scuttletoby/t3code/pull/206), [#207](https://github.com/scuttletoby/t3code/pull/207), [#212](https://github.com/scuttletoby/t3code/pull/212), [#299](https://github.com/scuttletoby/t3code/pull/299) |
| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned, test-select), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141), [#256](https://github.com/scuttletoby/t3code/pull/256) |
| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned, test-select, doc-check), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141), [#256](https://github.com/scuttletoby/t3code/pull/256) |
| fork-ci PR queue: merges armed pull requests in order once their reviews and checks pass. | Merges without someone watching each pull request. | none | only where used | [#18](https://github.com/scuttletoby/t3code/pull/18), [#19](https://github.com/scuttletoby/t3code/pull/19), [#20](https://github.com/scuttletoby/t3code/pull/20), [#21](https://github.com/scuttletoby/t3code/pull/21), [#32](https://github.com/scuttletoby/t3code/pull/32), [#61](https://github.com/scuttletoby/t3code/pull/61), [#70](https://github.com/scuttletoby/t3code/pull/70), [#71](https://github.com/scuttletoby/t3code/pull/71) |
| fork-ci head check and head gate: the queue's required check, posted by a GitHub App and judged by the default branch's code. | A pull request cannot fake its own required check. See [gate trust](docs/fork/gate-trust.md). | none | only where used | [#33](https://github.com/scuttletoby/t3code/pull/33), [#85](https://github.com/scuttletoby/t3code/pull/85), [#87](https://github.com/scuttletoby/t3code/pull/87) |
| Host kits (`fork-kit/`): `gh-apps` (GitHub App tokens for agents), `heavy` (run builds in a capped slice), `golive` (move a boot service to a new build; core and `check` so far), `desk` (a desktop's side of a fleet desk pool). | Things the fork installs on a machine, each with an installer, a self-check and tests. | none | only when installed | [#86](https://github.com/scuttletoby/t3code/pull/86), [#173](https://github.com/scuttletoby/t3code/pull/173), [#182](https://github.com/scuttletoby/t3code/pull/182), [#183](https://github.com/scuttletoby/t3code/pull/183) |
Expand Down
85 changes: 85 additions & 0 deletions docs/fork/agent-rules.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Agent rules (general)

Fork only. The rules for coding agents that hold in every project and on every machine, each written once. A
project's `AGENTS.md` and a machine's instruction file link here and add only their facts; they never copy a rule.
Where a tool enforces a rule, the tool is the authority.

## Facts each place supplies

- The machine's instruction file: its capacity check and sizes, agent limits, how the owner runs a command there.
- The project's `AGENTS.md`: build slot, test servers, where owner questions go, the state file.
- The [model-guard](../../fork-kit/model-guard/README.md) policy file: allowed models and efforts.
- The project's [review](../../fork-kit/review/SKILL.md) and [doc-check](../../fork-ci/actions/doc-check/README.md)
configs: review weights and rounds; instruction file budgets.

## Instruction files

- Only what every reader needs every time; the rest is a skill or doc, named in one line with when to read it.
_Why: they are re-read on every call._
- Current rules only: update in place, delete what you replace. _Why: git keeps history; old text misleads._
- Decisions go in issue comments; history in git, issues and releases; live state in a state file; lessons in
memory until a tool enforces them; what code or git can tell, nowhere. _Why: one place each._
- A change that adds a guard (check, hook, test) deletes the rule text it replaces; a line outside the repository
is named in the pull request. _Why: no stale copies._
- A rule that looks wrong goes to the owner with the reason. _Why: working around it hides the flaw._

## General first

- CI, review, agent and ops tooling is general by default: project facts in a project config file, project-only
parts in a thin adapter, a "General vs project" section in each pull request. _Why: the next project gets it._
- A check that refuses beats a rule in a doc; call a guard a security boundary only when it is one.
_Why: agents forget; checks do not._
- No guessed waits, no time gates: wait on real progress, advance when the check passes. _Why: guesses fail._

## Machine safety

- Before a build, a test server or several agents, run the capacity check with the job's size. On no: do not start,
do lighter work, check again on the next wake. Gate with `check && cmd`, never pipe it.
_Why: overload kills agents; a pipe hides the no._
- Builds and test servers only through the project's build slot and the capped slice (`heavy`). _Why: one cap._
- Stop every server, watcher, daemon and browser tab you started; list what is left to prove it.
_Why: leftovers starve the next job._
- Deletes: guarded variables (`rm -rf "${DIR:?}/${NAME:?}"`) or literal paths; look at the target first.
_Why: an empty variable deletes the wrong tree._
- Never print, commit or paste a key, token or credential file; use it only through its command, and ask for one
only through the secret request tool. _Why: chat and logs are kept._

## Work and pull requests

- Re-check the live state before acting on a brief, a summary or an old status. _Why: facts go stale._
- CI decides: fix the cause of red CI, never bypass it. No CI-skip marker in a commit message, even quoted.
_Why: it silently skips the real CI._
- Small, focused pull requests; one push per fix round. _Why: each push restarts CI._
- A test that fails the same way twice is known-failing: its fix goes first, no reruns. _Why: reruns waste CI._
- "Fixes #N" only when the fix is proven; else "Part of #N". _Why: merging closes the issue._
- Never update pull request branches by hand when a merge queue does it. _Why: it restarts every CI at once._
- Reports, handoffs and review notes go in the pull request or an issue. _Why: the repository holds current text._
- Reviews follow the [review skill](../../fork-kit/review/SKILL.md) (weights, the state question, round limit);
never restate it. _Why: one source._
- No `git stash`; edit tracked files in place. _Why: worktrees share the stash; a move drops `+x`._
- In a fork: build on upstream's mechanisms, check upstream first, never push, comment or open anything upstream.
_Why: thin forks rebase cleanly; upstream is the owner's._
- Public repositories hold nothing personal (names, hosts, addresses, home paths, tokens). _Why: anyone reads it._

## Agents and orchestrators

- Each task gets a chosen model and effort from the policy file, never the launch default. _Why: cost is a choice._
- One job per agent. New work is a new agent with a short brief naming the old thread; a running agent gets only
what changes its job. _Why: a long context costs on every call._
- Never end a turn on your own background run, or on remote work with nothing to wake you; wait in the turn or
register a wake-up and say what will wake you. _Why: nothing else wakes you._
- Ask tools for small outputs: list limits, JSON fields, `git diff --stat`, test output through `tail`.
_Why: output stays in context._
- An orchestrator stays responsive: longer work goes to a sub-agent, no sleep or poll loops; it keeps a terse
state file outside `/tmp`. _Why: owner messages wait otherwise._
- Post first, read the link back from the output, then pass it on. _Why: guessed links are wrong._
- Write briefs with the Write tool or a quoted heredoc (`<<'EOF'`). _Why: backticks in `<<EOF` run._

## The owner

- Automate what does not need the owner. Only real decisions go to them: plain English, recommendation first.
- Before asking, read the issue and its comments; ask only what is open. One issue per question, plus a short
list in chat. A sub-agent asks its orchestrator, never the owner. _Why: repeat questions waste their time._
- A command the owner must run goes at the top of the reply, ready to paste, for a machine they can reach.
- Make every tool call first and write the reply last. _Why: T3 hides the user's message otherwise._
- Legal, licensing and privacy decisions are the owner's: point them out, never conclude.
Loading
Loading