@sumrco/cli 0.1.0

package/ai/modules/kontract/resources/schema-reuse.rf.md

@@ -0,0 +1,233 @@
+---
+category: reference
+name: schema-reuse
+title: Schema Reuse and Shared Components
+description: "How to author OpenAPI/AsyncAPI specs with reusable shared components, $ref, and safe composition so Kontract output stays consistent and avoids copy-pasted contract drift."
+label: Schema Reuse
+when: Adding repeated fields, response envelopes, pagination, errors, schedules, config objects, or reviewing generated diffs with duplicated DTO/model shapes
+order: 12
+---
+
+# Schema Reuse and Shared Components
+
+Kontract works best when the spec is designed like a product API, not like a
+collection of copied YAML snippets. If the same concept appears in multiple
+operations or services, define it once and reference it with `$ref`.
+
+This reduces drift in the source specs immediately. It also gives Kontract a
+clear path to emit more shared generated code as the generator evolves.
+
+## What to share
+
+Prefer shared components for concepts that mean the same thing everywhere:
+
+- scalar primitives: UUIDs, ISO dates, slugs, URLs, MIME types, time strings;
+- path/query parameters: `id`, `recipeId`, pagination, date ranges;
+- standard error responses and error body schemas;
+- pagination metadata;
+- common response envelope fields such as `success`, `timestamp`, `path`, and
+  optional `message`;
+- weekly schedules and reusable time-slot shapes;
+- repeated configuration objects, such as measurement units, recipe step labels,
+  display colors, notification settings, or payment settings when they truly
+  share semantics.
+
+Example shared scalar and parameter file:
+
+```yaml
+# schema/shared/common.yml
+components:
+  schemas:
+    UuidString:
+      type: string
+      format: uuid
+    ImageMimeType:
+      type: string
+      pattern: '^image\/(jpeg|png|webp|gif)$'
+    PaginationMeta:
+      type: object
+      required: [page, pageSize, pageCount, total]
+      properties:
+        page:
+          type: integer
+          minimum: 1
+        pageSize:
+          type: integer
+          minimum: 1
+        pageCount:
+          type: integer
+          minimum: 0
+        total:
+          type: integer
+          minimum: 0
+  parameters:
+    id:
+      name: id
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/UuidString'
+```
+
+Use those components from service specs:
+
+```yaml
+parameters:
+  - $ref: ../shared/common.yml#/components/parameters/id
+content:
+  application/json:
+    schema:
+      $ref: ../shared/common.yml#/components/schemas/ImageMimeType
+```
+
+## Response envelopes
+
+If every endpoint repeats the same envelope fields, do not retype them in every
+schema. Put the shared part in a component and compose concrete responses with
+`allOf`.
+
+```yaml
+# schema/shared/common.yml
+components:
+  schemas:
+    SuccessResponseBase:
+      type: object
+      required: [success, timestamp, path]
+      properties:
+        success:
+          type: boolean
+        timestamp:
+          type: string
+          format: date-time
+        path:
+          type: string
+        message:
+          type: string
+```
+
+```yaml
+# schema/recipes/catalog.openapi.yml
+components:
+  schemas:
+    RecipesFindOneResponse:
+      allOf:
+        - $ref: ../shared/common.yml#/components/schemas/SuccessResponseBase
+        - type: object
+          required: [data]
+          properties:
+            data:
+              $ref: '#/components/schemas/RecipeResponse'
+```
+
+Use the same pattern for paginated responses:
+
+```yaml
+components:
+  schemas:
+    RecipesFindAllResponse:
+      allOf:
+        - $ref: ../shared/common.yml#/components/schemas/SuccessResponseBase
+        - type: object
+          required: [data]
+          properties:
+            data:
+              type: array
+              items:
+                $ref: '#/components/schemas/RecipeResponse'
+            meta:
+              $ref: ../shared/common.yml#/components/schemas/PaginationMeta
+```
+
+Kontract supports object `allOf` composition by flattening supported object refs
+and inline object parts. Today this mainly reduces YAML duplication and contract
+semantic drift. It may still emit concrete generated DTO/model properties per
+response until the generator grows preserved composition or shared-output
+emission.
+
+## Schedules and repeated nested objects
+
+If several features define the same day-of-week schedule or time-slot object,
+share the object definitions instead of duplicating each day shape.
+
+```yaml
+# schema/shared/scheduling.yml
+components:
+  schemas:
+    WeeklyTimeSlot:
+      type: object
+      required: [from, to]
+      properties:
+        from:
+          type: string
+          pattern: '^(0[6-9]|1\d|2[0-3]):[0-5]\d$'
+        to:
+          type: string
+          pattern: '^(0[6-9]|1\d|2[0-3]):[0-5]\d$'
+    WeeklySchedule:
+      type: object
+      properties:
+        sunday:
+          type: array
+          items:
+            $ref: '#/components/schemas/WeeklyTimeSlot'
+        monday:
+          type: array
+          items:
+            $ref: '#/components/schemas/WeeklyTimeSlot'
+```
+
+Then service-specific schedules can reference or compose those shared pieces.
+
+## Review checklist
+
+After writing or updating any `*.openapi.yml` or `*.asyncapi.yml` file, review
+the spec before running generation. Actively look for these smells:
+
+- the same `success/timestamp/path/message` fields repeated in many response
+  schemas;
+- identical pagination `meta` objects or `PaginationMeta` definitions copied
+  across services instead of referencing a shared component;
+- many `id` parameters declared inline instead of referencing a shared
+  parameter;
+- inline UUID, date, date-time, URL, slug, or enum-like scalar constraints that
+  already exist in a shared component;
+- identical regex patterns copied into multiple schemas;
+- repeated day-of-week schedule structures;
+- error response schemas or problem-details bodies copied instead of referencing
+  shared responses;
+- event envelopes or AsyncAPI reply wrappers copied with the same product
+  meaning;
+- generated diffs adding many near-identical DTO/model files after a small API
+  change.
+
+When you see a smell, propose a shared component before generating.
+
+## When not to share
+
+Do not share only because two shapes currently look alike. Keep separate
+components when:
+
+- endpoints have different validation rules or lifecycle/backwards-compatibility
+  needs;
+- a request DTO and response DTO intentionally differ, even if fields overlap;
+- names would become vague (`CommonThing`, `BaseData`, `GenericConfig`);
+- sharing would force unrelated teams/domains to coordinate every future change.
+
+A good shared component has a clear product meaning and a stable owner.
+
+## Safe workflow
+
+1. Move the repeated shape into `schema/shared/*.yml` or a domain-level shared
+   component.
+2. Replace duplicated schemas/parameters/responses with `$ref`.
+3. Use supported `allOf` object composition when a concrete response extends a
+   shared base.
+4. Run `sumr kontract validate`.
+5. Run a scoped generation first, for example:
+
+```bash
+sumr kontract generate --source api --target backend --specific recipes/catalog
+```
+
+6. Review both the spec diff and generated diff. If generated output changed in
+   unrelated domains, stop and investigate before committing.

