@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -0,0 +1,286 @@
+# .agent-project-settings.yml — repo-shared agent settings
+#
+# Committed to the repository (the opposite of `.agent-settings.yml`
+# which is git-ignored and per-developer). This file holds decisions
+# that belong to the **project**, not to an individual's workstation.
+#
+# Precedence (lowest → highest):
+#   1. Package defaults (shipped by event4u/agent-config)
+#   2. ~/.event4u/agent-config/agent-settings.yml — user-global DX-comfort
+#      defaults (whitelist: name, ide, rule_loading_tier, personal.bot_icon,
+#      personal.autonomy, telegraph.speak_scope). Created on opt-in via
+#      /onboard; project-local files always win. Legacy
+#      ~/.config/agent-config/agent-settings.yml is read as a fallback.
+#   3. This file (.agent-project-settings.yml) — team defaults
+#   4. .agent-settings.yml — developer overrides (gitignored)
+#
+# Any key marked `locked: true` in this file CANNOT be overridden by
+# .agent-settings.yml. Use sparingly — locked keys reduce developer
+# autonomy. Reserve for compliance or correctness concerns (e.g.
+# forcing a test framework, pinning a coding style).
+#
+# Full precedence model + user-global whitelist contract:
+#   docs/guidelines/agent-infra/layered-settings.md
+#
+# Copy this file to `.agent-project-settings.yml` (drop the `.example`)
+# and commit it.
+
+schema_version: 1
+
+# --- Agent config version pin (project-shared) ---
+#
+# Exact semver of @event4u/agent-config this project commits to. The
+# `npx @event4u/agent-config` dispatcher re-execs at this version when
+# the developer's locally-resolved version differs — so every
+# contributor runs the same agent surface regardless of their npm
+# cache state. Bump this together with a tested upgrade. Empty string
+# disables the pin (resolver picks the latest release; only safe for
+# greenfield projects). Ranges (^, ~, >=) are NOT supported.
+# CI guard: a release bump of `package.json` must update this value
+# in lockstep — see scripts/check_template_pin_drift.py (road-to-
+# portable-runtime-and-update-check P3.3).
+agent_config_version: "5.10.1"
+
+# --- Project identity ---
+project:
+  # Short slug used in agent output, prompts, and PR metadata. Keep it
+  # identical to the repo name unless there is a reason to differ.
+  slug: ""
+
+  # Human-readable name — used in generated docs and PR bodies.
+  name: ""
+
+  # Primary stack indicator — agent uses this to pick the right skills.
+  # Examples: "laravel", "nextjs", "symfony", "node-express", "react",
+  # "zend-laminas", "multi" (polyglot monorepo).
+  stack: ""
+
+# --- Modules (optional) ---
+#
+# Module-aware skills and commands (`module-management`, `/module
+# explore`, `/module create`, roadmap-writing) consult this block to
+# discover where modules live, which namespace template they use, and
+# whether per-module `agents/` folders ship contexts the agent should
+# auto-load. When `modules.enabled` is false (default), every
+# module-aware surface skips its module branch — the project is
+# treated as a flat repo.
+#
+# Populated automatically by `scripts/install.py` on a fresh install
+# when an `app/Modules/`, `src/modules/`, `packages/`, `internal/`, or
+# similar shape is detected. Set manually for custom layouts. Lockable
+# via `locked_keys: [modules.root_paths]` for compliance-critical
+# repos where the module layout must not drift.
+modules:
+  # Opt-in flag. When false, module-aware skills behave as if the
+  # block were absent — no enumeration, no auto-context-load. Flip to
+  # true once `root_paths` is populated and the team has agreed on the
+  # layout.
+  enabled: false
+
+  # Repo-relative paths to module root directories. Multiple entries
+  # supported for polyglot repos (e.g. `[app/Modules, packages]` for a
+  # Laravel + JS monorepo). Each subdirectory under a root path is a
+  # module unless its name is in `skip_dirs`. Examples by stack:
+  #   Laravel HMVC          → [app/Modules]
+  #   Symfony DDD-lite      → [src]
+  #   Node monorepo         → [packages]
+  #   Python src layout     → [src]
+  #   Go internal layout    → [internal]
+  root_paths: []
+
+  # Namespace template used when generating files for a new module.
+  # `{ModuleName}` is replaced with the module's directory name.
+  # Empty when the stack does not use a PHP-style namespace (Node,
+  # Python, Go). Examples:
+  #   Laravel HMVC          → "App\\Modules\\{ModuleName}\\App"
+  #   Symfony DDD-lite      → "App\\{ModuleName}"
+  namespace_template: ""
+
+  # Per-module agent docs directory name. The agent looks for this
+  # folder under every module to auto-load `contexts/*.md` when the
+  # user enters the module via `/module explore <Name>`. Override
+  # only if your project already uses a different convention.
+  agent_folder: "agents"
+
+  # Directory names skipped during module enumeration. Template
+  # scaffolds and example modules should not show up as real modules.
+  skip_dirs: [".module-template", ".example"]
+
+  # On-the-fly detection acknowledgement. The `module-detect-on-the-fly`
+  # skill flips this to `true` once the agent has asked the user whether
+  # detected module candidates should be enabled — regardless of the
+  # answer. Prevents repeated nagging on subsequent sessions when the
+  # user said "not now". Re-detection still runs if a new root appears
+  # outside the previously surfaced set.
+  detection_acknowledged: false
+
+# --- Memory layer (optional) ---
+#
+# Opt-in signal for the repo-shared, file-backed curated-memory files
+# under `agents/memory/`. If omitted, memory features stay inert —
+# no writes, no reads, no nagging.
+memory:
+  # Enable curated memory files under `agents/memory/` as part of
+  # this repo's dogfooding of its own memory conventions. Only flip
+  # to true after you have agreed on the six content types from
+  # road-to-engineering-memory.md.
+  dogfood: false
+
+  # Path strategy for curated files. `agents` keeps them alongside
+  # roadmaps; `github` puts routing-relevant files under `.github/`.
+  # `auto` picks `github` if that directory exists, else `agents`.
+  path_strategy: auto
+
+  # Hygiene reminders — the agent nudges when entries are stale.
+  # Expiry is evaluated per type (see road-to-engineering-memory.md).
+  hygiene:
+    enabled: true
+    # Warn when `last_validated` is older than this (days). 0 = off.
+    staleness_days: 180
+
+# --- Review routing (optional) ---
+#
+# Points the `review-routing` skill at the two project-local YAML
+# files. See guidelines/agent-infra/review-routing-data-format.md
+# for the schema.
+review_routing:
+  # Location of ownership-map.yml and historical-bug-patterns.yml.
+  # `github` = .github/<file>.yml · `agents` = agents/<file>.yml ·
+  # `auto` = first match wins.
+  location: auto
+
+# --- Role modes (optional) ---
+#
+# Default role loaded for every session in this repo. See
+# guidelines/agent-infra/role-contracts.md for the six modes.
+# Leave empty to fall back to inferred mode switching.
+roles:
+  # One of: developer, reviewer, tester, po, incident, planner.
+  default: ""
+
+  # If set, the agent refuses work outside the default contract
+  # until the user explicitly switches modes with `/mode <name>`.
+  locked: false
+
+# --- Personas (optional) ---
+#
+# Personas are reusable review lenses (see .augment/personas/README.md).
+# Skills cite them in frontmatter (`personas: [id]`). This block lets
+# the project decide the default cast used by multi-lens skills without
+# editing each skill. A developer's .agent-settings.yml can override
+# or narrow the selection unless the key is listed under `locked_keys`.
+personas:
+  # Core cast always loaded by multi-lens skills when `personas:` is
+  # omitted from the skill's frontmatter. Drop an id to remove it from
+  # the default cast repo-wide. Known Core ids: developer,
+  # senior-engineer, product-owner, stakeholder, critical-challenger,
+  # ai-agent.
+  default: [developer, senior-engineer, product-owner, stakeholder, critical-challenger, ai-agent]
+
+  specialists:
+    # Specialist personas auto-included on every multi-lens run. `qa`
+    # is the v1 specialist; more land in v1.1+ (security, performance).
+    # Leave empty to require explicit --personas=+<id> opt-in.
+    auto_include: [qa]
+
+# --- Ghostwriter (optional) ---
+#
+# Toggles for the /ghostwriter command cluster. Consumer-only —
+# the package itself ignores this block (fixtures never carry aliases).
+# See docs/contracts/ghostwriter-schema.md § Aliases.
+ghostwriter:
+  # When true, `/ghostwriter:write --as=<value>` resolves <value> against
+  # both slug filenames AND every profile's `aliases:` list
+  # (case-insensitive). Conflicts are rejected at lint time
+  # (task lint-ghostwriter-source), never at runtime.
+  # Set to false to disable alias resolution (slug-only matching);
+  # any `aliases:` already in profiles are then ignored at resolve time
+  # but still validated by the lint.
+  aliases: true
+
+# --- Quality pipeline (optional) ---
+#
+# Per-language gate tools the `quality-fix` command invokes. Empty
+# list = skip the language. Agent will still auto-detect; these
+# values are advisory.
+quality:
+  php:
+    # Tools to run in order. Known: phpstan, rector, ecs, pint.
+    tools: [phpstan, rector, ecs]
+  js:
+    # Known: eslint, prettier, tsc, biome.
+    tools: [eslint, prettier, tsc]
+
+# --- Prompt optimization (engine-inbound + engine-outbound) ---
+#
+# Controls how aggressively the agent reshapes a free-form prompt
+# *before* the engine plans (`/work "<prompt>"`) and how the
+# outbound `/optimize-prompt` skill polishes a copy-and-paste
+# prompt for an external AI.
+#
+# Single-knob model — `default:` applies to both inbound and
+# outbound surfaces unless an override key is set:
+#
+#   off  — engine runs the user's literal prompt. No reconstruction,
+#          no AC inference, no template selection. Closest to "raw"
+#          behaviour; useful for power users who already write
+#          structured prompts.
+#   mini — light shaping. Inbound: `refine-prompt` runs in
+#          stack-aware mode (reads `package.json` / `CLAUDE.md` /
+#          `.cursorrules` only to infer the framework), asks at
+#          most 5 targeted clarifying questions, emits a structured
+#          6-block prompt. Outbound: BASIC mode of `prompt-optimizer`
+#          (4-D pass with safe defaults, no clarifying questions).
+#   max  — full restructure. Inbound: `refine-prompt` runs the
+#          5-dimension confidence rubric + assumption inference;
+#          medium-band halts surface the assumption list, low-band
+#          asks one clarifying question. Outbound: DETAIL mode of
+#          `prompt-optimizer` with template selection (RTF, CO-STAR,
+#          RISEN, CRISPE, …) per `docs/guidelines/prompt-templates.md`.
+#
+# Default `max` reshapes every prompt before the engine plans —
+# the AI Council (anthropic/openai, 2026-05-17) warned this risks
+# latency, token cost, and loss of author intent on the inbound
+# side. If that bites you, uncomment `inbound: mini` below. The
+# outbound side (explicit `/optimize-prompt`) is opt-in and stays
+# at `max` regardless.
+#
+# Bypass: any prompt starting with `bypass_prefix` skips both
+# inbound and outbound shaping verbatim. `/`-prefixed slash
+# commands (`/work`, `/commit`, …) and `#`-prefixed memory entries
+# auto-bypass.
+prompt_optimization:
+  default: max
+
+  # Optional per-surface overrides. Leave commented to inherit
+  # `default:`. Council-recommended split is `inbound: mini,
+  # outbound: max` — uncomment if you want fewer interceptions
+  # on `/work` but full polish on `/optimize-prompt`.
+  # inbound: mini
+  # outbound: max
+
+  # Prefix that skips all shaping. Must start with `/` to align
+  # with this project's slash-command convention. Default `/raw`.
+  bypass_prefix: "/raw"
+
+# --- Locked keys (override this file only; never locks .agent-settings.yml) ---
+#
+# List keys from this file whose values cannot be overridden by a
+# developer's .agent-settings.yml. Dot-notation. Example:
+#   locked_keys:
+#     - project.stack
+#     - quality.php.tools
+locked_keys: []
+
+# --- Links to curated data (read-only references) ---
+#
+# Paths the agent consults read-only during work. Curated memory
+# files live here when memory.dogfood is true. These paths are for
+# reference only — no enforcement is done from this file.
+references:
+  # Architecture decisions live in ADRs (docs/decisions/), not curated memory.
+  domain_invariants: agents/memory/domain-invariants/
+  incident_learnings: agents/memory/incident-learnings/
+  product_rules: agents/memory/product-rules/
+  ownership_map: ""            # auto-resolved by review-routing
+  historical_bug_patterns: ""  # auto-resolved by review-routing

