@jterrats/open-orchestra 0.5.7 → 1.0.2

package/docs/setup-agents-applicability-review.md

@@ -0,0 +1,173 @@
+# setup-agents Applicability Review
+
+Date: 2026-05-14
+
+## Scope
+
+Review new `setup-agents` issues and local setup-agents standards to decide what
+should be adopted by Open Orchestra.
+
+Sources reviewed:
+
+- Open Orchestra issue #317
+- setup-agents issues #198-#211, with emphasis on #211, #209, #208, #205, #204,
+  #203, #202, #201, #200, #199, #198
+- Local setup-agents developer profile and generated Developer standards
+- Open Orchestra `setup-agents import` bridge and standards rules
+
+## Applies Directly
+
+### Visual Post-Write Validation
+
+Source: setup-agents #211 and Open Orchestra #317.
+
+This applies directly. Open Orchestra is the orchestrator and should own the
+generic gate contract:
+
+- external visual write manifest from agents or MCP integrations
+- export/snapshot evidence
+- fresh fetch of target state
+- duplicate, overlap, fallback-text, orphan, and bounds assertions
+- remediation loop where safe
+- blocking gate when non-remediable defects remain
+
+The Lucid-specific assertions belong in adapters or skills, but the gate type,
+evidence attachment, and workflow blocking behavior belong in Open Orchestra.
+
+### setup-agents Import Role Mapping
+
+Open Orchestra currently maps setup-agents `po` and `pm` aliases to `po` and
+`pm` in `src/setup-agents-import.ts`. Core Open Orchestra roles are
+`product_owner` and `product_manager`. Imported setup-agents tasks should map
+aliases to canonical role IDs.
+
+This is a bug-sized Open Orchestra fix.
+
+### Workflow Benchmark Feedback Into Estimates
+
+Source: setup-agents #205.
+
+Open Orchestra already has estimates and benchmark concepts. Historical
+calibration belongs in Open Orchestra so every stack benefits, not only
+Salesforce. The useful contract is:
+
+- estimates read completed run benchmark data when available
+- output includes historical median and variance
+- warning when historical estimates deviate materially
+- `--ignore-history` bypass
+- JSON output exposes calibration fields
+
+### Playbook Scaffolding And Playbook Authoring Docs
+
+Sources: setup-agents #204 and #201.
+
+Open Orchestra has phase playbooks and task-scoped workflow rendering. A
+scaffold command would reduce friction for teams adapting phases by stack
+without reading source. This applies cross-stack.
+
+### Gate vs Clarify Documentation
+
+Source: setup-agents #202.
+
+Open Orchestra exposes gates, reviews, decisions, and clarification patterns.
+The distinction should be documented in Open Orchestra user docs and runtime
+bootstrap copy because agents otherwise use phase gates for mid-phase questions.
+
+### Workflow Phase Matrix / End-to-End Workflow Narrative
+
+Sources: setup-agents #200 and #199.
+
+Open Orchestra should document its PM -> PO -> Architect -> Developer -> QA ->
+Release sequence, gates, evidence, review checkpoints, and what is autonomous
+versus human-approved. This is product documentation, not setup-agents-specific.
+
+### Rules Health / Generated Guidance Freshness
+
+Source: setup-agents #203.
+
+Open Orchestra already generates bootstrap and managed instruction blocks. A
+health surface that reports stale generated guidance, missing playbooks, and
+workflow readiness would apply directly.
+
+## Applies As A Pattern, Not Literally
+
+### API 66 Salesforce Agent Metadata CI/CD
+
+Source: setup-agents #209.
+
+The Salesforce metadata details do not belong in Open Orchestra core, but the
+pattern does:
+
+- deployment lanes are not always one generic deploy command
+- some artifacts require publish/activate flows
+- generated or managed artifacts may need ignore rules
+- dependency prechecks should run before deploy
+
+Open Orchestra should represent this as stack-specific release lanes or release
+playbook checks, not as Salesforce API 66 logic.
+
+### Auto-Run Local Rule Generation After Init
+
+Source: setup-agents #208.
+
+The exact `sf setup-agents init -> local` behavior is setup-agents-specific.
+For Open Orchestra, the applicable concept is first-run completeness: after
+`orchestra init`, users should exit with usable runtime instructions, workflow
+files, and a clear next command without a hidden second step.
+
+## Developer Standards To Generalize
+
+Several setup-agents Developer standards are Apex-specific, but the underlying
+rules are stack-agnostic and should remain or be strengthened in Open Orchestra:
+
+- Read project metadata/config before generating code.
+- Infer naming and layering from existing code.
+- Default to least privilege / safe execution context.
+- Never query or mutate data inside loops; batch or bulk operations.
+- Keep entry points thin; delegate business logic to services/handlers.
+- Scan for existing exception/logging patterns before adding new ones.
+- Prefer existing data access patterns over inventing a new repository/selector.
+- Handle 1..N records/requests, not only the happy-path singleton.
+- Use centralized test data builders/factories.
+- Include async tests that flush queued work.
+- Use user/permission-specific test contexts for authorization-sensitive logic.
+- Avoid fixed async patterns; choose queues, jobs, events, or schedulers based on
+  ordering, retry, observability, and failure semantics.
+- Use named external integrations/configured clients; never hardcode endpoints,
+  tokens, credentials, or command strings.
+- Validate response status before processing external responses.
+- Keep user-facing strings configurable/localizable where the product needs it.
+- Run static analysis before handoff.
+- Deploy/validate the changed production artifact before relying on tests that
+  exercise it.
+- Every sub-agent handoff should include project conventions, data access
+  strategy, test strategy, and known constraints.
+
+These already overlap with current Open Orchestra rules. The main gap is making
+some of them more explicit for Java, .NET, TypeScript, and Python examples
+without carrying Apex names into stack-agnostic docs.
+
+Adopted in Open Orchestra via `rules/development-engineering.mdc`, with examples
+for Java/Spring, .NET, TypeScript/Node, and Python.
+
+## Does Not Apply To Core
+
+- Salesforce-specific API 66 commands such as `sf agent publish
+  authoring-bundle`.
+- Salesforce-only metadata folders such as `genAiPlannerBundles/`.
+- LWC/SLDS/LDS-specific UI implementation rules.
+- Apex trigger handler naming, `with sharing`, SOQL/DML, PSG test setup, and
+  Custom Labels as literal rules.
+
+These belong in Salesforce/setup-agents profiles, not Open Orchestra core.
+
+## Recommended Open Orchestra Backlog
+
+1. Implement visual validation gate contract and evidence attachment.
+2. Fix setup-agents import role aliases to canonical Open Orchestra roles.
+3. Add benchmark-calibrated estimates.
+4. Add playbook scaffold command and authoring docs.
+5. Add Gate vs Clarify docs and workflow phase matrix.
+6. Add rules/playbook health to `orchestra health` or a dedicated status view.
+7. Add stack-agnostic Developer standards examples for Java, .NET, TypeScript,
+   and Python.

