@jterrats/open-orchestra 1.0.2 → 1.0.3

package/docs/site-content-workflow.md

@@ -0,0 +1,96 @@
+# Public Site Content Workflow
+
+The public site is a generated documentation surface. The source of truth stays
+in versioned documentation, while React renders a compact generated content
+module.
+
+## Source Of Truth
+
+- `docs/site-manifest.json` defines the public-site navigation, source
+  documents, section headings, launch links, and role labels used by the site.
+- `README.md` and focused documents under `docs/` provide the public copy that
+  appears on the site.
+- `scripts/generate-site-content.js` reads the manifest and referenced
+  markdown, validates headings, extracts concise public copy, and writes
+  `site/src/generated-site-content.js`.
+- `site/src/App.jsx` consumes `siteContent` from the generated module. It should
+  not own long-form public copy, command lists, launch links, persona labels, or
+  documentation summaries directly.
+
+This keeps docs and site copy aligned. To change public site wording, update the
+authoritative markdown or the manifest structure, then regenerate the site
+content.
+
+## Diagram Contract
+
+The architecture diagram has two public sources that must stay aligned:
+
+- `site/public/architecture.mmd` is the Mermaid file served by the React + Vite
+  site.
+- `docs/architecture.md` embeds the same Mermaid diagram for markdown readers
+  and links back to the served source.
+
+When the site diagram changes, update both files in the same task and validate
+the rendered site. Diagram changes should follow the reusable quality rules in
+`docs/diagrams/diagram-master-prompt.md`: readable labels, visible connector
+endpoints, contained text, balanced spacing, and a whole-canvas recheck after
+each correction.
+
+## Local Commands
+
+Regenerate generated site content:
+
+```bash
+npm run site:content
+```
+
+Build the public site:
+
+```bash
+npm run site:build
+```
+
+Run the local public site:
+
+```bash
+npm run site:dev
+```
+
+The `site` workspace also regenerates content before `npm run dev` and
+`npm run build`, so local preview and production builds use the same generated
+content path.
+
+## Required Review
+
+Use Technical Writer review for work that touches user-facing documentation or
+site copy. The existing `technical_writer` role owns user docs, technical docs,
+runbooks, release notes, help content, support-facing copy, and documentation
+blocking authority.
+
+Technical Writer review is required when a task changes:
+
+- `README.md`;
+- public docs under `docs/`;
+- changelog or release notes;
+- public site copy, launch links, command examples, or persona labels;
+- help content, runbooks, migration guidance, or support-facing docs.
+
+The workflow phase planner recommends `docs_review` for docs, README,
+changelog, public site, site copy, and help-content changes. The review should
+confirm audience fit, source-of-truth ownership, link correctness, command
+accuracy, generated-content alignment, and whether release notes are needed.
+
+## QA Evidence
+
+For public site or docs-driven content changes, attach evidence for:
+
+- `npm run site:build`;
+- `npm run lint` when code, generated files, or docs formatting are touched;
+- `npm run build` when package-level build contracts may be affected;
+- Playwright screenshots for desktop and mobile when layout, diagrams, or
+  visible site content changes;
+- manual visual review of responsive spacing, text wrapping, diagram rendering,
+  and horizontal overflow.
+
+If a visual issue is found, fix it, regenerate content if needed, re-render, and
+capture fresh screenshots before handoff.

package/docs/site-manifest.json

