From 6ebb13d51aef936937394ff574b5aa7945200ffc Mon Sep 17 00:00:00 2001 From: Julian lechner Date: Fri, 11 Sep 2026 15:44:32 +0200 Subject: [PATCH] docs(readme): document rule skills, managed manifest, and installer params Co-Authored-By: Claude Sonnet 5 --- README.md | 64 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 6661a81..662a07e 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,17 @@ into platform-specific packages that can be inspected before they are installed. - One shared source of truth for Codex and Claude Code. - Separate generated packages for Windows and Linux. - Native PowerShell 5.1 and Bash scripts. -- Interactive installation for Codex, Claude Code, or both. -- Dry-run support and timestamped backups of replaced managed files. +- Interactive or non-interactive (`-Client`/`-Platform`) installation for Codex, Claude Code, or both. +- Claude Code loads technology- and situation-specific rules as skills, so only their name and description sit + permanently in context; the full rule text loads only when the skill is invoked. Codex keeps loading rules as plain + files, unchanged. +- A managed-file manifest (path and SHA-256 per destination) makes installation idempotent, detects files this setup + previously installed but no longer ships, and protects files a user changed locally instead of silently overwriting + or deleting them. +- Dry-run support (no writes, no backups, no plugin changes) and timestamped, per-run backup directories. - Shared safety, notification, validation, and status-line hooks. -- User-level plugin installation and updates for Ponytail, i-have-adhd, Superpowers, and Context7. +- User-level plugin installation for Ponytail, i-have-adhd, Superpowers, and Context7; updates only with + `-UpdatePlugins`/`--update-plugins`. ## Architecture @@ -74,10 +81,11 @@ Every repository change must pass the build before completion. Building only wri ## Installation -The installer runs a fresh build and then asks for the target platform and client. Selecting Linux or Windows chooses -the generated package format; installation always targets the current user's home directory. +The installer runs a fresh build and then asks for the target platform and client, unless they are passed as +parameters. Selecting Linux or Windows chooses the generated package format; installation always targets the current +user's home directory. -Preview an installation without changing user files or plugins: +Preview an installation without changing user files, backups, or plugins: Powershell: (Windows) ```powershell @@ -89,7 +97,7 @@ Bash: (Linux) ./scripts/install.sh --dry-run ``` -Install the selected configuration: +Install the selected configuration interactively: Powershell: (Windows) ```powershell @@ -101,9 +109,29 @@ Bash: (Linux) ./scripts/install.sh ``` -Existing managed files receive timestamped backups before replacement. Unrelated files are left untouched. Selecting -Codex also installs shared skills to `.agents/skills`. A normal installation ensures configured plugins are present and -updates plugins that are already installed. +Install non-interactively, for scripting or CI: + +Powershell: (Windows) +```powershell +.\scripts\install.ps1 -Client Both -Platform Windows +``` + +Bash: (Linux) +```bash +./scripts/install.sh --client both --platform linux +``` + +`-Platform`/`--platform` defaults to the current platform when omitted together with `-Client`/`--client`. + +Every installed file is tracked in a per-destination manifest (`.ai-config-manifest.tsv`). A second run of the same +installation is a no-op for unchanged files (no write, no backup). A file this setup installed before but no longer +ships is backed up and removed, unless it was changed locally since the last install, in which case it is backed up +and left in place with a warning instead. A file the installer never tracked is never touched, even if a file of the +same name is now part of the package. Backups land in a single timestamped directory per run under +`backups//` inside each destination. + +Selecting Codex also installs shared skills to `.agents/skills`. A normal installation only installs plugins that are +missing; add `-UpdatePlugins`/`--update-plugins` to also update and enable plugins that are already installed. Run the same installation command whenever the repository configuration should be updated. There is no separate update script. @@ -127,10 +155,14 @@ The doctor reports concise `PASS`, `WARN`, and `FAIL` results without reading or ## Configuration Codex receives global instructions, rules, skills, agent TOML files, hooks, and `config.toml`. Its defaults keep writes -workspace-scoped and use automatic review for eligible escalation requests. +workspace-scoped and use automatic review for eligible escalation requests. Every rule ships as a plain file under +`rules/`, and `AGENTS.md` tells Codex to load the matching one by path. -Claude Code receives the equivalent global instructions, rules, skills, agents, hooks, and `settings.json`. Its generated -settings use the supported automatic permission mode where available. +Claude Code receives the equivalent global instructions, agents, hooks, and `settings.json`. Only `general.md` ships as +an always-applied rule file (its content is also embedded directly in `CLAUDE.md`); every technology- or +situation-specific rule (`adapters/claude/rule-skills.tsv`) is generated as a skill under `skills/rules/` instead, so +only its name and description are permanently visible and the full rule text loads only when Claude invokes it. Its +generated settings use the supported automatic permission mode where available. Both clients receive the same logical agent roles: @@ -147,8 +179,10 @@ when research, design, independent review, or focused verification adds value. ### Add a rule -Create a focused Markdown file in `shared/rules/`. Add its loading condition to `shared/global-instructions.md` when the -rule applies only to a language, framework, tool, or change area. +Create a focused Markdown file in `shared/rules/`. For a rule that applies only to a language, framework, tool, or +change area, add a row to `adapters/claude/rule-skills.tsv` (Claude generates it as a skill) and add its loading +condition to the Codex rule-loading text in `scripts/build.ps1`/`scripts/build.sh` (Codex loads it as a plain file, by +path — unchanged from before). A rule that should always apply, like `general.md`, needs neither. ### Add a skill