RFC: AI conventions

[hannahhoward]

This RFC sets the conventions for how we work with AI. It absorbs and supersedes dedicated review time and stacked PRs: the norms live here, that document keeps the evidence and the tooling evaluation, and this PR adds the supersession pointer to it.

The asks:

1. FilOne Standard as the base of everyone's writing style, wired however you like; workspace-setup is the recommended path (it now auto-updates at session start, installs the output style, and installs the stacked-PR tooling).
2. Readable prose is the author's job — "this is unintelligible, revise so I can review" is a reasonable response to a PR.
3. AGENTS.md + one-line CLAUDE.md in every repo.
4. Stacked PRs are the default for big work, on GitHub native stacks via gh stack.
5. Dedicated review time stays: minimum an hour a day, first response within one business day.
6. An accelerated workflow for AI-built work: spec first with human review from a colleague, then self-review and merge the stack if you are confident; human review always on request; adversarial Codex review recommended, with setup steps for automatic reviews.

Branch protections already match the accelerated workflow: no repo in fil-forge or fil-one requires an approving review any more (PR-before-merge and status checks were left untouched).

Read the docs rendered:

• AI conventions
• dedicated review time and stacked PRs (supersession pointer)

🤖 Generated with Claude Code

https://claude.ai/code/session_0123NvBGzdiqJwgqx4Chs3R4

[Copilot]

Pull request overview

Adds a new RFC proposing standard conventions for FilOne AI tooling setup and agent guidance across repositories, aiming to make machine bootstrap, agent context, and generated prose consistent across engineers and repos.

Changes:

• Introduces a standardized bootstrap flow via the workspace-setup script.
• Proposes adopting the “FilOne Standard” as the default output style for generated prose.
• Proposes standardizing repository agent guidance with AGENTS.md plus a one-line CLAUDE.md import.

Suppressed comments (1)

rfcs/2026-08-ai-conventions.md:27

• In this sentence, filenames like AGENTS.md/CLAUDE.md are not formatted as code, but elsewhere in the RFC they are (e.g. AGENTS.md, CLAUDE.md). Using backticks consistently makes the filenames easier to scan.

You get a workspace directory that symlinks to your fil-forge and fil-one clone trees, clones the shared knowledge base, and writes the AGENTS.md, CLAUDE.md, and Claude Code settings that tie it together. It asks before installing the optional ai-dev process module; declining is fine. It will not disturb the checkouts you already have: clones stay wherever you keep them, and the workspace reaches them through symlinks. Mine still points at `~/projects/go/src/github.com` — nothing moved, and I work from a much simpler path than the full Go tree.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[bajtos]

I am hesitant to dictate a single workspace setup.

1. AFAICT, the proposed setup does not support Claude Code sessions running in the cloud.
2. The models and coding agents are constantly evolving at a very fast pace. A setup that worked two weeks ago will almost certainly become suboptimal in one or two months.

I prefer a workspace setup that

• is as lightweight as possible,
• is based on existing conventions and practices,
• and supports different working styles (Claude Code in terminal, Claude Code running in the cloud VMs orchestrated via Claude Desktop, Claude Code running via GitHub Actions, etc.)

My impression of workspace-setup/DESIGN.md is that it's building bespoke structures for things we can get for free if we adopt a monorepo.

[pyropy]

I agree with Miro on this one. This works well for terminal sessions, but not so much for the remote sessions.

[bajtos]

On one hand, I agree we need a higher writing standard than Claude's current default output style.

On the other hand, I am not sure if it's a good idea to force everyone to write in the same style - isn't that removing our personalities from our writing?

The more I reflect on my experience with LLM-produced prose, the more I am leaning towards the opinion that we should write more prose ourselves:

• Writing is an act of thinking; it helps the writer to clarify their thought.
• Even with custom instructions in place, LLMs tend to generate text that's too verbose and requires more effort to read. Producing such texts is IMO disrespectful to readers.

I don't yet have a fully formed opinion on this. What I think is a good start:

• Agree that we all configure our LLMs to use the FilOne Standard.
• Leave everyone the freedom to personalise those instructions as long as they preserve the spirit of the FilOne Standard.

[hannahhoward]

I would say this:

