@event4u/agent-config 9.12.0 → 9.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/CHANGELOG.md +110 -238
  3. package/README.md +1 -1
  4. package/dist/agent-src/commands/optimize/deep.md +147 -0
  5. package/dist/agent-src/commands/optimize.md +12 -6
  6. package/dist/agent-src/rules/active-remediation.md +0 -2
  7. package/dist/agent-src/rules/architecture.md +0 -1
  8. package/dist/agent-src/rules/artifact-drafting-protocol.md +0 -4
  9. package/dist/agent-src/rules/autonomous-execution.md +1 -2
  10. package/dist/agent-src/rules/broken-access-control.md +0 -2
  11. package/dist/agent-src/rules/code-comment-discipline.md +0 -3
  12. package/dist/agent-src/rules/code-provenance.md +0 -3
  13. package/dist/agent-src/rules/communication-through-line.md +2 -3
  14. package/dist/agent-src/rules/content-quoting-floor.md +0 -2
  15. package/dist/agent-src/rules/context-hygiene.md +1 -3
  16. package/dist/agent-src/rules/decision-revisit-gate.md +0 -2
  17. package/dist/agent-src/rules/design-fidelity.md +29 -0
  18. package/dist/agent-src/rules/domain-adoption-policy.md +0 -3
  19. package/dist/agent-src/rules/downstream-changes.md +10 -1
  20. package/dist/agent-src/rules/external-reference-deep-dive.md +0 -7
  21. package/dist/agent-src/rules/fast-path-marker-visibility.md +0 -1
  22. package/dist/agent-src/rules/git-history-discipline.md +0 -7
  23. package/dist/agent-src/rules/guidelines.md +0 -2
  24. package/dist/agent-src/rules/improve-before-implement.md +4 -2
  25. package/dist/agent-src/rules/invite-challenge.md +0 -4
  26. package/dist/agent-src/rules/linked-projects-onboarding-gate.md +0 -2
  27. package/dist/agent-src/rules/markdown-safe-codeblocks.md +0 -1
  28. package/dist/agent-src/rules/minimal-safe-diff.md +2 -2
  29. package/dist/agent-src/rules/missing-tool-handling.md +0 -1
  30. package/dist/agent-src/rules/no-attribution-footers.md +0 -3
  31. package/dist/agent-src/rules/no-decorative-emojis-in-git-surfaces.md +8 -5
  32. package/dist/agent-src/rules/no-pr-progress-comments.md +1 -3
  33. package/dist/agent-src/rules/no-roadmap-references.md +0 -2
  34. package/dist/agent-src/rules/output-discipline.md +0 -1
  35. package/dist/agent-src/rules/prefer-enums-over-literals.md +0 -2
  36. package/dist/agent-src/rules/preservation-guard.md +0 -3
  37. package/dist/agent-src/rules/role-mode-adherence.md +0 -1
  38. package/dist/agent-src/rules/secret-vcs-guard.md +0 -2
  39. package/dist/agent-src/rules/senior-engineering-discipline.md +0 -2
  40. package/dist/agent-src/rules/session-canary.md +0 -2
  41. package/dist/agent-src/rules/size-enforcement.md +0 -5
  42. package/dist/agent-src/rules/source-confidentiality.md +0 -3
  43. package/dist/agent-src/rules/source-discovery-gate.md +0 -2
  44. package/dist/agent-src/rules/think-before-action.md +3 -3
  45. package/dist/agent-src/rules/token-budget-discipline.md +0 -1
  46. package/dist/agent-src/rules/token-efficiency.md +1 -2
  47. package/dist/agent-src/rules/tool-safety.md +0 -1
  48. package/dist/agent-src/rules/user-interaction.md +0 -3
  49. package/dist/agent-src/rules/user-interrupt-priority.md +0 -1
  50. package/dist/agent-src/skills/agent-docs-writing/SKILL.md +8 -0
  51. package/dist/agent-src/skills/analysis-skill-router/SKILL.md +55 -86
  52. package/dist/agent-src/skills/character-consistency/SKILL.md +7 -4
  53. package/dist/agent-src/skills/decision-record/SKILL.md +8 -0
  54. package/dist/agent-src/skills/design-review/SKILL.md +11 -0
  55. package/dist/agent-src/skills/design-system-capture/reference/design-system-json.md +8 -0
  56. package/dist/agent-src/skills/existing-ui-audit/SKILL.md +34 -3
  57. package/dist/agent-src/skills/fe-design/SKILL.md +10 -0
  58. package/dist/agent-src/skills/motion-choreographer/SKILL.md +7 -4
  59. package/dist/agent-src/skills/overbuild-review-lens/SKILL.md +201 -0
  60. package/dist/agent-src/skills/performance/SKILL.md +14 -0
  61. package/dist/agent-src/skills/pixar-storyteller/SKILL.md +8 -5
  62. package/dist/agent-src/skills/scene-expander/SKILL.md +9 -6
  63. package/dist/agent-src/skills/supply-chain-intake/SKILL.md +10 -0
  64. package/dist/agent-src/skills/universal-project-analysis/SKILL.md +14 -37
  65. package/dist/agent-src/skills/video-director/SKILL.md +9 -6
  66. package/dist/agent-src/templates/agents/agent-project-settings.example.yml +1 -1
  67. package/dist/agent-src/templates/scripts/work_engine/directives/ui/apply.ts +154 -13
  68. package/dist/agent-src/templates/scripts/work_engine/directives/ui/design.ts +118 -0
  69. package/dist/agent-src/templates/scripts/work_engine/directives/ui/polish.ts +40 -0
  70. package/dist/agent-src/templates/scripts/work_engine/state.ts +55 -0
  71. package/dist/cli-delegate/{chunk-QFKQLQ7X.js → chunk-GCVFLBP2.js} +399 -365
  72. package/dist/cli-delegate/cmd_export.js +1 -1
  73. package/dist/cli-delegate/cmd_prune.js +1 -1
  74. package/dist/cli-delegate/cmd_settings_migrate.js +1 -1
  75. package/dist/cli-delegate/cmd_sync.js +1 -1
  76. package/dist/cli-delegate/cmd_uninstall.js +1 -1
  77. package/dist/cli-delegate/cmd_validate.js +1 -1
  78. package/dist/discovery/deprecation-report.md +1 -1
  79. package/dist/discovery/discovery-manifest.json +123 -73
  80. package/dist/discovery/discovery-manifest.json.sha256 +1 -1
  81. package/dist/discovery/discovery-manifest.summary.md +4 -4
  82. package/dist/discovery/orphan-report.md +1 -1
  83. package/dist/discovery/packs.json +10 -8
  84. package/dist/discovery/trust-report.md +3 -3
  85. package/dist/discovery/workspaces.json +8 -6
  86. package/dist/hooks/dispatch.js +174 -13
  87. package/dist/install/install.mjs +648 -614
  88. package/dist/mcp/registry-manifest.json +3 -3
  89. package/dist/mcp/server.json +2 -2
  90. package/dist/mcp/server.mjs +783 -507
  91. package/dist/router.json +1 -1
  92. package/dist/scripts/condense.js +2 -2
  93. package/docs/MIGRATION.md +1 -1
  94. package/docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md +71 -0
  95. package/docs/guidelines/agent-infra/minimal-safe-diff-mechanics.md +24 -1
  96. package/docs/guidelines/code-clarity.md +9 -2
  97. package/docs/guidelines/design-fidelity-mechanics.md +44 -0
  98. package/llms.txt +63 -27
  99. package/package.json +4 -4
  100. package/src/agent-src/templates/scripts/work_engine/directives/ui/apply.ts +154 -13
  101. package/src/agent-src/templates/scripts/work_engine/directives/ui/design.ts +118 -0
  102. package/src/agent-src/templates/scripts/work_engine/directives/ui/polish.ts +40 -0
  103. package/src/agent-src/templates/scripts/work_engine/state.ts +55 -0
  104. package/src/config/agent-settings.template.yml +8 -0
  105. package/src/scripts/_lib/counted_probe.ts +142 -0
  106. package/src/scripts/_lib/exec_evidence.ts +5 -0
  107. package/src/scripts/_lib/overbuild_lens_contract.ts +196 -0
  108. package/src/scripts/_lib/release_scope.ts +207 -0
  109. package/src/scripts/_lib/scoped_projection.ts +212 -0
  110. package/src/scripts/ai_council/stance_tally.ts +37 -2
  111. package/src/scripts/audit_auto_rules.ts +9 -9
  112. package/src/scripts/audit_likelihood.ts +3 -3
  113. package/src/scripts/audit_overlap.ts +2 -2
  114. package/src/scripts/audit_skill_overlap.ts +233 -95
  115. package/src/scripts/audit_skill_overlap_allowlist.json +4 -0
  116. package/src/scripts/build_proof.ts +15 -1
  117. package/src/scripts/check_artefact_count_messaging.ts +128 -15
  118. package/src/scripts/check_dependency_floors.ts +16 -6
  119. package/src/scripts/check_gate_coverage.ts +6 -6
  120. package/src/scripts/check_kernel_rule_bundle.ts +5 -4
  121. package/src/scripts/check_token_quality_golden.ts +0 -18
  122. package/src/scripts/code_graph/loader.ts +35 -6
  123. package/src/scripts/compile_router.ts +3 -8
  124. package/src/scripts/condense.ts +2 -2
  125. package/src/scripts/count_scoped_projection.ts +104 -0
  126. package/src/scripts/explain_run.ts +0 -1
  127. package/src/scripts/generate_pack_manifests.ts +3 -20
  128. package/src/scripts/hooks/block_kernel_rule_writes.ts +145 -10
  129. package/src/scripts/hooks/block_no_verify.ts +101 -0
  130. package/src/scripts/install.ts +13 -90
  131. package/src/scripts/lint_agent_security.ts +5 -4
  132. package/src/scripts/lint_framework_leakage_allowlist.json +2 -2
  133. package/src/scripts/lint_regression.ts +92 -1
  134. package/src/scripts/lint_skill_descriptions.ts +93 -5
  135. package/src/scripts/project_thin_rules.ts +2 -2
  136. package/src/scripts/release.ts +107 -3
  137. package/src/scripts/resolve_lint_scope.ts +53 -0
  138. package/src/scripts/router_telemetry.ts +0 -5
  139. package/src/scripts/runtime_dispatcher.ts +40 -0
  140. package/src/scripts/schemas/pack.schema.json +1 -5
  141. package/src/scripts/schemas/rule.schema.json +1 -2
  142. package/src/scripts/self_review_gate.ts +15 -73
  143. package/src/scripts/skill_linter.ts +160 -11
  144. package/src/scripts/sweep_dead_scan_roots.ts +550 -0
  145. package/src/scripts/trigger_coverage.ts +11 -37
  146. package/src/scripts/update_counts.ts +90 -11