@@ -0,0 +1,143 @@
+{
+  "repositoryUrl": "https://github.com/jterrats/open-orchestra",
+  "packageUrl": "https://www.npmjs.com/package/@jterrats/open-orchestra",
+  "nav": [
+    { "href": "https://jterrats.dev", "label": "Main site" }
+  ],
+  "pages": [
+    {
+      "path": "/",
+      "label": "Home",
+      "title": "Start with governed local delivery",
+      "sections": ["hero", "quickstart", "capabilities"]
+    },
+    {
+      "path": "/docs",
+      "label": "Docs",
+      "title": "Documentation map",
+      "sections": ["docsCatalog"]
+    },
+    {
+      "path": "/console",
+      "label": "Web Console",
+      "title": "Local web console",
+      "sections": ["consoleGuide"]
+    },
+    {
+      "path": "/personas",
+      "label": "Personas",
+      "title": "Work by role",
+      "sections": ["personas", "workflow"]
+    },
+    {
+      "path": "/architecture",
+      "label": "Architecture",
+      "title": "Architecture and system boundaries",
+      "sections": ["architecture"]
+    },
+    {
+      "path": "/release",
+      "label": "Release",
+      "title": "Release readiness",
+      "sections": ["releaseGuide"]
+    },
+    {
+      "path": "/reference",
+      "label": "Reference",
+      "title": "Command and integration reference",
+      "sections": ["referenceGuide"]
+    }
+  ],
+  "hero": {
+    "source": "README.md",
+    "heading": "Open Orchestra"
+  },
+  "quickstart": {
+    "source": "README.md",
+    "heading": "First Visible Value"
+  },
+  "capabilities": {
+    "source": "README.md",
+    "heading": "Core Product Surface"
+  },
+  "architecture": {
+    "source": "docs/architecture.md",
+    "heading": "Architecture"
+  },
+  "personas": {
+    "source": "docs/persona-workflows.md",
+    "headings": [
+      { "heading": "Product Owner Refinement", "label": "PO" },
+      { "heading": "Developer Execution", "label": "Dev" },
+      { "heading": "QA Validation", "label": "QA" },
+      { "heading": "Tech Lead Oversight", "label": "TL" },
+      { "heading": "Release Management", "label": "RM" },
+      { "heading": "Technical Writer Review", "label": "TW" }
+    ]
+  },
+  "workflow": {
+    "source": "docs/orchestra-mvp.md"
+  },
+  "launch": {
+    "links": [
+      {
+        "title": "Install",
+        "label": "npm",
+        "href": "https://www.npmjs.com/package/@jterrats/open-orchestra",
+        "source": "README.md",
+        "heading": "Quick Start"
+      },
+      {
+        "title": "Quickstart",
+        "label": "README",
+        "href": "https://github.com/jterrats/open-orchestra#quick-start",
+        "source": "README.md",
+        "heading": "First Visible Value"
+      },
+      {
+        "title": "Release matrix",
+        "label": "docs/release-test-matrix.md",
+        "source": "docs/release-test-matrix.md",
+        "heading": "1.0.0 Release Test Matrix"
+      },
+      {
+        "title": "Runtime adapters",
+        "label": "docs/runtime-adapters.md",
+        "source": "docs/runtime-adapters.md",
+        "heading": "Runtime Adapters"
+      }
+    ]
+  },
+  "docs": {
+    "links": [
+      { "title": "Adoption guide", "source": "docs/adoption-guide.md", "heading": "Open Orchestra 1.0.0 Adoption Guide" },
+      { "title": "Core command surface", "source": "docs/core-command-surface.md", "heading": "Core Command Surface" },
+      { "title": "Runtime adapters", "source": "docs/runtime-adapters.md", "heading": "Runtime Adapters" },
+      { "title": "Site content workflow", "source": "docs/site-content-workflow.md", "heading": "Public Site Content Workflow" }
+    ]
+  },
+  "releaseDocs": {
+    "links": [
+      { "title": "Release test matrix", "source": "docs/release-test-matrix.md", "heading": "1.0.0 Release Test Matrix" },
+      { "title": "QA evidence", "source": "docs/site-content-workflow.md", "heading": "QA Evidence" },
+      { "title": "Package naming", "source": "docs/package-naming.md", "heading": "Package Naming Decision" },
+      { "title": "Upgrade dogfooding", "source": "README.md", "heading": "Quick Start" }
+    ]
+  },
+  "console": {
+    "links": [
+      { "title": "Web console QA", "source": "docs/web-console-qa.md", "heading": "Web Console QA Notes" },
+      { "title": "Local web console", "source": "docs/orchestra-mvp.md", "heading": "Commands" },
+      { "title": "Workflow progress API", "source": "README.md", "heading": "1.0.0 Workflow Tooling" },
+      { "title": "Delivery dashboard", "source": "docs/adoption-guide.md", "heading": "Release Operations" }
+    ]
+  },
+  "reference": {
+    "links": [
+      { "title": "Command contracts", "source": "docs/command-contracts.md", "heading": "Command Contracts" },
+      { "title": "Runtime LLM flow", "source": "docs/runtime-llm-flow.md", "heading": "Runtime LLM Flow" },
+      { "title": "Tracker adapter contract", "source": "docs/tracker-adapter-contract.md", "heading": "Tracker Adapter Contract" },
+      { "title": "Source of truth and learning", "source": "docs/source-of-truth-and-agent-learning.md", "heading": "Source of Truth and Agent Learning" }
+    ]
+  }
+}

