@sumrco/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">
   <p align="center">
-    <img src="https://dev.sumr.co/sumr-docs.svg" alt="SUMR" width="250" />
+    <img src="https://dev.sumr.co/sumr-docs.svg?v=1" alt="SUMR" width="250" />
   </p>
 </h1>
 

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

@@ -25,6 +25,8 @@ Start with these root folders under `{{PLAYBOOK_PATH}}/` and add more as the cod
 
 Keep `team-members/`, `workflows/`, and `lifecycle/` separate from `standards/` when they are repo-wide — they generate different output types and have different audiences.
 
+When a user asks for hooks or automatic AI-tool behavior, create a lifecycle source doc rather than editing generated hook files. Use `{{PLAYBOOK_PATH}}/lifecycle/` for repo-wide session behavior and sync it into Claude/Codex hook outputs.
+
 ## Full Structure Example
 
 ```

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

@@ -44,23 +44,49 @@ description: "Test isolation rules, temp dir pattern, and integration test appro
 | Field | Type | Purpose |
 |-------|------|---------|
 | `tags` | `string[]` | Freeform labels for human scanning only |
-| `modelTier` | `reasoning \| coding \| fast` | Preferred model tier for team-member/agent topics |
+| `modelTier` | `reasoning \| coding \| fast` | Model class for team-member/agent topics. Resolved to a concrete model per channel. |
+| `effort` | `low \| medium \| high` | Reasoning depth for team-member/agent topics. Channels that support effort emit their native knob. |
+| `access` | `read-only \| write \| full` | Permission posture. Channels translate it into their sandbox, tool, or permission model. |
+| `tools` | `string[]` | Agnostic capability tokens (`read`, `edit`, `shell`, `web`, `todo`, `task`). Channels translate them into native tool names or permission keys. |
 | `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
+### Agent Model + Tools Axes
 
-| Value | Codex model |
-|-------|-------------|
-| `reasoning` | `o4-mini` |
-| `coding` | `gpt-4.1` |
-| `fast` | `gpt-4o-mini` |
+Declare intent once with the agnostic axes; each channel emits what it supports.
 
 ```yaml
-modelTier: coding
+modelTier: reasoning   # reasoning | coding | fast  → model class
+effort: high           # low | medium | high        → Codex model_reasoning_effort
+access: read-only      # read-only | write | full   → channel-native permission posture
+tools: [read, web]     # read | edit | shell | web | todo | task  → channel-native tools/permissions
 ```
 
-An explicit `codex.model` override always takes precedence over `modelTier`.
+`modelTier` → concrete model per channel:
+
+| Tier | Claude |
+|------|--------|
+| `reasoning` | `opus` |
+| `coding` | `sonnet` |
+| `fast` | `haiku` |
+
+Claude uses the short aliases (which never drift). Other channels ship no model
+default — pin them with `SUMR_MODEL_<CHANNEL>_<TIER>` (e.g. `SUMR_MODEL_CODEX_REASONING=o3`)
+or a native block. Codex still derives `model_reasoning_effort` from `effort` (or
+`modelTier`) and `sandbox_mode` from `access`.
+
+`tools` is transformed per channel, not copied as Claude names:
+
+| Channel | Transform |
+|---|---|
+| Claude | `tools: "Read, Grep, Glob, ..."` |
+| Gemini | `tools:` array with native names such as `read_file`, `grep_search`, `web_fetch` |
+| GitHub Copilot | `tools:` array with aliases such as `read`, `search`, `edit`, `web` |
+| OpenCode | `permission:` object with keys such as `read`, `grep`, `edit`, `bash`, `webfetch` |
+| Codex | no tool allowlist; `access` maps to `sandbox_mode` |
+
+Resolution precedence (highest first): a native channel block (e.g. `codex.model`)
+→ the `SUMR_MODEL_*` env override → the adapter default.
 
 ## Native Channel Props
 
@@ -204,6 +230,10 @@ claude:
 
 ## Lifecycle File Fields
 
+Create a lifecycle doc when the user asks for hooks, AI session automation, startup context, stop/closeout quality checks, pre-tool policy checks, post-tool formatters, or automated guardrails in Claude/Codex/Cursor/Copilot/Gemini/OpenCode.
+
+Canonical source belongs in `{{PLAYBOOK_PATH}}/lifecycle/<name>.lc.md` for repo-wide behavior. Use tool-native hook files only as generated output.
+
 For `category: lifecycle` files, one additional field is required:
 
 | Field | Purpose | Example values |