@@ -0,0 +1,147 @@
1
+ ---
2
+ model_tier: high
3
+ name: optimize-deep
4
+ pack: meta
5
+ tier: 2
6
+ visibility: internal
7
+ sub: deep
8
+ cluster: optimize
9
+ skills: [ai-council, roadmap-writing, subagent-orchestration, decision-review]
10
+ description: "Autonomous deep-refactoring loop — subagent analysis, verified findings, council, central + sub-roadmaps, PR, then N refinement loops (default 3). E.g. 'run a deep optimization pass'."
11
+ argument-hint: "[--loops=N] [--scope=<path>] [--no-external]"
12
+ suggestion:
13
+ eligible: false
14
+ rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
15
+ workspaces:
16
+ - agent-config-maintainer
17
+ - engineering
18
+ packs:
19
+ - meta
20
+ ---
21
+
22
+ # /optimize-deep
23
+
24
+ Autonomous deep-improvement loop: **analyze → verify → council → roadmaps →
25
+ PR → refine ×N**. The autonomous sibling of [`/optimize project`](project.md)
26
+ (which is interview-driven and asks the user); this command answers its own
27
+ questions in the AI council and ends with a pull request plus a
28
+ council-refined roadmap set.
29
+
30
+ This is a **coordinator** over existing primitives — it composes, never
31
+ reimplements: subagent fan-out analysis, `/analyze:decision`-style decision
32
+ challenge, `ai-council` resolution, `/roadmap:create` output shape,
33
+ `/create-pr` mechanics.
34
+
35
+ ## When to invoke
36
+
37
+ - "Deep-analyze this package and build the improvement roadmap" /
38
+ "geh in die Tiefe und erstelle die Refactoring-Roadmap".
39
+ - Periodic renewal: question standing decisions after the environment
40
+ changed (new host capabilities, model generation, ecosystem shift).
41
+ - A refactoring mandate that should end in a reviewed PR, not a chat answer.
42
+
43
+ Do NOT invoke for: a single named bug, an interview-style sweep with the
44
+ user in the loop (route to `/optimize project`), a code-only analysis
45
+ (`/project-analyze`), or agent-layer file tooling (`/optimize` siblings).
46
+
47
+ ## Loop budget
48
+
49
+ `--loops=N` caps the refinement loops. **Default: 3** (council-locked
50
+ 2026-08-02: autonomous loops without a fast, trustworthy CI oracle are
51
+ compounding-error machines; 3 with a tripwire beats 5 on cost/benefit).
52
+ Hard ceiling: 5 — above that, re-invoke deliberately with fresh context.
53
+
54
+ **Halt-on-spin tripwire (checked after every loop, overrides the budget):**
55
+
56
+ - A loop ends with no material roadmap delta (no step added, removed,
57
+ re-scoped, or re-ordered) → STOP, the set has converged.
58
+ - The council splits on the same question twice → STOP, escalate that
59
+ question to the user instead of burning a third loop on it.
60
+ - Any validation target fails 3 consecutive refinement attempts → STOP
61
+ (N=3 budget, `autonomous-execution`).
62
+
63
+ ## Steps
64
+
65
+ ### Step 0 — Preflight (read-only)
66
+
67
+ 1. Live remote state first (`direct-answers` live-state law): fetch,
68
+ open PRs, recently merged work overlapping the scope — never from memory.
69
+ 2. Create or enter an isolated worktree on a fresh branch off the trunk
70
+ (branch/worktree creation is authorized by invoking this command; every
71
+ Hard-Floor action below stays gated).
72
+ 3. Honor any repo worktree-seeding convention when seeding the worktree;
73
+ never copy `.agent-settings.yml` into a worktree.
74
+ 4. Read the lock inventory: honest nulls, DR memories, `later/` resume
75
+ conditions, standing ADRs. These are constraints for Step 4, surfaced —
76
+ never silently relitigated (`decision-revisit-gate`).
77
+
78
+ ### Step 1 — Deep analysis (parallel subagents)
79
+
80
+ Fan out read-only analysis subagents over the repo's load-bearing surfaces
81
+ (token/context cost, execution flows, CI/PR pipeline, routing/activation,
82
+ decision debt, archived intelligence) plus — unless `--no-external` —
83
+ tree-level deep-dives of named external references (`external-reference-deep-dive`:
84
+ file trees + raw files, never README summaries). Each agent returns
85
+ structured findings with file:line evidence and an effort estimate.
86
+
87
+ ### Step 2 — Verification gate (non-negotiable)
88
+
89
+ Hand-verify every damning finding before it may steer the roadmap
90
+ (`plausible-mechanism-is-not-evidence`): re-run the grep/measurement the
91
+ finding rests on, in this checkout, at this SHA. A finding that fails
92
+ verification is dropped with a note. Findings colliding with a recorded
93
+ lock are marked and routed to Step 3 only if the mechanism differs
94
+ (mechanism-match test) — otherwise honored as locked.
95
+
96
+ ### Step 3 — Council pass
97
+
98
+ Run the AI council (`council:estimate` → `council:run --confirm`) on the
99
+ contested decisions only: priority order, roadmap topology, lock collisions
100
+ that pass the mechanism-match test, and the loop count when the user gave
101
+ none. Surface the fast-path marker verbatim where the low-impact path
102
+ resolves something. High-impact and user-required classes still reach the
103
+ user per `ai-council-config` — autonomy never rewires that floor.
104
+
105
+ ### Step 4 — Roadmap set
106
+
107
+ Author ONE central roadmap (goal, verified findings, locks honored,
108
+ sub-roadmap management table, pre-registered success criteria, provenance —
109
+ external sources anonymized + `ENC1:`-encrypted per `source-confidentiality`)
110
+ plus sub-roadmaps cut along the council's topology. Foundation-class
111
+ work (whatever must be true for the rest to be verifiable — typically the
112
+ CI oracle) gates the leverage-class work explicitly. Regenerate the
113
+ dashboard (`roadmap:progress`) in the same response as any roadmap write.
114
+
115
+ ### Step 5 — Pull request
116
+
117
+ Push the branch and open the PR per [`/create-pr`](../pr/create.md) — its
118
+ mechanics and the always-active PR-surface rules govern the body and reply
119
+ shape; do not restate them here.
120
+
121
+ ### Step 6 — Refinement loops (×N, autonomous)
122
+
123
+ Each loop: (a) re-read the roadmap set with fresh subagent reviewers
124
+ (adversarial: hunt over-building, missing evidence, lock violations,
125
+ sequencing errors); (b) resolve contested deltas in the council; (c) any
126
+ delta resting on a NEW factual claim re-enters the Step-2 verification gate
127
+ before application — reviewer assertions are findings, not facts; (d) apply
128
+ the surviving deltas to the roadmaps; (e) push to the same PR; (f) evaluate
129
+ the tripwire. Loop output is a delta summary in the PR description's
130
+ changelog section, not a comment (`no-pr-progress-comments`).
131
+
132
+ ## Output
133
+
134
+ - The PR URL (literal last line of the closing reply).
135
+ - Central + sub-roadmaps on the branch, dashboard regenerated.
136
+ - Council artifacts under `agents/runtime/council/` (local-only, auto-pruned).
137
+ - A one-paragraph verdict per refinement loop: what changed, what converged.
138
+
139
+ ## Gotchas
140
+
141
+ - Merge/deploy is where autonomy ends — Step 6 loop pushes go to the
142
+ already-open PR under the invocation's authorization; merging it,
143
+ deploying, or any irreversible external action stays this-turn gated.
144
+ - Council spend: estimate first; abort and surface if the configured budget
145
+ guard trips mid-run.
146
+ - Subagent cwd pins to the launch dir, not the worktree — pass absolute
147
+ paths into every subagent prompt.
@@ -2,19 +2,19 @@
2
2
  model_tier: medium
