简体中文 · English

# dsh-plugin-tailor > From “it runs” to “ship it”: audit → pick a style → brand assets → bilingual README → pre-release verification.

_{MIT · Node >=20 · DSH >=0.2.0-rc.2 <0.3.0 · v0.5.0}

Install · Seven styles · Six tools · Roadmap

8 audit dimensions, 44 checks, 7 styles, 12 original vector concepts

Real terminal: repo_audit scores dsh-plugin-resolver 81/100, repo_verify returns PASS

_{Real output: tailor audit ../dsh-plugin-resolver and tailor verify … (VHS tape to re-record)}

## Contents - [Why it exists](#why-it-exists) - [How it works](#how-it-works) - [Features](#features) - [Quickstart](#quickstart) - [Six tools](#six-tools) - [Seven styles](#seven-styles) - [Custom styles](#custom-styles) - [Brand assets](#brand-assets) - [Visual system](#visual-system) - [Tool output](#tool-output) - [Results and evidence](#results-and-evidence) - [Layout](#layout) - [Tests and CI](#tests-and-ci) - [Known limitations](#known-limitations) - [Security boundaries](#security-boundaries) - [FAQ](#faq) - [Roadmap](#roadmap) - [Ecosystem and listings](#ecosystem-and-listings) - [Feedback and security](#feedback-and-security) - [License](#license) ## Why it exists - **READMEs stop at “it runs”**: install commands hidden in docs, a random screenshot as the demo, no limitations section. The better the project, the more it loses on presentation. - **Every repository means redoing the same work**: first screen, badges, TOC, assets, release checks — and no reusable style. - **Nobody checks before release**: broken relative links, anchors, images, leftover TODOs, stale test counts — readers find them first. - **“Beautiful” has no standard**: instead of copying one template, this plugin distils what good repositories share into selectable style presets plus executable checks. What it does: **8 dimensions / 44 checks** for maturity, **7 style presets** for the README, **deterministic SVG** for brand assets, and one `repo_verify` before you publish.

Manual README versus tailor-generated: demo, evidence, brand, link checks

## How it works

repo_audit → repo_plan → repo_brand → repo_readme → repo_verify

1. **`repo_audit`** reads `package.json`, README, assets, CI and git state, scores 8 dimensions / 44 checks, and returns gaps sorted by impact. 2. **`repo_plan`** turns gaps into P0/P1/P2 tasks with acceptance criteria and the exact `repo_verify` command; style gaps (no GIF, no screenshots, no English page) become tasks too. 3. **`repo_brand`** generates `icon.svg` / `logo.svg` / `banner.svg` / `social-preview.svg` from the style palette and mark — deterministic, no image model, never overwrites existing files. 4. **`repo_readme`** assembles zh/en drafts from repository facts only; missing facts become `TODO(tailor)` markers; dry-run prints a diff, `apply` writes. 5. **`repo_verify`** re-runs the audit plus relative-link, image, anchor, badge, required-section and leftover-TODO checks, and reports PASS/FAIL with the baseline score delta. ## Features

Six capabilities: repo_audit, repo_readme, repo_brand, bilingual parity, write protection, repo_verify

