@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.
Files changed (79) hide show
  1. package/README.md +50 -3
  2. package/bin/cli.js +0 -0
  3. package/package.json +5 -3
  4. package/templates/.claude/commands/analyst-manual.md +38 -0
  5. package/templates/.claude/commands/casarium.md +55 -4
  6. package/templates/.claude/commands/feature-adr.md +8 -0
  7. package/templates/.claude/rules/trust-tiers.md +5 -0
  8. package/templates/.claude/shards/feature-adr.shard.md +64 -10
  9. package/templates/.claude/shards/phase-ai-factory.shard.md +109 -0
  10. package/templates/.claude/skills/ai-factory-mapper/README.md +90 -0
  11. package/templates/.claude/skills/ai-factory-mapper/SKILL.md +309 -0
  12. package/templates/.claude/skills/ai-factory-mapper/assets/report-template.md +123 -0
  13. package/templates/.claude/skills/ai-factory-mapper/references/catalog.md +230 -0
  14. package/templates/.claude/skills/ai-factory-mapper/references/coverage-formula.md +219 -0
  15. package/templates/.claude/skills/ai-factory-mapper/references/decomposition-checklist.md +183 -0
  16. package/templates/.claude/skills/ai-factory-mapper/references/pattern-library.md +312 -0
  17. package/templates/.claude/skills/ai-factory-mapper/scripts/build_docx_report.js +423 -0
  18. package/templates/.claude/skills/analyst-manual-full/SKILL.md +286 -0
  19. package/templates/.claude/skills/edu-site-generator/SKILL.md +254 -0
  20. package/templates/.claude/skills/edu-site-generator/examples/sample-course-structure.md +116 -0
  21. package/templates/.claude/skills/edu-site-generator/modules/00-content-analysis.md +84 -0
  22. package/templates/.claude/skills/edu-site-generator/modules/01-course-structure.md +75 -0
  23. package/templates/.claude/skills/edu-site-generator/modules/02-data-generation.md +186 -0
  24. package/templates/.claude/skills/edu-site-generator/modules/03-scaffold.md +249 -0
  25. package/templates/.claude/skills/edu-site-generator/modules/04-components.md +130 -0
  26. package/templates/.claude/skills/edu-site-generator/modules/05-gamification.md +163 -0
  27. package/templates/.claude/skills/edu-site-generator/modules/06-deploy.md +88 -0
  28. package/templates/.claude/skills/edu-site-generator/modules/07-verification.md +97 -0
  29. package/templates/.claude/skills/edu-site-generator/references/component-templates.md +436 -0
  30. package/templates/.claude/skills/edu-site-generator/references/data-schemas.md +164 -0
  31. package/templates/.claude/skills/edu-site-generator/references/exercise-catalog.md +110 -0
  32. package/templates/.claude/skills/edu-site-generator/references/tech-stack.md +69 -0
  33. package/templates/.claude/skills/feature-adr/SKILL.md +245 -59
  34. package/templates/.claude/skills/feature-adr/modules/03-adr.md +43 -0
  35. package/templates/.claude/skills/feature-adr/modules/03.5-ideation-swarm.md +180 -0
  36. package/templates/.claude/skills/feature-adr/modules/06-implementation-plan.md +56 -7
  37. package/templates/.claude/skills/feature-adr/modules/08-qe.md +87 -23
  38. package/templates/.claude/skills/feature-adr/modules/09-fleet-qe.md +305 -0
  39. package/templates/.claude/skills/feature-adr/references/agentic-qe/README.md +143 -0
  40. package/templates/.claude/skills/feature-adr/references/agentic-qe/brutal-honesty-review.md +240 -0
  41. package/templates/.claude/skills/feature-adr/references/agentic-qe/chaos-engineering-resilience.md +163 -0
  42. package/templates/.claude/skills/feature-adr/references/agentic-qe/code-goal-planner.md +446 -0
  43. package/templates/.claude/skills/feature-adr/references/agentic-qe/enterprise-integration-testing.md +111 -0
  44. package/templates/.claude/skills/feature-adr/references/agentic-qe/mutation-testing.md +236 -0
  45. package/templates/.claude/skills/feature-adr/references/agentic-qe/performance-testing.md +315 -0
  46. package/templates/.claude/skills/feature-adr/references/agentic-qe/qcsd-ideation-swarm.md +126 -0
  47. package/templates/.claude/skills/feature-adr/references/agentic-qe/qcsd-production-swarm.md +108 -0
  48. package/templates/.claude/skills/feature-adr/references/agentic-qe/qe-coverage-analysis.md +193 -0
  49. package/templates/.claude/skills/feature-adr/references/agentic-qe/qe-requirements-validation.md +254 -0
  50. package/templates/.claude/skills/feature-adr/references/agentic-qe/regression-testing.md +233 -0
  51. package/templates/.claude/skills/feature-adr/references/agentic-qe/risk-based-testing.md +212 -0
  52. package/templates/.claude/skills/feature-adr/references/agentic-qe/security-testing.md +311 -0
  53. package/templates/.claude/skills/feature-adr/references/agentic-qe/shift-left-testing.md +231 -0
  54. package/templates/.claude/skills/feature-adr/references/agentic-qe/tdd-london-chicago.md +249 -0
  55. package/templates/.claude/skills/transcript-site-generator/SKILL.md +287 -0
  56. package/templates/.claude/skills/transcript-site-generator/examples/sample-text-only-site.md +123 -0
  57. package/templates/.claude/skills/transcript-site-generator/examples/sample-transcript-site.md +134 -0
  58. package/templates/.claude/skills/transcript-site-generator/modules/00-input-analysis.md +132 -0
  59. package/templates/.claude/skills/transcript-site-generator/modules/01-content-parsing.md +117 -0
  60. package/templates/.claude/skills/transcript-site-generator/modules/02-site-generation.md +293 -0
  61. package/templates/.claude/skills/transcript-site-generator/modules/03-interactivity.md +406 -0
  62. package/templates/.claude/skills/transcript-site-generator/modules/04-deploy.md +130 -0
  63. package/templates/.claude/skills/transcript-site-generator/modules/05-verification.md +155 -0
  64. package/templates/.claude/skills/transcript-site-generator/references/component-catalog.md +86 -0
  65. package/templates/.claude/skills/transcript-site-generator/references/data-schemas.md +123 -0
  66. package/templates/.claude/skills/transcript-site-generator/references/tech-stack.md +132 -0
  67. package/templates/CLAUDE.md +9 -2
  68. package/templates/docs/edu-site-generator/01-deployment-guide.md +911 -0
  69. package/templates/docs/edu-site-generator/02-admin-guide.md +901 -0
  70. package/templates/docs/edu-site-generator/03-user-guide.md +1008 -0
  71. package/templates/docs/edu-site-generator/04-infrastructure-requirements.md +489 -0
  72. package/templates/docs/edu-site-generator/05-architecture.md +902 -0
  73. package/templates/docs/edu-site-generator/06-user-flows.md +759 -0
  74. package/templates/docs/transcript-site-generator/01-deployment-guide.md +1042 -0
  75. package/templates/docs/transcript-site-generator/02-admin-guide.md +918 -0
  76. package/templates/docs/transcript-site-generator/03-user-guide.md +925 -0
  77. package/templates/docs/transcript-site-generator/04-infrastructure-requirements.md +482 -0
  78. package/templates/docs/transcript-site-generator/05-architecture.md +1068 -0
  79. 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 &middot; 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
+ ```