3
3
  name: optimize
4
4
  disable-model-invocation: true
5
- argument-hint: "[skills|agents-dir|augmentignore|rtk|project|prompt] [args]"
5
+ argument-hint: "[skills|agents-dir|augmentignore|rtk|project|prompt|deep] [args]"
6
6
  pack: meta
7
- intent: "Optimization dispatcher — skills, rtk, augmentignore, agents-dir, project sweep, prompt"
8
- routes_to: [optimize-skills, optimize-rtk, optimize-augmentignore, optimize-agents-dir, optimize-project, optimize-prompt]
7
+ intent: "Optimization dispatcher — skills, rtk, augmentignore, agents-dir, project sweep, prompt, deep autonomous loop"
8
+ routes_to: [optimize-skills, optimize-rtk, optimize-augmentignore, optimize-agents-dir, optimize-project, optimize-prompt, optimize-deep]
9
9
  replaces: []
10
10
  tier: 1
11
11
  visibility: advanced
12
- description: Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters, project (project-wide sweep), prompt (AI-prompt polish)
12
+ description: Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters, project (project-wide sweep), prompt (AI-prompt polish), deep (autonomous deep-refactoring loop)
13
13
  cluster: optimize
14
14
  type: orchestrator
15
15
  suggestion:
16
16
  eligible: true
