@sumrco/cli 0.1.0

package/ai/modules/playbook/resources/authoring/extraction.rf.md

@@ -0,0 +1,81 @@
+---
+category: reference
+name: playbook-authoring-extraction
+title: Content Extraction
+description: "extract:examples marker syntax, code block classification, and size guidelines for SUMR docs."
+label: Extraction
+when: Adding examples sections to a doc, deciding whether to extract a code block, checking size limits, classifying a fenced code block
+order: 20
+---
+
+# Content Extraction
+
+## Marker Syntax
+
+Wrap dedicated examples sections with extraction markers:
+
+```markdown
+<!-- extract:examples -->
+## Examples
+
+\`\`\`text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+└── playwright/
+    ├── overview.md
+    ├── locators.md
+    └── fixtures.md
+\`\`\`
+<!-- /extract:examples -->
+```
+
+Skill-folder channels remove the extracted block from `SKILL.md`, write it to `examples.md`, and add an `## Additional resources` link. Flat-file channels keep extracted content inline because they cannot attach supporting files.
+
+Multiple `<!-- extract:examples -->` blocks in the same file are **merged** into one output. Each block must be self-contained — include any intro or title inside the marker, not outside it.
+
+> [!CAUTION]
+> Do not leave an intro sentence outside the marker with nothing below it:
+> ```markdown
+> Use the following pattern:       ← orphaned intro — BAD
+> <!-- extract:examples -->
+> \`\`\`ts
+> const roleByStatus = { draft: 'writer', ready: 'reviewer' } as const;
+> \`\`\`
+> <!-- /extract:examples -->
+> ```
+> Put the intro inside the block so the generated file is self-contained.
+
+## Mandatory Default
+
+In any file, if you create a dedicated `## Examples` section or equivalent sample/template section, wrap the whole section with `<!-- extract:examples -->` unless the snippet is truly inline and central to the instruction flow.
+
+Do not leave standalone examples sections unwrapped. Do not wrap marker examples shown inside fenced code blocks; the renderer treats those as literal documentation and does not extract them.
+
+## Code Block Classification
+
+Before wrapping any `` ``` `` block, classify it:
+
+| Purpose | Description | Action |
+|---------|-------------|--------|
+| **Example** | Demonstrates a usage pattern or flow | `extract:examples` |
+| **Sample** | Minimal runnable snippet | `extract:examples` |
+| **Template** | Boilerplate to copy | `extract:examples` |
+| **Config** | Short config snippet | Keep inline |
+| **Config** | Long config block | `extract:examples` |
+| **File structure / schema** | Directory tree, schema outline | Keep in main doc |
+| **ASCII diagram** | Decision tree, flow diagram | Keep in main doc |
+| **Inline snippet** | Core instruction, short 2-5 line example | Keep in main doc |
+
+**Default:** Short inline snippets, file structure trees, and core-instruction diagrams stay in the main doc without markers. Use `extract:examples` only when the block is supplementary and long enough to warrant a separate reference.
+
+Before wrapping any block, ask whether the generated `SKILL.md` should still be complete without the block. If yes, extract it. If no, keep it inline.
+
+## Size Guidelines
+
+| Threshold | Action |
+|-----------|--------|
+| ~60-120 lines | Ideal main doc size |
+| ~180 lines | Soft cap — consider splitting to references |
+| 500 lines | Hard cap — must split |
+
+When a main doc exceeds the soft cap, move detailed sections (deep examples, exhaustive rule tables, long walkthroughs) into `category: reference` files in the same folder.

package/ai/modules/playbook/resources/authoring/flows.rf.md

@@ -0,0 +1,55 @@
+---
+category: reference
+name: playbook-authoring-flows
+title: Flow Documentation
+description: "Flow documentation patterns for Playbook docs, including compact arrow flows, human approval gates, Mermaid diagrams, and transition rules."
+label: Flows
+when: Writing workflows, documenting lifecycle states, explaining approval gates, choosing between arrow flows and Mermaid diagrams
+order: 55
+---
+
+# Flow Documentation
+
+Use flow notation when a doc needs to show order, responsibility, gates, or allowed state transitions.
+
+## Simple Flow
+
+Use one compact arrow flow when the process is mostly linear:
+
+```text
+🕐 intake -> [researcher] -> 📝 draft -> ⏸ HUMAN APPROVES -> ✅ ready -> [implementer] -> review -> done
+```
+
+Rules:
+
+- Keep state names short and concrete.
+- Use `[role-or-agent]` for the actor responsible for a transition.
+- Label human decision gates explicitly, for example `⏸ HUMAN APPROVES`.
+- Keep emojis optional and functional; use them for state scanning, not decoration.
+- Put the flow near the top of workflow or lifecycle docs before detailed steps.
+
+## Complex Flow
+
+Use Mermaid when the process branches, loops, or has failure paths:
+
+```mermaid
+flowchart LR
+  intake["intake"] --> research["researcher"]
+  research --> draft["draft plan"]
+  draft --> approval{"Human approves?"}
+  approval -->|yes| ready["ready"]
+  approval -->|changes requested| draft
+  ready --> implement["implementer"]
+  implement --> review["review"]
+  review --> done["done"]
+```
+
+Add short transition rules below the diagram when an AI must know what is forbidden:
+
+- Do not enter implementation until the approval gate is satisfied.
+- If review finds missing context, return to draft instead of continuing.
+- If a blocker appears, stop and record the blocker instead of guessing.
+
+## When to Avoid Diagrams
+
+Avoid diagrams when a numbered list is clearer. If there is no meaningful state change, gate, or actor handoff, write concise steps instead.

package/ai/modules/playbook/resources/authoring/folder-structure.rf.md

@@ -0,0 +1,148 @@
+---
+category: reference
+name: playbook-authoring-folder-structure
+title: Folder Structure
+description: "Recommended Playbook folder layout, top-level naming, team-member placement patterns (root vs domain-embedded), and standards folder naming alternatives."
+label: Folder Structure
+when: Planning a docs folder, naming a standards folder, deciding where to put a team-member doc, restructuring an existing docs tree
+order: 70
+---
+
+# Folder Structure
+
+## Recommended Top-Level Folders
+
+Start with these root folders under `{{PLAYBOOK_PATH}}/` and add more as the codebase grows.
+
+| Folder | Purpose |
+|--------|---------|
+| `architecture/` | System design, diagrams, ADRs, infrastructure topology |
+| `standards/` | Domain-specific technical rules (backend, frontend, security…) |
+| `team-members/` | Orchestrators and cross-domain AI agents |
+| `workflows/` | User-invoked AI workflows (`.wf.md` files), such as issue triage or UI review |
+| `lifecycle/` | Lifecycle automation scripts (`.lc.md` files) that guard or enrich AI sessions |
+| `processes/` | Workflows, release checklists, incident runbooks, repeatable procedures |
+
+Keep `team-members/`, `workflows/`, and `lifecycle/` separate from `standards/` when they are repo-wide — they generate different output types and have different audiences.
+
+## Full Structure Example
+
+```
+{{PLAYBOOK_PATH}}/
+├── architecture/          ← system design, diagrams, ADRs
+│   ├── system/
+│   │   └── overview.md
+│   └── auth/
+│       ├── overview.md
+│       └── session-model.md   (category: reference, order: 10)
+├── standards/             ← domain-specific rules
+│   ├── backend/
+│   │   ├── overview.md
+│   │   ├── testing.md         (category: reference, order: 20)
+│   │   └── backend-worker.tm.md
+│   ├── frontend/
+│   │   ├── overview.md
+│   │   └── frontend-worker.tm.md
+│   └── security/
+│       └── overview.md
+├── team-members/          ← orchestrators and cross-domain agents
+│   ├── orchestrator.tm.md
+│   └── code-audit-runner.tm.md
+├── workflows/             ← user-invoked AI workflows
+│   └── ui-review.wf.md
+└── lifecycle/             ← optional lifecycle automations
+    └── session-start.lc.md
+```
+
+## Topic Folder Decision
+
+Every split starts by choosing the context owner.
+
+Use a same-folder reference when the new file only supports the current topic:
+
+```text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+└── playwright.md        (category: reference, order: 30)
+```
+
+Use a child topic folder when the split content is a standalone topic with its own rules and references:
+
+```text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+└── playwright/
+    ├── overview.md
+    ├── locators.md      (category: reference, order: 10)
+    └── fixtures.md      (category: reference, order: 20)
+```
+
+Decision rules:
+
+- If the parent folder is broad, avoid piling up many peer main docs. Create child topic folders.
+- If a file is really supporting detail for the current `overview.md`, keep it as a same-folder `category: reference`.
+- If a file belongs to a different domain, move it to that domain instead of keeping it near the source file.
+- If a folder is missing `overview.md`, create the entry point before adding references.
+
+Split flow:
+
+1. Analyze context.
+2. Choose same-folder reference or child topic folder.
+3. Split content into concise `overview.md` plus references.
+4. Check naming and frontmatter.
+5. Run `sumr playbook validate --source docs`.
+6. Run `sumr playbook sync --source docs --dry-run --json`.
+
+## Team-Member Placement
+
+Team-members can live in two places. Use the pattern that best fits the agent's scope.
+
+### Root folder — orchestrators and generalist agents
+
+Place agents that coordinate multiple domains or have no natural domain home in `{{PLAYBOOK_PATH}}/team-members/`:
+
+```
+{{PLAYBOOK_PATH}}/
+├── team-members/
+│   ├── orchestrator.tm.md       ← drives multi-domain tasks
+│   ├── code-audit-runner.tm.md  ← repo-wide quality agent
+│   └── quality-lead.tm.md       ← gate-keeper, not domain-specific
+└── standards/
+    └── backend/
+        └── overview.md
+```
+
+### Domain-embedded — domain-specific workers
+
+Place agents that are tightly coupled to one domain's standards beside the docs they follow:
+
+```
+{{PLAYBOOK_PATH}}/
+├── standards/
+│   ├── backend/
+│   │   ├── overview.md
+│   │   ├── testing.md
+│   │   └── backend-worker.tm.md   ← lives beside the standards it follows
+│   └── frontend/
+│       ├── overview.md
+│       └── frontend-worker.tm.md  ← updated when frontend docs change
+└── team-members/
+    └── orchestrator.tm.md         ← cross-domain, stays at root
+```
+
+**Rule of thumb:** If removing an agent breaks only one domain, embed it there. If removing it would affect the whole repo, put it in `team-members/`.
+
+## Standards Folder Naming
+
+The folder that holds technical rules can use any of these names. Pick one that fits your team's vocabulary and stick with it.
+
+| Name | Best when… |
+|------|-----------|
+| `standards/` | Rules are hard constraints the team must follow |
+| `guidelines/` | Recommendations where judgment calls are allowed |
+| `playbook/` | Mixing process, culture, and technical conventions in one place |
+| `handbook/` | Including onboarding, culture, and practices alongside tech rules |
+| `conventions/` | The primary focus is naming and structural consistency |
+| `practices/` | Framing rules as lived engineering habits rather than mandates |
+
+> All names work equally well with SUMR — the folder name is just a path segment. Only the frontmatter `name` field determines the generated skill identity.

package/ai/modules/playbook/resources/authoring/frontmatter.rf.md

@@ -0,0 +1,251 @@
+---
+category: reference
+name: playbook-authoring-frontmatter
+title: Frontmatter Schema
+description: "Required and optional frontmatter fields, category values, and per-category validation rules for SUMR Playbook docs."
+label: Frontmatter
+when: Adding frontmatter to a new doc, checking which fields are required, converting a file to a reference, choosing a category value
+order: 10
+---
+
+# Frontmatter Schema
+
+## Required Fields (All Files)
+
+These fields are mandatory on every canonical Playbook `.md` file:
+
+| Field | Rule |
+|-------|------|
+| `name` | Unique kebab-case identifier across all docs |
+| `title` | Human-readable display name |
+| `description` | Third-person, what + when, specific key terms. Always in double quotes. |
+
+```yaml
+---
+name: testing
+title: Testing Guidelines
+description: "Test isolation rules, temp dir pattern, and integration test approach for the SUMR CLI."
+---
+```
+
+## Categories
+
+| Value | Purpose | Required extra fields | AI output |
+|-------|---------|----------------------|-----------|
+| *(omitted)* | General how-to / main doc | — | Skill file |
+| `reference` | Supporting detail for a main doc | `title`, `label`, `when`, `order` | Skill file (attached) |
+| `team-member` | Tool-agnostic delegated role | — | Native agent/subagent profiles |
+| `workflow` | User-invoked AI workflow | — | Claude slash command |
+| `lifecycle` | Lifecycle automation script | `event` | Hook script + `hooks.json` |
+| `hook` | Legacy alias for `lifecycle` | `event` | Hook script + `hooks.json` |
+
+### Optional Fields for Any Category
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `tags` | `string[]` | Freeform labels for human scanning only |
+| `modelTier` | `reasoning \| coding \| fast` | Preferred model tier for team-member/agent topics |
+| `channels` | object | Legacy-compatible per-channel overrides. Prefer top-level native channel blocks in new docs. |
+| `target` | string | Output filename override (basename only, extension inferred) |
+
+### `modelTier` Values
+
+| Value | Codex model |
+|-------|-------------|
+| `reasoning` | `o4-mini` |
+| `coding` | `gpt-4.1` |
+| `fast` | `gpt-4o-mini` |
+
+```yaml
+modelTier: coding
+```
+
+An explicit `codex.model` override always takes precedence over `modelTier`.
+
+## Native Channel Props
+
+Use top-level channel blocks for tool-specific features instead of promoting every vendor option into the SUMR schema. Add a short comment above each block so humans can scan what tool the block configures.
+
+Comments are authoring guidance only. Playbook does not parse or require them.
+
+```yaml
+---
+category: team-member
+name: codebase-reviewer
+title: Codebase Reviewer
+description: "Reviews code for correctness, security, behavior regressions, and missing tests."
+modelTier: reasoning
+
+# Codex CLI agent profile options
+codex:
+  sandbox_mode: read-only
+  model_reasoning_effort: high
+
+# Claude Code subagent options
+claude:
+  tools: Read, Grep, Glob
+  mode: subagent
+
+# Cursor project rule options
+cursor:
+  globs: [src/**/*.ts, tests/**/*.ts]
+
+# GitHub Copilot custom agent options
+copilot:
+  tools: read
+
+# Gemini CLI subagent options
+gemini:
+  kind: codebase_investigator
+  max_turns: 20
+
+# OpenCode agent options
+opencode:
+  mode: subagent
+---
+```
+
+`channels:` remains supported as a legacy-compatible alias. If both shapes set the same channel property, the top-level channel block wins.
+
+## Team-Member Terminology Placeholder
+
+Canonical source docs must use `{{TEAM-MEMBER}}` when prose means a generated delegated role. Do not hardcode `agent` or `subagent` in reusable source prose unless you are describing a specific vendor field such as `mode: subagent`.
+
+Playbook replaces `{{TEAM-MEMBER}}` at render time because AI tools use different native names for the same SUMR concept:
+
+| Channel | Rendered label |
+| --- | --- |
+| Claude Code | `Subagent` |
+| Codex CLI | `Subagent` |
+| Cursor | `Subagent` |
+| Gemini CLI | `Subagent` |
+| GitHub Copilot | `Agent` |
+| OpenCode | `Agent` |
+
+Use the placeholder in descriptions and body text:
+
+```yaml
+description: "{{TEAM-MEMBER}} that reviews source code. Use after implementation."
+```
+
+```markdown
+Delegate directly to the **codebase-reviewer** {{TEAM-MEMBER}}.
+```
+
+### Team-Member Role Archetypes
+
+Use these as naming and writing guidance, not as a required `roleType` field:
+
+| Archetype | Use when |
+|---|---|
+| `orchestrator` | Coordinating mission state and handoffs |
+| `product-owner` | Clarifying problem, scope, and acceptance criteria |
+| `researcher` | Exploring code/docs and reporting evidence |
+| `planner` | Turning validated intent into an implementation plan |
+| `implementer` | Editing code according to an approved plan |
+| `reviewer` | Checking correctness, risks, and test gaps |
+| `validator` | Running verification and recording outcome |
+
+## Reference File Fields
+
+All six fields are mandatory for `category: reference` files:
+
+| Field | Purpose | Example |
+|-------|---------|---------|
+| `name` | Unique identifier | `typescript-imports` |
+| `description` | What it covers | `"Biome import ordering, type imports, #region rules."` |
+| `title` | Display name | `Import Organization` |
+| `label` | Short column label | `Imports` |
+| `when` | Action phrases (present participle) that trigger loading this reference | `Organizing imports, adding new imports` |
+| `order` | Sort position among siblings (integer) | `20` |
+
+```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 to a file
+order: 20
+---
+```
+
+### Writing Effective `when` Fields
+
+Use action phrases (present-participle -ing verbs) describing what the reader is doing, not keywords:
+
+| Bad (keywords) | Good (action phrases) |
+|---|---|
+| `imports, type imports, ordering` | `Organizing imports, reviewing import order, adding new imports` |
+| `atomic write, temp file, rename` | `Writing files safely, preventing partial writes on interruption` |
+| `knip, dead code, unused exports` | `Running dead-code checks, finding unused exports, cleaning before a PR` |
+
+## Workflow File Fields
+
+For `category: workflow` files, no extra frontmatter is required. Use `target` to control the output file name when needed.
+
+Optional Claude command metadata can be stored under a top-level `claude:` block:
+
+```yaml
+---
+category: workflow
+name: ui-review
+title: UI Review
+description: "Runs browser UI review and reports pass/fail evidence."
+target: ui-review.md
+
+# Claude Code slash command options
+claude:
+  model: opus
+  argument-hint: "[headed] [filename-filter]"
+---
+```
+
+## Lifecycle File Fields
+
+For `category: lifecycle` files, one additional field is required:
+
+| Field | Purpose | Example values |
+|-------|---------|---------------|
+| `event` | Lifecycle event that triggers this automation | `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop` |
+
+Optional fields for lifecycle automations:
+
+| Field | Purpose |
+|-------|---------|
+| `matcher` | Regex or glob to filter which commands trigger the automation |
+| `timeout` | Max seconds the automation may run |
+| `statusMessage` | Message shown while the lifecycle command runs |
+
+```yaml
+---
+category: lifecycle
+name: lint-on-save
+title: Lint on Save
+description: "Run Biome lint after every file write. Use to keep code quality in sync."
+event: post-exec
+timeout: 30
+statusMessage: Linting…
+---
+```
+
+The body must contain a code-fenced script block (Python, Bash, or JS). The fence language determines the interpreter. Existing `category: hook` and `.hk.md` files still work as legacy aliases.
+
+## Tags (Optional)
+
+`tags` is freeform and used only for human scanning — not parsed by the playbook sync. Keep them lowercase and concise.
+
+```yaml
+tags: [typescript, biome, conventions]
+```
+
+## Validation Checklist for Reference Files
+
+When reviewing a `category: reference` file, verify all of the following:
+
+1. All six required fields present: `name`, `description`, `title`, `label`, `when`, `order`
+2. No `## When to Use` section in the body — the `when` frontmatter field replaces it
+3. No `references:` field in frontmatter
+4. `when` field uses action phrases, not bare keywords
+5. `order` is an integer (10, 20, 30… — leave gaps for future inserts)

