@sumrco/cli 0.1.0

package/ai/modules/mission/resources/workflows/daily-triage.wf.md

@@ -0,0 +1,117 @@
+---
+category: workflow
+name: daily-triage
+title: Daily Mission Triage
+description: "Builds a daily SUMR Mission triage queue from configured trackers, open Mission state, or provided work items, then stops before approval or implementation."
+---
+
+# Daily Mission Triage
+
+Use this workflow for a daily planning run that prepares reviewable Mission plans without starting delivery.
+
+This is a triage workflow, not an implementation workflow. It helps teams decide what is ready for human review, approval, splitting, assignment, or later implementation.
+
+## Inputs
+
+The caller may provide:
+
+- A list of issue keys, tracker IDs, URLs, or custom work item labels.
+- Query output from a repo-specific tracker discovery script.
+- A configured tracker filter, such as bugs, incidents, customer requests, Todo, In Progress, or unplanned work.
+- No issue list, in which case inspect current Mission state with `sumr mission next` and `sumr mission list --all`.
+
+## Triage Goals
+
+Build a daily queue that answers:
+
+- Which missions need a plan?
+- Which draft plans are waiting for approval?
+- Which approved plans are ready for claim or dispatch?
+- Which missions are blocked, stale, duplicated, or already in progress?
+- Which tracker items should get a new draft Mission plan today?
+
+## Planning-Only Prompt
+
+For each selected work item that needs a draft plan, use this prompt shape:
+
+```text
+Run SUMR Mission planning only for {{issueOrWorkItem}}.
+
+Create or update the Mission, read full tracker context including description,
+comments, todos/checklists, linked docs, and images/screenshots, inspect relevant
+code paths read-only, write a draft implementation plan, register the plan
+without --approve, then stop.
+
+Do not approve the plan.
+Do not claim the mission.
+Do not implement.
+Do not create a worktree.
+Do not edit application code.
+```
+
+Use the `sumr-mission-planner` agent when the channel supports custom agents.
+
+## Steps
+
+1. Load existing Mission state:
+
+   ```bash
+   sumr mission next --all
+   sumr mission list --all
+   ```
+
+2. Collect candidate work items from the caller, the repo-specific tracker query, or the configured tracker.
+3. Normalize every candidate to a Mission issue key.
+4. Skip candidates that already have an approved plan, claim, implementation report, review report, validation report, or close-ready state.
+5. For each selected candidate, check current state:
+
+   ```bash
+   sumr mission status <issueKey>
+   ```
+
+6. Read tracker context before planning: description/body, acceptance criteria,
+   todos/checklists, comments/discussion, linked docs, and images/screenshots or
+   other attachments.
+7. If no mission exists, create one from tracker context:
+
+   ```bash
+   sumr mission start --tracker <tracker> --issue <issue> --name "<title>"
+   ```
+
+8. Run one planning agent per selected work item. Do not combine unrelated items into one plan.
+9. Register the draft plan without approval:
+
+   ```bash
+   sumr mission plan <issueKey> --from <draft-plan-file>
+   ```
+
+10. Verify the stop state:
+
+   ```bash
+   sumr mission status <issueKey>
+   ```
+
+   The next action should be plan approval, not claim or implementation.
+
+## Output
+
+Return a concise daily triage queue:
+
+- Issue key and title.
+- Tracker source and current tracker state when available.
+- Mission status and next action.
+- Draft plan path when one was created.
+- Affected areas.
+- Open questions or blockers.
+- Risk level.
+- Recommended delivery shape after approval: current checkout, sequential work, optional parallel workstreams, or no action.
+
+## Rules
+
+- Do not pass `--approve` during daily triage.
+- Do not run `sumr mission claim`.
+- Do not spawn implementation agents from this workflow.
+- Do not create worktrees during triage.
+- Do not mutate external trackers, labels, assignees, project status, pull requests, deployments, or external systems without explicit approval.
+- If the tracker query is unavailable or lacks permissions, report that clearly and continue from existing Mission state.
+- If a work item is ambiguous or blocked by missing product context, create the draft plan with open questions and leave the Mission waiting for approval.

package/ai/modules/mission/resources/workflows/full-delivery.wf.md

