@event4u/agent-config 1.9.1 → 1.13.0

package/config/agent-settings.template.yml

@@ -1,8 +1,9 @@
 # Agent Settings
 # This file is generated by scripts/install.py from
 # config/agent-settings.template.yml. It holds personal and project-wide
-# preferences. Run /config-agent-settings to re-sync it against the
-# template at .augment/templates/agent-settings.md.
+# preferences. Run /onboard for first-run setup; for later edits, change
+# values here directly or ask the agent (it follows the merge rules in
+# .augment/guidelines/agent-infra/layered-settings.md).
 
 # --- Cost profile ---
 #
@@ -41,11 +42,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
 
@@ -71,12 +73,37 @@ 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.
+chat_history:
+  # Log chat events to disk (true, false)
+  enabled: true
+
+  # Logging granularity
+  #   per_turn  = one entry per user↔agent turn (lightest)
+  #   per_phase = one entry per workflow phase
+  #   per_tool  = one entry per tool call (most verbose)
+  frequency: __CHAT_HISTORY_FREQUENCY__
+
+  # Max file size in KB before overflow handling kicks in (integer)
+  max_size_kb: __CHAT_HISTORY_MAX_SIZE_KB__
+
+  # Overflow behavior
+  #   rotate   = drop oldest entries to stay under max_size_kb
+  #   compress = mark for summarization on the next agent turn
+  on_overflow: __CHAT_HISTORY_ON_OVERFLOW__
+
 # --- 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`. Flip to false here if you
+  # want a silent agent; `custom` profile ignores this default entirely.
+  skill_improvement: true
 
 # --- Subagent orchestration ---
 #
@@ -94,3 +121,15 @@ subagents:
   # Maximum number of parallel subagent invocations
   # Integer, default 3. Set to 1 to serialize. Hard cap enforced by runtime.
   max_parallel: 3
+
+# --- 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

package/config/gitignore-block.txt

@@ -0,0 +1,24 @@
+# Agent config — symlinked from vendor (auto-managed)
+.augment/skills/
+.augment/commands/
+.augment/guidelines/
+.augment/templates/
+.augment/contexts/
+.augment/scripts/
+.augment/README.md
+
+# Agent config — NOT ignored (real copies, may contain project overrides)
+# .augment/rules/
+
+# Agent config — CLI wrapper (auto-generated on every install)
+/agent-config
+
+# Agent config — personal settings (written by the installer)
+.agent-settings.yml
+.agent-settings
+.agent-settings.backup.key-value
+
+# Agent config — persistent chat history (crash recovery, never commit)
+.agent-chat-history
+.agent-chat-history.bak
+.agent-chat-history.*.bak

package/config/profiles/balanced.ini

@@ -8,3 +8,8 @@
 ; See docs/customization.md for the full profile description.
 
 cost_profile=balanced
+
+; Chat history (crash recovery) — balanced = phase-level traceability
+chat_history_frequency=per_phase
+chat_history_max_size_kb=256
+chat_history_on_overflow=rotate

package/config/profiles/full.ini

@@ -8,3 +8,8 @@
 ; profile description.
 
 cost_profile=full
+
+; Chat history (crash recovery) — full = tool-level traceability + summarize on overflow
+chat_history_frequency=per_tool
+chat_history_max_size_kb=512
+chat_history_on_overflow=compress

package/config/profiles/minimal.ini

@@ -8,3 +8,8 @@
 ; config/agent-settings.template.ini to produce the user's .agent-settings.
 
 cost_profile=minimal
+
+; Chat history (crash recovery) — minimal = lightest footprint
+chat_history_frequency=per_turn
+chat_history_max_size_kb=128
+chat_history_on_overflow=rotate

package/docs/customization.md

@@ -52,20 +52,46 @@ those sections.
 | `personal.play_by_play` | `false` | Share intermediate findings during analysis |
 | `personal.open_edited_files` | `false` | Open edited files in IDE |
 | `personal.ide` | *(empty)* | IDE for file opening (`cursor`, `code`, `phpstorm`) |