package/ai/modules/kontract/resources/scope-and-splitting.rf.md

@@ -0,0 +1,147 @@
+---
+category: reference
+name: scope-and-splitting
+title: Scope, Size, and Splitting
+description: "How to keep Kontract specs and generator code small, domain-aligned, and reviewable with explicit line-count budgets and split triggers."
+label: Scope and Splitting
+when: Reviewing large specs or code files, deciding whether to split a domain/subdomain spec, or optimizing oversized Kontract modules
+order: 18
+---
+
+# Scope, Size, and Splitting
+
+Kontract is the next iteration of the AutoSync/AsyncAPI idea: keep the
+documentation-first and DRY discipline, but make the boundaries more explicit.
+Large files are not automatically bad, but they hide duplicated concepts,
+mixed domains, and unstable generated output. Treat size limits as review
+triggers first and hard caps second.
+
+## Source-of-truth rule
+
+Put durable guidance in Playbook resources and module docs; generated editor
+rules should point back to those resources. Do not copy long rules into Cursor,
+Claude, Codex, or generated contracts. The source contract spec and the source
+Playbook resource are the maintained truth.
+
+## Public example hygiene
+
+Files under `resources/` become public AI guidance. Never use internal SUMR,
+customer, product, infrastructure, event-subject, route, table, or data-model
+examples there. Public examples must be sanitized and generic.
+
+Use neutral domains such as:
+
+- kitchen recipes and ingredients;
+- bookstore inventory;
+- parcel shipping;
+- job hierarchies and departments;
+- todos or calendar events.
+
+Prefer `example.*`, `recipes`, `orders`, `ingredients`, `jobs`, or similarly
+generic names. Do not use real service names, internal nouns, customer nouns,
+NATS subject prefixes, API paths, or entity relationships as examples. Internal
+examples are acceptable in private `docs/` only when they are necessary to
+explain the module's current behavior.
+
+## File size budgets
+
+| File kind | Healthy target | Review trigger | Split/optimize trigger | Hard stop |
+|---|---:|---:|---:|---:|
+| Kontract TypeScript source | <= 200 lines | > 250 lines | > 400 lines | > 500 lines |
+| OpenAPI/AsyncAPI service spec | 150-350 lines | > 400 lines | > 700 lines | > 1000 lines |
+| Shared component YAML | 100-300 lines | > 400 lines | > 600 lines | > 900 lines |
+| Generated TypeScript output | no manual target | review if surprising | fix generator/spec, never hand-split | no hand edits |
+
+Exceptions require a documented reason in the PR or handoff. Generated files,
+large fixtures, and intentionally dense compatibility snapshots are exempt from
+manual splitting, but they can still reveal generator or spec-design problems.
+
+## Split triggers
+
+Split or optimize before adding more content when a file shows any of these:
+
+- multiple product domains or subdomains in one spec;
+- more than roughly 7-10 operations with different lifecycle owners;
+- request/response schemas for unrelated use cases in one component block;
+- repeated envelope, pagination, error, scalar, schedule, or config shapes;
+- repeated operation patterns that should become shared parameters/responses;
+- a TypeScript file with orchestration, parsing, emitting, IO, and formatting
+  responsibilities mixed together;
+- a generated diff where a small spec change creates many near-identical files.
+
+Do not split only by line count. First identify the product or technical
+boundary that gives the new file a stable name and owner.
+
+## Domain and subdomain spec structure
+
+Use directory nesting to communicate product ownership. The path should answer
+"who owns this contract?" and the filename should answer "which surface is this?"
+
+```text
+schema/
+  shared/
+    scalars.yml
+    pagination.yml
+    errors.yml
+    events.yml
+    scheduling.yml
+  recipes/
+    recipes.openapi.yml
+    ingredients.openapi.yml
+    publishing.asyncapi.yml
+  kitchen/
+    stations.openapi.yml
+    prep-jobs.asyncapi.yml
+    inventory.asyncapi.yml
+```
+
+Guidelines:
+
+- Keep one entry-point spec per bounded API surface, not one giant file per
+  repo.
+- Split by product meaning: `recipes`, `ingredients`, `orders`, `jobs`, or
+  `inventory`, not by generic words like `common`, `misc`, or `helpers`.
+- Use `schema/shared/` only for cross-domain concepts with stable semantics and
+  an obvious owner.
+- Prefer domain-local shared components when a concept is reused only inside one
+  domain.
+- Keep `info.title` deliberate because AsyncAPI NATS namespaces derive from it;
+  filenames and titles should not drift semantically.
+- Keep `$ref` paths repo-relative and validate after moving files.
+
+## Refactor order for oversized specs
+
+1. Extract repeated cross-domain scalars, pagination, errors, envelopes, events,
+   schedules, and config objects into `schema/shared/`.
+2. Extract repeated domain-only shapes into a domain-local shared YAML file.
+3. Split operations by subdomain when the file still mixes independently owned
+   workflows.
+4. Validate the moved refs with `sumr kontract validate`.
+5. Generate with the smallest useful scope and review both the spec diff and
+   generated output diff.
+
+## Refactor order for oversized code
+
+1. Name the current responsibilities in the file.
+2. Extract pure helpers first, then emitters/readers, then orchestration.
+3. Move interfaces and types into `src/types/` or `*.types.ts`; logic files
+   should import types instead of declaring them inline.
+4. Move reusable constants to `src/lib/constants.ts` or the existing constants
+   module.
+5. Add or adjust focused tests around the extracted seam before broad rewrites.
+
+Prefer small safe extractions over a big rewrite. The goal is a clearer module
+boundary, not a larger abstraction layer.
+
+## Review checklist
+
+Before accepting a large spec or source file:
+
+- [ ] The file is under the healthy target, or the reason for exceeding it is
+      documented.
+- [ ] The file has one clear product/technical owner.
+- [ ] Shared concepts are referenced with `$ref` rather than copied.
+- [ ] No generic bucket names (`common`, `misc`, `utils`) hide unrelated
+      responsibilities.
+- [ ] Generated output changes match the intended API surface only.
+- [ ] Any split keeps spec and regenerated output committed together.

