docs: document configuration architecture and usage
This commit is contained in:
Julian lechner
@@ -0,0 +1,183 @@
|
|||||||
|
# My AI Configuration
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
[](LICENSE)
|
||||||
|
|
||||||
|
`MyAiConfiguration` is a version-controlled global user configuration for OpenAI Codex and Claude Code.
|
||||||
|
|
||||||
|
It keeps rules, skills, agents, hooks, and orchestration guidance in shared source files. Client adapters turn those files
|
||||||
|
into platform-specific packages that can be inspected before they are installed.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- 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.
|
||||||
|
- Shared safety, notification, validation, and status-line hooks.
|
||||||
|
- User-level plugin installation and updates for Ponytail, i-have-adhd, Superpowers, and Context7.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```text
|
||||||
|
shared definitions -> client adapters -> generated packages -> user installation
|
||||||
|
```
|
||||||
|
|
||||||
|
| Directory | Purpose |
|
||||||
|
| --- | --- |
|
||||||
|
| `shared/` | Client-independent rules, agents, skills, hooks, status lines, and global instructions. |
|
||||||
|
| `adapters/` | Codex and Claude Code formats, settings, templates, and the plugin manifest. |
|
||||||
|
| `generated/` | Reproducible Windows and Linux packages. This directory is ignored by Git. |
|
||||||
|
| `scripts/` | Build, installation, diagnosis, and platform validation entry points. |
|
||||||
|
| `docs/` | Focused documentation about the configuration design. |
|
||||||
|
|
||||||
|
The build creates:
|
||||||
|
|
||||||
|
```text
|
||||||
|
generated/
|
||||||
|
├── codex-windows/
|
||||||
|
├── claude-windows/
|
||||||
|
├── codex-linux/
|
||||||
|
└── claude-linux/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Windows PowerShell 5.1 or newer on Windows.
|
||||||
|
- Bash on Linux.
|
||||||
|
- The Codex and Claude Code CLIs for the clients that should be installed or diagnosed.
|
||||||
|
- Network access for plugin installation and updates.
|
||||||
|
|
||||||
|
The Bash scripts do not require PowerShell. The PowerShell scripts remain compatible with Windows PowerShell 5.1;
|
||||||
|
PowerShell 7 can also run them.
|
||||||
|
|
||||||
|
## Build
|
||||||
|
|
||||||
|
Run the matching command from the repository root:
|
||||||
|
|
||||||
|
Powershell: (Windows)
|
||||||
|
```powershell
|
||||||
|
.\scripts\build.ps1
|
||||||
|
```
|
||||||
|
|
||||||
|
Bash: (Linux)
|
||||||
|
```bash
|
||||||
|
./scripts/build.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Every repository change must pass the build before completion. Building only writes reproducible files below
|
||||||
|
`generated/`; it does not modify global user configuration.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
Preview an installation without changing user files or plugins:
|
||||||
|
|
||||||
|
Powershell: (Windows)
|
||||||
|
```powershell
|
||||||
|
.\scripts\install.ps1 -DryRun
|
||||||
|
```
|
||||||
|
|
||||||
|
Bash: (Linux)
|
||||||
|
```bash
|
||||||
|
./scripts/install.sh --dry-run
|
||||||
|
```
|
||||||
|
|
||||||
|
Install the selected configuration:
|
||||||
|
|
||||||
|
Powershell: (Windows)
|
||||||
|
```powershell
|
||||||
|
.\scripts\install.ps1
|
||||||
|
```
|
||||||
|
|
||||||
|
Bash: (Linux)
|
||||||
|
```bash
|
||||||
|
./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.
|
||||||
|
|
||||||
|
Run the same installation command whenever the repository configuration should be updated. There is no separate update
|
||||||
|
script.
|
||||||
|
|
||||||
|
## Doctor
|
||||||
|
|
||||||
|
Check client availability, generated packages, source directories, hooks, and installed managed files:
|
||||||
|
|
||||||
|
Powershell: (Windows)
|
||||||
|
```powershell
|
||||||
|
.\scripts\doctor.ps1
|
||||||
|
```
|
||||||
|
|
||||||
|
Bash: (Linux)
|
||||||
|
```bash
|
||||||
|
./scripts/doctor.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
The doctor reports concise `PASS`, `WARN`, and `FAIL` results without reading or printing credentials.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Both clients receive the same logical agent roles:
|
||||||
|
|
||||||
|
- Architect
|
||||||
|
- Implementer
|
||||||
|
- Researcher
|
||||||
|
- Reviewer
|
||||||
|
- Verifier
|
||||||
|
|
||||||
|
Agent use is proportional to the task. Small changes can stay with the implementer, while additional roles are available
|
||||||
|
when research, design, independent review, or focused verification adds value.
|
||||||
|
|
||||||
|
## Extending the Configuration
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
### Add a skill
|
||||||
|
|
||||||
|
Create `shared/skills/<category>/<skill>/SKILL.md` with valid YAML frontmatter and a concise workflow. Reference shared
|
||||||
|
rules instead of repeating persistent standards.
|
||||||
|
|
||||||
|
### Add an agent
|
||||||
|
|
||||||
|
Create `shared/agents/<agent>/agent.yml` and `instructions.md`. Keep semantic behavior in these shared files; the build
|
||||||
|
renders the Codex and Claude Code formats.
|
||||||
|
|
||||||
|
Rebuild after every semantic change.
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
- Never store API keys, OAuth tokens, credentials, authentication state, or sensitive logs in this repository.
|
||||||
|
- Review generated output and use the installer's dry-run before installation.
|
||||||
|
- Global installation happens only through an explicit installer invocation.
|
||||||
|
- Plugins execute with permissions granted by their client; review their upstream sources and trust prompts.
|
||||||
|
- Codex keeps workspace sandboxing enabled and requires escalation outside expected development boundaries.
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
Create an [issue](https://git.lechner-systems.at/fraujulian/MyAiConfiguration/issues) for problems or proposed changes.
|
||||||
|
|
||||||
|
## Contributors
|
||||||
|
|
||||||
|
~ [**FrauJulian - Julian Lechner**](https://fraujulian.xyz/)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
Licensed under the [MIT License](LICENSE).
|
||||||
|
|||||||
@@ -0,0 +1,11 @@
|
|||||||
|
# Agents
|
||||||
|
|
||||||
|
The five shared agents are logical roles, not mandatory steps.
|
||||||
|
|
||||||
|
- `implementer` executes the smallest complete engineering change and performs self-review.
|
||||||
|
- `researcher` investigates code, patterns, evidence, alternatives, and unknowns without modifying implementation code by default.
|
||||||
|
- `architect` evaluates technical boundaries, dependencies, interfaces, constraints, and design options.
|
||||||
|
- `verifier` checks completed work against requested behavior, acceptance criteria, tests, generated output, and configuration.
|
||||||
|
- `reviewer` independently checks correctness, regressions, security, maintainability, architecture, tests, and unnecessary complexity.
|
||||||
|
|
||||||
|
Use only the roles that are likely to improve the outcome. Choose `researcher`, `reviewer`, and `verifier` based on the task's uncertainty, complexity, risk, blast radius, and verification value; none runs automatically. The agent may make evidence-based, reversible technical decisions. Ask the user when technical choices remain materially uncertain or when business behavior, user-visible behavior, UI, UX, APIs, database models, configuration formats, compatibility behavior, or other high-impact decisions are ambiguous or open to interpretation.
|
||||||
@@ -0,0 +1,5 @@
|
|||||||
|
# Architecture
|
||||||
|
|
||||||
|
Shared Markdown and metadata define meaning once. Codex and Claude adapters contain only client-specific paths, filenames, and serialization details. The build script renders those inputs into `generated/`. Installation is a separate, explicit step that copies generated files into global user-level locations with backups.
|
||||||
|
|
||||||
|
Generated output is ignored because it is reproducible build output. The source files are the reviewable record.
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
# Configuration
|
||||||
|
|
||||||
|
Codex receives a generated global `AGENTS.md`, agent TOML files, skills, and a `config.toml` adapter with workspace sandboxing, interactive approval boundaries, automatic approval review, enabled sub-agents, and a five-thread concurrency limit. Claude Code receives a generated global `CLAUDE.md`, agent Markdown files, skills, and `settings.json` with the `auto` permission mode, explicit `Agent` permission, and a five-operation tool/sub-agent concurrency limit. The exact installed locations are resolved from the user profile at install time; no machine-specific absolute path is stored in the repository.
|
||||||
|
|
||||||
|
Neither current client configuration model exposes a supported global `max_depth` setting. The repository does not emit an unsupported key that would be ignored or cause configuration validation errors.
|
||||||
|
|
||||||
|
Client settings remain thin adapters. Shared semantics remain in `shared/`.
|
||||||
|
|
||||||
|
User plugins are managed separately through `adapters/plugins.tsv` and the client-native plugin commands. They are not copied into `generated/` because each client owns its plugin cache and authentication state.
|
||||||
@@ -0,0 +1,7 @@
|
|||||||
|
# Hooks
|
||||||
|
|
||||||
|
Deterministic safety and validation hooks live in `shared/hooks/scripts/`. The flashbang entry points live directly in `shared/hooks/`. The command safety hook rejects obvious destructive commands outside the current development workspace. The session validation hook checks repository-local generated inputs. The post-change hook is an optional verification entry point.
|
||||||
|
|
||||||
|
The build includes the hooks and their client-specific registration in each payload. Installation places them beside the generated client files. The scripts do not grant permissions, bypass approvals, or replace client permission systems.
|
||||||
|
|
||||||
|
The PowerShell and Bash hook variants are registered only for the Codex and Claude `Stop` events. They run after the main agent finishes responding, not during tool calls, thinking, permission requests, or notifications. The default flash lasts about 500 milliseconds. The Windows command deliberately omits `-WindowStyle Hidden`, which can hide or minimize the shared terminal. The PowerShell hook creates a low-opacity click-through overlay without activating another window. The Bash hook creates the equivalent temporary overlay through Python's standard `tkinter` module, uses `xrandr` for multi-monitor bounds when available, and does not reactivate the terminal. It falls back to `notify-send` in headless or minimal environments. Hooks are intentionally not executed during build or doctor.
|
||||||
@@ -0,0 +1,11 @@
|
|||||||
|
# Plugins
|
||||||
|
|
||||||
|
The user-level plugin manifest is `adapters/plugins.tsv`. It maps each logical plugin to the marketplace selector understood by Claude Code and Codex.
|
||||||
|
|
||||||
|
The current baseline includes Ponytail, i-have-adhd, Superpowers, and Context7. The install script operates at user scope and is idempotent: existing Claude plugins are enabled and updated, and Codex plugins are updated or ensured through the Codex plugin command.
|
||||||
|
|
||||||
|
Plugin installation requires the corresponding client CLI, network access, and any authentication required by the plugin. Context7 may open an OAuth flow. Codex or plugin hooks may require a trust review in `/hooks`. The scripts never install plugins during a build or doctor run and never install them when `--dry-run` or `-DryRun` is used.
|
||||||
|
|
||||||
|
If Codex reports that a marketplace is already registered from another source, the scripts remove only the conflicting marketplace name from the configured user-level Codex sources, add the repository source from the manifest, and continue with the Codex plugin command. Other marketplace errors remain fatal.
|
||||||
|
|
||||||
|
Only trusted upstream marketplace sources should be added. Plugins are executable extensions and may access the permissions granted to their client.
|
||||||
@@ -0,0 +1,15 @@
|
|||||||
|
# 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.
|
||||||
|
|
||||||
|
The current structure is organized by purpose:
|
||||||
|
|
||||||
|
- `debugging/`
|
||||||
|
- `planning/`: implementation planning, impact analysis, and work-item definition
|
||||||
|
- `research/`: technical and repository research
|
||||||
|
- `reviews/`: code, security, performance, WPF, UI/UX, business, API, and EF Core reviews
|
||||||
|
- `implementation/`: SQL, unit-test, and integration-test writing
|
||||||
|
- `verification/`: facts, work-item, and regression verification
|
||||||
|
- `git/`: pull request responses and reviews
|
||||||
|
|
||||||
|
The files intentionally define only a small baseline. Detailed personal workflows and standards can be added later without changing the structure.
|
||||||
Reference in New Issue
Block a user