@event4u/agent-config 1.9.1 → 1.12.0

package/CONTRIBUTING.md

@@ -118,51 +118,100 @@ the policy is interpreted as follows:
 | **Minor** (x.X.0) | New skills, rules, commands, or guidelines. New tool support. New installer flags. New `.agent-settings.yml` keys with safe defaults. |
 | **Patch** (x.x.X) | Wording fixes and improvements in existing skills, linter fixes, CI changes, documentation updates, internal refactors with no user-visible effect. |
 
-Release notes live in [`CHANGELOG.md`](CHANGELOG.md) and are generated
-automatically by [release-please](https://github.com/googleapis/release-please)
-from [Conventional Commits](#commit-conventions). Contributors do **not** edit
-the changelog by hand; writing clean commit subjects is how notes are authored.
+Release notes live in [`CHANGELOG.md`](CHANGELOG.md) and are generated by
+`scripts/release.py` from [Conventional Commits](#commit-conventions) since
+the last tag. Contributors do **not** edit the changelog by hand; writing
+clean commit subjects is how notes are authored.
 
 ### Release process
 
-Releases are fully automated by the
-[release-please workflow](.github/workflows/release-please.yml):
-
-1. Every push to `main` triggers release-please. It scans Conventional Commits
-   since the last tag and opens (or updates) a **Release PR** — a single PR
-   that bumps `package.json`, `.claude-plugin/marketplace.json`, and
-   `CHANGELOG.md` in one atomic commit.
-2. Review the Release PR when you're ready to ship. Merging it makes
-   release-please push the matching git tag and create the GitHub Release.
-3. On the same workflow run, the `publish-npm` job takes over: it checks
-   out the tagged commit, verifies `package.json.version == tag`, and runs
-   `npm publish` against https://registry.npmjs.org with
-   [npm provenance](https://docs.npmjs.com/generating-provenance-statements)
-   so each tarball is cryptographically linked to the GitHub Actions run that
-   built it.
-4. The [Release Guard workflow](.github/workflows/release-guard.yml) runs on
-   the pushed tag and fails loudly if `package.json.version` or
-   `.claude-plugin/marketplace.json` disagree with the tag — an independent
-   cross-check that stays in place even with release-please driving the flow.
-
-Bump size is derived from commit types:
-`feat:` → minor, `fix:` → patch, `feat!:` / `fix!:` / `BREAKING CHANGE:` → major.
-Commits like `chore:`, `docs:`, `test:`, `ci:`, `refactor:` do not bump the
-version on their own and ride along in the next Release PR.
-
-#### Required repository secrets
-
-| Secret | Purpose |
-|---|---|
-| `NPM_TOKEN` | Granular Access Token for `@event4u/agent-config` with read-write scope. Used by the `publish-npm` job. Create in [npm → Access Tokens](https://www.npmjs.com/settings/event4u/tokens) and store under `Settings → Secrets and variables → Actions`. |
+Releases are driven by a single command that owns the entire pipeline from
+version bump to npm publish:
+
+```bash
+task release                       # auto-detect bump from commits (default)
+task release:major                 # force a major bump
+task release:minor                 # force a minor bump
+task release:patch                 # force a patch bump
+task release:version -- 2.0.0      # pin an exact X.Y.Z target
+task release -- --dry-run          # preview only, no git/gh mutations
+```
+
+All five tasks wrap [`scripts/release.py`](scripts/release.py). `task
+release` auto-detects the bump level from Conventional Commits since the
+last tag (`feat!:` / `BREAKING CHANGE:` → major, `feat:` → minor,
+`fix:` / `perf:` → patch; no-signal history falls through to patch).
+The `release:major` / `:minor` / `:patch` variants force a specific bump
+level when the commit history disagrees with what you actually want to
+ship, and `release:version` pins an exact target (e.g. to jump past a
+yanked version). All variants share the same pipeline:
+
+1. **Preflight** — asserts the invocation is on `main` with a clean tree,
+   in sync with `origin/main`, that `gh` is authenticated, and that the
+   target tag does not already exist.
+2. **Plan + preview** — computes the target version, parses Conventional
+   Commits since the last tag, renders the CHANGELOG section, and prints
+   everything for review.
+3. **Confirm** — a single `y/N` prompt (skippable with `--yes`).
+4. **Branch + bump** — creates `release/X.Y.Z`, bumps `package.json` and
+   `.claude-plugin/marketplace.json`, prepends the rendered section to
+   `CHANGELOG.md`.
+5. **Commit + push + PR** — commits as `release: X.Y.Z`, pushes the
+   branch, opens the release PR via `gh pr create`.
+6. **Wait for checks** — `gh pr checks --watch --required` (skippable with
+   `--no-wait`).
+7. **Merge** — `gh pr merge --merge --delete-branch` (merge-commit
+   strategy, required for the tag to land on a main commit).
+8. **Tag main** — fast-forwards `main`, tags the merge commit, pushes the
+   tag. This is what triggers [`publish-npm.yml`](.github/workflows/publish-npm.yml):
+   the workflow listens on bare-numeric tag pushes, verifies the tag
+   matches `package.json.version`, and runs `npm publish` against
+   https://registry.npmjs.org with
+   [npm provenance](https://docs.npmjs.com/generating-provenance-statements).
+9. **GitHub Release** — `gh release create X.Y.Z` with the rendered
+   changelog body as notes.
+
+The override tasks (`release:major` / `:minor` / `:patch`) exist for the
+cases where commit signal alone doesn't capture the release intent —
+e.g. shipping a major without a formal breaking-change commit, or
+downgrading a `feat:` release to patch because the feature was
+effectively internal. The preview always shows which level was chosen
+and what the rendered CHANGELOG looks like, so there's no surprise at
+merge time.
+
+[`release-guard.yml`](.github/workflows/release-guard.yml) still runs on
+every tag push and fails loudly if `package.json.version` or
+`.claude-plugin/marketplace.json.metadata.version` disagree with the tag —
+an independent cross-check that stays in place regardless of how the tag
+was produced.
+
+#### Previewing without side effects
+
+```bash
+task release -- --dry-run
+```
+
+This runs the preflight + plan and prints the preview, but stops before
+creating the branch. Use it to sanity-check the rendered CHANGELOG or to
+see which bump level matches your commits.
+
+#### npm authentication
+
+`publish-npm.yml` authenticates to npm via
+[OIDC Trusted Publishing](https://docs.npmjs.com/trusted-publishers) — no
+`NPM_TOKEN` secret is required. The trust link is configured on the package
+settings page on npmjs.com and bound to:
 
-#### Fallback: manual bump
+- Repository: `event4u-app/agent-config`
+- Workflow filename: `publish-npm.yml`
 
-`task release:bump -- X.Y.Z` is kept as an emergency fallback for the rare
-case where release-please is unavailable (workflow disabled, GitHub outage,
-hotfix on a branch other than `main`). In normal operation, do not use it —
-let the Release PR drive every version change. A manual bump does **not**
-publish to npm automatically; run `npm publish` locally after tagging.
+The workflow declares `id-token: write` so GitHub Actions can mint a
+short-lived OIDC ID token with claims about the run (repo, workflow, ref).
+`npm publish` sends that token to the registry, which verifies the claims
+against the trust link and — on match — authorizes the publish and records
+a provenance attestation. If the workflow file is renamed or moved, the
+trust link on npm must be updated accordingly or the publish step will
+fail.
 
 ## License of contributions
 

package/README.md

@@ -5,7 +5,7 @@ Teach your AI agents Laravel, PHP, testing, Git workflows, and **120+ more skill
 > Your agent learns to write Laravel code, run tests, create PRs, fix CI — and follows your team's coding standards while doing it.
 
 <p align="center">
-  <strong>124 Skills</strong> · <strong>44 Rules</strong> · <strong>67 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>124 Skills</strong> · <strong>46 Rules</strong> · <strong>73 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -238,7 +238,7 @@ can prioritize the right skills for extraction.
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 67 commands](.agent-src/commands/)
+→ [Browse all 73 commands](.agent-src/commands/)
 
 ---
 
@@ -263,7 +263,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 124 skills + 67 native commands). Cursor, Cline, Windsurf,
+> package (rules + 124 skills + 73 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.

package/composer.json

@@ -7,7 +7,8 @@
         "php": ">=8.0"
     },
     "bin": [
-        "bin/install.php"
+        "bin/install.php",
+        "scripts/agent-config"
     ],
     "archive": {
         "exclude": [

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,28 @@ 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 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 +98,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 +132,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.12.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,6 +29,9 @@
         "composer.json",
         "llms.txt"
     ],
+    "bin": {
+        "agent-config": "scripts/agent-config"
+    },
     "scripts": {
         "postinstall": "bash scripts/postinstall.sh"
     },