feat(create-readme): optional git clone, development block, remove telegram (#130)

* feat(create-readme): add include_clone, development_en/ru, remove telegram * docs(readme): update SKILL.md template and params for optional clone and development * docs(readme): add ADR-058, handoff, project map * docs(handoff): set PR number --------- Co-authored-by: opencode-agent <agent@opencode.local>
2026-07-29 20:50:52 +03:00 · 2026-07-29 20:50:52 +03:00 · 2a6d6eee2a
commit 2a6d6eee2a
parent c3efae6a30
5 changed files with 106 additions and 22 deletions
--- a/.opencode/skills/repo-readme/SKILL.md
+++ b/.opencode/skills/repo-readme/SKILL.md
@ -101,10 +101,11 @@ repos/{owner}/{repo}/contents/README.md` с base64-контентом и SHA.

 ### ⚡ Quick Start
 \`\`\`bash
-git clone https://github.com/slaid098/{repo_name}.git
+{git clone строка, если include_clone !== false}
 {quick_start}
 \`\`\`
 {access_url строка если передан — Access at {url}}
+{development_en блок, если передан — ### 🔧 Development + content}

 ---

@ -130,17 +131,17 @@ git clone https://github.com/slaid098/{repo_name}.git

 ### ⚡ Быстрый старт
 \`\`\`bash
-git clone https://github.com/slaid098/{repo_name}.git
+{git clone строка, если include_clone !== false}
 {quick_start}
 \`\`\`
 {access_url строка если передан — Доступ: {url}}
+{development_ru блок, если передан — ### 🔧 Разработка + content}

 ---

 ## 💬 Support and contacts / Поддержка и контакты

 👉 **[slaid098.dev/support](https://slaid098.dev/support)**
-{telegram строка, если передан}
 ```

 `validate` проверяет: наличие всех 4 пар EN/RU разделителей (summary +
@ -168,8 +169,25 @@ Quick Start (EN) и Быстрый старт (RU), language switcher `[English]
 - `features_en` / `features_ru` — массив `{ emoji, name, description }[]`.
 - `custom_sections_en` / `custom_sections_ru` — массивы
  `{ title, content }` (optional).
- `telegram` — username без `@` (optional).
 - `access_url` — URL для Access/Доступ строки после Quick Start bash-блока
  (optional). EN: `Access at {url}`, RU: `Доступ: {url}`. Omit if no web access.
+- `include_clone` — boolean (optional, default true). `false` убирает `git clone`
+  из Quick Start. Для userscript, web-app, npm-package.
+- `development_en` — raw markdown (optional). `### 🔧 Development` после EN
+  Quick Start, вне delimiter-тегов (не на slaid098.dev).
+- `development_ru` — raw markdown (optional). `### 🔧 Разработка` после RU
+  Быстрый старт, вне delimiter-тегов (не на slaid098.dev).
 - `repo` — `owner/name` для удалённой операции (optional).
 - `file_path` — локальный путь (default `README.md`).
+
+## 8. Кейс: userscript / web-app / npm-package
+
+Для репо без клонирования (userscript, web-app с demo URL, npm-package):
+
+- `include_clone: false` — убирает `git clone` из Quick Start
+- `quick_start` — команда установки (npm install, pip install, или ссылка на
+  установку userscript)
+- `access_url` — URL web-доступа (если есть)
+- `development_en` / `development_ru` — инструкции для разработчиков (как
+  собрать, как контрибьютить), рендерятся после Quick Start, вне
+  delimiter-тегов (не на slaid098.dev)
--- a/.opencode/tools/create-readme.ts
+++ b/.opencode/tools/create-readme.ts
@ -16,8 +16,10 @@ type CreateArgs = {
  quick_start: string
  features_en: Feature[]
  features_ru: Feature[]
-  telegram?: string
  access_url?: string
+  include_clone?: boolean
+  development_en?: string
+  development_ru?: string
  custom_sections_en?: CustomSection[]
  custom_sections_ru?: CustomSection[]
 }
@ -46,11 +48,14 @@ function generateReadme(args: CreateArgs): string {
  const customRu = (args.custom_sections_ru || [])
    .map((s) => `\n\n### ${s.title}\n${s.content}`)
    .join("")
-  const telegramLine = args.telegram
-    ? `\n💬 **Direct Telegram:** [@${args.telegram}](https://t.me/${args.telegram})`
-    : ""
  const accessLineEn = args.access_url ? `\nAccess at ${args.access_url}\n` : ""
  const accessLineRu = args.access_url ? `\nДоступ: ${args.access_url}\n` : ""
+  const developmentBlockEn = args.development_en
+    ? `\n\n### 🔧 Development\n${args.development_en}\n`
+    : ""
+  const developmentBlockRu = args.development_ru
+    ? `\n\n### 🔧 Разработка\n${args.development_ru}\n`
+    : ""

  return `# 🚀 ${args.repo_name}
 > ${args.tagline}
@ -75,9 +80,8 @@ ${renderFeaturesTable(args.features_en, false)}

 ### ⚡ Quick Start
 \`\`\`bash
-git clone https://github.com/slaid098/${args.repo_name}.git
-${args.quick_start}
-\`\`\`${accessLineEn}
+${args.include_clone !== false ? `git clone https://github.com/slaid098/${args.repo_name}.git\n` : ""}${args.quick_start}
+\`\`\`${accessLineEn}${developmentBlockEn}
 ---

 ## 🇷🇺 Русский
@ -96,14 +100,13 @@ ${renderFeaturesTable(args.features_ru, true)}

 ### ⚡ Быстрый старт
 \`\`\`bash
-git clone https://github.com/slaid098/${args.repo_name}.git
-${args.quick_start}
-\`\`\`${accessLineRu}
+${args.include_clone !== false ? `git clone https://github.com/slaid098/${args.repo_name}.git\n` : ""}${args.quick_start}
+\`\`\`${accessLineRu}${developmentBlockRu}
 ---

 ## 💬 Support and contacts / Поддержка и контакты

-👉 **[slaid098.dev/support](https://slaid098.dev/support)**${telegramLine}
+👉 **[slaid098.dev/support](https://slaid098.dev/support)**
 `
 }

@ -212,10 +215,6 @@ export default tool({
      )
      .optional()
      .describe("Array of features for RU table. Each: { emoji, name, description }. Required for create mode."),
-    telegram: tool.schema
-      .string()
-      .optional()
-      .describe("Telegram username without @. Optional; adds Direct Telegram line to Support section."),
    custom_sections_en: tool.schema
      .array(
        tool.schema.object({
@ -246,6 +245,18 @@ export default tool({
      .string()
      .optional()
      .describe("Optional URL for Access/Доступ line after Quick Start bash block. EN: 'Access at {url}', RU: 'Доступ: {url}'. Omit if no web access."),
+    include_clone: tool.schema
+      .boolean()
+      .optional()
+      .describe("If false, omits 'git clone' from Quick Start bash block. Default true (backward compatible). Set false for userscripts, web apps, npm packages."),
+    development_en: tool.schema
+      .string()
+      .optional()
+      .describe("Raw markdown for ### 🔧 Development section after EN Quick Start (outside delimiters, not shown on slaid098.dev). Omit if no dev section needed."),
+    development_ru: tool.schema
+      .string()
+      .optional()
+      .describe("Raw markdown for ### 🔧 Разработка section after RU Быстрый старт (outside delimiters, not shown on slaid098.dev). Omit if no dev section needed."),
  },
  async execute(args, context) {
    try {
@ -279,8 +290,10 @@ export default tool({
          quick_start: args.quick_start!,
          features_en: args.features_en!,
          features_ru: args.features_ru!,
-          telegram: args.telegram,
          access_url: args.access_url,
+          include_clone: args.include_clone,
+          development_en: args.development_en,
+          development_ru: args.development_ru,
          custom_sections_en: args.custom_sections_en,
          custom_sections_ru: args.custom_sections_ru,
        })
--- a/docs/decisions/058-pr-130-readme-optional-clone-and-development.md
+++ b/docs/decisions/058-pr-130-readme-optional-clone-and-development.md
@ -0,0 +1,33 @@
+# ADR-058: README — optional git clone, Development block, remove telegram
+
+## Статус
+Accepted (2026-07-29)
+
+## Контекст
+
+Тулза `create-readme` имела 3 проблемы:
+
+- **`git clone https://github.com/slaid098/{repo}.git` захардкожен** в Quick Start (стр. 78 EN, 99 RU). Не отключается — все README получают clone-строку, даже userscript / web-app / npm-package, где клонирование не имеет смысла.
+- **`custom_sections_en/ru` рендерятся ДО Quick Start** (стр. 74, 95) — не подходит для блока «Разработка», который логичен после Quick Start.
+- **Параметр `telegram`** — мёртвый: 0 call-sites, 0 тестов, валидатор не проверяет, собственный README репо без него. Ссылки `slaid098.dev/support` достаточно.
+
+Валидатор `validateReadme()` не проверяет `git clone`, `telegram`, `custom_sections` — изменения не сломают валидацию.
+
+## Решение
+
+3 новых optional-параметра + hard removal `telegram` (backward compatible):
+
+- **`include_clone?: boolean`** (default `true`) — `false` убирает `git clone` из Quick Start bash-блока. `undefined` → включает. Прецедент: `access_url` (ADR-052) — тот же паттерн «optional → условный рендер».
+- **`development_en?: string`** — raw markdown, рендерит `### 🔧 Development` после EN Quick Start, вне delimiter-тегов (не на slaid098.dev). Для инструкций разработчикам.
+- **`development_ru?: string`** — raw markdown, рендерит `### 🔧 Разработка` после RU Быстрый старт, вне delimiter-тегов.
+- **`telegram`** — hard removal: убран из `CreateArgs` type, рендера, JSON schema, pass-through. Support-секция: только `👉 **[slaid098.dev/support]...**`.
+- **Валидатор** — без изменений.
+
+Development-блок вне delimiter-тегов: разделители определяют только то, что парсер slaid098.dev вытягивает для витрины. Development-блок виден только на GitHub — правильно для доп. секции «для разработчиков».
+
+## Альтернативы
+
+- **`include_clone` как обязательный параметр** — отвергнуто: не все репо хотят убрать clone (большинству нужен). Default `true` → backward compatible.
+- **Development через `custom_sections`** — отвергнуто: `custom_sections` рендерятся ДО Quick Start. Development логичен после. Новый параметр → правильная позиция.
+- **Deprecation `telegram` (оставить параметр, игнорировать)** — отвергнуто: мёртвый код вводит в заблуждение. 0 call-sites → hard removal безопасен.
+- **Валидатор проверяет development-блок** — отвергнуто: блок optional, валидатор не должен требовать optional-секции.
--- a/docs/handoff/pr-130-readme-optional-clone-and-development.md
+++ b/docs/handoff/pr-130-readme-optional-clone-and-development.md
@ -0,0 +1,20 @@
+---
+pr: 130
+title: feat(create-readme): optional git clone, development block, remove telegram
+---
+
+## Что сделано
+- 3 новых optional-параметра: `include_clone` (default true, backward compatible), `development_en`, `development_ru` — raw markdown, `### 🔧 Development` / `### 🔧 Разработка` после Quick Start, вне delimiter-тегов
+- Hard removal `telegram` — убран из CreateArgs type, рендера (telegramLine), шаблона Support, JSON schema, pass-through. Support: только `slaid098.dev/support`
+- Валидатор `validateReadme()` — без изменений
+- SKILL.md §5 шаблон + §7 параметры обновлены, +§8 userscript-кейс
+- ADR-058 создан
+
+## Почему
+`git clone slaid098/{repo}` захардкожен — не отключался для userscript/web-app/npm-package. `custom_sections` рендерились до Quick Start — не подходили для блока «Разработка». `telegram` — мёртвый параметр (0 call-sites, 0 тестов, валидатор не проверяет).
+
+## Pending
+—
+
+## Watch out
+—
--- a/docs/project-map/README.md
+++ b/docs/project-map/README.md
@ -36,7 +36,7 @@ opencode-config/
 │   │   ├── python-development/SKILL.md # Python dev patterns
 │   │   ├── release/SKILL.md        # Tag + GitHub Release
 │   │   ├── repo-init/SKILL.md      # New repository bootstrap
-│   │   ├── repo-readme/SKILL.md    # Standardized README generation (create-readme tool: create vs validate, bilingual Why/What + Features table, GitHub metadata) — PR#112, PR#116, PR#118
+│   │   ├── repo-readme/SKILL.md    # Standardized README generation (create-readme tool: create vs validate, bilingual Why/What + Features table, GitHub metadata) — PR#112, PR#116, PR#118, PR#130
 │   │   ├── tunnel/SKILL.md         # Cloudflare tunnel toggle (tool `tunnel()`: 1-й вызов start, 2-й stop) — PR#63 (восстановлен, удалён в PR#42)
 │   │   ├── run-tests/SKILL.md      # Test runner guide
 │   │   └── spec/SKILL.md           # 9-phase spec generation
@ -45,7 +45,7 @@ opencode-config/
 │   │   ├── commit.ts               # commit tool wrapper (1 arg message, validates format+staged) — PR#38
 │   │   ├── create-issue.ts         # create-issue tool wrapper (3 args, validates format+labels; optional repo?: string) — PR#38, PR#65
 │   │   ├── create-pr.ts            # create-pr tool wrapper (3 args, validates format+Closes #N; optional repo?: string) — PR#38, PR#65
-│   │   ├── create-readme.ts        # create-readme tool (TS plugin, modes: create/validate; standardized bilingual README with features table, access_url, RU heading 'Русский' + anchor checks, 4 delimiter pairs for slaid098.dev; local fs + remote gh api) — PR#112, PR#116, PR#118
+│   │   ├── create-readme.ts        # create-readme tool (TS plugin, modes: create/validate; standardized bilingual README with features table, include_clone/development_en/ru optional params, RU heading 'Русский' + anchor checks, 4 delimiter pairs for slaid098.dev; local fs + remote gh api) — PR#112, PR#116, PR#118, PR#130
 │   │   ├── merge-pr.ts            # merge-pr tool wrapper (orchestrator-safe gh pr merge; optional repo?: string) — PR#30, PR#65
 │   │   ├── memory-access.ts        # memory-access tool (bump frontmatter last_accessed/access_count, regex replace, atomic write tmp+rename) — PR#101
 │   │   ├── memory-doctor.ts        # memory-doctor tool (read-only diagnostics: rg {lines, rgWorks} G9, allowSystemFallback:true G5, arch-mismatch detection G2, npm-missing hint G3; markdown ✅/❌ report) — PR#101, PR#124