@@ -0,0 +1,18 @@
+---
+category: workflow
+name: full-delivery
+title: Full Mission Delivery
+description: "Runs the richer Mission flow with issue sync, research, plan approval, branch check, delivery, quality, PR assist, and closeout."
+---
+
+# Full Mission Delivery
+
+Use this workflow when the task is broad, risky, or benefits from explicit research and quality gates.
+
+```text
+issue.sync -> context.research -> plan.create -> plan.approve(human) -> branch.check(ask) -> work.claim -> implementation.report -> review.report -> validation.report -> quality.gate -> pr.prepare(ask) -> pr.create(human) -> mission.close
+```
+
+Do not collapse research, plan approval, PR creation, or closeout unless the user explicitly approves.
+
+ARGUMENTS: $ARGUMENTS

package/ai/modules/mission/resources/workflows/mission-cycle.wf.md

@@ -0,0 +1,30 @@
+---
+category: workflow
+name: cycle
+title: Mission Cycle
+description: "Guides an AI agent through the configured Mission flow, next action, planning, implementation, validation, PR assist, handoff, and closeout."
+---
+
+# Mission Cycle
+
+Use this workflow when the user gives an issue key, tracker ID, mission ID, or asks to resume AI-assisted work.
+
+## Configured Flow
+
+This repo uses `{{MISSION_FLOW_PRESET}}`.
+
+```text
+{{MISSION_FLOW_TEXT}}
+```
+
+## Steps
+
+1. Confirm Mission is initialized. If not, run `sumr mission init`.
+2. Identify or create the mission with `sumr mission start`.
+3. Run `sumr mission status <key>` or `sumr mission next`.
+4. Follow the returned next action and stop at `human` or `ask` gates.
+5. Use Mission reports for implementation, review, validation, quality, and handoff evidence.
+6. Use `sumr mission pr <key> --preview` before asking to create a PR.
+7. Never push, create PRs, mutate trackers, merge, or deploy without explicit approval.
+
+ARGUMENTS: $ARGUMENTS

package/ai/modules/mission/resources/workflows/planning-only.wf.md

@@ -0,0 +1,68 @@
+---
+category: workflow
+name: planning-only
+title: Mission Planning Only
+description: "Creates SUMR Mission draft plans for one or more work items, then stops before approval, claim, worktree creation, or implementation."
+---
+
+# Mission Planning Only
+
+Use this workflow when a user or automation wants reviewable Mission plans without implementation.
+
+## Input
+
+The caller provides one or more issue keys, tracker IDs, URLs, or custom work item labels.
+
+## Planning-Only Prompt
+
+For each work item, use this prompt shape:
+
+```text
+Run SUMR Mission planning only for {{issueOrWorkItem}}.
+
+Create or update the Mission, read full tracker context including description,
+comments, todos/checklists, linked docs, and images/screenshots, inspect relevant
+code paths read-only, write a draft implementation plan, register the plan
+without --approve, then stop.
+
+Do not approve the plan.
+Do not claim the mission.
+Do not implement.
+Do not create a worktree.
+Do not edit application code.
+```
+
+Use the `sumr-mission-planner` agent when the channel supports custom agents.
+
+## Steps
+
+1. Normalize each work item to a Mission issue key.
+2. Run one planner per work item. Do not combine multiple unrelated items into one Mission plan.
+3. Check existing state with `sumr mission status <issueKey>` before creating or updating a plan.
+4. Read tracker context before planning: description/body, acceptance criteria,
+   todos/checklists, comments/discussion, linked docs, and images/screenshots or
+   other attachments.
+5. If no mission exists, create one from tracker context:
+
+   ```bash
+   sumr mission start --tracker <tracker> --issue <issue> --name "<title>"
+   ```
+
+6. Write a draft plan and register it without approval:
+
+   ```bash
+   sumr mission plan <issueKey> --from <draft-plan-file>
+   ```
+
+7. Verify `sumr mission status <issueKey>` shows a plan pending approval.
+8. Return a planning queue grouped by issue key.
+
+## Rules
+
+- Do not pass `--approve` during planning-only runs.
+- Do not run `sumr mission claim`.
+- Do not spawn implementation agents from this workflow.
+- Do not create worktrees during planning.
+- Do not mutate external trackers, labels, assignees, project status, PRs, deployments, or external systems without explicit approval.
+- If a mission already has an approved plan, claim, implementation report, or validation report, skip planning and report the existing state instead of overwriting it.
+- If the issue is ambiguous or blocked by missing product context, create the draft plan with open questions and leave the Mission waiting for approval.

package/ai/modules/mission/resources/workflows/pr-assist.wf.md