package/dist/agent-src/templates/agents/proposal.example.md

@@ -0,0 +1,155 @@
+---
+# proposal.example.md — curated self-improvement proposal
+#
+# Used by the five-stage pipeline in road-to-curated-self-improvement.md:
+#   capture → classify → propose → gate → upstream
+#
+# An agent drafting a rule/skill/guideline change in a consumer project
+# produces this doc and hands it to `upstream-contribute`. The gate
+# (`scripts/check_proposal.py`) verifies evidence, scope, and
+# portability before a PR is opened.
+#
+# Copy this file, fill every field, run `task check-proposal`, commit.
+
+proposal_id: ""                    # stable kebab-case slug, unique per repo
+type: ""                           # rule | skill | command | guideline
+scope: ""                          # project | package
+stage: proposed                    # captured | classified | proposed | gated | upstream
+source_learning: ""                # agents/learnings/<date>-<slug>.md
+target_artifact: ""                # dist/agent-src/<type>/<name>.md (for upstream scope)
+                                   # or agents/overrides/<...> (for project scope)
+author: ""                         # name or team slug
+created: 2026-01-01                # ISO date
+last_updated: 2026-01-01
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+lifecycle: active
+trust:
+  level: core
+  confidence: high
+  human_review_required: false
+install:
+  default: true
+  removable: false
+---
+
+# Proposal: <short title>
+
+## 1. Learning
+
+**What happened.** One paragraph, no log excerpts, no names. State
+the pattern, not the anecdote.
+
+> Example:
+> *Across 3 PRs in the `Billing` module, reviewers flagged the
+> same omission: mass-assignable attributes on `Payment` that
+> should be guarded. No existing skill covers this path.*
+
+## 2. Classification
+
+Check exactly one box per line.
+
+- **Scope:** [ ] project-local only  [ ] upstream (applies broadly)
+- **Type:** [ ] rule  [ ] skill  [ ] command  [ ] guideline
+- **Replaces existing:** [ ] yes → `<target_artifact>`  [ ] no → new artifact
+- **Urgency:** [ ] blocking  [ ] this quarter  [ ] opportunistic
+
+**Why this scope / type.** Two sentences max. The gate rejects
+proposals where scope is `upstream` but the evidence is single-repo.
+
+## 3. Evidence
+
+At least TWO independent references. The gate rejects proposals
+with fewer than two `source` entries, or with entries that all
+resolve to the same PR / incident / repository.
+
+```yaml
+evidence:
+  - kind: pr           # pr | issue | incident | review-comment | test-failure
+    ref: https://github.com/example/repo/pull/1234
+    summary: Reviewer caught the same omission as PR #1187 and #1221.
+  - kind: review-comment
+    ref: https://github.com/example/repo/pull/1221#discussion_r556677
+    summary: Three reviewers flagged mass-assignment on Payment.
+```
+
+## 4. Proposed artefact
+
+The full body of the draft rule / skill / command / guideline goes
+here. If it is more than ~80 lines, commit it as a separate file
+under `agents/drafts/<proposal_id>.md` and link from here.
+
+```markdown
+# <draft title>
+
+...complete draft body...
+```
+
+## 5. Quality gate expectations
+
+List the checks the draft MUST pass before the gate signs off. The
+gate auto-runs every item in this list.
+
+- [ ] Passes `scripts/skill_linter.py` with zero errors
+- [ ] Passes `scripts/check_portability.py` (no project-specific
+      identifiers)
+- [ ] References in the draft all resolve (`check_references.py`)
+- [ ] Size within budget for its type (per `size-enforcement` rule)
+- [ ] `preservation-guard` check: if `Replaces existing`, justify
+      the replacement below.
+
+## 6. Replacement justification (if applicable)
+
+Leave blank if `Replaces existing: no`. Otherwise:
+
+- **What the existing artefact does well:** …
+- **What it misses:** …
+- **Why extension inside the existing artefact was rejected:** …
+- **Migration note for consumer projects:** …
+
+## 7. Success signal
+
+How will we know this proposal pays off? One concrete metric, one
+time window, one decision rule.
+
+- **Metric:** <e.g., "reviewer comments about mass-assignment in the
+  Billing module per month">
+- **Baseline:** <current value from evidence>
+- **Target:** <e.g., "drop to < 1 per quarter">
+- **Evaluation date:** <ISO date, typically +90 days from upstream
+  merge>
+- **Retire rule:** <"if still > baseline after 2 windows, retire">
+
+## 8. Risks and alternatives rejected
+
+- **Risks:** …
+- **Alternatives rejected:**
+  - `<alt 1>` — <why not>
+  - `<alt 2>` — <why not>
+
+## 9. Gate verdict (filled by gate, not author)
+
+- **Verdict:** [ ] pass  [ ] request changes  [ ] block
+- **Gate run date:** …
+- **Notes:** …
+
+## 10. Upstream PR (filled on stage transition)
+
+- **PR URL:** …
+- **Merge date:** …
+- **Originating project:** <consumer repo slug; metadata only>
+- **Retired:** <YYYY-MM-DD when the shipped artefact was removed; blank while live>
+- **Superseded-by:** <proposal_id of the replacement, if any>
+
+---
+
+<!--
+Authoring checklist (delete before committing):
+  [ ] All ten sections filled (or explicitly N/A).
+  [ ] `proposal_id` is unique in this repo.
+  [ ] At least two independent `evidence` entries.
+  [ ] Draft body complete; no "TODO" / "TBD" markers.
+  [ ] `Success signal` has a real number and a real date.
+-->