package/docs/skill-loading-strategy.md

@@ -46,12 +46,22 @@ Skill manifests should be able to declare `sourceGroups` so the orchestrator can
 
 1. Parse the task brief into goal, touched paths, impacted systems, requested outputs, risk areas, and likely roles.
 2. Activate roles from the role catalog.
-3. Match task signals against skill manifests by triggers, paths, roles, capabilities, and risk areas.
-4. Load only the selected skill summaries first.
-5. Load the full `SKILL.md` only when the skill is needed for execution or review.
-6. Load matching source-of-truth entries and recent relevant lessons for the selected skills.
-7. Load skill assets, templates, scripts, or examples only at the point of use.
-8. Record selected skills and source groups in task context, handoffs, evidence, and final summary.
+3. Match task signals against skill manifests by triggers, paths, runtime phase, requested evidence, and risk areas.
+4. Use roles and capabilities as eligibility and ranking signals, not as automatic activation. A role may be allowed to use a skill without loading it for every task owned by that role.
+5. Load only the selected skill summaries first.
+6. Load the full `SKILL.md` only when the skill is needed for execution or review.
+7. Load matching source-of-truth entries and recent relevant lessons for the selected skills.
+8. Load skill assets, templates, scripts, or examples only at the point of use.
+9. Record selected skills and source groups in task context, handoffs, evidence, and final summary.
+
+## Runtime Activation
+
+Skill planning separates availability from activation:
+
+- **Available:** the role and capability catalog says a profile is allowed to use a skill.
+- **Activated:** the current task, phase, risks, acceptance criteria, evidence needs, touched paths, or explicit user request require that skill now.
+
+For example, Architect can use `qa-evidence-pack` to validate ADRs, diagrams, contracts, and architecture decisions, but it should only load that skill when the task asks for QA evidence, acceptance coverage, integration verification, visual evidence, or release evidence. The same rule applies to every profile: QA, Developer, DevOps, SRE, PO, BA, Release, and specialist roles should receive only the skills needed for the active runtime context.
 
 ## Built-in Skill Candidates
 
@@ -92,7 +102,8 @@ Primary MD files should stay bounded:
 ## Implemented CLI Surface
 
 - `orchestra skills list` lists the canonical built-in skill catalog.
-- `orchestra skills plan --task <id>` selects skills from task text, owner role, paths, risks, and source groups.
+- `orchestra skills plan --task <id>` selects skills from runtime task signals, paths, risks, acceptance/evidence needs, and role/capability eligibility.
+- `orchestra skills advise --prompt <text> [--role <role>] [--phase <phase>] [--risks <csv>] [--evidence <csv>] [--json]` selects skills from advisory or prompt-only runtime signals without requiring a registered task first.
 - `orchestra skills render --target generic|claude|cursor|codex|vscode --task <id>` renders selected skills for a runtime or IDE.
 - `orchestra skills render --target <target> --skills <csv>` renders explicit skills when no task exists.
 - `orchestra skills validate` validates canonical skills against portable `manifest.json` and `SKILL.md` files.

