@sumrco/cli 0.1.0

package/ai/modules/playbook/resources/authoring/overview.md

@@ -0,0 +1,213 @@
+---
+name: playbook-authoring
+title: Playbook Authoring
+description: "How to write canonical SUMR Playbook docs: frontmatter schema, references, extraction markers, and authoring checklist. Use when creating or editing agnostic Playbook Markdown."
+tags: [authoring, docs, markdown]
+---
+
+## When to Use
+
+- Creating a new `.md` file anywhere under `{{PLAYBOOK_PATH}}/`.
+- Editing or restructuring existing docs.
+- Reviewing a doc for schema or structure compliance.
+- Deciding whether to split a long doc into main + references.
+- Explaining workflow, lifecycle, approval, or handoff flows.
+
+## Core Principle: Layered Docs
+
+Keep main docs concise and high-signal. Push deep detail into `category: reference` files in the same folder.
+
+| Size | Action |
+|------|--------|
+| ~60-120 lines | Ideal for a main doc |
+| ~180 lines | Soft cap — consider splitting |
+| 500+ lines | Hard cap — must split |
+
+Reference files attach automatically by **folder proximity** — no linking field needed. The main doc and its references live in the same folder.
+
+## Splitting Existing Docs
+
+Before splitting a file, decide the owning context folder. Do not just create another peer `.md` file in a broad folder when the split content is really its own topic.
+
+Use this flow:
+
+1. Analyze context: identify the domain, the current folder owner, and whether the file is a main topic or supporting detail.
+2. Choose placement:
+   - Same-folder `category: reference` when the extracted content only supports the current `overview.md`.
+   - Child folder with `overview.md` when the extracted content is a substantial standalone subtopic.
+   - Child folder with `overview.md` when the split creates two or more files for the same microconcept. The child overview is the invoker/entry point; its sibling files are references.
+3. Split content: keep concise rules and navigation in `overview.md`; move deep examples, tables, and edge cases to references.
+4. Check naming: kebab-case filenames, stable `name` fields, `label`/`when`/`order` for references, and no generated prefixes in source docs.
+5. Run `sumr playbook validate --source docs`.
+6. Run `sumr playbook sync --source docs --dry-run --json`; run normal sync only after the preview is clean.
+
+Example: if `{{PLAYBOOK_PATH}}/standards/testing/playwright.md` is a full Playwright standard, split it into its own topic folder:
+
+```text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+└── playwright/
+    ├── overview.md
+    ├── locators.md      (category: reference, order: 10)
+    └── fixtures.md      (category: reference, order: 20)
+```
+
+If the Playwright content is only supporting detail for the general testing standard, keep it beside the testing overview:
+
+```text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+└── playwright.md        (category: reference, order: 30)
+```
+
+If the split creates a Playwright CLI topic plus its own command catalog, promote the microconcept to a child folder:
+
+```text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+└── playwright-cli/
+    ├── overview.md            (main topic: Playwright CLI)
+    └── command-catalog.md     (category: reference, order: 10)
+```
+
+Avoid this shape when both files belong to the same microconcept:
+
+```text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+├── playwright-cli.md
+└── playwright-cli-command-catalog.md
+```
+
+## Frontmatter (All Files)
+
+Every `.md` file under `{{PLAYBOOK_PATH}}/` must have at minimum `name`, `title`, and `description`. Always quote `description` in double quotes.
+
+```yaml
+---
+name: unique-kebab-identifier
+title: Human Readable Title
+description: "What this doc covers. Use when doing X."
+---
+```
+
+See **Frontmatter** for the full schema, categories, and required fields per category.
+
+## Reference Files
+
+To make a file a reference (supporting detail for a main doc):
+
+1. Set `category: reference`
+2. Add `title`, `label`, `when`, `order` to frontmatter
+3. Remove the `## When to Use` section from the body (`when` field replaces it)
+4. Keep the file in the **same folder** as the main doc
+
+```yaml
+---
+category: reference
+name: typescript-imports
+title: Import Organization
+description: "Biome distance-based import ordering, type imports, and #region rules."
+label: Imports
+when: Organizing imports, reviewing import order, adding new imports
+order: 20
+---
+```
+
+> [!CAUTION]
+> Do not create a `references/` subfolder. Reference files live next to the main doc in the same directory. Do not add a `references:` frontmatter field — attachment is automatic.
+
+## Folder Organization
+
+Recommended top-level folders under `{{PLAYBOOK_PATH}}/`:
+
+| Folder | Purpose |
+|--------|---------|
+| `architecture/` | System design and diagrams |
+| `standards/` | Domain rules — also: `guidelines/`, `playbook/`, `handbook/`, `conventions/`, `practices/` |
+| `team-members/` | Orchestrators and cross-domain AI agents |
+| `workflows/` | User-invoked AI workflows |
+| `lifecycle/` | Lifecycle automation scripts |
+| `processes/` | Workflows and runbooks |
+
+**Team-member placement:** Put orchestrators and generalist agents in `team-members/`. Put domain-specific workers (e.g. `backend-worker.tm.md`) inside their domain folder, beside the standards they follow.
+
+See **Folder Structure** for naming alternatives, placement rules, and a full structure example.
+
+## Extraction Markers
+
+Wrap dedicated examples sections with markers so they can be consumed separately:
+
+```markdown
+<!-- extract:examples -->
+## Examples
+
+\`\`\`text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+└── playwright/
+    ├── overview.md
+    ├── locators.md
+    └── fixtures.md
+\`\`\`
+<!-- /extract:examples -->
+```
+
+**When to extract:** Dedicated `## Examples` sections, sample templates, and long boilerplate blocks. Skill-folder channels remove the block from `SKILL.md`, write it to `examples.md`, and add an `## Additional resources` link.
+
+**Keep in main doc:** Short inline snippets, file structure trees, ASCII diagrams, schema outlines that are core to the instructions.
+
+See **Extraction** for the full code-block classification table.
+
+## Flow Documentation
+
+Use a compact arrow flow for simple workflows:
+
+```text
+🕐 intake -> [researcher] -> 📝 draft -> ⏸ HUMAN APPROVES -> ✅ ready -> [implementer] -> review -> done
+```
+
+Use Mermaid plus transition rules when the flow branches, loops, or has failure paths.
+
+See **Flows** for arrow notation, Mermaid patterns, approval gates, and when to avoid diagrams.
+
+## Descriptions
+
+Write descriptions in **third person** with **what + when** and **specific key terms**. Avoid vague labels ("overview", "best practices") and meta phrasing ("this document describes...").
+
+```yaml
+# Bad
+description: "TypeScript conventions."
+
+# Good
+description: "Naming, import ordering, type discipline, and Biome rules for the SUMR CLI. Use when writing or reviewing TypeScript."
+```
+
+See **Descriptions** for rules, examples, and YAML safety (when to quote).
+
+## Placeholders
+
+Use `{{PLAYBOOK_PATH}}` anywhere in a topic body to reference the configured Playbook source directory. At sync time the token is replaced with the first `playbook.sources` entry from `sumr.yaml` (e.g. `docs`).
+
+```markdown
+See `{{PLAYBOOK_PATH}}/standards/backend/overview.md` for the backend rules.
+```
+
+**When to use:** Any time a doc needs to reference another file in the docs tree without hard-coding the folder name. Frontmatter fields are not substituted — only the body.
+
+## Checklist
+
+Before committing any `.md` file under `{{PLAYBOOK_PATH}}/`:
+
+- [ ] `name`, `title`, and `description` present
+- [ ] `description` is in double quotes, third person, specific
+- [ ] Main how-to docs have `## When to Use` section
+- [ ] Reference files have `title`, `label`, `when`, `order` — and no `## When to Use` in body
+- [ ] Dedicated examples, samples, and templates wrapped with `<!-- extract:examples -->`; no standalone examples section left unwrapped
+- [ ] Workflow and lifecycle docs use a compact arrow flow or Mermaid diagram when state transitions matter
+- [ ] No `references:` frontmatter field
+- [ ] No `## References` or `## Related` sections added manually
+- [ ] Doc is under the soft cap (~180 lines); if over, split to references
+- [ ] `{{PLAYBOOK_PATH}}` used instead of hard-coded `docs/` or similar paths in body
+
+See **Markdown** for formatting rules (headings, callouts, code blocks, anti-patterns).

