@event4u/agent-config 1.9.1 → 1.13.0

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

@@ -12,8 +12,9 @@ grouped sections (`personal`, `project`, `github`, `eloquent`, `pipelines`,
 
 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.
+a full YAML engine. Ask the agent to normalize after manual edits — it
+follows the merge rules in
+[`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ### Migration from the legacy `.agent-settings` (key=value)
 
@@ -32,13 +33,15 @@ 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`.
+`scripts/install.py` (via `config/agent-settings.template.yml`)
+writes to `.agent-settings.yml` on first install. Subsequent edits are
+made by the user directly or by the agent on request, following the
+[section-aware merge rules](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ```yaml
 # Agent Settings
 # This file is git-ignored. Each developer has their own settings.
-# Run /config-agent-settings to create or update this file.
+# Run scripts/install to create this file, then /onboard for first-run setup.
 
 # --- Cost profile ---
 #
@@ -60,10 +63,11 @@ personal:
   open_edited_files: false
 
   # User's first name — used to address the user personally
+  # Captured by /onboard on first run.
   user_name: ""
 
   # rtk (Rust Token Killer) installed for output filtering (true, false)
-  # Agent will auto-detect and ask once, then store the result
+  # Detected and set by /onboard on first run.
   rtk_installed: false
 
   # Minimal output mode (true, false)
@@ -76,11 +80,12 @@ personal:
   # 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)
+  # Personal preference — each developer decides for themselves.
   pr_comment_bot_icon: false
 
+# --- Project / team preferences ---
+project:
   # Path to the PR template file (relative to project root)
   pr_template: .github/pull_request_template.md
 
@@ -106,12 +111,34 @@ eloquent:
   # magic_properties = use $model->column_name (Laravel default)
   access_style: getters_setters
 
+# --- Chat history (crash recovery) ---
+#
+# Persistent JSONL log at .agent-chat-history (project root, git-ignored).
+# Keeps a durable record of the conversation so a crashed or switched
+# agent session can be resumed. See scripts/chat_history.py for the API.
+#
+# Defaults below are placeholders — scripts/install.py substitutes them
+# per cost_profile (see config/profiles/*.ini).
+chat_history:
+  # Log chat events to disk (true, false)
+  enabled: true
+
+  # Logging granularity: per_turn | per_phase | per_tool
+  frequency: per_phase
+
+  # Max file size in KB before overflow handling kicks in
+  max_size_kb: 256
+
+  # Overflow behavior: rotate (drop oldest) | compress (summarize)
+  on_overflow: rotate
+
 # --- Optional pipelines ---
 pipelines:
   # Skill improvement pipeline (true, false)
-  # true  = after meaningful tasks, propose learning capture and improvements
+  # true  = after meaningful tasks, propose learning capture and improvements (default)
   # false = silent, no post-task analysis
-  skill_improvement: false
+  # Included by every cost_profile except `custom`.
+  skill_improvement: true
 
 # --- Subagent orchestration ---
 subagents:
@@ -154,30 +181,48 @@ personas:
   # the whole list. Ignored personas stay invokable explicitly via
   # `--personas=<id>`. Mirrors `.augmentignore` semantics.
   ignore: []
+
+# --- Onboarding ---
+#
+# Tracks whether the initial setup flow (/onboard) has been completed
+# for this developer on this project. When false, the onboarding-gate
+# rule prompts the user to run /onboard before starting normal work.
+# Missing entirely = legacy project (treated as onboarded).
+onboarding:
+  # Has the developer completed /onboard? (true, false)
+  # Set to true automatically by /onboard at the end. Flip to false
+  # if you want to re-run the flow.
+  onboarded: false
 ```
 
 ## 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.
+Personal and project-level settings (initial file written by
+`scripts/install.py`, edits follow the merge rules in
+[`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
+**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.user_name` | first name | _(empty)_ | User's first name, used to address the user personally. Captured by `/onboard`. |
+| `personal.rtk_installed` | `true`, `false` | `false` | Whether rtk (Rust Token Killer) is installed. Detected and set by `/onboard`. |
 | `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 |
+| `personal.pr_comment_bot_icon` | `true`, `false` | `false` | Prefix PR comment replies with 🤖 to indicate bot-authored replies. Personal preference — each developer decides. |
 | `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. |
+| `chat_history.enabled` | `true`, `false` | `true` | Persist chat events to `.agent-chat-history` (JSONL) for crash recovery. |
+| `chat_history.frequency` | `per_turn`, `per_phase`, `per_tool` | per profile | Logging granularity. Defaults: `minimal`→`per_turn`, `balanced`→`per_phase`, `full`→`per_tool`. |
+| `chat_history.max_size_kb` | integer | per profile | Max file size before overflow handling. Defaults: `minimal`→`128`, `balanced`→`256`, `full`→`512`. |
+| `chat_history.on_overflow` | `rotate`, `compress` | per profile | On overflow: `rotate` drops oldest entries; `compress` marks the file for summarization on the next turn. Defaults: `minimal`/`balanced`→`rotate`, `full`→`compress`. |
+| `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
 | `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. |
@@ -185,6 +230,7 @@ Personal and project-level settings (written by `/config-agent-settings` and
 | `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>`. |
+| `onboarding.onboarded` | `true`, `false` | `false` | Whether `/onboard` has run on this project. The `onboarding-gate` rule prompts for `/onboard` when this is `false`. Missing entirely = legacy project, treated as onboarded. |
 
 ### Rename-Map (migration)
 
@@ -200,7 +246,7 @@ Applied automatically when `scripts/install` finds a legacy `.agent-settings`
 | `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_comment_bot_icon` | `personal.pr_comment_bot_icon` |
 | `pr_template` | `project.pr_template` |
 | `upstream_repo` | `project.upstream_repo` |
 | `improvement_pr_branch_prefix` | `project.improvement_pr_branch_prefix` |
@@ -221,28 +267,34 @@ The `cost_profile` setting selects which agent surfaces are active. See
 
 | 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). |
+| `minimal` | Rules, skills, and commands only. **Includes the learning loop.** Default. |
+| `balanced` | `minimal` + Runtime dispatcher for skills that declare a shell command. |
+| `full` | `balanced` + 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.
+**Learning loop:** `pipelines.skill_improvement` is `true` by default and is
+included in every profile except `custom`. It triggers post-task learning
+capture via the `skill-improvement-trigger` rule. Flip to `false` in the
+settings file if you want a silent agent without touching the profile.
+
+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:
+When new settings are added to this template, the
+[section-aware merge rules](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+govern the update:
 
-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,
+1. 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
+2. Existing keys keep their **current value** — never overwritten.
+3. The **order** of keys follows this template — existing values are
    reordered to match.
-5. Comments from the template are preserved in the output.
+4. Comments from the template are preserved in the output.
+
+Re-run `scripts/install` to pull in template drift, or ask the agent to
+update a specific key — it walks the same rules.
 
 ## Adding new settings
 
@@ -252,5 +304,5 @@ When adding a new setting:
    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.
+4. Re-run `scripts/install` (or ask the agent to sync) to pull the new
+   key into the user's file.

package/.agent-src/templates/github-workflows/roadmap-progress-check.yml

@@ -0,0 +1,63 @@
+# Roadmap Progress Check — template shipped by agent-config
+#
+# Copy this file to `.github/workflows/roadmap-progress-check.yml` in the
+# consumer project. It fails CI when `agents/roadmaps-progress.md` is
+# stale relative to the source roadmaps under `agents/roadmaps/`.
+#
+# This is the last-line defence behind the `roadmap-progress-sync` rule
+# and the optional pre-commit hook (see `./agent-config hooks:install`).
+# A green check here proves the dashboard reflects reality on every PR
+# that touches roadmaps.
+#
+# Prerequisites:
+#   - `.augment/scripts/update_roadmap_progress.py` installed by
+#     `task install` (or `./agent-config install`).
+#   - At least one file exists under `agents/roadmaps/` — absence
+#     short-circuits the check with a passing exit (consumer projects
+#     that haven't adopted roadmaps stay green).
+#
+# This workflow is intentionally narrow: it only runs when relevant
+# files change, so it adds zero overhead to unrelated PRs.
+
+name: Roadmap Progress Check
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "agents/roadmaps/**"
+      - "agents/roadmaps-progress.md"
+      - ".augment/scripts/update_roadmap_progress.py"
+  pull_request:
+    paths:
+      - "agents/roadmaps/**"
+      - "agents/roadmaps-progress.md"
+      - ".augment/scripts/update_roadmap_progress.py"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Verify roadmaps-progress.md is fresh
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Run roadmap progress check
+        run: python3 .augment/scripts/update_roadmap_progress.py --check
+
+      - name: Remediation hint on failure
+        if: failure()
+        run: |
+          echo "::error::roadmaps-progress.md is stale."
+          echo "Regenerate locally with one of:"
+          echo "  ./agent-config roadmap:progress"
+          echo "  task roadmap-progress"
+          echo "  python3 .augment/scripts/update_roadmap_progress.py"
+          echo "Then commit and push the updated agents/roadmaps-progress.md."

package/.agent-src/templates/hooks/pre-commit-roadmap-progress

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Pre-commit hook: roadmap progress dashboard sync (event4u/agent-config)
+#
+# Installed by `./agent-config hooks:install`. Aborts the commit if
+# `agents/roadmaps-progress.md` is out of date relative to staged
+# changes under `agents/roadmaps/`. Exits silently when no roadmap
+# files are staged — zero overhead on unrelated commits.
+#
+# To run manually:
+#   ./agent-config roadmap:progress-check
+#
+# To uninstall:
+#   rm .git/hooks/pre-commit
+set -e
+
+# Only act on commits that touch roadmap content.
+staged="$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)"
+case "$staged" in
+  *agents/roadmaps/*.md*|*agents/roadmaps-progress.md*|*.augment/scripts/update_roadmap_progress.py*)
+    : ;;
+  *)
+    exit 0 ;;
+esac
+
+# Resolve the script — prefer the consumer-shipped path, fall back to
+# the source-of-truth copy when run from inside the package itself.
+script=""
+for cand in \
+  ".augment/scripts/update_roadmap_progress.py" \
+  ".agent-src/scripts/update_roadmap_progress.py" \
+  ".agent-src.uncompressed/scripts/update_roadmap_progress.py"; do
+  if [ -f "$cand" ]; then
+    script="$cand"
+    break
+  fi
+done
+
+if [ -z "$script" ]; then
+  echo "⚠️  pre-commit-roadmap-progress: update_roadmap_progress.py not found." >&2
+  echo "    Run \`task install\` (or \`./agent-config install\`) and retry." >&2
+  echo "    Skipping check — letting commit through." >&2
+  exit 0
+fi
+
+if ! python3 "$script" --check >/dev/null 2>&1; then
+  echo "❌  agents/roadmaps-progress.md is stale relative to your staged changes." >&2
+  echo "" >&2
+  echo "    Regenerate the dashboard with one of:" >&2
+  echo "      ./agent-config roadmap:progress" >&2
+  echo "      task roadmap-progress" >&2
+  echo "      python3 $script" >&2
+  echo "" >&2
+  echo "    Then \`git add agents/roadmaps-progress.md\` and retry the commit." >&2
+  echo "" >&2
+  echo "    To bypass once (NOT recommended):" >&2
+  echo "      git commit --no-verify" >&2
+  exit 1
+fi
+
+exit 0