package/docs/story-mapping-adoption-review.md

@@ -0,0 +1,99 @@
+# Story Mapping Adoption Review
+
+Task: STORY-MAPPING-SKILL-ADOPTION
+Date: 2026-05-16
+
+## Current Assessment
+
+Open Orchestra has partial story map support in `src/lucid-story-map.ts`:
+
+- deterministic Lucidspark payload creation.
+- stable IDs for capabilities, features, business stories, and technical stories.
+- update/reflow diff support.
+- grouping banner reflow tests in `test/lucid-story-map.test.js`.
+
+The reviewed external baseline has a broader reusable Story Mapping skill:
+
+- Jeff Patton-style markdown template.
+- personas, epics, user stories, priorities, and Gherkin acceptance criteria.
+- Mermaid story map generation rules.
+- Mermaid PDF rendering script and truncation-safe CSS.
+- Lucidspark board constants, color map, layout zones, cache contract, update mode,
+  reflow mode, conflict handling, grouping banner resizing, and UTF-8 title safety.
+
+Conclusion: Open Orchestra has the engine-level Lucidspark payload foundation, but
+does not yet expose Story Mapping as a first-class skill/workflow capability.
+
+## Reusable Patterns
+
+Bring these patterns into Open Orchestra:
+
+- `story-mapping` skill metadata and trigger routing for `story map`, `story mapping`,
+  `epic breakdown`, `backlog visualization`, and `release planning map`.
+- Markdown story map template with personas, priority legend, epics, user stories, and
+  acceptance criteria.
+- Mermaid story map output path for lightweight offline rendering and evidence.
+- PDF/SVG render validation that checks for parser failures and suspiciously small output.
+- Lucidspark cache contract for create/update/reflow operations.
+- Conflict rules: preserve untracked board items, require confirmation before deletes,
+  and preserve manual positions during update mode.
+- UTF-8 title safety for Lucid MCP document titles.
+
+## Existing Open Orchestra Strengths
+
+Do not replace these existing Open Orchestra rules:
+
+- `src/lucid-story-map.ts` already has a narrow typed payload model and tests.
+- `skills/diagram-export/SKILL.md` already includes the newer high-fidelity diagram
+  rules added during UML recreation: diagram contracts, post-render visual QA,
+  connector endpoint checks, line crossing review, editable/rendered equivalence, and
+  source-free validation.
+- `rules/diagram-quality.mdc` already captures stricter draw.io/SVG fidelity rules
+  than the external baseline.
+
+## Suggested Adoption Scope
+
+1. Add `skills/story-mapping/SKILL.md` and `manifest.json`.
+2. Register `story-mapping` in `src/skills-catalog.ts` for product owner, product
+   manager, analyst/business analyst, architect, and UX/UI designer roles.
+3. Add markdown-to-story-map parsing or a documented source JSON contract that feeds
+   `createLucidsparkStoryMap`.
+4. Add local Mermaid `.mmd` generation for story maps so offline agents can produce
+   evidence without Lucid.
+5. Add render evidence helpers using the existing `orchestra diagrams lint` path where
+   Mermaid is used.
+6. Extend tests to cover markdown template generation, Mermaid source generation,
+   Lucidspark cache behavior, update mode, delete confirmation, and reflow.
+
+## Diagram Rules Comparison
+
+External baseline diagram rules to consider:
+
+- Salesforce Architect diagram type decision matrix.
+- schema-first Lucid MCP payload workflow.
+- one-call-per-diagram Lucid creation.
+- post-write Lucid validation for duplicates, icon-text gaps, bounds, phantom text,
+  and orphan items.
+- multi-page diagram payload guidance.
+- token-efficient visual editing guidance: push to visual tools and avoid chat-only
+  pixel nudging where a visual tool is available.
+
+Open Orchestra already has:
+
+- diagram lint command and evidence recording.
+- prompt registry coverage for `diagrams.md`.
+- high-fidelity draw.io/SVG quality rules from the UML recreation iterations.
+- source-free diagram contract requirement.
+
+Recommendation: merge external baseline Lucid-specific operational checks and story-map
+skill model into Open Orchestra, but keep Open Orchestra's stricter high-fidelity
+diagram QA rules as the master visual quality layer.
+
+## Open Questions
+
+- Should Story Mapping be a CLI command (`orchestra story-map ...`) or remain a skill
+  invoked by workflow roles?
+- Should markdown be the source of truth, or should Open Orchestra use a typed JSON
+  source file and generate markdown/Mermaid/Lucidspark from it?
+- Should Lucid/Lucidspark cache files live in `docs/story-map/.cache/` or under
+  `.agent-workflow/artifacts/story-map/`?

