heimdall-agent 1.1.0 → 1.4.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.
- package/README.md +101 -31
- package/README.pt-BR.md +124 -40
- package/agents/code-sentinel.md +7 -1
- package/agents/frontend-designer.md +6 -1
- package/agents/modernizer.md +8 -3
- package/agents/orchestrator.md +22 -8
- package/agents/reviewer.md +3 -1
- package/config/agents.json +177 -5
- package/config/mcp.json +1 -1
- package/config/mcp.resolved.json +74 -0
- package/config/mcp.template.json +85 -0
- package/config/models.json +70 -0
- package/config/profiles.json +4 -3
- package/config/skills.json +321 -93
- package/docs/SKILLS.md +158 -75
- package/docs/designs/old/2026-11-16 upstream-skill-sync-and-provenance-links.md +60 -0
- package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
- package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
- package/doctrine/AGENTS.md +7 -4
- package/hooks/heimdall-hook.cjs +16 -1
- package/hooks/hooks.json +11 -0
- package/lib/catalog-sync.cjs +8 -3
- package/lib/model-context.cjs +50 -1
- package/lib/model-router.cjs +294 -0
- package/package.json +1 -1
- package/playbooks/01-interactive-grilling-gate.md +14 -10
- package/playbooks/03-adversarial-code-review.md +12 -4
- package/playbooks/05-canonical-plan-template.md +8 -13
- package/playbooks/06-model-registry-matrix.md +27 -19
- package/readme.html +1006 -0
- package/setup.mjs +317 -206
- package/skills/antislop-copywriting/SKILL.md +36 -1
- package/skills/brainstorming/SKILL.md +60 -38
- package/skills/codebase-design/DEEPENING.md +37 -0
- package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
- package/skills/codebase-design/SKILL.md +114 -0
- package/skills/communication-doctrine/SKILL.md +2 -2
- package/skills/domain-modeling/ADR-FORMAT.md +47 -0
- package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
- package/skills/domain-modeling/SKILL.md +74 -0
- package/skills/executing-plans/SKILL.md +6 -4
- package/skills/grill-me/SKILL.md +65 -0
- package/skills/handoff/SKILL.md +77 -0
- package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
- package/skills/improve-codebase-architecture/SKILL.md +71 -0
- package/skills/mcp-cleanup/SKILL.md +61 -0
- package/skills/mcp-sync/SKILL.md +58 -0
- package/skills/modern-web-guidance/SKILL.md +90 -0
- package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
- package/skills/owasp-security/reference/languages.md +378 -372
- package/skills/owasp-security/reference/owasp-report.md +1144 -1140
- package/skills/owasp-security/reference/review-checklist.md +134 -132
- package/skills/ruminate/SKILL.md +140 -0
- package/skills/subagent-driven-development/SKILL.md +7 -4
- package/skills/taste-skill/SKILL.md +367 -534
- package/skills/to-spec/SKILL.md +75 -0
- package/skills/to-tickets/SKILL.md +105 -0
- package/skills/upstream-skill-sync/SKILL.md +46 -0
- package/skills/wayfinder/SKILL.md +128 -0
- package/skills/writing-plans/SKILL.md +1 -1
|
@@ -123,7 +123,8 @@ The workspace and ledger are shared with superpowers:subagent-driven-development
|
|
|
123
123
|
and the new one resumes from the same ledger.
|
|
124
124
|
|
|
125
125
|
- Each plan owns a workspace: at skill start, run
|
|
126
|
-
`../subagent-driven-development/scripts/sdd-workspace PLAN_FILE`
|
|
126
|
+
`../subagent-driven-development/scripts/sdd-workspace PLAN_FILE` by its
|
|
127
|
+
absolute path, from the working tree you're executing in — it
|
|
127
128
|
prints the plan's git-ignored directory
|
|
128
129
|
(`<repo-root>/.superpowers/sdd/<plan-basename>/`), home to every
|
|
129
130
|
artifact for THIS plan: ledger, briefs, review packages. Another plan's
|
|
@@ -169,7 +170,8 @@ in the workspace and read its tail; read a brief, not the whole plan.
|
|
|
169
170
|
|
|
170
171
|
### 1. Take the task
|
|
171
172
|
|
|
172
|
-
- Run this skill's `scripts/task-start PLAN_FILE N
|
|
173
|
+
- Run this skill's `scripts/task-start PLAN_FILE N` by its absolute path,
|
|
174
|
+
from the working tree you're executing in. It prints the brief
|
|
173
175
|
path and BASE (the commit the task's range is cut from) in one call.
|
|
174
176
|
Read the brief for every task, including ones you remember from setup:
|
|
175
177
|
what you remember is a summary, the brief has the exact values,
|
|
@@ -222,7 +224,7 @@ the claim. If any item is missing, the task is not complete: finish it.
|
|
|
222
224
|
### 4. Complete the task
|
|
223
225
|
|
|
224
226
|
Run this skill's `scripts/task-done PLAN_FILE N BASE -- <test command>`
|
|
225
|
-
with the test command the brief names for the whole task. It runs the
|
|
227
|
+
by its absolute path, from the working tree you're executing in, with the test command the brief names for the whole task. It runs the
|
|
226
228
|
tests, keeps the full output in the workspace, prints the tail, and — only
|
|
227
229
|
if they pass — appends the completion line to the ledger:
|
|
228
230
|
|
|
@@ -234,7 +236,7 @@ mark the todo complete and take the next task.
|
|
|
234
236
|
## Final Review
|
|
235
237
|
|
|
236
238
|
Run `../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD`
|
|
237
|
-
(MERGE_BASE = the commit the branch started from, e.g.
|
|
239
|
+
by its absolute path, from the working tree you're executing in (MERGE_BASE = the commit the branch started from, e.g.
|
|
238
240
|
`git merge-base main HEAD`) and review from the file it prints.
|
|
239
241
|
|
|
240
242
|
**With a subagent tool:** dispatch the reviewer on the most capable
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: grill-me
|
|
3
|
+
description: Relentlessly interview the user to stress-test and sharpen a plan, architecture, or design before implementation. Use when planning features, resolving tradeoffs, or when the user invokes /grill-me.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# The Grilling Protocol (Stress-Test & Sharpen Plans)
|
|
7
|
+
|
|
8
|
+
Interview the user relentlessly until you reach an airtight shared understanding. Map the problem space as a **design tree**: every decision branches into the decisions that hang off it.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 1. The Design Tree Frontier (Round-by-Round)
|
|
13
|
+
|
|
14
|
+
Work the design tree in **rounds**.
|
|
15
|
+
- The **frontier** is every decision whose prerequisites are already settled: the questions you can ask *now* without guessing at answers you haven't heard yet.
|
|
16
|
+
- Ask the whole frontier in one round: number each question and provide your concrete recommendation.
|
|
17
|
+
- **Dependency Rule**: If Question B depends on the choice made in Question A, Question B does NOT belong in this round. It belongs in a *subsequent* round once Question A is resolved.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 2. The "Yes-to-Approve" Triage Format
|
|
22
|
+
|
|
23
|
+
Always format questions so the user can quickly accept your recommendations with minimal keystrokes (e.g. replying *"1: yes, 2: yes, 3: no do Y"*):
|
|
24
|
+
|
|
25
|
+
```markdown
|
|
26
|
+
❓ **Q1 - <Decision Title>**: <Context, boundary conditions, edge cases, and options>
|
|
27
|
+
|
|
28
|
+
➡️ **Recommended**: <Your recommended answer and justification>
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
❓ **Q2 - <Decision Title>**: <Context, boundary conditions, edge cases, and options>
|
|
33
|
+
|
|
34
|
+
➡️ **Recommended**: <Your recommended answer and justification>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**Rule**: Word each question and recommendation so answering *"yes"* or *"accept"* selects your recommended path.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 3. Autonomous Fact-Finding Invariant (Zero Lazy Questions)
|
|
42
|
+
|
|
43
|
+
**Finding facts is your job, never the user's.**
|
|
44
|
+
- If a question hinges on a fact from the repository (e.g., existing middleware, schema types, installed package versions, API endpoints, config flags):
|
|
45
|
+
- **Look it up autonomously** using filesystem tools, greps, and doc inspections before asking.
|
|
46
|
+
- Never ask the user for anything you can discover yourself.
|
|
47
|
+
- Only present decisions, requirements, and business trade-offs that cannot be answered by the code.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 4. ADR & Documentation Integration
|
|
52
|
+
|
|
53
|
+
When grilling uncovers settled architectural decisions for significant or multi-system features:
|
|
54
|
+
- Record each settled decision in an **Architectural Decision Record (ADR)** under `docs/adr/YYYY-MM-DD-<decision>.md` (or the project's designated ADR directory).
|
|
55
|
+
- Keep ADRs compact: Context, Decision, Invariants, Consequences.
|
|
56
|
+
- Maintain consistent domain terminology in the project's domain docs or glossary.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 5. Exit Criteria
|
|
61
|
+
|
|
62
|
+
The grilling session is complete when:
|
|
63
|
+
1. The decision frontier is empty (all branches visited, zero hidden assumptions).
|
|
64
|
+
2. The user has confirmed the proposed recommendations or made their adjustments.
|
|
65
|
+
3. The agreed scope is ready to be compiled into a specification or plan (`to-spec` / `writing-plans` / `05-canonical-plan-template.md`).
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: handoff
|
|
3
|
+
description: Compact the current conversation and session context into an isolated handoff document so a fresh agent or subagent can pick up work without drift.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# The Handoff Protocol
|
|
7
|
+
|
|
8
|
+
When ending a session, switching agent contexts, or spawning a fresh child agent (e.g. via `invoke_subagent`, `herdr`, or `claude --bg`), create a lean, structured handoff document.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 0. Auto-Trigger on Coherence Degradation (MANDATORY)
|
|
13
|
+
|
|
14
|
+
Invoke this skill **proactively** — without waiting for an explicit user request — when you detect any of the following signals in your own output:
|
|
15
|
+
- Contradictory statements within the same turn or across recent turns
|
|
16
|
+
- Lost task thread: unable to state the current objective without re-reading prior context
|
|
17
|
+
- Repeated self-corrections (3+ corrections to your own output in a single turn)
|
|
18
|
+
- Hallucinated state that contradicts prior tool results or file contents
|
|
19
|
+
- User has said "loop", "stuck", "drip", "hallucinating", or requested a fresh start
|
|
20
|
+
|
|
21
|
+
When auto-triggered, announce: "Detected coherence degradation. Invoking handoff protocol to preserve context." Then execute the full protocol below. Do NOT continue working after detecting these signals. Extracted from 187 sessions via `/ruminate`.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 1. Zero-Duplication & Pointer-First Principle
|
|
26
|
+
|
|
27
|
+
Do **not** dump raw source code, large file bodies, verbose conversational histories, or full plan duplicates into the handoff artifact.
|
|
28
|
+
- **Reference existing artifacts by path or commit hash**:
|
|
29
|
+
- Plan / Spec: `docs/designs/YYYY-MM-DD-<feature>.md`
|
|
30
|
+
- ADRs: `docs/adr/`
|
|
31
|
+
- Git branch & diff: `feature/xyz` (`git diff origin/main..HEAD`)
|
|
32
|
+
- Failing test paths: `tests/integration/...`
|
|
33
|
+
- **Redact secrets**: Strip API keys, session tokens, or sensitive credentials.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 2. Storage Location
|
|
38
|
+
|
|
39
|
+
Write the handoff file to the operating system's temporary directory to avoid polluting the git working tree:
|
|
40
|
+
- **Windows**: `$env:TEMP\handoff-<feature>-<timestamp>.md` (e.g. `C:\Users\<user>\AppData\Local\Temp\...`)
|
|
41
|
+
- **Linux / macOS**: `/tmp/handoff-<feature>-<timestamp>.md`
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 3. Mandatory Document Structure
|
|
46
|
+
|
|
47
|
+
A handoff document must follow this template:
|
|
48
|
+
|
|
49
|
+
```markdown
|
|
50
|
+
# Session Handoff: <Feature or Task Name>
|
|
51
|
+
|
|
52
|
+
### 1. Status & Blast Radius
|
|
53
|
+
- **Current State**: [WIP / Blocked / Ready for Verification / Awaiting Review]
|
|
54
|
+
- **Target Branch**: `<branch-name>`
|
|
55
|
+
- **Last Verified Commit**: `<short-hash>` (or unstaged changes in working copy)
|
|
56
|
+
|
|
57
|
+
### 2. Settled Decisions & Pointers
|
|
58
|
+
- **Spec / Plan**: [docs/designs/YYYY-MM-DD-feature.md](file:///path/to/spec)
|
|
59
|
+
- **ADR**: [docs/adr/...](file:///path/to/adr)
|
|
60
|
+
- **Decided Invariants**: <1-2 bullet summary of settled boundaries>
|
|
61
|
+
|
|
62
|
+
### 3. Open Frontier & Next Immediate Actions
|
|
63
|
+
1. <Exact first command or test to execute>
|
|
64
|
+
2. <Expected failure or next component to modify>
|
|
65
|
+
|
|
66
|
+
### 4. Suggested Skills for Next Agent
|
|
67
|
+
- `<skill-name-1>`: <Why the next agent should call this skill>
|
|
68
|
+
- `<skill-name-2>`: <Why the next agent should call this skill>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 4. Seeding the Next Agent
|
|
74
|
+
|
|
75
|
+
- **Antigravity / Subagent**: Launch the subagent with the handoff path or concise summary containing the pointer.
|
|
76
|
+
- **Claude Code CLI**: Run `claude --bg --name "<Task Name>" -- "$(cat <path-to-temp-handoff>)"`. Passing via file keeps the shell from misinterpreting special characters (`$`, backticks).
|
|
77
|
+
- **Herdr Multiplexing**: Seed the target agent pane via `herdr agent prompt <agent> "..."`.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# HTML Report Format
|
|
2
|
+
|
|
3
|
+
The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
|
|
4
|
+
|
|
5
|
+
## Scaffold
|
|
6
|
+
|
|
7
|
+
```html
|
|
8
|
+
<!doctype html>
|
|
9
|
+
<html lang="en">
|
|
10
|
+
<head>
|
|
11
|
+
<meta charset="utf-8" />
|
|
12
|
+
<title>Architecture review for {{repo name}}</title>
|
|
13
|
+
<script src="https://cdn.tailwindcss.com"></script>
|
|
14
|
+
<script type="module">
|
|
15
|
+
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
|
|
16
|
+
mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
|
|
17
|
+
</script>
|
|
18
|
+
<style>
|
|
19
|
+
/* small custom layer for things Tailwind doesn't cover cleanly:
|
|
20
|
+
dashed seam lines, hand-drawn-feeling arrow heads, etc. */
|
|
21
|
+
.seam { stroke-dasharray: 4 4; }
|
|
22
|
+
.leak { stroke: #dc2626; }
|
|
23
|
+
.deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
|
|
24
|
+
</style>
|
|
25
|
+
</head>
|
|
26
|
+
<body class="bg-stone-50 text-slate-900 font-sans">
|
|
27
|
+
<main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
|
|
28
|
+
<header>...</header>
|
|
29
|
+
<section id="candidates" class="space-y-10">...</section>
|
|
30
|
+
<section id="top-recommendation">...</section>
|
|
31
|
+
</main>
|
|
32
|
+
</body>
|
|
33
|
+
</html>
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Header
|
|
37
|
+
|
|
38
|
+
Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
|
|
39
|
+
|
|
40
|
+
## Candidate card
|
|
41
|
+
|
|
42
|
+
The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
|
|
43
|
+
|
|
44
|
+
Each candidate is one `<article>`:
|
|
45
|
+
|
|
46
|
+
- **Title**: short, names the deepening (e.g. "Collapse the Order intake pipeline").
|
|
47
|
+
- **Badge row**: recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
|
|
48
|
+
- **Files**: monospaced list, `font-mono text-sm`.
|
|
49
|
+
- **Before / After diagram**: the centrepiece. Two columns, side by side. See patterns below.
|
|
50
|
+
- **Problem**: one sentence. What hurts.
|
|
51
|
+
- **Solution**: one sentence. What changes.
|
|
52
|
+
- **Wins**: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
|
|
53
|
+
- **ADR callout** (if applicable): one line in an amber-tinted box.
|
|
54
|
+
|
|
55
|
+
No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
|
|
56
|
+
|
|
57
|
+
## Diagram patterns
|
|
58
|
+
|
|
59
|
+
Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
|
|
60
|
+
|
|
61
|
+
### Mermaid graph (the workhorse for dependencies / call flow)
|
|
62
|
+
|
|
63
|
+
Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
|
|
64
|
+
|
|
65
|
+
```html
|
|
66
|
+
<div class="rounded-lg border border-slate-200 bg-white p-4">
|
|
67
|
+
<pre class="mermaid">
|
|
68
|
+
flowchart LR
|
|
69
|
+
A[OrderHandler] --> B[OrderValidator]
|
|
70
|
+
B --> C[OrderRepo]
|
|
71
|
+
C -.leak.-> D[PricingClient]
|
|
72
|
+
classDef leak stroke:#dc2626,stroke-width:2px;
|
|
73
|
+
class C,D leak
|
|
74
|
+
</pre>
|
|
75
|
+
</div>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
|
|
79
|
+
|
|
80
|
+
Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since Mermaid won't render that with the right weight.
|
|
81
|
+
|
|
82
|
+
### Cross-section (good for layered shallowness)
|
|
83
|
+
|
|
84
|
+
Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
|
|
85
|
+
|
|
86
|
+
### Mass diagram (good for "interface as wide as implementation")
|
|
87
|
+
|
|
88
|
+
Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
|
|
89
|
+
|
|
90
|
+
### Call-graph collapse
|
|
91
|
+
|
|
92
|
+
Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
|
|
93
|
+
|
|
94
|
+
## Style guidance
|
|
95
|
+
|
|
96
|
+
- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
|
|
97
|
+
- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
|
|
98
|
+
- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
|
|
99
|
+
- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
|
|
100
|
+
- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
|
|
101
|
+
|
|
102
|
+
## Top recommendation section
|
|
103
|
+
|
|
104
|
+
One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
|
|
105
|
+
|
|
106
|
+
## Tone
|
|
107
|
+
|
|
108
|
+
Plain English, concise, but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
|
|
109
|
+
|
|
110
|
+
**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
|
|
111
|
+
|
|
112
|
+
**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
|
|
113
|
+
|
|
114
|
+
**Phrasings that fit the style:**
|
|
115
|
+
|
|
116
|
+
- "Order intake module is shallow: interface nearly matches the implementation."
|
|
117
|
+
- "Pricing leaks across the seam."
|
|
118
|
+
- "Deepen: one interface, one place to test."
|
|
119
|
+
- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
|
|
120
|
+
|
|
121
|
+
**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"*, because those terms aren't in the glossary and don't earn their place.
|
|
122
|
+
|
|
123
|
+
No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: improve-codebase-architecture
|
|
3
|
+
description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Improve Codebase Architecture
|
|
8
|
+
|
|
9
|
+
Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
|
|
10
|
+
|
|
11
|
+
This command is _informed_ by the project's domain model and built on a shared design vocabulary:
|
|
12
|
+
|
|
13
|
+
- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
|
|
14
|
+
- The domain language in `GLOSSARY.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
|
|
15
|
+
|
|
16
|
+
## Process
|
|
17
|
+
|
|
18
|
+
### 1. Explore
|
|
19
|
+
|
|
20
|
+
**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
|
|
21
|
+
|
|
22
|
+
- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
|
|
23
|
+
- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
|
|
24
|
+
|
|
25
|
+
Read the project's domain glossary (`GLOSSARY.md`) and any ADRs in the area you're touching first.
|
|
26
|
+
|
|
27
|
+
Then spawn a sub-agent with a fresh context window to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
|
|
28
|
+
|
|
29
|
+
- Where does understanding one concept require bouncing between many small modules?
|
|
30
|
+
- Where are modules **shallow**, with an interface nearly as complex as the implementation?
|
|
31
|
+
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
|
|
32
|
+
- Where do tightly-coupled modules leak across their seams?
|
|
33
|
+
- Which parts of the codebase are untested, or hard to test through their current interface?
|
|
34
|
+
|
|
35
|
+
Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
|
|
36
|
+
|
|
37
|
+
### 2. Present candidates as an HTML report
|
|
38
|
+
|
|
39
|
+
Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.
|
|
40
|
+
|
|
41
|
+
The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
|
|
42
|
+
|
|
43
|
+
For each candidate, render a card with:
|
|
44
|
+
|
|
45
|
+
- **Files**: which files/modules are involved
|
|
46
|
+
- **Problem**: why the current architecture is causing friction
|
|
47
|
+
- **Solution**: plain English description of what would change
|
|
48
|
+
- **Benefits**: explained in terms of locality and leverage, and how tests would improve
|
|
49
|
+
- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
|
|
50
|
+
- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
|
|
51
|
+
|
|
52
|
+
End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
|
|
53
|
+
|
|
54
|
+
**Use GLOSSARY.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `GLOSSARY.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
|
|
55
|
+
|
|
56
|
+
**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
|
|
57
|
+
|
|
58
|
+
See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
|
|
59
|
+
|
|
60
|
+
Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
|
|
61
|
+
|
|
62
|
+
### 3. Grilling loop
|
|
63
|
+
|
|
64
|
+
Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
|
|
65
|
+
|
|
66
|
+
Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:
|
|
67
|
+
|
|
68
|
+
- **Naming a deepened module after a concept not in `GLOSSARY.md`?** Add the term to `GLOSSARY.md`. Create the file lazily if it doesn't exist.
|
|
69
|
+
- **Sharpening a fuzzy term during the conversation?** Update `GLOSSARY.md` right there.
|
|
70
|
+
- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
|
|
71
|
+
- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mcp-cleanup
|
|
3
|
+
description: Kill orphaned MCP server processes left behind by crashed or closed agent sessions. Use when node.exe/cmd.exe count is high, MCP servers are unresponsive, or after closing multiple IDE/CLI sessions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# MCP Cleanup Skill (`mcp-cleanup`)
|
|
7
|
+
|
|
8
|
+
Use this skill when the user reports slow performance, high process counts, unresponsive MCP tools, or after closing multiple agent sessions without clean shutdown.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## When to Invoke
|
|
13
|
+
|
|
14
|
+
- User says `/mcp-cleanup`, "kill mcp orphans", "clean up mcp", "too many node processes"
|
|
15
|
+
- When MCP servers fail to connect and orphan processes are suspected
|
|
16
|
+
- As part of post-crash recovery
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Execution Steps
|
|
21
|
+
|
|
22
|
+
1. **Count current MCP-related processes** (diagnostic baseline):
|
|
23
|
+
- On Windows (PowerShell):
|
|
24
|
+
```powershell
|
|
25
|
+
Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" |
|
|
26
|
+
Where-Object { $_.CommandLine -match 'context7-mcp|chrome-devtools-mcp|rea\.mjs|npx\.cmd|open-design' } |
|
|
27
|
+
Select-Object ProcessId, Name, @{N='CmdLine';E={$_.CommandLine.Substring(0, [Math]::Min(120, $_.CommandLine.Length))}} |
|
|
28
|
+
Format-Table -AutoSize
|
|
29
|
+
```
|
|
30
|
+
- On macOS/Linux:
|
|
31
|
+
```bash
|
|
32
|
+
ps aux | grep -E 'context7-mcp|chrome-devtools-mcp|rea\.mjs|npx' | grep -v grep
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
2. **Warn the user**: Tell them how many orphan processes were found and that killing them will break any active MCP connections. Ask for confirmation unless the user explicitly said "force" or "kill all".
|
|
36
|
+
|
|
37
|
+
3. **Kill orphaned processes**:
|
|
38
|
+
- On Windows (PowerShell):
|
|
39
|
+
```powershell
|
|
40
|
+
Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='cmd.exe'" |
|
|
41
|
+
Where-Object { $_.CommandLine -match 'context7-mcp|chrome-devtools-mcp|rea\.mjs|npx\.cmd' } |
|
|
42
|
+
ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
|
|
43
|
+
```
|
|
44
|
+
- On macOS/Linux:
|
|
45
|
+
```bash
|
|
46
|
+
pkill -f 'context7-mcp|chrome-devtools-mcp|rea\.mjs|npx.*mcp'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
4. **Verify cleanup**: Re-run the diagnostic count from step 1 and report how many processes remain.
|
|
50
|
+
|
|
51
|
+
5. **Recommend prevention**: Remind the user about `/mcp-sync` to ensure configs use direct `node.exe` calls instead of `npx`, which prevents future orphan multiplication.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Guardrails
|
|
56
|
+
|
|
57
|
+
- NEVER kill node.exe/cmd.exe processes that do NOT match the MCP command-line patterns above.
|
|
58
|
+
- NEVER run cleanup while the user has active agent sessions unless they explicitly confirm.
|
|
59
|
+
- NEVER use `taskkill /F /IM node.exe` — this kills ALL node processes including unrelated apps.
|
|
60
|
+
- Always filter by CommandLine content, not just process name.
|
|
61
|
+
- Report exact counts before and after — never claim cleanup succeeded without verification.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mcp-sync
|
|
3
|
+
description: Resolve Heimdall MCP template to local paths and sync to agent harness configs. Use when toggling MCP servers, setting up a new machine, or after installing/updating global npm MCP packages.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# MCP Sync Skill (`mcp-sync`)
|
|
7
|
+
|
|
8
|
+
Use this skill when the user wants to update MCP server configurations, toggle servers on/off, set up MCP on a new machine, or after running `npm install -g` / `npm update -g` for MCP packages.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## When to Invoke
|
|
13
|
+
|
|
14
|
+
- User says `/mcp-sync`, "sync mcp", "update mcp config", "enable/disable <server>"
|
|
15
|
+
- After installing or updating global MCP npm packages
|
|
16
|
+
- When setting up Heimdall on a new workstation
|
|
17
|
+
- When an MCP server fails to connect due to path issues
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Execution Steps
|
|
22
|
+
|
|
23
|
+
1. **Check prerequisites**: Verify `config/mcp.template.json` exists. If missing, report error and stop.
|
|
24
|
+
|
|
25
|
+
2. **Toggle servers if requested**: If the user asked to enable or disable a specific server, edit `config/mcp.template.json` and set `"disabled": true/false` on that server entry before resolving.
|
|
26
|
+
|
|
27
|
+
3. **Run the resolver**:
|
|
28
|
+
```bash
|
|
29
|
+
node scripts/resolve-mcp.mjs --sync
|
|
30
|
+
```
|
|
31
|
+
This generates `config/mcp.resolved.json` and writes to `~/.gemini/config/mcp_config.json` and `~/.claude/settings.json`.
|
|
32
|
+
|
|
33
|
+
4. **Report results**: Show which servers are enabled/disabled, any unresolved placeholders, and remind the user to restart agent sessions.
|
|
34
|
+
|
|
35
|
+
5. **If unresolved placeholders exist**: Tell the user which packages to install globally:
|
|
36
|
+
```bash
|
|
37
|
+
npm install -g @upstash/context7-mcp chrome-devtools-mcp rea-agents
|
|
38
|
+
```
|
|
39
|
+
Then re-run the resolver.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Architecture Notes
|
|
44
|
+
|
|
45
|
+
- `config/mcp.template.json` is the portable source of truth (committed to git).
|
|
46
|
+
- `config/mcp.resolved.json` is machine-specific (gitignored).
|
|
47
|
+
- The resolver replaces `{{PLACEHOLDER}}` tokens with local paths detected at runtime.
|
|
48
|
+
- Disabled servers are excluded from harness configs but preserved in the template.
|
|
49
|
+
- Never use `npx` in resolved configs — always direct `node.exe` calls to avoid Windows process multiplication.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Guardrails
|
|
54
|
+
|
|
55
|
+
- NEVER edit `config/mcp.resolved.json` directly — it is generated.
|
|
56
|
+
- NEVER add `npx` commands to any MCP config.
|
|
57
|
+
- NEVER start dev servers to test MCP connectivity.
|
|
58
|
+
- Always run `--sync` to propagate changes to harness configs; generating `mcp.resolved.json` alone does not update running agents.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: modern-web-guidance
|
|
3
|
+
description: |
|
|
4
|
+
Search tool for modern web development best practices. MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks. Do NOT skip — web APIs evolve rapidly and training weights contain obsolete patterns.
|
|
5
|
+
Trigger immediately for: modals/dialogs/popovers, tables, dark mode, anchor positioning, container queries, view transitions, scroll-driven animations, parallax/reveals, forms, validation, autofill, accessibility, custom selects, scrollbars, CWV (LCP, INP, CLS), content-visibility, fetch priority, image optimization, security, passkeys, HTML sanitization, web components, dates/timezones, built-in AI, WebAssembly, standard HTML/CSS/DOM in frameworks, etc.
|
|
6
|
+
DO NOT trigger for: backend (SQL, ORMs, API routes), infra/scripts (CI/CD, Docker, Actions, Python/Go, Git), or tooling/trivial (Vite, tsconfig, ESLint, tests, copy/renames, 3P docs), etc.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Modern Web Guidance
|
|
10
|
+
|
|
11
|
+
Search and retrieve standardized modern web best practices at the **start** of implementing or updating any web UI, CSS layout/animation, or client-side JS logic (dates/timezones, sanitization, performance, accessibility, UX fixes) before writing ad-hoc solutions or adding dependencies.
|
|
12
|
+
|
|
13
|
+
## Primary Workflow
|
|
14
|
+
|
|
15
|
+
### Step 1. Search Use Cases
|
|
16
|
+
|
|
17
|
+
Run `modern-web-guidance` directly with `npx` using a **2–5 word action-oriented English query** for a **single web platform capability or UI pattern**:
|
|
18
|
+
- **Keep queries focused and generic**: Describe the user-visible capability (`<verb> + <UI/platform object>`, optionally paired with the target HTML/CSS/JS feature name if known). Omit framework/library names (`React`, `Vue`, `Tailwind`, etc.) and app/domain nouns (product, route, or component/file names). Split multi-feature tasks into separate `search` calls.
|
|
19
|
+
- **Name implied UI primitives**: When the user's prompt expresses intent without naming the UI primitive (e.g. "confirm first", "delete with confirmation", "pick a date"), translate the domain intent into the implied UI component or platform mechanism (e.g. search `"confirmation modal dialog"` or `"confirm dialog"` rather than `"confirm destructive action"`, or `"date picker input"` rather than `"pick a date"`).
|
|
20
|
+
- **Example**: Search `"light dismiss dialog"` or `"responsive data table"`, **not** `"dialog"` (too terse), `"responsive table dark mode"` (compound — split into two searches), or `"close React settings modal on outside click"` (framework/app noise).
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_11_10-47b4c80e
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
> **Note**: Returns `[{ "id", "description" }, ...]`. Judge results by their `description` fields:
|
|
27
|
+
> - **Match found**: Call `retrieve` directly—do not also run `list`.
|
|
28
|
+
> - **Weak or empty results**: If `search` returns `[]` or unrelated descriptions, **rephrase `search` once** using the concrete HTML/CSS/UI component noun or synonym (e.g., `dialog`, `modal`, `popover`, `table`, `form`) before falling back to `list` (or use `list` once for broad UI audits).
|
|
29
|
+
> - **Topic not covered**: If no `description` matches after rephrasing, proceed without retrieving unrelated guides.
|
|
30
|
+
|
|
31
|
+
### Step 2. Retrieve Best Practices
|
|
32
|
+
|
|
33
|
+
Once you have relevant `id`(s) from the search results, call `retrieve` to get the full guide(s)—including both specific use-case guides that match your task and any broader discipline guide (e.g., `html`, `css`, `forms`, `accessibility`, `color`, `performance`, `security`) that applies. You can pass multiple IDs separated by commas.
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
npx -y modern-web-guidance@latest retrieve "<id>"
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
If `retrieve` saves large output (> 9.5 KB) to a temporary file to prevent truncation, read that file path in full using your file-reading tool (reading remaining line ranges if needed)—do not use `cat` or `head`.
|
|
40
|
+
|
|
41
|
+
### Step 3. Verify Guidance Compliance
|
|
42
|
+
|
|
43
|
+
When generating or modifying code, cross-check the implementation against the retrieved guide before concluding:
|
|
44
|
+
- **Applicable Guidance & Fallbacks**: Ensure the relevant modern patterns and necessary fallback strategies from the guide are correctly applied, without forcing unrequested features.
|
|
45
|
+
- **Task Fulfillment**: Confirm that the implementation fully satisfies the user's request.
|
|
46
|
+
- Do not run `legacy-scan`; it's for detecting legacy patterns to modernize, not this.
|
|
47
|
+
|
|
48
|
+
### Step 4. Disclose Skill Usage
|
|
49
|
+
|
|
50
|
+
When you consult `modern-web-guidance` for a task, end the response where you deliver those changes with a `### Modern Web Guidance` section:
|
|
51
|
+
- **When retrieved guides shaped your code**: Write **one** bullet (1–2 sentences, ≤75 words) per newly applied `<id>` in first-person voice explaining the non-obvious implementation choices, CSS/API overrides, or fallbacks `<id>` required and the pitfall it prevented, anchored by a short verbatim quote of that specific rule or gotcha (never the guide's intro overview):
|
|
52
|
+
`- **\`<id>\`**: <Non-obvious APIs, overrides, or fallbacks applied and the pitfall prevented> ("<short verbatim quote of the specific rule or gotcha>").`
|
|
53
|
+
- **Never** guess `<id>`s or quotes from memory after context compaction (re-run `search`/`retrieve` if needed), and credit **only** guide-backed changes from the current turn.
|
|
54
|
+
- **When searched/listed in this turn but zero guides applied**: Write one first-person sentence naming which topics or guides you checked in `modern-web-guidance` and why none applied (omit if any guide applied).
|
|
55
|
+
|
|
56
|
+
## Alternative flow: Modernize an existing codebase
|
|
57
|
+
|
|
58
|
+
**Only** when asked for a broad, open-ended codebase modernization or legacy-pattern scan where no specific target feature or component is named (do **not** run `legacy-scan` when asked to add, update, fix, or audit a specific feature or component), run the 4-step modernization flow:
|
|
59
|
+
|
|
60
|
+
> **Note**: `legacy-scan` scans for a curated subset (~20% of the guidance corpus).
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
npx -y modern-web-guidance@latest legacy-scan <path> --json
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
1. Scan: Run `legacy-scan <path> --json` to detect legacy web platform patterns across the project or directory.
|
|
67
|
+
2. Verify: Check each finding against its `keepWhen` / `dropWhen` rubric; drop false positives (fallbacks, cross-file helpers, vendor code, lookalikes).
|
|
68
|
+
3. Report: Summarize verified findings (and the modernization plan, if editing) for the user, noting that `legacy-scan` only checks the subset of guides (~20% of the catalog) that have deterministic legacy rules.
|
|
69
|
+
4. Modernize (when the user asked to modernize rather than only audit/report): Retrieve each finding's guide (`retrieve "<guide-id>"` via Step 2), apply the replacement (keeping existing libraries as fallbacks where the guide requires one), and re-run `legacy-scan <path>` on the modified files to confirm resolution.
|
|
70
|
+
- Dropped findings and kept fallbacks still match static scans; do not edit safe code or inspect `legacy-scan.mjs` to force 0 findings.
|
|
71
|
+
|
|
72
|
+
## Using npx / pnpx
|
|
73
|
+
|
|
74
|
+
- **Runner & Permissions**: Prefer `pnpx` over `npx` if `pnpm` is available (`pnpx` does not use `-y`); on Windows, use `npx.cmd`. When requesting tool permissions, allowlist `npx -y modern-web-guidance@latest *` (or `pnpx modern-web-guidance@latest *`) specifically, never bare `npx *` or `pnpx *`.
|
|
75
|
+
- **Sandboxes & Network**: Fetching `modern-web-guidance` requires outbound network access. In sandboxed or approval-gated environments (e.g., Codex, Claude Code), **proactively request approval/allowlisting with network access BEFORE the first execution** to avoid timeouts, and set `NPM_CONFIG_CACHE=/tmp/npm-cache` if `~/.npm` is read-only.
|
|
76
|
+
- **Offline**: If the command hangs due to being offline, retry with `npx --offline …`.
|
|
77
|
+
|
|
78
|
+
## Guidelines
|
|
79
|
+
|
|
80
|
+
- Always search **first** to find the most relevant guides. Do not hallucinate guides or ignore them; they represent the preferred local standard for the user's project.
|
|
81
|
+
- These guides use vanilla HTML/CSS/JS; adapt them to your framework without dropping the modern feature:
|
|
82
|
+
- **Types**: Spread/cast newly shipped HTML attributes (`{...({ popover: 'hint', interestfor: id, commandfor: id, switch: '' } as any)}`, `[attr.*]`) rather than removing them or merging `@types/react`.
|
|
83
|
+
- **SSR & Bundlers**: Guard `window`/`HTMLElement` in SSR and load polyfills via bare `import('<pkg>')` in client effects (or set Vite `build.target: 'esnext'` for top-level `await`)—never copy files from `node_modules`.
|
|
84
|
+
- **DOM, IDs & CSS**: Call `showModal()`/`moveBefore()` via refs on non-VDOM-managed nodes, generate per-instance IDs/`anchor-name`s (`useId()`), and keep `:root` and `@starting-style` top-level/unscoped.
|
|
85
|
+
|
|
86
|
+
## Interpreting Browser Support & Fallbacks
|
|
87
|
+
|
|
88
|
+
* **Default Behavior**: All guides assume **Baseline Widely available** features are safe to use without fallbacks. For features that are not Baseline widely available, you **MUST** follow the fallback recommendations in the guide, unless the user has specified a custom browser support policy.
|
|
89
|
+
* **Custom Policies**: If the user defines explicit browser support requirements, use the guide's compatibility data to determine if a fallback can be ignored (for `Baseline YYYY` targets, a feature satisfies the target if its "Baseline since" date is `<= YYYY`). Examples: _"Do not implement feature fallbacks"_, _"Safari 17.4+"_, _"Never implement polyfills; use a lightweight custom fallback or redesign"_, or _"Allow Newly Available features if feature-detected with graceful degradation"_.
|
|
90
|
+
* **Reactive Policy Discovery**: Suggest documenting a policy in `AGENTS.md` or `CLAUDE.md` (e.g., `**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and no external dependencies`) if the developer targets a restricted runtime (Electron/Tauri), excludes specific browsers, hesitates over polyfill size/complexity, or asks if a feature is safe without fallbacks.
|