diff --git a/README.md b/README.md index eee862b..877899a 100644 --- a/README.md +++ b/README.md @@ -96,8 +96,8 @@ Install and update also rebuild internally; the explicit build above lets you ch - Separate install, update, and uninstall scripts: install refuses to run against an already-installed destination, update refuses to run against one that is not installed yet, and uninstall refuses to run against one that was never installed. -- User-level plugin installation for Ponytail, i-have-adhd, Superpowers, Context7, Caveman, QMD, Humanizer, Impeccable, and - Anthropic Frontend Design, with an interactive extension toggle during both install and update. Only extensions +- User-level extension installation for Ponytail, i-have-adhd, Superpowers, Context7, Caveman, QMD, MCPorter, + Humanizer, Impeccable, and Anthropic Frontend Design, with an interactive extension toggle during both install and update. Only extensions installed and recorded by this setup can be removed through deselection. - Optional local semantic retrieval for both clients using Qwen3-Embedding-0.6B embeddings and Qwen3-Reranker-0.6B reranking, disabled by default and removable through the install/update choice. @@ -111,8 +111,9 @@ Install and update also rebuild internally; the explicit build above lets you ch - Python `venv` and `pip` when the optional semantic retrieval layer is enabled. - Node.js 22 or newer and `npm` when QMD or MCPorter is selected. -The Bash scripts do not require PowerShell. The PowerShell scripts remain compatible with PowerShell 5.1; -PowerShell 7 can also run them. +Core Bash setup scripts do not require PowerShell. The credential commands use Windows Credential Manager and require +PowerShell, including when invoked through their Bash wrappers. The PowerShell scripts remain compatible with +PowerShell 5.1; PowerShell 7 can also run them. ## Architecture @@ -214,12 +215,18 @@ and replaced, with a warning. Untracked files outside package target paths are l Previously managed files no longer shipped are backed up and removed if unchanged. If locally modified, they are backed up and retained with a warning. Backups are stored under `backups//` in each destination. -Local Codex `model`, `model_reasoning_effort`, `plugins`, and `marketplaces` settings are preserved when syncing `config.toml`; -other local settings are not generally merged. Dry runs still rebuild `generated/`, but do not modify installation destinations. +Codex skill backups use `.agents/.ai-config-skill-backups/` instead, so Codex does not discover backup copies as skills. +Existing `.agents/skills/backups/` content is moved there on the next install, update, or uninstall. +Codex `config.toml` synchronization merges setup-owned keys while retaining other root keys, extra fields in managed +tables, plugin and marketplace tables, and unowned array tables. Other standalone tables may be dropped; the previous +file is backed up when content changes. Claude `settings.json` synchronization retains unrelated settings and hooks. +Dry runs still rebuild `generated/`, but do not modify installation destinations. Selecting Codex also installs shared skills to `.agents/skills`. An interactive extension list includes plugins and Codex skills; unchecked extensions are skipped on installation. Normal install and update ask whether to enable Flashbang, apply the custom status line, and enable Qwen3 semantic retrieval. Choices are saved for Quickupdate. +The shared skill catalog includes development skills and focused writing, image, site structure, psychology, and +conversion skills. All retained skills are included in both generated clients. The status line defaults to enabled to preserve existing behavior. Disabling it removes the custom client setting and, for Claude, the setup-owned status line script. Disabling retrieval on update removes its setup-owned runtime and index. Dry runs preview changes without updating extensions or retrieval. See [Plugins](docs/plugins.md) for client-specific behavior. @@ -270,7 +277,8 @@ touching anything, unless `-Force`/`--force` is passed; running without a termin fails instead of hanging. Removal reuses the same manifest-sync logic as install and update: every managed file is backed up under `backups//` before removal, and a file changed locally since the last install/update is backed up but left in place with a warning instead of being deleted. Files this setup never installed are never -touched. A destination directory is only deleted once it is fully empty; backups already on disk are always kept. +touched. Codex skill backups are kept under `.agents/.ai-config-skill-backups/`. A destination directory is only +deleted once it is fully empty; backups already on disk are always kept. Extensions and skills recorded in the ledger are removed the same way `update` removes a deselected extension: pre-existing or manually installed ones outside the ledger are left alone, and a skill file modified since it was installed is kept with a warning. An enabled semantic retrieval setup is disabled and its setup-owned runtime and @@ -285,7 +293,10 @@ keep outside this setup's ledger, or files this setup never installed. Codex and Claude Code receive the same shared rules, skills, agents, hooks, and status data. Codex loads applicable rules from generated files, while Claude Code exposes technology- and situation-specific rules as generated skills. -The default configuration keeps writes workspace-scoped and enables automatic review for eligible escalation requests. Both clients include the same logical agent roles and compact status displays. See [Configuration](docs/configuration.md) for settings, permissions, and limitations. +Codex defaults to workspace-write sandboxing and automatic review for eligible escalation requests. Claude uses +automatic permissions and enables its sandbox where the platform supports it; explicit deny rules still apply where it +does not. Both clients include the same logical agent roles and compact status displays. See +[Configuration](docs/configuration.md) for settings, permissions, and limitations. ## Support diff --git a/adapters/prompt-budget-baseline.json b/adapters/prompt-budget-baseline.json index 37299d9..6995d0d 100644 --- a/adapters/prompt-budget-baseline.json +++ b/adapters/prompt-budget-baseline.json @@ -4,16 +4,16 @@ "permanent_context_hard_limit_tokens": 15000, "metrics": { "permanent_context_tokens": { - "claude": 14521, - "codex": 12997 + "claude": 5451, + "codex": 3767 }, "instruction_tokens": { "claude": 1485, "codex": 1485 }, "skill_metadata_tokens": { - "claude": 12233, - "codex": 10784 + "claude": 3163, + "codex": 1554 }, "auto_loaded_rule_tokens": { "claude": 678, diff --git a/adapters/prompt-budget-baseline.tsv b/adapters/prompt-budget-baseline.tsv index 0abd1da..2e4faf7 100644 --- a/adapters/prompt-budget-baseline.tsv +++ b/adapters/prompt-budget-baseline.tsv @@ -1,10 +1,10 @@ metric client baseline_tokens -permanent_context_tokens claude 14521 -permanent_context_tokens codex 12997 +permanent_context_tokens claude 5451 +permanent_context_tokens codex 3767 instruction_tokens claude 1485 instruction_tokens codex 1485 -skill_metadata_tokens claude 12233 -skill_metadata_tokens codex 10784 +skill_metadata_tokens claude 3163 +skill_metadata_tokens codex 1554 auto_loaded_rule_tokens claude 678 auto_loaded_rule_tokens codex 678 rule_catalog_tokens claude 28818 diff --git a/docs/skills.md b/docs/skills.md index 2245919..5fd3c47 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -1,6 +1,6 @@ # Skills -Skills are reusable workflows. Rules are persistent constraints and agents are specialized roles. Each skill is a minimal `SKILL.md` with YAML frontmatter and a small initial workflow so both clients can consume it. +Skills are reusable workflows. Rules are persistent constraints and agents are specialized roles. Each skill has a readable `SKILL.md` with YAML frontmatter; detailed guidance may live in that file or its `references/` directory. The current structure is organized by purpose: @@ -11,9 +11,14 @@ The current structure is organized by purpose: - `implementation/`: SQL, unit-test, and integration-test writing - `verification/`: facts, work-item, and regression verification - `git/`: pull request reviews +- `content-strategy/`, `copy-editing/`, `copywriting/`: planning, editing, and writing text +- `image/`, `site-architecture/`: visuals and website structure +- `marketing-psychology/`, `offers/`, `product-marketing/`, `cro/`: audience understanding, value framing, and conversion Each skill defines a focused workflow with the investigation, decision points, and output expected for that task. Keep guidance specific to the skill; shared repository constraints belong in the rules. +The single catalog in `shared/skills/` includes development skills and focused skills for writing, images, content and site structure, positioning, psychology, and conversion. Builds include every retained skill for both clients. Updating a managed installation backs up and removes unchanged setup-owned skills deleted from the catalog; local changes are backed up and retained. + Claude's generated package additionally has `skills/rules/`: one skill per focused rule file or directory in `shared/rules/`. The rule-to-skill loading conditions live in `shared/global-instructions.md`, so full rule text loads only when Claude invokes a matching skill instead of sitting permanently in context. Codex reads the matching rule