package/docs/workspace-repo-strategy.md

@@ -0,0 +1,63 @@
+# Workspace And Repository Strategy
+
+## Current Position
+
+Open Orchestra uses npm workspaces while the package, web console, public site,
+and VS Code extension are still evolving together.
+
+This keeps local development coherent:
+
+- one root install;
+- one lockfile;
+- one build/test surface for release validation;
+- shared issue, workflow, and evidence history;
+- simpler refactors while contracts are still changing.
+
+## Future Direction
+
+Move workspace packages to independent repositories when their release cadence,
+ownership, or distribution channels become meaningfully independent.
+
+Likely split candidates:
+
+- `site`: public/docs site, deployable independently.
+- `web-console`: React/Vite console if it becomes a standalone app or SaaS
+  frontend.
+- `extensions/vscode-open-orchestra`: VS Code marketplace extension with its own
+  packaging, versioning, and release checks.
+- SaaS services or prompt registry components when they need separate runtime,
+  scaling, security, or deployment ownership.
+
+## Split Criteria
+
+Consider extracting a workspace when at least one is true:
+
+- it has a different release cadence from the CLI package;
+- it has a different deployment target or CI/CD pipeline;
+- it needs separate access control, secrets, or infrastructure ownership;
+- it has a distinct package registry or marketplace release process;
+- changes frequently require isolated review or rollback;
+- its dependency graph materially conflicts with the root package;
+- external contributors should work on it without touching CLI internals.
+
+## Non-Goals For Now
+
+- Do not split repositories before package boundaries and contracts stabilize.
+- Do not duplicate shared workflow rules across repos manually.
+- Do not move code only to reduce directory count.
+
+## Migration Guardrails
+
+Before extracting a workspace:
+
+- define the public contract between the CLI and the extracted package;
+- move shared types or protocol definitions into a versioned package or schema;
+- preserve issue/task traceability across repos;
+- keep release notes and compatibility expectations explicit;
+- ensure local/offline development remains possible;
+- keep Open Orchestra managed instruction blocks project-local and non-invasive.
+
+## Decision
+
+Use npm workspaces now. Plan for independent repositories later, once package
+boundaries, release cadence, ownership, and deployment needs justify the split.

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "workspaces": [
+    "extensions/vscode-open-orchestra",
     "site",
     "web-console"
   ],
@@ -28,6 +29,7 @@
     "build:web": "npm run build:web:legacy && npm run build:web:react",
     "build:web:legacy": "esbuild src/web-console-client.js --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/assets/web-console.js",
     "build:web:react": "npm --workspace @jterrats/open-orchestra-web-console run build",
+    "site:content": "node scripts/generate-site-content.js",
     "site:build": "npm --workspace @jterrats/open-orchestra-site run build",
     "site:dev": "npm --workspace @jterrats/open-orchestra-site run dev -- --host 127.0.0.1"
   },

package/rules/agent-collaboration.mdc

@@ -22,6 +22,8 @@ Agents must collaborate through explicit artifacts and review checkpoints. Paral
 
 ## Collaboration Flow
 - Product Owner and Analyst define acceptance criteria before Developer or QA treat the task as ready.