- **8 dimensions / 44 checks**: identity, first screen, install, docs, evidence, release, community, brand — every gap comes with a concrete fix, not just a score. - **7 styles + bilingual drafts**: from evidence-first to minimal typography; dry-run diff first, write second. - **Author your own style**: built-ins are seven JSON files; custom styles live in `.tailor/styles/` or `~/.tailor/styles/`, with `extends` inheritance and schema validation. - **12 vector concepts × 12 brand files**: icon / maskable / light+dark logo / light+dark wordmark / light+dark banner / social / brand-sheet / brand-tokens.json / index — 12 files, byte-identical on re-run. - **Visual QA**: the palette is checked for WCAG contrast and `repo_brand` prints PASS/FAIL; the audit carries 14 brand/visual checks (sizes, ratios, light/dark pairs, alt text, first-screen image, width control). - **3 README layout engines**: `editorial` / `centered` / `showcase`, configured per style via `visual`, not one template recoloured. - **Write protection**: hand-written READMEs, existing assets and dirty worktrees are refused unless `force` is explicit. - **Pre-release verification**: relative links, images, anchors, badges, required sections and leftover TODOs in one PASS/FAIL command. - **CLI and DSH tools share one logic layer**: `bin/tailor.mjs` calls the same code as the six tools, so the terminal reproduces the agent. ## Quickstart > **Published to npm and GitHub Releases (v0.5.0). Three ways to install:** ```sh # 1) DSH plugin (recommended, straight from npm) dsh plugin --profile add dsh-plugin-tailor # 2) CLI only (no DSH needed) npm install -g dsh-plugin-tailor dsh-repo-tailor styles # 3) Offline: source or the release tarball git clone https://github.com/sakikoTGW/dsh-plugin-tailor dsh plugin --profile add /path/to/dsh-plugin-tailor dsh plugin --profile add /path/to/dsh-plugin-tailor-0.5.0.tgz ``` Restart the engine once and the six `repo_*` tools are live. After that, edits under `logic/` apply on the next call; edits to `host/register.js` or `index.js` need an engine restart. The CLI uses the same logic and needs no DSH host: ```sh node bin/tailor.mjs styles # list the 7 styles node bin/tailor.mjs audit . --style=terminal # score + gaps node bin/tailor.mjs plan . --style=terminal # task list node bin/tailor.mjs brand . --style=playful --apply node bin/tailor.mjs readme . --style=evidence --lang=both node bin/tailor.mjs verify . --style=evidence node bin/tailor.mjs style:init . --id=my-style --extends=evidence # custom style ```

CLI help: six commands and examples

_{tailor --help: six commands and examples, same logic as the DSH tools.}

From DSH: ```text repo_audit { path: ".", style: "terminal" } repo_plan { path: ".", style: "terminal" } repo_readme { path: ".", style: "terminal", lang: "both" } repo_brand { path: ".", style: "terminal", apply: true } repo_verify { path: ".", style: "terminal" } ``` ## Six tools | Tool | R/W | Arguments | Returns | |---|---|---|---| | `repo_styles` | read | `path?`, `json?` | built-in + custom style ids, origin (builtin/global/repo) and validation errors; `json: true` returns a machine-readable payload | | `repo_audit` | read | `path`, `style?` | 0-100 score, 8-dimension breakdown, impact-sorted gaps, style gaps | | `repo_plan` | read | `path`, `style?`, `limit?` | P0/P1/P2 tasks with acceptance criteria and verify command | | `repo_readme` | dry-run / write | `path`, `style?`, `lang?`, `apply?`, `force?` | diff, TODO list, style gaps | | `repo_brand` | dry-run / write | `path`, `style?`, `concept?`, `tagline?`, `apply?`, `force?` | 8 files (12 concepts) | | `repo_verify` | read | `path`, `style?` | PASS/FAIL, per-check detail, leftover TODOs, score delta | Writes are dry-run by default; hand-written READMEs and existing assets are refused/skipped unless `force`; a dirty worktree is refused without `force`. ## Seven styles

Seven README style presets: evidence-first, terminal, mobile, playful, product, platform, minimal

