@event4u/agent-config 1.9.1

package/.agent-src/skills/verify-before-complete/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: verify-before-complete
+description: "Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs."
+source: package
+---
+
+# verify-before-complete
+
+## When to use
+
+* Just before claiming a task, feature, fix, or refactor is complete
+* Just before proposing `/commit`, `/create-pr`, or pushing
+* Before answering "is it ready?", "can I merge?", "does it work?"
+* After a sequence of edits, when next step is reporting to the user
+* Whenever "should work", "looks good", "probably fine" is about to
+  appear in a reply
+
+Do NOT use when:
+
+* Still actively editing — run targeted tests, not the full gate
+* Pure documentation changes with no executable impact
+* The user explicitly asks for a draft / exploration, not a final answer
+
+## Goal
+
+Make every completion claim **traceable to captured output from this
+message**. No claim survives unless the command that proves it was run
+and its output was read inside the current turn.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH EVIDENCE IN THIS MESSAGE.
+```
+
+"I already ran it earlier in the conversation" does not count. Earlier
+runs are stale the moment another edit lands.
+
+## Procedure
+
+### 1. Identify the claim you are about to make
+
+Examples: *"all tests pass"*, *"ready for PR"*, *"refactor is done"*,
+*"bug is fixed"*.
+
+Each claim maps to a specific verification command. Write the mapping
+before running anything:
+
+| Claim | Evidence command |
+|---|---|
+| "tests pass" | full or targeted test suite |
+| "no static errors" | PHPStan / TypeScript / mypy on changed scope |
+| "style is clean" | ECS / Prettier / ESLint |
+| "no automated refactor pending" | Rector --dry-run clean |
+| "endpoint works" | curl / Postman / integration test output |
+| "UI renders" | Playwright snapshot or manual browser check |
+| "bug is fixed" | regression test passes |
+
+### 2. Run the command fresh
+
+* Run against current working tree, not a cached summary.
+* PHP projects inside Docker: run inside the container (see
+  [`docker`](../docker/SKILL.md) and [`tests-execute`](../tests-execute/SKILL.md)).
+* Use targeted runs during iteration (`--filter=`, `--testNamePattern`).
+  Run full suite only in the final verification pass.
+
+### 3. Read the full output
+
+* Check the exit code.
+* Count failures, errors, warnings.
+* Do not rely on the last line — scroll through the output for
+  deprecations, skipped tests, silent retries.
+
+### 4. Match output against the claim
+
+Ask: *"Does this output actually support what I am about to say?"*
+
+* 248/250 tests passed with 2 skipped → do not say "all green"; name the skips.
+* PHPStan exit 0 but only analyzed one file → do not say "no static
+  errors"; name the scope that was checked.
+* `curl` returned 200 → check the body, not just the status.
+
+### 5. Only then make the claim
+
+Reference the evidence: *"Tests: 250/250 passed. PHPStan: level 8, 0
+errors on `app/Services/`."* — not *"everything looks good"*.
+
+## The end-of-work sequence (PHP projects)
+
+When all code changes are done and ready to report completion:
+
+1. **Targeted tests** — test(s) covering the changed code pass
+2. **Full test suite** — only after targeted pass is green
+3. **PHPStan** → **Rector --dry-run** → **ECS** → **PHPStan** (second pass
+   catches issues Rector / ECS introduced)
+4. Fix any output from steps 1–3 and restart the sequence
+5. Only then: claim completion or suggest `/commit`, push, or PR
+
+Do not run the full quality pipeline between intermediate edits — burns
+time and tokens. Use it once, at the end.
+
+See [`quality-tools`](../quality-tools/SKILL.md) for exact commands per
+tool.
+
+## Minimum evidence per task type
+
+| Task type | Required evidence |
+|---|---|
+| Code change (logic) | Targeted tests + PHPStan on changed scope |
+| New feature | Tests (new + suite) + PHPStan + smoke check (curl/UI) |
+| Bug fix | Regression test (RED → GREEN) + full suite |
+| Refactoring | Full suite + PHPStan + Rector dry-run |
+| Config / env change | Relevant command or service output (not just file diff) |
+| Migration | Migration run output + rollback dry-run + tests |
+| API endpoint | HTTP response body + status + content-type |
+| Frontend component | Rendered state (Playwright or manual) + unit tests |
+| Documentation only | No verification needed |
+
+**Never accept** as proof: "should work", "looks correct", "the logic
+is sound", "compiles" (unless compilation itself is the contract).
+
+## Output format
+
+When reporting completion to the user:
+
+1. **What was changed** — one line summary per changed file / component
+2. **Verification run** — exact command and its exit code
+3. **Result** — numeric breakdown (tests passed/failed/skipped, errors,
+   warnings)
+4. **Caveats** — anything the output flagged but you chose to accept
+5. **Next step** — e.g. "Ready for `/commit`" or "Awaiting review"
+
+## Gotchas
+
+* "No output" from a linter is not proof it ran — check exit code and
+  analyzed-file count.
+* Silencing a warning with `@phpstan-ignore-next-line` or `// @ts-expect-error`
+  without a reason code passes the linter but defers the real problem.
+* Running tests with `--stop-on-failure` then reporting "passed" — only
+  ran until the first failure; the green streak after is unexamined.
+* Cached static-analysis results (`--cache` directories) can report
+  clean after you broke something; clear the cache for large changes.
+* Running the test suite on the wrong branch (forgot to switch or
+  rebase) — verify `git status` and `git log -1` before the final gate.
+* A previously green PHPStan run in the same conversation is stale as
+  soon as any edit lands. Run it again.
+
+## Red flags — STOP and run the gate
+
+* About to write "done", "ready", "works", "passes" without a
+  command-output reference in the same message
+* About to suggest `/commit` / push / PR without a verification block
+* Relying on an earlier-in-conversation test run
+* Partial evidence (tests green, PHPStan not run — or vice versa)
+* "The failing test is unrelated, let me skip it" — verify first, then
+  decide
+* Reporting a green run by paraphrasing instead of quoting exit code
+  and counts
+
+## Do NOT
+
+* Do NOT claim completion without running the mapping command in this
+  message
+* Do NOT trust a summary written earlier in the conversation
+* Do NOT suppress warnings or skip tests to pass the gate
+* Do NOT report only the last line of output — read the whole thing
+* Do NOT run the full quality pipeline between intermediate edits —
+  run once at the end
+
+## When to hand over to another skill
+
+* Exact PHPStan / Rector / ECS commands → [`quality-tools`](../quality-tools/SKILL.md)
+* Running tests inside Docker → [`tests-execute`](../tests-execute/SKILL.md)
+* Writing the regression test the gate requires →
+  [`test-driven-development`](../test-driven-development/SKILL.md)
+* Diagnosing why the gate failed → [`systematic-debugging`](../systematic-debugging/SKILL.md)
+* Committing once the gate is green → [`git-workflow`](../git-workflow/SKILL.md)
+
+## Validation checklist
+
+Before sending a completion message:
+
+* [ ] Every claim maps to a command run in this turn
+* [ ] Exit code of each command is read and matches the claim
+* [ ] Output is quoted with numeric counts, not paraphrased
+* [ ] No warnings or skips are hidden
+* [ ] Targeted tests green → full suite green → quality pipeline clean
+* [ ] `git status` reflects only the intended change set