package/ai/modules/kontract/resources/spec-layout.rf.md

@@ -0,0 +1,69 @@
+---
+category: reference
+name: spec-layout
+title: Spec File Layout
+description: "Required folder and file conventions for Kontract OpenAPI/AsyncAPI source specs."
+label: Spec Layout
+when: Creating or moving API spec files, adding a shared base spec, or debugging why a spec is not picked up
+order: 10
+---
+
+# Spec File Layout
+
+Kontract discovers specs by filename convention under the configured schema
+directory (default `schema/`).
+
+```text
+schema/
+  recipes.openapi.yml           ← one OpenAPI doc per service/domain
+  recipes.asyncapi.yml          ← one AsyncAPI doc per service/domain
+  base.yml                      ← shared components, referenced via $ref
+```
+
+## Rules
+
+- OpenAPI specs end in `*.openapi.yml` / `*.openapi.yaml`.
+- AsyncAPI specs end in `*.asyncapi.yml` / `*.asyncapi.yaml`.
+- Discovery is recursive; `base.yml` is skipped as an entry point.
+- Service output paths mirror nested spec paths under the configured source
+  input directory.
+- Use nested domain/subdomain paths when one root file would mix independently
+  owned API surfaces; see the scope and splitting reference for line-count
+  thresholds and naming rules.
+- Share common schemas through `$ref` into `base.yml`. Do **not** duplicate
+  schemas across specs and do **not** merge by hand-mutating parsed JSON.
+- Prefer a `schema/shared/` folder for cross-domain components such as common
+  parameters, error responses, pagination, scalar constraints, response envelope
+  fragments, schedules, and reusable config objects.
+- The NATS namespace comes from the AsyncAPI `info.title`, not the filename —
+  set `info.title` deliberately.
+- Multi-file specs are bundled automatically (OpenAPI via Redocly core in-process
+  with CLI fallback, AsyncAPI via `@asyncapi/cli bundle`); keep `$ref` paths
+  repo-relative.
+
+## OpenAPI authoring rules
+
+- Put reusable HTTP payloads in `components.schemas`.
+- Operation request/response schemas should reference components with `$ref`.
+  Inline operation schemas are rejected so generated DTO/model names stay stable.
+- Prefer explicit object schemas over anonymous nested shapes when a payload is
+  shared by multiple operations.
+- If multiple responses repeat the same envelope fields, extract the envelope
+  fragment and compose concrete responses with supported object `allOf`.
+- If multiple schemas repeat the same regex or scalar validation, extract a
+  named scalar component and reference it.
+- Use stable `operationId` values. They become Swagger metadata constants such
+  as `SWG_LIST_RECIPES`.
+- Unsupported composition features (`oneOf`, `anyOf`, `not`, `discriminator`)
+  must either be modeled differently or implemented in Kontract before use.
+
+## AsyncAPI operation classification
+
+| AsyncAPI shape      | Generated client kind |
+|---------------------|-----------------------|
+| `receive` + `reply` | Query                 |
+| `receive`           | Command               |
+| `send`              | Event                 |
+
+Run `sumr kontract validate` after any layout change to confirm specs still
+resolve before generating.

