commonfabric/labs/writing-code

Writing Code in Common Fabric

This skill is a map, not a recipe. It assumes you know how to write TypeScript. What it supplies is the part you cannot derive from the tree: which of this repository's documents governs what you are about to touch, and which of its conventions nothing will catch for you.

All paths are relative to the repo root.

Read these before your first edit

• docs/development/DEVELOPMENT.md — coding style and design principles. §

Style & Conventions is the part that applies to every edit; § Code Design & Principles is the part a reviewer will hold a new abstraction to.

• docs/development/code-comment-style.md — how a comment is written, // and

JSDoc alike. A comment describes the system as it stands, and nothing comes between a doc comment and the declaration it documents. Blank lines bound that pairing on both sides: one above the comment, one below the declaration.

Everything below this line is read-when-it-applies. Reach for it by what you are doing, not by reading the list through.

What governs what you are touching

• Adding or reordering class members — docs/development/DEVELOPMENT.md, §

Classes.

• Adding an import — the same document, § Imports, for how imports are

grouped and collated; docs/development/imports.md for what may not import what at all.

• Writing a new file — docs/development/code-comment-style.md, "File

headers".

• Writing or changing a test — docs/development/unit-test-coding-style.md

before the first one, and docs/development/TESTING.md for how the suites run. Not every file in the tree follows the conventions, so a neighbor is not evidence of them.

• Making anything wait — docs/development/waiting-in-tests.md. Avoiding

timeouts, retry loops, and sleeps is a repository-wide principle, not a testing one.

• Adding or changing an experimental flag —

docs/development/EXPERIMENTAL_OPTIONS.md, which is the registry as well as the guidance, and is updated in the same change.

• Adding a dependency — docs/development/DEPENDENCIES.md.
• Adding a workspace package — .claude/rules/workspace-packages.md. A

missing test task is the edit most often forgotten; the root test runner refuses to start and names the package.

• Writing a pattern — the pattern-dev skill at

skills/pattern-dev/SKILL.md, in addition to this one.

• Changing behavior a live document describes — docs/README.md. That

document is part of your change, not a follow-up to it.

docs/development/README.md indexes the rest; docs/features/README.md indexes one document per subsystem. Read the relevant one before changing a subsystem you have not worked in before.

The conventions nothing will catch

This is the part worth knowing by heart, because a green run is not evidence about any of it. deno fmt settles line width, indent, semicolons, and quotes; deno lint and deno task check settle types, untagged TODOs, and import mechanics; the gates in AGENTS.md, § Automated gates settle the rest of what a machine can settle. Everything here passes all of that and can still be wrong, so it is the set a reviewer is left to find by reading. Tells include, for example:

• Class shape. #privateName over TypeScript's private; a class exposes

no enumerable properties; members run in the order § Classes gives. A private field type-checks clean and is still an own enumerable property. A test that needs a # member reaches it through an accessForTestingOnly getter, never through a cast on the instance; § Classes says how that getter is shaped and what it cannot cover.

• Test-only exports. Code a package offers only to other packages' tests

goes behind its ./for-testing-only export-map entry, in no barrel, each value export carrying a ForTestingOnly suffix (_FOR_TESTING_ONLY for an upper-case constant). Nothing checks that only tests and benchmarks import it. docs/development/DEVELOPMENT.md, § Offering test-only code to other packages, holds the rest.

• Import grouping and collation. Every specifier naming the same package

sits in one contiguous run. Nothing sorts imports here.

• Word choice. American spelling, and one word per concept — this reaches

comments, error and log messages, and test descriptions as much as it reaches documents. § Word choice holds the list.

• What a comment is for. A doc comment states the contract; mechanics go in

//. A comment that litigates what the code does _not_ do, or narrates how it got here, is a comment to cut.

• Layer direction. Imports run down the pace layers in AGENTS.md. Only

mutual cycles are gated, so an existing upward import is not a precedent.

Before you push

deno fmt --check, deno lint, deno task check, and the deno task test of every package you touched. Each misses what the others catch, and none of them runs the separate gates listed under § Automated gates — check-docs among them, which is why a TypeScript block in a document can break on a change that never opened one.

Patterns are the exception deno task check does not own: deno task cfcheck is the authoritative pattern type-check.

When you think you are done

skills/cf-review/SKILL.md is the house reviewer, and self-review before pushing is one of the things it is for. It holds code to the documents above — so if it finds something here that this skill never pointed you at, that gap is itself worth reporting.