@event4u/agent-config 1.9.1 → 1.12.0

package/.agent-src/commands/onboard.md

@@ -0,0 +1,171 @@
+---
+name: onboard
+description: First-run setup for a developer on this project — captures name, IDE, bot-icon preference, rtk, cost_profile, and learning opt-out, then sets onboarding.onboarded=true
+skills: [file-editor]
+disable-model-invocation: true
+---
+
+# /onboard
+
+Centralized first-run flow. Bundles what used to be scattered "ask once"
+prompts (user_name, IDE, rtk install, cost profile, learning loop) into a
+single interactive setup. Ends by setting `onboarding.onboarded: true` in
+`.agent-settings.yml`.
+
+Triggered by the [`onboarding-gate`](../rules/onboarding-gate.md) rule when
+`onboarding.onboarded` is `false` or by the user explicitly re-running it.
+
+## When NOT to use
+
+- Change cost profile only → [`/set-cost-profile`](set-cost-profile.md).
+- Single-value edit → ask the agent to change it, or edit
+  `.agent-settings.yml` directly. The agent follows the merge rules in
+  [`layered-settings`](../guidelines/agent-infra/layered-settings.md).
+
+## Preconditions
+
+`.agent-settings.yml` exists. If missing, tell the user to run
+`scripts/install` (or `python3 scripts/install.py`) first and stop — this
+command assumes the file and its template-derived defaults are in place.
+
+## Steps
+
+### 1. Greet and set expectations
+
+Keep it short. One line explaining this is the one-time setup, six
+questions, one at a time, following the iron law (`user-interaction`).
+
+### 2. Capture `personal.user_name`
+
+Skip if already set (non-empty). Otherwise:
+
+```
+> What first name should I use when talking to you?
+>
+> 1. Type your name
+> 2. Skip — stay anonymous
+```
+
+Free-text answer → write to `personal.user_name`. `2` → leave empty.
+
+### 3. Capture `personal.ide` (with auto-detect)
+
+Skip if already set. Otherwise auto-detect first:
+
+```bash
+ps aux | grep -iE '(Visual Studio Code|Code Helper|phpstorm|cursor)' | grep -v grep
+```
+
+- Detected → confirm: `> Detected {ide}. 1. Yes, use it  2. Pick another  3. Skip`.
+- Not detected → ask:
+
+```
+> Which IDE do you use for this project?
+>
+> 1. VS Code (code)
+> 2. PhpStorm (phpstorm)
+> 3. Cursor (cursor)
+> 4. Skip — I'll configure it later
+```
+
+If IDE is set, also ask about `personal.open_edited_files` (`true`/`false`).
+
+### 4. Capture `personal.pr_comment_bot_icon`
+
+Personal preference — each developer decides how their own PR replies
+should look. Skip only if the user has already set a non-default value
+deliberately (agent can't tell, so always ask on first run):
+
+```
+> When I reply to PR review comments on your behalf, should I prefix each
+> reply with 🤖 so reviewers can tell it was a bot-authored reply?
+>
+> 1. Yes — prefix replies with 🤖 (transparent to reviewers)
+> 2. No — plain replies, no prefix (default)
+```
+
+`1` → write `personal.pr_comment_bot_icon: true`. `2` → leave `false`.
+
+### 5. Detect `personal.rtk_installed`
+
+Silent `which rtk`.
+
+- **Found** → write `personal.rtk_installed: true`. No question.
+- **Not found** → ask:
+
+```
+> rtk (Rust Token Killer) is not installed. It cuts verbose CLI output by
+> 60–90% and saves tokens on long test/log/git runs.
+>
+> 1. Install via Homebrew — brew install rtk
+> 2. Install via Cargo — cargo install rtk
+> 3. Skip for now — continue without it
+```
+
+`1` or `2` → run install, on success set `rtk_installed: true` and apply
+rtk post-install steps (telemetry off, init --global) per the
+[`rtk-output-filtering`](../skills/rtk-output-filtering/SKILL.md) skill.
+`3` → leave `rtk_installed: false` and move on. No "ask again tomorrow"
+logic — `/onboard` is one-shot.
+
+### 6. Confirm `cost_profile` and learning loop
+
+Read current `cost_profile` and `pipelines.skill_improvement` values.
+Present them plainly (they already have sensible defaults from the
+template — `minimal` + `skill_improvement: true`):
+
+```
+> Cost profile: {current} (minimal by default — includes the learning loop)
+> Learning loop (skill_improvement): {current} (true by default)
+>
+> 1. Keep defaults — recommended
+> 2. Change cost profile — opens /set-cost-profile
+> 3. Disable learning loop — sets pipelines.skill_improvement=false
+```
+
+`2` → defer to `/set-cost-profile` and return here. `3` → flip the toggle.
+
+### 7. Mark onboarded
+
+Write `onboarding.onboarded: true` to `.agent-settings.yml` using the
+section-aware merge rules from
+[`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+(preserve comments, key order, touch only the changed fields).
+
+### 8. Summary
+
+Echo what was captured, in one block:
+
+```
+✅  Onboarding complete.
+
+  personal.user_name: {value or —}
+  personal.ide: {value or —}
+  personal.open_edited_files: {value}
+  personal.pr_comment_bot_icon: {value}
+  personal.rtk_installed: {value}
+  cost_profile: {value}
+  pipelines.skill_improvement: {value}
+  onboarding.onboarded: true
+
+You can re-run this with /onboard anytime, or edit .agent-settings.yml
+directly — the agent follows the merge rules in `layered-settings` when
+you ask it to change a value.
+```
+
+## Gotchas
+
+- `.agent-settings.yml` is git-ignored. This command never commits.
+- One question per turn. The iron law from `ask-when-uncertain` applies;
+  do not stack questions 2–6 into a single prompt.
+- Re-running `/onboard` when `onboarded: true` is allowed — walk through
+  all steps again and rewrite the values the user confirms.
+- Never overwrite a non-empty value without asking (applies to `user_name`
+  and `ide`).
+
+## See also
+
+- [`onboarding-gate`](../rules/onboarding-gate.md) — rule that triggers this command
+- [`set-cost-profile`](set-cost-profile.md) — isolated profile change
+- [`layered-settings`](../guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
+- [`agent-settings` template](../templates/agent-settings.md) — settings reference

package/.agent-src/commands/roadmap-create.md

@@ -92,8 +92,13 @@ Show the complete roadmap to the user and ask (in their language) if anything sh
 
 ### 7. Update the progress dashboard
 
-Run `task roadmap-progress` so the new roadmap shows up in
-`agents/roadmaps-progress.md`. Mention the new overall count to the user.
+Regenerate `agents/roadmaps-progress.md` so the new roadmap shows up:
+
+```bash
+./agent-config roadmap:progress
+```
+
+Mention the new overall count to the user.
 
 ### 8. Offer execution
 

package/.agent-src/commands/roadmap-execute.md

@@ -44,7 +44,7 @@ For each open step:
 
 - Update the roadmap file: mark the completed step (e.g. `[x]` or add a completion note).
 - Run quality tools if code was changed (PHPStan at minimum).
-- Run `task roadmap-progress` so `agents/roadmaps-progress.md` reflects the new state.
+- Regenerate `agents/roadmaps-progress.md` — `./agent-config roadmap:progress`.
 - Ask: "Continue with the next step?"
 
 ### 5. After all steps in a phase
@@ -56,7 +56,7 @@ For each open step:
 
 - Summarize total progress: steps completed, steps remaining.
 - Update the roadmap file with the current status.
-- Run `task roadmap-progress` one last time so the dashboard matches the final state.
+- Regenerate the dashboard one last time so it matches the final state.
 - **If ALL steps are done** → trigger the completion & archiving workflow from the `roadmap-management` skill.
 
 ### Rules

package/.agent-src/commands/set-cost-profile.md

@@ -0,0 +1,101 @@
+---
+name: set-cost-profile
+description: Change the cost_profile in .agent-settings.yml — shows each profile's meaning and applies the selection
+skills: [file-editor]
+disable-model-invocation: true
+---
+
+# /set-cost-profile
+
+Changes `cost_profile` in `.agent-settings.yml`. Four profiles are defined in
+the [`agent-settings` template](../templates/agent-settings.md#cost-profiles):
+
+- `minimal` · `balanced` · `full` · `custom`
+
+`/set-cost-profile` without an argument asks interactively.
+`/set-cost-profile <name>` validates and applies directly.
+
+## When NOT to use
+
+- For first-run setup use [`/onboard`](onboard.md).
+- For any other single-value change, edit `.agent-settings.yml`
+  directly or ask the agent — the merge rules live in
+  [`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+- For role modes use [`/mode`](mode.md) — different concept (sets
+  `roles.active_role`, not `cost_profile`).
+
+## Steps
+
+### 1. Parse argument
+
+- `/set-cost-profile` → interactive (continue with steps 2–5).
+- `/set-cost-profile <name>` → validate `<name>` against the four defined
+  profiles. If unknown, refuse and list the valid values.
+
+Profile names are case-insensitive on input; the file value stays lowercase.
+
+### 2. Read settings
+
+Read `.agent-settings.yml`. If missing, tell the user to run
+`scripts/install` first and stop — do not create the file here.
+
+Extract the current `cost_profile` value.
+
+### 3. Load profile descriptions
+
+Read `.augment/templates/agent-settings.md` and extract the `## Cost profiles`
+section (table rows). This is the single source of truth for profile
+meanings — do not paraphrase or inline descriptions in this command.
+
+### 4. Show current state and options
+
+Render the current value and present numbered choices with the hint text
+extracted in step 3:
+
+```
+> Current: cost_profile = {current}
+>
+> 1. minimal — {hint from template}
+> 2. balanced — {hint from template}
+> 3. full — {hint from template}
+> 4. custom — {hint from template}
+> 5. Keep current — no change
+```
+
+If `<name>` was passed as argument, skip the numbered prompt and use that
+value directly — still echo the old → new line in step 6.
+
+### 5. Write the value
+
+Update `cost_profile` in `.agent-settings.yml` using the
+[section-aware merge rules](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+(preserve comments, preserve key order, touch only the changed field).
+
+If the user picked "Keep current", do nothing and stop.
+
+### 6. Confirm
+
+```
+> cost_profile: {old} → {new}
+```
+
+If the new profile activates a surface the user hasn't used before
+(`balanced` adds the runtime dispatcher, `full` adds tool adapters), point
+the user at `docs/customization.md` for setup details — no inline setup
+steps here, that's the docs' job.
+
+## Gotchas
+
+- `.agent-settings.yml` is git-ignored. This command never commits the file.
+- Profile names are case-sensitive in the file; case-insensitive on input.
+- The template is the source of truth for descriptions — if it changes,
+  this command reflects the new text on next run.
+- `custom` ignores the profile matrix — every per-feature toggle must be
+  set explicitly afterwards. Warn the user when switching to `custom`.
+
+## See also
+
+- [`agent-settings`](../templates/agent-settings.md) — profile matrix and settings reference
+- [`layered-settings`](../guidelines/agent-infra/layered-settings.md) — merge rules for settings edits
+- [`onboard`](onboard.md) — first-run setup (includes profile confirmation)
+- [`mode`](mode.md) — role-mode setter (different concept)

package/.agent-src/commands/sync-agent-settings.md

@@ -0,0 +1,122 @@
+---
+name: sync-agent-settings
+description: Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing
+disable-model-invocation: true
+---
+
+# /sync-agent-settings
+
+Reconciles `.agent-settings.yml` with the shipped template
+(`config/agent-settings.template.yml`) and the selected cost-profile
+preset (`config/profiles/{profile}.ini`). Applies the section-aware
+merge rules documented in
+[`layered-settings`](../guidelines/agent-infra/layered-settings.md):
+
+- Template section order wins — keys reorder to match.
+- Existing user scalar values are preserved.
+- Missing keys land with their template / profile default.
+- Template comments replace user comments in the same position.
+- Unknown user keys (not in the template) are preserved under a
+  trailing `_user:` block so custom additions never vanish silently.
+
+Idempotent. Safe to run after every package update.
+
+Use when:
+
+- A new package version added sections (e.g. `chat_history`,
+  `onboarding`) that your local file is missing.
+- A key moved sections (e.g. `pr_comment_bot_icon` from `project` to
+  `personal`) and you want the reshuffle applied.
+- You edited the file by hand and want to normalize formatting.
+
+## When NOT to use
+
+- To change a value (`ide`, `cost_profile`, `max_parallel`) → edit the
+  file directly or ask the agent; the sync only reconciles structure.
+- To create `.agent-project-settings.yml` (team file) → that is a
+  separate concern; this command only touches the developer file.
+- To migrate a legacy flat `.agent-settings` → run
+  `python3 scripts/install.py` first; the installer owns migrations.
+
+## Steps
+
+### 1. Locate script and target
+
+The sync script ships in the installed package. Resolve in order:
+
+1. `./agent-config/scripts/sync_agent_settings.py` — CLI wrapper at the project root.
+2. `vendor/event4u/agent-config/scripts/sync_agent_settings.py` — Composer.
+3. `node_modules/@event4u/agent-config/scripts/sync_agent_settings.py` — npm.
+
+Target is always `<project_root>/.agent-settings.yml`.
+
+### 2. Dry-run — show the user what would change
+
+Run the script with `--dry-run` and capture stdout. Three outcomes:
+
+- **No changes** (exit 0, stdout contains `already in sync`) → tell the
+  user and stop. No prompt needed.
+  ```
+  > ✅ .agent-settings.yml already in sync — nothing to do.
+  ```
+- **Drift detected** → show the unified diff and ask:
+  ```
+  > 📝 /sync-agent-settings would update .agent-settings.yml:
+  >
+  > {diff}
+  >
+  > 1. Apply — write the changes
+  > 2. Skip — leave the file untouched
+  ```
+- **Script error** (exit 2, e.g. template or profile missing) → print
+  the error and stop; do not prompt.
+
+### 3. Act on the choice
+
+- `1` (Apply) → re-run the script **without** `--dry-run`. Confirm:
+  ```
+  > ✅ .agent-settings.yml updated.
+  ```
+  Then re-run with `--check` to confirm idempotency.
+- `2` (Skip) → stop. No changes made.
+
+Free-text replies (`"nö"`, `"leave it"`, unrecognized input) count as
+`2`. Never write on ambiguous input.
+
+### 4. Profile override
+
+The script auto-detects the profile from the target's `cost_profile`
+key and falls back to `minimal`. To sync against a different profile
+(e.g. during a profile change), pass `--profile balanced` or
+`--profile full` — but ask the user first; changing the profile is a
+separate decision from reconciling structure.
+
+## `--check` mode
+
+`sync_agent_settings.py --check` exits **2** if the file is out of
+sync, **0** otherwise — suitable for CI. Emit no diff prompt in
+check-only workflows; report the drift and let the pipeline decide.
+
+## Gotchas
+
+- **Unknown keys end up under `_user:`.** They are not deleted, but the
+  user should review and either upstream them (propose a template key)
+  or remove them. The block carries a comment explaining this.
+- **Bare lowercase identifiers stay unquoted** (`per_turn`, `rotate`,
+  `phpstorm`). Everything else (names, paths, empty strings) stays
+  quoted. That is intentional — idempotency depends on it.
+- **Comments from the template win.** If you added a note above a key,
+  the sync replaces it with the template comment. Put notes in a
+  separate file if you need them to survive syncs.
+- Changes to `config/agent-settings.template.yml` or the profile
+  presets require a package update in the consumer project before
+  this command can apply them.
+
+## See also
+
+- [`scripts/sync_agent_settings.py`](../../../scripts/sync_agent_settings.py) — the helper
+- [`config/agent-settings.template.yml`](../../../config/agent-settings.template.yml) — canonical template
+- [`config/profiles/`](../../../config/profiles/) — profile presets
+- [`layered-settings`](../guidelines/agent-infra/layered-settings.md) — the merge rules this command enforces
+- [`scripts/install.py`](../../../scripts/install.py) — first-install path; this command handles the update path
+- [`/sync-gitignore`](sync-gitignore.md) — sibling command for the `.gitignore` block

package/.agent-src/commands/sync-gitignore.md

@@ -0,0 +1,104 @@
+---
+name: sync-gitignore
+description: Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing
+disable-model-invocation: true
+---
+
+# /sync-gitignore
+
+Ensures the consumer project's `.gitignore` contains every entry the
+package expects to be ignored (symlinked `.augment/` subdirectories,
+`/agent-config` CLI wrapper, `.agent-settings*`, `.agent-chat-history*`).
+Canonical list lives in `config/gitignore-block.txt`; the same file
+drives the installer, so the two cannot drift.
+
+Use when:
+
+- A fresh package version added new managed entries and the installer
+  has not been re-run yet.
+- The project's `.gitignore` never got the block (older install, manual
+  setup, or installer ran with `--skip-gitignore`).
+- You want to audit what the block **should** look like without writing.
+
+## When NOT to use
+
+- To disable logging or change what is logged → that is
+  `chat_history.enabled` in `.agent-settings.yml`, not `.gitignore`.
+- To delete the block entirely → do it by hand; the package will not
+  re-remove its own entries.
+- To change what the block contains → edit
+  `config/gitignore-block.txt` in the package repo and re-release.
+
+## Steps
+
+### 1. Locate script and target
+
+The sync script ships in the installed package. Resolve in order:
+
+1. `./agent-config/scripts/sync_gitignore.py` — if the CLI wrapper
+   directory exists at the project root.
+2. `vendor/event4u/agent-config/scripts/sync_gitignore.py` — Composer.
+3. `node_modules/@event4u/agent-config/scripts/sync_gitignore.py` — npm.
+
+Target is always `<project_root>/.gitignore`. If no `.gitignore` exists,
+stop and tell the user — the package does not create one unilaterally:
+
+```
+> 📝 No .gitignore found at <project_root>. Create one first (e.g. `touch .gitignore`), then re-run /sync-gitignore.
+```
+
+### 2. Dry-run — show the user what would change
+
+Run the script with `--dry-run` and capture stdout. Three outcomes:
+
+- **No changes** (exit 0, stdout says "already in sync") → tell the
+  user and stop. No prompt needed.
+  ```
+  > ✅ .gitignore already in sync — nothing to do.
+  ```
+- **Additions only** (default append-only mode) → show the unified
+  diff and ask:
+  ```
+  > 📝 /sync-gitignore would add {N} entr{y|ies} to .gitignore:
+  >
+  > {diff}
+  >
+  > 1. Apply — write the changes
+  > 2. Skip — leave .gitignore untouched
+  ```
+- **Script error** (exit 2, e.g. template missing) → print the error
+  and stop; do not prompt.
+
+### 3. Act on the choice
+
+- `1` (Apply) → re-run the script **without** `--dry-run`. Confirm:
+  ```
+  > ✅ .gitignore updated ({N} entries added).
+  ```
+- `2` (Skip) → stop. No changes made.
+
+Free-text replies (`"nö"`, `"leave it"`, unrecognized input) count as
+`2`. Never write on ambiguous input.
+
+### 4. Offer `--replace` only when asked
+
+Do **not** suggest `--replace` by default. It rewrites the block in
+full and drops user-added lines inside the block — destructive.
+Mention it only if the user explicitly asks to clean up or reset the
+block, and confirm once more before running it.
+
+## Gotchas
+
+- The script honors the explicit `# event4u/agent-config — END` marker.
+  Legacy blocks without it get the marker added automatically on the
+  first sync — that is expected, not a bug.
+- User-added lines **inside** the block survive append-only syncs.
+  They do not survive `--replace`.
+- Changes to `config/gitignore-block.txt` require a package update in
+  the consumer project before this command can apply them.
+
+## See also
+
+- [`scripts/sync_gitignore.py`](../../../scripts/sync_gitignore.py) — the helper
+- [`config/gitignore-block.txt`](../../../config/gitignore-block.txt) — canonical block body
+- [`scripts/install.sh`](../../../scripts/install.sh) — installer integration (same source of truth, `--skip-gitignore` to opt out)

package/.agent-src/commands/tests-execute.md

@@ -14,13 +14,13 @@ disable-model-invocation: true
 Check in this order — use the **first match**:
 
 1. **Makefile** exists → look for test targets (`make test`, `make test-unit`, etc.)
-2. **Taskfile.yml** exists → look for test tasks (`task test`, `task test-unit`, etc.)
-3. **`artisan` exists** → Laravel project → `php artisan test`
-4. **`vendor/bin/pest` exists** → Pest → `vendor/bin/pest`
-5. **Fallback** → PHPUnit → `vendor/bin/phpunit`
+2. **`artisan` exists** → Laravel project → `php artisan test`
+3. **`vendor/bin/pest` exists** → Pest → `vendor/bin/pest`
+4. **Fallback** → PHPUnit → `vendor/bin/phpunit`
 
-**Prefer Makefile/Taskfile targets** over raw commands — they handle container access,
-environment variables, and parallel settings automatically.
+**Prefer Makefile targets** over raw commands — they handle container access,
+environment variables, and parallel settings automatically. If the project
+uses a different task runner, inspect its config before falling back to raw.
 
 ### 2. Run the tests
 

package/.agent-src/commands/upstream-contribute.md

@@ -115,10 +115,11 @@ Frontmatter must have `source: package`.
 ### 6. Run quality gates
 
 ```bash
-task lint-skills                    # 0 FAIL required
-task check-compression              # No 🔴 errors for this file
-task generate-tools                 # Regenerate symlinks
-task consistency                    # Everything clean
+python3 scripts/skill_linter.py --all           # 0 FAIL required
+python3 scripts/check_compression.py            # No 🔴 errors for this file
+python3 scripts/compress.py --generate-tools    # Regenerate symlinks
+bash scripts/compress.sh --check                # .agent-src/ in sync with source
+bash scripts/compress.sh --check-hashes         # All hashes match
 ```
 
 Fix any issues before continuing.

package/.agent-src/contexts/augment-infrastructure.md

@@ -68,7 +68,7 @@ Define hard constraints: coding standards, Docker usage, language preferences, s
 | `rtk.md` | Using rtk for token-efficient CLI output filtering |
 | `agent-docs.md` | When to read/create/update documentation |
 | `augment-portability.md` | Everything in `.augment/` must be project-agnostic |
-| `roadmap-progress-sync.md` | Checkbox edits in `agents/roadmaps/*.md` must trigger `task roadmap-progress` in the same response |
+| `roadmap-progress-sync.md` | Checkbox edits in `agents/roadmaps/*.md` must regenerate `agents/roadmaps-progress.md` in the same response |
 
 ### Skills (`.augment/skills/`)
 
@@ -113,7 +113,7 @@ Commands organized by workflow:
 | **E2E** | `e2e-plan`, `e2e-heal` |
 | **Agents** | `agents-prepare`, `agents-audit`, `agents-cleanup`, `copilot-agents-optimize`, `agent-handoff`, `agent-status`, `optimize-agents`, `optimize-augmentignore`, `optimize-skills`, `optimize-rtk-filters` |
 | **Overrides** | `override-create`, `override-manage` |
-| **Config** | `config-agent-settings`, `commit` |
+| **Config** | `onboard`, `set-cost-profile`, `commit` |
 | **Packages** | `package-test`, `package-reset` |
 | **Project** | `project-analyze`, `project-health`, `jira-ticket` |
 

package/.agent-src/contexts/override-system.md

@@ -149,7 +149,7 @@ When a project using this package wants to **optimize** a shared rule or skill:
 
 - The PR must contain **both** uncompressed and compressed versions (complete files)
 - The compressed version must be derived from the uncompressed version
-- Changes must pass the skill linter (`task lint-skills`)
+- Changes must pass the skill linter (`python3 scripts/skill_linter.py --all`)
 - Changes must not be project-specific (no domain assumptions)
 - Changes must pass the promotion gate (see `controlled-self-optimization.md`)
 

package/.agent-src/contexts/subagent-configuration.md

@@ -51,9 +51,9 @@ completes a multi-step task 2-3x faster than serial at ~2x the cost.
 
 ## When settings change
 
-The `/config-agent-settings` command detects changes and re-resolves
-on next invocation. There is no long-running process to restart — the
-commands read `.agent-settings.yml` on each run.
+Edits to `.agent-settings.yml` (manual or via the agent) take effect
+on the next invocation — there is no long-running process to restart.
+The commands read `.agent-settings.yml` fresh on each run.
 
 ## Related