8000 docs: specs live in the repo, one folder per ticket by simon-inkie · Pull Request #149 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

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
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,11 @@ For setting up a machine and running the checks, see [README.md](README.md)

## House rules for agents

- Specs live in the repo. Every ticket (GitHub issue) gets a folder
`.specs/<issue-number>-<slug>/` holding its SPEC.md, ISSUE-TEXT.md if used,
and any design notes, in the same pull request as the code. Never keep a spec
only in a chat, a ticket comment or a wiki. See
[DEVELOPMENT.md](DEVELOPMENT.md) section 2.
- No internal material (names, hosts, paths, ticket ids, addresses) may enter
the repository. `pnpm check:leaks` enforces it; read the rule comments before
extending the denylist.
Expand Down
5 changes: 5 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,10 @@ This file is a pointer. The repository's contributing rules are in
same files every other coding-agent runtime reads, so there is exactly one copy
of the rules and no chance of drift.

**Specs live in the repo.** Every ticket (GitHub issue) gets a folder
`.specs/<issue-number>-<slug>/` holding its SPEC.md and any design notes, in the
same pull request as the code. Never keep a spec only in a chat, a ticket
comment or a wiki. Detail: [DEVELOPMENT.md](DEVELOPMENT.md) section 2.

The one thing worth repeating here, so a session that reads only this file is
not blind: sign off every commit (`git commit -s`).
4 changes: 4 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,10 @@ pnpm -C packages/deck check:dashes
number, for example `39-contributor-workflow`.
- Start from an issue. Non-trivial work keeps a SPEC at
`.specs/<issue>-<slug>/SPEC.md`, updated in the same commits as the code.
Specs live in the repo: every ticket gets a `.specs/<issue>-<slug>/` folder
that travels in the same pull request, and a spec is never kept only in a
chat, a ticket comment or a wiki. See
[DEVELOPMENT.md](DEVELOPMENT.md) section 2.
- Keep each PR to one change. Unrelated changes go in separate PRs.
- Commit titles follow `type(scope): summary (#issue)`, for example
`fix(base): anchor stuck-pane literals to the start of a rendered line (#20)`.
Expand Down
5 changes: 5 additions & 0 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,11 @@ using the branch name as the folder name. Anything else the work needs
folder is committed and merged with the code; it is the permanent record of
why the change looks the way it does.

Before an issue number exists the folder is `.specs/<slug>/`. The moment the
issue is created, rename it with `git mv` and record the number in the SPEC
header. A spec is never kept only outside the repository (in a chat, a ticket
comment or a wiki), and external maintainers follow the same rule.

A starting SPEC can be ten lines. Use this skeleton:

```markdown
Expand Down
Loading
0