package/ai/modules/playbook/resources/team-members/playbook-technical-writer.tm.md

@@ -0,0 +1,31 @@
+---
+category: team-member
+name: playbook-technical-writer
+title: Playbook Technical Writer
+description: "A SUMR Playbook authoring specialist. Use when drafting, reviewing, or restructuring canonical Playbook Markdown and AI resource docs."
+
+# Codex CLI agent profile options
+codex:
+  sandbox_mode: read-only
+---
+
+# Playbook Technical Writer
+
+You are responsible for producing canonical SUMR Playbook Markdown that can be rendered into multiple AI channels.
+
+Apply **playbook-authoring** before writing or editing Playbook docs.
+
+## Responsibilities
+
+- Write concise main topics with high-signal instructions.
+- Before splitting, decide the owning context folder: same-folder references for supporting detail, child `overview.md` topic folders for standalone subtopics.
+- If a split creates multiple files for one microconcept, promote it to a child folder. The child `overview.md` is the invoker/entry point; sibling files are references.
+- Move deep detail into `category: reference` files beside the `overview.md` they support.
+- Review every fenced code block before extraction. Wrap dedicated examples, samples, and templates with `<!-- extract:examples -->`; keep short core snippets, file trees, and marker syntax examples inline.
+- Keep frontmatter complete, stable, and tool-agnostic.
+- Use `category: team-member`, `workflow`, or `lifecycle` only when the doc represents an AI resource rather than a normal skill/topic. Treat `hook` as a legacy alias for `lifecycle`.
+- Avoid editing generated channel output directly.
+
+## Output
+
+Return the proposed Markdown content or a focused review with specific schema, structure, and wording fixes.

