diff --git a/.claude/skills/plain-writing/LICENSE b/.claude/skills/plain-writing/LICENSE deleted file mode 100644 index 945595d..0000000 --- a/.claude/skills/plain-writing/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 Shreya Shankar - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/.claude/skills/plain-writing/SKILL.md b/.claude/skills/plain-writing/SKILL.md deleted file mode 100644 index 5022d20..0000000 --- a/.claude/skills/plain-writing/SKILL.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -name: plain-writing -description: >- - Writes and edits prose in a plain and boring style: simple everyday words, - complete sentences, no dashes, no jargon, and no analogies. Use when - drafting or revising documents, Notion pages, reports, summaries, READMEs, - emails, slides, commit messages, or PR descriptions, or when the user asks - to simplify, clean up, tighten, reword, or make writing clearer. Use when - the user invokes /plain-writing deslopify or asks to deslopify an agent - response. Do not apply to code, only to the words around it. -license: MIT ---- - -# Plain writing - -The plain writing skill captures how the user wants writing to read: plain, -boring, and easy to understand in one pass. Apply it by default when you write -for them. - -There are four groups of rules: word choice and tone, sentences and paragraphs, -punctuation and formatting, and patterns to avoid. Each rule has a before and -after. After the rules comes the deslopify command. - -## Word choice and tone - -1. **Use simple, everyday words.** Don't pick a fancy synonym when a plain word - works. Also avoid words AI tools overuse, e.g., "delve", "tapestry", - "landscape", "robust", "leverage", and "reach". - Before: We leverage the cache to unlock a more robust query experience. - After: We use the cache to make repeated queries faster. - -2. **No jargon.** Always use human-understandable language, the way two people - talk to each other. Don't invent jargon or shorthand (that is, if a word or - phrase is not in the Merriam Webster dictionary, don't use it). Use - established technical terms only when they are most precise, and briefly - define them when readers may not know them. - Before: The score is a calibrated proxy for whether the property holds. - After: The score estimates how likely the property is to hold. - -3. **No puffery or empty emphasis.** Drop words that add emphasis but no - information, e.g., "really", "real", "matters", "worth", "carries weight", - "boasts", "a testament to", "pivotal", "renowned", and "quietly". State the - actual point, or cut the sentence. - Before: This result matters, and it carries weight for the design. - After: The scores barely moved, so we can skip the model on most documents. - -4. **Use consistent terminology and constrain your vocabulary.** - Before: Upload the document. The file is parsed, and the record is saved. - After: Upload the document. The document is parsed and saved. - -5. **It's ok to use contractions.** They match everyday speech, so use them - freely. - Before: Do not worry, it is not going to overwrite your file. - After: Don't worry, it's not going to overwrite your file. - -6. **Do not invent hyphenated adjectives.** Avoid a phrase you make up by - joining words with a hyphen to sound compact or clever. If you would not find - it in a dictionary, don't use it. A common compound adjective that people - already use is fine, e.g., "well-crafted". - Before: We added a reveal-style colon to the output. - After: We added a colon that shows the schema. - -7. **Keep the writing boring, descriptive, and explanatory.** Do not use a - catchy phrase, slogan, clever label, or wording meant to sound memorable. - This rule applies everywhere; to headings, topic sentences, callouts, - labels, summaries, and ordinary prose. - Before: Legal requirements as a floor. - After: Applicable legal constraints. - Before: # The alignment loop - After: # Iterative refinement using development disagreements - -## Sentences and paragraphs - -8. **Write complete sentences.** Each sentence should have a subject and a - verb. Do not write fragments, and do not stitch unrelated ideas together with - colons or semicolons. But it is ok to join closely related ideas with plain - conjunctions, like "and", "because", or "so". - Before: The agent polls the file and reacts to changes, and the team meets on - Tuesdays. - After: The agent polls the file and reacts to changes. The team meets on - Tuesdays. - -9. **When you present a workflow or sequence, walk through it in order.** Use - "First", "Second", "Third", and give each step its own sentence so the - reader can follow it, or break up steps with semicolons. - Before: The groups the features were sorted into were the authors' own - reading, the example posts were written by hand, and finer detail meant - training extra small models and labeling again. - After: First, the authors sorted the features into groups themselves, based on - their own reading of the outputs. Second, they wrote the example posts by - hand. Third, when they wanted finer detail, they trained another small - model, and they labeled the posts again. - -10. **Organize a paragraph as a topic sentence and then support.** Start each - paragraph or section with a topic sentence that states the main point. Then, - the next sentence should be a supporting example or fact, with an extra - sentence about it if it needs one. Then, introduce more support with a plain - connective like "For example", "Moreover", or "Or". - Before: The parser skips files with no changes. The cache holds the previous - output. Most renders are fast. - After: Most renders are fast. For example, the parser skips files with no - changes, so the server returns early. Moreover, the cache keeps the previous - output, so a repeated render does no work. - -11. **Never write three or more clauses in one sentence, or three or more - example sentences in a row.** In ordinary prose, a sentence may have one or - two related clauses. Do not pack three or more clauses into one prose - sentence. If you need that many points, use a numbered First / Second / Third - sequence under rule 9, or short bullet points when you are writing a - brief. If list points are examples and you want to inline them, introduce - with "e.g.". Also do not give three or more example sentences back to back - to support the same point. - Before: The parser reads the file, the validator checks the fields, and the - writer saves the record. - After: The parser reads the file, and the validator checks the fields. The - writer then saves the record. - -12. **Prefer long, explanatory sentences over short, punchy ones.** In ordinary - prose, write the way people explain things out loud: longer sentences with - commas, and the simplest way to say the point. Do not break one thought into - a stack of short sentences, and don't write catchy short phrases. Short - lines are fine only in labeled briefs, bullets, or a First / Second / Third - sequence, e.g., "To do: validate recall on long queries." - Before: The gate runs on every merge. It blocks regressions. Nobody - bypasses it. - After: The gate runs on every merge, and it blocks changes that fail a - regression case. A regression cannot make it to production, unless someone - deliberately overrides the check. - Before: Search ranking now uses a scored model instead of heuristics. The - change reduced p95 latency from 900 ms to 220 ms. We still need to validate - recall on long queries. - After: Search ranking now uses a scored model instead of heuristics, and - p95 latency fell from 900 ms to 220 ms. To do: validate recall on long - queries. - -13. **Be precise and unambiguous, and cut unnecessary clauses.** Say exactly - what changes, who does what, or by what mechanism. Prefer a concrete - statement over an evocative abstraction, e.g., don't say things like - "improvement stops being guesswork". Also drop trailing or side clauses - that add no fact, e.g., "before we call the work done", "as we move - forward", or "for the time being". Keep the sentence long when the content - needs it, but do not pad it. - Before: With trusted scores, improvement stops being guesswork. - After: With trusted scores, you can measure whether each change helped, - so you keep or revert each change based on the measured result. - Before: We still need to validate recall on long queries before we call - the work done. - After: To do: validate recall on long queries. - -14. **In chat, give context on the problem.** When you are chatting back and - forth, write for a smart reader who does not have context on the problem, - or who forgot it. Give context on the problem and on what was happening - before. Then say what changed. Keep the setup short. Do not dump the whole - history. Ignore this rule if you are writing an essay. - Before: The exporter now waits on the reset header, and `dotnet test` is - green. - After: The Okta System Log exporter was rereading whole hours, so a retry - could write the same event twice. It now waits using the response reset - header, and the six acceptance tests pass. - -## Punctuation and formatting - -15. **No dashes or middle dots.** Do not use em dashes or en dashes, including in - number ranges. Join clauses with a period or "and", and write ranges with - "to". Do not use the middle dot (·) as a separator; use a comma, "and", or - separate lines instead. - Before: The build is fast — it finishes in 10 to 20 seconds. - After: The build is fast. It finishes in 10 to 20 seconds. - -16. **Don't use colons to join clauses in ordinary prose.** Do not use a colon - to glue two clauses or to set up a point in essay-like writing. A colon is - fine when you introduce a list. A colon is also fine as a short label in - updates, briefs, status notes, and PR descriptions, e.g., "Summary:", - "Changes:", or "Remaining work:". - Before: Read for the schema: the feature fires. - After: Read for the schema. The feature fires. - Before (allowed in a PR or update): Summary: Replace em dashes in - generated docs. - After (same text is fine): Summary: Replace em dashes in generated docs. - -17. **Use straight quotes, not curly quotes.** - Before: The system logs each “event” as it happens. - After: The system logs each "event" as it happens. - -18. **Keep the formatting plain.** Use sentence case in headings. Do not use - bold for decoration. - Before: ## How To Install The Skill - After: ## How to install the skill - -19. **You can use lists, but do not overuse them.** Keep a list to three or - four points, and nest extra points if you need more. When you are writing - an essay, use lists and tables very sparingly. - Before: Shipped this week: - - dark mode - - an invite link fix - - a schema mismatch that blocked analytics export - - renderer cleanup - - copy edits - - a scored ranking model - - a p95 drop from 900 ms to 220 ms - - untested recall on long queries - After: Search ranking now uses a scored model, and p95 latency fell from - 900 ms to 220 ms. The old heuristic path is still in the repo as a - fallback. - - Shipped - - Dark mode - - Invite link fix - - Still open - - Test recall on long queries - - Unblock analytics export - -## Patterns to avoid - -20. **Do not give inanimate things fake agency.** Do not write as if a system - or object transforms, decides, or intends on its own when a person or - process is the real actor. Ordinary factual verbs for tools and systems are - fine, e.g., "The API returns JSON", "The job writes the file", or "The - paper argues". Prefer a human or process subject when that is clearer. - Before: The logs become searchable records, once the job finishes. - After: You can search the logs, once the job finishes. - -21. **No analogies or imagery.** Do not explain by comparing to something else, - and do not use metaphor. Describe the actual thing in literal terms. Write - in a boring way. - Before: The feature index is like a card catalog that the optimizer can flip - through. - After: The feature index is a list of named features. The optimizer can look - up which feature matches a request. - -22. **Never use negative parallelism of the form "not just X, it is Y" or - "not only X, but Y".** State what the thing is. A plain refusal or - correction is fine, including a short quote of a customer's hype phrase - when you replace it with a concrete fact. - Before: It is not just a parser, it is a full toolchain. - After: It is a parser and a formatter. - Before: We do not describe the API as "enterprise-grade robust," because - that phrase can mean different things. - After: The API has a 99.9% monthly uptime SLO. - -23. **Do not stack rhetorical questions.** AI writing often asks two or three - rhetorical questions in a row to sound thoughtful. Don't do this. Just state - the problem directly. - Before: Does the tool keep the writer's voice? Does it make the argument - stronger or weaker? - After: We do not yet know whether the tool keeps the writer's voice, or - whether it makes the argument stronger or weaker. - -24. **Do not use vague demonstrative pronouns.** Do not use "This", "That", - "These", or "Those", especially do not start a sentence with a demonstrative - pronoun, and never begin a paragraph with a sentence that contains a - demonstrative anywhere in it. - Before: That context carries into the next turn. - After: The agent applies the rules you saved on the next turn. - -25. **Do not open with a count of things.** Never start by announcing how many - points are coming, e.g., "Two cautions." or "Three things to keep in mind." - State the first point directly. If you absolutely must present many things, - use a bullet list instead. - Before: Two cautions. First, the section can drift out of date. Second, - it can balloon if every item gets a sentence. - After: The section can drift out of date, because it duplicates facts - that live elsewhere. It can also balloon if every item gets a sentence. - -## The deslopify command - -When the user says `/plain-writing deslopify`, rewrite the previous agent -response, or the text after the command, for a sharp CEO or technical reader -who has no project context. Return only the rewrite. - -Start with the main conclusion, then cover the background, how it works, and -present all information logically and sequentially. Include technical details -the reader needs (standardize on existing well-known terminology, not new -terminology), and define unfamiliar terms. - -Follow the plain-writing rules above. diff --git a/.claude/skills/plain-writing/UPSTREAM.md b/.claude/skills/plain-writing/UPSTREAM.md deleted file mode 100644 index 6293e8a..0000000 --- a/.claude/skills/plain-writing/UPSTREAM.md +++ /dev/null @@ -1,3 +0,0 @@ -Copied from https://github.com/docwriter-org/plain-writing-skill at commit -f0d3630983ac7a82aa580f1c1509d72df739ee12 (`skills/plain-writing/SKILL.md`). -The licence is MIT and is kept in `LICENSE` next to this file. diff --git a/.gitignore b/.gitignore index 7e11084..f639757 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,11 @@ # Local design notes and specs. Decisions that should be public go in docs/adr/. docs/design/ -# Claude Code files. The plain-writing skill under .claude/skills/ is already tracked, so it stays. +# Files for AI coding tools. They are local settings, not part of auditd-kit. .claude/ +CLAUDE.md +AGENTS.md +docs/agents/ # Python virtualenv for lint tools .venv/ @@ -10,7 +13,5 @@ docs/design/ # Release build output. dist/ -.claude/skills/plain-writing - # yamllint settings are in tests/lint.sh. .yamllint.yml diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 9b624a0..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,47 +0,0 @@ -# auditd-kit - -auditd-kit turns on Linux audit logging (auditd) across a fleet with safe defaults. It ships plain -rule and config files and POSIX shell scripts. - -## Public repository rules - -The repository is public. Never commit any of the following: - -- Client names, hostnames, IP addresses, workspace IDs, or any other site details. Examples use - `example.com` and RFC 5737 addresses. -- Design specs, plans, or notes from conversations. Keep them in `docs/design/`, which git ignores. -- Secrets or credentials. - -Record a decision that other people need to know as an ADR in `docs/adr/`. See -`docs/adr/README.md` for the format. - -## Writing style - -Use the `plain-writing` skill (`.claude/skills/plain-writing/SKILL.md`) for all prose, including -docs, ADRs, comments, commit messages, and PR descriptions. - -Keep docs short. Write only what a reader needs to use or change auditd-kit, and don't pad a doc -with summaries, restated context, or generic advice. - -Update `AI-DECLARATION.md` when the way AI tools are used on the project changes. - -## Workflow - -- Work on a short-lived branch named `feat/`, `fix/`, `docs/`, `ci/`, or `chore/`. -- Open a PR into `main`, and give it a Conventional Commits title, e.g. `feat: add a host check`. -- `main` takes squash merges only, after the required checks pass. -- Never push to `main` directly. - -## Agent skills - -### Issue tracker - -Issues live in GitHub Issues for `spydisec/auditd-kit` (via the `gh` CLI); external PRs are not a triage surface. See `docs/agents/issue-tracker.md`. - -### Triage labels - -Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`. - -### Domain docs - -Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root (created lazily). See `docs/agents/domain.md`. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 43c994c..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 66fec55..7a82638 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,8 +38,7 @@ To change an earlier decision, write a new record and mark the old one as supers ## Writing style Write prose in plain words and complete sentences. Don't use em dashes, en dashes, or curly quotes, write -headings in sentence case, and keep code comments sparse. The rules are in -`.claude/skills/plain-writing/SKILL.md`. +headings in sentence case, and keep code comments sparse. ## Licence diff --git a/docs/agents/domain.md b/docs/agents/domain.md deleted file mode 100644 index b548c53..0000000 --- a/docs/agents/domain.md +++ /dev/null @@ -1,51 +0,0 @@ -# Domain Docs - -How the engineering skills should consume this repo's domain documentation when exploring the codebase. - -## Before exploring, read these - -- **`CONTEXT.md`** at the repo root, or -- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic. -- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. - -If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. - -## File structure - -Single-context repo (most repos): - -``` -/ -├── CONTEXT.md -├── docs/adr/ -│ ├── 0001-event-sourced-orders.md -│ └── 0002-postgres-for-write-model.md -└── src/ -``` - -Multi-context repo (presence of `CONTEXT-MAP.md` at the root): - -``` -/ -├── CONTEXT-MAP.md -├── docs/adr/ ← system-wide decisions -└── src/ - ├── ordering/ - │ ├── CONTEXT.md - │ └── docs/adr/ ← context-specific decisions - └── billing/ - ├── CONTEXT.md - └── docs/adr/ -``` - -## Use the glossary's vocabulary - -When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. - -If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). - -## Flag ADR conflicts - -If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: - -> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md deleted file mode 100644 index 82cfbf5..0000000 --- a/docs/agents/issue-tracker.md +++ /dev/null @@ -1,45 +0,0 @@ -# Issue tracker: GitHub - -Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations. - -## Conventions - -- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies. -- **Read an issue**: `gh issue view --comments`, filtering comments by `jq` and also fetching labels. -- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters. -- **Comment on an issue**: `gh issue comment --body "..."` -- **Apply / remove labels**: `gh issue edit --add-label "..."` / `--remove-label "..."` -- **Close**: `gh issue close --comment "..."` - -Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone. - -## Pull requests as a triage surface - -**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_ - -When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents: - -- **Read a PR**: `gh pr view --comments` and `gh pr diff ` for the diff. -- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`). -- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`. - -GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`. - -## When a skill says "publish to the issue tracker" - -Create a GitHub issue. - -## When a skill says "fetch the relevant ticket" - -Run `gh issue view --comments`. - -## Wayfinding operations - -Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets. - -- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`. -- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #` at the top of the child body. Labels: `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev. -- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos///issues//dependencies/blocked_by -F issue_id=`, where `` is the blocker's numeric **database id** (`gh api repos///issues/ --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #, #` line at the top of the child body. A ticket is unblocked when every blocker is closed. -- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins. -- **Claim**: `gh issue edit --add-assignee @me` — the session's first write. -- **Resolve**: `gh issue comment --body ""`, then `gh issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md deleted file mode 100644 index b716855..0000000 --- a/docs/agents/triage-labels.md +++ /dev/null @@ -1,15 +0,0 @@ -# Triage Labels - -The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. - -| Label in mattpocock/skills | Label in our tracker | Meaning | -| -------------------------- | -------------------- | ---------------------------------------- | -| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | -| `needs-info` | `needs-info` | Waiting on reporter for more information | -| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | -| `ready-for-human` | `ready-for-human` | Requires human implementation | -| `wontfix` | `wontfix` | Will not be actioned | - -When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. - -Edit the right-hand column to match whatever vocabulary you actually use.