@event4u/agent-config 1.22.0 → 1.23.0

package/.agent-src/skills/adr-create/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: adr-create
+description: "Use when capturing an architectural decision — naming the file, picking the next ADR number, filling Status / Context / Decision / Consequences, and regenerating the index — even without saying 'ADR'."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 30
+  allowed_tools: []
+  command:
+    - python3
+    - scripts/adr/regenerate_index.py
+---
+
+# adr-create
+
+## When to use
+
+Use this skill when:
+
+- A non-trivial architectural choice needs a written record (kernel
+  membership, cap raises, contract changes, library swap, deprecation).
+- A decision overrides a previous one and needs `supersedes:` linkage.
+- A roadmap phase closes and the chosen variant must be cited.
+- The user says "write an ADR for X", "decision log this", "we need
+  a record of why we picked Y".
+
+Do NOT use when:
+
+- The change is reversible without governance impact (typo, lint
+  fix, refactor that stays inside one module).
+- The decision is already covered by an existing ADR — extend or
+  supersede it instead of duplicating.
+- A skill, rule, or guideline is the better home (use those skills).
+
+## Goal
+
+- Sequential `ADR-NNN-<slug>.md` numbering with no gaps.
+- Standard template: Status, Context, Decision, Consequences,
+  Alternatives, References.
+- Regenerated index so readers find the ADR by topic, not by ls.
+- Zero MCP-tool dependency — pure filesystem + Python.
+
+## Preconditions
+
+- An ADR directory exists (default `docs/adr/`; `docs/decisions/` is
+  the recognised alias used in this package and many older projects).
+- The decision is **already made** — ADRs record outcomes, they do
+  not run the decision process. For unresolved trade-offs, run the
+  council or consult `adversarial-review` first.
+
+## Procedure
+
+### 1. Inspect and resolve the ADR directory
+
+Identify the canonical directory in this order:
+
+1. `docs/adr/` — default per spec.
+2. `docs/decisions/` — accepted alias if `docs/adr/` is missing.
+3. Anything else — fail, ask the user to pick one of the two
+   canonical paths. Do not invent a third location.
+
+### 2. Pick the next ADR number
+
+Scan the directory for `ADR-*.md`, parse the leading 3-digit number,
+take `max + 1` (zero-padded). For an empty directory, start at `001`.
+Reject re-use of an existing number — the index regenerator treats
+duplicates as a hard failure.
+
+### 3. Pick a slug
+
+Short, hyphen-lowercase, scope-revealing. Match peer ADRs in the
+directory. Examples: `kernel-swap-deferred`, `flat-cluster-subs`,
+`http-bridge-deferred-with-trigger`. Reject slugs longer than 60 chars.
+
+### 4. Author the ADR
+
+Use the standard template (frontmatter + body). All sections are
+required; "n/a" is acceptable for genuinely empty Alternatives or
+References blocks but never for Status, Context, Decision, or
+Consequences.
+
+```markdown
+---
+adr: NNN
+status: proposed | accepted | superseded | deprecated
+date: YYYY-MM-DD
+decision: <slug>
+supersedes: — | ADR-MMM
+superseded_by: — | ADR-MMM
+phase: <roadmap> · <phase-id>
+---
+
+# ADR-NNN — <Decision Title>
+
+## Status
+
+**<Proposed | Accepted | …>** · YYYY-MM-DD.
+
+## Context
+
+What problem forced this decision? What constraints applied? What
+alternatives were on the table at decision time?
+
+## Decision
+
+The chosen variant, in one paragraph. Concrete enough that a reader
+six months later knows what was actually picked.
+
+## Consequences
+
+### Accepted
+
+- Hard guarantees we now make.
+
+### Trade-offs
+
+- What we gave up. Mitigations, if any.
+
+## Alternatives considered
+
+- **Variant X — <name>.** Rejected because <reason>.
+- **Variant Y — <name>.** Rejected because <reason>.
+
+## References
+
+- Linked roadmap, contract, prior ADR, council session id.
+```
+
+### 5. Regenerate the index
+
+Run the dispatcher:
+
+```bash
+python3 scripts/runtime_dispatcher.py run --skill adr-create
+# or directly:
+python3 scripts/adr/regenerate_index.py --dir docs/adr/
+```
+
+The script scans `ADR-*.md`, reads frontmatter (`adr`, `status`,
+`date`, `decision`, `supersedes`), and writes `INDEX.md` with one
+table row per ADR plus broken-supersede warnings on stderr.
+
+### 6. Validate
+
+- `python3 scripts/adr/regenerate_index.py --check` exits 0
+  (index is up to date, no number gaps, no broken supersedes).
+- The project's CI / quality pipeline passes locally.
+
+## Output format
+
+1. Path of the new `ADR-NNN-<slug>.md` file.
+2. Path of the regenerated `INDEX.md`.
+3. One-line summary of the decision.
+4. Linked roadmap or phase, if any.
+
+## Gotchas
+
+- `docs/adr/` is the default path; some projects use
+  `docs/decisions/` (this package included). Pass `--dir` to the
+  index regenerator when running outside the default.
+- Frontmatter `adr:` is the canonical number; the filename prefix
+  must match. The index regenerator fails on mismatch.
+- ADRs are append-only history. To revise a decision, write a new
+  ADR with `supersedes: ADR-MMM` and flip the old one's status to
+  `superseded`.
+- Never delete an ADR file — supersede it. Deletion breaks
+  historical links and round-trips through git history checks.
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every ADR you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, `## Context` states the
+  forcing function in 2–3 sentences; no historical narrative.
+- Per the cite-don't-restate principle, `## Decision` links the
+  rules / contracts it overrides; no rule body is quoted in full.
+- Per the cheap-question check, `## Alternatives considered` lists
+  genuine design alternatives, not strawmen.
+
+**Pre-save self-check:**
+1. Does `## Context` carry more than 5 sentences of setup?
+2. Does `## Decision` restate rule text instead of citing the rule?
+3. Are alternatives evaluated with a real consequence each, or with
+   stylistic preference?
+4. Does the ADR forecast consequences with hedge phrases ("might",
+   "could potentially") instead of decidable claims?
+
+## Do NOT
+
+- Skip Context — a decision without context is folklore.
+- Reuse an existing ADR number — the index regenerator hard-fails.
+- Author ADRs for reversible refactors or minor cleanups.
+- Cite a council session id without ensuring the file is committed
+  or otherwise reachable from the repo (per `no-council-references`).