@@ -0,0 +1,21 @@
+---
+category: workflow
+name: pr-assist
+title: Mission PR Assist
+description: "Prepares a scoped PR preview from Mission artifacts, issue context, verification evidence, and repo PR conventions."
+---
+
+# Mission PR Assist
+
+Use this workflow after implementation and validation evidence exists.
+
+1. Run `sumr mission status <key>`.
+2. Confirm the current branch is not protected.
+3. Run `sumr mission pr <key> --preview`.
+4. Review the generated PR body for scope drift, local-only paths, raw commit logs, and raw diff stats.
+5. Remove or split unrelated dependency, audit, tooling, infrastructure, or cleanup changes unless they are required for the issue.
+6. Ask before `--create-draft` or `--create`.
+
+Never merge or mutate issue/project state.
+
+ARGUMENTS: $ARGUMENTS

package/ai/modules/mission/resources/workflows/standard-delivery.wf.md

@@ -0,0 +1,18 @@
+---
+category: workflow
+name: standard-delivery
+title: Standard Mission Delivery
+description: "Runs the default practical Mission flow from issue intake through plan approval, implementation evidence, validation, quality gate, and PR preview."
+---
+
+# Standard Mission Delivery
+
+Use this workflow for normal issue delivery.
+
+```text
+issue.sync -> context.research(skipped) -> plan.create -> plan.approve(human) -> branch.check(ask) -> work.claim -> implementation.report -> review.report -> validation.report -> quality.gate -> pr.prepare(ask) -> pr.create(human)
+```
+
+Stop for human approval before implementation and before PR creation.
+
+ARGUMENTS: $ARGUMENTS

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

@@ -0,0 +1,78 @@
+apiVersion: sumr.dev/v1
+kind: CliModule
+metadata:
+  name: mission
+  package: "@sumrco/cli"
+  description: File-backed execution state for AI-assisted work
+  owners:
+    - team: "@sumr-org/mission-team"
+  tags:
+    - ai-workflow
+    - state
+    - cache
+spec:
+  visibility: public
+  group: modules
+  targets:
+    contractVersion: ^1.0.0
+    bunVersion: ">=1.1.0"
+  commands:
+    - name: init
+      summary: Initialize Mission state for the current repository or global workspace
+      visibility: public
+    - name: start
+      summary: Start or resume a mission
+      visibility: public
+    - name: status
+      summary: Show mission status and next action
+      visibility: public
+    - name: next
+      summary: Show the next mission action
+      visibility: public
+    - name: list
+      summary: List missions
+      visibility: public
+    - name: plan
+      summary: Create or register a mission plan
+      visibility: public
+    - name: approve
+      summary: Approve the current mission plan for implementation
+      visibility: public
+    - name: claim
+      summary: Claim a mission for implementation
+      visibility: public
+    - name: report
+      summary: Create a mission report
+      visibility: public
+    - name: block
+      summary: Mark a mission as blocked
+      visibility: public
+    - name: unblock
+      summary: Clear a mission blocker
+      visibility: public
+    - name: close
+      summary: Close a completed mission
+      visibility: public
+    - name: clean
+      summary: Remove expired closed mission cache
+      visibility: public
+    - name: flow
+      summary: Inspect and configure Mission flow presets
+      visibility: public
+    - name: pr
+      summary: Prepare or create a pull request from Mission evidence
+      visibility: public
+  exports:
+    resources: []
+    binaries: []
+    aiResources:
+      module: mission
+      roots:
+        - ./resources
+      activation:
+        mode: command
+        initCommand: mission init
+        key: mission
+  flags:
+    experimental: false
+    deprecated: null

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