package/docs/skill-loading-strategy.md

@@ -58,6 +58,7 @@ Skill manifests should be able to declare `sourceGroups` so the orchestrator can
 - `prompt-registry`: read and update `.generated-prompts/` registers for substantial AI-generated artifacts.
 - `diagram-export`: generate, validate, and export architecture or workflow diagrams.
 - `static-analysis`: run local quality, typing, SAST, dependency, and secret checks.
+- `collection-standards`: centralize repeated collections and keep collection processing linear or explicitly bounded across product code, QA automation, and DevOps scripts.
 - `pr-review`: produce review findings, PR summary, risks, rollout notes, and missing-test gaps.
 - `playwright-evidence`: plan browser automation and attach screenshots, traces, videos, and reports.
 - `backlog-sync`: keep GitHub issues, local stories, and workflow tasks aligned.

package/docs/source-of-truth-and-agent-learning.md

@@ -78,6 +78,20 @@ Do not record a lesson for:
 4. If reusable, append one JSONL entry with root cause, fix, prevention, and verification.
 5. If the same lesson appears repeatedly, promote it into the relevant skill or project rule.
 
+## Memory Governance
+
+Local memory is useful only while it stays bounded, current, and safe to load
+into future agent context. Use `orchestra memory governance` to inspect active,
+archived, stale, and sensitive lessons. Use `orchestra lessons prune --dry-run`
+before applying retention cleanup, then run without `--dry-run` to archive stale
+or overflow lessons.
+
+Use `orchestra lessons archive --id <lesson-id>` when a lesson is superseded but
+still useful as audit history. Use `orchestra lessons redact --id <lesson-id>`
+when a stored lesson contains token-like or secret-shaped values. Use
+`orchestra lessons delete --id <lesson-id>` only when the record should be
+removed from local memory entirely.
+
 ## Relationship to Skills
 
 Skills should declare which source groups they use and which lessons are relevant. The orchestrator should load lessons only for the selected skills and current operation, not the full historical log.