package/.agent-src/skills/agent-docs-writing/SKILL.md

@@ -168,6 +168,7 @@ When starting work, read documentation in this order:
 | Significant multi-step change | Ask user about creating a roadmap in `agents/roadmaps/` |
 | New convention introduced | Update relevant doc in `./agents/` or `.augment/guidelines/` |
 | Database schema changed | Update `agents/docs/database-setup.md` |
+| Architectural decision made | Use the [`adr-create`](../adr-create/SKILL.md) skill — writes a numbered ADR under `docs/adr/` (or `docs/decisions/`) and regenerates the index |
 
 ## When to update documentation
 
@@ -187,7 +188,7 @@ After completing a significant code change, run this mental checklist:
 | New API endpoint | OpenAPI annotations, `AGENTS.md` API section |
 | New module created | Create `app/Modules/{Module}/agents/` |
 | Service/repository signature changed | Check if referenced in `agents/docs/services-and-repos.md` |
-| New environment variable | `.env.example`, `AGENTS.md` env section |
+| New environment variable | `.env.example`, `AGENTS.md` environment section |
 | Docker/compose change | `agents/docs/docker.md`, `Makefile` documentation |
 | New Artisan command | `AGENTS.md` commands section |
 | New pattern/convention introduced | Relevant guideline in `.augment/guidelines/` |
@@ -220,6 +221,27 @@ Do NOT auto-update docs without the user's knowledge. Flag what needs updating a
 - AGENTS.md and copilot-instructions.md have different audiences — don't copy content between them.
 - Module docs go in `app/Modules/*/agents/`, NOT in the central `agents/` directory.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every agent-doc update you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, doc updates state what