package/ai/modules/playbook/sumr.module.yaml

@@ -0,0 +1,47 @@
+apiVersion: sumr.dev/v1
+kind: CliModule
+metadata:
+  name: playbook
+  package: "@sumrco/cli"
+  description: Sync team standards into AI tools (Claude, Cursor, Codex, VS Code)
+  owners:
+    - team: "@sumr-org/playbook-team"
+  tags:
+    - docs
+    - authoring
+    - ai-tools
+spec:
+  visibility: private
+  group: modules
+  targets:
+    contractVersion: ^1.0.0
+    bunVersion: ">=1.1.0"
+  commands:
+    - name: config
+      summary: Manage playbook configuration in sumr.yaml
+      visibility: private
+    - name: sync
+      summary: Render Playbook Markdown into AI tool channels
+      visibility: private
+    - name: validate
+      summary: Check Playbook docs for errors without writing files
+      visibility: private
+    - name: status
+      summary: Show Playbook status, sources, and counts
+      visibility: private
+    - name: add
+      summary: Scaffold a new Playbook doc with correct frontmatter
+      visibility: private
+    - name: clean
+      summary: Remove all rendered Playbook outputs from this repo
+      visibility: private
+    - name: authoring
+      summary: Print the canonical Playbook Markdown authoring contract
+      visibility: private
+  exports:
+    resources:
+      - ./resources
+    binaries: []
+  flags:
+    experimental: false
+    deprecated: null

package/ai/registry.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "variant": "public",
+  "modules": [
+    {
+      "label": "kontract",
+      "path": "./ai/modules/kontract/resources"
+    },
+    {
+      "label": "mission",
+      "path": "./ai/modules/mission/resources"
+    },
+    {
+      "label": "playbook",
+      "path": "./ai/modules/playbook/resources"
+    }
+  ]
+}

package/bin/_sumr

@@ -0,0 +1,4 @@
+#!/bin/bash
+_sumr_cli "$@"
+_sumr_rc=$?
+return $_sumr_rc 2>/dev/null || exit $_sumr_rc

package/bin/sumr

@@ -0,0 +1,7 @@
+#!/bin/bash
+if command -v _sumr_cli >/dev/null 2>&1; then
+  exec _sumr_cli "$@"
+fi
+
+echo "sumr: _sumr_cli not found. Reinstall SUMR CLI." >&2
+exit 1