@@ -221,17 +251,20 @@ Optional fields for lifecycle automations:
 ```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…
+name: code-quality-closeout
+title: Code Quality Closeout
+description: "Runs changed-scope quality checks when an AI coding session stops."
+event: Stop
+timeout: 300
+statusMessage: "Running code quality closeout"
+target: code_quality_closeout.py
 ---
 ```
 
 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.
 
+After authoring a lifecycle doc, run `sumr playbook validate --source docs`, then `sumr playbook sync --source docs --dry-run --json`, then normal sync once the preview shows only expected generated hook outputs.
+
 ## Tags (Optional)
 
 `tags` is freeform and used only for human scanning — not parsed by the playbook sync. Keep them lowercase and concise.

package/ai/modules/playbook/resources/authoring/lifecycle-hooks.rf.md

@@ -0,0 +1,110 @@
+---
+category: reference
+name: lifecycle-hooks
+title: Lifecycle Hooks
+description: "Lifecycle automation authoring for Claude and Codex hooks generated from Playbook docs. Use when users ask for hooks, AI automation, startup context, or tool-use guardrails."
+label: Lifecycle Hooks
+when: Creating hooks, AI lifecycle automations, startup context loaders, stop checks, pre-tool guards, post-tool checks, Claude hooks, or Codex hooks
+order: 35
+---
+
+Create lifecycle source docs before editing tool-native hook files.
+
+```text
+User asks for hook/automation
+-> create {{PLAYBOOK_PATH}}/lifecycle/<name>.lc.md
+-> validate
+-> dry-run sync
+-> sync generated Claude/Codex hook outputs
+```
+
+## Language
+
+- Say **lifecycle automation** in canonical Playbook docs.
+- Treat **hook** as the generated AI Channel mechanism.
+- `category: hook` and `.hk.md` are legacy aliases; use `category: lifecycle`
+  and `.lc.md` for new docs.
+
+## Placement
+
+- Use `{{PLAYBOOK_PATH}}/lifecycle/` for repo-wide AI session behavior.
+- Place domain-specific lifecycle docs beside the domain they guard only when the
+  automation is inseparable from that domain.
+- Keep lifecycle docs separate from normal standards unless the automation is
+  the whole point of the doc.
+
+## Required frontmatter
+
+```yaml
+---
+category: lifecycle
+name: quality-stop-check
+title: Quality Stop Check
+description: "Runs a quality check before the AI session stops. Use when guarding handoff quality."
+event: Stop
+target: quality-stop-check.sh
+---
+```
+
+Required:
+
+- `category: lifecycle`
+- `name`
+- `title`
+- `description`
+- `event`
+- `target`
+
+Useful optional fields:
+
+- `matcher` — event source or tool filter, such as `Bash|apply_patch`
+- `timeout` — timeout in seconds
+- `statusMessage` — short status shown while the hook runs
+
+## Generated outputs
+
+Claude and Codex both have generated hook outputs.
+
+| Channel | Generated outputs |
+|---|---|
+| Claude | `.claude/hooks/sumr-*`, `.claude/settings.json` hook bindings |
+| Codex | `.codex/hooks/sumr-*`, `.codex/hooks.json`, `.codex/config.toml` hooks feature flag |
+
+Do not hand-edit generated hook outputs when a Playbook lifecycle source doc can
+generate them. Edit the lifecycle source doc, validate, then sync.
+
+## Script body
+
+The lifecycle doc body must include one recognized code fence:
+
+- `bash`
+- `sh`
+- `python`
+- `js`
+- `ts`
+
+Example:
+
+```markdown
+\`\`\`bash
+#!/usr/bin/env bash
+set -euo pipefail
+bun run check
+\`\`\`
+```
+
+The renderer writes the script into the channel-specific hooks folder and binds
+it to the configured lifecycle event.
+
+## Validation flow
+
+After creating or changing a lifecycle doc:
+
+```bash
+sumr playbook validate --source docs
+sumr playbook sync --source docs --dry-run --json
+sumr playbook sync --source docs
+```
+
+Review the dry-run output before writing. Expected changes should be limited to
+generated hook scripts, hook binding files, and channel config files.

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

@@ -1,18 +1,30 @@
 ---
 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]
