@event4u/agent-config 5.10.0 → 6.0.0

package/.agent-src/skills/upstream-contribute/SKILL.md

@@ -1,261 +0,0 @@
----
-model_tier: inherit
-name: upstream-contribute
-description: "Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package."
-domain: process
-execution:
-  type: assisted
-  handler: internal
-  allowed_tools: ["github"]
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# upstream-contribute
-
-## When to use
-
-- A new skill was created in a project that should be shared across all projects
-- A rule or skill improvement was discovered that benefits all consumers
-- A bug was found in a shared skill, rule, or command
-- The `learning-to-rule-or-skill` skill identified something worth upstreaming
-- An override was created locally and should become the new default
-- A project-specific skill/rule could be **generalized** to benefit all consumers
-- The `upstream-proposal` rule suggested a contribution and user agreed
-
-Do NOT use when:
-
-- **The user has NOT given explicit consent** — this is the #1 rule
-- The content already exists in the shared package
-- The learning is truly one-off and cannot be generalized
-
-## Goal
-
-Contribute a learning, skill, rule, or fix from a consumer project back to the
-shared `agent-config` package — with correct file placement, quality gates, and PR structure.
-
-## Core principles
-
-- **⛔ Consent first** — NEVER create a PR, branch, or any upstream action without explicit user approval
-- **Universality first** — the contribution must work for ALL consumers, not just one project
-- **Generalize when possible** — project-specific content CAN become universal with adaptation
-- **Evidence-based** — learnings must have occurred 2+ times or be clearly generalizable
-- **Complete pairs** — both uncondensed and condensed versions required
-- **Quality verified** — must pass linter before PR creation
-- **Local benefit immediately** — use override for instant project benefit while PR is pending
-
-## Package repository
-
-The shared agent-config package lives at:
-
-```
-git@github.com:event4u-app/agent-config.git
-```
-
-GitHub: `https://github.com/event4u-app/agent-config`
-
-## Procedure
-
-### 0. Mandatory consent gate
-
-**This step is NON-NEGOTIABLE. No exceptions.**
-
-Before ANY upstream work (branch, files, PR), ask the user:
-
-```
-> 🔄 This [skill/rule/guideline] could improve the shared agent-config package.
-> [Brief explanation of what would be contributed and why it's valuable]
->
-> 1. Yes — create an upstream PR
-> 2. No — keep it project-local only
-```
-
-- **If user picks 2** → STOP. Do not mention upstream again for this item.
-- **If user picks 1** → continue with the procedure below.
-- **If `project.upstream_repo` is empty in `.agent-settings.yml`** → ask the user to configure it first.
-- **NEVER skip this step**, even if the user previously agreed to other contributions.
-
-### 1. Determine contribution type
-
-| Type | Uncondensed path | Condensed path |
-|---|---|---|
-| **New skill** | `.agent-src.uncondensed/skills/{name}/SKILL.md` | `.augment/skills/{name}/SKILL.md` |
-| **New rule** | `.agent-src.uncondensed/rules/{name}.md` | `.augment/rules/{name}.md` |
-| **New command** | `.agent-src.uncondensed/commands/{name}.md` | `.augment/commands/{name}.md` |
-| **New guideline** | `.agent-src.uncondensed/guidelines/{category}/{name}.md` | `.augment/guidelines/{category}/{name}.md` |
-| **Update to existing** | Same path as original | Same path as original |
-
-### 2. Apply locally as override (immediate benefit)
-
-Create an override so the project benefits immediately:
-
-```
-agents/overrides/{type}/{name}.md
-```
-
-With frontmatter:
-
-```yaml
----
-overrides: {type}/{name}
-mode: replace  # or extend
----
-```
-
-This step is optional if the change is low-urgency.
-
-### 2b. Generalize project-specific content (if needed)
-
-If the content is project-specific but could be made universal:
-
-1. **Identify project-specific parts** — domain names, local paths, project conventions
-2. **Abstract them** — replace with generic patterns, configurable values, or examples
-3. **Show the user the diff** — original vs. generalized version
-4. **Get approval** — user must confirm the generalized version is correct
-
-Example: A project-specific "import-csv" skill → generic "file-import" skill with configurable format.
-
-### 3. Prepare the upstream contribution
-
-The agent needs access to the package repository. Ask the user:
-
-```
-> The improvement should go to the shared agent-config package.
-> I need to create a PR in `event4u-app/agent-config`.
->
-> 1. I have the package repo cloned locally — tell me the path
-> 2. Clone it for me into a temp directory
-> 3. I'll handle the PR manually — just give me the files
-```
-
-**Option 1:** User provides path → work directly in that repo.
-
-**Option 2:** Clone into temp directory:
-
-```bash
-git clone git@github.com:event4u-app/agent-config.git /tmp/agent-config-upstream
-cd /tmp/agent-config-upstream
-```
-
-**Option 3:** Output the file contents as copyable blocks for the user.
-
-### 4. Create branch and files
-
-```bash
-cd {package-repo-path}
-git checkout main && git pull
-git checkout -b feat/skills/{name}  # or fix/rules/{name}, etc.
-```
-
-Create both files:
-
-- **Uncondensed version** → `.agent-src.uncondensed/{type}/{name}` (full, verbose, human-readable)
-- **Condensed version** → `.augment/{type}/{name}` (token-efficient, preserving all code blocks,
-  headings, frontmatter, validation, gotchas)
-
-For skills, the condensed version should be 40-60% shorter than uncondensed.
-For rules and commands, they are usually copied 1:1 (no condensation).
-
-### 5. Ensure file quality
-
-The files must:
-
-- Have correct YAML frontmatter (`name`, `description`, `source: package`)
-- NOT contain project-specific references (no domain names, local paths, FQDNs)
-- Follow the skill/rule/command template structure
-- Have exactly one trailing newline
-
-### 6. Run quality gates (if working in the package repo)
-
-```bash
-python3 scripts/skill_linter.py --all          # 0 FAIL required
-python3 scripts/check_condensation.py            # No errors for this file
-python3 scripts/condense.py --generate-tools    # Regenerate symlinks
-bash scripts/condense.sh --check                # .agent-src/ in sync with source
-bash scripts/condense.sh --check-hashes         # All hashes match
-```
-
-If not in the package repo, note that these checks will run in CI after the PR is created.
-
-### 6b. Proposal gate — MANDATORY when a proposal doc exists
-
-If the contribution originates from a proposal under `agents/proposals/`
-(produced by `learning-to-rule-or-skill` via the pipeline in
-[`self-improvement-pipeline`](../../../docs/guidelines/agent-infra/self-improvement-pipeline.md)),
-run the Stage-4 gate before opening the PR:
-
-```bash
-./agent-config proposal:check agents/proposals/{slug}.md
-```
-
-**Hard refusal rule:** if `./agent-config proposal:check` exits non-zero, STOP —
-do not create the branch, do not push, do not open the PR. Surface the
-findings to the user, ask them to fix the proposal (add evidence,
-remove TODO markers, complete required sections), then rerun.
-
-When no proposal doc exists (small fix, typo, pure bug-fix), skip this
-step and document the rationale in the PR body under the Promotion
-Gate.
-
-### 7. Commit and create PR
-
-Branch naming: `feat/skills/{name}`, `fix/rules/{name}`, `feat/commands/{name}`
-
-Commit message format:
-
-```
-feat(skills): add {name} skill
-fix(rules): improve {name} rule — {what changed}
-feat(commands): add {name} command
-```
-
-PR title: Same as commit message.
-
-PR body must use the package's PR template with these gates:
-
-- **Promotion Gate** — learning occurred 2+ times, improves correctness, prevents real failure
-- **Quality Gate** — linter passes, tests pass
-- **Universality Gate** — no project-specific assumptions, benefits all consumers
-- **Completeness Gate** — both versions present, symlinks regenerated
-
-### 8. After merge — clean up override
-
-Once the PR is merged and the package is updated in the project:
-
-```bash
-# In the consumer project
-rm agents/overrides/{type}/{name}.md
-composer update event4u/agent-config  # or npm update
-```
-
-The shared version now replaces the local override.
-
-## Output format
-
-1. Summary of what is being contributed (type, name, why)
-2. File contents for both uncondensed and condensed versions
-3. If working in the package repo: branch name, commit message, PR title
-4. If Option 3: copyable file blocks for the user to paste
-5. Reminder to clean up local override after upstream merge
-
-## Gotcha
-
-- Agent in consumer project doesn't know the package repo URL — this skill provides it
-- Agent may try to edit `.augment/` in the consumer project — that's read-only (symlinked)
-- Agent may forget the condensed version — both are mandatory
-- Agent may include project-specific references in the skill — must be universal
-- The `source` field in frontmatter must be `package`, not `project`
-- Agent may not have git access to the package repo — Option 3 handles this gracefully
-
-## Do NOT
-
-- **Do NOT create any upstream artifact without explicit user consent** — this is the #1 rule
-- **Do NOT open a PR if `./agent-config proposal:check` blocks** — fix the proposal first (step 6b)
-- Do NOT edit `.augment/` in the consumer project — it's managed by the package
-- Do NOT submit project-specific content without generalizing it first
-- Do NOT skip the condensed version — both files are mandatory
-- Do NOT forget to clean up the local override after upstream merge
-- Do NOT bypass quality gates — they exist for a reason
-- Do NOT assume consent from a previous contribution — ask every time

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