package/ai/modules/kontract/resources/team-members/contract-author.tm.md

@@ -0,0 +1,52 @@
+---
+category: team-member
+name: contract-author
+title: Contract Author
+description: "Owns API spec authoring and Kontract regeneration discipline: edits OpenAPI/AsyncAPI specs, validates, regenerates, and keeps generated contracts consistent without hand-editing outputs."
+modelTier: reasoning
+channels:
+  codex:
+    sandbox_mode: workspace-write
+---
+
+# Contract Author
+
+You own the API contract source of truth for this repo. You change YAML specs
+and let Kontract generate the TypeScript — you never hand-write or hand-patch
+generated contracts.
+
+Apply the generated **sumr-kontract-usage** skill, plus the configuration,
+spec-layout, schema-reuse, scope-and-splitting, and generated-output
+references, before acting.
+
+## Responsibilities
+
+- Translate API requirements into OpenAPI/AsyncAPI specs under `schema/`.
+- After writing or updating any `*.openapi.yml` / `*.asyncapi.yml` file, review
+  it against Kontract reuse, layout, and generation rules before validating.
+- Keep shared shapes in shared component files and reference them with `$ref`.
+- Keep specs domain-aligned and reviewable: use domain/subdomain paths, split
+  oversized files at documented thresholds, and avoid generic `common` buckets
+  for unrelated concepts.
+- Proactively spot duplicated envelope fields, pagination metadata, error
+  schemas, path/query params, regex scalar constraints, schedules, and config
+  objects before generating.
+- Prefer supported object `allOf` composition when a concrete response extends
+  a shared base envelope.
+- Run `sumr kontract validate` then `sumr kontract generate` for every change.
+- Review the generated diff for correctness and unintended breakage.
+- If a generated diff creates many near-identical DTO/model files, pause and
+  propose a spec-level shared component refactor.
+- Keep spec + regenerated output committed together.
+- When generated files are missing, check `sumr.yaml` target options and the
+  installed `SUMR Kontract module` version before changing application code.
+
+## Boundaries
+
+- Never edit files under the generated `contracts/` output.
+- Never hand-write Zod schemas, DTOs, NATS subjects, or clients that Kontract owns.
+- Do not introduce a second source of truth; the spec is authoritative.
+- Do not over-share unrelated concepts only because their current fields look
+  similar; shared components must have the same product meaning and owner.
+- Flag breaking contract changes for human review before commit.
+- Scope `--clean` to the intended source/target in consumer repos.