17
- trigger_description: "optimize my skills, manage agents directory, tune augmentignore, optimize rtk filters, optimize this project, optimize this prompt"
17
+ trigger_description: "optimize my skills, manage agents directory, tune augmentignore, optimize rtk filters, optimize this project, optimize this prompt, run a deep optimization pass"
18
18
  trigger_context: "maintainer auditing/trimming the agent layer, running a project-wide optimization sweep, or polishing an AI prompt (NOT AGENTS.md — that's /agents)"
19
19
  workspaces:
20
20
  - agent-config-maintainer
@@ -42,6 +42,7 @@ the **agent layer** (skills, agents-dir, augmentignore, rtk), the **project**
42
42
  | `/optimize rtk` | `commands/optimize/rtk.md` | Create or refine project-local rtk filters |
43
43
  | `/optimize project` | `commands/optimize/project.md` | Project-wide optimization sweep — inventory roadmaps/ADRs/agent folders, challenge stale decisions, emit new roadmap(s) |
44
44
  | `/optimize prompt` | `commands/optimize/prompt.md` | Optimize a raw prompt for ChatGPT/Claude/Gemini via the 4-D methodology |
45
+ | `/optimize deep` | `commands/optimize/deep.md` | Autonomous deep-refactoring loop — subagent analysis, council, central + sub-roadmaps, PR, N refinement loops (default 3) |
45
46
 
46
47
  Sub-command names match the locked contract in