@@ -1,34 +0,0 @@
-# {{project_name}}
-
-<!--
-  Fill placeholders or run `/agents init`, then delete this
-  comment. Iron Law — capability bullets, not path lists; paths rot.
-  Tool stubs (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`) link here.
-  Anatomy + recipes: `.augment/contexts/contracts/agents-md-anatomy.md`.
--->
-
-> {{project_description}}
-
-## Layers
-
-| Layer | Location | Edits |
-|---|---|---|
-| Installed package | `.augment/`, `.agent-src/` | hands-off — managed by `event4u/agent-config` |
-| Project layer | `agents/`, `agents/overrides/`, `.agent-settings.yml` | your customizations and config |
-
-## Pointers
-
-- **Filling out this AGENTS.md** — section templates, capability bullets, multi-agent entry flow, monorepo per-package layout: [`.augment/contexts/contracts/consumer-agents-md-guide.md`](.augment/contexts/contracts/consumer-agents-md-guide.md).
-- **Behavior rules (always active)** — Iron Laws and routed rules that fire automatically while you work in this project: [`.augment/rules/`](.augment/rules/).
-- **Skills (on-demand expertise)** — domain skills surfaced by description; invoked when their trigger fires: [`.augment/skills/`](.augment/skills/).
-- **Commands (workflows)** — slash-commands the agent runs end-to-end (`/work`, `/implement-ticket`, `/commit`, `/create-pr`, …): [`.augment/commands/`](.augment/commands/).
-- **Project-specific docs** — your own architecture notes, roadmaps, sessions, contexts: [`agents/`](agents/).
-
-## Emergency triage — read this when nothing else is reachable
-
-1. **What is this repo?** — Consumer project; agent-config is installed as a shared skill / rule / command suite at `.augment/` and `.agent-src/`.
-2. **What language?** — Project-specific; agents mirror the user's language at runtime.
-3. **Where do I edit agent-config?** — Do not edit `.augment/` or `.agent-src/` here; they are installed artifacts. Project edits live in `agents/` and project source.
-4. **Lint / test / sync entry point?** — Project-specific (see project README); agent-config reinstalls via `composer update event4u/agent-config` or `npm update @event4u/agent-config`.
-5. **Where do the always-active rules live?** — `.agent-src/rules/` (kernel = 9 Iron-Law rules; tier-1 / tier-2 routed via `.agent-src/router.json`).
-6. **Per-module agent docs?** — If `modules.enabled: true`, each module under `modules.root_paths` may carry its own `{agent_folder}/` (default `agents/`). See `module-management` skill.

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

@@ -1,286 +0,0 @@
-# .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.7.0"
-
-# --- 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 @event4u/agent-memory companion package and
-# the repo-shared curated-memory files. 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: agents/memory/architecture-decisions/
-  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