package/ai/modules/kontract/resources/workflows/contract-change.wf.md

@@ -0,0 +1,60 @@
+---
+category: workflow
+name: contract-change
+title: Contract Change
+description: "Guides an AI agent through safely changing an API spec and regenerating Kontract contracts."
+---
+
+# Contract Change
+
+Use this workflow whenever an API surface changes (new endpoint, message,
+field, or breaking change) and the generated contracts must follow.
+
+## Flow
+
+```text
+🕐 edit spec -> review spec -> validate -> generate -> review diff -> ⏸ HUMAN APPROVES -> commit
+```
+
+## Steps
+
+1. **Edit the spec** under `schema/` (`*.openapi.yml` / `*.asyncapi.yml`).
+   Before adding new schemas, scan for existing shared components. Reuse shared
+   components via `$ref`; never duplicate schemas.
+2. **Review the written spec** before validation. Check new or changed
+   `*.openapi.yml` / `*.asyncapi.yml` files against Kontract best practices:
+   stable component names, no inline operation payload schemas, correct `$ref`
+   paths, reusable shared components, domain/subdomain boundaries, documented
+   size thresholds, and no copy-pasted product concepts.
+3. **Refactor repeated shapes first**. If the change repeats envelope fields,
+   pagination metadata, error bodies, ID/date params, regex scalar constraints,
+   schedules, or config objects, extract a shared component and reference it.
+4. **Validate**: `sumr kontract validate` (scope with `--source` if large).
+   Fix every reported error before continuing.
+5. **Generate**: `sumr kontract generate`. Unchanged specs are skipped.
+   Scope large repos with `--source`, `--target`, or `--specific`.
+6. **Review the diff** of the generated `contracts/` output. Confirm
+   `http/models`, `http/enums`, `http/zod`, optional `http/dto`,
+   optional `http/swagger.ts`, and NATS `SUBJECTS` match the intended change;
+   watch for unintended removals. If the diff introduces many near-identical
+   generated files, return to the spec and look for a shared component.
+7. **Do not edit generated files** to "fix" the diff — change the spec and
+   regenerate instead.
+8. **Commit** the spec change and the regenerated output together so they
+   never drift.
+
+## Transition rules
+
+- Do not run `validate` or `generate` until the changed spec has been reviewed
+  for avoidable duplication and unsupported patterns.
+- Do not run `generate` until `validate` passes clean.
+- If the generated diff is unexpected, return to the spec — not the output.
+- Treat a breaking contract change as requiring human approval before commit.
+- If files that should exist are missing, compare `sumr.yaml` generator options
+  and the installed `SUMR Kontract module` version before changing application code.
+- Use `--clean` only when you intend to remove selected generated output/cache
+  before regeneration. Prefer scoped clean commands in consumer repos:
+
+```bash
+sumr kontract generate --source api --target backend --clean
+```

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

