@event4u/agent-config 5.10.0 → 6.0.0

package/dist/agent-src/skills/threat-modeling/SKILL.md

@@ -0,0 +1,207 @@
+---
+model_tier: high
+name: threat-modeling
+description: "Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation."
+personas:
+  - security-engineer
+domain: quality
+council_depth: deep
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# threat-modeling
+
+
+> **Grounded corpus (Tier-1 consultation):** ground surface → threats →
+> controls before enumerating from memory — `python3
+> <skills-root>/corpus-grounding/scripts/ground.py ground --manifest
+> <skills-root>/threat-modeling/data/manifest.json "<surface description>"`
+> returns surface class, ATT&CK/CWE-cited threats, required controls, and
+> negative tests, with confidence + evidence-gap. Propose grounded
+> findings; human confirms. Corpus: [`data/threats.csv`](data/threats.csv)
+> (MITRE ATT&CK v16 / OWASP ASVS-derived; owner + cadence in the manifest).
+
+> You are a reviewer specialized in **pre-impl threat analysis**.
+> Your only job is to produce a compact threat model for a planned change —
+> actors, assets, trust boundaries, abuse cases, and the minimum controls
+> the implementer must add. You do **not** audit existing code end-to-end,
+> you do **not** review diffs, you do **not** implement controls — sibling
+> skills handle those.
+
+## When to use
+
+* The change adds or modifies authentication, authorization, or permission checks
+* The change adds a public endpoint, webhook, file upload, queue worker,
+  scheduled task, or third-party integration
+* The change touches sensitive data, tenant boundaries, secrets, billing flows,
+  or admin-only capabilities
+* A `security-sensitive-stop-rule` trigger fired and the agent must produce a
+  risk review before patching
+
+Do NOT use when:
+
+* The change is a cosmetic refactor or documentation-only edit — skip entirely
+* The change is a diff ready for review — route to
+  [`judge-security-auditor`](../judge-security-auditor/SKILL.md)
+* The concern is a full-codebase security posture review — route to
+  [`security-audit`](../security-audit/SKILL.md)
+* The concern is end-to-end authorization enforcement — route to
+  [`authz-review`](../authz-review/SKILL.md)
+* The concern is output/log leakage on an existing API — route to
+  [`data-exposure-review`](../data-exposure-review/SKILL.md)
+* The concern is implementing the controls once identified — route to
+  [`security`](../security/SKILL.md)
+
+## Procedure
+
+### 1. Anchor on the planned change
+
+Read the task description (ticket, feature plan, spec) and the entrypoints
+the change will touch. You are modelling **the stated change**, not the
+whole system. If the change is unclear from available context, stop and ask
+before continuing — never invent a threat model for an imagined feature.
+
+### 2. Inspect the execution path
+
+Trace the path once through existing code:
+
+- Where does untrusted input enter? (route, webhook, queue payload, CLI arg,
+  uploaded file, imported record)
+- Which actor types cross this path? (anonymous, authenticated user, admin,
+  service account, queue worker, cron)
+- What assets does the path touch? (PII, credentials, internal IDs, billing,
+  tenant-scoped records, files, secrets)
+- Where are the privilege boundaries? (auth gate, authorization layer, tenant
+  scope, admin gate)
+
+### 3. Model the risks
+
+For every distinct abuse case, answer:
+
+| Field | What to fill in |
+|---|---|
+| Entry point | route / job / webhook + concrete file |
+| Actor | who can trigger it |
+| Precondition | what must be true (auth state, data state) |
+| Impact | concrete damage (data loss, privilege escalation, DoS, leakage) |
+| Current control | what exists today |
+| Missing control | what the change must add |
+
+Prioritize by **impact × plausibility**, not by novelty. Skip generic
+OWASP bullets unless you can anchor them in a concrete file or line.
+
+### 4. Convert risks to engineering actions
+
+For each prioritized abuse case, propose the **smallest effective control**
+and name the exact file/layer it belongs in:
+
+- input validation → where
+- authorization check → where
+- rate limiting → where
+- output filtering → where
+- safer default → where
+- logging / alerting → where
+
+State whether a new **negative test** is required and what condition it
+must assert (e.g. *"POST /imports with tenant-B id from tenant-A session
+returns 403"*).
+
+## Validation
+
+Before finalizing the threat model, confirm:
+
+1. Every entry point has at least one identified control owner
+2. Every 🔴 abuse case has either an existing control or a required new one
+3. Every 🔴 abuse case has at least one proposed negative test
+4. You have NOT produced generic advice — every risk cites a file, route, or job
+5. You have NOT proposed offensive testing steps, exploit chains, or bypass ideas
+6. If the change is out of scope for threat modelling (no trust boundary
+   crossed), you have said so explicitly and stopped
+
+## Output format
+
+```
+Skill:   threat-modeling
+Target:  <feature / ticket / change summary>
+
+Actors:   <list, one per line>
+Assets:   <list, one per line>
+Entry points:   <route / job / webhook — file:line>
+Trust boundaries:   <where untrusted → trusted crossings happen>
+
+Abuse cases (prioritized):
+  🔴  <name> — entry point · actor · precondition
+      Impact: <concrete damage>
+      Current control: <what exists>
+      Missing control: <what to add, where>
+      Required test: <negative assertion>
+  🟡  ...
+  🟢  ...
+
+Implementation plan:
+  1. <control>, <file/layer>
+  2. ...
+
+Missing tests:
+  1. <assertion>, <test file>
+```
+
+Severity: 🔴 exploitable by external actor with current or no privilege /
+🟡 exploitable only with elevated privilege or partial auth / 🟢 defense-in-depth
+improvement, not a concrete exploit path.
+
+Required fields (ordered):
+
+1. **Skill** and **Target** — one-line change summary
+2. **Actors**, **Assets**, **Entry points**, **Trust boundaries**
+3. **Abuse cases** — prioritized; every entry cites entry point + actor + impact + current + missing control + required test
+4. **Implementation plan** — ordered controls mapped to files/layers
+5. **Missing tests** — ordered negative assertions
+
+Runtime confirmation (e.g. *"reproduce the abuse against staging"*, *"query
+the DB to confirm scope leakage exists today"*) is a follow-up for the
+implementer — **this skill does not execute tools, reproduce exploits, or
+run tests**.
+
+## Gotcha
+
+* **Generic OWASP bullets without a file anchor** — "SQL injection risk" is
+  noise unless you cite the query. Drop it or anchor it.
+* **Confusing authentication with authorization** — a logged-in user is not an
+  authorized user. Model authorization as a distinct boundary even when auth
+  is already enforced upstream.
+* **Treating queue workers and webhooks as trusted** — they carry attacker-
+  influenced payloads. Model them as untrusted entry points.
+* **Modelling the whole system when the change is narrow** — the model is
+  scoped to the planned change. Out-of-scope risks belong to `security-audit`.
+* **Producing offensive test steps** — you name abuse cases and required
+  controls, not exploit procedures.
+
+## Do NOT
+
+* NEVER produce exploit chains, payloads, or bypass techniques — if the task
+  asks for offensive work, stop and refuse per `never-help-build-offensive-cyber-capability`
+* NEVER return a threat model out of politeness when no trust boundary is crossed — say so and stop
+* NEVER treat "internal" or "behind the WAF" as a substitute for a control
+* NEVER approve a plan without at least one negative test per 🔴 abuse case
+* NEVER silently fall back to a generic checklist when the diff context is missing — ask instead
+
+## References
+
+- **STRIDE threat model** — Microsoft Security Development Lifecycle, Shostack
+  *Threat Modeling: Designing for Security* (2014). Framing basis for the
+  Actors / Assets / Entry Points / Trust Boundaries / Abuse Cases rubric.
+  [learn.microsoft.com/en-us/security/engineering/threat-modeling-tool-threats](https://learn.microsoft.com/en-us/security/engineering/threat-modeling-tool-threats)
+- **OWASP ASVS v4.0.3** — Authorization (V4), Validation & Encoding (V5),
+  Session Management (V3) — default baseline for "Missing control" entries.
+  [owasp.org/www-project-application-security-verification-standard/](https://owasp.org/www-project-application-security-verification-standard/)
+- **OWASP Top 10 2021** — A01 Broken Access Control, A04 Insecure Design,
+  A05 Security Misconfiguration — cross-reference when naming abuse cases.
+  [owasp.org/Top10/](https://owasp.org/Top10/)
+- [`authz-review`](../authz-review/SKILL.md),
+  [`data-exposure-review`](../data-exposure-review/SKILL.md),
+  [`security`](../security/SKILL.md),
+  [`security-audit`](../security-audit/SKILL.md) — sibling review / impl skills.

package/dist/agent-src/skills/threat-modeling/data/manifest.json

@@ -0,0 +1,83 @@
+{
+  "manifest_version": 1,
+  "domain": "security-threat-modeling",
+  "tier": "conditional-grounding",
+  "retriever": "bm25",
+  "default_domain": "threats",
+  "domains": {
+    "surfaces": {
+      "file": "surfaces.csv",
+      "search_cols": [
+        "Surface",
+        "Keywords"
+      ],
+      "output_cols": [
+        "Surface",
+        "Surface Class",
+        "Data Classes",
+        "Notes"
+      ],
+      "max_results": 1
+    },
+    "threats": {
+      "file": "threats.csv",
+      "search_cols": [
+        "Surface Class",
+        "Threat",
+        "Abuse Case",
+        "Source Refs"
+      ],
+      "output_cols": [
+        "Surface Class",
+        "Threat",
+        "Source Refs",
+        "Abuse Case",
+        "Required Controls",
+        "Negative Tests",
+        "Severity"
+      ],
+      "max_results": 4
+    }
+  },
+  "detect": {
+    "surfaces": [
+      "surface",
+      "login",
+      "upload",
+      "webhook",
+      "tenant",
+      "billing",
+      "secret",
+      "endpoint"
+    ],
+    "threats": [
+      "threat",
+      "abuse",
+      "attack",
+      "idor",
+      "ssrf",
+      "forgery",
+      "stuffing",
+      "escalation"
+    ]
+  },
+  "reasoning": {
+    "file": "reasoning.csv",
+    "category_domain": "surfaces",
+    "category_column": "Surface Class",
+    "match_column": "Surface_Class",
+    "rules_column": "Decision_Rules",
+    "plan": {
+      "surfaces": 1,
+      "threats": 4
+    }
+  },
+  "default_category": "General",
+  "owner": "package-maintainer",
+  "refresh_cadence": "quarterly",
+  "upstream": {
+    "repo": "derived: MITRE ATT&CK + CWE + OWASP API Top 10 / ASVS 4.0",
+    "sha": "ATT&CK v16 / ASVS 4.0.3",
+    "last_checked": "2026-06-07"
+  }
+}

package/dist/agent-src/skills/threat-modeling/data/reasoning.csv

@@ -0,0 +1,10 @@
+Surface_Class,Priority_Controls,Decision_Rules,Anti_Patterns,Severity
+authentication,MFA + rate-limit + rotation baseline,"{""if_password_reset"": ""single-use-hashed-tokens"", ""if_sso"": ""validate-audience-and-issuer"", ""if_remember_me"": ""rotate-on-privilege-change""}",Custom crypto + roll-your-own session store,HIGH
+authorization,"Object-level policy checks, deny-by-default","{""if_admin_panel"": ""separate-admin-guard"", ""if_mass_assignment_possible"": ""explicit-allowlist-dto""}",Route-middleware-only authorization,CRITICAL
+tenancy,ORM-layer global scope + sealed job context,"{""if_background_jobs"": ""seal-tenant-at-dispatch"", ""if_reports_or_exports"": ""scope-exports-explicitly""}",tenant_id from request body,CRITICAL
+file-upload,Content-sniffed allowlist outside webroot,"{""if_url_fetch"": ""ssrf-denylist-post-dns"", ""if_image_processing"": ""reencode-dont-trust""}",Extension-only validation,HIGH
+external-integration,HMAC + replay window + idempotency,"{""if_outbound_calls"": ""timeout-and-circuit-break"", ""if_queue_consumer"": ""verify-before-enqueue""}",Trusting source IP alone,HIGH
+public-endpoint,Rate limit + cache + minimal payload,"{""if_search_endpoint"": ""cap-page-size"", ""if_health_check"": ""no-version-disclosure""}",Expensive unauthenticated queries,MEDIUM
+billing,Ledger + idempotency + server-side amounts,"{""if_refunds"": ""one-way-state-machine"", ""if_webhooks_from_psp"": ""verify-signature-and-amount""}",Mutable balance column updates,CRITICAL
+secrets,Manager + redaction + scan,"{""if_third_party_keys"": ""scope-and-rotate-quarterly"", ""if_ci_pipeline"": ""masked-vars-only""}",Secrets in env committed to VCS,HIGH
+data-exposure,Allowlist serializers + contract tests,"{""if_admin_fields"": ""separate-serializer"", ""if_logs_contain_payloads"": ""logger-redaction-keys""}",Spreading model attributes into responses,MEDIUM

package/dist/agent-src/skills/threat-modeling/data/surfaces.csv

@@ -0,0 +1,10 @@
+Surface,Keywords,Surface Class,Data Classes,Notes
+Login / session / token issuance,login password session jwt token oauth sso 2fa mfa reset,authentication,"credentials, session tokens",Covers password reset and remember-me flows
+Authorization / policy / role check,authorization policy gate voter role permission admin rbac acl,authorization,entitlements,Includes admin-only routes and ownership checks
+Tenant boundary / row-level scope,tenant multi-tenant tenant_id scope row-level isolation,tenancy,all tenant data,Any query touching tenant-scoped tables
+File upload / user-supplied URL,upload file image attachment url fetch import csv,file-upload,"user files, server filesystem",Includes URL-fetch (SSRF surface)
+Outbound integration / webhook consumer,webhook integration third-party callback queue consumer api client,external-integration,"partner payloads, secrets",Inbound webhooks AND outbound calls
+Public unauthenticated endpoint,public endpoint health status unauthenticated anonymous,public-endpoint,whatever it returns,Includes health/status and marketing forms
+Billing / payment / balance mutation,billing payment charge refund invoice subscription balance credit,billing,money movement,Anything that changes an amount owed/paid
+Secrets / key handling,secret api-key signing key env vault kms rotation,secrets,credentials,"Storage, rotation, and logging paths"
+Data export / serializer / log channel,export serializer api-resource log audit csv download report,data-exposure,"PII, internal fields",Response shaping and log sinks

package/dist/agent-src/skills/threat-modeling/data/threats.csv

@@ -0,0 +1,16 @@
+Surface Class,Threat,Source Refs,Abuse Case,Required Controls,Negative Tests,Severity
+authentication,Credential stuffing / brute force,"ATT&CK T1110, CWE-307",Attacker replays breached credential lists against login,Rate-limit per account+IP; lockout with jitter; breached-password check; MFA,Test: >N failed logins → 429/lockout; lockout not bypassable via case-variant email,HIGH
+authentication,Session fixation / insufficient invalidation,"CWE-384, ATT&CK T1563",Attacker fixes a session id pre-login or reuses one post-logout/password-change,Rotate session id on login + privilege change; invalidate all sessions on password reset,Test: session id differs pre/post login; old token rejected after reset,HIGH
+authentication,Password-reset token abuse,CWE-640,Attacker enumerates/reuses reset tokens or intercepts via referrer leak,"Single-use, short-TTL, hashed-at-rest tokens; uniform response on unknown email; no token in URL logs",Test: token unusable twice; expired token rejected; response identical for known/unknown email,HIGH
+authorization,IDOR / missing object-level check,"CWE-639, OWASP API1",Authenticated user swaps an id in the request and reads/writes another user's object,Object-level ownership check in policy (never only route middleware); deny-by-default,"Test: user A GET/PUT on B's resource id → 403/404, for EVERY verb",CRITICAL
+authorization,Privilege escalation via mass assignment,CWE-915,Attacker posts role/is_admin fields the endpoint binds blindly,Explicit allowlist DTO/fillable; server-side role assignment only via admin flow,Test: POST with role=admin → field ignored AND audit-logged,HIGH
+tenancy,Cross-tenant read via unscoped query,CWE-639,Missing tenant_id scope on a query/report/export leaks another tenant's rows,Global scope at the ORM/repository layer; tenant from session never from request; scoped test fixtures,Test: tenant A token + tenant B resource id across list/show/export/report → empty/403,CRITICAL
+tenancy,Cross-tenant write via background job,CWE-862,Queued job re-resolves tenant from payload an attacker influenced,Jobs carry tenant context sealed at dispatch; consumer re-asserts scope before write,Test: forged job payload with foreign tenant_id → rejected,HIGH
+file-upload,Malicious file / polyglot upload,"CWE-434, ATT&CK T1105",Attacker uploads webshell/polyglot accepted by extension-only check,Content-sniff + allowlist MIME; store outside webroot with random names; never execute; AV scan if executable risk,Test: .php/.svg-with-script renamed .jpg → rejected or neutralized; direct URL fetch of stored file cannot execute,HIGH
+file-upload,SSRF via user-supplied URL,"CWE-918, ATT&CK T1090",URL-fetch feature pointed at cloud metadata / internal services,Deny private/link-local ranges post-DNS-resolution; scheme allowlist; egress proxy; response-size cap,Test: http://169.254.169.254/ and DNS-rebinding host → blocked,CRITICAL
+external-integration,Webhook forgery / replay,CWE-345,Attacker posts forged or replayed events to the webhook consumer,HMAC signature verification with rotation; timestamp tolerance window; idempotency key store,Test: bad signature → 401; stale timestamp → rejected; duplicate event id processed once,HIGH
+public-endpoint,Resource exhaustion / scraping,"CWE-770, ATT&CK T1499",Unauthenticated endpoint hammered for DoS or bulk data harvest,Rate limit + cache; no expensive queries pre-auth; pagination caps; no PII in public responses,Test: response carries rate-limit headers; page size capped server-side,MEDIUM
+billing,Race condition on balance / double-spend,CWE-362,Parallel requests redeem the same credit/refund twice,DB-level constraint or SELECT FOR UPDATE / idempotency key on money mutations; ledger over mutable balance,Test: N parallel redeems of one voucher → exactly one success,CRITICAL
+billing,Price/amount tampering,CWE-602,Client-supplied price or currency trusted at checkout,Recompute amounts server-side from catalog; signed cart or server-held cart only,Test: tampered client amount → server total unchanged,CRITICAL
+secrets,Secret leakage via logs / errors / VCS,"CWE-532, ATT&CK T1552","Key appears in exception payload, debug log, or committed .env",Centralized secret manager; logger redaction list; pre-commit secret scan; scoped short-lived tokens,Test: forced exception on auth path → no credential substring in log sink,HIGH
+data-exposure,Over-broad serializer / API resource,"CWE-213, OWASP API3","Serializer returns internal fields (cost, flags, foreign tenant refs) the UI ignores but attackers read",Explicit field allowlist per resource; separate admin vs public serializers; contract test on response shape,Test: schema-diff response against documented contract → no undocumented fields,MEDIUM

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

@@ -0,0 +1,261 @@
+---
+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                # dist/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/dist/agent-src/templates/AGENTS.md

@@ -0,0 +1,34 @@
+# {{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/`, `dist/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 `dist/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 `dist/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?** — `dist/agent-src/rules/` (kernel = 9 Iron-Law rules; tier-1 / tier-2 routed via `dist/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.