.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Design docs
+    url: https://git.produktor.io/eSlider/swarm-house/src/branch/main/docs/12-design-journey.md
+    about: Start with the design journey, then open an issue here.
+  - name: Open questions
+    url: https://git.produktor.io/eSlider/swarm-house/src/branch/main/docs/09-open-questions.md
+    about: Known unknowns — check before duplicating.

.github/ISSUE_TEMPLATE/default.md

@@ -0,0 +1,24 @@
+---
+name: Change / task
+about: Default issue template — caveman style
+title: ""
+labels: []
+---
+
+Write **caveman-full**: short lines, fragments OK, no filler. See [`CONTRIBUTING.md`](../../CONTRIBUTING.md#caveman-style-default).
+
+## What
+
+<!-- One line. What need fix or build. -->
+
+## Why
+
+<!-- Problem or goal. Skip if obvious from title. -->
+
+## Done when
+
+- [ ]
+
+## Notes
+
+<!-- Links, ADR, open question §. Optional. -->

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+Write **caveman-full** by default. See [`CONTRIBUTING.md`](../CONTRIBUTING.md#caveman-style-default).
+
+## What
+
+<!-- What changed. Bullets OK. -->
+
+## Why
+
+<!-- Problem this fixes or design gap closed. -->
+
+## Test
+
+- [ ] `pytest tests/ -q` (if code touched)
+- [ ] `python scripts/check_docs.py` (if docs touched)
+- [ ] ADR added if boundary/contract changed
+
+## Links
+
+<!-- Closes / Relates to #issue. Optional demo URL. -->

AGENTS.md

@@ -24,6 +24,23 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and TDD re
 
 ## Conventions
 
+### Caveman style (default for collaboration)
+
+**Issues, pull requests, and code reviews** use **caveman-full** by default:
+
+- Short sentences or fragments; drop articles and filler when clear
+- Lead with fact, verdict, or ask — not preamble
+- Bullets over paragraphs; one idea per line
+- Keep technical terms, acronyms, paths, and code exact
+- English only; no identifying references (same as all repo prose)
+
+README tiers: root [`README.md`](README.md) = **caveman-lite** (full sentences, less filler);
+component READMEs = **caveman-full**. Design docs in `docs/` stay readable prose unless
+editing for consistency.
+
+Templates: [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/),
+[`.github/pull_request_template.md`](.github/pull_request_template.md).
+
 - Markdown: ATX headings, fenced code blocks with language tags, pipe tables.
 - Python: PEP 8, type hints, pure functions where possible, no unnecessary classes.
 - TypeScript: strict mode, functional components and hooks, no extra UI libraries.

CONTRIBUTING.md

@@ -77,6 +77,41 @@ test: cover broadcast frame roundtrip
 Never include AI tool references, `Co-authored-by` trailers for assistants, or
 identifying names of people, companies, or locations.
 
+## Caveman style (default)
+
+Use **caveman-full** in **issues**, **pull requests**, and **reviews** unless the
+author explicitly asks otherwise.
+
+| Do | Skip |
+| --- | --- |
+| Short lines, fragments OK | Long preamble ("I wanted to start by saying…") |
+| Lead with what / why / verdict | Filler ("just", "basically", "kind of") |
+| Bullets, checklists | Repeated context already in diff or issue |
+| Exact terms, paths, code | Invented abbreviations or vague "the thing" |
+
+**Examples**
+
+| Fluffy | Caveman |
+| --- | --- |
+| I think we should probably consider adding a link checker to CI because links might break. | Add CI link checker. Broken relative links fail merge. |
+| This pull request implements the documentation improvements that were discussed in the audit. | Docs audit: glossary T0–T4, fix ground README link, rsync wording. |
+| LGTM but maybe we could think about whether the anchor format is consistent? | Merge OK. Fix glossary anchors in follow-up (#1). |
+
+README intensity: root = caveman-lite; `simulator/`, `prototype/`, `infra/`, `docs/adr/` READMEs =
+caveman-full. Numbered design docs in `docs/` stay full prose.
+
+Gitea pre-fills [issue](.github/ISSUE_TEMPLATE/default.md) and
+[PR](.github/pull_request_template.md) templates with this style.
+
+### Reviews
+
+Default review voice = caveman-full:
+
+1. **Verdict first** — merge / wait / no, or approve / request changes
+2. **Findings** — bullet per blocker or nit; file + line when useful
+3. **Scope** — say if issue AC met, partial, or out of scope
+4. No essay; link ADR, issue, or doc section instead of restating design
+
 ## Pull request checklist
 
 - [ ] Tests added or updated; `pytest tests/ -q` passes locally

docs/improvement/README.md

@@ -6,6 +6,13 @@ Point-in-time audits and follow-up work for links, terminology, readability, and
 | --- | --- | --- |
 | [2026-07-10 audit](2026-07-10-audit.md) | 2026-07-10 | Full `docs/` + README pass; glossary T0–T4; live demo links |
 
+## Collaboration style
+
+Issues, PRs, and reviews default to **caveman-full** ([`CONTRIBUTING.md`](../../CONTRIBUTING.md#caveman-style-default),
+[`AGENTS.md`](../../AGENTS.md#caveman-style-default-for-collaboration)). Gitea templates live under
+[`.github/ISSUE_TEMPLATE/`](../../.github/ISSUE_TEMPLATE/) and
+[`.github/pull_request_template.md`](../../.github/pull_request_template.md).
+
 ## CI automation
 
 Enforced in Gitea Actions (`docs-verify` job). Rules live in [`scripts/docs_rules.yaml`](../../scripts/docs_rules.yaml); see [ci-rules.md](ci-rules.md).