| id | Style | Language | Hero | Demo | Default concept | Best for | |---|---|---|---|---|---|---| | `evidence` | Evidence-first | bilingual | banner | GIF | `arcs` | engineering repos with benchmarks/tests | | `terminal` | Terminal tool | bilingual | centered logo | GIF | `prompt` | CLI tools with a real logo | | `mobile` | Mobile · community | zh-first | banner | screenshots | `orbit` | apps / mobile / community products | | `playful` | GIF-first tutorial | en-first | logo | GIF | `bubble` | TUIs and developer tools | | `product` | Product page | en-first | brand banner | screenshots | `radar` | end-user products | | `platform` | Panel platform | bilingual | centered logo | GIF | `hexstack` | panels and platforms | | `minimal` | Minimal type | en-first | none | none | `monogram` | mature tools / frameworks | How to choose, each preset's section order, and the “12 things good repositories share” live in [docs/STYLES.md](docs/STYLES.md). ## Custom styles The seven built-ins are not code — they are seven **JSON files** (`styles/*.json`). Your own style is JSON too: put it in `/.tailor/styles/` or `~/.tailor/styles/`; the loader merges, validates and picks it up without touching logic. ```sh cp styles/evidence.json .tailor/styles/acme.json # change id / copy / palette, then node bin/tailor.mjs styles . # acme shows up with repo origin node bin/tailor.mjs readme . --style=acme --lang=both ``` Or inherit from an existing style and override only what you need: ```sh node bin/tailor.mjs style:init . --id=acme --extends=evidence ``` ```json { "extends": "evidence", "id": "acme", "label": { "zh": "Acme evidence", "en": "Acme evidence" }, "palette": { "brand": "#E4572E", "deep": "#B23A1C" }, "labels": { "install": { "zh": "开始使用", "en": "Get started" } } } ``` - Load order: built-in → `~/.tailor/styles` → `/.tailor/styles`; later wins on the same id. - `extends` merges key by key: `label` / `palette` / `labels` merge, `sections` / `badgeSet` arrays replace. - Field reference and full schema: [styles/README.md](styles/README.md) and [styles/schema.json](styles/schema.json). - Invalid style files are **skipped** and reported by `repo_styles`; other styles keep working. - Machine-readable: `tailor styles . --json` (DSH tool `repo_styles { json: true }`) returns `styles` / `dirs` / `errors` for GUIs and other agents. - Every tool (`repo_audit` / `repo_plan` / `repo_readme` / `repo_brand` / `repo_verify`) accepts a custom `style` id. ## Brand assets

`repo_brand` is not a template swap: pick one of 12 hand-built geometric concepts, combined with the style palette and light/dark layouts.

The 12 concepts one by one: needle, stitch, quill, arcs, orbit, prompt, bubble, radar, hexstack, monogram, spark, layers

_{12 concepts, one per frame; the full contact sheet is above.}

_logo-dark

_icon

_{Light and dark banners/logos: dark for the README, light for docs and slides.}

| Concept | Best for | Concept | Best for | |---|---|---|---| | `needle` | tailoring / custom / craft | `stitch` | done / verify / delivery | | `quill` | writing / docs / narrative | `arcs` | growth / metrics / evidence | | `orbit` | network / remote / connection | `prompt` | CLI / terminal / tools | | `bubble` | product / interaction / light | `radar` | monitoring / scanning / security | | `hexstack` | platform / panel / layers | `monogram` | mature tools / minimal | | `spark` | generic / brand / highlight | `layers` | architecture / modules / reuse | One run writes 12 files: | File | Size | Purpose | |---|---|---| | `icon.svg` | 512×512 | icon / avatar | | `icon-maskable.svg` | 512×512 | PWA / Android, 80% safe area | | `logo.svg` / `logo-dark.svg` | 760×176 | light / dark lockups | | `wordmark.svg` / `wordmark-dark.svg` | 760×120 | text-only lockup for slides / video | | `banner.svg` / `banner-light.svg` | 1280×400 | dark / light banners | | `social-preview.svg` | 1280×640 | GitHub social preview | | `brand-sheet.svg` | 1280×auto | 12 concepts + palette contrast | | `brand-tokens.json` | — | palette, contrast, type, spacing and motion tokens | | `assets/README.md` | — | asset index, usage and switch commands | The palette is checked for WCAG contrast before it reaches the tokens: body ≥7:1, graphics ≥3:1; dry-run lists every check. ```sh node bin/tailor.mjs brand . --style=evidence --concept=needle \ --tagline="From it runs to ship it." --apply --force ``` Dry-run lists files, concept and contrast checks; `apply` writes, and existing files are skipped by default. ## Visual system Visuals are a system of explainable rules, not "add a banner". The design and motion principles live in [docs/DESIGN.md](docs/DESIGN.md) (from emotion-design / apple-design / hallmark: decide the emotion first, motion must carry information, no fake terminal chrome, spacing and type go into tokens).

Logo construction motion: grid → mark → tile → lockup → identity, each beat explained

_{Mark construction: 6 beats, ~3s; the last beat holds for 2s instead of looping decoratively.}