+- Product Owner and Business Analyst must validate user stories, definitions, assumptions, acceptance criteria, non-goals, and priority with the user before approving the `po→architect` handoff.
+- If user validation is missing or scope is still ambiguous, keep the task in refinement, record the open question, and do not route it to Architect as ready-for-design.
 - Architect and Security review designs before implementation when work touches boundaries, data, auth, infra, or external integrations.
 - UX/UI Designer reviews user-facing flows before implementation when the task changes screens, copy, navigation, onboarding, or accessibility.
 - SRE, DBA, Compliance/Privacy, and Release Manager review before release when reliability, database, regulatory, or rollout risk is material.

package/rules/code-review-engineering.mdc

@@ -14,6 +14,7 @@ Code review protects behavior, users, operations, and maintainability. Review ri
 - Confirm evidence: commands run, screenshots, logs, traces, benchmarks, or QA results when relevant.
 
 ## Required Checks
+- Module boundaries: file size, responsibility, layer placement, command/controller thinness, and god-file risk.
 - API changes: contract, compatibility, auth, validation, rate limits, and error shape.
 - Data changes: migrations, indexes, constraints, backfills, rollback, and sensitive data handling.
 - UI changes: responsive layout, accessibility, copy, states, and screenshots.
@@ -29,6 +30,7 @@ Code review protects behavior, users, operations, and maintainability. Review ri
 
 ## Self-Review
 - Authors must review their own diff before requesting review.
+- Authors must confirm large-file additions, command-module logic, and repeated hardcoded collections were either avoided, extracted, or recorded as explicit debt.
 - Remove debug code, dead code, unrelated formatting, and accidental files.
 - Summarize architectural decisions, trade-offs, test evidence, and known gaps in the PR.
 - Confirm static analysis and required hooks passed before requesting review.

package/rules/delivery-quality-gates.mdc

@@ -8,6 +8,7 @@ alwaysApply: true
 Development work is not complete when code compiles. Every implementation must move through developer verification, QA review, automation planning, and evidence capture.
 
 ## Developer Gate
+
 - Developer delivers code with unit tests for new or changed business logic.
 - Unit tests must cover success paths, failure paths, and relevant boundary cases.
 - Developer must run the focused unit test suite and report the exact command and result.
@@ -15,25 +16,36 @@ Development work is not complete when code compiles. Every implementation must m
 - Developer must address API, data, frontend, performance, concurrency, config, and AI-assisted development rules when the change touches those areas.
 
 ## QA Gate
+
 - QA receives the Developer handoff before release approval.
 - QA must produce a test plan covering acceptance criteria, regression areas, edge cases, data setup, and environment assumptions.
 - QA must execute or explicitly defer each test case with a reason.
 - QA findings must include severity, reproduction steps, expected result, actual result, and evidence.
+- QA execution must be reviewable through a sprint-review-style evidence demo before release approval. Analyst/BA compares the executed evidence against the GitHub issue, user story, acceptance criteria, and Orchestra task; Architect reviews whether the tests cover architecture contracts, boundaries, integrations, data flow, and risk areas.
+- Analyst/BA must record comments on the GitHub issue/user story and the Orchestra task when evidence does not prove the requested behavior, acceptance criteria, or business workflow. Those findings block release until fixed or explicitly accepted as risk by the Product Owner.
+- QA approval is incomplete when only QA signs off on execution. Record Analyst/BA and Architect review outcomes, or document why a role is not applicable with Product Owner acceptance.
 
 ## Automation Gate
+
 - QA and Developer must identify which manual checks should become automated tests.
 - Prefer Playwright for browser-based E2E, smoke, and regression flows.
 - Use Page Object pattern for Playwright suites. Selectors belong in page objects or stable test helpers, not scattered through test bodies.
 - Automated tests must be deterministic and avoid real network, clock, or randomness unless controlled by fixtures, mocks, or seeded data.
 
 ## Evidence Gate
+
 - Every completed delivery must include test evidence: commands run, pass/fail result, logs or screenshots when relevant, and unresolved risks.