+  changed; no "In this section we will…" frames.
+- Per the cheap-question check, AGENTS.md surface offers options
+  only where the project genuinely diverges.
+- Per the post-action summary suppression, doc edits append change
+  notes to the existing log entry; no new "Summary of changes" block.
+
+**Pre-save self-check:**
+1. Does the doc open with a narrative intro instead of the actual
+   content?
+2. Are paragraphs added that summarize an existing table?
+3. Does the doc duplicate the rule index instead of linking the
+   relevant rule?
+4. Is German prose present outside `DE: / EN:` anchor blocks?
+
 ## Do NOT
 
 - Do NOT create docs unless there's a real need (new module, significant change).

package/.agent-src/skills/command-writing/SKILL.md

@@ -166,6 +166,29 @@ multi-paragraph explanation, extract it into a skill and call it.
   `.agent-src.uncompressed/`.
 * Duplicating another command's workflow instead of delegating via `skills:`.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every command you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, command output blocks state
+  the action result, not "Now we will execute…".
+- Per the post-action summary suppression, the success path emits
+  the artifact (PR URL, commit hash) without a wrapping summary.
+- Per the cheap-question check, never offer "preview vs. execute"
+  as a numbered option when the command's role is to execute.
+
+**Pre-save self-check:**
+1. Does any command step prescribe a "Let me…" or "Found it" output
+   line?
+2. Does the command default to multi-line summaries when a one-line
+   outcome suffices?
+3. Is a confirmation gate used outside the Iron-Law / Routine /
+   Contextual taxonomy?
+4. Are template placeholders (`{{var}}`) accompanied by setup prose
+   instead of action prose?
+
 ## Do NOT
 
 * Do NOT set `disable-model-invocation: false`

package/.agent-src/skills/context-authoring/SKILL.md

@@ -156,6 +156,29 @@ schema regex and by `scripts/lint_load_context.py`. Body links to
 Canonical reference: `rule-writing` § 3b and
 `docs/contracts/load-context-schema.md`.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every context file you author.
+
+**Examples in this artifact:**
+- Per the charter's index nature, context files are reviewer fuel —
+  they hold mechanics, not Iron-Law obligations.
+- Per the cite-don't-restate principle, when a section mirrors a
+  rule, link the rule and stop.
+- Per the act-skip-narration rule, lookup tables open the section;
+  explanatory prose follows only if the table is ambiguous.
+
+**Pre-save self-check:**
+1. Does the context file restate Iron-Law text instead of linking
+   the rule?
+2. Does any section open with "This document explains…" instead of
+   the lookup material?
+3. Are placeholders (`<add me>`, `TBD`) shipped instead of actual
+   content?
+4. Are the cited rules linked with stable anchors (verified to
+   exist)?
+
 ## Do NOT
 
 - Do NOT copy content between projects. Every context file is local to its

package/.agent-src/skills/conventional-commits-writing/SKILL.md

@@ -113,6 +113,29 @@ Or add `BREAKING CHANGE:` in the commit body/footer.
 - Squash merge titles should describe the net effect, not every internal detail
 - `refactor` means NO behavior change — if behavior changes, use `feat` or `fix`
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every commit message you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, the subject states the
+  change in 50 chars; no scaffolding ("This commit will…").
+- Per the post-action summary suppression, the body lists changed
+  surfaces in bullets — no closing paragraph re-summarizing them.
+- Per the cheap-question check, never propose a `feat` vs. `chore`
+  numbered choice when the type is decidable from the diff.
+
+**Pre-save self-check:**
+1. Does the subject line carry filler ("various improvements",
+   "general updates")?
+2. Does the body re-narrate the diff instead of stating intent?
+3. Are co-author / attribution footers present without explicit user
+   request (per
+   [`no-attribution-footers`](../../rules/no-attribution-footers.md))?
+4. Is the type / scope chosen from the diff, not from the asker's
+   framing?
+
 ## Do NOT
 
 - Do NOT use vague messages: `update stuff`, `fix bug`, `changes`

package/.agent-src/skills/guideline-writing/SKILL.md