Three layout engines, configured in a style's `visual` block (custom styles can use them too): | engine | Styles | First screen | Nav | Demo | Feel | |---|---|---|---|---|---| | `editorial` | `evidence` / `minimal` | left-aligned banner or type-only | inline links | 720–760px | long-form, dense | | `centered` | `terminal` / `platform` | centered logo + centered H1 | `` chips | 760px | product homepage, clear anchor | | `showcase` | `mobile` / `playful` / `product` | full-width banner + centered H1 | `` chips | 860px | launch page, visuals first | Configurable: `engine`, `badgeStyle` (flat-square / for-the-badge), `demoWidth`, `navStyle`, `featureCards`, `footer`; schema in [styles/README.md](styles/README.md). The visual audit is now 14 checks (brand dimension weighs 20%): logo size/ratio, light/dark pairs, banner ratio, 2:1 social preview, maskable icon, wordmark, tokens, demo asset, README image count, alt coverage, first-screen image, width control. `repo_audit` sorts the gaps by impact. ## Tool output Real CLI output, not mockups; each screenshot is rendered from the actual stdout with the command in the frame. _{tailor styles: describes styles only, no repository names.} _{tailor brand . --style=evidence --concept=needle: dry-run lists 8 files and 12 concepts.} _{tailor verify: on PASS it reports links, images, anchors, sections and leftover TODOs.} ## Results and evidence - **Self-audit**: this repository used itself to add docs, brand assets and README — score **37 → 100** (D → A). `dsh-plugin-resolver` audits at **81/100 (B)** and `repo_verify` returns `PASS`. - **Tests**: 18 offline tests (`npm test`, pass 18 / fail 0); CI runs on Node 20/22/24. - **Pure logic**: `auditFacts` **0.01 ms**, `renderReadme` **0.03 ms**, `verifyFacts` **0.03 ms**; `collectFacts` is **109–794 ms** because it spawns 4 `git` processes (depends on repository size). - **CLI end-to-end**: `tailor audit .` median **248 ms**, of which ~200 ms is Node startup. - **Method**: environment, procedure and output sizes are in [BENCHMARK.md](BENCHMARK.md); before/after and test output are in [docs/EVIDENCE.md](docs/EVIDENCE.md). ## Layout ```text index.js host half: tool registration + hot-loaded logic host/register.js tool schemas (stable; restart to change) logic/ api.js six tool entry points facts.mjs read-only repository facts rubric.mjs 8 dimensions / 44 checks plan.mjs gaps → P0/P1/P2 tasks styles.mjs style loader (JSON + custom + extends + validation) style-schema.mjs style schema and merge rules readme.mjs bilingual drafts, layout engines, diff, apply safety brand.mjs 12-concept brand engine (12 files + contrast QA) palette.mjs colour, contrast, design tokens verify.mjs links / anchors / images / sections / TODOs util.mjs diff, slug, path boundary styles/ seven built-in style JSON files + schema.json + docs bin/tailor.mjs CLI (same logic as the tools) bench/micro.mjs pure-logic microbenchmark docs/ SPEC / STYLES / DESIGN / ACCEPTANCE / EVIDENCE test/tailor.test.mjs 18 offline tests ``` ## Tests and CI ```sh npm test # 18 offline tests node bench/micro.mjs . # pure-logic microbenchmark node bin/tailor.mjs verify . --style=evidence ``` - Coverage: style registry, facts, audit ordering, plan, README rendering/write safety, deterministic brand, broken links/images/anchors, host registration, CLI. - CI: `.github/workflows/test.yml`, Node 20/22/24 matrix, runs `npm test`, a CLI smoke test and `npm pack --dry-run`. _{Real CI: the Node 20 / 22 / 24 jobs all pass in 19 seconds.} ## Known limitations - **The score measures structure and evidence presence, not prose quality**: 100 does not mean the README is pleasant to read; a human still decides. - **Drafts must be reviewed**: `TODO(tailor)` markers are for you to fill; `repo_verify` reports leftover TODOs as a warning. - **zh / en only**, no auto style selection, no auto commit / push / publish. - **No real screenshots or images**: `repo_brand` only generates SVG geometry and tokens; the demo GIF/screenshots must be recorded from a real run. - **Motion is a GIF explainer, not interactive animation**: `mark-motion.gif` only explains the construction; a README cannot honour `prefers-reduced-motion`. - **Brand assets are geometric SVG, not illustration/photography**: illustration-level work still needs a human or an image model; `repo_brand` guarantees concept choice, 12 files, light/dark pairs, contrast QA, consistency and reproducibility. - **Invalid custom styles are skipped**: `repo_styles` lists the file and the reason; the loader does not guess or auto-fix. - **`collectFacts` dominates runtime** (git subprocesses + directory walk); the judgement logic itself is effectively free. - **SVG text metrics depend on system fonts** (Inter / Segoe UI / Microsoft YaHei), so widths vary slightly across machines. - npm package and plugin share the name: install `dsh-plugin-tailor`; the CLI command is `dsh-repo-tailor` (or `npx dsh-plugin-tailor`); release steps in [PUBLISHING.md](PUBLISHING.md). ## Security boundaries | Action | Boundary | |---|---| | Read | repository files only, plus `git status/log/tag`; the plugin makes no network requests | | Write (only with `apply: true`) | `README.md` / `README.en.md` / `assets/*.svg` / `assets/README.md` / `.tailor/baseline.json` | | Refuse | path traversal (`../`), hand-written README without `force`, existing assets without `force`, dirty worktree without `force` | | Never | execute repository scripts, run `npm install`, commit / push / publish, call an image model | | Dependencies | Node standard library only; zero runtime dependencies | ## FAQ **How is this different from a README template?** A template gives structure; this gives an 8-dimension audit, style-based generation, write protection and pre-release verification. Facts come from the repository; missing ones become TODOs, never invented numbers. **Will it overwrite my hand-written README?** No by default. Only files with a `generated-by` marker may be regenerated; otherwise `force` is required. **Does it need network access?** No. Badge images are loaded by GitHub from shields.io at render time; the plugin itself makes no requests. **Which languages and styles are supported?** `zh` / `en` pages; seven styles: `evidence`, `terminal`, `mobile`, `playful`, `product`, `platform`, `minimal`. Legacy ids still work. **Why review the README after a 100 score?** The score measures structure, evidence and brand presence — not prose quality or factual correctness. A human still reads it before publishing. **When will it be on npm?** It is published: `dsh-plugin-tailor@0.5.0` (`latest` points at the current version). ## Roadmap - [x] **v0.1** 8-dimension audit, P0–P2 planning, bilingual drafts, pre-release verification - [x] **v0.2** 12 original vector concepts, light/dark brand kit, brand sheet - [x] **v0.3** style-only presets, real CLI screenshots, re-recorded demo - [x] **v0.4** structured styles (JSON + schema), custom styles, `extends`, `style:init` - [x] **v0.5** visual: 12-file brand kit, contrast QA, 3 layout engines, 44 checks, construction motion - [ ] **v0.5** npm 0.5.0 publish + `dsh-plugins` hub listing - [ ] **v0.4** `--palette` variants (warm / high-contrast / mono / follow brand) - [ ] **v0.5** side-by-side style previews from a real repository - [ ] **v0.5** optional image-model illustration mode (PNG, SVG geometry stays the default) ## Ecosystem and listings - Install helper: [`dsh-plugin-resolver`](https://github.com/sakikoTGW/dsh-plugin-resolver) (installs the right version in one tool call) - Index: [`dsh-plugins`](https://github.com/sakikoTGW/dsh-plugins) (`catalog.json` is the source of truth) - Mobile adaptation: [`dsh-plugin-resolver-dshgo`](https://github.com/sakikoTGW/dsh-plugin-resolver-dshgo) - Listing status: GitHub Release ✅ · npm ⏳ · hub catalog ⏳ ## Feedback and security - Issues and ideas: - Security: use **Security → Advisories → Report a vulnerability** (private, see [SECURITY.md](SECURITY.md)) - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) · Release process: [PUBLISHING.md](PUBLISHING.md) ## License [MIT](LICENSE) _{Built for DeepSeek Harness · part of dsh-plugins · back to top ↑} _{If it saved you time, a ⭐ helps others find it.}