development-pattern-guide

development-pattern-guide

Turn a real codebase into a paginated, offline HTML tutorial that teaches the pattern behind it — so a developer can engineer their own project the same way. A trivial example of the output: a tutorial on using the Singleton Pattern to write a database library.

The generated site is plain static HTML + CSS + vanilla JS. It opens directly in a browser: no build step, no server, no CDN, no network. All assets (including fonts) are bundled.

Skill assets live next to this file under assets/: default-global.css, guide.js, fonts/ (bundled WOFF2 + FONTS.md), templates/ (page-template.html, toc-template.html, architecture-template.html), and guide.schema.json. Resolve them relative to this SKILL.md; call that directory SKILL_DIR.

1. Detect the operation

Read the user's request and pick exactly one:

If the request is ambiguous (e.g. a path and "add a chapter"), ask the user which operation they want before proceeding.

A user-supplied style guide (style-guide.html + style-guide.css) may be provided to Create or Update style. See §6.

2. Output location (all operations that write a guide)

• The guide is always written into a subfolder named development-pattern-guide/. Create it if it does not exist; reuse it if it does.
• Deciding the parent of that subfolder:
  • Local repository source → you MUST ask the user where to put it:

    "Create the guide inside the repository (<repo>/development-pattern-guide/) or in the folder you started from (<cwd>/development-pattern-guide/)?"

  • Repo URL source (cloned to a temp dir) → use the current working directory (the folder the user started in). Do not write the guide into the temp clone.
  • Local folder source that is not a git repo → default to that folder; if it is clearly read-only or not the user's project, ask.
• Inside the guide folder, copy the skill assets into an assets/ subfolder (see §3, step 7). Never modify the originals in SKILL_DIR.

3. Create a new guide

Step 0 — Parse inputs

Identify the source (repo path / repo URL / folder) and any --style-guide / --style-css paths. Report the plan to the user in one short line.

Step 1 — Acquire the source

• Repo URL → git clone --depth 1 <url> into a temp directory; analyze there.
• Local path / folder → analyze in place (read-only; do not modify the source).
• Verify the path exists; if not, stop and tell the user.

Step 2 — Resolve the output location

Apply §2. Confirm the final guide path with the user before generating files.

Step 3 — Research the codebase (do this thoroughly and deeply)

Build a deep understanding before writing anything. Shallow, surface-level research produces a shallow guide, which is the failure mode to avoid. Read the actual implementation, not just file names and signatures. Prefer, in order: available code-intelligence tools → language servers → glob/grep → reading key files. Trace at least one real end-to-end path through the code yourself. Determine:

• Tech stack: languages, frameworks, runtimes, package managers, notable libraries/SDKs, cloud services (note .NET Aspire if present — see §5/Deployment).
• High-level architecture: the core systems, sub-systems, major components, and how they interact (entry points, control flow, data/request flow).
• Key classes/modules/services and their responsibilities, including the contracts and invariants they uphold (what must always be true) and the boundaries between them (interfaces, abstractions, seams).
• Control and data flow specifics: how a request/operation actually moves through the system step by step, where state lives, and how errors, edge cases, and failures are handled.
• The repeatable pattern: the core idea that makes this design work and could be reused in another project (e.g. "a single shared accessor guards all access to a resource"). Capture it with real depth, not just a one-line label:
  • Motivation: the problem the pattern solves and why a naive approach falls short.
  • Forces and trade-offs: the competing concerns it balances, and what it deliberately gives up to gain what it gains.
  • Structure: the roles/participants in the pattern and how they collaborate.
  • Consequences: what becomes easy, what becomes hard, and the failure modes to watch for. This pattern, in this depth, is the spine of the tutorial.
• Setup/run path: how someone installs deps and runs it locally.

Carry this research forward into the approval summary in Step 6 and into the chapter content; do not discard the depth once analysis is done.

Step 4 — Generalize all names (critical)