@@ -0,0 +1,148 @@
+---
+category: reference
+name: playbook-authoring-structure
+title: Content Structure
+description: "Body templates for canonical Playbook topics and reference files, with required sections and structure rules."
+label: Structure
+when: Creating a new how-to doc, creating a new reference file, checking required body sections, deciding how to structure a new doc
+order: 50
+---
+
+# Content Structure
+
+## Main How-To Doc
+
+```yaml
+---
+name: my-topic
+description: "What this covers. Use when doing X."
+tags: [optional, tags]
+---
+```
+
+```markdown
+# Topic Title
+
+Brief intro — one or two sentences. Optional.
+
+## When to Use
+
+- Bullet conditions describing when this doc is relevant
+- Be specific about the action or context
+
+## Core Rules / Overview
+
+High-level rules or overview. Keep concise.
+Push deep details to reference files in the same folder.
+
+## Key Section
+
+Main content. Code snippets inline for short examples.
+
+<!-- extract:examples -->
+## Examples
+
+\`\`\`ts
+const stateByTransition = {
+  draft: ['review'],
+  review: ['approved', 'changes-requested'],
+} as const;
+\`\`\`
+<!-- /extract:examples -->
+```
+
+Rules:
+- `## When to Use` is required in every main doc.
+- Keep the main doc under ~180 lines. If it goes over, move deep sections to `category: reference` files.
+- Do not add a `## References` or `## Related` section manually — the playbook sync generates the reference table automatically.
+
+## Reference File
+
+```yaml
+---
+category: reference
+name: my-topic-detail
+title: Detail Section Title
+description: "What this reference covers (specific, no meta phrasing)."
+label: Detail
+when: Doing X, reviewing Y, adding Z
+order: 10
+---
+```
+
+```markdown
+# Detail Section Title
+
+## Section A
+
+Content...
+
+## Section B
+
+Content...
+
+<!-- extract:examples -->
+## Examples
+
+\`\`\`ts
+const requiredReferenceFields = ['label', 'when', 'order'] as const;
+\`\`\`
+<!-- /extract:examples -->
+```
+
+Rules:
+- No `## When to Use` in the body — `when` frontmatter replaces it.
+- No `references:` frontmatter field.
+- Keep the file in the **same folder** as the main doc it supports.
+- `order` uses integers with gaps (10, 20, 30…) to allow future inserts.
+
+## Splitting an Existing File
+
+Before moving text, decide whether the current folder is the right context owner.
+
+Use this linear flow:
+
+1. Analyze context: read the current folder, `overview.md`, sibling docs, and generated output expectations.
+2. Choose placement:
+   - Same-folder reference when the extracted content supports the current `overview.md`.
+   - New child folder when the extracted content deserves its own main topic and references.
+   - New child folder when the split produces multiple files for one microconcept. The child `overview.md` is the invoker/entry point; the other files become references.
+3. Split: keep the entry point short; move deep examples, edge cases, long tables, and checklists into references.
+4. Check rules: one `overview.md` per topic folder, no manual `references/` folder, no `references:` frontmatter, reference files have `label`, `when`, and `order`.
+5. Validate: run `sumr playbook validate --source docs`.
+6. Preview: run `sumr playbook sync --source docs --dry-run --json` and inspect warnings before normal sync.
+
+Do not create several overview-like peers in a broad folder. For example, if `standards/testing/playwright.md` becomes a standalone topic, create `standards/testing/playwright/overview.md` and put Playwright references beside it.
+
+Example: if `standards/testing/playwright-cli.md` is split into command usage plus a command catalog, do not leave both files in `standards/testing/`. Use the child topic folder:
+
+```text
+{{PLAYBOOK_PATH}}/standards/testing/
+├── overview.md
+└── playwright-cli/
+    ├── overview.md            ← main topic and invoker
+    └── command-catalog.md     ← category: reference
+```
+
+The parent testing overview should route to the child topic at a high level. The detailed Playwright CLI references belong beside the child `overview.md`, not beside the parent testing overview.
+
+## Folder Structure Pattern
+
+```
+{{PLAYBOOK_PATH}}/
+└── my-topic/
+    ├── overview.md           ← main how-to doc (entry point)
+    ├── detail-a.md           ← category: reference, order: 10
+    ├── detail-b.md           ← category: reference, order: 20
+    └── detail-c.md           ← category: reference, order: 30
+```
+
+Each folder has **one** `overview.md` as the entry point. All `category: reference` files live alongside it. Do not nest references further.
+
+## When to Restructure
+
+If a folder is missing an `overview.md` or has multiple unrelated how-to files:
+
+1. Create `overview.md` as the main doc summarising the domain.
+2. Convert the sub-topic files to `category: reference` with `title`, `label`, `when`, `order`.
+3. If a file is actually about a different domain, move it to the appropriate folder instead.

package/ai/modules/playbook/resources/authoring/cross-referencing.rf.md

