[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7191XEBJSZ2SS0CV5TSNZDJ":3,"skill-same:01M7191XEBJSZ2SS0CV5TSNZDJ":104},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":30,"publishedAt":51,"linkOnly":52,"markdownContent":53,"markdownBody":54,"frontMatter":55,"refName":56,"commitSha":57,"skillDirectory":58,"forksCount":59,"repositoryHtmlUrl":60,"repositoryHomepageUrl":61,"ownerHtmlUrl":62,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":63,"install":64,"resources":77},"01M7191XEBJSZ2SS0CV5TSNZDJ","converge-diagrams",null,"This skill should be used when creating, editing, or reviewing inline SVG diagrams for the Converge landing site (anything under src\u002Fpages\u002F**, src\u002Fcomponents\u002Fsections\u002F**, or src\u002Fcontent\u002Fblog\u002F**). It encodes the component-based primitive system under src\u002Fcomponents\u002Fdiagrams\u002F, the Converge dark-theme palette + shape semantics, the preview-and-verify loop using headless Chrome against the Astro dev\u002Fpreview server, and the pitfalls that cost iterations to discover. Trigger phrases include \"add a diagram to the landing page\", \"edit the Architecture diagram\", \"replace the SVG in the Hero\", \"make a diagram for the FeatureGrid\", \"draw the playbook lifecycle\", \"illustrate convergence\", \"check how the diagram looks\".","openplaybooks-dev\u002Fconverge","openplaybooks-dev","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F270560357?v=4","01M7191G17AHW5SXN63HJ0BEZV","01M7191G29922BDNWN8CFVG4PD",3,"MIT","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-diagrams\u002FSKILL.md",[17,22,25],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":26,"categoryName":27,"taxonomyType":28,"taxonomyTypeDesc":29},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50],"diagrams","converge diagrams","converge","system","for","dark","theme","edit","playbook","how","component","palette","inline","server","astro","architecture","components","loop","architecture diagram","landing site","2026-11-10 10:12:30",false,"---\nname: converge-diagrams\ndescription: This skill should be used when creating, editing, or reviewing inline SVG diagrams for the Converge landing site (anything under src\u002Fpages\u002F**, src\u002Fcomponents\u002Fsections\u002F**, or src\u002Fcontent\u002Fblog\u002F**). It encodes the component-based primitive system under src\u002Fcomponents\u002Fdiagrams\u002F, the Converge dark-theme palette + shape semantics, the preview-and-verify loop using headless Chrome against the Astro dev\u002Fpreview server, and the pitfalls that cost iterations to discover. Trigger phrases include \"add a diagram to the landing page\", \"edit the Architecture diagram\", \"replace the SVG in the Hero\", \"make a diagram for the FeatureGrid\", \"draw the playbook lifecycle\", \"illustrate convergence\", \"check how the diagram looks\".\n---\n\n# Converge Landing Diagrams\n\nInline SVG diagrams on the Converge landing site are authored as Astro\ncomponents under `src\u002Fcomponents\u002Fdiagrams\u002F`, composed from shape-semantic\nprimitives that share the site's dark-theme palette and styling. One-off\ninline `\u003Csvg>` blocks inside section components (e.g.\n`ConvergenceJourney.astro`) are legacy decoration — always build new\nexplanatory diagrams with the primitives so they stay consistent across\nthe page.\n\n## When this skill applies\n\nApply this skill when:\n\n- Adding a new diagram to a landing-page section (`.astro` under\n  `src\u002Fcomponents\u002Fsections\u002F` or `src\u002Fpages\u002F`).\n- Adding or editing a diagram inside a blog post (`.mdx` under\n  `src\u002Fcontent\u002Fblog\u002F`).\n- Editing or replacing an existing diagram component under\n  `src\u002Fcomponents\u002Fdiagrams\u002F`.\n- Reviewing a rendered diagram for layout or style issues.\n- Reworking a legacy one-off inline `\u003Csvg>` into the primitive system.\n\nDo not apply for:\n\n- Pure decorative animations (e.g. `ConvergenceJourney.astro`) that\n  exist only to set mood — they aren't trying to explain anything and\n  don't need shape semantics.\n- General SVG editing outside `src\u002Fcomponents\u002Fdiagrams\u002F` (icon files,\n  social cards, OG images).\n\n## The canonical reference\n\nRead `src\u002Fcomponents\u002Fdiagrams\u002FREADME.md` **first**. It documents the\nshape vocabulary, palette vars from `src\u002Fstyles\u002Ftokens.css`, shared CSS\nclasses, animation conventions, directory layout, and the MDX\u002FAstro\nembedding pattern. This SKILL.md assumes that reference is current — do\nnot duplicate it here.\n\nIf `src\u002Fcomponents\u002Fdiagrams\u002F` does not exist yet on this branch, the\nfirst diagram drop must scaffold it. Use the starter template under\n[assets\u002Fstarter.astro](assets\u002Fstarter.astro) and add a `README.md`\nalongside it that captures the palette\u002Fshape vocabulary you adopt.\n\nThen consult the three references bundled with this skill for the\nsession-specific knowledge that isn't in the project README:\n\n- [references\u002Fworkflow.md](references\u002Fworkflow.md) — the preview loop (Astro dev server \u002F `astro build && astro preview` + headless Chrome), how to crop and view output, rebuild discipline.\n- [references\u002Fpitfalls.md](references\u002Fpitfalls.md) — the traps that repeatedly cost iterations (dg-step opacity, color unification with dark theme tokens, magic-number insets, labels without auto-wrap).\n- [references\u002Flayout-patterns.md](references\u002Flayout-patterns.md) — layout idioms (horizontal arrows, symmetric padding, compactness, bindings vs arrows).\n\n## Core procedure\n\nWhen asked to create or edit a diagram, proceed in this order:\n\n### 1. Read the reference materials\n\nLoad `src\u002Fcomponents\u002Fdiagrams\u002FREADME.md` plus the three references\nabove. Skim, don't memorize — refer back when designing.\n\n### 2. Design the layout before writing code\n\nSketch positions with concrete numbers in a config object at the top of\nthe `.astro` file. Prefer absolute coordinates with a `viewBox` sized to\ncontent, and use named constants for box dimensions and column offsets.\n\n**Derive container size from content, not the other way around.** Start\nfrom inner widths, gaps, and pad; compute `APP_W = sum(cols) + (n-1) *\nGAP + 2 * APP_PAD_X`. Downstream siblings reference `APP.x + APP_W`,\nnot a hardcoded x. Same for vertical: pick row centers so top-pad ==\nbottom-pad. This keeps padding balanced on all four sides as you\niterate. See [references\u002Flayout-patterns.md](references\u002Flayout-patterns.md).\n\n### 3. Compose from primitives\n\nUse the shape-semantic primitives:\n\n| Shape | Meaning | Primitive |\n|---|---|---|\n| Sharp rectangle | Data (task output file, artifact, row) | `DataBox` |\n| Round-cornered rectangle | Subsystem \u002F logic (a task body, a check) | `LogicBox` (`memoized` + `status` props, slot) |\n| Elevated container with header | A Converge task \u002F playbook node | `TaskCard` (slot in local coords; `status` prop) |\n| Indigo-tinted container with header | A Converge playbook \u002F project root | `PlaybookContainer` (slot in local coords) |\n| Bullet (flat left, rounded right) | Goal \u002F deliverable state | `TargetBullet` |\n| Animated dashed arrow with head | Flow \u002F causation (parent → child run, body → check) | `FlowArrow` |\n| Static dashed line, no head | Binding \u002F identity (declared output → file, task → owner) | `Connector` |\n\nDelta state + run status annotations (orthogonal, on any shape):\n\n| Prop | Values | Visual |\n|---|---|---|\n| `state` | `new`, `updated`, `removed`, `changed`, `idle` | Cyan \u002F violet \u002F accent-red \u002F thin-accent fill (state cascade is prevented by direct-child CSS combinator — see pitfalls). |\n| `status` | `passing`, `running`, `failing` | Top-left badge. Passing draws a check on hover; running spins on hover; failing pulses. All suppressed when `state=\"removed\"`. |\n| `highlight` | `true` | Thick indigo border for \"currently-discussed element\" |\n\nNew shape primitives should **compose on top of `ShapeGroup`**, not\nre-implement the wrapper `\u003Cg>` + state class + title + badge logic.\n\nPalette tokens come from `src\u002Fstyles\u002Ftokens.css`:\n`--color-bg`, `--color-bg-elev`, `--color-indigo`, `--color-indigo-light`,\n`--color-cyan`, `--color-violet`, `--color-accent`, `--color-text`,\n`--color-text-muted`, `--color-text-dim`, `--color-border`. Never\nhardcode hex values inside a primitive — always go through the token.\n\n### 4. Render labels with foreignObject\n\nAll label-bearing primitives (`DataBox`, `LogicBox`, `TaskCard`,\n`TargetBullet`) use `\u003CforeignObject>` with a flex-centered `\u003Cdiv\nclass=\"dg-fo-label\">` so the browser auto-wraps labels against the box\nwidth. Just pass `label=\"...\"` — never pre-split into manual lines.\n\n### 5. Preview and verify before reporting done\n\nRun the preview script bundled with this skill:\n\n```bash\nscripts\u002Fpreview.sh \u003Cpage-slug>\n# Example: scripts\u002Fpreview.sh \u002F\n# Example: scripts\u002Fpreview.sh \u002Fblog\u002Fplaybook-anatomy\n```\n\nThe script handles: building the Astro site (`pnpm build`), serving the\n`dist\u002F` output on a free port with `pnpm preview` (no base-path\nmirroring is needed — this site is rooted at `\u002F`), screenshotting with\nheadless Chrome at retina-ish density, and printing paths to PNG crops.\nRead the PNGs with the `Read` tool to self-check before reporting the\ndiagram done.\n\nFor tight iteration, you can also point the script at the running\n`pnpm dev` server via `PREVIEW_DEV=1 scripts\u002Fpreview.sh \u003Cslug>` — that\nskips the build but reflects the current source file directly.\n\nDo NOT report a diagram complete based solely on \"the build compiled\".\nAlways render and look. Small issues like overlapping labels, dimmed\nrows, or wrong arrow styles are invisible from code alone.\n\n### 6. Iterate on visual feedback\n\nCommon iterations (see pitfalls for full details):\n\n- Elements faded at ~35% opacity → `dg-step` leaking onto static rows; remove it.\n- Boxes rendering with wrong dark fills → CSS variable typo (e.g. `var(--bg-elev)` instead of `var(--color-bg-elev)`); the token names in `tokens.css` are all `--color-*`.\n- Labels overlapping → `\u003CforeignObject>` not used, or box too narrow for the string.\n- Arrows to wrong targets → mixing absolute vs. TaskCard-local coordinate space.\n\n## Embedding pattern\n\n**Inside a section component** (most landing-page usage) — import with a\npath alias from `src` so it works regardless of how the section is\nre-organized:\n\n```astro\n---\n\u002F\u002F src\u002Fcomponents\u002Fsections\u002FArchitecture.astro\nimport PlaybookLifecycle from '@\u002Fcomponents\u002Fdiagrams\u002Fconcepts\u002FPlaybookLifecycle.astro';\n---\n\n\u003Csection>\n  \u003Ch2>How a playbook converges\u003C\u002Fh2>\n  \u003CPlaybookLifecycle \u002F>\n\u003C\u002Fsection>\n```\n\n**Inside a blog MDX post** — import with the same alias:\n\n```mdx\n---\ntitle: Anatomy of a Converge playbook\n---\nimport PlaybookLifecycle from '@\u002Fcomponents\u002Fdiagrams\u002Fconcepts\u002FPlaybookLifecycle.astro';\n\n## The lifecycle\n\n\u003CPlaybookLifecycle \u002F>\n```\n\nThe `@\u002F` alias is wired up in `astro.config.mjs` and resolves to\n`.\u002Fsrc\u002F`. Use it instead of relative `..\u002F..\u002F` paths.\n\n## Discipline\n\n- **Shape carries meaning.** Pick primitives by semantics, not \"what looks right\".\n- **No manual line-splitting.** If a label overflows, widen the box or shorten the label.\n- **Absolute coords for outer layout; local coords inside slotted containers.** `TaskCard`'s slot renders children with (0, 0) = container top-left.\n- **All flow arrows use the same color.** Default indigo; `variant=\"cyan\"` \u002F `\"muted\"` only when semantically meaningful.\n- **Bindings are silent.** `Connector` (static, dashed, no arrowhead) for \"X is bound to Y\" — e.g. task → declared output file, playbook → owner.\n- **Padding balanced on ALL sides.** Left == right inside every container, and top == bottom. Derive the container's width\u002Fheight from its content (`APP_W = sum(cols) + (n-1)*GAP + 2*APP_PAD_X`); downstream siblings reference `APP.x + APP_W`, not a hardcoded x. See [references\u002Flayout-patterns.md](references\u002Flayout-patterns.md) \"Balanced padding on all sides\".\n- **Prefer compactness.** Diagrams should read well at landing-page column width (~960px on desktop, narrower on mobile); stretch only when a visual story demands it.\n- **Never use `dg-step` for static content.** It's opacity-35% by default and only lights up on hover — reserved for progressive-reveal narratives (e.g. \"phase 1 → 2 → 3\" walk-through).\n- **All animations are idle by default, active on `.dg-root:hover`.** Flow-drift, delta-pulse, check-draw, spin — each gated the same way. No always-on motion on a static page. When adding a new `@keyframes` rule, register it in the `@media (prefers-reduced-motion: reduce)` block at the bottom of `diagrams.css`.\n- **State rules in CSS use the direct-child combinator (`.dg-state-X > .dg-box`)**, not descendant. A state class on a container would otherwise cascade into every nested `.dg-box`. Each shape primitive owns its own state on its own `ShapeGroup`-wrapped `\u003Cg>`.\n- **Compose new shape primitives on `ShapeGroup`**, not from scratch. It owns the wrapper `\u003Cg>`, state\u002Fhighlight class composition, `\u003Ctitle>removed\u003C\u002Ftitle>` tooltip, and the status-badge rendering (with suppression when removed). Never re-implement any of that.\n- **Multi-state scenario diagrams take a `scenario` prop**, inlined in the MDX or section file next to the prose. Don't create a `.astro` wrapper per scenario — the scenario is content, not a reusable component.\n- **Honor the dark theme.** Every primitive uses CSS variables from `tokens.css`. Never hardcode `#fff` or `#000`; always go through `var(--color-bg)` \u002F `var(--color-text)`. This keeps any future light-mode toggle clean.\n\n## Iteration expectations\n\nExpect 2–4 preview cycles for any non-trivial diagram. After the first\nrender, opacity\u002Fcolor\u002Foverlap issues almost always surface that weren't\nvisible from code inspection. Budget for the loop — don't try to land\nthe diagram in one shot.\n\n## Starter template\n\nSee [assets\u002Fstarter.astro](assets\u002Fstarter.astro) for a minimal\nshape-semantic diagram skeleton tuned for the Converge dark theme. Copy\nand adapt rather than writing from scratch.\n","# Converge Landing Diagrams\n\nInline SVG diagrams on the Converge landing site are authored as Astro\ncomponents under `src\u002Fcomponents\u002Fdiagrams\u002F`, composed from shape-semantic\nprimitives that share the site's dark-theme palette and styling. One-off\ninline `\u003Csvg>` blocks inside section components (e.g.\n`ConvergenceJourney.astro`) are legacy decoration — always build new\nexplanatory diagrams with the primitives so they stay consistent across\nthe page.\n\n## When this skill applies\n\nApply this skill when:\n\n- Adding a new diagram to a landing-page section (`.astro` under\n  `src\u002Fcomponents\u002Fsections\u002F` or `src\u002Fpages\u002F`).\n- Adding or editing a diagram inside a blog post (`.mdx` under\n  `src\u002Fcontent\u002Fblog\u002F`).\n- Editing or replacing an existing diagram component under\n  `src\u002Fcomponents\u002Fdiagrams\u002F`.\n- Reviewing a rendered diagram for layout or style issues.\n- Reworking a legacy one-off inline `\u003Csvg>` into the primitive system.\n\nDo not apply for:\n\n- Pure decorative animations (e.g. `ConvergenceJourney.astro`) that\n  exist only to set mood — they aren't trying to explain anything and\n  don't need shape semantics.\n- General SVG editing outside `src\u002Fcomponents\u002Fdiagrams\u002F` (icon files,\n  social cards, OG images).\n\n## The canonical reference\n\nRead `src\u002Fcomponents\u002Fdiagrams\u002FREADME.md` **first**. It documents the\nshape vocabulary, palette vars from `src\u002Fstyles\u002Ftokens.css`, shared CSS\nclasses, animation conventions, directory layout, and the MDX\u002FAstro\nembedding pattern. This SKILL.md assumes that reference is current — do\nnot duplicate it here.\n\nIf `src\u002Fcomponents\u002Fdiagrams\u002F` does not exist yet on this branch, the\nfirst diagram drop must scaffold it. Use the starter template under\n[assets\u002Fstarter.astro](assets\u002Fstarter.astro) and add a `README.md`\nalongside it that captures the palette\u002Fshape vocabulary you adopt.\n\nThen consult the three references bundled with this skill for the\nsession-specific knowledge that isn't in the project README:\n\n- [references\u002Fworkflow.md](references\u002Fworkflow.md) — the preview loop (Astro dev server \u002F `astro build && astro preview` + headless Chrome), how to crop and view output, rebuild discipline.\n- [references\u002Fpitfalls.md](references\u002Fpitfalls.md) — the traps that repeatedly cost iterations (dg-step opacity, color unification with dark theme tokens, magic-number insets, labels without auto-wrap).\n- [references\u002Flayout-patterns.md](references\u002Flayout-patterns.md) — layout idioms (horizontal arrows, symmetric padding, compactness, bindings vs arrows).\n\n## Core procedure\n\nWhen asked to create or edit a diagram, proceed in this order:\n\n### 1. Read the reference materials\n\nLoad `src\u002Fcomponents\u002Fdiagrams\u002FREADME.md` plus the three references\nabove. Skim, don't memorize — refer back when designing.\n\n### 2. Design the layout before writing code\n\nSketch positions with concrete numbers in a config object at the top of\nthe `.astro` file. Prefer absolute coordinates with a `viewBox` sized to\ncontent, and use named constants for box dimensions and column offsets.\n\n**Derive container size from content, not the other way around.** Start\nfrom inner widths, gaps, and pad; compute `APP_W = sum(cols) + (n-1) *\nGAP + 2 * APP_PAD_X`. Downstream siblings reference `APP.x + APP_W`,\nnot a hardcoded x. Same for vertical: pick row centers so top-pad ==\nbottom-pad. This keeps padding balanced on all four sides as you\niterate. See [references\u002Flayout-patterns.md](references\u002Flayout-patterns.md).\n\n### 3. Compose from primitives\n\nUse the shape-semantic primitives:\n\n| Shape | Meaning | Primitive |\n|---|---|---|\n| Sharp rectangle | Data (task output file, artifact, row) | `DataBox` |\n| Round-cornered rectangle | Subsystem \u002F logic (a task body, a check) | `LogicBox` (`memoized` + `status` props, slot) |\n| Elevated container with header | A Converge task \u002F playbook node | `TaskCard` (slot in local coords; `status` prop) |\n| Indigo-tinted container with header | A Converge playbook \u002F project root | `PlaybookContainer` (slot in local coords) |\n| Bullet (flat left, rounded right) | Goal \u002F deliverable state | `TargetBullet` |\n| Animated dashed arrow with head | Flow \u002F causation (parent → child run, body → check) | `FlowArrow` |\n| Static dashed line, no head | Binding \u002F identity (declared output → file, task → owner) | `Connector` |\n\nDelta state + run status annotations (orthogonal, on any shape):\n\n| Prop | Values | Visual |\n|---|---|---|\n| `state` | `new`, `updated`, `removed`, `changed`, `idle` | Cyan \u002F violet \u002F accent-red \u002F thin-accent fill (state cascade is prevented by direct-child CSS combinator — see pitfalls). |\n| `status` | `passing`, `running`, `failing` | Top-left badge. Passing draws a check on hover; running spins on hover; failing pulses. All suppressed when `state=\"removed\"`. |\n| `highlight` | `true` | Thick indigo border for \"currently-discussed element\" |\n\nNew shape primitives should **compose on top of `ShapeGroup`**, not\nre-implement the wrapper `\u003Cg>` + state class + title + badge logic.\n\nPalette tokens come from `src\u002Fstyles\u002Ftokens.css`:\n`--color-bg`, `--color-bg-elev`, `--color-indigo`, `--color-indigo-light`,\n`--color-cyan`, `--color-violet`, `--color-accent`, `--color-text`,\n`--color-text-muted`, `--color-text-dim`, `--color-border`. Never\nhardcode hex values inside a primitive — always go through the token.\n\n### 4. Render labels with foreignObject\n\nAll label-bearing primitives (`DataBox`, `LogicBox`, `TaskCard`,\n`TargetBullet`) use `\u003CforeignObject>` with a flex-centered `\u003Cdiv\nclass=\"dg-fo-label\">` so the browser auto-wraps labels against the box\nwidth. Just pass `label=\"...\"` — never pre-split into manual lines.\n\n### 5. Preview and verify before reporting done\n\nRun the preview script bundled with this skill:\n\n```bash\nscripts\u002Fpreview.sh \u003Cpage-slug>\n# Example: scripts\u002Fpreview.sh \u002F\n# Example: scripts\u002Fpreview.sh \u002Fblog\u002Fplaybook-anatomy\n```\n\nThe script handles: building the Astro site (`pnpm build`), serving the\n`dist\u002F` output on a free port with `pnpm preview` (no base-path\nmirroring is needed — this site is rooted at `\u002F`), screenshotting with\nheadless Chrome at retina-ish density, and printing paths to PNG crops.\nRead the PNGs with the `Read` tool to self-check before reporting the\ndiagram done.\n\nFor tight iteration, you can also point the script at the running\n`pnpm dev` server via `PREVIEW_DEV=1 scripts\u002Fpreview.sh \u003Cslug>` — that\nskips the build but reflects the current source file directly.\n\nDo NOT report a diagram complete based solely on \"the build compiled\".\nAlways render and look. Small issues like overlapping labels, dimmed\nrows, or wrong arrow styles are invisible from code alone.\n\n### 6. Iterate on visual feedback\n\nCommon iterations (see pitfalls for full details):\n\n- Elements faded at ~35% opacity → `dg-step` leaking onto static rows; remove it.\n- Boxes rendering with wrong dark fills → CSS variable typo (e.g. `var(--bg-elev)` instead of `var(--color-bg-elev)`); the token names in `tokens.css` are all `--color-*`.\n- Labels overlapping → `\u003CforeignObject>` not used, or box too narrow for the string.\n- Arrows to wrong targets → mixing absolute vs. TaskCard-local coordinate space.\n\n## Embedding pattern\n\n**Inside a section component** (most landing-page usage) — import with a\npath alias from `src` so it works regardless of how the section is\nre-organized:\n\n```astro\n---\n\u002F\u002F src\u002Fcomponents\u002Fsections\u002FArchitecture.astro\nimport PlaybookLifecycle from '@\u002Fcomponents\u002Fdiagrams\u002Fconcepts\u002FPlaybookLifecycle.astro';\n---\n\n\u003Csection>\n  \u003Ch2>How a playbook converges\u003C\u002Fh2>\n  \u003CPlaybookLifecycle \u002F>\n\u003C\u002Fsection>\n```\n\n**Inside a blog MDX post** — import with the same alias:\n\n```mdx\n---\ntitle: Anatomy of a Converge playbook\n---\nimport PlaybookLifecycle from '@\u002Fcomponents\u002Fdiagrams\u002Fconcepts\u002FPlaybookLifecycle.astro';\n\n## The lifecycle\n\n\u003CPlaybookLifecycle \u002F>\n```\n\nThe `@\u002F` alias is wired up in `astro.config.mjs` and resolves to\n`.\u002Fsrc\u002F`. Use it instead of relative `..\u002F..\u002F` paths.\n\n## Discipline\n\n- **Shape carries meaning.** Pick primitives by semantics, not \"what looks right\".\n- **No manual line-splitting.** If a label overflows, widen the box or shorten the label.\n- **Absolute coords for outer layout; local coords inside slotted containers.** `TaskCard`'s slot renders children with (0, 0) = container top-left.\n- **All flow arrows use the same color.** Default indigo; `variant=\"cyan\"` \u002F `\"muted\"` only when semantically meaningful.\n- **Bindings are silent.** `Connector` (static, dashed, no arrowhead) for \"X is bound to Y\" — e.g. task → declared output file, playbook → owner.\n- **Padding balanced on ALL sides.** Left == right inside every container, and top == bottom. Derive the container's width\u002Fheight from its content (`APP_W = sum(cols) + (n-1)*GAP + 2*APP_PAD_X`); downstream siblings reference `APP.x + APP_W`, not a hardcoded x. See [references\u002Flayout-patterns.md](references\u002Flayout-patterns.md) \"Balanced padding on all sides\".\n- **Prefer compactness.** Diagrams should read well at landing-page column width (~960px on desktop, narrower on mobile); stretch only when a visual story demands it.\n- **Never use `dg-step` for static content.** It's opacity-35% by default and only lights up on hover — reserved for progressive-reveal narratives (e.g. \"phase 1 → 2 → 3\" walk-through).\n- **All animations are idle by default, active on `.dg-root:hover`.** Flow-drift, delta-pulse, check-draw, spin — each gated the same way. No always-on motion on a static page. When adding a new `@keyframes` rule, register it in the `@media (prefers-reduced-motion: reduce)` block at the bottom of `diagrams.css`.\n- **State rules in CSS use the direct-child combinator (`.dg-state-X > .dg-box`)**, not descendant. A state class on a container would otherwise cascade into every nested `.dg-box`. Each shape primitive owns its own state on its own `ShapeGroup`-wrapped `\u003Cg>`.\n- **Compose new shape primitives on `ShapeGroup`**, not from scratch. It owns the wrapper `\u003Cg>`, state\u002Fhighlight class composition, `\u003Ctitle>removed\u003C\u002Ftitle>` tooltip, and the status-badge rendering (with suppression when removed). Never re-implement any of that.\n- **Multi-state scenario diagrams take a `scenario` prop**, inlined in the MDX or section file next to the prose. Don't create a `.astro` wrapper per scenario — the scenario is content, not a reusable component.\n- **Honor the dark theme.** Every primitive uses CSS variables from `tokens.css`. Never hardcode `#fff` or `#000`; always go through `var(--color-bg)` \u002F `var(--color-text)`. This keeps any future light-mode toggle clean.\n\n## Iteration expectations\n\nExpect 2–4 preview cycles for any non-trivial diagram. After the first\nrender, opacity\u002Fcolor\u002Foverlap issues almost always surface that weren't\nvisible from code inspection. Budget for the loop — don't try to land\nthe diagram in one shot.\n\n## Starter template\n\nSee [assets\u002Fstarter.astro](assets\u002Fstarter.astro) for a minimal\nshape-semantic diagram skeleton tuned for the Converge dark theme. Copy\nand adapt rather than writing from scratch.\n",{"name":5,"description":7},"main","7d618d8bc059f1a0974706d1d15ec25f73cf1e1d",".claude\u002Fskills\u002Fconverge-diagrams",1,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge","https:\u002F\u002Fplaybooks.to","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev","2026-06-13 10:11:21",{"source":8,"skillName":5,"commands":65,"prompt":75,"zipAvailable":76},[66,69,72],{"tool":67,"command":68},"npx","npx skills add openplaybooks-dev\u002Fconverge --skill converge-diagrams",{"tool":70,"command":71},"bunx","bunx skills add openplaybooks-dev\u002Fconverge --skill converge-diagrams",{"tool":73,"command":74},"pnpm","pnpm dlx skills add openplaybooks-dev\u002Fconverge --skill converge-diagrams","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-diagrams\u002FSKILL.md",true,[78,84,90,94,98],{"path":79,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":82,"sourceHtmlUrl":83},"assets\u002Fstarter.astro","ASSET","资产文件",3128,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-diagrams\u002Fassets\u002Fstarter.astro",{"path":85,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Flayout-patterns.md","REFERENCE","参考文档",9231,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-diagrams\u002Freferences\u002Flayout-patterns.md",{"path":91,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Fpitfalls.md",8218,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-diagrams\u002Freferences\u002Fpitfalls.md",{"path":95,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Fworkflow.md",3355,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-diagrams\u002Freferences\u002Fworkflow.md",{"path":99,"resourceType":100,"resourceTypeDesc":101,"sizeBytes":102,"sourceHtmlUrl":103},"scripts\u002Fpreview.sh","SCRIPT","脚本",3953,"https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fconverge-diagrams\u002Fscripts\u002Fpreview.sh",[105,128,137,159,181,207],{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":112,"publishedAt":51},"01M71989MQF3GPZ7P5TX6S93PD","hello-checker","Use this skill when asked to \"verify\", \"check\", or \"validate\" a file's existence and content. It provides a reliable workflow for confirming files meet their spec.","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Ftests\u002Ftest-codex-real\u002F.converge\u002Fskills\u002Fhello-checker\u002FSKILL.md",[111],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,35],"checker","hello checker","hello","it","use","content","validate","spec","verify","check","file","workflow","when","Meet","files",{"skillNo":129,"name":130,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":134,"publishedAt":51},"01M7198823W79B3S15TPV97TCB","ask-skill","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Ftests\u002Ftest-ask-autonomous\u002F.converge\u002Fplaybooks\u002Fdefault\u002Fskills\u002Fask-skill\u002FSKILL.md",[133],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[135,136],"ask skill","ask",{"skillNo":138,"name":139,"nameZh":6,"description":140,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":141,"categories":142,"keywords":147,"publishedAt":51},"01M71986EJ6VCM8YKGEM2YEDQV","html-review-artifact","Framework-wide guidance for crafting polished human-review artifacts as markdown or HTML","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fskills\u002Fhtml-review-artifact\u002FSKILL.md",[143,146],{"categoryNo":144,"categoryName":145,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[148,149,150,151,152,35,153,154,155,156,157,158],"html","artifact","review","html review artifact","as","framework","wide","guidance","markdown","human","artifacts",{"skillNo":160,"name":161,"nameZh":6,"description":162,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":163,"categories":164,"keywords":166,"publishedAt":51},"01M719833M2XWXG1VPBW30GW7J","converge-planning","Design a Converge playbook end-to-end. Use when the user says \"plan a project\", \"design a playbook\", \"decompose into tasks\", \"scaffold a Converge workflow\", \"onboard to Converge\", or asks how to write TASK.md \u002F playbook.yml. Two entry points: plan a new playbook or update an existing one. Hand off to `\u002Fconverge-control` after producing the playbook structure.","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fskills\u002Fconverge-planning\u002FSKILL.md",[165],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[33,167,168,169,124,170,117,171,172,173,174,40,175,39,176,177,178,179,180,125],"converge planning","planning","structure","tasks","decompose","hand","write","plan","update","new","design","how to","end","project",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":191,"publishedAt":51},"01M7197XZT1T9GDYAJGVGX1J60","converge-control","Operate a Converge playbook end-to-end — start runs, monitor progress, narrow failures with `--select`, inspect runtime state, validate definitions, surgically reset subtrees, and stop stuck or orphaned runs. Use this skill whenever the user says \"run my playbook\", \"execute this\", \"monitor the run\", \"converge failed\", \"the run is stuck\", \"retry failures\", \"babysit this playbook\", \"what's the status?\", \"show me the gantt\", or asks how to use `converge run` \u002F `--select` \u002F `inspect` \u002F `doctor` \u002F `clean` \u002F `stop`. Also use it for `HTTP 401` \u002F `Invalid API key` failures on the first task — those are environment-not-playbook problems — and for any post-run cleanup work. Hand off to `converge-planning` if the user wants to design or restructure the playbook itself.","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fskills\u002Fconverge-control\u002FSKILL.md",[187,188],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":189,"categoryName":190,"taxonomyType":28,"taxonomyTypeDesc":29},"01JBSEEDCAT000000000000030","开发工程师",[192,193,33,194,195,196,197,198,199,200,172,201,202,177,178,203,179,204,205,206],"converge control","control","operate","invalid","show","api","me","work","reset","show me","cleanup","clean","inspect","select","retry",{"skillNo":208,"name":209,"nameZh":6,"description":210,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":211,"categories":212,"keywords":214,"publishedAt":51},"01M7197SCVN0QTD3CM4M83WYJH","repair-taskts","Fix task.ts definition issues — Seed syntax, missing .build(), empty checks, import errors, TypeScript errors","https:\u002F\u002Fgithub.com\u002Fopenplaybooks-dev\u002Fconverge\u002Fblob\u002Fmain\u002Fpackages\u002Fcore\u002Fsrc\u002Fnavigator\u002Frepair\u002Fskill-templates\u002Frepair-taskts\u002FSKILL.md",[213],{"categoryNo":189,"categoryName":190,"taxonomyType":28,"taxonomyTypeDesc":29},[215,216,217,38,173,218,219,220,221,222,223,224,225,226,227,179,228,33,229,230],"repair taskts","repair","Bash","read","line","at","spawn","code","analysis","number","errors","issues","fix","chain","definition","never"]