@@ -130,6 +130,28 @@ Above the split signal, break by sub-topic into sibling files in the same folder
 * Hollowing out a skill into "see guideline" — the skill must remain
   executable (see `preservation-guard`).
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every guideline you author.
+
+**Examples in this artifact:**
+- Per the charter's index nature, guidelines describe practice
+  patterns; they do **not** restate Iron-Laws from rules.
+- Per the act-skip-narration rule, code examples lead with the
+  pattern, not its motivation.
+- Per the cheap-question check, guidelines do not prescribe stylistic
+  forks ("table vs. paragraph") — pick one.
+
+**Pre-save self-check:**
+1. Does the guideline restate text from a rule body instead of
+   linking the rule?
+2. Are code examples preceded by narrative ramp-up?
+3. Does the guideline introduce a new convention without citing the
+   rule that holds the obligation?
+4. Are sections labeled "Overview" / "Background" carrying only
+   restatement?
+
 ## Do NOT
 
 * Do NOT add `type:` or `alwaysApply:` to the frontmatter

package/.agent-src/skills/persona-writing/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: persona-writing
+description: "Use when creating or editing a persona in .agent-src.uncompressed/personas/ — voice / focus / unique questions / output expectations — even when the user just says 'add a reviewer voice for X'."
+source: package
+---
+
+<!-- cloud_safe: degrade -->
+
+# persona-writing
+
+## When to use
+
+* Creating a new persona file in
+  `.agent-src.uncompressed/personas/{id}.md`
+* Rewriting an existing persona (focus shift, output-expectation
+  change — not a typo fix)
+* Deciding whether a new reviewer voice should be a persona at all
+  (vs. a skill of its own)
+
+Do NOT use this skill when:
+
+* The content is a multi-step workflow → use
+  [`skill-writing`](../skill-writing/SKILL.md)
+* The content is a hard obligation the agent must always honor → use
+  [`rule-writing`](../rule-writing/SKILL.md)
+* The content describes the project's role-mode contract → that lives
+  in `docs/contracts/role-contracts.md`, not in personas
+
+## Persona vs skill vs role-mode — critical test
+
+| Intent | Artifact |
+|---|---|
+| "Agent should review through a specific lens" | **Persona** |
+| "Agent should run a multi-step workflow" | **Skill** |
+| "Agent's closing contract differs by role" | **Role-mode** (contract file) |
+
+A persona is **passive reference content** — it never triggers by
+description, never appears in `<available_skills>`. Skills cite
+personas via the `personas:` frontmatter key.
+
+## Procedure
+
+### 0. Drafting protocol
+
+Creating or materially rewriting a persona must go through
+Understand → Research → Draft per the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md)
+rule. Inspect existing personas under
+`.agent-src.uncompressed/personas/` for overlap before writing a new
+one.
+
+### 1. Decide focus, not topic
+
+A persona owns **one focus**: automation-readiness, adversarial
+challenge, product-owner priorities, etc. If the focus needs three
+sentences, it is two personas.
+
+### 2. Draft the persona file
+
+Required sections:
+
+* `## Focus` — one paragraph, what this lens *cares about* and what
+  it *ignores*.
+* `## Unique questions` — 4–7 questions only this persona would ask.
+  Each question must be decidable against the artifact under review.
+* `## Output expectations` — what the persona produces (verdict
+  format, severity vocabulary, citation discipline).
+
+Optional: `## Anti-patterns this persona catches` — concrete examples
+the persona is calibrated to flag.
+
+### 3. Cite from at least one skill
+
+A persona that is not cited by any skill via the `personas:`
+frontmatter key is dead code. Either wire it into an existing skill
+or do not ship it.
+
+## Frontmatter shape
+
+```yaml
+---
+id: <kebab-case-id>
+role: <Human-Readable Role>
+description: "One sentence: what this voice catches that others miss."
+tier: core | specialty
+mode: developer | product-owner | qa | stakeholder | none
+version: "1.0"
+source: package
+---
+```
+
+The `mode:` field is advisory only — it suggests which role-mode the
+persona pairs naturally with; it does not bind.
+
+## Output format
+
+A single Markdown file at `.agent-src.uncompressed/personas/{id}.md`:
+
+1. Frontmatter (`id`, `role`, `description`, `tier`, `mode`,
+   `version`, `source`)
+2. `## Focus` — one paragraph, what the lens cares about and ignores
+3. `## Unique questions` — 4–7 decidable questions
+4. `## Output expectations` — verdict format, severity vocabulary
+
+Length: ≤ 80 lines for a tier-core persona; longer signals the focus
+is too broad.
+
+## Gotchas
+
+- **Persona without a citing skill** — a persona that no skill
+  references via `personas:` never loads. Wire it in or do not ship.
+- **Focus drift across rewrites** — adding "and also …" to `## Focus`
+  is the first symptom of a second persona hiding inside the first.
+- **Vibe-based unique questions** — "Does this feel right?" cannot
+  be evaluated against the artifact. Replace with decidable triggers.
+- **Restating role-mode contracts** — closing-contract obligations
+  belong in `docs/contracts/role-contracts.md`, not in the persona
+  body.
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every persona you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, `## Focus` opens with what
+  the persona cares about, not "This persona was created to…".
+- Per the cite-don't-restate principle, link rules the persona
+  enforces; do not paste their text into the persona body.
+- Per the cheap-question check, `## Unique questions` lists decidable
+  questions only — drop any that read like vibe checks.
+
+**Pre-save self-check:**
+1. Does `## Focus` open with the lens, or with persona meta-narrative?
+2. Are unique questions decidable against the artifact alone?
+3. Are any questions duplicated from another persona?
+4. Is the persona cited by at least one skill via `personas:`?
+
+## Do NOT
+
+* Author a persona that nobody cites.
+* Restate Iron-Law text from rules inside `## Output expectations`.
+* Use ALL-CAPS Iron-Law fenced blocks — those belong in rules on the
+  [`kernel-membership`](../../../docs/contracts/kernel-membership.md)
+  list.
+* Ship a persona that overlaps an existing one's focus by more than
+  50 % — merge instead.
+
+## Examples
+
+See `.agent-src.uncompressed/personas/ai-agent.md` (automation
+readiness) and `critical-challenger.md` (adversarial review) for
+canonical structure.