package/docs/traceability-flow.md

@@ -37,17 +37,32 @@ orchestra evidence add --task STORY-1 --role developer --type command --summary
 ## QA Verification
 
 QA verifies acceptance criteria, regression areas, edge cases, and data setup.
+Each acceptance criterion must map to evidence that proves an observable
+outcome. For CLI work, assert exit code, stdout/stderr, generated files,
+workflow events, or final state. For web work, assert visible user-facing state.
+For API, data, DB, storage, or integration work, assert response contracts,
+persisted state, side effects, sandbox/mock/contract/webhook/event/log outcomes,
+or record a deferred validation with owner and rationale.
 Browser automation should use Playwright evidence when the behavior is
 user-facing:
 
 ```bash
 orchestra playwright plan --task STORY-1
+orchestra qa coverage --task STORY-1 --json
 orchestra playwright evidence --task STORY-1 --kind trace --path test-results/story-1.zip --summary "acceptance flow trace"
 orchestra review --task STORY-1 --role qa --result approve --findings "..." --recommendation "..."
 ```
 
 Developer-to-QA handoff should include touched files, commands, known gaps, and
-recommended Playwright coverage.
+recommended Playwright, CLI, shell, or API coverage. `qa coverage` maps each
+acceptance criterion to `covered`, `planned`, `skipped`, or `gap` using task
+paths, project scripts, and existing evidence; release readiness surfaces
+unresolved QA automation gaps before promotion.
+
+Evidence summaries should name the acceptance criterion they cover or say
+"covers all acceptance criteria" when a single artifact proves the full story.
+Smoke and regression checks that do not map to a criterion are still useful, but
+they do not count as acceptance coverage.
 
 ## Advisory Conversion
 

package/docs/tracker-adapter-contract.md

@@ -4,6 +4,7 @@ Open Orchestra currently ships a GitHub-oriented tracker command:
 
 ```bash
 orchestra github sync --issue <number> --task <id> --comment --json
+orchestra tracker sync --tracker jira --remote PROJ-123 --issue-file jira-123.json --json
 ```
 
 The product contract is broader than GitHub CLI. A runtime may use `gh` when it
@@ -23,7 +24,9 @@ custom issue system.
 ## Common Adapter Shape
 
 Every tracker adapter should provide the same normalized fields to Open
-Orchestra:
+Orchestra. Runtime MCP skills, Jira/GitLab/Bitbucket CLIs, or custom bridge
+scripts should write this shape to a workspace-local JSON file and pass it to
+`orchestra tracker sync --issue-file <file>`:
 
 | Field | Meaning |
 | --- | --- |
@@ -42,6 +45,12 @@ Writes should support comment, status update, close, and accepted-risk note when
 the provider allows them. Missing write support should be reported as a transport
 capability gap, not treated as successful sync.
 
+The generic sync command maps the normalized issue into local task fields,
+detects existing-link conflicts before writing, and records local evidence when
+the sync is applied. Live remote reads and writes remain adapter-owned; the CLI
+does not fabricate Jira, GitLab, Bitbucket, or MCP calls when no adapter runner
+is available.
+
 ## MCP Fallback Requirements
 
 MCP tracker tools must:

package/docs/web-console-qa.md

@@ -0,0 +1,35 @@
+# Web Console QA Notes
+
+The web console is a local browser surface for workflow operations. It is not a
+replacement for the CLI; it consumes the same JSON contracts and should remain
+usable when a user needs to inspect state, create tasks, attach evidence, run or
+resume workflows, and review release readiness.
+
+## 1.0.0 Browser Support
+
+- Chromium is the release-blocking automated browser for 1.0.0 E2E coverage.
+- Desktop smoke uses the default Playwright viewport.
+- Mobile smoke uses a narrow viewport and must not create horizontal overflow.
+- Keyboard-only operation must reach refresh, task creation, evidence,
+  Playwright evidence, workflow start, gate approval, resume, and cancel
+  controls.
+
+## Required States
+
+- Loading: the status line announces `Loading workflow`.
+- Success: the status line announces `Workflow loaded`.
+- Empty: operational panels render friendly empty states when no matching data
+  exists.
+- Error: failed API calls render recoverable copy without raw stack traces.
+
+## Release Evidence
+
+Run:
+
+```bash
+npm run test:e2e -- e2e/web-console.spec.js
+```
+
+Attach the command result as QA evidence before release readiness. If a browser
+failure is accepted temporarily, record the affected viewport, failed action,
+user impact, owner, and expiry as review or release evidence.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.5.7",
+  "version": "1.0.2",
   "type": "module",
   "workspaces": [
-    "site"
+    "site",
+    "web-console"
   ],
   "bin": {
     "orchestra": "bin/orchestra.js"
@@ -14,14 +15,19 @@
     "test": "npm run build && node --test test/**/*.js extensions/**/*.test.cjs",
     "test:e2e": "npm run build && npm run site:build && playwright test",
     "test:e2e:init": "node --test e2e/init-onboarding.test.js",
-    "lint": "eslint . && prettier --check \"{bin,e2e,scripts,test,src}/**/*.js\" \"site/src/**/*.{css,js,jsx}\" \"site/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
-    "format": "prettier --write \"{bin,e2e,scripts,test,src}/**/*.js\" \"site/src/**/*.{css,js,jsx}\" \"site/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
+    "lint": "eslint . && prettier --check \"{bin,e2e,scripts,test,src}/**/*.js\" \"{site,web-console}/src/**/*.{css,js,jsx}\" \"{site,web-console}/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
+    "format": "prettier --write \"{bin,e2e,scripts,test,src}/**/*.js\" \"{site,web-console}/src/**/*.{css,js,jsx}\" \"{site,web-console}/*.{html,js,json}\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.{js,json}\"",
     "secret-scan": "node scripts/secret-scan.js",
+    "security:audit": "node scripts/security-audit.js",
     "validate:workflow": "node scripts/validate-workflow.js",
-    "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm test && npm run validate:workflow",
+    "release:matrix": "node scripts/release-test-matrix.js",
+    "performance:bench": "npm run build && node scripts/performance-benchmark.js",
+    "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm run security:audit && npm test && npm run validate:workflow",
     "prepack": "npm run build",
     "hooks:install": "git config core.hooksPath .githooks",
-    "build:web": "esbuild src/web-console-client.js --bundle --format=esm --platform=browser --target=es2022 --outfile=dist/assets/web-console.js",
+    "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: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/development-engineering.mdc

@@ -0,0 +1,68 @@
+---
+description: Stack-agnostic developer implementation standards across common application stacks
+alwaysApply: true
+---
+
+# Development Engineering
+
+Developer work must start from the existing project shape, preserve the local architecture, and leave verifiable evidence that the changed production artifact works.
+
+## Project Context First
+- Read the project manifest, build files, framework config, and existing module boundaries before generating code.
+- 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.
+
+## Entry Points And Layers
+- Controllers, routes, commands, triggers, handlers, jobs, and webhooks must stay thin.
+- Delegate business rules to services or domain modules, and delegate I/O to repositories, clients, gateways, or data-access modules.
+- 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.
+
+## Bulk And Batch Safety
+- Implement for 1..N records, requests, files, events, or messages. Do not special-case only the happy-path singleton.
+- Avoid unbounded data reads, writes, queries, or network calls inside loops. Prefer set-based reads, bulk writes, batching, pagination, or bounded concurrency.
+- When collection-processing complexity matters, load `collection-standards` for O(n), map/index, and bounded-complexity guidance.
+- Make transaction boundaries explicit and keep them as small as correctness allows.
+- Add regression coverage for multi-item input when the code can receive lists, streams, queues, or batched requests.
+
+## Data Access
+- Reuse the existing data-access pattern before adding a new repository, selector, ORM helper, query builder, or gateway abstraction.
+- Model query shape from real access patterns, including filters, sort order, pagination, indexes, locking, and authorization scope.
+- Keep data ownership explicit. Unrelated modules should not write directly to another bounded context without a service, event, or contract.
+- Validate migrations, generated artifacts, or deployed metadata before relying on tests that exercise them.
+
+## Errors And Logging
+- Scan for the existing exception and logging framework before adding try/catch blocks or new error types.
+- Convert operational errors to user-safe messages at the boundary. Propagate or fail fast on programmer errors.
+- Include useful context in logs: operation name, stable IDs, duration, retry count, and external system name when relevant.
+- Never swallow errors with empty catches or generic success fallbacks.
+
+## External Integrations
+- Use configured clients, named endpoints, and typed configuration. Never hardcode endpoints, tokens, credentials, shell commands, or timeouts.
+- Validate URLs before outbound calls, validate response status before parsing, and handle non-2xx responses explicitly.
+- Define timeouts, retries, backoff, idempotency keys, circuit breaking, and observability for integrations with side effects or production impact.
+- Keep provider-specific request and response mapping in adapters so product logic does not depend on one vendor shape.
+
+## Async Workflows
+- Choose queues, jobs, events, schedulers, or workflow engines based on ordering, retry, observability, latency, and partial-failure semantics.
+- Async payloads should carry stable IDs and versioned schemas, not large mutable snapshots unless snapshots are required for correctness.
+- Define retry policy, dead-letter handling, compensation or forward-fix behavior, and user-visible recovery for critical work.
+- Tests for async code must flush or drain queued work using the framework-supported pattern.
+
+## Testing
+- Use centralized builders, factories, fixtures, or test data helpers instead of copy-pasted setup blocks.
+- Authorization-sensitive logic needs tests under representative user, role, permission, tenant, or policy contexts.
+- Add tests for bulk input, empty input, partial failure, retries, authorization denial, and malformed external responses when applicable.
+- Run static analysis before handoff and include exact commands, results, known gaps, and suggested QA coverage in the handoff.
+
+## Stack Examples
+- Java/Spring: keep controllers thin, place rules in services, use repositories for data access, define `@Transactional` boundaries deliberately, and use Testcontainers or slice tests for persistence contracts.
+- .NET: keep controllers or minimal APIs thin, place rules in application services, pass `CancellationToken`, centralize typed options, and test EF Core query behavior with realistic providers when query translation matters.
+- TypeScript/Node: route or CLI handlers should call services, services should call typed repositories or clients, config should be validated at startup, and integration tests should cover pagination, async drains, and external status handling.
+- Python: endpoint or command functions should call services, services should call repositories or clients, use pytest fixtures/builders for setup, validate settings at startup, and test migrations or ORM queries when schema behavior changes.
+
+## Handoff
+- Handoffs must state the active project conventions, data-access strategy, test strategy, changed artifacts, validation commands, known constraints, and remaining risks.
+- When a task touches security, data, async workflows, external integrations, or infrastructure, include the related review outcome before release approval.

package/rules/devops-tooling.mdc

@@ -29,6 +29,7 @@ DevOps decisions must cover deployability, scalability, downtime strategy, obser
 - Do not approve infrastructure or release changes without deployment, rollback, monitoring, and ownership details.
 - Prefer managed services when they reduce operational risk without creating unacceptable lock-in or cost exposure.
 - Record tool choices and major operational trade-offs in an ADR when they affect long-term operations.
+- CI/CD, IaC, runbooks, and operational scripts that repeat command matrices, provider lists, environment maps, or resource collections must load the `collection-standards` skill.
 
 ## Scalability
 - Define expected traffic, data volume, concurrency, growth assumptions, and bottlenecks.

package/rules/dry-clean-code.mdc

@@ -7,6 +7,7 @@ alwaysApply: true
 
 ## Don't Repeat Yourself
 - **Single Source of Truth for data.** If a constant, type, or config exists in one place, every consumer must import or derive from it — never copy-paste.
+- When work touches repeated collections, option sets, fixtures, matrices, or collection-processing complexity, load the `collection-standards` skill instead of embedding detailed collection rules here.
 - When two blocks share >5 lines of identical structure, extract a reusable function.
 - Cross-package type sharing: define once, import at build time, or add a sync test. Never maintain parallel copies.
 

package/rules/performance-reliability.mdc

@@ -16,6 +16,7 @@ Performance and reliability must be designed, measured, and protected. Do not op
 ## Hot Paths
 - Avoid N+1 queries, unbounded loops with I/O, repeated serialization, and large synchronous work on request paths.
 - Paginate or stream large datasets. Do not load unbounded result sets into memory.
+- Load the `collection-standards` skill when implementation, QA automation, or DevOps scripting processes repeated collections, joins lists, scans logs, builds command matrices, or must prove O(n) or bounded complexity.
 - Keep expensive work outside user-facing request paths through queues, jobs, or precomputation.
 - Measure before and after performance changes and report the evidence.
 

package/rules/testing-discipline.mdc

@@ -18,6 +18,7 @@ alwaysApply: true
 ## Test Structure
 - **Arrange → Act → Assert.** Separate setup, execution, and verification with blank lines.
 - Use factory functions or builders for test data — never copy-paste fixtures across test files.
+- QA automation, E2E suites, contract tests, and test scripts that repeat fixture collections, selectors, expected outputs, or command matrices must load the `collection-standards` skill.
 - Tests must be deterministic. No reliance on system clock, network, or random values without seeding.
 
 ## Sync Tests
@@ -36,7 +37,9 @@ alwaysApply: true
 
 ## QA Handoff
 - Developer must provide QA with test commands run, pass/fail results, covered scenarios, and known gaps.
-- QA must produce a test plan before release approval.
+- QA must produce a test plan before release approval and map every acceptance criterion to automated, manual, contract/mock, or deferred evidence.
+- QA evidence must validate observable outcomes, not only execution. CLI checks assert exit code, stdout/stderr, files, events, or final state; browser checks assert visible user-facing state; API checks assert response contract and side effects; integration checks assert sandbox/mock/contract/webhook/event/log outcomes or defer with owner and rationale.
+- Evidence summaries or metadata must name the covered acceptance criterion or explicitly state that all acceptance criteria are covered. Smoke and regression checks are useful but do not count as acceptance coverage unless they map to an acceptance criterion.
 - QA and Developer must decide which manual checks should be automated, preferring Playwright for browser flows.
 - User-facing QA plans must include responsive, accessibility, copy, tooltip, loading, empty, error, success, and recovery-state checks.
 - API, data, async, performance, and config changes must include targeted regression checks for contract, migration, idempotency, latency, and environment behavior when applicable.

package/skills/collection-standards/SKILL.md

@@ -0,0 +1,63 @@
+# Collection Standards
+
+Use this skill when a task touches repeated collections, option sets, fixtures,
+command matrices, selectors, validators, or collection-processing complexity.
+It applies to product code, QA automation, scripts, CI/CD, IaC helpers,
+operational tooling, and generated code.
+
+## When To Load
+
+- Developer, QA/SDET, DevOps, Platform, SRE, or Performance work writes code,
+  scripts, tests, generated options, or automation helpers.
+- The task mentions hardcoded values, arrays, maps, key/value pairs, options,
+  fixtures, selectors, command cases, provider lists, CI matrices, roles,
+  statuses, validators, bulk/batch processing, O(n), N+1, nested loops, or
+  complexity.
+- A review finds duplicated collections or repeated scans across files.
+
+## Single Source Of Truth
+
+- If the same list, map, enum-like set, key/value collection, option list,
+  validator set, selector set, fixture set, provider list, role/status list,
+  script argument collection, or CI matrix is needed in more than one place,
+  define one typed source of truth.
+- Prefer the smallest project-native shape: exported constant, typed union,
+  registry, builder, factory, fixture helper, page object, or config-derived
+  adapter.
+- Derive all arrays, lookup maps, dropdown options, validators, test data,
+  command arguments, docs examples, and automation config from that source.
+- Do not maintain parallel copies in product code, tests, QA scripts, DevOps
+  scripts, generated docs, or UI controls. If duplication is unavoidable across
+  packages, add a sync test.
+
+## Collection Complexity
+
+- Default to O(n) or explicitly bounded collection processing for normal code,
+  CLI commands, QA automation, CI scripts, and operational tools.
+- Avoid nested scans, repeated full-list filters, N+1 calls, unbounded log
+  scans, and synchronous work over large collections.
+- For joins or repeated lookups, build a `Map`, dictionary, index, page object,
+  or normalized structure once, then use O(1) lookups.
+- Paginate, stream, batch, or bound large data sources. Do not load unbounded
+  result sets into memory.
+- If O(n^2) or another higher-complexity approach is intentional, document the
+  input bound or measured trade-off and attach representative multi-item
+  evidence.
+
+## Review Checklist
+
+- What collection is authoritative?
+- Which consumers derive from it?
+- Are tests, scripts, UI controls, validators, and docs using the same source?
+- Are joins/lookups linear or bounded?
+- Is there evidence with more than one item, including empty and multi-item
+  cases when the workflow supports collections?
+
+## Evidence
+
+- `file`: changed source-of-truth module, registry, builder, fixture helper, or
+  page object.
+- `command`: focused test, E2E, script, lint, or build proving the derived
+  consumers work.
+- `report`: reviewer note or benchmark when complexity is intentionally higher
+  than O(n).

package/skills/collection-standards/manifest.json

@@ -0,0 +1,69 @@
+{
+  "id": "collection-standards",
+  "name": "Collection Standards",
+  "summary": "Centralize repeated collections and keep collection processing linear or explicitly bounded across product code, QA automation, and DevOps scripts.",
+  "triggers": [
+    "collection",
+    "collections",
+    "hardcoded",
+    "array",
+    "arrays",
+    "map",
+    "maps",
+    "key/value",
+    "option",
+    "options",
+    "fixture",
+    "fixtures",
+    "matrix",
+    "matrices",
+    "selector",
+    "selectors",
+    "o(n)",
+    "o(n2)",
+    "o(n^2)",
+    "complexity",
+    "nested loop",
+    "nested loops",
+    "n+1",
+    "bulk",
+    "batch"
+  ],
+  "roles": [
+    "developer",
+    "tech_lead",
+    "frontend_specialist",
+    "backend_specialist",
+    "mobile_specialist",
+    "qa",
+    "sdet",
+    "devops",
+    "platform_engineer",
+    "sre",
+    "performance_engineer"
+  ],
+  "capabilities": [
+    "maintainability",
+    "performance-safety",
+    "automation-quality"
+  ],
+  "riskAreas": [
+    "maintainability",
+    "performance",
+    "release",
+    "devops",
+    "sre"
+  ],
+  "sourceGroups": [
+    "codebase",
+    "quality-security",
+    "agent-memory"
+  ],
+  "evidence": [
+    "file",
+    "command",
+    "report"
+  ],
+  "loadBudget": "small",
+  "entry": "skills/collection-standards/SKILL.md"
+}