+description: "How to write canonical SUMR Playbook docs: frontmatter schema, references, extraction markers, and authoring checklist. Use when creating or editing Markdown docs, technical docs, AI docs, agent skills, specs, runbooks, or Playbook sources."
+tags: [authoring, docs, markdown, ai-docs, technical-docs, specs, skills]
 ---
 
 ## When to Use
 
 - Creating a new `.md` file anywhere under `{{PLAYBOOK_PATH}}/`.
 - Editing or restructuring existing docs.
+- Writing or reviewing technical docs, engineering docs, architecture docs, runbooks, specs, ADRs, standards, or process docs.
+- Writing AI-facing docs, agent instructions, AI skills, agent skills, Codex/Claude resources, or Markdown files meant to guide an AI tool.
 - Reviewing a doc for schema or structure compliance.
+- Checking whether a Markdown file should be treated as Playbook format before editing it.
 - Deciding whether to split a long doc into main + references.
 - Explaining workflow, lifecycle, approval, or handoff flows.
 
+If the user asks for "AI docs", "AI format", "agent docs", "agent skills",
+"technical docs", "Markdown docs", "MD files", "spec files", "runbooks",
+"ADRs", "standards", or "docs structure", treat this skill as relevant even
+when the user never says "Playbook".
+
+When modifying any `.md` file that is not clearly a generated artifact, ask
+whether it should follow Playbook format unless the repository already requires
+Playbook frontmatter for that folder.
+
 ## Core Principle: Layered Docs
 
 Keep main docs concise and high-signal. Push deep detail into `category: reference` files in the same folder.
@@ -25,6 +37,17 @@ Keep main docs concise and high-signal. Push deep detail into `category: referen
 
 Reference files attach automatically by **folder proximity** — no linking field needed. The main doc and its references live in the same folder.
 
+## Lifecycle-First Hook Guidance
+
+When a user asks for hooks, post-edit checks, AI session automation, quality
+gates, startup context loading, tool-use guards, or any process that should run
+automatically inside an AI tool, create a `category: lifecycle` Playbook doc
+first. Treat Claude/Codex hook files as generated AI Channel outputs, not the
+source of truth.
+
+See **Lifecycle Hooks** for event fields, generated Claude and Codex outputs,
+placement rules, and validation flow.
+
 ## 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.

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

@@ -3,10 +3,8 @@ 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
+modelTier: reasoning
+access: read-only
 ---
 
 # Playbook Technical Writer
@@ -24,6 +22,8 @@ Apply **playbook-authoring** before writing or editing Playbook docs.
 - 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`.
+- When the user asks for hooks, automatic AI checks, session start/stop behavior, pre/post tool guards, quality closeout, or similar AI-tool automation, propose a `category: lifecycle` doc in `{{PLAYBOOK_PATH}}/lifecycle/` before any tool-native hook edits.
+- Explain that Claude/Codex hook files are generated AI Channel output; the Playbook lifecycle doc is the source of truth.
 - Avoid editing generated channel output directly.
 
 ## Output

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

@@ -3,7 +3,7 @@ kind: CliModule
 metadata:
   name: playbook
   package: "@sumrco/cli"
-  description: Sync team standards into AI tools (Claude, Cursor, Codex, VS Code)
+  description: Sync Playbook docs into AI tools (Claude, Cursor, Codex, VS Code)
   owners:
     - team: "@sumr-org/playbook-team"
   tags:
@@ -11,7 +11,7 @@ metadata:
     - authoring
     - ai-tools
 spec:
-  visibility: private
+  visibility: public
   group: modules
   targets:
     contractVersion: ^1.0.0
@@ -19,25 +19,25 @@ spec:
   commands:
     - name: config
       summary: Manage playbook configuration in sumr.yaml
-      visibility: private
+      visibility: public
     - name: sync
       summary: Render Playbook Markdown into AI tool channels
-      visibility: private
+      visibility: public
     - name: validate
       summary: Check Playbook docs for errors without writing files
-      visibility: private
+      visibility: public
     - name: status
       summary: Show Playbook status, sources, and counts
-      visibility: private
+      visibility: public
     - name: add
       summary: Scaffold a new Playbook doc with correct frontmatter
-      visibility: private
+      visibility: public
     - name: clean
       summary: Remove all rendered Playbook outputs from this repo
-      visibility: private
+      visibility: public
     - name: authoring
       summary: Print the canonical Playbook Markdown authoring contract
-      visibility: private
+      visibility: public
   exports:
     resources:
       - ./resources