package/.agent-src/skills/readme-writing/SKILL.md

@@ -156,6 +156,26 @@ After writing, verify:
 - READMEs for packages consumed by others need install/usage focus, not internal dev workflow
 - The model forgets to validate commands against `Taskfile.yml` / `Makefile` / `package.json scripts`
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every README you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, the README opens with one
+  sentence stating what the project is.
+- Per the cite-don't-restate principle, "Installation" links to the
+  canonical install script, not its full contents.
+- Per the cheap-question check, "Quick start vs. full guide" is
+  offered only when the two paths produce different artifacts.
+
+**Pre-save self-check:**
+1. Does the opening paragraph carry marketing adjectives ("modern",
+   "comprehensive", "powerful")?
+2. Are setup steps narrated instead of bulleted commands?
+3. Are screenshots / GIFs present without explicit user request?
+4. Is content duplicated from `AGENTS.md` rather than linked?
+
 ## Do NOT
 
 - Do NOT invent features, setup steps, or commands not found in the repo

package/.agent-src/skills/readme-writing-package/SKILL.md

@@ -177,6 +177,25 @@ README = enough to adopt. Docs = enough to master.
 - Existing README may be outdated — verify against actual `composer.json` / source, not old text
 - Model forgets post-install steps (config publish, service provider, env vars)
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every package README you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, the package README opens
+  with one sentence: what installs, what it does.
+- Per the cite-don't-restate principle, link upstream docs for
+  advanced topics; ship the minimal usage example only.
+- Per the post-action summary suppression, no "What's new" block —
+  that belongs in `CHANGELOG.md`.
+
+**Pre-save self-check:**
+1. Does the opening pitch include marketing adjectives?
+2. Is the minimal usage example over 10 lines when 5 would suffice?
+3. Are CI badges shipped without verifying that they resolve?
+4. Does the doc duplicate CHANGELOG content?
+
 ## Do NOT
 
 - Do NOT invent package capabilities or compatibility