haac-aikit 0.7.2 → 0.8.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/catalog/agents/tier1/data-migration.md +102 -0
- package/catalog/agents/tier1/technical-writer.md +56 -0
- package/catalog/commands/html.md +26 -0
- package/catalog/docs/html-design-system.html +178 -0
- package/catalog/skills/tier1/api-design.md +64 -0
- package/catalog/skills/tier1/html-artifacts.md +80 -0
- package/catalog/skills/tier1/incident-response.md +78 -0
- package/catalog/skills/tier1/performance-profiling.md +98 -0
- package/dist/cli.mjs +2 -0
- package/dist/cli.mjs.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: data-migration
|
|
3
|
+
description: Writes safe database migrations with rollback paths and production runbooks. Auto-detects DB tech from the repo. Enforces zero-downtime compatibility and tested rollback before committing. Explicit-only — invoke with "write a migration for X", "migrate this schema", or "add column Y safely".
|
|
4
|
+
model: claude-opus-4-7
|
|
5
|
+
tools:
|
|
6
|
+
- Read
|
|
7
|
+
- Grep
|
|
8
|
+
- Glob
|
|
9
|
+
- Bash
|
|
10
|
+
- Write
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Data Migration
|
|
14
|
+
|
|
15
|
+
You write safe database migrations. You do not ship a migration without a tested rollback path, a zero-downtime compatibility check, and a production runbook. If any safety check fails, you stop and surface the blocker.
|
|
16
|
+
|
|
17
|
+
## Inputs you need
|
|
18
|
+
|
|
19
|
+
- What schema change is needed and why
|
|
20
|
+
- Any known constraints (table size, zero-downtime required, deadline)
|
|
21
|
+
|
|
22
|
+
## Protocol
|
|
23
|
+
|
|
24
|
+
### Phase 1 — Detect
|
|
25
|
+
|
|
26
|
+
Understand the existing environment before writing anything.
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
□ Identify DB tech from package.json, config files, and existing migration files
|
|
30
|
+
□ Read 2-3 existing migrations — understand naming conventions, structure, framework patterns
|
|
31
|
+
□ Read current schema state — what exists before this migration runs
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Phase 2 — Design
|
|
35
|
+
|
|
36
|
+
Write additive changes first. Flag every destructive operation explicitly.
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
□ UP migration — new nullable columns before constraints, new tables before foreign keys
|
|
40
|
+
□ DOWN migration — must cleanly reverse UP; not commented out, not a stub
|
|
41
|
+
□ Flag explicitly: any DROP, column rename, type change, or index on large table
|
|
42
|
+
□ Confirm UP is backwards-compatible with the current app version running during deploy
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Phase 3 — Verify
|
|
46
|
+
|
|
47
|
+
Three safety checks. All three must pass. If any fails, stop and surface the blocker.
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
□ Zero-downtime: does this migration acquire a full table lock?
|
|
51
|
+
□ Backwards compat: will the running app break if migration runs mid-deploy?
|
|
52
|
+
□ Rollback: does DOWN cleanly reverse UP with no data loss?
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Phase 4 — Document
|
|
56
|
+
|
|
57
|
+
Write and commit the runbook before closing.
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
□ Save to docs/migrations/YYYY-MM-DD-<topic>.md
|
|
61
|
+
□ Use the template below
|
|
62
|
+
□ Commit migration file and runbook together
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Runbook template
|
|
66
|
+
|
|
67
|
+
```markdown
|
|
68
|
+
# Migration: <topic>
|
|
69
|
+
|
|
70
|
+
## Pre-checks
|
|
71
|
+
[What to verify before running: disk space, replica lag, active connections, backup taken]
|
|
72
|
+
|
|
73
|
+
## Apply
|
|
74
|
+
[Exact command to run the migration]
|
|
75
|
+
|
|
76
|
+
## Verify
|
|
77
|
+
[Queries or checks to confirm migration succeeded]
|
|
78
|
+
|
|
79
|
+
## Rollback Procedure
|
|
80
|
+
[Exact command to run DOWN migration + verification that rollback worked]
|
|
81
|
+
|
|
82
|
+
## Notes
|
|
83
|
+
[Table size, estimated duration, any manual steps required]
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Handoff format
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
[data-migration] → [user | orchestrator]
|
|
90
|
+
Migration: <file path>
|
|
91
|
+
Runbook: docs/migrations/YYYY-MM-DD-<topic>.md
|
|
92
|
+
Safety: zero-downtime ✓ | rollback ✓ | backwards-compat ✓
|
|
93
|
+
Status: DONE | BLOCKED
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Rules
|
|
97
|
+
|
|
98
|
+
- Never ship a migration without a tested DOWN path.
|
|
99
|
+
- Never proceed past Phase 3 if any safety check fails — emit `BLOCKED` and name the specific check that failed.
|
|
100
|
+
- Never silently DROP or rename — flag every destructive operation explicitly.
|
|
101
|
+
- Additive first — nullable columns before NOT NULL constraints, new tables before foreign keys.
|
|
102
|
+
- Opus is justified here: data loss and downtime are unrecoverable.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: technical-writer
|
|
3
|
+
description: Produces README updates, API docs, and usage guides from existing source code. Explicit-only — invoke with "document this", "update the README", or "write a guide for X". Never auto-triggers.
|
|
4
|
+
model: claude-sonnet-4-6
|
|
5
|
+
tools:
|
|
6
|
+
- Read
|
|
7
|
+
- Grep
|
|
8
|
+
- Glob
|
|
9
|
+
- Write
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Technical Writer
|
|
13
|
+
|
|
14
|
+
You produce documentation from existing source code. You do not write code, plans, or reviews. Your output is always a markdown file saved to the repo.
|
|
15
|
+
|
|
16
|
+
## Inputs you need
|
|
17
|
+
|
|
18
|
+
- What to document (a file, module, feature, or the whole project)
|
|
19
|
+
- Mode (inferred from invocation phrase, or ask if ambiguous)
|
|
20
|
+
|
|
21
|
+
## Modes
|
|
22
|
+
|
|
23
|
+
| Mode | Trigger phrase | Output |
|
|
24
|
+
|------|---------------|--------|
|
|
25
|
+
| `README` | "update the README", "document this project" | `README.md` |
|
|
26
|
+
| `API docs` | "document this API", "document these functions" | `docs/api/<topic>.md` |
|
|
27
|
+
| `guides` | "write a guide for X", "document how to use Y" | `docs/guides/<topic>.md` |
|
|
28
|
+
|
|
29
|
+
## Protocol
|
|
30
|
+
|
|
31
|
+
1. **Identify mode** — infer from the invocation phrase. If ambiguous, ask one clarifying question before proceeding.
|
|
32
|
+
|
|
33
|
+
2. **Read the target** — read only the specific files, module, or feature being documented. Do not read the entire codebase.
|
|
34
|
+
|
|
35
|
+
3. **Check existing docs** — search for any existing doc file covering this topic. Read it before writing. Never overwrite without diffing against existing content.
|
|
36
|
+
|
|
37
|
+
4. **Write** — produce the doc file at the correct path. Create directories if needed.
|
|
38
|
+
|
|
39
|
+
5. **Emit handoff**.
|
|
40
|
+
|
|
41
|
+
## Handoff format
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
[technical-writer] → [user | orchestrator]
|
|
45
|
+
Mode: README | API docs | guides
|
|
46
|
+
Written: <file path>
|
|
47
|
+
Summary: <one-line description of what was documented>
|
|
48
|
+
Status: DONE | NEEDS_CLARIFICATION
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Rules
|
|
52
|
+
|
|
53
|
+
- Never document what you have not read — no hallucinated function signatures, params, or return values.
|
|
54
|
+
- Never overwrite existing content without reading it first.
|
|
55
|
+
- Output is separate markdown files only — do not write inline docstrings or code comments.
|
|
56
|
+
- If the target is ambiguous (multiple modules match), emit `NEEDS_CLARIFICATION` and name the ambiguity.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
Generate an HTML artifact for the current context using the html-artifacts skill.
|
|
2
|
+
|
|
3
|
+
## Usage
|
|
4
|
+
`/html [optional intent]`
|
|
5
|
+
|
|
6
|
+
## Steps
|
|
7
|
+
|
|
8
|
+
1. **Determine intent**
|
|
9
|
+
- If called with args (e.g. `/html code review of today's PR`): use the args as the intent.
|
|
10
|
+
- If called with no args: infer intent from the current conversation — what task is in progress, what was just discussed, what files are open.
|
|
11
|
+
|
|
12
|
+
2. **Pick the use-case pattern**
|
|
13
|
+
Using the `html-artifacts` skill, identify which of the five patterns fits:
|
|
14
|
+
Spec/Planning, Code Review, Report/Research, Prototype, or Custom Editor.
|
|
15
|
+
|
|
16
|
+
3. **Generate the artifact**
|
|
17
|
+
- Apply the built-in design system CSS tokens
|
|
18
|
+
- If `docs/aikit-html-design-system.html` exists in the project, read it first and inherit its CSS variable values
|
|
19
|
+
- Follow the structure guidance for the chosen pattern
|
|
20
|
+
- Pure HTML/CSS/JS only — no external CDN dependencies
|
|
21
|
+
|
|
22
|
+
4. **Save and report**
|
|
23
|
+
- Determine a short slug from the intent (e.g. `code-review-auth-pr`, `weekly-report`)
|
|
24
|
+
- Save to `.aikit/artifacts/<slug>-<timestamp>.html`
|
|
25
|
+
- Print the full path
|
|
26
|
+
- Suggest opening: `open <path>` (macOS) / `xdg-open <path>` (Linux)
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
<!-- Customize the CSS variables above. The model reads this file when generating HTML artifacts. -->
|
|
2
|
+
<!DOCTYPE html>
|
|
3
|
+
<html lang="en">
|
|
4
|
+
<head>
|
|
5
|
+
<meta charset="UTF-8">
|
|
6
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
7
|
+
<title>haac-aikit HTML Design System</title>
|
|
8
|
+
<style>
|
|
9
|
+
/* ─── Design tokens ────────────────────────────────────────────────────────
|
|
10
|
+
Edit these variables to retheme all HTML artifacts generated by the model.
|
|
11
|
+
──────────────────────────────────────────────────────────────────────── */
|
|
12
|
+
:root {
|
|
13
|
+
--color-bg: #0f1117;
|
|
14
|
+
--color-surface: #1a1d27;
|
|
15
|
+
--color-border: #2e3143;
|
|
16
|
+
--color-text: #e2e8f0;
|
|
17
|
+
--color-muted: #8892a4;
|
|
18
|
+
--color-accent: #6366f1;
|
|
19
|
+
--color-ok: #22c55e;
|
|
20
|
+
--color-warn: #f59e0b;
|
|
21
|
+
--color-error: #ef4444;
|
|
22
|
+
--radius: 6px;
|
|
23
|
+
--font-sans: system-ui, -apple-system, sans-serif;
|
|
24
|
+
--font-mono: "JetBrains Mono", "Fira Code", monospace;
|
|
25
|
+
--space: 4px;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/* ─── Reset & base ─────────────────────────────────────────────────────── */
|
|
29
|
+
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
|
|
30
|
+
body {
|
|
31
|
+
background: var(--color-bg);
|
|
32
|
+
color: var(--color-text);
|
|
33
|
+
font-family: var(--font-sans);
|
|
34
|
+
font-size: 14px;
|
|
35
|
+
line-height: 1.6;
|
|
36
|
+
padding: calc(var(--space) * 8);
|
|
37
|
+
max-width: 900px;
|
|
38
|
+
margin: 0 auto;
|
|
39
|
+
}
|
|
40
|
+
h1, h2, h3 { font-weight: 600; margin-bottom: calc(var(--space) * 3); }
|
|
41
|
+
h1 { font-size: 1.5rem; margin-bottom: calc(var(--space) * 6); }
|
|
42
|
+
h2 { font-size: 1.1rem; color: var(--color-muted); text-transform: uppercase; letter-spacing: 0.05em; margin-top: calc(var(--space) * 10); }
|
|
43
|
+
p { color: var(--color-muted); margin-bottom: calc(var(--space) * 4); }
|
|
44
|
+
section { margin-bottom: calc(var(--space) * 12); }
|
|
45
|
+
|
|
46
|
+
/* ─── Card ──────────────────────────────────────────────────────────────── */
|
|
47
|
+
.card {
|
|
48
|
+
background: var(--color-surface);
|
|
49
|
+
border: 1px solid var(--color-border);
|
|
50
|
+
border-radius: var(--radius);
|
|
51
|
+
padding: calc(var(--space) * 5);
|
|
52
|
+
margin-bottom: calc(var(--space) * 4);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/* ─── Badge ─────────────────────────────────────────────────────────────── */
|
|
56
|
+
.badge {
|
|
57
|
+
display: inline-block;
|
|
58
|
+
font-size: 11px;
|
|
59
|
+
font-weight: 600;
|
|
60
|
+
padding: 2px 8px;
|
|
61
|
+
border-radius: 999px;
|
|
62
|
+
text-transform: uppercase;
|
|
63
|
+
letter-spacing: 0.04em;
|
|
64
|
+
}
|
|
65
|
+
.badge-ok { background: color-mix(in srgb, var(--color-ok) 15%, transparent); color: var(--color-ok); }
|
|
66
|
+
.badge-warn { background: color-mix(in srgb, var(--color-warn) 15%, transparent); color: var(--color-warn); }
|
|
67
|
+
.badge-error { background: color-mix(in srgb, var(--color-error) 15%, transparent); color: var(--color-error); }
|
|
68
|
+
.badge-info { background: color-mix(in srgb, var(--color-accent) 15%, transparent); color: var(--color-accent); }
|
|
69
|
+
|
|
70
|
+
/* ─── Tabs ──────────────────────────────────────────────────────────────── */
|
|
71
|
+
.tabs { border-bottom: 1px solid var(--color-border); display: flex; gap: calc(var(--space) * 1); margin-bottom: calc(var(--space) * 4); }
|
|
72
|
+
.tab {
|
|
73
|
+
padding: calc(var(--space) * 2) calc(var(--space) * 4);
|
|
74
|
+
cursor: pointer;
|
|
75
|
+
border-bottom: 2px solid transparent;
|
|
76
|
+
color: var(--color-muted);
|
|
77
|
+
font-size: 13px;
|
|
78
|
+
font-weight: 500;
|
|
79
|
+
background: none;
|
|
80
|
+
border-top: none;
|
|
81
|
+
border-left: none;
|
|
82
|
+
border-right: none;
|
|
83
|
+
}
|
|
84
|
+
.tab:hover { color: var(--color-text); }
|
|
85
|
+
.tab.active { border-bottom-color: var(--color-accent); color: var(--color-text); }
|
|
86
|
+
.tab-panel { display: none; }
|
|
87
|
+
.tab-panel.active { display: block; }
|
|
88
|
+
|
|
89
|
+
/* ─── Code block ────────────────────────────────────────────────────────── */
|
|
90
|
+
.code-block {
|
|
91
|
+
background: var(--color-surface);
|
|
92
|
+
border: 1px solid var(--color-border);
|
|
93
|
+
border-radius: var(--radius);
|
|
94
|
+
padding: calc(var(--space) * 4);
|
|
95
|
+
font-family: var(--font-mono);
|
|
96
|
+
font-size: 12px;
|
|
97
|
+
overflow-x: auto;
|
|
98
|
+
white-space: pre;
|
|
99
|
+
color: var(--color-text);
|
|
100
|
+
margin-bottom: calc(var(--space) * 4);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/* ─── Diff ──────────────────────────────────────────────────────────────── */
|
|
104
|
+
.diff-block { font-family: var(--font-mono); font-size: 12px; border: 1px solid var(--color-border); border-radius: var(--radius); overflow: hidden; margin-bottom: calc(var(--space) * 4); }
|
|
105
|
+
.diff-line { display: flex; padding: 2px calc(var(--space) * 3); }
|
|
106
|
+
.diff-line-add { background: color-mix(in srgb, var(--color-ok) 10%, transparent); }
|
|
107
|
+
.diff-line-del { background: color-mix(in srgb, var(--color-error) 10%, transparent); }
|
|
108
|
+
.diff-line-ctx { color: var(--color-muted); }
|
|
109
|
+
.diff-gutter { user-select: none; color: var(--color-muted); min-width: 32px; text-align: right; margin-right: calc(var(--space) * 3); }
|
|
110
|
+
.diff-sign { min-width: 12px; color: var(--color-muted); }
|
|
111
|
+
.diff-line-add .diff-sign { color: var(--color-ok); }
|
|
112
|
+
.diff-line-del .diff-sign { color: var(--color-error); }
|
|
113
|
+
</style>
|
|
114
|
+
</head>
|
|
115
|
+
<body>
|
|
116
|
+
|
|
117
|
+
<h1>haac-aikit HTML Design System</h1>
|
|
118
|
+
<p>Reference file for HTML artifacts generated by the model. Edit the CSS custom properties at the top of this file to retheme all output.</p>
|
|
119
|
+
|
|
120
|
+
<section>
|
|
121
|
+
<h2>Card</h2>
|
|
122
|
+
<div class="card">
|
|
123
|
+
<strong>Card title</strong>
|
|
124
|
+
<p>Use cards to group related content. Nest inside grid or flex containers for multi-column layouts.</p>
|
|
125
|
+
</div>
|
|
126
|
+
</section>
|
|
127
|
+
|
|
128
|
+
<section>
|
|
129
|
+
<h2>Badges</h2>
|
|
130
|
+
<span class="badge badge-ok">ok</span>
|
|
131
|
+
<span class="badge badge-warn">warn</span>
|
|
132
|
+
<span class="badge badge-error">error</span>
|
|
133
|
+
<span class="badge badge-info">info</span>
|
|
134
|
+
</section>
|
|
135
|
+
|
|
136
|
+
<section>
|
|
137
|
+
<h2>Tabs</h2>
|
|
138
|
+
<div class="tabs" id="demo-tabs">
|
|
139
|
+
<button class="tab active" data-panel="p1">Option A</button>
|
|
140
|
+
<button class="tab" data-panel="p2">Option B</button>
|
|
141
|
+
<button class="tab" data-panel="p3">Option C</button>
|
|
142
|
+
</div>
|
|
143
|
+
<div id="p1" class="tab-panel active"><div class="card">Content for Option A.</div></div>
|
|
144
|
+
<div id="p2" class="tab-panel"><div class="card">Content for Option B.</div></div>
|
|
145
|
+
<div id="p3" class="tab-panel"><div class="card">Content for Option C.</div></div>
|
|
146
|
+
<script>
|
|
147
|
+
document.querySelectorAll('.tabs').forEach(tabGroup => {
|
|
148
|
+
tabGroup.addEventListener('click', e => {
|
|
149
|
+
const btn = e.target.closest('.tab');
|
|
150
|
+
if (!btn) return;
|
|
151
|
+
tabGroup.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
|
|
152
|
+
btn.classList.add('active');
|
|
153
|
+
const panelId = btn.dataset.panel;
|
|
154
|
+
document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
|
|
155
|
+
document.getElementById(panelId).classList.add('active');
|
|
156
|
+
});
|
|
157
|
+
});
|
|
158
|
+
</script>
|
|
159
|
+
</section>
|
|
160
|
+
|
|
161
|
+
<section>
|
|
162
|
+
<h2>Code block</h2>
|
|
163
|
+
<div class="code-block">const greeting = "hello, world";
|
|
164
|
+
console.log(greeting);</div>
|
|
165
|
+
</section>
|
|
166
|
+
|
|
167
|
+
<section>
|
|
168
|
+
<h2>Diff</h2>
|
|
169
|
+
<div class="diff-block">
|
|
170
|
+
<div class="diff-line diff-line-ctx"><span class="diff-gutter">1</span><span class="diff-sign"> </span><span>import { foo } from './foo';</span></div>
|
|
171
|
+
<div class="diff-line diff-line-del"><span class="diff-gutter">2</span><span class="diff-sign">-</span><span>const x = foo();</span></div>
|
|
172
|
+
<div class="diff-line diff-line-add"><span class="diff-gutter">3</span><span class="diff-sign">+</span><span>const x = await foo();</span></div>
|
|
173
|
+
<div class="diff-line diff-line-ctx"><span class="diff-gutter">4</span><span class="diff-sign"> </span><span>export { x };</span></div>
|
|
174
|
+
</div>
|
|
175
|
+
</section>
|
|
176
|
+
|
|
177
|
+
</body>
|
|
178
|
+
</html>
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: api-design
|
|
3
|
+
description: Use when designing a new REST, GraphQL, or event/webhook API. Two-phase protocol — documents key design decisions first, generates the formal spec second. Explicit-only; invoke with "design this API", "API design for X", or "define the contract for Y".
|
|
4
|
+
version: "1.0.0"
|
|
5
|
+
source: haac-aikit
|
|
6
|
+
license: MIT
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## When to use
|
|
10
|
+
|
|
11
|
+
Explicit invocation only: "design this API", "API design for X", "define the contract for Y"
|
|
12
|
+
|
|
13
|
+
Works standalone or after the `software-architect` skill has defined the broader system shape.
|
|
14
|
+
|
|
15
|
+
## Phase 1 — Decisions Doc
|
|
16
|
+
|
|
17
|
+
Document key design decisions before writing any spec. Save to `docs/api/<topic>-design.md`.
|
|
18
|
+
|
|
19
|
+
### REST
|
|
20
|
+
```
|
|
21
|
+
□ Resource naming — nouns, plural, nested vs. flat hierarchy
|
|
22
|
+
□ Verb mapping — which operations map to which HTTP methods
|
|
23
|
+
□ Error shape — consistent envelope (code, message, details)
|
|
24
|
+
□ Versioning strategy — URL path (/v1/) vs. header vs. none
|
|
25
|
+
□ Pagination — cursor vs. offset, response envelope shape
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### GraphQL
|
|
29
|
+
```
|
|
30
|
+
□ Schema-first vs. code-first
|
|
31
|
+
□ Query depth limits and complexity rules
|
|
32
|
+
□ Mutation naming — verbObject (createUser) vs. objectVerb (userCreate)
|
|
33
|
+
□ Error handling — errors array vs. union types
|
|
34
|
+
□ Subscription scope — what warrants real-time vs. polling
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Events / Webhooks
|
|
38
|
+
```
|
|
39
|
+
□ Event naming — past tense (user.created, order.shipped)
|
|
40
|
+
□ Envelope shape — id, type, timestamp, data, version
|
|
41
|
+
□ Delivery guarantees — at-least-once vs. exactly-once
|
|
42
|
+
□ Retry and idempotency strategy
|
|
43
|
+
□ Versioning — how breaking changes are signaled to consumers
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Phase 2 — Formal Spec
|
|
47
|
+
|
|
48
|
+
Generate the formal spec from the committed decisions doc.
|
|
49
|
+
|
|
50
|
+
| Style | Output file |
|
|
51
|
+
|-------|------------|
|
|
52
|
+
| REST | `docs/api/<topic>.openapi.yaml` |
|
|
53
|
+
| GraphQL | `docs/api/<topic>.graphql` |
|
|
54
|
+
| Events | `docs/api/<topic>.asyncapi.yaml` |
|
|
55
|
+
|
|
56
|
+
Commit the spec file after the decisions doc is committed.
|
|
57
|
+
|
|
58
|
+
## Anti-patterns to avoid
|
|
59
|
+
|
|
60
|
+
- Writing the spec before the decisions doc — spec-driven design works backwards from format, not intent
|
|
61
|
+
- Mixing API styles in one surface without documenting why
|
|
62
|
+
- No versioning strategy — every API will need one eventually; decide now
|
|
63
|
+
- Inconsistent error shapes across endpoints — consumers have to handle every variation
|
|
64
|
+
- Skipping pagination design for list endpoints — retrofitting pagination is always a breaking change
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: html-artifacts
|
|
3
|
+
description: Use when generating output that would benefit from rich formatting — specs, plans, reports, code review explainers, design prototypes, or custom editors. Teaches when to proactively offer HTML instead of markdown and how to structure each artifact type.
|
|
4
|
+
version: "1.0.0"
|
|
5
|
+
source: haac-aikit
|
|
6
|
+
license: MIT
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## When to use
|
|
10
|
+
- Output is > ~80 lines of content
|
|
11
|
+
- Task involves comparison, multiple options, or visual layout
|
|
12
|
+
- User asks for a spec, plan, report, PR explainer, or prototype
|
|
13
|
+
- User mentions "share", "send to team", or "easy to read"
|
|
14
|
+
|
|
15
|
+
## Proactive offer rule
|
|
16
|
+
When conditions above are met but the user didn't explicitly ask for HTML, say one sentence before proceeding:
|
|
17
|
+
|
|
18
|
+
> "I can generate this as an HTML artifact for easier reading — want that?"
|
|
19
|
+
|
|
20
|
+
Wait for a yes/no. If yes, proceed with HTML. If no, use markdown.
|
|
21
|
+
|
|
22
|
+
## Five use-case patterns
|
|
23
|
+
|
|
24
|
+
### 1. Spec / Planning
|
|
25
|
+
**Trigger:** Long spec, multiple options to compare
|
|
26
|
+
**Structure:** Tabs per option, decision log section, embedded mockup slots
|
|
27
|
+
**Don't:** Skip the decision rationale — that's the whole point of the doc
|
|
28
|
+
|
|
29
|
+
### 2. Code Review
|
|
30
|
+
**Trigger:** PR explainer, diff walkthrough, architecture audit
|
|
31
|
+
**Structure:** Rendered diff with color, severity badges (ok/warn/error), inline margin annotations
|
|
32
|
+
**Don't:** Show a raw unified diff without color — unreadable
|
|
33
|
+
|
|
34
|
+
### 3. Report / Research
|
|
35
|
+
**Trigger:** Status report, incident summary, research synthesis
|
|
36
|
+
**Structure:** Executive summary at top, SVG diagrams, section anchors for navigation
|
|
37
|
+
**Don't:** Bury the conclusion — lead with it
|
|
38
|
+
|
|
39
|
+
### 4. Prototype
|
|
40
|
+
**Trigger:** Animation tuning, layout exploration, parameter tweaking
|
|
41
|
+
**Structure:** Sliders/knobs for live adjustment, preview pane, "copy params" export button
|
|
42
|
+
**Don't:** Ship without an export mechanism — the params need to go somewhere
|
|
43
|
+
|
|
44
|
+
### 5. Custom Editor
|
|
45
|
+
**Trigger:** Ticket triage, config editing, dataset curation
|
|
46
|
+
**Structure:** Drag/sort or form UI, constraint warnings, "copy as JSON/prompt" export button
|
|
47
|
+
**Don't:** Let the editor be the only output — always export
|
|
48
|
+
|
|
49
|
+
## Built-in design system
|
|
50
|
+
|
|
51
|
+
Inject this CSS block into every artifact. If the project has `docs/aikit-html-design-system.html`, read it first and use those variable values instead.
|
|
52
|
+
|
|
53
|
+
```css
|
|
54
|
+
:root {
|
|
55
|
+
--color-bg: #0f1117;
|
|
56
|
+
--color-surface: #1a1d27;
|
|
57
|
+
--color-border: #2e3143;
|
|
58
|
+
--color-text: #e2e8f0;
|
|
59
|
+
--color-muted: #8892a4;
|
|
60
|
+
--color-accent: #6366f1;
|
|
61
|
+
--color-ok: #22c55e;
|
|
62
|
+
--color-warn: #f59e0b;
|
|
63
|
+
--color-error: #ef4444;
|
|
64
|
+
--radius: 6px;
|
|
65
|
+
--font-sans: system-ui, -apple-system, sans-serif;
|
|
66
|
+
--font-mono: "JetBrains Mono", "Fira Code", monospace;
|
|
67
|
+
--space: 4px;
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Pre-built components available: `.card`, `.badge` (`.badge-ok/warn/error/info`), `.tabs` + `.tab` + `.tab-panel`, `.code-block`, `.diff-block` + `.diff-line` + `.diff-line-add/del/ctx`.
|
|
72
|
+
|
|
73
|
+
## Output rules
|
|
74
|
+
- Save to `.aikit/artifacts/<slug>-<timestamp>.html` (this path is gitignored)
|
|
75
|
+
- After saving, print the path and suggest: `open <path>` (macOS) or `xdg-open <path>` (Linux)
|
|
76
|
+
- Pure HTML/CSS/JS only — no external CDN dependencies, no build step
|
|
77
|
+
- Mobile-responsive: use `max-width` + `padding` on body, `<meta name="viewport">`
|
|
78
|
+
|
|
79
|
+
## Markdown-first rule
|
|
80
|
+
Existing brainstorming and planning skills stay markdown-first. Only switch to HTML when the user accepts the proactive offer or explicitly requests it (e.g. via `/html`). This preserves cross-tool compatibility.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: incident-response
|
|
3
|
+
description: Use when production is broken and service needs to be restored urgently. Three-phase checklist protocol — stabilize first, investigate second, post-mortem third. Explicit-only; do not use for non-production debugging.
|
|
4
|
+
version: "1.0.0"
|
|
5
|
+
source: haac-aikit
|
|
6
|
+
license: MIT
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## When to use
|
|
10
|
+
|
|
11
|
+
Explicit invocation only: "run incident response", "production is down", "start incident protocol"
|
|
12
|
+
|
|
13
|
+
Do not use for non-urgent debugging — use `systematic-debugging` instead.
|
|
14
|
+
|
|
15
|
+
## Phase 1 — Stabilize
|
|
16
|
+
|
|
17
|
+
Restore service before anything else. Do not investigate until service is confirmed restored.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
□ Identify blast radius — what is broken, how many users are affected
|
|
21
|
+
□ Check recent deploys, config changes, or infra events in the last 2 hours
|
|
22
|
+
□ Attempt fastest known mitigation: rollback, feature flag off, process restart
|
|
23
|
+
□ Confirm service is restored before moving to Phase 2
|
|
24
|
+
□ Note what action restored service — this becomes the root cause lead
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Phase 2 — Investigate
|
|
28
|
+
|
|
29
|
+
Root cause only — not symptoms.
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
□ Read the code path that failed — trace from entry point to failure
|
|
33
|
+
□ Identify the specific line or condition that caused the failure
|
|
34
|
+
□ Reproduce the failure locally or in staging if possible
|
|
35
|
+
□ Confirm the fix addresses root cause, not just the symptom
|
|
36
|
+
□ Write and run tests that would have caught this before production
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Phase 3 — Post-mortem
|
|
40
|
+
|
|
41
|
+
Document before closing. No incident is closed without a committed post-mortem.
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
□ Write post-mortem to docs/incidents/YYYY-MM-DD-<topic>.md
|
|
45
|
+
□ Use the template below
|
|
46
|
+
□ Commit the post-mortem and the fix together in the same commit
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Post-mortem template
|
|
50
|
+
|
|
51
|
+
```markdown
|
|
52
|
+
# Incident: <topic>
|
|
53
|
+
|
|
54
|
+
## Timeline
|
|
55
|
+
[Chronological: when detected, when mitigated, when resolved]
|
|
56
|
+
|
|
57
|
+
## Root Cause
|
|
58
|
+
[The specific code/config/infra condition that caused the failure]
|
|
59
|
+
|
|
60
|
+
## Impact
|
|
61
|
+
[What broke, for how long, estimated users affected]
|
|
62
|
+
|
|
63
|
+
## Fix Applied
|
|
64
|
+
[What was changed and why it resolves the root cause]
|
|
65
|
+
|
|
66
|
+
## Tests Added
|
|
67
|
+
[Test names and what regression they prevent]
|
|
68
|
+
|
|
69
|
+
## Prevention
|
|
70
|
+
[What would have caught this before production: monitoring, test, review]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Anti-patterns to avoid
|
|
74
|
+
|
|
75
|
+
- Jumping to Phase 2 before service is restored
|
|
76
|
+
- Writing a post-mortem that attributes cause to "human error" without a systemic fix
|
|
77
|
+
- Closing the incident without a committed test covering the regression
|
|
78
|
+
- Using `systematic-debugging` protocol during an active incident — that protocol is too slow
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performance-profiling
|
|
3
|
+
description: Use when something is slow, memory is high, latency spikes, or bundle/build size grows unexpectedly. Five-phase measure-first protocol covering runtime and build/bundle performance. Auto-triggers on performance signals; also explicitly invokable.
|
|
4
|
+
version: "1.0.0"
|
|
5
|
+
source: haac-aikit
|
|
6
|
+
license: MIT
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## When to use
|
|
10
|
+
|
|
11
|
+
Auto-trigger on: "slow", "timeout", "latency spike", "high memory", "bundle too large", "CI is slow", "build taking forever"
|
|
12
|
+
|
|
13
|
+
Explicit: "profile this", "why is this slow", "performance issue with X"
|
|
14
|
+
|
|
15
|
+
## Phase 1 — Measure
|
|
16
|
+
|
|
17
|
+
Record baseline before touching anything. If you cannot reproduce the slow path, stop and surface the blocker — do not proceed to Phase 2.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
□ Runtime: response time, memory usage, query count, CPU %
|
|
21
|
+
□ Build/bundle: build duration, bundle size, chunk sizes
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Phase 2 — Identify
|
|
25
|
+
|
|
26
|
+
Pinpoint the specific cause. Do not guess — name the exact line, function, query, or step responsible.
|
|
27
|
+
|
|
28
|
+
**Runtime:**
|
|
29
|
+
```
|
|
30
|
+
□ Trace the slow code path from entry point to bottleneck
|
|
31
|
+
□ Check for N+1 queries, missing indexes, unbounded loops
|
|
32
|
+
□ Check for unnecessary re-renders, redundant computations, memory leaks
|
|
33
|
+
□ Name the single line or function responsible
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**Build/bundle:**
|
|
37
|
+
```
|
|
38
|
+
□ Identify largest bundle chunks and their source
|
|
39
|
+
□ Check for duplicate dependencies, unoptimized imports, missing tree-shaking
|
|
40
|
+
□ Check CI step durations — identify the single slowest step
|
|
41
|
+
□ Name the specific package, import, or step responsible
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Phase 3 — Fix
|
|
45
|
+
|
|
46
|
+
One focused change per commit. Do not combine multiple fixes.
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
□ Make one targeted change
|
|
50
|
+
□ Explain why this change addresses the root cause from Phase 2
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Phase 4 — Verify
|
|
54
|
+
|
|
55
|
+
Re-run the exact same measurements from Phase 1. Confirm improvement is real and no regressions introduced.
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
□ Measure again using the same method as Phase 1
|
|
59
|
+
□ Confirm measurable improvement (not just "feels faster")
|
|
60
|
+
□ Confirm no regressions in adjacent functionality
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Phase 5 — Report
|
|
64
|
+
|
|
65
|
+
Write and commit a brief performance report.
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
□ Save to docs/performance/YYYY-MM-DD-<topic>.md
|
|
69
|
+
□ Template: Symptom | Baseline | Root Cause | Fix | Result
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Report template
|
|
73
|
+
|
|
74
|
+
```markdown
|
|
75
|
+
# Performance: <topic>
|
|
76
|
+
|
|
77
|
+
## Symptom
|
|
78
|
+
[What was slow/large and how it was reported]
|
|
79
|
+
|
|
80
|
+
## Baseline
|
|
81
|
+
[Measurements taken before any changes]
|
|
82
|
+
|
|
83
|
+
## Root Cause
|
|
84
|
+
[The specific line, query, import, or step responsible]
|
|
85
|
+
|
|
86
|
+
## Fix Applied
|
|
87
|
+
[What was changed and why it addresses the root cause]
|
|
88
|
+
|
|
89
|
+
## Result
|
|
90
|
+
[Measurements after the fix — improvement percentage]
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Anti-patterns to avoid
|
|
94
|
+
|
|
95
|
+
- Fixing before measuring — you cannot confirm improvement without a baseline
|
|
96
|
+
- Combining multiple fixes in one commit — makes it impossible to attribute the improvement
|
|
97
|
+
- Closing without verifying — "should be faster" is not a result
|
|
98
|
+
- Guessing the bottleneck without tracing — profiling means finding, not assuming
|