From 28bf869572f5da9cb7dffc7bbb16751c476fb2e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kay=20Sch=C3=A4fer?= Date: Fri, 18 Sep 2026 15:13:43 +0200 Subject: [PATCH] docs: audit cleanup (dedup rules, add SECURITY/DECISIONS/PR template) - resolve REST canonical ownership: skill = wire format, backend/api.md = API topic - dedup rule copies: security checklist, video scrubbing, session docs, escalation gates - add SECURITY.md, DECISIONS.md, .github/PULL_REQUEST_TEMPLATE.md, skills/README.md - README: reuse/license note, budget wording, PRD route; lessons date format; MANIFEST heading/ownership --- .github/PULL_REQUEST_TEMPLATE.md | 27 +++++++++++++++++++++++++ AGENTS.md | 1 + CHANGELOG.md | 19 ++++++++++++++++++ DECISIONS.md | 14 +++++++++++++ MANIFEST.md | 10 ++++++++-- README.md | 18 +++++++++++------ SECURITY.md | 25 +++++++++++++++++++++++ backend/api.md | 34 ++------------------------------ checklists/session.md | 7 +------ core/context-budget.md | 1 + core/docs-system.md | 2 +- core/workflow.md | 4 ++-- frontend/scroll-motion.md | 5 +---- legal/legal-maintenance.md | 2 +- lessons/README.md | 2 +- security/web-api.md | 9 +-------- skills/README.md | 18 +++++++++++++++++ skills/rest-guidelines/SKILL.md | 2 +- 18 files changed, 136 insertions(+), 64 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 DECISIONS.md create mode 100644 SECURITY.md create mode 100644 skills/README.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..f87d05d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,27 @@ +## What + + + +## Why + + + +## How to verify + + + +## Risk / blast radius + +- Shared files/symbols touched: +- Do-not-touch list: + +## Checklist + +- [ ] One purpose; fix ≠ feature; refactor separate ([core/git.md](../core/git.md)). +- [ ] Local gates run: lint, types, tests, build ([core/workflow.md](../core/workflow.md)). +- [ ] No secrets, no debug code, no unrelated files. +- [ ] Tests added/updated; deny tests for new guarded surfaces (401/403). +- [ ] Docs updated (list paths) **or** explicit "unchanged because …". +- [ ] `CHANGELOG` entry under `[Unreleased]` if user-visible/API/security. +- [ ] Legal trigger table walked if processing/PII/tools changed. +- [ ] Regression matrix walked for risky changes ([core/regression.md](../core/regression.md)). diff --git a/AGENTS.md b/AGENTS.md index 1edbc42..cb3744d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,7 @@ This file is a **router**, not an encyclopedia. Read only the files the current | --- | --- | | Any session | [core/workflow.md](core/workflow.md), [core/context-budget.md](core/context-budget.md) | | New feature / route | [core/architecture.md](core/architecture.md), [templates/feature-spec.md](templates/feature-spec.md), [testing/strategy.md](testing/strategy.md) | +| Product definition / PRD | [templates/PRD.md](templates/PRD.md) | | Refactor / bugfix | [core/regression.md](core/regression.md), [core/clean-code.md](core/clean-code.md) | | UI implementation | [skills/frontend-ui/SKILL.md](skills/frontend-ui/SKILL.md), [frontend/ui.md](frontend/ui.md), [frontend/ux.md](frontend/ux.md), [frontend/components.md](frontend/components.md) | | Design tokens / themes | [frontend/design.md](frontend/design.md) | diff --git a/CHANGELOG.md b/CHANGELOG.md index dff20e6..27a401b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,25 @@ All notable changes to this collection are documented here. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/). +## [Unreleased] + +### Added + +- `SECURITY.md` (root) — vulnerability reporting + pointer to `security/`. +- `DECISIONS.md` (root) — canonical decision log (referenced by `core/docs-system.md`, `legal/legal-maintenance.md`). +- `.github/PULL_REQUEST_TEMPLATE.md` — mirrors `checklists/pr.md`. +- `skills/README.md` — skill index. +- Subfolder-README rule in `core/context-budget.md`. + +### Changed + +- REST ownership resolved: `skills/rest-guidelines/SKILL.md` owns the wire format; `backend/api.md` owns the API topic. Duplicated tables removed from `backend/api.md`. +- Deduplicated rule copies: security review checklist (`security/web-api.md` → skill), video scrubbing (`frontend/scroll-motion.md` → skill), session docs (`checklists/session.md` → `core/docs-system.md`), escalation gates (`core/workflow.md` → AGENTS/security). +- Lessons date format documented as `YYYY-MM` (matches existing rows). +- `README.md`: reuse/license note added; copy/submodule guidance softened; budget wording clarified. +- `AGENTS.md` routing now reaches `templates/PRD.md`. +- `MANIFEST.md` heading `tooling` → `Tooling`; ownership map split for API topic vs REST wire format. + ## [1.0.0] - 2026-09-17 ### Added diff --git a/DECISIONS.md b/DECISIONS.md new file mode 100644 index 0000000..a5bdae8 --- /dev/null +++ b/DECISIONS.md @@ -0,0 +1,14 @@ +# Decision Log + +Dated one-liners for rule and structure decisions of this collection, including +"checked, unchanged" outcomes. Append-only; supersede, never rewrite. + +Format: `YYYY-MM-DD: — `. + +## 2026-09-18 + +- REST wire format is canonical in `skills/rest-guidelines/SKILL.md`; `backend/api.md` owns the API topic (auth, validation, endpoint DoD). Reason: remove dual ownership flagged in the audit. +- No license granted for this collection; `README.md` states that reuse requires permission. Reason: proprietary decision by the maintainer. +- Added root `SECURITY.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `DECISIONS.md`, `skills/README.md`. Reason: close hygiene gaps (no reporting path, no PR template, no decision-log home, no skill index). +- Lessons keep `YYYY-MM` date granularity; `lessons/README.md` format was corrected to match the rows. Reason: docs must match the data. +- `lessons/*` rows stay even when the rule is promoted into a topic file. Reason: lessons are the append-only origin; topic files are canonical ([lessons/README.md](lessons/README.md)). diff --git a/MANIFEST.md b/MANIFEST.md index 8326d45..050866c 100644 --- a/MANIFEST.md +++ b/MANIFEST.md @@ -11,12 +11,14 @@ Maintainer index — read when adding, renaming, or auditing files, **not** at s | [README.md](README.md) | Human onboarding, adoption, customization, limits | Adopting the collection | | [MANIFEST.md](MANIFEST.md) | This index | Adding, renaming, auditing files | | [CHANGELOG.md](CHANGELOG.md) | Release history of the collection | Updating the collection | +| [DECISIONS.md](DECISIONS.md) | Decision log (rule/structure decisions, "unchanged" checks) | Rule lifecycle, audits | +| [SECURITY.md](SECURITY.md) | Vulnerability reporting + scope for this collection | Reporting a security issue | | [CLAUDE.md](CLAUDE.md) | Pointer `@AGENTS.md` for Claude Code | Tool reads it automatically | | [GEMINI.md](GEMINI.md) | Pointer `@AGENTS.md` for Gemini CLI | Tool reads it automatically | | [.github/copilot-instructions.md](.github/copilot-instructions.md) | Pointer for GitHub Copilot | Tool reads it automatically | | [opencode.json](opencode.json) | Tool permissions (allow/deny/ask), subagent roles | OpenCode setup | -## tooling +## Tooling | Path | Purpose | Read when | | --- | --- | --- | @@ -24,6 +26,7 @@ Maintainer index — read when adding, renaming, or auditing files, **not** at s | [scripts/install-skills.mjs](scripts/install-skills.mjs) | Copies `skills/` into `.agents/skills/` and `.claude/skills/` | Adopting skills into a project | | [examples/hooks/README.md](examples/hooks/README.md) | Deterministic gate hook examples (Claude Code) | Setting up enforcement | | [.github/workflows/docs-check.yml](.github/workflows/docs-check.yml) | CI job running the docs check on push/PR | CI changes | +| [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md) | PR description + checklist | Opening a PR | ## Rule ownership — canonical file per topic @@ -39,9 +42,11 @@ Maintainer index — read when adding, renaming, or auditing files, **not** at s | Consent, Impressum, BFSG | `legal/compliance-de.md` | | Overlays, scroll ownership | `frontend/scroll-motion.md` | | Accessibility baseline | `frontend/accessibility.md` | -| API contracts | `backend/api.md` (+ `skills/rest-guidelines/`) | +| API topic (auth, validation, endpoint DoD) | `backend/api.md` | +| REST wire format (paths, JSON, methods, status, errors, pagination) | `skills/rest-guidelines/SKILL.md` | | Release ritual | `checklists/release.md` | | Rule lifecycle (add/delete) | `core/context-budget.md` | +| Decision log | `DECISIONS.md` | ## core/ — process & engineering @@ -138,6 +143,7 @@ Maintainer index — read when adding, renaming, or auditing files, **not** at s | Path | Purpose | Read when | | --- | --- | --- | +| [skills/README.md](skills/README.md) | Skill index | Choosing a skill | | [skills/plan-first/SKILL.md](skills/plan-first/SKILL.md) | Plan before code | Any non-trivial task | | [skills/tdd-extraction/SKILL.md](skills/tdd-extraction/SKILL.md) | Derive failing test first | Bugs, features | | [skills/rest-guidelines/SKILL.md](skills/rest-guidelines/SKILL.md) | REST subset, OpenAPI duty | API design | diff --git a/README.md b/README.md index b03e61d..2a6c949 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ Canonical repository: https://github.com/Neuroklast/agent-documents git clone https://github.com/Neuroklast/agent-documents.git ``` +Reading/evaluating is unrestricted; copying or submoduling into another project requires permission — see [License / reuse](#license--reuse). Once permitted: + Use in a target project (copy): ```powershell @@ -40,7 +42,7 @@ Then point the target repo's root `AGENTS.md` at `docs/agent-docs/AGENTS.md` and 4. Delete unused stack adapters and skills — the router must only point at files that exist. 5. Optionally copy `opencode.json` and adjust permissions; copy `CLAUDE.md` / `GEMINI.md` / `.github/copilot-instructions.md` for tool compatibility. 6. Add a short **Project facts** block to `AGENTS.md`: stack, package manager, check commands, deploy target. Never invent these — read the manifests. -7. Install skills where your tools discover them: `node scripts/install-skills.mjs ` (copies into `.agents/skills/` and `.claude/skills/`). opencode and Codex read `.agents/skills/`; Claude Code reads `.claude/skills/`. +7. Install skills where your tools discover them: `node scripts/install-skills.mjs ` (copies into `.agents/skills/` and `.claude/skills/`). opencode reads `.agents/skills/`; Claude Code reads `.claude/skills/` — verify the path for other tools. 8. Optional: copy `examples/hooks/` and wire them into `.claude/settings.json` for deterministic gates. ## Monorepos @@ -56,8 +58,8 @@ commands, package layout, and what differs from the root. AGENTS.md Router: hard rules, routing table README.md This file MANIFEST.md Maintainer index (not read at session start) -CHANGELOG.md Release history of the collection -CLAUDE.md / GEMINI.md / .github/copilot-instructions.md Pointers +CHANGELOG.md / DECISIONS.md / SECURITY.md History, decision log, security policy +CLAUDE.md / GEMINI.md / .github/* Tool pointers + PR template opencode.json Tool permissions (OpenCode) core/ Workflow, context budget, git, clean code, quality, architecture, regression, docs frontend/ UI, UX, design, components, accessibility, scroll/motion, performance @@ -68,7 +70,7 @@ testing/ Strategy, unit, e2e, contracts/CI checklists/ Session, PR, release, launch lessons/ Distilled hard-won lessons by area roles/ Subagent role contracts (architect, reviewer, tester, …) -skills/ Task-specific skills (SKILL.md per folder, Agent Skills spec) +skills/ Task-specific skills (SKILL.md per folder; index in skills/README.md) templates/ PRD, ADR, feature spec, deviation record stack/ Next.js, Supabase, R2, TypeScript, C++/JUCE scripts/ check-docs.mjs, install-skills.mjs @@ -78,7 +80,7 @@ examples/hooks/ Deterministic gate hook examples ## Principles - **MUST / NEVER / ALWAYS** phrasing. Bullets, not prose. -- Every topic file ≤ 150 lines, every skill ≤ 100 lines. If a topic grows, split by concern and register it in `MANIFEST.md`. +- Every markdown file except `AGENTS.md`/`MANIFEST.md` ≤ 150 lines; every skill ≤ 100 lines. If a topic grows, split by concern and register it in `MANIFEST.md`. - `MANIFEST.md` is a maintainer index; sessions read the `AGENTS.md` routing table only. - Facts over templates: no invented operator data, no invented APIs, no invented version numbers. - Structural gates (CI scripts, contract tests, hooks) beat prose bans. Markdown is the contract; enforcement lives in tooling. @@ -89,7 +91,7 @@ examples/hooks/ Deterministic gate hook examples node scripts/check-docs.mjs ``` -Checks line budgets (AGENTS.md ≤ 120, MANIFEST ≤ 200, topic ≤ 150, skill ≤ 100), skill frontmatter +Checks line budgets (AGENTS.md ≤ 120, MANIFEST ≤ 200, every other markdown file ≤ 150, skill ≤ 100), skill frontmatter (name/description per the Agent Skills spec), relative links, MANIFEST coverage, and prints a token estimate per file. CI runs it on every push and PR ([.github/workflows/docs-check.yml](.github/workflows/docs-check.yml)). @@ -141,3 +143,7 @@ Git protected main, required checks, no force-push - Update the matching topic file whenever a convention changes; new topic → new file + `MANIFEST.md` entry. - Keep `AGENTS.md` ≤ 120 lines. It is a router, not documentation. - Archive superseded docs with a banner instead of deleting history ([core/docs-system.md](core/docs-system.md)). + +## License / reuse + +No license is granted — all rights reserved. Copying, submoduling, or redistributing into another project requires permission from the maintainer; open an issue to ask. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..9ad0fef --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,25 @@ +# Security Policy + +This repository is a portable governance collection (markdown). It ships no +runtime code and no deployed service. The agent-facing security contracts live +in [`security/`](security/security.md). + +## Reporting a vulnerability + +- Report privately via GitHub Security Advisories ("Report a vulnerability" on + the repository). Do not open a public issue. +- Include: affected file/path, impact, reproduction, suggested fix. +- We acknowledge within ~72 h and do not disclose details before a fix ships. + +## Scope + +- A wrong or unsafe rule is treated like a bug: open an issue with the affected + file and a concrete correction. +- If a secret was committed: report privately; rotation happens before any + history cleanup (human approval required). + +## Baseline + +- [security/security.md](security/security.md) — secrets, least privilege, hardening, residual risk. +- [security/web-api.md](security/web-api.md) — XSS, CSRF, SSRF, headers, uploads, rate limits. +- [security/owasp-llm.md](security/owasp-llm.md) — OWASP LLM Top 10 agent rules. diff --git a/backend/api.md b/backend/api.md index 6f36e81..64ea651 100644 --- a/backend/api.md +++ b/backend/api.md @@ -2,39 +2,9 @@ Load for: any API endpoint or spec. Mandatory skill: [../skills/rest-guidelines/SKILL.md](../skills/rest-guidelines/SKILL.md). -## Resource design +## REST wire format -- Paths: kebab-case, plural nouns, no verbs: `/api/v1/invoice-line-items`. -- IDs are opaque strings (UUIDs), never sequential integers in public APIs. -- snake_case JSON properties; plural names for arrays; `_at` for timestamps, `_date` for dates. -- NEVER trailing slashes. NEVER RPC-style verbs (`/getUser`) unless the action is genuinely a process (`/imports`). -- Additive-only changes within a version; breaking changes → new version. - -## Methods & status codes - -| Method | Semantics | -| --- | --- | -| GET | Safe, idempotent, cacheable where appropriate | -| POST | Create; idempotency key for retryable creates | -| PUT | Full replace | -| PATCH | Partial merge | -| DELETE | Idempotent removal | - -- 200 OK, 201 Created + `Location`, 202 Accepted (async), 204 No Content. -- 400 validation, 401 unauthenticated, 403 unauthorized, 404 missing, 409 conflict, 422 semantic rejection, 429 rate limited (with retry info), 500 server error. -- NEVER 200 with an error body. - -## Errors - -- `application/problem+json`: `type`, `title`, `status`, `detail`, `instance`. -- NEVER stack traces, SQL, or internal identifiers in responses. -- Validation errors: field-level detail, stable machine-readable codes. - -## Pagination & filtering - -- Cursor pagination default; opaque `next_cursor`; default page size ~50, max ~200. -- Offset pagination only where the repo already does it. -- Filters as query params (snake_case); never unbounded result sets. +Paths, JSON shape, methods, status codes, problem+json errors, pagination, and versioning are canonical in [../skills/rest-guidelines/SKILL.md](../skills/rest-guidelines/SKILL.md). Do not restate or fork them here. ## Auth & limits diff --git a/checklists/session.md b/checklists/session.md index ad6d7ee..7f04d54 100644 --- a/checklists/session.md +++ b/checklists/session.md @@ -20,12 +20,7 @@ Definition of Done: [../core/quality.md](../core/quality.md). ## 3. Docs -- [ ] Matching topic/feature docs updated. -- [ ] `CHANGELOG` entry under `[Unreleased]` (behavior/API/security changes). -- [ ] QA checklist updated for new/changed testable flows. -- [ ] Lessons appended if an incident/pitfall occurred. -- [ ] Legal trigger table walked (if processing/PII/tools changed) ([../legal/legal-maintenance.md](../legal/legal-maintenance.md)). -- [ ] Or explicit: `Docs: unchanged because `. +Walk the maintenance matrix in [../core/docs-system.md](../core/docs-system.md) and the legal trigger table ([../legal/legal-maintenance.md](../legal/legal-maintenance.md)); update each affected doc or record `Docs: unchanged because `. ## 4. Git diff --git a/core/context-budget.md b/core/context-budget.md index 6115d33..574257b 100644 --- a/core/context-budget.md +++ b/core/context-budget.md @@ -16,6 +16,7 @@ MANIFEST.md is a maintainer index and is not part of the session read chain. - NEVER read whole docs trees "to be safe". That burns context and hides the relevant rule. - When a task spans areas, read at most 2–3 topic files plus the files those topics or the invoked skill name directly. - Load skills only when their description matches the task. +- Subfolders get a `README.md` only when they hold a non-rule index (e.g. `lessons/`, `roles/`, `skills/`). Pure topic folders rely on `AGENTS.md` routing + `MANIFEST.md`. ## File size budgets diff --git a/core/docs-system.md b/core/docs-system.md index a075990..61db8e6 100644 --- a/core/docs-system.md +++ b/core/docs-system.md @@ -37,7 +37,7 @@ Load for: every session end, when behavior or conventions change. ## Decision log - When a legal/compliance/architecture check happened but nothing changed, record a dated one-liner: `YYYY-MM-DD: checked , unchanged because `. -- The log lives next to the affected docs (e.g. in the legal maintenance file or the ADR list). +- For this collection the log is [../DECISIONS.md](../DECISIONS.md); in a target project keep it next to the affected docs (e.g. legal maintenance file or the ADR list). ## Archive policy diff --git a/core/workflow.md b/core/workflow.md index 1255e0c..b42d06a 100644 --- a/core/workflow.md +++ b/core/workflow.md @@ -45,8 +45,8 @@ Load for: every session. ## Escalation — stop and ask the human -- Production deploy, destructive DB migration, data backfill. -- `rm -rf`, force-push, history rewrite, secret rotation. +Approval gates for deploys, destructive migrations, data backfills, `rm -rf`, history rewrite, force-push, and secret rotation are canonical in [AGENTS.md](../AGENTS.md) §Hard rules and [../security/security.md](../security/security.md) §Least privilege. Additionally stop and ask for: + - Deviation from a safety rule (e.g. realtime/MISRA, see [../skills/c-realtime/SKILL.md](../skills/c-realtime/SKILL.md)). - Legal text wording, operator data, pricing/contract terms. diff --git a/frontend/scroll-motion.md b/frontend/scroll-motion.md index 6595397..e878b6d 100644 --- a/frontend/scroll-motion.md +++ b/frontend/scroll-motion.md @@ -46,10 +46,7 @@ Load for: scroll behavior, overlays, carousels, video scrubbing, z-index. ## Video scrubbing -- NEVER drive `HTMLVideoElement.currentTime` in a scroll handler on the main thread as the default — it stalls mobile. -- Preferred: pre-rendered frame sequence on canvas, or WebCodecs + canvas with a scroll timeline. -- ALWAYS reduced-motion fallback: static poster/first frame. -- See [../skills/video-scrubbing/SKILL.md](../skills/video-scrubbing/SKILL.md) before implementing. +Scroll-bound video is implemented per [../skills/video-scrubbing/SKILL.md](../skills/video-scrubbing/SKILL.md) (frame-sequence/WebCodecs canvas, reduced-motion poster, mobile memory budget). Do not drive `HTMLVideoElement.currentTime` from a scroll handler by default. ## Multi-column builders diff --git a/legal/legal-maintenance.md b/legal/legal-maintenance.md index a2fde57..189511a 100644 --- a/legal/legal-maintenance.md +++ b/legal/legal-maintenance.md @@ -43,7 +43,7 @@ If a change triggers nothing: record it explicitly — `YYYY-MM-DD: checked `. diff --git a/skills/rest-guidelines/SKILL.md b/skills/rest-guidelines/SKILL.md index 9b6ad1e..0fd6a9e 100644 --- a/skills/rest-guidelines/SKILL.md +++ b/skills/rest-guidelines/SKILL.md @@ -5,7 +5,7 @@ description: REST API design rules (Zalando-style subset) for any endpoint. Use # Skill — REST Guidelines -Self-contained subset of the Zalando RESTful API Guidelines. Authoritative for this collection. +Self-contained subset of the Zalando RESTful API Guidelines. Canonical for the REST wire format (paths, JSON, methods, status codes, errors, pagination, versioning). The API topic owner (auth, validation, endpoint DoD) is [../../backend/api.md](../../backend/api.md). ## Resource naming