@@ -0,0 +1,42 @@
+apiVersion: sumr.dev/v1
+kind: CliModule
+metadata:
+  name: kontract
+  package: "@sumrco/cli"
+  description: Generate and validate API contract code
+  owners:
+    - team: "@sumr-org/kontract-team"
+  tags:
+    - contracts
+    - openapi
+    - asyncapi
+spec:
+  visibility: public
+  group: modules
+  targets:
+    contractVersion: ^1.0.0
+    bunVersion: ">=1.1.0"
+  commands:
+    - name: init
+      summary: Activate Kontract AI guidance for this workspace
+      visibility: public
+    - name: generate
+      summary: Generate TypeScript contracts from API specs
+      visibility: public
+    - name: validate
+      summary: Validate API specifications
+      visibility: public
+  exports:
+    resources: []
+    binaries: []
+    aiResources:
+      module: kontract
+      roots:
+        - ./resources
+      activation:
+        mode: command
+        initCommand: kontract init
+        key: kontract
+  flags:
+    experimental: false
+    deprecated: null

package/ai/modules/mission/resources/flow-actions.rf.md

@@ -0,0 +1,40 @@
+---
+name: flow-actions
+title: Mission Flow Actions
+description: "Canonical Mission action IDs and what each action means."
+label: Flow Actions
+when: Mapping Mission next actions to commands, reports, PR previews, or closeout
+order: 20
+---
+
+# Mission Flow Actions
+
+Known action IDs:
+
+```text
+issue.sync
+context.research
+plan.create
+plan.approve
+branch.check
+work.claim
+implementation.report
+review.report
+validation.report
+quality.gate
+pr.prepare
+pr.create
+mission.close
+```
+
+`issue.sync` is not only identifier normalization. For tracker-backed work it
+requires reading the work item title, description/body, acceptance criteria,
+todos/checklists, linked docs, comments/discussion, and attachments or embedded
+images/screenshots. Comments are part of the source of truth because they often
+contain decisions, updated errors, blockers, and scope changes.
+
+`branch.check` must confirm the implementation branch before claim or PR work. Use any stored Mission branch or claim branch as the default branch. If the current checkout differs, switch to the stored branch or ask before intentionally reclaiming the Mission. Check local and remote branches and open PRs for the issue key when those tools are available.
+
+Do not skip directly to implementation when `plan.approve` is pending. Do not create a PR when validation or quality evidence is missing unless the user explicitly asks for a draft or preview.
+
+Use `sumr mission next` as the source of truth for the next action.

package/ai/modules/mission/resources/flow-config.rf.md

@@ -0,0 +1,39 @@
+---
+name: flow-config
+title: Mission Flow Config
+description: "How Mission reads sumr.yaml flow config, presets, step order, and transition policies."
+label: Flow Config
+when: Reading, changing, or explaining Mission flow behavior
+order: 10
+---
+
+# Mission Flow Config
+
+Mission flow is repo configuration in `sumr.yaml`; runtime state stays in `.sumr-cache/mission`.
+
+```yaml
+mission:
+  tracker:
+    provider: github
+  git:
+    provider: github
+    prMode: ask
+  flow:
+    preset: standard-delivery
+    steps:
+      - uses: plan.create
+        advance: auto
+      - uses: plan.approve
+        advance: human
+```
+
+Use only known action IDs. Do not invent actions, shell commands, graph edges, or tracker mutations.
+
+Transition policies:
+
+- `auto`: continue when the action is already satisfied.
+- `ask`: ask before continuing.
+- `human`: stop until explicit human approval.
+- `manual`: wait for a command, report, or user action to satisfy the step.
+
+When a mission starts, the active flow is snapshotted into mission state. Later YAML edits should not silently rewrite older missions.