+- Evidence must be packaged for human review, not only recorded as command status. Use compact reports that map acceptance criteria to tests, results, and artifact paths.
 - Playwright evidence should include trace, screenshot, or video for failed E2E cases when the framework supports it.
 - User-facing delivery should include screenshots or recordings for key responsive breakpoints when practical.
 - Manual QA evidence should include tested build/version, environment, browser/device when relevant, and timestamp.
+- CLI evidence must include command, exit code, expected stdout/stderr or final state, actual result, and relevant files/events.
+- API and integration evidence must include contract results and receiver-side verification such as sandbox records, webhook/event/log output, database/query result, or a documented deferral with owner and Product Owner acceptance.
+- Visual/UI/diagram bug evidence must include actual screenshot/render, source or expected image when available, diff when practical, and annotated image overlays for ambiguous layout, spacing, alignment, clipping, connector, or text-fit issues.
 - Release approval requires visible evidence from Developer and QA, not just a verbal status.
 
 ## Release Decision
+
 - Product Owner gives go/no-go using QA results, automation status, unresolved defects, and risk acceptance.
 - Security, DevOps, or QA blockers cannot be bypassed without explicit Product Owner risk acceptance.
 - A delivery with deferred tests must include the follow-up backlog item and owner before release.

package/rules/development-engineering.mdc

@@ -12,6 +12,8 @@ Developer work must start from the existing project shape, preserve the local ar
 - Infer naming, layering, dependency direction, error style, logging style, and test conventions from nearby code.
 - Do not introduce a new framework pattern, repository style, package layout, or dependency injection approach without a recorded architecture decision.
 - Keep framework-specific adapters at the boundary. Domain and service code should remain portable where the product permits it.
+- Before writing to an existing file, run a module-boundary check: current file size, responsibility, exported surface, and whether the new behavior belongs in domain, model, service, repository, or adapter code.
+- Do not increase god-file risk. If a file is already large, multi-purpose, or adapter-shaped, prefer adding a focused module and wiring it from the existing entry point instead of adding more logic.
 
 ## Entry Points And Layers
 - Controllers, routes, commands, triggers, handlers, jobs, and webhooks must stay thin.
@@ -19,6 +21,7 @@ Developer work must start from the existing project shape, preserve the local ar
 - Keep request parsing, authorization, validation, orchestration, and persistence responsibilities separate enough that each can be tested directly.
 - Public APIs and CLI commands must define request, response, errors, pagination, compatibility, and idempotency before implementation.
 - Developer-owned code, scripts, generated options, and automation helpers that repeat collection values or process collections at scale must load the `collection-standards` skill.
+- CLI command modules should be nearly logicless: parse input, call one service or use-case, format output, and convert expected errors to user-safe messages. Business rules, workflow policy, persistence, retries, batching, and duplicated registries belong outside command modules.
 
 ## Bulk And Batch Safety
 - Implement for 1..N records, requests, files, events, or messages. Do not special-case only the happy-path singleton.

package/rules/diagram-quality.mdc

