@dzhechkov/keysarium 1.4.0 → 1.5.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 +50 -3
- package/bin/cli.js +0 -0
- package/package.json +5 -3
- package/templates/.claude/commands/analyst-manual.md +38 -0
- package/templates/.claude/commands/casarium.md +55 -4
- package/templates/.claude/commands/feature-adr.md +8 -0
- package/templates/.claude/rules/trust-tiers.md +5 -0
- package/templates/.claude/shards/feature-adr.shard.md +64 -10
- package/templates/.claude/shards/phase-ai-factory.shard.md +109 -0
- package/templates/.claude/skills/ai-factory-mapper/README.md +90 -0
- package/templates/.claude/skills/ai-factory-mapper/SKILL.md +309 -0
- package/templates/.claude/skills/ai-factory-mapper/assets/report-template.md +123 -0
- package/templates/.claude/skills/ai-factory-mapper/references/catalog.md +230 -0
- package/templates/.claude/skills/ai-factory-mapper/references/coverage-formula.md +219 -0
- package/templates/.claude/skills/ai-factory-mapper/references/decomposition-checklist.md +183 -0
- package/templates/.claude/skills/ai-factory-mapper/references/pattern-library.md +312 -0
- package/templates/.claude/skills/ai-factory-mapper/scripts/build_docx_report.js +423 -0
- package/templates/.claude/skills/analyst-manual-full/SKILL.md +286 -0
- package/templates/.claude/skills/edu-site-generator/SKILL.md +254 -0
- package/templates/.claude/skills/edu-site-generator/examples/sample-course-structure.md +116 -0
- package/templates/.claude/skills/edu-site-generator/modules/00-content-analysis.md +84 -0
- package/templates/.claude/skills/edu-site-generator/modules/01-course-structure.md +75 -0
- package/templates/.claude/skills/edu-site-generator/modules/02-data-generation.md +186 -0
- package/templates/.claude/skills/edu-site-generator/modules/03-scaffold.md +249 -0
- package/templates/.claude/skills/edu-site-generator/modules/04-components.md +130 -0
- package/templates/.claude/skills/edu-site-generator/modules/05-gamification.md +163 -0
- package/templates/.claude/skills/edu-site-generator/modules/06-deploy.md +88 -0
- package/templates/.claude/skills/edu-site-generator/modules/07-verification.md +97 -0
- package/templates/.claude/skills/edu-site-generator/references/component-templates.md +436 -0
- package/templates/.claude/skills/edu-site-generator/references/data-schemas.md +164 -0
- package/templates/.claude/skills/edu-site-generator/references/exercise-catalog.md +110 -0
- package/templates/.claude/skills/edu-site-generator/references/tech-stack.md +69 -0
- package/templates/.claude/skills/feature-adr/SKILL.md +245 -59
- package/templates/.claude/skills/feature-adr/modules/03-adr.md +43 -0
- package/templates/.claude/skills/feature-adr/modules/03.5-ideation-swarm.md +180 -0
- package/templates/.claude/skills/feature-adr/modules/06-implementation-plan.md +56 -7
- package/templates/.claude/skills/feature-adr/modules/08-qe.md +87 -23
- package/templates/.claude/skills/feature-adr/modules/09-fleet-qe.md +305 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/README.md +143 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/brutal-honesty-review.md +240 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/chaos-engineering-resilience.md +163 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/code-goal-planner.md +446 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/enterprise-integration-testing.md +111 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/mutation-testing.md +236 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/performance-testing.md +315 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/qcsd-ideation-swarm.md +126 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/qcsd-production-swarm.md +108 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/qe-coverage-analysis.md +193 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/qe-requirements-validation.md +254 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/regression-testing.md +233 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/risk-based-testing.md +212 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/security-testing.md +311 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/shift-left-testing.md +231 -0
- package/templates/.claude/skills/feature-adr/references/agentic-qe/tdd-london-chicago.md +249 -0
- package/templates/.claude/skills/transcript-site-generator/SKILL.md +287 -0
- package/templates/.claude/skills/transcript-site-generator/examples/sample-text-only-site.md +123 -0
- package/templates/.claude/skills/transcript-site-generator/examples/sample-transcript-site.md +134 -0
- package/templates/.claude/skills/transcript-site-generator/modules/00-input-analysis.md +132 -0
- package/templates/.claude/skills/transcript-site-generator/modules/01-content-parsing.md +117 -0
- package/templates/.claude/skills/transcript-site-generator/modules/02-site-generation.md +293 -0
- package/templates/.claude/skills/transcript-site-generator/modules/03-interactivity.md +406 -0
- package/templates/.claude/skills/transcript-site-generator/modules/04-deploy.md +130 -0
- package/templates/.claude/skills/transcript-site-generator/modules/05-verification.md +155 -0
- package/templates/.claude/skills/transcript-site-generator/references/component-catalog.md +86 -0
- package/templates/.claude/skills/transcript-site-generator/references/data-schemas.md +123 -0
- package/templates/.claude/skills/transcript-site-generator/references/tech-stack.md +132 -0
- package/templates/CLAUDE.md +9 -2
- package/templates/docs/edu-site-generator/01-deployment-guide.md +911 -0
- package/templates/docs/edu-site-generator/02-admin-guide.md +901 -0
- package/templates/docs/edu-site-generator/03-user-guide.md +1008 -0
- package/templates/docs/edu-site-generator/04-infrastructure-requirements.md +489 -0
- package/templates/docs/edu-site-generator/05-architecture.md +902 -0
- package/templates/docs/edu-site-generator/06-user-flows.md +759 -0
- package/templates/docs/transcript-site-generator/01-deployment-guide.md +1042 -0
- package/templates/docs/transcript-site-generator/02-admin-guide.md +918 -0
- package/templates/docs/transcript-site-generator/03-user-guide.md +925 -0
- package/templates/docs/transcript-site-generator/04-infrastructure-requirements.md +482 -0
- package/templates/docs/transcript-site-generator/05-architecture.md +1068 -0
- package/templates/docs/transcript-site-generator/06-user-flows.md +855 -0
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tdd-london-chicago
|
|
3
|
+
description: "Apply London (mock-based) and Chicago (state-based) TDD schools. Use when practicing test-driven development or choosing testing style for your context."
|
|
4
|
+
category: development-practices
|
|
5
|
+
priority: high
|
|
6
|
+
tokenEstimate: 1100
|
|
7
|
+
agents: [qe-test-generator, qe-test-implementer, qe-test-refactorer]
|
|
8
|
+
implementation_status: optimized
|
|
9
|
+
optimization_version: 1.0
|
|
10
|
+
last_optimized: 2025-12-02
|
|
11
|
+
dependencies: []
|
|
12
|
+
quick_reference_card: true
|
|
13
|
+
tags: [tdd, testing, london-school, chicago-school, red-green-refactor, mocks]
|
|
14
|
+
trust_tier: 2
|
|
15
|
+
validation:
|
|
16
|
+
schema_path: schemas/output.json
|
|
17
|
+
validator_path: scripts/validate-config.json
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
# Test-Driven Development: London & Chicago Schools
|
|
22
|
+
|
|
23
|
+
<default_to_action>
|
|
24
|
+
When implementing TDD or choosing testing style:
|
|
25
|
+
1. IDENTIFY code type: domain logic → Chicago, external deps → London
|
|
26
|
+
2. WRITE failing test first (Red phase)
|
|
27
|
+
3. IMPLEMENT minimal code to pass (Green phase)
|
|
28
|
+
4. REFACTOR while keeping tests green (Refactor phase)
|
|
29
|
+
5. REPEAT cycle for next functionality
|
|
30
|
+
|
|
31
|
+
**Quick Style Selection:**
|
|
32
|
+
- Pure functions/calculations → Chicago (real objects, state verification)
|
|
33
|
+
- Controllers/services with deps → London (mocks, interaction verification)
|
|
34
|
+
- Value objects → Chicago (test final state)
|
|
35
|
+
- API integrations → London (mock external services)
|
|
36
|
+
- Mix both in practice (London for controllers, Chicago for domain)
|
|
37
|
+
|
|
38
|
+
**Critical Success Factors:**
|
|
39
|
+
- Tests drive design, not just verify it
|
|
40
|
+
- Make tests fail first to ensure they test something
|
|
41
|
+
- Write minimal code - no features beyond what's tested
|
|
42
|
+
</default_to_action>
|
|
43
|
+
|
|
44
|
+
## Quick Reference Card
|
|
45
|
+
|
|
46
|
+
### When to Use
|
|
47
|
+
- Starting new feature with test-first approach
|
|
48
|
+
- Refactoring legacy code with test coverage
|
|
49
|
+
- Teaching TDD practices to team
|
|
50
|
+
- Choosing between mocking vs real objects
|
|
51
|
+
|
|
52
|
+
### TDD Cycle
|
|
53
|
+
| Phase | Action | Discipline |
|
|
54
|
+
|-------|--------|------------|
|
|
55
|
+
| **Red** | Write failing test | Verify it fails, check message is clear |
|
|
56
|
+
| **Green** | Minimal code to pass | No extra features, don't refactor |
|
|
57
|
+
| **Refactor** | Improve structure | Keep tests passing, no new functionality |
|
|
58
|
+
|
|
59
|
+
### School Comparison
|
|
60
|
+
| Aspect | Chicago (Classicist) | London (Mockist) |
|
|
61
|
+
|--------|---------------------|------------------|
|
|
62
|
+
| Collaborators | Real objects | Mocks/stubs |
|
|
63
|
+
| Verification | State (assert outcomes) | Interaction (assert calls) |
|
|
64
|
+
| Isolation | Lower (integrated) | Higher (unit only) |
|
|
65
|
+
| Refactoring | Easier | Harder (mocks break) |
|
|
66
|
+
| Design feedback | Emerges from use | Explicit from start |
|
|
67
|
+
|
|
68
|
+
### Agent Coordination
|
|
69
|
+
- `qe-test-generator`: Generate tests in both schools
|
|
70
|
+
- `qe-test-implementer`: Implement minimal code (Green)
|
|
71
|
+
- `qe-test-refactorer`: Safe refactoring (Refactor)
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Chicago School (State-Based)
|
|
76
|
+
|
|
77
|
+
**Philosophy:** Test observable behavior through public API. Keep tests close to consumer usage.
|
|
78
|
+
|
|
79
|
+
```javascript
|
|
80
|
+
// State verification - test final outcome
|
|
81
|
+
describe('Order', () => {
|
|
82
|
+
it('calculates total with tax', () => {
|
|
83
|
+
const order = new Order();
|
|
84
|
+
order.addItem(new Product('Widget', 10.00), 2);
|
|
85
|
+
order.addItem(new Product('Gadget', 15.00), 1);
|
|
86
|
+
|
|
87
|
+
expect(order.totalWithTax(0.10)).toBe(38.50);
|
|
88
|
+
});
|
|
89
|
+
});
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**When Chicago Shines:**
|
|
93
|
+
- Domain logic with clear state
|
|
94
|
+
- Algorithms and calculations
|
|
95
|
+
- Value objects (`Money`, `Email`)
|
|
96
|
+
- Simple collaborations
|
|
97
|
+
- Learning new domain
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## London School (Mock-Based)
|
|
102
|
+
|
|
103
|
+
**Philosophy:** Test each unit in isolation. Focus on how objects collaborate.
|
|
104
|
+
|
|
105
|
+
```javascript
|
|
106
|
+
// Interaction verification - test method calls
|
|
107
|
+
describe('Order', () => {
|
|
108
|
+
it('delegates tax calculation', () => {
|
|
109
|
+
const taxCalculator = {
|
|
110
|
+
calculateTax: jest.fn().mockReturnValue(3.50)
|
|
111
|
+
};
|
|
112
|
+
const order = new Order(taxCalculator);
|
|
113
|
+
order.addItem({ price: 10 }, 2);
|
|
114
|
+
|
|
115
|
+
order.totalWithTax();
|
|
116
|
+
|
|
117
|
+
expect(taxCalculator.calculateTax).toHaveBeenCalledWith(20.00);
|
|
118
|
+
});
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
**When London Shines:**
|
|
123
|
+
- External integrations (DB, APIs)
|
|
124
|
+
- Command patterns with side effects
|
|
125
|
+
- Complex workflows
|
|
126
|
+
- Slow operations (network, I/O)
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Mixed Approach (Recommended)
|
|
131
|
+
|
|
132
|
+
```javascript
|
|
133
|
+
// London for controller (external deps)
|
|
134
|
+
describe('OrderController', () => {
|
|
135
|
+
it('creates order and sends confirmation', async () => {
|
|
136
|
+
const orderService = { create: jest.fn().mockResolvedValue({ id: 123 }) };
|
|
137
|
+
const emailService = { send: jest.fn() };
|
|
138
|
+
|
|
139
|
+
const controller = new OrderController(orderService, emailService);
|
|
140
|
+
await controller.placeOrder(orderData);
|
|
141
|
+
|
|
142
|
+
expect(orderService.create).toHaveBeenCalledWith(orderData);
|
|
143
|
+
expect(emailService.send).toHaveBeenCalled();
|
|
144
|
+
});
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
// Chicago for domain logic
|
|
148
|
+
describe('OrderService', () => {
|
|
149
|
+
it('applies discount when threshold met', () => {
|
|
150
|
+
const service = new OrderService();
|
|
151
|
+
const order = service.create({ items: [...], total: 150 });
|
|
152
|
+
|
|
153
|
+
expect(order.discount).toBe(15); // 10% off > $100
|
|
154
|
+
});
|
|
155
|
+
});
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Common Pitfalls
|
|
161
|
+
|
|
162
|
+
### ❌ Over-Mocking (London)
|
|
163
|
+
```javascript
|
|
164
|
+
// BAD - mocking everything
|
|
165
|
+
const product = { getName: jest.fn(), getPrice: jest.fn() };
|
|
166
|
+
```
|
|
167
|
+
**Better:** Only mock external dependencies.
|
|
168
|
+
|
|
169
|
+
### ❌ Mocking Internals
|
|
170
|
+
```javascript
|
|
171
|
+
// BAD - testing private methods
|
|
172
|
+
expect(order._calculateSubtotal).toHaveBeenCalled();
|
|
173
|
+
```
|
|
174
|
+
**Better:** Test public behavior only.
|
|
175
|
+
|
|
176
|
+
### ❌ Test Pain = Design Pain
|
|
177
|
+
- Need many mocks? → Too many dependencies
|
|
178
|
+
- Hard to set up? → Constructor does too much
|
|
179
|
+
- Can't test without database? → Coupling issue
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Agent-Assisted TDD
|
|
184
|
+
|
|
185
|
+
```typescript
|
|
186
|
+
// Agent generates tests in both schools
|
|
187
|
+
await Task("Generate Tests", {
|
|
188
|
+
style: 'chicago', // or 'london'
|
|
189
|
+
target: 'src/domain/Order.ts',
|
|
190
|
+
focus: 'state-verification' // or 'collaboration-patterns'
|
|
191
|
+
}, "qe-test-generator");
|
|
192
|
+
|
|
193
|
+
// Agent-human ping-pong TDD
|
|
194
|
+
// Human writes test concept
|
|
195
|
+
const testIdea = "Order applies 10% discount when total > $100";
|
|
196
|
+
|
|
197
|
+
// Agent generates formal failing test (Red)
|
|
198
|
+
await Task("Create Failing Test", testIdea, "qe-test-generator");
|
|
199
|
+
|
|
200
|
+
// Human writes minimal code (Green)
|
|
201
|
+
|
|
202
|
+
// Agent suggests refactorings
|
|
203
|
+
await Task("Suggest Refactorings", { preserveTests: true }, "qe-test-refactorer");
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## Agent Coordination Hints
|
|
209
|
+
|
|
210
|
+
### Memory Namespace
|
|
211
|
+
```
|
|
212
|
+
aqe/tdd/
|
|
213
|
+
├── test-plan/* - TDD session plans
|
|
214
|
+
├── red-phase/* - Failing tests generated
|
|
215
|
+
├── green-phase/* - Implementation code
|
|
216
|
+
└── refactor-phase/* - Refactoring suggestions
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Fleet Coordination
|
|
220
|
+
```typescript
|
|
221
|
+
const tddFleet = await FleetManager.coordinate({
|
|
222
|
+
workflow: 'red-green-refactor',
|
|
223
|
+
agents: {
|
|
224
|
+
testGenerator: 'qe-test-generator',
|
|
225
|
+
testExecutor: 'qe-test-executor',
|
|
226
|
+
qualityAnalyzer: 'qe-quality-analyzer'
|
|
227
|
+
},
|
|
228
|
+
mode: 'sequential'
|
|
229
|
+
});
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## Related Skills
|
|
235
|
+
- [agentic-quality-engineering](../agentic-quality-engineering/) - TDD with agent coordination
|
|
236
|
+
- [refactoring-patterns](../refactoring-patterns/) - Refactor phase techniques
|
|
237
|
+
- [api-testing-patterns](../api-testing-patterns/) - London school for API testing
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Remember
|
|
242
|
+
|
|
243
|
+
**Chicago:** Test state, use real objects, refactor freely
|
|
244
|
+
**London:** Test interactions, mock dependencies, design interfaces first
|
|
245
|
+
**Both:** Write the test first, make it pass, refactor
|
|
246
|
+
|
|
247
|
+
Neither is "right." Choose based on context. Mix as needed. Goal: well-designed, tested code.
|
|
248
|
+
|
|
249
|
+
**With Agents:** Agents excel at generating tests, validating green phase, and suggesting refactorings. Use agents to maintain TDD discipline while humans focus on design decisions.
|
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
# transcript-site-generator — Interactive Transcript Site Generator
|
|
2
|
+
|
|
3
|
+
<!-- Trust Tier: 2 — Validated | BTO Layer 2 Score: 7.82/10 | Promoted: 2026-03-05 -->
|
|
4
|
+
|
|
5
|
+
> Generate a modern, interactive, mobile-friendly, SEO-optimized static website from a transcript or YouTube video link, ready for GitHub Pages deployment. Zero build step required.
|
|
6
|
+
|
|
7
|
+
## When To Activate
|
|
8
|
+
|
|
9
|
+
Trigger on:
|
|
10
|
+
- "generate transcript site from [content]"
|
|
11
|
+
- "create interactive transcript [topic]"
|
|
12
|
+
- "build transcript website from YouTube [url]"
|
|
13
|
+
- "сгенерируй сайт из транскрипта"
|
|
14
|
+
- "сделай сайт из видео [url]"
|
|
15
|
+
- `/transcript-site [content or YouTube URL]`
|
|
16
|
+
|
|
17
|
+
## Overview
|
|
18
|
+
|
|
19
|
+
This skill transforms text transcripts, content, or YouTube video links into production-ready interactive websites. The **default output is a pure static site** (single HTML + JS file) that deploys to GitHub Pages with zero build step — no React, no Vite, no npm install needed.
|
|
20
|
+
|
|
21
|
+
### Features
|
|
22
|
+
|
|
23
|
+
- **Interactive transcript** with section navigation, scroll-spy TOC, full-text search (Ctrl+K)
|
|
24
|
+
- **YouTube embed** with clickable timestamps for video synchronization (if URL provided)
|
|
25
|
+
- **Dark/Light mode** toggle with localStorage persistence
|
|
26
|
+
- **Reading progress bar** and back-to-top button
|
|
27
|
+
- **Copy-quote** buttons per section (copies section text to clipboard)
|
|
28
|
+
- **Reading statistics** (word count, estimated reading time, section count)
|
|
29
|
+
- **SEO optimization** — Open Graph, Twitter Cards, JSON-LD (VideoObject/Article)
|
|
30
|
+
- **Print-friendly** CSS media queries
|
|
31
|
+
- **GitHub Pages** deployment via `docs/` folder (zero build) or GitHub Actions
|
|
32
|
+
- **Mobile-friendly** — responsive layout, hamburger menu, 44px touch targets
|
|
33
|
+
- **Speaker labels** — automatic speaker detection and visual differentiation
|
|
34
|
+
|
|
35
|
+
## Architecture
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
.claude/skills/transcript-site-generator/
|
|
39
|
+
├── SKILL.md <- This file (orchestrator)
|
|
40
|
+
├── modules/
|
|
41
|
+
│ ├── 00-input-analysis.md <- Step 0: Detect input type, extract transcript
|
|
42
|
+
│ ├── 01-content-parsing.md <- Step 1: Split into sections, extract timestamps
|
|
43
|
+
│ ├── 02-site-generation.md <- Step 2: Generate index.html with all content
|
|
44
|
+
│ ├── 03-interactivity.md <- Step 3: Generate app.js (search, TOC, dark mode)
|
|
45
|
+
│ ├── 04-deploy.md <- Step 4: GitHub Pages config + Actions workflow
|
|
46
|
+
│ └── 05-verification.md <- Step 5: Validate output, open in browser
|
|
47
|
+
├── references/
|
|
48
|
+
│ ├── tech-stack.md <- Stack: Tailwind CDN, vanilla JS, static HTML
|
|
49
|
+
│ ├── data-schemas.md <- Section data structure, metadata schema
|
|
50
|
+
│ └── component-catalog.md <- HTML sections and JS modules catalog
|
|
51
|
+
└── examples/
|
|
52
|
+
├── sample-transcript-site.md <- Example: YouTube + Russian podcast
|
|
53
|
+
└── sample-text-only-site.md <- Example: text-only, English, no YouTube
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Pipeline
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
Step 0 Step 1 Step 2 Step 3
|
|
60
|
+
INPUT -> PARSE -> GENERATE -> INTERACTIVITY
|
|
61
|
+
(text/URL/ (split into (index.html (app.js:
|
|
62
|
+
yt-dlp) sections + with Tailwind search, TOC,
|
|
63
|
+
timestamps) CDN + content) dark mode)
|
|
64
|
+
|
|
65
|
+
|
|
|
66
|
+
v
|
|
67
|
+
Step 4 Step 5
|
|
68
|
+
DEPLOY -> VERIFY
|
|
69
|
+
(docs/ + (file check
|
|
70
|
+
GH Actions + open)
|
|
71
|
+
workflow)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Input Requirements
|
|
75
|
+
|
|
76
|
+
The skill accepts one of:
|
|
77
|
+
1. **Text transcript** — pasted directly or as a file path
|
|
78
|
+
2. **YouTube URL** — extracts transcript via `yt-dlp --write-auto-sub --sub-lang ru,en --skip-download`
|
|
79
|
+
3. **Both** — YouTube URL for embed + custom/edited transcript text
|
|
80
|
+
|
|
81
|
+
Minimum: enough content for 3 sections. No maximum (long transcripts benefit most from navigation).
|
|
82
|
+
|
|
83
|
+
### YouTube Transcript Extraction
|
|
84
|
+
|
|
85
|
+
When a YouTube URL is provided:
|
|
86
|
+
```bash
|
|
87
|
+
# Check yt-dlp availability
|
|
88
|
+
which yt-dlp || pip install yt-dlp
|
|
89
|
+
|
|
90
|
+
# Extract auto-generated subtitles (prefer manual, fallback to auto)
|
|
91
|
+
yt-dlp --write-sub --sub-lang ru,en --skip-download --sub-format vtt -o "/tmp/transcript" "<URL>" 2>/dev/null \
|
|
92
|
+
|| yt-dlp --write-auto-sub --sub-lang ru,en --skip-download --sub-format vtt -o "/tmp/transcript" "<URL>"
|
|
93
|
+
|
|
94
|
+
# Extract video metadata
|
|
95
|
+
yt-dlp --print title --print channel --print duration --skip-download "<URL>"
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
If `yt-dlp` is not installed:
|
|
99
|
+
```
|
|
100
|
+
yt-dlp not found. Install with: pip install yt-dlp
|
|
101
|
+
Alternatively, paste the transcript text directly.
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Output
|
|
105
|
+
|
|
106
|
+
A **pure static site** in the `docs/` directory — zero build step, deploys directly via GitHub Pages:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
<project-root>/
|
|
110
|
+
├── docs/ <- GitHub Pages source
|
|
111
|
+
│ ├── index.html (99KB+ single-file: HTML + inline Tailwind + SEO)
|
|
112
|
+
│ └── static/
|
|
113
|
+
│ ├── app.js (search, TOC scroll-spy, dark mode, progress bar)
|
|
114
|
+
│ └── style.css (minimal overrides)
|
|
115
|
+
├── .github/workflows/deploy.yml (GitHub Pages deployment workflow)
|
|
116
|
+
└── README.md (project description + link to live site)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### index.html Structure
|
|
120
|
+
|
|
121
|
+
The HTML file is self-contained with:
|
|
122
|
+
- **Tailwind CSS via CDN** (`<script src="https://cdn.tailwindcss.com">`) with dark mode config
|
|
123
|
+
- **Font Awesome via CDN** for icons (moon/sun, search, copy, hamburger)
|
|
124
|
+
- **Full SEO head**: Open Graph, Twitter Cards, JSON-LD structured data
|
|
125
|
+
- **Semantic HTML**: `<header>`, `<nav>`, `<main>`, `<article>`, `<section>`, `<footer>`
|
|
126
|
+
- **All transcript content** rendered as HTML sections with anchor IDs
|
|
127
|
+
- **Responsive layout**: fixed sidebar TOC (desktop) + hamburger menu (mobile)
|
|
128
|
+
- **YouTube embed** (if video URL provided): responsive iframe with aspect-ratio container
|
|
129
|
+
|
|
130
|
+
### app.js Features
|
|
131
|
+
|
|
132
|
+
Vanilla JavaScript (no frameworks) implementing:
|
|
133
|
+
- **Full-text search** — Ctrl+K modal, 300ms debounce, highlighted results with context
|
|
134
|
+
- **TOC scroll-spy** — IntersectionObserver highlights the active section in sidebar
|
|
135
|
+
- **Dark/Light mode** — toggle with localStorage persistence, icon switch (moon/sun)
|
|
136
|
+
- **Reading progress bar** — requestAnimationFrame-based scroll tracking
|
|
137
|
+
- **Back-to-top button** — appears after 500px scroll
|
|
138
|
+
- **Copy-quote** — per-section copy button with "Copied!" feedback
|
|
139
|
+
- **Mobile navigation** — hamburger toggle with slide-out sidebar
|
|
140
|
+
- **Keyboard shortcuts** — Ctrl/Cmd+K (search), Escape (close modal)
|
|
141
|
+
- **Timestamp links** — clickable timestamps that seek YouTube player (if embedded)
|
|
142
|
+
|
|
143
|
+
## Execution Protocol
|
|
144
|
+
|
|
145
|
+
### Step 0: Input Analysis
|
|
146
|
+
```
|
|
147
|
+
Read: modules/00-input-analysis.md
|
|
148
|
+
```
|
|
149
|
+
- Detect input type (text / YouTube URL / both)
|
|
150
|
+
- If YouTube URL: extract transcript via yt-dlp, get video metadata
|
|
151
|
+
- If text: accept as-is
|
|
152
|
+
- Detect language (Russian / English)
|
|
153
|
+
- **Output:** Raw transcript text + optional video metadata + language
|
|
154
|
+
|
|
155
|
+
### Step 1: Content Parsing
|
|
156
|
+
```
|
|
157
|
+
Read: modules/01-content-parsing.md
|
|
158
|
+
```
|
|
159
|
+
- Split transcript into logical sections (by topic shifts, speaker changes, or markers)
|
|
160
|
+
- Extract timestamps if present (from VTT or inline `[HH:MM:SS]`)
|
|
161
|
+
- Generate section titles from content
|
|
162
|
+
- Detect speakers if multi-speaker transcript
|
|
163
|
+
- Calculate word counts and reading time
|
|
164
|
+
- **Output:** Structured section list with titles, content, timestamps, speakers
|
|
165
|
+
|
|
166
|
+
### Step 2: Site Generation
|
|
167
|
+
```
|
|
168
|
+
Read: modules/02-site-generation.md
|
|
169
|
+
Read: references/data-schemas.md
|
|
170
|
+
```
|
|
171
|
+
- Generate `docs/index.html` — complete self-contained page:
|
|
172
|
+
- Tailwind CSS + Font Awesome via CDN
|
|
173
|
+
- Full SEO meta tags (OG, Twitter, JSON-LD)
|
|
174
|
+
- Header with title, stats, dark mode toggle, search button
|
|
175
|
+
- Sidebar TOC with all section links
|
|
176
|
+
- YouTube embed (if video URL provided)
|
|
177
|
+
- All transcript sections as HTML with anchor IDs
|
|
178
|
+
- Footer with author credits and source link
|
|
179
|
+
- Generate `docs/static/style.css` — minimal CSS overrides
|
|
180
|
+
- **Output:** Complete HTML + CSS files
|
|
181
|
+
|
|
182
|
+
### Step 3: Interactivity
|
|
183
|
+
```
|
|
184
|
+
Read: modules/03-interactivity.md
|
|
185
|
+
Read: references/component-catalog.md
|
|
186
|
+
```
|
|
187
|
+
- Generate `docs/static/app.js` — vanilla JS:
|
|
188
|
+
- Search modal with highlighting and context snippets
|
|
189
|
+
- TOC scroll-spy (IntersectionObserver)
|
|
190
|
+
- Dark mode toggle with localStorage
|
|
191
|
+
- Reading progress bar
|
|
192
|
+
- Back-to-top button
|
|
193
|
+
- Copy-quote buttons
|
|
194
|
+
- Mobile hamburger menu
|
|
195
|
+
- Keyboard shortcuts
|
|
196
|
+
- YouTube timestamp sync (if video embedded)
|
|
197
|
+
- **Output:** Complete JS file
|
|
198
|
+
|
|
199
|
+
### Step 4: Deployment
|
|
200
|
+
```
|
|
201
|
+
Read: modules/04-deploy.md
|
|
202
|
+
```
|
|
203
|
+
- Create `.github/workflows/deploy.yml` for GitHub Pages from `docs/`
|
|
204
|
+
- Create or update `README.md` with project description and live site link
|
|
205
|
+
- Configure GitHub Pages source as `docs/` on `main` branch
|
|
206
|
+
- **Output:** Deploy config + README
|
|
207
|
+
|
|
208
|
+
### Step 5: Verification
|
|
209
|
+
```
|
|
210
|
+
Read: modules/05-verification.md
|
|
211
|
+
```
|
|
212
|
+
- Verify `docs/index.html` exists and has valid HTML structure
|
|
213
|
+
- Verify `docs/static/app.js` exists and has no syntax errors
|
|
214
|
+
- Check all section IDs are unique
|
|
215
|
+
- Check SEO meta tags are present
|
|
216
|
+
- Verify mobile responsiveness classes
|
|
217
|
+
- Check dark mode CSS works
|
|
218
|
+
- **Output:** Verification report
|
|
219
|
+
|
|
220
|
+
## Customization Points
|
|
221
|
+
|
|
222
|
+
| Parameter | Default | How to specify | Description |
|
|
223
|
+
|-----------|---------|---------------|-------------|
|
|
224
|
+
| Language | auto-detect | "language: en" in prompt | UI language (ru/en) |
|
|
225
|
+
| Theme color | Indigo | "use green theme" in prompt | Primary Tailwind color palette |
|
|
226
|
+
| YouTube URL | none | Include URL in input | Optional video embed with timestamps |
|
|
227
|
+
| Author | from transcript/video | "author: John Doe" in prompt | Attribution in footer |
|
|
228
|
+
| Show timestamps | auto (if available) | "hide timestamps" in prompt | Toggle timestamp display |
|
|
229
|
+
| Show stats | yes | "no stats" in prompt | Word count, reading time in header |
|
|
230
|
+
| Show copy buttons | yes | "no copy buttons" in prompt | Copy-quote per section |
|
|
231
|
+
| Output dir | docs/ | "output to site/" in prompt | Static site output directory |
|
|
232
|
+
| Deploy method | docs/ folder | "use GitHub Actions" in prompt | `docs/` (zero build) or GitHub Actions |
|
|
233
|
+
|
|
234
|
+
Customization is passed via natural language in the user's prompt. The agent parses these from the initial request during Step 0. If the output directory is not `docs/`, update the deploy workflow `path` accordingly.
|
|
235
|
+
|
|
236
|
+
### Conflict Detection
|
|
237
|
+
|
|
238
|
+
Before writing to the output directory, check if it already exists:
|
|
239
|
+
- If `docs/` has existing content, warn: `"docs/ already exists. Overwrite? (yes/no/use different dir)"`
|
|
240
|
+
- Never silently overwrite existing files
|
|
241
|
+
|
|
242
|
+
## Large Transcript Strategy
|
|
243
|
+
|
|
244
|
+
For transcripts exceeding 30,000 words (~150 KB HTML output), the generated `index.html` may exceed single-file output limits. In this case:
|
|
245
|
+
|
|
246
|
+
1. **Generate the HTML shell first** — `<head>`, header, sidebar TOC, search modal, footer (without section content)
|
|
247
|
+
2. **Generate transcript sections in batches** — 5-10 sections per Write operation, appending to the HTML file
|
|
248
|
+
3. **Close the HTML** — add closing `</main>`, `</div>`, `</body>`, `</html>` tags
|
|
249
|
+
4. **Verify integrity** — check that `</html>` appears exactly once and all section IDs are present
|
|
250
|
+
|
|
251
|
+
This chunked approach ensures complete output regardless of transcript length.
|
|
252
|
+
|
|
253
|
+
## Anti-Patterns
|
|
254
|
+
|
|
255
|
+
| Anti-Pattern | Detection | Fix |
|
|
256
|
+
|-------------|-----------|-----|
|
|
257
|
+
| Using React/Vite for simple transcript | Unnecessary complexity | Use static HTML + vanilla JS (default) |
|
|
258
|
+
| Transcript split into too many files | Multiple HTML pages | Single index.html with anchor navigation |
|
|
259
|
+
| Missing Tailwind CDN script | No styling | Always include `<script src="https://cdn.tailwindcss.com">` |
|
|
260
|
+
| Missing dark mode config in Tailwind | Dark mode broken | Add `tailwind.config = { darkMode: 'class' }` |
|
|
261
|
+
| Too few sections (<3) | Not enough for navigation | Merge more content or split deeper |
|
|
262
|
+
| Giant monolithic section | Section > 3000 words | Split into sub-sections |
|
|
263
|
+
| No search results feedback | Empty search shows nothing | Show "no results" message |
|
|
264
|
+
| Missing print styles | Page breaks mid-section | Add `@media print` rules |
|
|
265
|
+
| No mobile TOC | Desktop-only sidebar | Add hamburger menu for screens < 768px |
|
|
266
|
+
| YouTube embed not responsive | Fixed-width iframe | Use padding-bottom aspect-ratio trick |
|
|
267
|
+
| Missing fallback for yt-dlp | Script crashes if not installed | Check availability, offer text paste |
|
|
268
|
+
| No Font Awesome CDN | Missing icons | Include FA CDN link in `<head>` |
|
|
269
|
+
| Content in separate JS files | Unnecessary indirection for static site | Inline content directly in HTML |
|
|
270
|
+
| Using npm/build step | Over-engineering for static content | Deploy `docs/` directly, zero build |
|
|
271
|
+
|
|
272
|
+
## Dependencies
|
|
273
|
+
|
|
274
|
+
- **Tech stack:** Pure HTML + Tailwind CSS (CDN) + Vanilla JavaScript
|
|
275
|
+
- **External CDNs:** Tailwind CSS, Font Awesome
|
|
276
|
+
- **Optional:** yt-dlp (for YouTube transcript extraction)
|
|
277
|
+
- **Skills used:** None (standalone skill)
|
|
278
|
+
- **Deployment:** GitHub Pages via `docs/` folder (no build step)
|
|
279
|
+
|
|
280
|
+
## Checkpoint Protocol
|
|
281
|
+
|
|
282
|
+
After each step, output:
|
|
283
|
+
```
|
|
284
|
+
Step N/5: [Name] Complete
|
|
285
|
+
Artifacts: [list]
|
|
286
|
+
"ok" to continue | "[feedback]" to adjust
|
|
287
|
+
```
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Example: Text-Only Transcript Site (No YouTube)
|
|
2
|
+
|
|
3
|
+
## Input
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
Input type: Pasted text
|
|
7
|
+
Title: "AI in Healthcare: Panel Discussion at TechConf 2025"
|
|
8
|
+
Language: English
|
|
9
|
+
YouTube: none
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Parsed Sections (Step 1 Output)
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
Section 1: "Opening Remarks" - 480 words
|
|
16
|
+
Section 2: "Current State of Medical AI" - 1120 words
|
|
17
|
+
Section 3: "Regulatory Challenges" - 890 words
|
|
18
|
+
Section 4: "Patient Data Privacy" - 1050 words
|
|
19
|
+
Section 5: "Clinical Decision Support Systems" - 1340 words
|
|
20
|
+
Section 6: "AI-Assisted Diagnostics in Radiology" - 960 words
|
|
21
|
+
Section 7: "Audience Q&A" - 720 words
|
|
22
|
+
Section 8: "Closing Thoughts" - 410 words
|
|
23
|
+
|
|
24
|
+
Total: 6,970 words, ~35 min read, 3 speakers
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Generated File Structure
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
project-root/
|
|
31
|
+
├── docs/
|
|
32
|
+
│ ├── index.html (52 KB)
|
|
33
|
+
│ └── static/
|
|
34
|
+
│ ├── app.js (9 KB) <- smaller: no YouTube seek code
|
|
35
|
+
│ └── style.css (0.4 KB)
|
|
36
|
+
├── .github/
|
|
37
|
+
│ └── workflows/
|
|
38
|
+
│ └── deploy.yml
|
|
39
|
+
└── README.md
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Key Differences from YouTube Example
|
|
43
|
+
|
|
44
|
+
| Aspect | YouTube Example | Text-Only Example |
|
|
45
|
+
|--------|----------------|-------------------|
|
|
46
|
+
| Video embed | Yes (`<iframe>`) | Omitted |
|
|
47
|
+
| Timestamp links | Yes (`seekTo()`) | Omitted |
|
|
48
|
+
| `seekTo` function | In app.js | Not generated |
|
|
49
|
+
| `onYouTubeIframeAPIReady` | In app.js | Not generated |
|
|
50
|
+
| `og:type` | `video.other` | `article` |
|
|
51
|
+
| JSON-LD VideoObject | Yes | Omitted |
|
|
52
|
+
| `og:image` | YouTube thumbnail | Not set (or custom) |
|
|
53
|
+
| app.js size | ~11 KB | ~9 KB |
|
|
54
|
+
|
|
55
|
+
## Sample Section HTML (No Timestamp)
|
|
56
|
+
|
|
57
|
+
```html
|
|
58
|
+
<section id="section-regulatory-challenges" class="mb-12 scroll-mt-20">
|
|
59
|
+
<div class="flex items-start justify-between mb-4">
|
|
60
|
+
<h2 class="text-2xl font-bold text-gray-900 dark:text-white">
|
|
61
|
+
3. Regulatory Challenges
|
|
62
|
+
</h2>
|
|
63
|
+
<button data-copy="section-regulatory-challenges"
|
|
64
|
+
class="copy-btn flex-shrink-0 p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800
|
|
65
|
+
text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 no-print"
|
|
66
|
+
aria-label="Copy">
|
|
67
|
+
<i class="far fa-copy"></i>
|
|
68
|
+
</button>
|
|
69
|
+
</div>
|
|
70
|
+
<div class="mb-3 flex items-center gap-2">
|
|
71
|
+
<span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium
|
|
72
|
+
bg-primary-100 text-primary-800 dark:bg-primary-900 dark:text-primary-200">
|
|
73
|
+
Dr. Sarah Chen · Panelist
|
|
74
|
+
</span>
|
|
75
|
+
</div>
|
|
76
|
+
<div class="prose prose-lg dark:prose-invert max-w-none">
|
|
77
|
+
<p>The FDA's approach to AI-based medical devices has evolved significantly...</p>
|
|
78
|
+
<p>We're seeing a shift from traditional 510(k) pathways to the new PCCP framework...</p>
|
|
79
|
+
</div>
|
|
80
|
+
</section>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## SEO Head (Article-only, no VideoObject)
|
|
84
|
+
|
|
85
|
+
```html
|
|
86
|
+
<title>AI in Healthcare: Panel Discussion at TechConf 2025</title>
|
|
87
|
+
<meta name="description" content="Panel discussion transcript covering medical AI, regulatory challenges, patient data privacy, and clinical decision support systems." />
|
|
88
|
+
<meta property="og:type" content="article" />
|
|
89
|
+
<!-- No og:image (no YouTube thumbnail available) -->
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## JSON-LD (Article only)
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"@context": "https://schema.org",
|
|
97
|
+
"@type": "Article",
|
|
98
|
+
"headline": "AI in Healthcare: Panel Discussion at TechConf 2025",
|
|
99
|
+
"author": { "@type": "Organization", "name": "TechConf" },
|
|
100
|
+
"datePublished": "2025-11-15",
|
|
101
|
+
"description": "Panel discussion transcript covering medical AI...",
|
|
102
|
+
"wordCount": 6970
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Stats Displayed in Header
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
35 min read · 6,970 words · 8 sections
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Verification Results
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
File checks: 5/5 passed
|
|
116
|
+
HTML structure: 11/11 passed (no YouTube-specific checks)
|
|
117
|
+
Content: 6/6 passed
|
|
118
|
+
Interactivity: 8/8 passed (no seekTo/YouTube checks)
|
|
119
|
+
Responsive: 6/6 passed
|
|
120
|
+
Dark mode: 6/6 passed
|
|
121
|
+
SEO: 5/5 passed (no VideoObject checks)
|
|
122
|
+
Print: 4/4 passed
|
|
123
|
+
```
|