🤖 (agents): Add AGENTS.md docs-sync policy with CLAUDE.md import
Changes
2 files changed, +57 -0
ADD
AGENTS.md
+56 -0
@@ -0,0 +1,56 @@
1
+# Agent instructions for git-shark
2
+
3
+git-shark is a self-hosted Git platform: a single Quarkus service (Java 21,
4
+Panache Next, Qute server-rendered UI, PostgreSQL, Flyway) serving bare git
5
+repositories over smart HTTP and SSH, with OIDC login and opt-in ForgeFed
6
+federation. Source layout: `src/main/java/de/workaround/`, templates in
7
+`src/main/resources/templates/`, migrations in
8
+`src/main/resources/db/migration/`, docs in `docs/`.
9
+
10
+## Keep the docs in sync
11
+
12
+`docs/` is organized by audience. **Whenever you implement, change, or remove a
13
+feature, update the matching docs in the same commit or PR** — do not leave doc
14
+updates for later.
15
+
16
+| You changed… | Update |
17
+|---|---|
18
+| Anything a logged-in user sees or does (UI pages, workflows, error messages, handles/URL forms) | `docs/users/` |
19
+| Configuration properties, environment variables, exposed endpoints, deployment/proxy requirements, DB tables, operational behavior (queues, retries, monitoring) | `docs/admins/` — including the configuration-reference table in `admins/getting-started.md` when adding or changing a `GITSHARK_*`/config property |
20
+| Architecture, implementation decisions, protocol behavior, or the capability set of a subsystem | `docs/maintainers/` |
21
+| The overall feature set | The feature list in the root `README.md` |
22
+
23
+Checklist per doc change:
24
+
25
+- **New doc file** → add it to the index in `docs/README.md` under the right
26
+ audience section, and link it from related docs.
27
+- **Moved/renamed doc** → `grep -rn` the whole repo for the old path (root
28
+ `README.md` links into `docs/`) and fix every reference.
29
+- **Numbers and behavior claims** (defaults, limits, intervals, endpoint paths,
30
+ table names) must match the source — verify against the code, don't copy
31
+ from an older doc.
32
+
33
+### Federation specifics
34
+
35
+The federation subsystem has one doc per audience; a federation change usually
36
+touches more than one:
37
+
38
+- `docs/users/federation.md` — what users can do (follow/unfollow, feeds,
39
+ identity, error messages).
40
+- `docs/admins/federation.md` — config vars, allowlist semantics, exposed
41
+ endpoints, reverse-proxy rules, delivery-queue operations, table inventory,
42
+ troubleshooting.
43
+- `docs/maintainers/forgefed.md` — component map, data flows, implementation
44
+ decisions with rationale, and the **"What works today" / "What still needs
45
+ to be implemented" lists: when you implement something from the gap list,
46
+ move it to the works list; when you add a new capability or discover a new
47
+ gap, record it.** New load-bearing design decisions belong in the decisions
48
+ section with their why.
49
+
50
+## Conventions
51
+
52
+- Commit messages: `<gitmoji> (<context>): <message>`, e.g.
53
+ `📝 (docs): Update federation user guide`.
54
+- Never add functionality without a failing test first; the test must be green
55
+ after the implementation. Docs-only changes need no tests.
56
+- Code style: tabs, Allman braces; match the surrounding code.
ADD
CLAUDE.md
+1 -0
@@ -0,0 +1 @@
1
+@AGENTS.md