-| `pipelines.skill_improvement` | `false` | Enable post-task learning capture |
+| `pipelines.skill_improvement` | `true` | Post-task learning capture. Included in every profile except `custom`. |
+| `chat_history.enabled` | `true` | Persistent JSONL log at `.agent-chat-history` for crash recovery. |
+| `chat_history.frequency` | per profile | Logging granularity: `per_turn`, `per_phase`, or `per_tool` (see matrix below). |
+| `chat_history.max_size_kb` | per profile | Max file size before overflow handling (see matrix below). |
+| `chat_history.on_overflow` | per profile | `rotate` drops oldest, `compress` marks for summarization (see matrix below). |
+| `onboarding.onboarded` | `false` | Whether `/onboard` has run. The `onboarding-gate` rule prompts for `/onboard` while this is `false`. |
 
 ### Cost profiles
 
 | Profile | Description |
 |---|---|
-| `minimal` | Zero extra surface. Rules, skills, and commands only. |
-| `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. |
 
+All profiles except `custom` ship with `pipelines.skill_improvement: true`,
+so the agent captures learnings after meaningful tasks by default. Set it
+to `false` in `.agent-settings.yml` to silence post-task analysis without
+changing the profile.
+
 The authoritative matrix of all matrix-controlled settings lives in
 [`.agent-src.uncompressed/templates/agent-settings.md`](../.agent-src.uncompressed/templates/agent-settings.md).
 
+### Chat-history defaults per profile
+
+`scripts/install.py` fills these placeholders from
+[`config/profiles/*.ini`](../config/profiles) when it writes
+`.agent-settings.yml`. Edit the values afterwards if you want different
+behavior — the per-profile table is just the initial default.
+
+| Setting | `minimal` | `balanced` | `full` |
+|---|---|---|---|
+| `chat_history.enabled` | `true` | `true` | `true` |
+| `chat_history.frequency` | `per_turn` | `per_phase` | `per_tool` |
+| `chat_history.max_size_kb` | `128` | `256` | `512` |
+| `chat_history.on_overflow` | `rotate` | `rotate` | `compress` |
+
+`custom` ignores these defaults — set every value explicitly.
+
 ---
 
 ## Project documentation

package/docs/getting-started.md

@@ -19,11 +19,29 @@ runs a bash payload sync and a Python bridge generator (Python 3 is
 recommended; without it the payload sync still runs). No Task or Make
 required for end users.
 
+## Project CLI — `./agent-config`
+
+The installer writes `./agent-config` into your project root (gitignored)
+so you can run a few package scripts without installing `go-task`,
+`make`, or other build tools:
+
+```bash
+./agent-config mcp:render          # sync MCP server config into .cursor/ and .windsurf/
+./agent-config roadmap:progress    # regenerate agents/roadmaps-progress.md
+./agent-config hooks:install       # install pre-commit roadmap-progress hook (opt-in)
+./agent-config first-run           # guided setup
+./agent-config help                # full command list
+```
+
+The wrapper is regenerated on every `npm install` / `composer install`
+and delegates to the copy under `node_modules/@event4u/agent-config/`
+or `vendor/event4u/agent-config/`.
+
 ## First Run
 
 Open your agent and try the 3 tests below. That's it — no additional tools needed.
 
-**Optional:** For a guided walkthrough, run `task first-run` (requires [Task](https://taskfile.dev/)).
+**Optional:** For a guided walkthrough, run `./agent-config first-run`.
 
 ---
 
@@ -81,7 +99,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 44 rules. No configuration needed.
+This is enforced automatically by 46 rules. No configuration needed.
 
 ---
 
@@ -115,8 +133,40 @@ Your agent now understands slash commands:
 | `/create-pr` | Create PR with Jira-linked description |
 | `/fix-ci` | Fetch and fix GitHub Actions failures |
 | `/quality-fix` | Run and fix all quality checks |
+| `/chat-history` | Inspect the persistent chat-history log |
+| `/chat-history-resume` | Recover context after a crashed or switched session |
+| `/chat-history-clear` | Wipe the chat-history log (with confirmation) |
+
+→ [Browse all 73 commands](../.agent-src/commands/)
+
+---
+
+## Crash recovery — `.agent-chat-history`
+
+When `chat_history.enabled: true` in `.agent-settings.yml` (on by default
+for every profile), the agent keeps a JSONL log of your conversation in
+`.agent-chat-history` at the project root. The file is git-ignored and
+rotates at the size configured in the profile (`128 KB` on `minimal`,
+`256 KB` on `balanced`, `512 KB` on `full`).
+
+When a chat opens and finds an existing log, the agent runs a
+4-state ownership check and chooses the right flow:
+
+- **match** — this chat already owns the file. Append silently.
+- **foreign** — a different session's file. You get 3 options:
+  Resume (adopt), New start (archive + init), Ignore (skip logging).
+- **returning** — this chat once owned the file, but another session
+  took over in between. You get 3 options: Merge (your history in front
+  of the foreign entries), Replace (wipe foreign entries, keep yours
+  only), Continue (just leave the file and append from now on).
+- **missing** — no file yet. Init and proceed.
+
+Run `/chat-history-resume` to walk through the prompts explicitly, or
+let the agent ask on the first turn of a new chat. All merge/replace/
+resume paths read the on-disk entries into context before any write.
 
-→ [Browse all 67 commands](../.agent-src/commands/)
+See the [`chat-history` rule](../.agent-src/rules/chat-history.md) and
+[`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
 
 ---
 

package/docs/mcp.md

@@ -48,13 +48,24 @@ values literal, or resolve them from the environment.
 
 ## Usage
 
+**Consumer projects** — use the `./agent-config` CLI installed into the
+project root:
+
+```bash
+./agent-config mcp:render                    # write in-project targets
+./agent-config mcp:render --claude-desktop   # also write user-scope Claude Desktop
+./agent-config mcp:check                     # dry-run; exit 1 if targets are stale
+```
+
+**Package maintainers** — the same commands are available through Taskfile:
+
 ```bash
-task mcp:render                        # write in-project targets
-task mcp:render -- --claude-desktop    # also write user-scope Claude Desktop
-task mcp:check                         # dry-run; exit 1 if targets are stale
+task mcp:render
+task mcp:render -- --claude-desktop
+task mcp:check
 ```
 
-Or invoke the script directly:
+Or invoke the script directly (maintainer workflow, inside the package repo):
 
 ```bash
 python3 scripts/mcp_render.py [--source PATH] [--claude-desktop] [--check]

package/package.json

@@ -1,9 +1,17 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.9.1",
-    "description": "Shared agent configuration — skills, rules, commands, guidelines, and templates for AI coding tools",
+    "version": "1.13.0",
+    "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/event4u-app/agent-config.git"
+    },
+    "bugs": {
+        "url": "https://github.com/event4u-app/agent-config/issues"
+    },
+    "homepage": "https://github.com/event4u-app/agent-config#readme",
     "files": [
         ".agent-src/",
         ".augment-plugin/",
@@ -21,11 +29,22 @@
         "composer.json",
         "llms.txt"
     ],
+    "bin": {
+        "agent-config": "scripts/agent-config"
+    },
     "scripts": {
         "postinstall": "bash scripts/postinstall.sh"
     },
     "publishConfig": {
         "access": "public",
         "provenance": true
+    },
+    "peerDependencies": {
+        "@event4u/agent-memory": "^1.1.0"
+    },
+    "peerDependenciesMeta": {
+        "@event4u/agent-memory": {
+            "optional": true
+        }
     }
 }

package/scripts/agent-config

@@ -0,0 +1,230 @@
+#!/usr/bin/env bash
+# agent-config — consumer-facing CLI for the event4u/agent-config package.
+#
+# This is the MASTER entrypoint shipped inside the package
+# (node_modules/@event4u/agent-config/scripts/agent-config or
+# vendor/event4u/agent-config/scripts/agent-config). A thin wrapper at
+# the consumer's repo root (`./agent-config`) delegates here.
+#
+# Commands are strictly consumer-facing. Maintainer workflows stay in
+# Taskfile.yml and are NOT exposed here.
+#
+# Invariants:
+#   * CWD on entry is the consumer's repo root — we keep it that way
+#     so underlying scripts resolve paths correctly.
+#   * PACKAGE_ROOT is derived from this script's location, used only to
+#     locate the package-internal Python scripts (mcp_render.py, …).
+#   * Unknown arguments are forwarded verbatim to the underlying script.
+
+set -euo pipefail
+
+# Resolve symlinks in BASH_SOURCE so PACKAGE_ROOT points at the real
+# package directory even when invoked via a symlink (global npm install,
+# vendor/bin symlink, user-placed symlink on PATH, …).
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+PACKAGE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CONSUMER_ROOT="$(pwd)"
+
+VERSION_FILE="$PACKAGE_ROOT/package.json"
+
+usage() {
+  cat <<'EOF'
+agent-config — event4u/agent-config CLI
+
+Usage:
+  ./agent-config <command> [options]
+
+Commands:
+  mcp:render                 Render mcp.json → .cursor/mcp.json, .windsurf/mcp.json
+                             (pass --claude-desktop to also write user-scope config)
+  mcp:check                  Dry-run mcp:render; exit non-zero if targets are stale
+  roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
+  roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
+  hooks:install              Install the pre-commit roadmap-progress hook
+                             (use --print to dump it, --force to overwrite an existing hook)
+  first-run                  Guided first-run setup — cost profile, settings, tooling
+  help                       Show this help
+  --version, -V              Print package version
+
+Examples:
+  ./agent-config mcp:render
+  ./agent-config mcp:render --claude-desktop
+  ./agent-config mcp:check
+  ./agent-config roadmap:progress
+  ./agent-config hooks:install
+  ./agent-config first-run
+
+All commands operate on the CURRENT DIRECTORY (your project root).
+The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
+EOF
+}
+
+print_version() {
+  if [[ -f "$VERSION_FILE" ]] && command -v python3 >/dev/null 2>&1; then
+    python3 -c "import json; print(json.load(open('$VERSION_FILE'))['version'])"
+  else
+    echo "unknown"
+  fi
+}
+
+require_python3() {
+  if ! command -v python3 >/dev/null 2>&1; then
+    echo "❌  agent-config: python3 not found on PATH" >&2
+    echo "    Install Python 3.10+ and retry." >&2
+    exit 127
+  fi
+}
+
+# Locate a script. First argument is relative to PACKAGE_ROOT, second is
+# an optional fallback relative to CONSUMER_ROOT (for scripts that ship
+# to the consumer via .augment/, e.g. update_roadmap_progress.py).
+resolve_script() {
+  local pkg_rel="$1"
+  local consumer_rel="${2-}"
+  local pkg_abs="$PACKAGE_ROOT/$pkg_rel"
+  if [[ -f "$pkg_abs" ]]; then
+    printf '%s' "$pkg_abs"
+    return 0
+  fi
+  if [[ -n "$consumer_rel" && -f "$CONSUMER_ROOT/$consumer_rel" ]]; then
+    printf '%s' "$CONSUMER_ROOT/$consumer_rel"
+    return 0
+  fi
+  echo "❌  agent-config: script not found: $pkg_rel" >&2
+  [[ -n "$consumer_rel" ]] && echo "    (also tried: $consumer_rel in $CONSUMER_ROOT)" >&2
+  return 1
+}
+
+cmd_mcp_render() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/mcp_render.py")"
+  exec python3 "$script" "$@"
+}
+
+cmd_mcp_check() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/mcp_render.py")"
+  exec python3 "$script" --check "$@"
+}
+
+cmd_roadmap_progress() {
+  require_python3
+  local script
+  script="$(resolve_script ".agent-src/scripts/update_roadmap_progress.py" ".augment/scripts/update_roadmap_progress.py")"
+  exec python3 "$script" "$@"
+}
+
+cmd_roadmap_progress_check() {
+  require_python3
+  local script
+  script="$(resolve_script ".agent-src/scripts/update_roadmap_progress.py" ".augment/scripts/update_roadmap_progress.py")"
+  exec python3 "$script" --check "$@"
+}
+
+cmd_first_run() {
+  local script
+  script="$(resolve_script "scripts/first-run.sh")"
+  exec bash "$script" "$@"
+}
+
+cmd_hooks_install() {
+  local force=false
+  local print_only=false
+  for arg in "$@"; do
+    case "$arg" in
+      --force)   force=true ;;
+      --print)   print_only=true ;;
+      -h|--help)
+        cat <<'HELP'
+agent-config hooks:install — install the pre-commit roadmap-progress hook.
+
+Usage:
+  ./agent-config hooks:install [--force] [--print]
+
+Without flags: copies the hook to .git/hooks/pre-commit. Refuses to
+overwrite an existing pre-commit hook unless --force is given (the
+existing hook may already chain other tooling).
+
+  --print   dump the hook script to stdout (for manual chaining into an
+            existing pre-commit script, husky, lefthook, etc.)
+  --force   overwrite an existing .git/hooks/pre-commit (DESTRUCTIVE)
+HELP
+        return 0 ;;
+      *)
+        echo "❌  hooks:install: unknown argument: $arg" >&2
+        echo "    Run \`./agent-config hooks:install --help\` for usage." >&2
+        return 2 ;;
+    esac
+  done
+
+  local hook_src
+  hook_src="$(resolve_script ".agent-src/templates/hooks/pre-commit-roadmap-progress" ".augment/templates/hooks/pre-commit-roadmap-progress")" || return 1
+
+  if $print_only; then
+    cat "$hook_src"
+    return 0
+  fi
+
+  local git_dir
+  git_dir="$(git -C "$CONSUMER_ROOT" rev-parse --git-dir 2>/dev/null || true)"
+  if [[ -z "$git_dir" ]]; then
+    echo "❌  hooks:install: $CONSUMER_ROOT is not a git repository." >&2
+    return 1
+  fi
+  # Resolve relative git-dir paths (worktrees, submodules) against CONSUMER_ROOT.
+  [[ "$git_dir" != /* ]] && git_dir="$CONSUMER_ROOT/$git_dir"
+
+  local hook_dir="$git_dir/hooks"
+  local target="$hook_dir/pre-commit"
+  mkdir -p "$hook_dir"
+
+  if [[ -f "$target" ]] && ! $force; then
+    if grep -q "pre-commit-roadmap-progress" "$target" 2>/dev/null; then
+      echo "✅  hooks:install: already installed at $target"
+      return 0
+    fi
+    echo "⚠️   hooks:install: $target already exists and looks unrelated." >&2
+    echo "    Options:" >&2
+    echo "      1. Inspect it and append the snippet manually:" >&2
+    echo "         ./agent-config hooks:install --print >> $target" >&2
+    echo "      2. Replace it (destructive):" >&2
+    echo "         ./agent-config hooks:install --force" >&2
+    return 1
+  fi
+
+  cp "$hook_src" "$target"
+  chmod +x "$target"
+  echo "✅  hooks:install: pre-commit hook installed at $target"
+  echo "    To uninstall: rm $target"
+}
+
+main() {
+  local cmd="${1-}"
+  [[ $# -gt 0 ]] && shift || true
+
+  case "$cmd" in
+    mcp:render)              cmd_mcp_render "$@" ;;
+    mcp:check)               cmd_mcp_check "$@" ;;
+    roadmap:progress)        cmd_roadmap_progress "$@" ;;
+    roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
+    hooks:install)           cmd_hooks_install "$@" ;;
+    first-run)               cmd_first_run "$@" ;;
+    help|--help|-h|"")        usage ;;
+    --version|-V)            print_version ;;
+    *)
+      echo "❌  agent-config: unknown command: $cmd" >&2
+      echo "    Run \`./agent-config help\` for the command list." >&2
+      exit 2
+      ;;
+  esac
+}
+
+main "$@"