1. Yes, writing is thinking. It's not the only way to clarify thinking but I lean on it a lot as well.
2. Nothing in adopting a writing style changes that, we already have a standard unless everyone is already changing the default claude output style. My impression is that several people are not doing this.
3. There is a lot of writing that just doesn't need each that level of intention, people are already using claude code to generate it, and for all of that I want the version used to be better than Claude's default which is abysmal.

Broadly I don't want to prevent people from customizing, but I do want folks to use SOMETHING and for every dev who cares about writing prose enough to customize their writing output style there is a dev who's always preferred coding to writing in the first place and thinks Claude is now here to rescue them from prose entirely. For that dev, I want them to use this. (there's an extreme here where I wouldn't want such a dev on our team, but I've certainly witnessed sizable variation among the folks here)

[bajtos]

Rule changes go to knowledge-base by PR; pull your clone and re-run setup.sh to pick them up.

How will the process of distributing updates look in practice?

1. Miro opens a PR against the knowledge-base
2. Hannah approves it and one of them lands the PR.
3. How will Srdjan learn that they need to "pull their clone and re-run setup.sh"?

Can we find a distribution mechanism that's natively supported by coding agents, e.g. plugins or skills?

I think this is another argument in favour of a monorepo. With monorepo, knowledge-base changes are interleaved with code changes. A single git pull fetches everything together; we don't need to remember to pull the knowledge base.

[hannahhoward]

I agree with monorepo. Monorepo is a long path -- I welcome a proposal to get us there fast.

[pyropy]

We might want to instruct agents via AGENTS.md to periodically check for potential knowledge base updates.

[bajtos]

How do we want to handle (de)duplication of instructions that we want to share in more than one repository?

Example to consider:

We want to have the same short section in piri & ingot AGENTS.md with instructions related to how these two services are deployed as part of the FilOne Appliance. E.g. "read all sensitive configuration options via env vars, never via CLI flags or from config files".

How can we achieve that in the proposed setup?

[hannahhoward]

I think there's no obvious way around that other than monorepo

[bajtos]

How can we set up this workflow to work with Claude Code running in the cloud & controlled via the Claude Desktop app?

[bajtos]

See https://code.claude.com/docs/en/output-styles#create-a-custom-output-style

I am wondering if we should distribute the output style as a managed policy? ( .claude/output-styles inside the managed settings directory)

I think the missing step in this document is explaining where to put the output style definition file (User: ~/.claude/output-styles; Project: .claude/output-styles).

[bajtos]

I am trialling the following setup:

• Put the writing style to ~/.claude/output-styles/filone-writing-style.md
• In Claude Code >> /settings >> Output Style, select filone-writing-style.

[bajtos]

What are the six repos affected?

[alanshaw]

I'm worried that https://github.com/fil-one/knowledge-base contains a LOT of old and now defunct information about Storacha era (and earlier) will confuse agents (also humans!).

It's also not referencing the newly updated UCAN protocol specs or any of the RFCs we have been writing.

[alanshaw]

UCAN protocol specs addressed in https://github.com/fil-one/knowledge-base/pull/1

[alanshaw]

👌

[pyropy]

We might potentially want to account for git worktree workflows.

[pyropy]

I agree with Miro on this one. This works well for terminal sessions, but not so much for the remote sessions.

[pyropy]

We might want to instruct agents via AGENTS.md to periodically check for potential knowledge base updates.

[hannahhoward]

@bajtos @pyropy

A meta comment on how I've responded to your suggestions:

1. I've changed the ask significantly around writing style -- in short, I just want everyone to start from the writing style and customize it as you like, but understand you'll be accountable to writing being terrible.
2. The terminal setup remains as an easy path for those who want it, but not required, and I've updated to address concerns about staying up to date. Moreover, the settings and skills will be perfect for when we have a monorepo
3. The only clean way to address in all environments including remote sessions is to do a monorepo, which seems outside the scope of this RFC. I welcome such an RFC -- it feels important, but also, hard to imagine exactly how we scope it -- or alternative ways to set things up, though I'd push back on a setup where we keep updating every repo to stay in line.

[bajtos]

+1 to dedicate at least one hour per day for PR reviews.

held on the calendar

Can we give developers more flexibility in how they achieve the target?

For example, I prefer to start my day with deep implementation work and review PRs in the afternoon. (I do admit that I need more discipline there, because sometimes my focused session overruns. At the same time, a block on the calendar would not solve that for me, I need to find a different mechanism.)