The tutorial teaches a reusable pattern, so it must not use the source's real identifiers. For every system, sub-system, class, and library, derive a general-purpose name from its purpose and use that consistently everywhere.

• Example: RetailerFinancialRecord → DataModel; AcmePaymentGateway → PaymentService; Foo.Bar.UserRepositoryImpl → Repository.
• Keep a naming map (real → general) for your own consistency; write the general names into pages and into guide.json. Never leak the originals into the rendered guide. (You may keep the map in memory; do not ship it in the site.)
• One exception: the "Sourced Repository" chapter (Step 5). That chapter exists to describe the real originating repository, so it does use the source's real identifiers. This carve-out is strictly limited to that single chapter — every other chapter, the TOC, the architecture node graph, and guide.json must still use only the generalized names.

Step 5 — Plan the chapters

Order is fixed for the framing chapters; pattern chapters sit in the middle.

Required, in this order: 0. Table of Contents — index.html (pretty landing page; links to all chapters).

1. Introduction — what this pattern does at its core.
2. Sourced Repository — a high-level, technically detailed overview of the real originating source repository the pattern was derived from: its systems, sub-systems, and key classes/modules/services, and how they fit together. The purpose is to give the reader the context needed to understand what was actually studied when deriving the pattern. This chapter is the single explicit exception to the name-generalization rule (§3 Step 4 / §7): it uses the source's real identifiers. See the per-chapter guidance below for what to cover.
3. Prerequisites — required tools, technologies, SDKs/packages, accounts or permissions, and assumed skills.
4. High Level Architecture — core systems/sub-systems, major components, how they interact, and data/request flow. Rendered as an interactive left-to-right node graph: clickable nodes → modal dialogs, with directional labeled edges showing each relationship (see §7 and architecture-template.html).

Then the pattern chapters — the "learn by doing" core. Break the pattern into logical chapters, one HTML page each, sequenced so a reader can build their own solution chapter-by-chapter.

Then, last (in this order):

• Extending the System — how to add features/plugins/modules, where they hook into the pattern, and common extension patterns.
• Deployment — when applicable (cloud-derived patterns): how to deploy. If the source uses Aspire, explain deploying with Aspire (e.g. azd / Aspire manifests). Omit this chapter if deployment is not relevant to the pattern.
• Appendix: Additional Reading — the absolute last chapter: curated URLs for the stack and concepts used by the pattern. Render these as a vertically stacked list of full-width cards using <div class="resource-list"> containing one <div class="resource-card"> per resource (each with a title, a short description, and the link). Do not use the multi-column .card-grid; full-width stacked cards give long URLs room to wrap so they never overflow.

Number chapters 1..N (the TOC page is number 0 / index.html). Name files NN-slug.html (zero-padded), e.g. 01-introduction.html.

Chapter titles must be plain, specific, descriptive names for the thing the chapter covers, written for an engineer scanning a table of contents. Name the component or concept directly (e.g. "Domain Model", "Repository Layer", "Composition Root", "Data Import Service"). Do not use decorative, abstract, or "artistic" phrasing, marketing language, or prose instructions (avoid "The Heart of the System", "Bringing It All Together", "Start with the Data"). Keep titles short and concrete. Write them in title case (capitalize principal words as for the title of a book or article), not sentence case or prose. The same rule applies to the section titles within each chapter (see §7).

Sourced Repository chapter — what to cover. This chapter is unique: it describes the real source repository the pattern was derived from, so the reader knows exactly what was studied. Write it from the deep research in Step 3 and cover, with genuine technical depth (per §7):

• What the project is: its purpose, domain, and tech stack (languages, frameworks, runtimes, notable libraries/SDKs/services).
• Systems and sub-systems: the major systems, the sub-systems inside them, and how they interact (entry points, control flow, data/request flow).
• Key classes/modules/services: the important real types and their responsibiliti

Content truncated.