package/.agent-src/skills/websocket/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: websocket
+description: "Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'."
+source: package
+---
+
+# websocket
+
+## When to use
+
+Use when implementing real-time features — WebSockets, Broadcasting, or persistent connections.
+
+Do NOT use when:
+- REST API endpoints (use `api-design` skill)
+- Reverb server setup/deployment (use `laravel-reverb` skill)
+
+## Procedure: Create a broadcast event
+
+### Step 0: Inspect
+
+1. Check `config/broadcasting.php` for driver (Reverb, Pusher, Ably).
+2. Check existing broadcast events — match patterns.
+3. Check `routes/channels.php` for channel authorization.
+
+### Step 1: Create event class
+
+1. Implement `ShouldBroadcast`.
+2. Define `broadcastOn()` with appropriate channel type (public/private/presence).
+3. Define `broadcastAs()` for event name.
+4. Define `broadcastWith()` — small payload (IDs + changed fields only).
+
+### Step 2: Authorize channel
+
+Add authorization in `routes/channels.php` for private/presence channels.
+
+### Step 3: Client setup
+
+Use Laravel Echo to listen on the channel. Wire up reconnection with exponential backoff.
+
+## Conventions
+
+→ See guideline `php/websocket.md` for broadcasting setup, channel types, connection management, Echo.
+
+### Validate
+
+- Verify private/presence channels have authorization in `routes/channels.php`.
+- Confirm event implements `ShouldBroadcast` (or `ShouldBroadcastNow`).
+- Check that no sensitive data is broadcast on public channels.
+- Test client receives event — use browser console or Echo debug mode.
+
+## Output format
+
+1. Event class with broadcastOn() and channel definitions
+2. Client-side listener integration code
+
+## Gotcha
+
+- Connections are stateful — don't assume they persist after page navigation.
+- Always implement reconnection with exponential backoff.
+- Don't broadcast sensitive data on public channels — use private/presence.
+
+## Do NOT
+
+- Do NOT send entire model objects — select only needed fields.
+- Do NOT skip channel authorization for user-specific data.
+- Do NOT rely on WebSocket delivery — use acknowledgments for critical messages.
+
+## Auto-trigger keywords
+
+- WebSocket
+- real-time
+- broadcasting
+- Laravel Echo
+- channel authorization
+- ShouldBroadcast

