Skip to content

Commit 98a84fc

Browse files
owainlewisowainlewis
authored
docs: add repository standards doc (#54)
Define what healthy means for this repo: required standards for license, docs-match-code, and related checks that agents should use when reviewing the repo, opening issues, and preparing PRs.
1 parent db76845 commit 98a84fc

1 file changed

Lines changed: 158 additions & 0 deletions

File tree

‎STANDARDS.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Cortex Standards
2+
3+
These standards define what healthy means for this repository.
4+
Factory and other agents should use this file when reviewing the repo, opening issues, and preparing PRs.
5+
6+
## Required Standards
7+
8+
### License
9+
10+
- The repo must have a `LICENSE` file.
11+
- The license must be MIT unless the owner explicitly changes it.
12+
- `Cargo.toml` and `README.md` must name the same license.
13+
14+
Factory may open a PR to add a missing MIT license file when the repo clearly says MIT elsewhere.
15+
Factory must stop and ask if the intended license is unclear or if the work would change the license.
16+
17+
### Docs Match Code
18+
19+
- `README.md` must describe behavior that exists in the current code or in shipped releases.
20+
- `docs/prd.md` must describe product intent, not claim that planned features have shipped.
21+
- `docs/roadmap.md` must match GitHub issue state for planned and completed work.
22+
- Release docs must be based on merged PRs, commits, tags, and linked issues.
23+
- Keybindings, slash commands, install commands, and known limitations must match the code.
24+
25+
Factory may open PRs for small doc corrections.
26+
Factory must open an issue instead of changing docs when the product decision is unclear.
27+
28+
### GitHub Project
29+
30+
- Active milestone work must have a GitHub Project.
31+
- Issues selected for active milestone work must be present on that project.
32+
- Project status must reflect real work state.
33+
- Done means the linked PR or direct commit is merged.
34+
- In Progress means active implementation, review, checks, or blocked work after start.
35+
- Todo means planned work that has not started.
36+
37+
Factory may add missing issue links to the project when GitHub permissions allow.
38+
Factory must not create or rename project fields without human approval.
39+
40+
### GitHub Issues And Labels
41+
42+
Every open issue must have at least one type label:
43+
44+
- `bug`: broken behavior.
45+
- `documentation`: docs are missing, stale, or wrong.
46+
- `enhancement`: user-visible feature work.
47+
- `quality`: tests, performance, refactors, CI, or internal code health.
48+
49+
Factory-specific labels:
50+
51+
- `factory-ready`: an agent may work this issue without more product input.
52+
- `factory-triage`: the issue needs clarification, acceptance criteria, or scope shaping.
53+
- `factory-needs-human`: the issue needs a human decision before implementation.
54+
- `factory-blocked`: the issue cannot move until a named blocker is resolved.
55+
56+
An issue may have `factory-ready` only when all of these are true:
57+
58+
- The expected behavior is clear.
59+
- The acceptance criteria are clear.
60+
- The work is small enough for one focused PR.
61+
- The issue does not require a human review item listed below.
62+
- The issue has no known blocker.
63+
64+
Use `factory-needs-human` for:
65+
66+
- product direction changes
67+
- license changes
68+
- release decisions
69+
- public claims
70+
- pricing or business decisions
71+
- deleting features
72+
- broad dependency or architecture choices
73+
- unclear editor behavior or keybinding decisions
74+
75+
Factory may add missing labels when the right label is clear.
76+
Factory must comment and stop when the label choice depends on judgment.
77+
78+
### Tests
79+
80+
- Behavior changes must include focused tests when the behavior can be tested without brittle terminal mocks.
81+
- Pure editor logic must have unit tests.
82+
- File behavior must test save, load, missing file, and error paths when touched.
83+
- Keybinding and command dispatch changes must test the changed binding or command.
84+
- Terminal-facing changes must include manual smoke evidence when automated tests are not enough.
85+
86+
Required local checks:
87+
88+
```sh
89+
cargo fmt --check
90+
cargo clippy -- -D warnings
91+
cargo test
92+
```
93+
94+
Factory must run the relevant checks before opening a PR.
95+
Factory must explain any check it could not run.
96+
97+
### CI
98+
99+
- CI must run on pull requests.
100+
- CI must run on pushes to `main`.
101+
- CI must run formatting, clippy, tests, and a release build.
102+
- CI must use the stable Rust toolchain unless the repo explicitly changes toolchains.
103+
- CI must not require secrets for normal pull request checks.
104+
105+
Factory may open PRs for small CI fixes.
106+
Factory must stop and ask before changing release, signing, publishing, or secret-related workflows.
107+
108+
### Agent Instructions
109+
110+
- `AGENTS.md` must exist.
111+
- Agent instructions must say Cortex is macOS-only.
112+
- Agent instructions must require small scoped changes.
113+
- Agent instructions must require docs to stay aligned with `docs/prd.md` and `docs/roadmap.md`.
114+
- Agent instructions must block broad product changes without human review.
115+
116+
Factory may open PRs for small instruction fixes.
117+
Factory must not weaken safety rules.
118+
119+
## Recommended Standards
120+
121+
- `CONTRIBUTING.md` explains local setup, checks, issue flow, and PR expectations.
122+
- `SECURITY.md` explains how to report security issues.
123+
- Open issues link to roadmap phases when they are roadmap work.
124+
- Non-trivial issues have a plan under `docs/issues/<issue-number>-plan.md`.
125+
- Performance-sensitive work includes a benchmark, smoke check, or clear manual test.
126+
127+
Factory may open issues for missing recommended standards.
128+
Factory should not block normal work on recommended standards.
129+
130+
## Human Review Required
131+
132+
Human review is required before:
133+
134+
- merging PRs
135+
- cutting releases
136+
- changing the license
137+
- changing product direction
138+
- changing editor behavior that is not clearly requested by an issue
139+
- changing keybindings that are not clearly requested by an issue
140+
- adding large dependencies
141+
- deleting features
142+
- making public claims
143+
- changing safety rules
144+
145+
Factory must stop and ask when work touches these areas and the issue does not already give clear approval.
146+
147+
## Factory Review Rule
148+
149+
When Factory reviews this repo against these standards, it should classify each failed standard as one of:
150+
151+
- `fix`: open the smallest safe PR.
152+
- `issue`: open or update a focused issue.
153+
- `blocked`: report the missing human decision or permission.
154+
155+
Factory should prefer PRs for mechanical fixes.
156+
Factory should prefer issues for judgment calls.
157+
Factory must not merge.
158+
Factory must not push to `main`.

0 commit comments

Comments
 (0)