better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/creative/creative-sketch.md

@@ -1,240 +0,0 @@
----
-title: "Sketch — Throwaway HTML mockups: 2-3 design variants to compare"
-sidebar_label: "Sketch"
-description: "Throwaway HTML mockups: 2-3 design variants to compare"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Sketch
-
-Throwaway HTML mockups: 2-3 design variants to compare.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/creative/sketch` |
-| Version | `1.0.1` |
-| Author | Hermes Agent (adapted from gsd-build/get-shit-done) |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `sketch`, `mockup`, `design`, `ui`, `prototype`, `html`, `variants`, `exploration`, `wireframe`, `comparison` |
-| Related skills | [`spike`](/docs/user-guide/skills/bundled/software-development/software-development-spike), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`popular-web-designs`](/docs/user-guide/skills/bundled/creative/creative-popular-web-designs), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Sketch
-
-Use this skill when the user wants to **see a design direction before committing** to one — exploring a UI/UX idea as disposable HTML mockups. The point is to generate 2-3 interactive variants so the user can compare visual directions side-by-side, not to produce shippable code.
-
-Load this when the user says things like "sketch this screen", "show me what X could look like", "compare layout A vs B", "give me 2-3 takes on this UI", "let me see some variants", "mockup this before I build".
-
-## When NOT to use this
-
-- User wants a production component — use `claude-design` or build it properly
-- User wants a polished one-off HTML artifact (landing page, deck) — `claude-design`
-- User wants a diagram — `excalidraw`, `architecture-diagram`
-- The design is already locked — just build it
-
-## If the user has the full GSD system installed
-
-If `gsd-sketch` shows up as a sibling skill (installed via `npx get-shit-done-cc --hermes`), you can use **`gsd-sketch`** for the fuller workflow: persistent `.planning/sketches/` with MANIFEST, frontier mode analysis, consistency audits across past sketches, and integration with the rest of GSD. This skill is the lightweight standalone version — one-off sketching without the state machinery.
-
-> **Note:** The upstream GSD project ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)) is **archived / no longer maintained** on GitHub. The npm package (`get-shit-done-cc`) still installs, but treat it as an archived community project — this standalone `sketch` skill is the maintained path and needs nothing extra.
-
-## Core method
-
-```
-intake  →  variants  →  head-to-head  →  pick winner (or iterate)
-```
-
-### 1. Intake (skip if the user already gave you enough)
-
-Before generating variants, get three things — one question at a time, not all at once:
-
-1. **Feel.** "What should this feel like? Adjectives, emotions, a vibe." — *"calm, editorial, like Linear"* tells you more than *"minimal"*.
-2. **References.** "What apps, sites, or products capture the feel you're imagining?" — actual references beat abstract descriptions.
-3. **Core action.** "What's the single most important thing a user does on this screen?" — the variants should all serve this well; if they don't, they're just decoration.
-
-Reflect each answer briefly before the next question. If the user already gave you all three upfront, skip straight to variants.
-
-### 2. Variants (2-3, never 1, rarely 4+)
-
-Produce **2-3 variants** in one go. Each variant is a complete, standalone HTML file. Don't describe variants — build them. The point is comparison.
-
-Each variant should take a **different design stance**, not different pixel values. Three good variant axes:
-
-- **Density:** compact / airy / ultra-dense (pick two contrasting poles)
-- **Emphasis:** content-first / action-first / tool-first
-- **Aesthetic:** editorial / utilitarian / playful
-- **Layout:** single-column / sidebar / split-pane
-- **Grounding:** card-based / bare-content / document-style
-
-Pick one axis and pull apart from it. Two variants that differ only in accent color are wasted effort — the user can't distinguish them.
-
-**Variant naming:** describe the stance, not the number.
-
-<!-- ascii-guard-ignore -->
-```
-sketches/
-├── 001-calm-editorial/
-│   ├── index.html
-│   └── README.md
-├── 001-utilitarian-dense/
-│   ├── index.html
-│   └── README.md
-└── 001-playful-split/
-    ├── index.html
-    └── README.md
-```
-<!-- ascii-guard-ignore-end -->
-
-### 3. Make them real HTML
-
-Each variant is a **single self-contained HTML file**:
-
-- Inline `<style>` — no build step, no external CSS
-- System fonts or one Google Font via `<link>`
-- Tailwind via CDN (`<script src="https://cdn.tailwindcss.com"></script>`) is fine
-- Realistic fake content — actual sentences, actual names, not "Lorem ipsum"
-- **Interactive**: links clickable, hovers real, at least one state transition (open/close, filter, toggle). A frozen static image is a worse spike than a sloppy animated one.
-
-Open it in a browser. If it looks broken, fix it before showing the user.
-
-**Verify variants visually — use Hermes' browser tools.** Don't just write HTML and hope it renders; load each variant and look at it:
-
-```
-browser_navigate(url="file:///absolute/path/to/sketches/001-calm-editorial/index.html")
-browser_vision(question="Does this layout look clean and readable? Any visible bugs (overlapping text, unstyled elements, broken images)?")
-```
-
-`browser_vision` returns an AI description of what's actually on the page plus a screenshot path — catches layout bugs that pure source inspection misses (e.g. a font import that silently failed, a flex container that collapsed). Fix and re-navigate until each variant looks right.
-
-**Default CSS reset + system font stack** for fast starts:
-
-```html
-<style>
-  * { box-sizing: border-box; margin: 0; padding: 0; }
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
-                 "Helvetica Neue", Arial, sans-serif;
-    -webkit-font-smoothing: antialiased;
-    color: #1a1a1a;
-    background: #fafafa;
-    line-height: 1.5;
-  }
-</style>
-```
-
-### 4. Variant README
-
-Each variant's `README.md` answers:
-
-```markdown
-## Variant: {stance name}
-
-### Design stance
-One sentence on the principle driving this variant.
-
-### Key choices
-- Layout: ...
-- Typography: ...
-- Color: ...
-- Interaction: ...
-
-### Trade-offs
-- Strong at: ...
-- Weak at: ...
-
-### Best for
-- The kind of user or use case this variant actually serves
-```
-
-### 5. Head-to-head
-
-After all variants are built, present them as a comparison. Don't just list — **opinionate**:
-
-```markdown
-## Three takes on the home screen
-
-| Dimension | Calm editorial | Utilitarian dense | Playful split |
-|-----------|----------------|-------------------|---------------|
-| Density   | Low            | High              | Medium        |
-| Primary action visibility | Low | High | Medium |
-| Scan-ability | High | Medium | Low |
-| Feel | Calm, trusted | Sharp, tool-like | Inviting, energetic |
-
-**My take:** Utilitarian dense for power users, calm editorial for content-forward audiences. Playful split is weakest — tries to do both and commits to neither.
-```
-
-Let the user pick a winner, or combine two into a hybrid, or ask for another round.
-
-## Theming (when the project has a visual identity)
-
-If the user has an existing theme (colors, fonts, tokens), put shared tokens in `sketches/themes/tokens.css` and `@import` them in each variant. Keep tokens minimal:
-
-```css
-/* sketches/themes/tokens.css */
-:root {
-  --color-bg: #fafafa;
-  --color-fg: #1a1a1a;
-  --color-accent: #0066ff;
-  --color-muted: #666;
-  --radius: 8px;
-  --font-display: "Inter", sans-serif;
-  --font-body: -apple-system, BlinkMacSystemFont, sans-serif;
-}
-```
-
-Don't over-tokenize a throwaway sketch — three colors and one font is usually enough.
-
-## Interactivity bar
-
-A sketch is interactive enough when the user can:
-
-1. **Click a primary action** and something visible happens (state change, modal, toast, navigation feint)
-2. **See one meaningful state transition** (filter a list, toggle a mode, open/close a panel)
-3. **Hover recognizable affordances** (buttons, rows, tabs)
-
-More than that is over-engineering a throwaway. Less than that is a screenshot.
-
-## Frontier mode (picking what to sketch next)
-
-If sketches already exist and the user says "what should I sketch next?":
-
-- **Consistency gaps** — two winning variants from different sketches made independent choices that haven't been composed together yet
-- **Unsketched screens** — referenced but never explored
-- **State coverage** — happy path sketched, but not empty / loading / error / 1000-items
-- **Responsive gaps** — validated at one viewport; does it hold at mobile / ultrawide?
-- **Interaction patterns** — static layouts exist; transitions, drag, scroll behavior don't
-
-Propose 2-4 named candidates. Let the user pick.
-
-## Output
-
-- Create `sketches/` (or `.planning/sketches/` if the user is using GSD conventions) in the repo root
-- One subdir per variant: `NNN-stance-name/index.html` + `README.md`
-- Tell the user how to open them: `open sketches/001-calm-editorial/index.html` on macOS, `xdg-open` on Linux, `start` on Windows
-- Keep variants disposable — a sketch that you felt the need to preserve should be promoted into real project code, not curated as an asset
-
-**Typical tool sequence for one variant:**
-
-```
-terminal("mkdir -p sketches/001-calm-editorial")
-write_file("sketches/001-calm-editorial/index.html", "<!doctype html>...")
-write_file("sketches/001-calm-editorial/README.md", "## Variant: Calm editorial\n...")
-browser_navigate(url="file://$(pwd)/sketches/001-calm-editorial/index.html")
-browser_vision(question="How does this look? Any obvious layout issues?")
-```
-
-Repeat for each variant, then present the comparison table.
-
-## Attribution
-
-Adapted from the GSD (Get Shit Done) project's `/gsd-sketch` workflow — MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done)). The upstream GSD repo is now **archived/unmaintained** on GitHub; the `get-shit-done-cc` npm package still installs (`npx get-shit-done-cc --hermes --global`) and ships persistent sketch state, theme/variant pattern references, and consistency-audit workflows, but treat it as an archived community project.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music.md

@@ -1,319 +0,0 @@
----
-title: "Songwriting And Ai Music — Songwriting craft and Suno AI music prompts"
-sidebar_label: "Songwriting And Ai Music"
-description: "Songwriting craft and Suno AI music prompts"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Songwriting And Ai Music
-
-Songwriting craft and Suno AI music prompts.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Bundled (installed by default) |
-| Path | `skills/creative\songwriting-and-ai-music` |
-| Version | `1.0.0` |
-| Author | Teknium (teknium1), Hermes Agent |
-| License | MIT |
-| Platforms | linux, macos, windows |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Songwriting & AI Music Generation
-
-Everything here is a GUIDELINE, not a rule. Art breaks rules on purpose.
-Use what serves the song. Ignore what doesn't.
-
----
-
-## 1. Song Structure (Pick One or Invent Your Own)
-
-Common skeletons — mix, modify, or throw out as needed:
-
-```
-ABABCB  Verse/Chorus/Verse/Chorus/Bridge/Chorus    (most pop/rock)
-AABA    Verse/Verse/Bridge/Verse (refrain-based)    (jazz standards, ballads)
-ABAB    Verse/Chorus alternating                    (simple, direct)
-AAA     Verse/Verse/Verse (strophic, no chorus)     (folk, storytelling)
-```
-
-The six building blocks:
-- Intro      — set the mood, pull the listener in
-- Verse      — the story, the details, the world-building
-- Pre-Chorus — optional tension ramp before the payoff
-- Chorus     — the emotional core, the part people remember
-- Bridge     — a detour, a shift in perspective or key
-- Outro      — the farewell, can echo or subvert the rest
-
-You don't need all of these. Some great songs are just one section
-that evolves. Structure serves the emotion, not the other way around.
-
----
-
-## 2. Rhyme, Meter, and Sound
-
-RHYME TYPES (from tight to loose):
-- Perfect: lean/mean
-- Family: crate/braid
-- Assonance: had/glass (same vowels, different endings)
-- Consonance: scene/when (different vowels, similar endings)
-- Near/slant: enough to suggest connection without locking it down
-
-Mix them. All perfect rhymes can sound like a nursery rhyme.
-All slant rhymes can sound lazy. The blend is where it lives.
-
-INTERNAL RHYME: Rhyming within a line, not just at the ends.
-  "We pruned the lies from bleeding trees / Distilled the storm
-   from entropy" — "lies/flies," "trees/entropy" create internal echoes.
-
-METER: The rhythm of stressed vs unstressed syllables.
-- Matching syllable counts between parallel lines helps singability
-- The STRESSED syllables matter more than total count
-- Say it out loud. If you stumble, the meter needs work.
-- Intentionally breaking meter can create emphasis or surprise
-
----
-
-## 3. Emotional Arc and Dynamics
-
-Think of a song as a journey, not a flat road.
-
-ENERGY MAPPING (rough idea, not prescription):
-  Intro: 2-3  |  Verse: 5-6  |  Pre-Chorus: 7
-  Chorus: 8-9  |  Bridge: varies  |  Final Chorus: 9-10
-
-The most powerful dynamic trick: CONTRAST.
-- Whisper before a scream hits harder than just screaming
-- Sparse before dense. Slow before fast. Low before high.
-- The drop only works because of the buildup
-- Silence is an instrument
-
-"Whisper to roar to whisper" — start intimate, build to full power,
-strip back to vulnerability. Works for ballads, epics, anthems.
-
----
-
-## 4. Writing Lyrics That Work
-
-SHOW, DON'T TELL (usually):
-- "I was sad" = flat
-- "Your hoodie's still on the hook by the door" = alive
-- But sometimes "I give my life" said plainly IS the power
-
-THE HOOK:
-- The line people remember, hum, repeat
-- Usually the title or core phrase
-- Works best when melody + lyric + emotion all align
-- Place it where it lands hardest (often first/last line of chorus)
-
-PROSODY — lyrics and music supporting each other:
-- Stable feelings (resolution, peace) pair with settled melodies,
-  perfect rhymes, resolved chords
-- Unstable feelings (longing, doubt) pair with wandering melodies,
-  near-rhymes, unresolved chords
-- Verse melody typically sits lower, chorus goes higher
-- But flip this if it serves the song
-
-AVOID (unless you're doing it on purpose):
-- Cliches on autopilot ("heart of gold" without earning it)
-- Forcing word order to hit a rhyme ("Yoda-speak")
-- Same energy in every section (flat dynamics)
-- Treating your first draft as sacred — revision is creation
-
----
-
-## 5. Parody and Adaptation
-
-When rewriting an existing song with new lyrics:
-
-THE SKELETON: Map the original's structure first.
-- Count syllables per line
-- Mark the rhyme scheme (ABAB, AABB, etc.)
-- Identify which syllables are STRESSED
-- Note where held/sustained notes fall
-
-FITTING NEW WORDS:
-- Match stressed syllables to the same beats as the original
-- Total syllable count can flex by 1-2 unstressed syllables
-- On long held notes, try to match the VOWEL SOUND of the original
-  (if original holds "LOOOVE" with an "oo" vowel, "FOOOD" fits
-   better than "LIFE")
-- Monosyllabic swaps in key spots keep rhythm intact
-  (Crime -> Code, Snake -> Noose)
-- Sing your new words over the original — if you stumble, revise
-
-CONCEPT:
-- Pick a concept strong enough to sustain the whole song
-- Start from the title/hook and build outward
-- Generate lots of raw material (puns, phrases, images) FIRST,
-  then fit the best ones into the structure
-- If you need a specific line somewhere, reverse-engineer the
-  rhyme scheme backward to set it up
-
-KEEP SOME ORIGINALS: Leaving a few original lines or structures
-intact adds recognizability and lets the audience feel the connection.
-
----
-
-## 6. Suno AI Prompt Engineering
-
-### Style/Genre Description Field
-
-FORMULA (adapt as needed):
-  Genre + Mood + Era + Instruments + Vocal Style + Production + Dynamics
-
-```
-BAD:  "sad rock song"
-GOOD: "Cinematic orchestral spy thriller, 1960s Cold War era, smoky
-       sultry female vocalist, big band jazz, brass section with
-       trumpets and french horns, sweeping strings, minor key,
-       vintage analog warmth"
-```
-
-DESCRIBE THE JOURNEY, not just the genre:
-```
-"Begins as a haunting whisper over sparse piano. Gradually layers
- in muted brass. Builds through the chorus with full orchestra.
- Second verse erupts with raw belting intensity. Outro strips back
- to a lone piano and a fragile whisper fading to silence."
-```
-
-TIPS:
-- V4.5+ supports up to 1,000 chars in Style field — use them
-- NO artist names or trademarks. Describe the sound instead.
-  "1960s Cold War spy thriller brass" not "James Bond style"
-  "90s grunge" not "Nirvana-style"
-- Specify BPM and key when you have a preference
-- Use Exclude Styles field for what you DON'T want
-- Unexpected genre combos can be gold: "bossa nova trap",
-  "Appalachian gothic", "chiptune jazz"
-- Build a vocal PERSONA, not just a gender:
-  "A weathered torch singer with a smoky alto, slight rasp,
-   who starts vulnerable and builds to devastating power"
-
-### Metatags (place in [brackets] inside lyrics field)
-
-STRUCTURE:
-  [Intro] [Verse] [Verse 1] [Pre-Chorus] [Chorus]
-  [Post-Chorus] [Hook] [Bridge] [Interlude]
-  [Instrumental] [Instrumental Break] [Guitar Solo]
-  [Breakdown] [Build-up] [Outro] [Silence] [End]
-
-VOCAL PERFORMANCE:
-  [Whispered] [Spoken Word] [Belted] [Falsetto] [Powerful]
-  [Soulful] [Raspy] [Breathy] [Smooth] [Gritty]
-  [Staccato] [Legato] [Vibrato] [Melismatic]
-  [Harmonies] [Choir] [Harmonized Chorus]
-
-DYNAMICS:
-  [High Energy] [Low Energy] [Building Energy] [Explosive]
-  [Emotional Climax] [Gradual swell] [Orchestral swell]
-  [Quiet arrangement] [Falling tension] [Slow Down]
-
-GENDER:
-  [Female Vocals] [Male Vocals]
-
-ATMOSPHERE:
-  [Melancholic] [Euphoric] [Nostalgic] [Aggressive]
-  [Dreamy] [Intimate] [Dark Atmosphere]
-
-SFX:
-  [Vinyl Crackle] [Rain] [Applause] [Static] [Thunder]
-
-Put tags in BOTH style field AND lyrics for reinforcement.
-Keep to 5-8 tags per section max — too many confuses the AI.
-Don't contradict yourself ([Calm] + [Aggressive] in same section).
-
-### Custom Mode
-- Always use Custom Mode for serious work (separate Style + Lyrics)
-- Lyrics field limit: ~3,000 chars (~40-60 lines)
-- Always add structural tags — without them Suno defaults to
-  flat verse/chorus/verse with no emotional arc
-
----
-
-## 7. Phonetic Tricks for AI Singers
-
-AI vocalists don't read — they pronounce. Help them:
-
-PHONETIC RESPELLING:
-- Spell words as they SOUND: "through" -> "thru"
-- Proper nouns are highest failure rate — test early
-- "Nous" -> "Noose" (forces correct pronunciation)
-- Hyphenate to guide syllables: "Re-search", "bio-engineering"
-
-DELIVERY CONTROL:
-- ALL CAPS = louder, more intense
-- Vowel extension: "lo-o-o-ove" = sustained/melisma
-- Ellipses: "I... need... you" = dramatic pauses
-- Hyphenated stretch: "ne-e-ed" = emotional stretch
-
-ALWAYS:
-- Spell out numbers: "24/7" -> "twenty four seven"
-- Space acronyms: "AI" -> "A I" or "A-I"
-- Test proper nouns/unusual words in a short 30-second clip first
-- Once generated, pronunciation is baked in — fix in lyrics BEFORE
-
----
-
-## 8. Workflow
-
-1. Write the concept/hook first — what's the emotional core?
-2. If adapting, map the original structure (syllables, rhyme, stress)
-3. Generate raw material — brainstorm freely before structuring
-4. Draft lyrics into the structure
-5. Read/sing aloud — catch stumbles, fix meter
-6. Build the Suno style description — paint the dynamic journey
-7. Add metatags to lyrics for performance direction
-8. Generate 3-5 variations minimum — treat them like recording takes
-9. Pick the best, use Extend/Continue to build on promising sections
-10. If something great happens by accident, keep it
-
-EXPECT: ~3-5 generations per 1 good result. Revision is normal.
-Style can drift in extensions — restate genre/mood when extending.
-
----
-
-## 9. Lessons Learned
-
-- Describing the dynamic ARC in the style field matters way more
-  than just listing genres. "Whisper to roar to whisper" gives
-  Suno a performance map.
-- Keeping some original lines intact in a parody adds recognizability
-  and emotional weight — the audience feels the ghost of the original.
-- The bridge slot in a song is where you can transform imagery.
-  Swap the original's specific references for your theme's metaphors
-  while keeping the emotional function (reflection, shift, revelation).
-- Monosyllabic word swaps in hooks/tags are the cleanest way to
-  maintain rhythm while changing meaning.
-- A strong vocal persona description in the style field makes a
-  bigger difference than any single metatag.
-- Don't be precious about rules. If a line breaks meter but hits
-  harder, keep it. The feeling is what matters. Craft serves art,
-  not the other way around.
-
----
-
-## 10. Local / Open-Source Music Generation
-
-For local, GPU-based generation instead of Suno, two optional skills
-cover this (heavy dependencies, so not installed by default):
-
-- **heartmula** — full songs with vocals from lyrics + tags
-  (open-source Suno alternative, 8-16GB VRAM):
-  `hermes skills install official/creative/heartmula`
-- **audiocraft** — Meta's MusicGen (instrumental text-to-music) and
-  AudioGen (sound effects):
-  `hermes skills install official/creative/audiocraft-audio-generation`
-
-The lyric-writing and prompting craft in this skill applies to
-heartmula too — its input format is lyrics with bracketed structure
-tags plus comma-separated style tags.