47
48
  [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
@@ -60,14 +61,19 @@ Sub-command names match the locked contract in
60
61
  > 4. rtk — create or refine project-local rtk filters
61
62
  > 5. project — project-wide sweep (roadmaps, ADRs, decisions → new roadmaps)
62
63
  > 6. prompt — polish a raw AI prompt (4-D methodology)
64
+ > 7. deep — autonomous deep-refactoring loop (analysis → council → roadmaps → PR → refine ×N)
63
65
 
64
66
  ## Rules
65
67
 
66
68
  - **Suggest only — never auto-apply.** All `/optimize` sub-commands are
67
69
  audit-grade: they report and propose, but the user approves every change.
70
+ Exception: `deep` is the explicitly autonomous variant — invoking it IS the
71
+ approval for its worktree/branch/roadmap/PR flow; the Hard Floor
72
+ (merge/deploy/prod/bulk-delete) still gates inside it.
68
73
  - **Scope check before routing.** Agent-layer subs (1–4) never touch project
69
74
  code or roadmaps; `project` never rewrites the agent layer; `prompt` only
70
- returns a rewritten prompt.
75
+ returns a rewritten prompt; `deep` writes roadmaps + a PR branch but never
76
+ merges.
71
77
  - **Do NOT chain sub-commands.** One `/optimize <sub>` per turn.
72
78
  - If the user invokes `/optimize` with no argument, **show the menu** — do
73
79
  not guess which sub-command they meant.
@@ -4,8 +4,6 @@ tier: "2b"
4
4
  alwaysApply: false
5
5
  description: "Spotted an issue (security gap, missing test, bad code, duplication, stale idiom) — never ignore: small→fix inline, bigger→ask, many→follow-up PR"
6
6
  triggers:
7
- - intent: "spotted an unrelated issue while working"
8
- - intent: "found legacy or duplicated code"
9
7
  - keyword: "refactor"
10
8
  - keyword: "duplicate"
11
9
  - keyword: "legacy"
@@ -7,7 +7,6 @@ triggers:
7
7
  - keyword: "controller"
8
8
  - keyword: "service"
9
9
  - keyword: "module"
10
- - intent: "structural decision"
11
10
  routes_to:
12
11
  - "skill:module-detect-on-the-fly"
13
12
  workspaces: [agent-config-maintainer, engineering]
@@ -4,10 +4,6 @@ tier: "2a"
4
4
  alwaysApply: false
5
5
  description: "New or significantly rewritten skill/rule/command/guideline — mandatory Understand → Research → Draft first"
6
6
  triggers:
7
- - intent: "create new skill"
8
- - intent: "create new rule"
9
- - intent: "create new command"
10
- - intent: "create new guideline"
11
7
  - phrase: "new skill"
12
8
  - phrase: "new rule"
13
9
  - phrase: "new command"
@@ -8,9 +8,8 @@ load_context:
8
8
  - ../contexts/execution/autonomy-mechanics.md
9
9
  - ../contexts/execution/autonomy-examples.md
10
10
  triggers:
11
- - intent: "trivial workflow question"
12
- - intent: "autonomy mode"
13
11
  - keyword: "personal.autonomy"
12
+ - phrase: "autonomy mode"
14
13
  workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
15
14
  packs: [meta]
16
15
  ---
@@ -4,8 +4,6 @@ tier: "2a"
4
4
  alwaysApply: false
5
5
  description: "Endpoint/query on user/tenant data — authenticated ≠ authorized: server-derived ownership/tenant/role + negative tests (401/non-owner/cross-tenant)"
6
6
  triggers:
7
- - intent: "returning user or tenant data"
8
- - intent: "adding an endpoint that reads a record by id"
9
7
  - keyword: "endpoint"
10
8
  - keyword: "route"
11
9
  - keyword: "authorization"
@@ -4,9 +4,6 @@ tier: "2b"
4
4
  alwaysApply: false
5
5
  description: "Writing/editing code — a comment states a WHY or constraint the code cannot show; never restate what names/types say; no signature-mirroring docblocks"
6
6
  triggers:
7
- - intent: "writing or generating code"
8
- - intent: "adding a class / method / function"
9
- - intent: "refactoring code"
10
7
  - keyword: "comment"
11
8
  - keyword: "docblock"
12
9
  - keyword: "phpdoc"
@@ -4,9 +4,6 @@ tier: "2a"
4
4
  alwaysApply: false
5
5
  description: "Porting/adapting external code (algorithm, structure, >~10 lines) — close the source, re-derive; conscious borrows need a ledger entry + license check"
6
6
  triggers:
7
- - intent: "porting or adapting code from an external source"
8
- - intent: "implementing an algorithm or structure seen in another project"
9
- - intent: "reusing a snippet from online / another repo / a training-data recall"
10
7
  - keyword: "port this"
11
8
  - keyword: "adapt this"
12
9
  - keyword: "based on this repo"
@@ -3,11 +3,10 @@ type: "auto"
3
3
  tier: "2b"
4
4
  alwaysApply: false
5
5
  description: "Multi-step or continuation replies carry a red thread — goal once, each turn tied to it, name what changed, close with one end-summary"
6
- triggers:
7
- - intent: "producing a multi-step or continuation reply"
8
- - intent: "reporting progress on ongoing work"
9
6
  workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
10
7
  packs: [meta]
8
+ triggers:
9
+ - phrase: "reporting progress"
11
10
  ---
12
11
 
13
12
  # Communication Through-Line
@@ -3,8 +3,6 @@ type: "auto"
3
3
  tier: "2a"
4
4
  description: "Cap verbatim quoting from external sources — 15 words max per quote, one quote per source, never a complete short work, paraphrase by default"
5
5
  triggers:
6
- - intent: "drafting content from a source"
7
- - intent: "summarizing an external document"
8
6
  - keyword: "quote"
9
7
  - keyword: "excerpt"
10
8
  - keyword: "verbatim"
@@ -4,10 +4,8 @@ tier: "1"
4
4
  alwaysApply: false
5
5
  description: "Debugging, fixing errors, or long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers"
6
6
  triggers:
7
- - intent: "long conversation"
8
- - intent: "tool loop"
9
- - intent: "fresh chat"
10
7
  - keyword: "3-failure"
8
+ - phrase: "long conversation"
11
9
  routes_to:
12
10
  - "guideline:agent-infra/context-hygiene-mechanics"
13
11
  workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
@@ -5,8 +5,6 @@ description: "Beneficial change blocked by a lock (honest-null, don't-relitigate
5
5
  alwaysApply: false
6
6
  council_depth: deep
7
7
  triggers:
8
- - intent: "blocked by prior decision"
9
- - intent: "revisit past verdict"
10
8
  - keyword: "don't relitigate"
11
9
  - keyword: "honest null"
12
10
  - keyword: "already decided"
@@ -9,10 +9,21 @@ triggers:
9
9
  - keyword: "design system"
10
10
  - keyword: "design spec"
11
11
  - keyword: "Figma"
12
+ - keyword: "handoff"
13
+ - keyword: "Claude Design"
12
14
  - phrase: "match the design"
13
15
  - phrase: "build this design"
14
16
  - phrase: "design fidelity"
15
17
  - phrase: "stick to the design"
18
+ - phrase: "design.html"
19
+ - phrase: "attached artifact"
20
+ - phrase: "provided artifact"
21
+ - phrase: "übernimm das design"
22
+ - phrase: "baue das nach"
23
+ - phrase: "bau das nach"
24
+ - phrase: "1:1 um"
25
+ - phrase: "1:1 nach"
26
+ - file_pattern: "*design.html"
16
27
  applies_to_user_types:
17
28
  - "creator"
18
29
  - "developer"
@@ -73,6 +84,24 @@ porting, or modifying UI to match it.
73
84
  - The user explicitly invites exploration ("show me options", "redesign this", "improve the layout") — that authorises deviation for that turn.
74
85
  - Non-UI surfaces (scripts, CLI, backend).
75
86
 
87
+ ## Routing — an attached artifact is a trigger, an attached HTML file is not
88
+
89
+ Matching is plain lower-cased substring containment on the prompt, plus fnmatch
90
+ over the open files. Three handover classes must reach this rule: an English
91
+ phrasing, a German one, and a prompt carrying **no** keyword at all because the
92
+ artifact is simply attached. The last is covered by `file_pattern: *design.html`
93
+ — the conventional handover filename, not `*.html`, which would fire on every
94
+ HTML edit in every project and be strictly worse than the gap it closes. A
95
+ handover under some other filename needs one word in the prompt.
96
+
97
+ The trigger set is deliberately phrase-heavy on the German side and on
98
+ `artifact`: a bare `artifact` keyword fires on "the CI build artifact is 40 MB".
99
+ `ROUTING_MATRIX` in
100
+ [`design_fidelity_routing.test.ts`](../../tests/scripts/design_fidelity_routing.test.ts)
101
+ pins both halves — every class that must route, and the near-misses that must
102
+ stay silent (fixture `daf-port-trigger-de`). Extending the set without adding a
103
+ near-miss row there is how an over-broad trigger lands.
104
+
76
105
  Body migrated to [`guideline:design-fidelity-mechanics`](../docs/guidelines/design-fidelity-mechanics.md) (per P4 of `road-to-kernel-and-router.md`) — surgical visual edits (targeted-edit vs redesign-trigger discipline, stable anchors), asset & imagery discipline (owned-asset path, third-party delivery is self-hosted by default, real-imagery-as-proof, iconography floor, no unrequested filler), deviation-surfacing shape, failure-mode catalog, `daf-*` fixtures.
77
106
  Trigger-set above activates this routing on demand, independent of the discipline profile (ADR-110).
78
107
 
@@ -4,9 +4,6 @@ tier: "2b"
4
4
  alwaysApply: false
5
5
  description: "Adopting a new domain track (mobile, ML, IoT…) — demand/owner/CI gates BEFORE harvest"
6
6
  triggers:
7
- - intent: "adopt new domain"
8
- - intent: "harvest new domain track"
9
- - intent: "open a domain plate"
10
7
  - keyword: "mobile track"
11
8
  - keyword: "ml track"
12
9
  - keyword: "blockchain track"
@@ -4,7 +4,6 @@ tier: "2b"
4
4
  alwaysApply: false
5
5
  description: "After EVERY code edit, find ALL downstream changes — callers, tests, imports, types, documentation"
6
6
  triggers:
7
- - intent: "after code edit"
8
7
  - keyword: "callers"
9
8
  - keyword: "imports"
10
9
  - keyword: "downstream"
@@ -81,6 +80,16 @@ Next.js / Python / Go) live in [`agent-docs-writing`](../skills/agent-docs-writi
81
80
  Before making a change that affects a **public API** (endpoint response, service method signature,
82
81
  event payload, job constructor), assess the impact:
83
82
 
83
+ **Why the surface, not just the contract, is the thing to keep small** (Hyrum's
84
+ Law): with enough consumers, every *observable* behaviour of a system becomes
85
+ something somebody depends on, regardless of what the documented contract
86
+ promises — iteration order, an error message's wording, a timing side effect, a
87
+ field that happens to be present. Two consequences, and they point in opposite
88
+ directions. Adding: a smaller exported surface is fewer accidental contracts to
89
+ honour later, so do not export what the caller does not need. Removing: the
90
+ list above is a floor, not a ceiling — an observable behaviour nobody documented
91
+ can still break someone when it disappears.
92
+
84
93
  ### Always ask the user first when:
85
94
 
86
95
  - Removing or renaming a public method/class
@@ -4,13 +4,6 @@ tier: "2b"
4
4
  description: "User names an external repo/file/URL as reference — fetch the actual tree and inspect; never summarize from README"
5
5
  alwaysApply: false
6
6
  triggers:
7
- - intent: "look at how X does it"
8
- - intent: "compare with reference repo"
9
- - intent: "use as template / vorlage"
10
- - intent: "wie macht es X"
11
- - intent: "vergleiche mit Y"
12
- - intent: "schau dir Z an"
13
- - intent: "study this competitor"
14
7
  - keyword: "github.com/"
15
8
  - keyword: "source of truth"
16
9
  - phrase: "reference repo"
@@ -7,7 +7,6 @@ triggers:
7
7
  - keyword: "fast-path"
8
8
  - keyword: "Resolved via low-impact council"
9
9
  - keyword: "low_impact"
10
- - intent: "low-impact council dispatch"
11
10
  validator_ignore:
12
11
  - type: "substring"
13
12
  pattern: ".agent-src.uncondensed/"
@@ -4,13 +4,6 @@ tier: "2a"
4
4
  alwaysApply: false
5
5
  description: "Git history — no unasked rebase/squash/amend; never drop foreign commits; pushed rewrite → re-push same turn"
6
6
  triggers:
7
- - intent: "rebase the branch"
8
- - intent: "squash commits"
9
- - intent: "clean up commit history"
10
- - intent: "fold this into the previous commit"
11
- - intent: "tidy history after pushing"
12
- - intent: "reseat the branch base"
13
- - intent: "exclude these commits from the branch"
14
7
  - keyword: "git rebase"
15
8
  - keyword: "rebase --onto"
16
9
  - keyword: "reset --hard"
@@ -6,8 +6,6 @@ alwaysApply: false
6
6
  load_context:
7
7
  - ../contexts/communication/rules-auto/guidelines-mechanics.md
8
8
  triggers:
9
- - intent: "writing code"
10
- - intent: "reviewing code"
11
9
  - keyword: "convention"
12
10
  workspaces: [agent-config-maintainer, engineering]
13
11
  packs: [meta]
@@ -5,8 +5,6 @@ description: "Before features or architectural changes — validate against exis
5
5
  alwaysApply: false
6
6
  council_depth: deep
7
7
  triggers:
8
- - intent: "implement feature"
9
- - intent: "architectural change"
10
8
  - keyword: "refactor"
11
9
  - keyword: "implement"
12
10
  - keyword: "migration"
@@ -42,6 +40,10 @@ Before implementing:
42
40
 
43
41
  On a "build me an app / add this feature" ask, ONE reflexive pre-check before the three checks: **who asked · what breaks if unbuilt · what's the evidence?** Recommend **build** only at a real retention/activation blocker (evidence, not anxiety); else **defer/validate**, naming the missing evidence. Advisory — "just build it" proceeds immediately; no network lookup. Hierarchy + build/defer table: guideline § 8-pre.
44
42
 
43
+ ## The solution-size ladder — stop at the first rung that works
44
+
45
+ Once the demand gate says build, "does this already exist?" has an **ordered** answer set: need-to-exist → reuse-in-repo → stdlib / framework → **native platform** → installed dependency → smallest working form. Stop at the first rung that carries the requirement. Ordered **after** comprehension — it shortens the solution, never the reading. Two axes, not one: the ladder is *scope*; **shape** is the other half — of what must exist, the form with the least cognitive load, explicitly not the fewest keystrokes. Rungs, the platform-rung examples, and the precedence order when they pull against each other: guideline § 8b-ladder / § 8b-shape / § 8b-precedence.
46
+
45
47
  ## The three checks
46
48
 
47
49
  Run, in order: **1. Is the request clear?** · **2. Does it fit the existing architecture?** · **3. Is the approach sound?**
@@ -5,10 +5,6 @@ description: "Before executing a complex plan — ask 'am I solving the right pr
5
5
  alwaysApply: false
6
6
  council_depth: deep
7
7
  triggers:
8
- - intent: "complex plan"
9
- - intent: "design decision"
10
- - intent: "architectural plan"
11
- - intent: "multi-step implementation"
12
8
  - keyword: "plan"
13
9
  - keyword: "design"
14
10
  - keyword: "architecture"
@@ -4,8 +4,6 @@ tier: "2b"
4
4
  alwaysApply: false
5
5
  description: "IDE-attached sibling repo detected — prompt once to opt into cross-repo awareness, persist local-only"
6
6
  triggers:
7
- - intent: "work across two projects"
8
- - intent: "sibling repository"
9
7
  - keyword: "linked project"
10
8
  - keyword: "cross-repo"
11
9
  - keyword: "sibling repo"
@@ -4,7 +4,6 @@ tier: "2b"
4
4
  description: "Generating markdown with code blocks — prevent broken nesting"
5
5
  alwaysApply: false
6
6
  triggers:
7
- - intent: "markdown with code blocks"
8
7
  - keyword: "triple backticks"
9
8
  - file_pattern: "*.md"
10
9
  workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
@@ -4,11 +4,11 @@ tier: "2a"
4
4
  alwaysApply: false
5
5
  description: "Writing or reviewing a diff — smallest change that solves the problem; no drive-by edits or reformatting"
6
6
  triggers:
7
- - intent: "writing a diff"
8
- - intent: "reviewing a diff"
9
7
  - keyword: "drive-by"
10
8
  - keyword: "rewrite"
11
9
  - keyword: "fix"
10
+ - phrase: "from scratch"
11
+ - phrase: "second system"
12
12
  routes_to:
13
13
  - "guideline:agent-infra/minimal-safe-diff-mechanics"
14
14
  workspaces: [engineering]
@@ -5,7 +5,6 @@ description: "CLI tool needed for the task is not installed — ask before worki
5
5
  triggers:
6
6
  - keyword: "command not found"
7
7
  - keyword: "not installed"
8
- - intent: "install tool"
9
8
  routes_to:
10
9
  - "guideline:agent-infra/missing-tool-handling"
11
10
  workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
@@ -4,9 +4,6 @@ tier: "3"
4
4
  alwaysApply: false
5
5
  description: "PR/issue/comment/commit bodies — no 'Generated with' / 'Co-authored by' / 'opened by' attribution footers"
6
6
  triggers:
7
- - intent: "PR body"
8
- - intent: "commit message"
9
- - intent: "Jira comment"
10
7
  - keyword: "co-authored"
11
8
  workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
12
9
  packs: [meta]
@@ -4,13 +4,16 @@ tier: "3"
4
4
  alwaysApply: false
5
5
  description: "PR/issue/commit titles and comments — no decorative emojis; bodies only with an in-artifact legend"
6
6
  triggers:
7
- - intent: "PR title"
8
- - intent: "PR body"
9
- - intent: "commit message"
10
- - intent: "issue title"
11
- - intent: "post PR comment"
12
7
  - keyword: "gh pr create"
13
8
  - keyword: "git commit"
9
+ - keyword: "🤖"
10
+ - keyword: "🚀"
11
+ - keyword: "🎉"
12
+ - keyword: "✨"
13
+ - keyword: "🔥"
14
+ - keyword: "💡"
15
+ - keyword: "👍"
16
+ - keyword: "❤️"
14
17
  workspaces: [agent-config-maintainer, engineering]
15
18
  packs: [meta]
16
19
  ---
@@ -4,11 +4,9 @@ tier: "2a"
4
4
  alwaysApply: false
5
5
  description: "PR comments — no unsolicited progress/status/CI narration unless personal.pr_progress_comments is true"
6
6
  triggers:
7
- - intent: "post PR comment"
8
- - intent: "PR status update"
9
- - intent: "CI fix progress"
10
7
  - keyword: "gh pr comment"
11
8
  - keyword: "PullRequestComment"
9
+ - phrase: "status comment"
12
10
  workspaces: [agent-config-maintainer, engineering]
13
11
  packs: [meta]
14
12
  ---
@@ -8,8 +8,6 @@ triggers:
8
8
  - path_prefix: "agents/runtime/council/questions/"
9
9
  - path_prefix: "agents/runtime/council/responses/"
10
10
  - path_prefix: "agents/runtime/council/sessions/"
11
- - intent: "link from stable artifact"
12
- - intent: "link to council artefact"
13
11
  routes_to:
14
12
  - "skill:ai-council"
15
13
  - "skill:agent-docs-writing"
@@ -3,7 +3,6 @@ type: "auto"
3
3
  tier: "2a"
4
4
  description: "No placeholder prose in generated code/UI — no truncation shorthands; on budget overflow emit a clean PAUSED breakpoint"
5
5
  triggers:
6
- - intent: "generating code or multi-section output"
7
6
  - keyword: "// rest of component"
8
7
  - keyword: "for brevity"
9
8
  - keyword: "rest follows the same pattern"
@@ -4,8 +4,6 @@ tier: "2b"
4
4
  alwaysApply: false
5
5
  description: "Field with multiple non-boolean states — prefer an enum over string/numeric literals; old-style literals found → note, finish the task, ask after"
6
6
  triggers:
7
- - intent: "modeling a field with multiple states"
8
- - intent: "adding a status or type field"
9
7
  - keyword: "enum"
10
8
  - keyword: "status"
11
9
  - keyword: "kind"
@@ -4,9 +4,6 @@ tier: "2b"
4
4
  alwaysApply: false
5
5
  description: "Merging/refactoring/condensing skills, rules, commands, or guidelines — prevent quality loss"
6
6
  triggers:
7
- - intent: "merge skill"
8
- - intent: "condense rule"
9
- - intent: "refactor artifact"
10
7
  - keyword: "Iron Law"
11
8
  validator_ignore:
12
9
  - type: "substring"
@@ -6,7 +6,6 @@ alwaysApply: false
6
6
  triggers:
7
7
  - keyword: "active_role"
8
8
  - keyword: "role-mode"
9
- - intent: "mode marker"
10
9
  workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
11
10
  packs: [meta]
12
11
  ---
@@ -4,8 +4,6 @@ tier: "2a"
4
4
  alwaysApply: false
5
5
  description: "Writing a credential into a tracked file or committing one in any VCS (git/svn/hg) — STOP, show the match, ask, offer alternatives; never silently"
6
6
  triggers:
7
- - intent: "writing a credential or API key into a file"
8
- - intent: "committing or staging changes that may contain a secret"
9
7
  - keyword: "secret"
10
8
  - keyword: "password"
11
9
  - keyword: "credential"