package/dist/agent-src/templates/command.md

@@ -0,0 +1,105 @@
+# Command Template
+
+> Template for creating new commands in `.agent-src.uncondensed/commands/{command-name}.md`.
+
+## Instructions
+
+1. Create file: `.agent-src.uncondensed/commands/{command-name}.md`
+2. Copy the template below
+3. Replace all `{placeholders}` with actual content
+4. Remove all `<!-- comments -->` when done
+5. Run: `python3 scripts/skill_linter.py .agent-src.uncondensed/commands/{command-name}.md`
+6. Sync: `task sync` (regenerates `dist/agent-src/` and `.augment/`)
+7. Generate Claude symlink: `task generate-tools` (or manually create symlink)
+
+## Template
+
+````markdown
+---
+name: {command-name}
+description: {Short description of what the command does}
+disable-model-invocation: true
+skills: [{optional-skill-1}, {optional-skill-2}]
+suggestion:
+  eligible: true
+  trigger_description: "natural-language pattern, comma-separated examples"
+  trigger_context: "concrete signal — branch name, file pattern, recent tool output"
+# council_depth: deep   # uncomment for architecture/refactor/bug-diagnose commands
+---
+
+<!-- FRONTMATTER RULES (delete this comment when done):
+  - name: must match the filename (without .md)
+  - description: short, human-readable — what the command does
+  - disable-model-invocation: ALWAYS true for commands (prevents Claude from auto-invoking)
+  - skills: optional — list skills this command references or delegates to
+  - suggestion: REQUIRED — drives the in-host command suggester
+    - eligible: true  → set trigger_description + trigger_context
+    - eligible: false → set rationale (why never auto-suggested)
+    See agents/settings/contexts/command-suggestion-eligibility.md for guidance.
+  - council_depth: optional — only `deep` is accepted. **Omit the key
+    for default depth** (`standard` is the implicit default and is
+    rejected by the schema — every frontmatter byte counts). Set `deep`
+    when this command triggers AI Council on architecture, refactoring,
+    or bug-diagnosis artefacts. The host translates `deep` into
+    `--depth deep` on the council CLI, raising the round floor to
+    `ai_council.deep_min_rounds`. See .augment/skills/ai-council/SKILL.md.
+-->
+
+# /{command-name}
+
+{One-line summary of what this command does.}
+
+**Source of truth:** `.agent-src.uncondensed/` — never read or edit `dist/agent-src/` or `.augment/` directly.
+
+## Steps
+
+### 1. {First step}
+
+{What to do, what to check, what to run.}
+
+### 2. {Second step}
+
+{Next action.}
+
+### 3. {Third step}
+
+{Continue until workflow is complete.}
+
+### N. Present findings
+
+<!-- For audit/analysis commands: state findings, then act or hand back.
+     For action commands: state what was done.
+
+     Default-terse per the
+     [Frugality Charter](../contexts/contracts/frugality-charter.md):
+     no preview-then-confirm pair, no "Ready to proceed?" gate, no
+     numbered options unless options differ in *consequence* (per
+     `no-cheap-questions § Pre-Send Self-Check`). Routine confirmations
+     are governed by `verbosity.routine_confirmations: false` (default).
+
+     Only emit a numbered-options block when ALL of:
+       1. Two or more options carry distinct consequences (not sequencing/format),
+       2. The user has not fenced the next step (per `scope-control § fenced step`),
+       3. No option violates `commit-policy`, `scope-control § git-ops`,
+          or `non-destructive-by-default`. -->
+
+## Rules
+
+<!-- Command-specific constraints. Keep short. -->
+
+- {Rule 1}
+- {Rule 2}
+````
+
+## Checklist
+
+Before considering a command complete:
+
+- [ ] **Frontmatter**: has `name`, `description`, `disable-model-invocation: true`, `suggestion` block
+- [ ] **Steps**: numbered sub-headings (`### 1.`, `### 2.`, ...)
+- [ ] **Source of truth**: works on `.agent-src.uncondensed/`, not `dist/agent-src/` or `.augment/`
+- [ ] **No auto-apply**: presents findings, asks before destructive changes
+- [ ] **Linter passes**: `python3 scripts/skill_linter.py` reports 0 FAIL
+- [ ] **English only**: all content in English
+- [ ] **Synced**: `dist/agent-src/commands/` has the same file
+- [ ] **Claude symlink**: `.claude/skills/{name}/SKILL.md` → `../../../dist/agent-src/commands/{name}.md`