package/.agent-src/templates/AGENTS.md

@@ -0,0 +1,146 @@
+# {{project_name}}
+
+<!--
+  AGENTS.md — entry point for AI coding agents working on this project.
+
+  This file was installed by `event4u/agent-config` as a starting template.
+  Fill in the placeholders below (or run `/copilot-agents-init` to do it
+  interactively) and then delete this HTML comment.
+
+  Keep it short. Detailed conventions belong in `.augment/` (read-only from
+  the shared package) or in `agents/overrides/` (project-specific).
+-->
+
+{{project_description}}
+
+## Agent Infrastructure
+
+| Layer | Location | Purpose |
+|---|---|---|
+| **Shared package** | `.augment/` | Skills, rules, commands, guidelines, templates — read-only |
+| **Project overrides** | `agents/overrides/` | Customizations of shared resources |
+| **Project docs** | `agents/` | Architecture, features, roadmaps, sessions, contexts |
+| **Agent settings** | `.agent-settings.yml` | Project-specific config consumed by skills (YAML) |
+
+### Key References
+
+| What | Where |
+|---|---|
+| Behavior rules (always active) | `.augment/rules/` |
+| Coding guidelines | `.augment/guidelines/` |
+| Skills (on-demand expertise) | `.augment/skills/` |
+| Commands (workflows) | `.augment/commands/` |
+| Copilot instructions | `.github/copilot-instructions.md` |
+
+### Recommended entry flow
+
+For most tickets — feature, bug fix, or refactor — start with
+[`/implement-ticket`](.augment/commands/implement-ticket.md). It drives the
+linear flow `refine → memory → analyze → plan → implement → test → verify →
+report` with block-on-ambiguity semantics and no auto-git. Persona comes from
+`.agent-settings.yml` (`roles.active_role`). Use `/commit` and `/create-pr`
+explicitly after the delivery report.
+
+### Multi-Agent Support
+
+| Tool | Rules | Skills | How |
+|---|---|---|---|
+| **Augment Code** | `.augment/rules/` | `.augment/skills/` | Native (source) |
+| **Claude Code** | `.claude/rules/` | `.claude/skills/` | Symlinks + Agent Skills standard |
+| **Cursor** | `.cursor/rules/` | — | Symlinks |
+| **Cline** | `.clinerules/` | — | Symlinks |
+| **Windsurf** | `.windsurfrules` | — | Concatenated file |
+| **Gemini CLI** | `GEMINI.md` | — | Symlink → AGENTS.md |
+
+Regenerate: `task generate-tools` · Clean: `task clean-tools`
+(Requires the `task` binary; see https://taskfile.dev if missing.)
+
+---
+
+## Tech Stack
+
+<!-- Replace with your actual stack. Examples:
+  - Framework: Laravel 11 (PHP ^8.2) / Next.js 15 / Rails 7 / Django 5
+  - Database: PostgreSQL / MySQL / MariaDB / SQLite
+  - Queue: Redis / RabbitMQ / SQS
+  - Testing: Pest / PHPUnit / Jest / Vitest / pytest
+  - Code style / linters: ECS / PHPStan / Ruff / ESLint
+-->
+
+- **Language:** {{primary_language}}
+- **Framework:** {{framework}}
+- **Database:** {{database}}
+- **Testing:** {{test_framework}}
+- **Code style:** {{code_style_tool}}
+
+---
+
+## Development Setup
+
+<!-- Replace with your project's actual setup commands. Examples:
+  - `make start` / `make console` / `make test`
+  - `docker compose up` / `docker compose exec app bash`
+  - `npm run dev` / `npm test`
+  - `php artisan serve` / `php artisan test`
+-->
+
+```bash
+{{dev_start_command}}
+{{dev_test_command}}
+```
+
+### Environment files
+
+| File | Purpose |
+|---|---|
+| `.env` | Main environment |
+| `.env.local` | Local overrides |
+| `.env.testing` | Testing environment |
+
+---
+
+## Project Structure
+
+<!-- Document your directory conventions:
+  - Where new features go
+  - Module/component boundaries
+  - Namespace conventions
+-->
+
+{{project_structure_notes}}
+
+---
+
+## Testing
+
+<!-- Document:
+  - Test framework and its quirks
+  - How to run all tests / targeted tests
+  - Test data strategy (seeders, factories, fixtures)
+  - Performance-critical tests or suites
+-->
+
+{{testing_notes}}
+
+---
+
+## Quality Tools
+
+<!-- Document:
+  - Which linters/formatters run
+  - Whether they auto-fix or report only
+  - CI enforcement level
+-->
+
+{{quality_tools_notes}}
+
+---
+
+## Additional Documentation
+
+| Document | Topic |
+|---|---|
+| `.github/copilot-instructions.md` | Coding standards for GitHub Copilot (self-contained) |
+| `agents/` | Project-specific architecture docs and roadmaps |
+| `.augment/contexts/` | Shared cross-cutting concepts from the package |
+| `.agent-settings.yml` | Project-specific agent configuration (YAML) |

package/.agent-src/templates/agent-settings.md

@@ -0,0 +1,256 @@
+# Agent Settings Template
+
+User-specific agent settings stored in `.agent-settings.yml` (project root,
+git-ignored). This file is **not committed** — each developer has their own
+settings.
+
+## File format
+
+**YAML**, with a single top-level scalar (`cost_profile`) plus one level of
+grouped sections (`personal`, `project`, `github`, `eloquent`, `pipelines`,
+`subagents`). Comments with `#`.
+
+Keep the format regular — 2-space indent, no tabs, no lists, one nesting
+level only. The installer's YAML handler is a restricted stdlib parser, not
+a full YAML engine. Run `/config-agent-settings` to normalize after manual
+edits.
+
+### Migration from the legacy `.agent-settings` (key=value)
+
+If a project still has the old flat `.agent-settings` file, the next run of
+`scripts/install` migrates it automatically:
+
+1. Reads `.agent-settings` (key=value)
+2. Maps each key into its new nested path (see Rename-Map below)
+3. Writes `.agent-settings.yml` (YAML with sections)
+4. Leaves a one-shot backup `.agent-settings.backup.key-value`
+5. Deletes the old `.agent-settings`
+
+The migration runs exactly once. On subsequent runs the YAML file already
+exists and is the source of truth.
+
+## Template
+
+This block defines the personal and project-level settings that
+`/config-agent-settings` (and `bin/install.php` via
+`config/agent-settings.template.yml`) writes to `.agent-settings.yml`.
+
+```yaml
+# Agent Settings
+# This file is git-ignored. Each developer has their own settings.
+# Run /config-agent-settings to create or update this file.
+
+# --- Cost profile ---
+#
+# Controls which agent surfaces are active. See `docs/customization.md` for
+# the authoritative description.
+#
+# minimal  = rules, skills, and commands only (zero extra surface, default)
+# balanced = + runtime dispatcher for skills that declare a shell command
+# full     = + tool adapters (GitHub / Jira, read-only, opt-in)
+# custom   = ignore profile — every matrix value must be set explicitly
+cost_profile: minimal
+
+# --- Personal preferences ---
+personal:
+  # IDE to use for opening files (code, phpstorm, cursor)
+  ide: ""
+
+  # Automatically open edited files in the IDE (true, false)
+  open_edited_files: false
+
+  # User's first name — used to address the user personally
+  user_name: ""
+
+  # rtk (Rust Token Killer) installed for output filtering (true, false)
+  # Agent will auto-detect and ask once, then store the result
+  rtk_installed: false
+
+  # Minimal output mode (true, false)
+  # true  = short bullet points during work, concise summary at the end
+  # false = verbose explanations and reasoning
+  minimal_output: true
+
+  # Play-by-play mode (true, false)
+  # true  = briefly share intermediate findings as you go
+  # false = silently investigate, only report the conclusion
+  play_by_play: false
+
+# --- Project / team preferences ---
+project:
+  # Prefix PR comment replies with a bot icon 🤖 (true, false)
+  pr_comment_bot_icon: false
+
+  # Path to the PR template file (relative to project root)
+  pr_template: .github/pull_request_template.md
+
+  # Target repository for universal improvement PRs (e.g. org/agent-config)
+  upstream_repo: ""
+
+  # Branch prefix for improvement PRs
+  improvement_pr_branch_prefix: "improve/agent-"
+
+# --- GitHub integration ---
+github:
+  # API method for replying to PR review comments
+  # replies_endpoint      = POST /pulls/comments/{id}/replies (preferred)
+  # create_review_comment = POST /pulls/{number}/reviews (fallback)
+  # auto                  = detect on first use and update this setting
+  pr_reply_method: create_review_comment
+
+# --- Eloquent (Laravel) ---
+eloquent:
+  # Model property access style
+  # getters_setters  = strict typed getters/setters, getAttribute() only inside model
+  # get_attribute    = use getAttribute()/setAttribute() everywhere
+  # magic_properties = use $model->column_name (Laravel default)
+  access_style: getters_setters
+
+# --- Optional pipelines ---
+pipelines:
+  # Skill improvement pipeline (true, false)
+  # true  = after meaningful tasks, propose learning capture and improvements
+  # false = silent, no post-task analysis
+  skill_improvement: false
+
+# --- Subagent orchestration ---
+subagents:
+  # Model for implementer subagents (empty = same tier as the session model)
+  implementer_model: ""
+
+  # Model for judge subagents
+  # (empty = one tier above implementer: opus if sonnet, sonnet if haiku)
+  judge_model: ""
+
+  # Maximum number of parallel subagent invocations (integer, default 3)
+  # Set to 1 to serialize. Hard cap enforced by runtime.
+  max_parallel: 3
+
+# --- Role modes (see guidelines/agent-infra/role-contracts.md) ---
+roles:
+  # Role the agent defaults to at the start of a session.
+  # Allowed: "" (no default), developer, reviewer, tester, po, incident, planner
+  default_role: ""
+
+  # Role currently active. Set by /mode <name>; cleared by /mode none.
+  # The rule `role-mode-adherence` (auto-triggered when non-empty)
+  # requires every closing output to match the mode's contract.
+  active_role: ""
+
+# --- Personas (developer-local override of team default lens) ---
+#
+# Personas are reusable review lenses (see .augment/personas/README.md).
+# The team default cast lives in `.agent-project-settings.yml` under
+# `personas.default`. This block lets a developer narrow or widen the
+# local cast without touching the team file. Ignored if the project
+# locks `personas.default` via `locked_keys`.
+personas:
+  # Override the effective default cast for THIS developer. Empty =
+  # inherit team default. Provide a full list (not a diff) to replace
+  # the team cast entirely for local runs.
+  override: []
+
+  # Drop specific persona ids from the default cast without replacing
+  # the whole list. Ignored personas stay invokable explicitly via
+  # `--personas=<id>`. Mirrors `.augmentignore` semantics.
+  ignore: []
+```
+
+## Settings Reference
+
+Personal and project-level settings (written by `/config-agent-settings` and
+`bin/install.php`). **Key paths use dot-notation** to denote nesting:
+`personal.user_name` lives under `personal:` in YAML.
+
+| Key path | Values | Default | Description |
+|---|---|---|---|
+| `cost_profile` | `minimal`, `balanced`, `full`, `custom` | `minimal` | Selects which agent surfaces are active. See [Cost profiles](#cost-profiles). |
+| `personal.ide` | `code`, `phpstorm`, `cursor` | _(empty)_ | CLI command to open files in the IDE |
+| `personal.open_edited_files` | `true`, `false` | `false` | Auto-open edited files in the IDE after edits |
+| `personal.user_name` | first name | _(empty)_ | User's first name. Agent asks on first interaction if empty, then addresses user by name. |
+| `personal.rtk_installed` | `true`, `false` | `false` | Whether rtk (Rust Token Killer) is installed. Agent auto-detects once and stores the result. |
+| `personal.minimal_output` | `true`, `false` | `true` | When `true`: short bullet points during work, concise summary at end. When `false`: verbose explanations. |
+| `personal.play_by_play` | `true`, `false` | `false` | When `true`: share intermediate findings during investigation. When `false`: work silently, report only the conclusion. |
+| `project.pr_comment_bot_icon` | `true`, `false` | `false` | Prefix PR comment replies with 🤖 to indicate bot-authored replies |
+| `project.pr_template` | file path | `.github/pull_request_template.md` | Path to PR template file. Read this instead of searching for it. |
+| `project.upstream_repo` | `org/repo` | _(empty)_ | Target repository for universal improvement PRs (e.g., `org/agent-config`). |
+| `project.improvement_pr_branch_prefix` | string | `improve/agent-` | Branch prefix for agent improvement PRs. |
+| `github.pr_reply_method` | `replies_endpoint`, `create_review_comment`, `auto` | `create_review_comment` | GitHub API method for replying to PR review comments. `auto` detects on first use. |
+| `eloquent.access_style` | `getters_setters`, `get_attribute`, `magic_properties` | `getters_setters` | How to access Eloquent model attributes. See `eloquent` skill for details. |
+| `pipelines.skill_improvement` | `true`, `false` | `false` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. |
+| `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
+| `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
+| `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
+| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../guidelines/agent-infra/role-contracts.md). |
+| `roles.active_role` | same as `default_role` | _(empty)_ | Role currently active; set by `/mode <name>`, cleared by `/mode none`. Enables the `role-mode-adherence` rule. |
+| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../guidelines/agent-infra/layered-settings.md). |
+| `personas.ignore` | list of persona ids | `[]` | Persona ids dropped from the default cast locally. Ignored personas stay invokable via `--personas=<id>`. |
+
+### Rename-Map (migration)
+
+Applied automatically when `scripts/install` finds a legacy `.agent-settings`
+(key=value) and writes the new `.agent-settings.yml`:
+
+| Legacy flat key | New YAML path |
+|---|---|
+| `cost_profile` | `cost_profile` |
+| `ide` | `personal.ide` |
+| `open_edited_files` | `personal.open_edited_files` |
+| `user_name` | `personal.user_name` |
+| `rtk_installed` | `personal.rtk_installed` |
+| `minimal_output` | `personal.minimal_output` |
+| `play_by_play` | `personal.play_by_play` |
+| `pr_comment_bot_icon` | `project.pr_comment_bot_icon` |
+| `pr_template` | `project.pr_template` |
+| `upstream_repo` | `project.upstream_repo` |
+| `improvement_pr_branch_prefix` | `project.improvement_pr_branch_prefix` |
+| `github_pr_reply_method` | `github.pr_reply_method` |
+| `eloquent_access_style` | `eloquent.access_style` |
+| `skill_improvement_pipeline` | `pipelines.skill_improvement` |
+| `subagent_implementer_model` | `subagents.implementer_model` |
+| `subagent_judge_model` | `subagents.judge_model` |
+| `subagent_max_parallel` | `subagents.max_parallel` |
+
+Unknown keys in the legacy file are preserved under a `_legacy:` section
+so nothing is silently dropped; the migration log points them out.
+
+## Cost profiles
+
+The `cost_profile` setting selects which agent surfaces are active. See
+`docs/customization.md` for the authoritative description.
+
+| Profile | Description |
+|---|---|
+| `minimal` | Rules, skills, and commands only. Zero extra surface. Default. |
+| `balanced` | + Runtime dispatcher for skills that declare a shell command. |
+| `full` | + Tool adapters (GitHub / Jira, read-only, opt-in). |
+| `custom` | Ignore profile — every matrix value must be set explicitly. |
+
+The only cross-profile toggle written to `.agent-settings.yml` today is
+`pipelines.skill_improvement`. Other per-feature toggles may be added in
+future releases; when they land, they ship with a live consumer in code
+and get documented here, not before.
+
+## Sync rules
+
+When new settings are added to this template:
+
+1. The `/config-agent-settings` command detects missing keys (dot-paths) in
+   the user's `.agent-settings.yml`.
+2. Missing keys are added with their **default value** from this template,
+   inside the correct section.
+3. Existing keys keep their **current value** — never overwritten.
+4. The **order** of keys follows this template — existing values are
+   reordered to match.
+5. Comments from the template are preserved in the output.
+
+## Adding new settings
+
+When adding a new setting:
+
+1. Add the key with its default value to the template block above, inside
+   the right section (or create a new section if it is a new domain).
+2. Add a row to the Settings Reference table using the full dot-path.
+3. Update the relevant skill or command that reads this setting.
+4. The next time `/config-agent-settings` runs, it will add the new key
+   automatically.

package/.agent-src/templates/agents/.gitattributes.fragment

@@ -0,0 +1,16 @@
+# Agent memory — append-only JSONL, union-merged.
+# Append this block to the consumer project's root .gitattributes.
+# See: agents/roadmaps/road-to-memory-merge-safety.md
+
+# Intake layer — agent-written, append-only. Union merge concats both
+# sides on conflict instead of failing. Reader deduplicates by id.
+agents/memory/intake/*.jsonl merge=union eol=lf
+
+# Curated memory — content-addressed drop-ins. One file per entry.
+# Normal merge is fine; filename collisions are content-identity.
+agents/memory/ownership/*.yml              text eol=lf
+agents/memory/historical-patterns/*.yml    text eol=lf
+agents/memory/domain-invariants/*.yml      text eol=lf
+agents/memory/architecture-decisions/*.yml text eol=lf
+agents/memory/incident-learnings/*.yml     text eol=lf
+agents/memory/product-rules/*.yml          text eol=lf