package/ai/modules/playbook/resources/authoring/markdown.rf.md

@@ -0,0 +1,108 @@
+---
+category: reference
+name: playbook-authoring-markdown
+title: Markdown Formatting
+description: "Markdown formatting rules: headings, callouts, emphasis, lists, code blocks, tables, and common anti-patterns."
+label: Markdown
+when: Writing or reviewing markdown, choosing heading levels, adding callouts or warnings, structuring lists and tables, fixing formatting anti-patterns
+order: 40
+---
+
+# Markdown Formatting
+
+## Headings
+
+Headings are for **document structure**, not for emphasis or urgency.
+
+- ATX-style only (`#`, `##`, `###`)
+- One `#` (H1) per file, matching the title
+- Never skip levels (H2 → H4 is wrong; H2 → H3 is correct)
+- Blank line before and after every heading
+- Space after `#` characters
+- No trailing punctuation on headings (no `:` or `.`)
+- No duplicate heading text within a file
+
+Move urgency into the body using callouts — never into heading text:
+
+| Bad | Good |
+|-----|------|
+| `## CRITICAL: Do Not Edit Output` | `## Do Not Edit Generated Output` |
+| `## IMPORTANT: Test Isolation` | `## Test Isolation` |
+| `## ⚠️ Breaking Changes` | `## Breaking Changes` |
+
+## Callouts
+
+Use GitHub/GitLab alert syntax for urgency and importance:
+
+```markdown
+> [!NOTE]
+> Supplementary information the reader should notice.
+
+> [!IMPORTANT]
+> Essential information required for success.
+
+> [!WARNING]
+> Potential issue that could cause a problem.
+
+> [!CAUTION]
+> Action that could cause data loss or an irreversible change.
+```
+
+Limit to **1-2 callouts per major section**. If everything is critical, nothing is. Integrate important information into prose instead of boxing it all.
+
+## Emphasis
+
+- `**bold**` for strong importance inline
+- `*italic*` sparingly for secondary emphasis
+- Pick asterisks consistently — never mix `*` and `_`
+
+## Lists
+
+- Ordered (`1.`) when sequence matters (steps, priority order)
+- Unordered (`-`) for collections where order is irrelevant
+- Consistent marker throughout a file (`-` preferred)
+- Blank lines surrounding each list
+- 2-space indent for nested items
+
+## Code Blocks
+
+- Always fenced (triple backticks) — never indented
+- Always specify the language identifier: ` ```ts `, ` ```bash `, ` ```yaml `
+- Blank line before and after the block
+- Inline code: single backticks, no internal spaces: `` `code` ``
+- Do not prefix shell commands with `$` unless also showing output alongside
+
+## Tables
+
+- Use only for genuinely tabular data (row/column scanning adds value)
+- If data is sparse or unbalanced, use a list instead
+- Keep cells concise
+- Every row must have the same number of columns
+- Blank lines surrounding the table
+
+## Whitespace
+
+- End files with a single newline
+- No trailing whitespace on lines
+- No multiple consecutive blank lines
+- Use spaces, not hard tabs
+
+## Links
+
+- Descriptive link text — never `"click here"` or `"here"`
+- For cross-doc references inside `{{PLAYBOOK_PATH}}/`, reference by **name** (main topics) or **label** (reference files) in bold — never by file path. See **Cross-Refs**.
+
+## Anti-Pattern Quick Reference
+
+| Anti-pattern | Fix |
+|---|---|
+| Heading for emphasis (`## CRITICAL: ...`) | Structural heading + callout in body |
+| ALL CAPS in headings | Sentence or title case |
+| Skipped heading levels (H2 → H4) | Increment one level at a time |
+| Generic link text (`"click here"`) | Descriptive link text |
+| Indented code blocks | Fenced code blocks with language |
+| Mixed emphasis markers (`*` and `_`) | Pick one, use consistently |
+| Stacking many callouts | Limit 1-2 per section; integrate into prose |
+| Trailing colon on heading (`## When to Use:`) | Remove trailing punctuation |
+| Bare URLs | Wrap in `[text](url)` |
+| Table for non-tabular data | Use a list instead |