@event4u/agent-config 1.21.0 → 1.23.0

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

package/.agent-src/skills/roadmap-management/SKILL.md

@@ -9,8 +9,8 @@ source: package
 ## When to use
 
 Use this skill when:
-- Creating a new roadmap (`roadmap-create` command)
-- Executing a roadmap (`roadmap-execute` command)
+- Creating a new roadmap (`/roadmap:create` command)
+- Executing a roadmap (`/roadmap:process-step|phase|full` commands)
 - Checking roadmap progress
 - Updating roadmap status after completing work
 
@@ -119,8 +119,8 @@ Every roadmap follows this structure:
 
 Every roadmap implicitly includes the project's quality pipeline
 (static analysis, autofixes, tests). What's configurable is **when**
-the pipeline runs during `/roadmap execute`, controlled by
-`roadmap.quality_cadence` in `.agent-settings.yml`:
+the pipeline runs during `/roadmap:process-step|phase|full`,
+controlled by `roadmap.quality_cadence` in `.agent-settings.yml`:
 
 | Cadence | Pipeline runs | Trade-off |
 |---|---|---|
@@ -164,7 +164,7 @@ unfamiliar codebases.
    evidence-based reason (e.g. risky migration benefits from a spike).
    Never include release versions, deprecation dates, or git tags in
    the roadmap text. If the user declines, do **not** re-propose during
-   `roadmap-execute`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+   `/roadmap:process-*`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
 5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
    **Before writing**, scan the entire roadmap namespace for a
    collision — active, `archive/`, `skipped/`, and nested subdirs —
@@ -289,8 +289,8 @@ is rewritten by `.augment/scripts/update_roadmap_progress.py`.
 **Always regenerate in the SAME response** after any of the following
 (enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)):
 
-- Creating a new roadmap (`roadmap-create`)
-- Marking a step `[x]`, `[~]`, or `[-]` during `roadmap-execute`
+- Creating a new roadmap (`/roadmap:create`)
+- Marking a step `[x]`, `[~]`, or `[-]` during `/roadmap:process-*`
 - Archiving or moving a roadmap to `skipped/`
 - Adding, renaming, or removing a phase
 

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