@@ -0,0 +1,57 @@
+---
+category: reference
+name: playbook-authoring-cross-referencing
+title: Cross-Referencing
+description: "How to reference other topics within SUMR docs: use name for main topics, label for references. Never use file paths."
+label: Cross-Refs
+when: Referencing another topic from within content, choosing how to link to a related doc
+order: 60
+---
+
+# Cross-Referencing
+
+## Never Use File Paths
+
+Do not link to other docs by file path. Files are moved and renamed by generators — paths are not stable identifiers.
+
+```markdown
+# Bad — file paths break after generation
+See [Frontmatter](frontmatter.rf.md) for the schema.
+Follow [TypeScript](typescript.md) rules.
+
+# Good — reference by name or label
+See **Frontmatter** for the schema.
+Follow the **typescript** conventions.
+```
+
+## How to Reference
+
+**Referencing a main topic** — use its `name` field in bold:
+
+```markdown
+Follow the rules in **typescript**.
+See **patterns** for the renderer pipeline.
+```
+
+**Referencing a reference file** — use its `label` field in bold (the label is the short column name visible in the generated reference table):
+
+```markdown
+See **Extraction** for the code-block classification table.
+Follow the rules in **Descriptions** when writing description fields.
+```
+
+The difference: `name` is lowercase kebab (`typescript`, `patterns`). `label` is the display name used in the reference table (`Extraction`, `Descriptions`, `Command Router`).
+
+## Action Words
+
+| Word | When to use | Example |
+|------|-------------|---------|
+| **Follow** | The reader must obey the rules there | `Follow the rules in **Descriptions**.` |
+| **See** | For more detail, informational reference | `See **Extraction** for marker syntax.` |
+| **Use** | Use that topic when doing X | `Use **patterns** when adding a renderer.` |
+
+## What Not to Add
+
+- No `## References` section — the generator builds the reference table automatically from `category: reference` files in the same folder.
+- No `## Related` sections.
+- No summary lists: "For X see **ref**; for Y see **ref**." — inline contextual references are fine; summary lists are not.

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

@@ -0,0 +1,71 @@
+---
+category: reference
+name: playbook-authoring-descriptions
+title: Writing Descriptions
+description: "Rules for writing effective frontmatter descriptions — third person, what-plus-when, specific key terms, length, and YAML safety."
+label: Descriptions
+when: Writing or reviewing a description field, fixing vague or meta descriptions, checking YAML quoting
+order: 30
+---
+
+# Writing Descriptions
+
+Descriptions are how AI tools discover and select the right doc. A good description states **what the doc contains** and **when to use it**, in **third person**, with **specific key terms**.
+
+## Rules
+
+1. **Third person only.** The description is injected into context; first or second person breaks discovery.
+   - Good: `"Atomic write helpers, managed block markers, and pruning logic for SUMR renderers."`
+   - Bad: `"This document describes..."` / `"I help you..."` / `"Use this to..."`
+
+2. **What + when.** Include what the doc covers and when it is relevant.
+   - Good: `"Test isolation rules, temp dir pattern, and integration test approach. Use when writing CLI tests."`
+   - Bad: `"Testing guidelines."` — too vague, no trigger
+
+3. **Specific key terms.** So the AI can match the user's query. Avoid restating the filename.
+   - Good: `"Naming, import ordering, type discipline, and Biome rules for the SUMR CLI."`
+   - Bad: `"TypeScript overview."` / `"TypeScript."`
+
+4. **Avoid:** Meta phrasing (`"this document..."`, `"the following guide..."`), vague standalone labels (`"overview"`, `"best practices"`), first/second person, empty filler.
+
+## YAML Safety
+
+Descriptions containing `: `, `#`, `[`, `]`, or `{{` **must** be wrapped in double quotes:
+
+```yaml
+# Bad — unquoted colon causes YAML parse error
+description: Config schema: migrations and deprecation codes.
+
+# Good
+description: "Config schema: migrations and deprecation codes. Use when changing config fields."
+```
+
+Always quote descriptions. It is the safest default and causes no harm.
+
+## Length
+
+Aim for under 80 characters. Clarity over strict length — two short sentences are fine when one trigger phrase isn't enough.
+
+<!-- extract:examples -->
+## Examples
+
+| Type | Bad | Good |
+|------|-----|------|
+| How-to | `"TypeScript conventions."` | `"Naming, import ordering, type discipline, and Biome rules. Use when writing or reviewing TypeScript."` |
+| Reference | `"Import rules."` | `"Biome distance-based import ordering, type imports, and #region rules."` |
+| How-to | `"Testing guidelines."` | `"Test isolation rules, temp dir pattern, and integration test approach for the SUMR CLI."` |
+| How-to | `"Authoring docs."` | `"Frontmatter schema, reference files, extraction markers, and checklist. Use when creating or editing {{PLAYBOOK_PATH}}/."` |
+
+### Full YAML examples
+
+```yaml
+# How-to doc
+description: "Naming, import ordering, type discipline, and Biome rules. Use when writing or reviewing TypeScript."
+
+# Reference file
+description: "Biome distance-based import ordering, type imports, and #region rules."
+
+# Config doc
+description: "Config schema: versioning, migration registry, deprecation codes. Use when changing config fields."
+```
+<!-- /extract:examples -->