@@ -0,0 +1,35 @@
+# Diagram Quality
+
+- Classify diagram work before drawing: `semantic`, `inspired-by-reference`, or `recreation`.
+- A `recreation` must be reviewed as pixel-perfect against its source reference. Do not treat structural similarity as acceptance.
+- For `recreation`, first inventory every visible source element: containers, labels, icons, connectors, arrowheads, line styles, colors, borders, spacing, rotations, z-order, and page/canvas bounds.
+- For `recreation`, compare the rendered output against the source after every iteration and record source-vs-output gaps by element ID or visual region.
+- If a `recreation` cannot be made pixel-perfect with the chosen target, reclassify it as an approximation, state the reason, and list residual fidelity gaps before handoff.
+- High-fidelity diagram work must include a post-render visual QA pass before handoff.
+- Re-evaluate container width, height, text fit, spacing, and visual balance after real labels are placed.
+- Run global layout reflow after the diagram is populated with real content. Recalculate whether parent containers, swimlanes, grouped boxes, and cards must grow to contain child nodes, subcards, chips, icons, labels, and internal connectors with minimum padding.
+- When a parent container grows, re-evaluate neighboring element positions, connector routes, label lanes, and page/canvas bounds. Do not accept a local fix that creates a new collision elsewhere.
+- Treat text wrapping as a geometry change. After a label, pill, badge, note, callout, or card text wraps, recalculate its rendered bounding box and revalidate connector lanes, parent containment, neighboring labels, and page bounds.
+- Text wrapping or smaller text is not the default fix for overflow. Prefer growing the containing element or repositioning children unless the source reference explicitly uses tighter text.
+- Avoid connector lines crossing over containers, labels, or important symbols whenever practical.
+- Use bend points and explicit connector routing when straight lines make the diagram harder to read.
+- Prefer the simplest readable connector route: straight if line-of-sight is clear, one orthogonal bend when needed, and curves or multi-bend paths only when avoiding a real obstacle or crossing.
+- Validate every connector endpoint visually: the line must start at the source element edge and terminate at the intended target element edge, not float near it or end deep inside the shape.
+- Validate label clearance after rendering; labels must not sit on container borders, connector lines, or arrowheads unless the source explicitly requires that overlap.
+- Validate connector-label lanes after rendering; labels must sit in intentional whitespace or have an explicit readable background. Move nodes, reroute connectors, or move labels when a label touches or visually collides with a connector.
+- Validate element order after rendering; connectors and arrowheads must not be hidden behind the states or containers they connect.
+- Validate connector anchor aesthetics after rendering; choose source and target boundary points that minimize bends, avoid unnecessary travel, and keep arrowheads on clean edge points.
+- Avoid diagonal connectors when an orthogonal route can preserve the same relationship, and use visible line jumps or bridges when crossings are unavoidable.
+- Before accepting connector bends, evaluate whether a small repositioning of the connected elements can reduce bends without harming nearby layout.
+- Keep editable diagram source and rendered output geometrically equivalent; do not make SVG-only corrections that cannot be reproduced from the draw.io XML.
+- Validate annotation target clarity; annotation arrows must visibly land on the element or line they describe, and annotation text must not obscure the target.
+- For diagrams without a source reference, create a diagram contract before drawing and validate the render against that contract before handoff.
+- Source-free diagrams still require a pixel-perfect pass against their own contract before delivery: no text overflow, no clipped containers, no floating or buried connector endpoints, no unintended overlaps, no hidden arrowheads, and no incoherent whitespace.
+- For source-free diagrams, iterate after the first render until container sizes, line routing, connector anchors, label positions, and visual balance are correct. Do not deliver an unreviewed first render.
+- For every post-render correction, re-run the full diagram review rather than checking only the edited area. A diagram passes only when the whole canvas still satisfies container containment, label clearance, connector routing, z-order, and whitespace rules.
+- A regenerated diagram must materially change geometry for the finding it claims to fix. If two versions preserve the same collision, overflow, endpoint gap, or unnecessary route bend, change the layout strategy instead of only re-rendering.
+- Preserve source text orientation when labels are vertical or diagonal; use explicit draw.io rotation values instead of approximating rotated labels with spacing or line breaks.
+- Validate exported artifacts, then inspect the rendered output against the source PDF, screenshot, or design reference at the fidelity level declared for the task.
+- Record residual fidelity gaps explicitly when a diagram is an approximation rather than pixel-perfect.
+- Before final delivery, clean diagram artifacts. Keep only the accepted editable source, accepted render, prompt master or final prompt, and minimum QA evidence needed for traceability. Archive or exclude intermediate previews, failed renders, temporary prompts, and one-off correction notes from the final deliverable.
+- Do not delete iteration evidence that is needed for audit. Move it to workflow evidence, an explicit archive folder, or an ignored output location, then point the final handoff to the accepted artifact paths.