@@ -0,0 +1,157 @@
+---
+name: roadmap-writing
+description: "Use when authoring or rewriting a roadmap in agents/roadmaps/ — phase prose, goal sentence, acceptance criteria, council notes — even when the user just says 'write a plan for X' or 'draft a roadmap'."
+source: package
+---
+
+<!-- cloud_safe: degrade -->
+
+# roadmap-writing
+
+## When to use
+
+* Authoring a new roadmap file in `agents/roadmaps/{name}.md` (or
+  module-scoped under `app/Modules/{Module}/agents/roadmaps/`)
+* Rewriting an existing roadmap (phase restructure, goal pivot,
+  council-pass integration — not a checkbox flip)
+* Drafting a phase block, exit criteria, or rollback section that
+  will land inside an existing roadmap
+
+Do NOT use this skill when:
+
+* Flipping checkboxes, regenerating the dashboard, archiving on
+  completion → use [`roadmap-management`](../roadmap-management/SKILL.md)
+* Updating AGENTS.md / module docs / contexts → use
+  [`agent-docs-writing`](../agent-docs-writing/SKILL.md)
+* Capturing an architectural decision → use
+  [`adr-create`](../adr-create/SKILL.md)
+
+## Roadmap-writing vs roadmap-management — critical test
+
+| Intent | Artifact |
+|---|---|
+| "I need to write the plan body" | **roadmap-writing** (this skill) |
+| "I need to track progress / regenerate dashboard / archive" | **roadmap-management** |
+
+This skill owns the **prose authoring** axis: structure, goal
+sentence, phase blocks, acceptance criteria. The execution and
+dashboard-sync axis stays in `roadmap-management`.
+
+## Procedure
+
+### 0. Drafting protocol
+
+Authoring or materially rewriting a roadmap must go through
+Understand → Research → Draft per the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md)
+rule. Inspect existing roadmaps under `agents/roadmaps/` for overlap
+or supersession before opening a new one.
+
+### 1. Read the canonical template first
+
+The structure, frontmatter, lifecycle, and complexity-tier rules live
+in [`.agent-src.uncompressed/templates/roadmaps.md`](../../templates/roadmaps.md).
+Read it before authoring. Do not restate its rules in the roadmap
+body — link the template if a phase needs to override one.
+
+### 2. Pick complexity tier honestly
+
+Default `lightweight` (≤ 6 phases, ≤ 600 lines). Only use
+`structural` when the change touches a contract, kernel rule, or
+budget invariant — the complexity linter enforces it. Standard:
+[`roadmap-complexity-standard`](../../../docs/contracts/roadmap-complexity-standard.md).
+
+### 3. Write the goal first
+
+One sentence, top of file, decidable: "Reduce X by Y on flow Z."
+Vague goals ("improve roadmaps") force every reader to re-derive
+intent. If the goal needs three sentences, the roadmap is two
+roadmaps.
+
+### 4. Phase blocks carry checkboxes
+
+Every non-intro phase contains at least one `- [ ]`. Decision tables
+and council-pass notes capture the *why*; checkboxes capture the
+*what to do next*. Without checkboxes the phase is invisible to
+`agents/roadmaps-progress.md` — enforced by
+[`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)
+Iron Law #2.
+
+### 5. Exit & rollback per phase
+
+Each phase declares **exit criteria** (decidable signals that the
+phase is done) and **rollback** (what to revert if the phase fails).
+A phase without exit criteria is open-ended; a phase without
+rollback assumes success.
+
+## Output format
+
+A single Markdown file at `agents/roadmaps/{name}.md`:
+
+1. Frontmatter (`status`, `complexity`)
+2. `# Road to {short title}`
+3. One-sentence outcome blockquote
+4. `## Goal` — decidable target
+5. `## Prerequisites` — checkboxes
+6. `## Context` — why now, links to tickets
+7. Numbered `## Phase N — {name}` sections with checkboxes,
+   exit criteria, rollback
+8. `## Acceptance criteria` — final gates
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every roadmap you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, the goal sentence states the
+  outcome — no "This roadmap exists because…" ramp-up.
+- Per the cite-don't-restate principle, link the canonical template
+  for structural rules; do not paste them into the roadmap.
+- Per the post-action summary suppression, council-pass integration
+  notes append to the existing phase block — no new "Summary of
+  council passes" section.
+- Per the cheap-question check, never propose a "lightweight vs.
+  structural" numbered choice when the diff makes the answer
+  decidable.
+
+**Pre-save self-check:**
+1. Does the goal sentence open with the outcome, or with backstory?
+2. Does any phase block restate template rules instead of linking
+   them?
+3. Are checkboxes present in every non-intro phase?
+4. Are exit criteria decidable, or vibe-based ("looks good")?
+5. Is content duplicated from another roadmap (supersession instead)?
+
+## Do NOT
+
+* Author a roadmap without a goal sentence.
+* Restate `templates/roadmaps.md` rules inside the roadmap body.
+* Include version numbers, target releases, or git tags — banned by
+  template rule 13 + [`scope-control`](../../rules/scope-control.md#git-operations--permission-gated).
+* Plan automatic branch switches mid-roadmap (template rule 14).
+* Ship a phase without checkboxes (`roadmap-progress-sync` Iron Law #2).
+* Use ALL-CAPS Iron-Law fenced blocks — those belong in
+  [`kernel-membership`](../../../docs/contracts/kernel-membership.md)-listed
+  rules, not roadmaps.
+
+## Gotchas
+
+- **No checkboxes in a phase** — `agents/roadmaps-progress.md` cannot
+  count the phase; the dashboard reports zero open work even though
+  the phase has prose. Enforced by `roadmap-progress-sync` Iron Law #2.
+- **Vague goal sentence** — "Improve roadmap quality" forces every
+  reader to re-derive intent and blocks decidable acceptance.
+- **Restating template rules** — pasting structural rules into the
+  roadmap body creates two sources of truth that drift over months.
+- **Version numbers in phase names** — `Phase 1 — v1.8.0` violates
+  template rule 13 and `scope-control § git-operations`.
+- **Author-during-execution branch switches** — the agent should not
+  propose a new branch mid-roadmap; that decision is fenced to
+  authoring time.
+
+## Examples
+
+See `agents/roadmaps/archive/road-to-token-frugality.md`
+(structural, multi-phase, council-integrated) and any
+`agents/roadmaps/road-to-*.md` for canonical structure.

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

@@ -165,6 +165,28 @@ and body links (relative `../../docs/...`, rewriter handles depth).
 * Forgetting to run `python3 scripts/compress.py --generate-tools` — downstream tools stay stale.
 * Editing `.agent-src/rules/` or `.augment/rules/` directly — those are generated.
 
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every rule you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, no intent prose in the rule
+  body — start with the obligation, not a setup paragraph.
+- Per the Iron-Law literal predicate, ALL-CAPS fenced obligations
+  belong only when the rule sits on the
+  [`kernel-membership`](../../../docs/contracts/kernel-membership.md)
+  list.
+- Per the cheap-question check, the rule's "When to ask" guidance
+  must list decidable triggers, not vibe-based judgment.
+
+**Pre-save self-check:**
+1. Does the rule body open with the obligation, or with a setup
+   paragraph?
+2. Are any examples mere narration (no decidable test)?
+3. Are ALL-CAPS Iron-Law blocks used outside a kernel-listed rule?
+4. Are interactions duplicated from another rule rather than linked?
+
 ## Do NOT
 
 * Do NOT inline long procedures

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

@@ -0,0 +1,226 @@
+---
+name: script-writing
+description: "Use when adding or editing any script under `scripts/` — `--quiet` flag, `_lib/script_output` helpers, silent Taskfile wiring, Iron-Law carve-outs — even when you just say 'add a check script for X'."
+source: package
+---
+
+<!-- cloud_safe: degrade -->
+
+# script-writing
+
+## When to use
+
+* Creating a new Python script in `scripts/{name}.py` (linters, checks, generators, measure tools)
+* Editing an existing script that prints progress or success lines
+* Wiring a script into `Taskfile.yml` or `taskfiles/*.yml`
+* Reviewing a PR that adds scripts and asking "why does this still print on minimal?"
+
+Do NOT use this skill when:
+
+* The content is a one-off / archival under `scripts/ai_council/one_off_archive/` — those carry an `_one_off_` prefix and are exempt from the verbosity convention
+* The content is a shell entrypoint with secret prompts (install-keys, release confirms) → see § 3 Iron-Law carve-outs
+* The content is a `.mjs` / Node script under `scripts/cost/` — different runtime; convention covered in `agents/contexts/cost-tracking.md`
+
+## Script vs other writers — critical test
+
+| Intent | Artifact |
+|---|---|
+| "Maintenance script the agent or CI runs" | **This skill** |
+| "User types `/foo` to invoke" | `command-writing` |
+| "Constraint the agent must always honor" | `rule-writing` |
+| "Reference knowledge agents cite" | `guideline-writing` |
+
+Scripts orchestrate file checks, generators, and validators. They are
+neither user-invoked nor agent-routed — `task` and CI call them.
+
+## Procedure
+
+### 0. Run the Drafting Protocol
+
+Creating or materially rewriting a script that joins the linter / check
+family **must** go through Understand → Research → Draft from the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) rule.
+
+* **Understand** — what failure does this script catch that no existing
+  check catches? Is it a one-off (then archive it) or evergreen?
+* **Research** — `ls scripts/check_*.py scripts/lint_*.py`, grep for
+  overlap, skim 1–2 peer scripts (e.g. `lint_handoffs.py`,
+  `check_md_language.py`).
+* **Draft** — propose name + one-line purpose first. Only fill the body
+  after the shape is confirmed.
+
+### 1. `--quiet` flag — argparse + sys.argv fallback
+
+Every `check_*.py` / `lint_*.py` script MUST accept `--quiet` so the
+silent Taskfile layer (§ 4) can suppress success-only output.
+
+**With argparse (preferred):**
+
+```python
+parser = argparse.ArgumentParser(...)
+parser.add_argument("--quiet", action="store_true",
+                    help="Only print on failure")
+args = parser.parse_args()
+...
+if not args.quiet:
+    print("✅ All clean")
+```
+
+**Plain script (no argparse) fallback:**
+
+```python
+import sys
+
+QUIET = "--quiet" in sys.argv
+...
+if not QUIET:
+    print("✅ All clean")
+```
+
+Failure output (`❌`, non-zero exit) is **never** gated — failures must
+always print regardless of `--quiet`.
+
+### 2. `_lib/script_output` helpers — preferred for new scripts
+
+For anything richer than a single `✅`/`❌`, import the verbosity-aware
+router instead of raw `print()`:
+
+```python
+from _lib.script_output import info, success, warn, error, flush_summary
+
+info("Loading manifest")          # drops on silent + minimal
+success("Wrote 3 files")          # collected at minimal, printed at verbose
+warn("Skipping stale entry")      # stderr unless silent
+error("Manifest missing")         # stderr always
+
+flush_summary("Done — 3 entries") # one-line summary at minimal
+```
+
+Resolution order (first wins, cached for the process):
+
+1. `AGENT_SCRIPT_VERBOSITY` env (`silent` / `minimal` / `verbose`)
+2. `SCRIPT_OUTPUT_VERBOSE=1` alias (== `verbose`)
+3. `.agent-settings.yml` → `verbosity.script_output`
+4. Default `minimal`
+
+The resolved level is exported back into `AGENT_SCRIPT_VERBOSITY` so
+child processes inherit it. Tests reset via `reset_level()` from the
+same module — see `tests/test_script_output.py`.
+
+### 3. Iron-Law carve-outs — never silenced
+
+The following surfaces **MUST** use plain `print()` and never the
+helpers, so verbosity settings cannot suppress them:
+
+* Release confirms — every task in `taskfiles/release.yml`
+* Secret prompts — `install-anthropic-key`, `install-openai-key`,
+  `setup-evals`, `install-hooks` interactive sections
+* `runtime-e2e` and `test-triggers-live`
+* CI orchestration sentinels — `_ci-start`, `_ci-end`, root `ci`
+* Any prompt that asks the user for confirmation per
+  [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) — Hard Floor cannot be silenced
+
+If unsure, check `scripts/ai_council/one_off_archive/2026-05/_one_off_silent_taskfiles.py`
+`CARVE_OUTS` for the canonical list.
+
+### 4. Taskfile wiring — `silent: true` + `{{.QUIET_FLAG}}`
+
+Every Taskfile task that wraps a `--quiet`-aware script MUST set
+`silent: true` and pass `{{.QUIET_FLAG}}` to the script:
+
+```yaml
+# Per-task in taskfiles/*.yml:
+tasks:
+  lint-handoffs:
+    silent: true
+    cmd: python3 scripts/lint_handoffs.py {{.QUIET_FLAG}}
+```
+
+The `QUIET_FLAG` var is defined once at the root of `Taskfile.yml`
+and resolves to `""` only when `AGENT_SCRIPT_VERBOSITY=verbose`:
+
+```yaml
+# Root Taskfile.yml — already in place, do not duplicate:
+vars:
+  QUIET_FLAG:
+    sh: '[ "$AGENT_SCRIPT_VERBOSITY" = "verbose" ] && echo "" || echo "--quiet"'
+```
+
+Carve-out tasks (release, install secrets, CI orchestration — see § 3)
+do **not** add `silent: true` and do **not** use `{{.QUIET_FLAG}}`.
+
+### 5. Validate
+
+* Run `python3 scripts/skill_linter.py .agent-src.uncompressed/skills/script-writing/SKILL.md` → 0 FAIL
+* Run `python3 scripts/{your-script}.py --quiet` and the verbose path — exit code 0 on clean, non-zero on failure regardless of flag
+* If the script uses `_lib/script_output`, add a test under `tests/` patterned on `tests/test_script_output.py` — assert `silent` / `minimal` / `verbose` behave per § 2
+* Run the full CI pipeline locally (see `Taskfile.yml` in this repo for the script list) — must exit 0 except for tolerated warnings
+
+## Output format
+
+1. Script file at `scripts/{name}.py` with `--quiet` accepted
+2. Taskfile wiring with `silent: true` + `{{.QUIET_FLAG}}` (unless carve-out)
+3. Test under `tests/` if `_lib/script_output` is used
+4. Linter output showing 0 FAIL
+
+## Gotchas
+
+* Forgetting `--quiet` — the silent Taskfile layer wraps the script and the call fails with `unrecognized arguments: --quiet`
+* Gating `❌` failures behind `--quiet` — failures must always print
+* Using raw `print()` for progress lines — drops on `minimal`, no inheritance
+* Adding `silent: true` to a release / install-keys task — bypasses the Hard Floor confirmation
+* Editing `Taskfile.yml`'s `QUIET_FLAG` var — single source of truth, do not duplicate
+* Forgetting that `from _lib.script_output import …` requires the script's resolution to walk up to `scripts/` — copy the `Path(__file__).resolve().parent` pattern from a peer
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every script you author. Phase 10 of the charter (settings hooks
+row — `verbosity.script_output` / `verbosity.taskfile_command_echo`)
+is what this skill exists to teach.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, success lines are gated behind
+  `--quiet` so the only thing visible at `minimal` is the end-of-run
+  summary or a failure.
+- Per the post-action summary suppression, scripts with multi-step
+  output collect via `success()` and emit one `flush_summary()` line.
+- Per the cheap-question check, scripts never prompt unless they hit
+  a Hard Floor surface (§ 3 carve-outs).
+
+**Pre-save self-check:**
+1. Does every `print("✅ ...")` line sit behind `--quiet` / the helper?
+2. Does the script add `silent: true` + `{{.QUIET_FLAG}}` to its
+   Taskfile entry (unless a carve-out)?
+3. Are failure lines (`❌`, exit non-zero) **never** gated by quiet?
+4. Are Iron-Law surfaces using plain `print()` and not the helper?
+
+## Do NOT
+
+* Do NOT gate `❌` / failure output behind `--quiet`
+* Do NOT use `_lib/script_output` for release confirms or secret prompts
+* Do NOT add `silent: true` to carve-out tasks
+* Do NOT hardcode `print()` for progress in new scripts — use `info()`
+* Do NOT skip the Taskfile wiring — without it the verbosity gates leak
+* Do NOT edit `.agent-src/`, `.augment/`, or `.claude/` projections
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's `task`
+runner and `_lib/script_output` are not reachable. The skill still
+applies — with prose-only validation:
+
+* Emit the full script + Taskfile snippet as copyable Markdown blocks. Do not attempt to write to disk.
+* Self-check: `--quiet` accepted, failures never gated, success lines gated, helper imports look syntactically right.
+* Tell the user to save under `scripts/{name}.py`, wire the Taskfile entry, and run `task lint-skills && task ci` locally before committing.
+* Skip every reference to running the linter or `task` commands yourself — they only run on the user's machine.
+
+## Examples
+
+Good description (trigger-shaped, names domain + symptoms):
+
+> "Use when adding or editing any script under `scripts/` — `--quiet` flag, `_lib/script_output` helpers, silent Taskfile wiring, Iron-Law carve-outs — even when you just say 'add a check script for X'."
+
+Bad description (vague, no trigger):
+
+> "Script conventions"