Spec Writing

Trellis specs are coding guidance for future agents. They should explain how to work in this repository, not how a generic project might be organized.

Write From Evidence

Each important rule should be backed by one of these:

A source file that demonstrates the preferred pattern.
A test file that shows expected behavior.
A project document that defines the convention.
A repeated pattern across multiple files.

Use short snippets only when they make the rule clearer. Prefer linking to the file path and naming the symbol or behavior.

File Structure

Keep the spec tree aligned with the project:

Keep index.md as the navigation file for the spec directory.
Split topics when developers would look for them independently.
Merge topics when separate files would repeat the same rule.
Delete template files that do not apply.
Add new files for important local patterns the template missed.

Content Standards

Good spec sections include:

When the rule applies.
The local pattern to follow.
The source or test files that prove the pattern.
Common mistakes or anti-patterns.
Verification commands or checks when they are specific and reliable.

Avoid:

Placeholder prose.
Generic framework advice.
Tool instructions that only work in one agent host.
Long copied code blocks.
Rules based on a single accidental implementation detail.

Example Shape

## Command Handlers

Command handlers should keep argument parsing, validation, and side effects separate. The local pattern is:

- Parse CLI flags at the command boundary.
- Convert raw inputs into typed task options before invoking core logic.
- Keep filesystem writes in the command or service layer, not in template helpers.

Reference files:
- `packages/cli/src/commands/example.ts`
- `packages/cli/test/commands/example.test.ts`

Avoid passing raw `process.argv` or unvalidated config objects into shared helpers.

Final Pass

Before finishing:

grep -R "To be filled\\|TODO: fill\\|placeholder" .trellis/spec

Also check links, index files, and whether any spec still describes a template rather than this repository.

2.1 KiB Raw Blame History