@jterrats/open-orchestra 0.1.0 → 0.2.1

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@jterrats/open-orchestra",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "orchestra": "bin/orchestra.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run build:web",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test test/**/*.js extensions/**/*.test.cjs",
-    "lint": "eslint . && prettier --check \"{bin,scripts,test}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.json\"",
-    "format": "prettier --write \"{bin,scripts,test}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.json\"",
+    "lint": "eslint . && prettier --check \"{bin,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.json\"",
+    "format": "prettier --write \"{bin,scripts,test,src}/**/*.js\" \"extensions/**/*.{cjs,json,md}\" \"src/**/*.ts\" \"*.json\"",
     "secret-scan": "node scripts/secret-scan.js",
     "validate:workflow": "sh -c 'test ! -d .agent-workflow || (npm run build && node bin/orchestra.js validate)'",
     "precommit": "npm run lint && npm run typecheck && npm run secret-scan && npm test && npm run validate:workflow",
-    "hooks:install": "git config core.hooksPath .githooks"
+    "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"
   },
   "engines": {
     "node": ">=22"
@@ -22,6 +23,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^25.6.0",
+    "esbuild": "^0.28.0",
     "eslint": "^10.2.1",
     "prettier": "^3.8.3",
     "typescript": "^6.0.3",
@@ -45,8 +47,10 @@
     "dist/",
     "rules/",
     "docs/",
+    "skills/",
     "AGENTS.md",
     "CLAUDE.md",
+    "CHANGELOG.md",
     "README.md",
     "package.json"
   ],

package/rules/agent-roles.mdc

@@ -39,16 +39,41 @@ Use roles to force complete thinking, not to create silos. A single agent may co
 - Does not start coding until acceptance criteria and technical boundaries are clear enough.
 - Confirms the agreed implementation approach before editing files, except for trivial mechanical changes.
 
+## Frontend Specialist
+- Owns browser behavior, component architecture, responsive UI, accessibility implementation, client performance, and visual regression risk.
+- Reviews user-facing web changes against mobile-first flows, WCAG-oriented checks, and Playwright-visible behavior.
+- Blocks frontend changes that cannot be verified in target browsers or viewports.
+
+## Backend Specialist
+- Owns service boundaries, API contracts, domain services, persistence integration, concurrency, and failure modes.
+- Reviews backend changes for secure coding, observability, idempotency, retries, data integrity, and server-side tests.
+- Blocks backend changes with unclear contracts, untested failure modes, or unsafe data handling.
+
+## Mobile Specialist
+- Owns mobile UX, device compatibility, offline behavior, permissions, native or hybrid runtime constraints, and store readiness.
+- Reviews mobile changes with device evidence instead of relying only on desktop responsive checks.
+- Blocks mobile releases without device matrix, runtime constraints, or store readiness evidence when applicable.
+
 ## QA
 - Owns verification strategy, test coverage, regression risk, and release confidence.
 - Defines happy paths, failure paths, boundary cases, and non-functional checks.
 - Challenges work that has implementation but no credible test plan.
 
+## SDET / Test Automation Engineer
+- Owns automated test architecture, Playwright fixtures, page objects, resilient locators, and CI test reliability.
+- Converts QA plans and acceptance criteria into repeatable smoke, regression, and evidence-producing tests.
+- Blocks automation-heavy releases when tests are brittle, unisolated, or missing traceable evidence.
+
 ## DevOps
 - Owns deployment, CI/CD, observability, runtime configuration, rollback, and operational readiness.
 - Verifies environment segregation, infrastructure as code, migrations, secrets, and runbooks.
 - Blocks releases that cannot be deployed, monitored, rolled back, or supported.
 
+## Platform Engineer
+- Owns internal developer platforms, golden paths, reusable templates, self-service workflows, and platform guardrails.
+- Treats developer experience as a product while preserving security, compliance, cost visibility, and operational control.
+- Blocks cross-repo platform changes without template validation, adoption notes, or self-service smoke evidence.
+
 ## Security
 - Owns threat modeling, abuse cases, data classification, identity, secrets, and dependency risk.
 - Reviews authentication, authorization, input handling, logging, encryption, and third-party exposure.
@@ -89,6 +114,11 @@ Use roles to force complete thinking, not to create silos. A single agent may co
 - Reviews user-facing changes for diagnosability, help text, recovery paths, and support escalation needs.
 - Feeds production incidents, tickets, and user pain back into Product Owner and QA workflows.
 
+## AI Evaluation / Prompt Quality Engineer
+- Owns eval objectives, datasets, rubrics, prompt regression checks, model comparisons, and LLM behavior evidence.
+- Treats prompt, model routing, and provider fallback changes as testable product behavior.
+- Blocks AI behavior changes that rely on subjective review without eval cases, scoring rationale, or accepted residual risk.
+
 ## Compliance / Privacy
 - Owns regulatory requirements, privacy obligations, retention, consent, auditability, and data processing risk.
 - Reviews PII, restricted data, data residency, retention policies, access logs, consent, and third-party processors.

package/rules/ai-assisted-development.mdc

@@ -29,3 +29,25 @@ AI-generated work must meet the same engineering bar as human-written work. Spee
 - Discuss the approach with the user before non-trivial AI-assisted implementation.
 - Explain trade-offs clearly and identify risks introduced by generated code.
 - If generated code reveals a better or riskier path than agreed, pause and realign before continuing.
+
+## Prompt Registry
+
+- Use `.generated-prompts/` as the durable prompt register for generated or substantially changed artifacts.
+- Before creating or substantially changing an artifact, read the relevant register file to preserve conventions, constraints, decisions, and known risks.
+- After substantial changes, add or update one entry for the artifact with task, active role, key decisions, evidence, and the final prompt or a concise prompt summary.
+- Keep only the latest prompt in each entry; rely on git history for prior versions. Do not update entries for typos, formatting-only edits, or single-line mechanical fixes.
+
+## Skill Loading
+
+- Keep primary agent instruction files as short indexes plus non-negotiable rules.
+- Load detailed skills only when task signals, active roles, touched paths, or risk areas require them.
+- Prefer skill summaries first; load full skill instructions, assets, scripts, and examples only at execution time.
+- Record selected skills in task context, handoffs, evidence, and final summaries when they materially shaped the work.
+
+## Source of Truth and Learning
+
+- Select authoritative source groups before acting: project instructions, backlog, architecture, codebase, quality/security, DevOps/runtime, vendor docs, and agent memory.
+- Prefer local project sources first and official vendor documentation for current APIs, frameworks, cloud services, providers, and tools.
+- When an action fails in a reusable way, record the lesson in `.agent-workflow/agent-lessons.jsonl` with operation, error signature, root cause, fix, prevention, and verification.
+- Before repeating risky operations, search prior lessons for matching tool, command, error signature, or operation.
+- Promote repeated lessons into the relevant skill or rule instead of letting agents rediscover the same failure.

package/skills/agent-learning/SKILL.md

@@ -0,0 +1,24 @@
+# Agent Learning
+
+Record reusable failure lessons and promote repeated lessons into skills or rules.
+
+## When To Load
+
+- Trigger: `failure`
+- Trigger: `failed`
+- Trigger: `error`
+- Trigger: `syntax`
+- Trigger: `escaping`
+- Trigger: `permission`
+- Trigger: `lesson`
+- Trigger: `learn`
+
+## Procedure
+
+- Search relevant lessons before repeating risky operations.
+- After reusable failures, record operation, error signature, root cause, fix, prevention, and verification.
+- Promote repeated lessons into versioned skills or rules after review.
+
+## Evidence
+
+- `file`

package/skills/agent-learning/manifest.json

@@ -0,0 +1,40 @@
+{
+  "id": "agent-learning",
+  "name": "Agent Learning",
+  "summary": "Record reusable failure lessons and promote repeated lessons into skills or rules.",
+  "triggers": [
+    "failure",
+    "failed",
+    "error",
+    "syntax",
+    "escaping",
+    "permission",
+    "lesson",
+    "learn"
+  ],
+  "roles": [
+    "parent",
+    "context_curator",
+    "toolsmith",
+    "developer",
+    "qa"
+  ],
+  "capabilities": [
+    "failure-learning",
+    "memory-hygiene",
+    "repeat-prevention"
+  ],
+  "riskAreas": [
+    "maintainability",
+    "governance"
+  ],
+  "sourceGroups": [
+    "agent-memory",
+    "codebase"
+  ],
+  "evidence": [
+    "file"
+  ],
+  "loadBudget": "small",
+  "entry": "skills/agent-learning/SKILL.md"
+}

package/skills/backlog-sync/SKILL.md

@@ -0,0 +1,24 @@
+# Backlog Sync
+
+Keep GitHub issues, local stories, and workflow tasks aligned.
+
+## When To Load
+
+- Trigger: `backlog`
+- Trigger: `issue`
+- Trigger: `story`
+- Trigger: `epic`
+- Trigger: `github`
+- Trigger: `acceptance criteria`
+- Trigger: `refine`
+
+## Procedure
+
+- Confirm backlog IDs and acceptance criteria before implementation.
+- Keep local tasks, docs, and GitHub issues aligned when one changes.
+- Surface missing refinement as a blocker instead of guessing scope.
+
+## Evidence
+
+- `file`
+- `report`

package/skills/backlog-sync/manifest.json

@@ -0,0 +1,41 @@
+{
+  "id": "backlog-sync",
+  "name": "Backlog Sync",
+  "summary": "Keep GitHub issues, local stories, and workflow tasks aligned.",
+  "triggers": [
+    "backlog",
+    "issue",
+    "story",
+    "epic",
+    "github",
+    "acceptance criteria",
+    "refine"
+  ],
+  "roles": [
+    "product_manager",
+    "product_owner",
+    "business_analyst",
+    "planner",
+    "parent"
+  ],
+  "capabilities": [
+    "backlog-management",
+    "story-refinement",
+    "scope-control"
+  ],
+  "riskAreas": [
+    "governance",
+    "scope"
+  ],
+  "sourceGroups": [
+    "product-backlog",
+    "project-instructions",
+    "agent-memory"
+  ],
+  "evidence": [
+    "file",
+    "report"
+  ],
+  "loadBudget": "small",
+  "entry": "skills/backlog-sync/SKILL.md"
+}

package/skills/diagram-export/SKILL.md

@@ -0,0 +1,35 @@
+# Diagram Export
+
+Create, validate, and export architecture, workflow, and sequence diagrams.
+
+## When To Load
+
+- Trigger: `diagram`
+- Trigger: `mermaid`
+- Trigger: `architecture`
+- Trigger: `flow`
+- Trigger: `sequence`
+- Trigger: `draw.io`
+- Trigger: `lucid`
+
+## Procedure
+
+- Identify the diagram purpose and authoritative architecture sources before drawing.
+- Choose the diagram style from the decision matrix before drafting.
+- Prefer text-native diagrams such as Mermaid unless the project requires another format.
+- Run `orchestra diagrams lint --file <diagram.mmd>` for lint-only validation before sharing Mermaid diagrams.
+- Attach evidence with `orchestra diagrams lint --file <diagram.mmd> --task <task-id>` when the diagram supports workflow delivery.
+- If `mmdc` is missing, report the install guidance instead of pretending validation passed.
+
+## Decision Matrix
+
+- Architecture boundary or component ownership: C4/container or component diagram.
+- User, business, or agent workflow: flowchart or state diagram.
+- Service/API/message exchange: sequence diagram.
+- Data ownership or relationships: entity relationship diagram.
+- Runtime topology, infrastructure, or deployment: deployment or infrastructure diagram.
+
+## Evidence
+
+- `file`
+- `report`

package/skills/diagram-export/manifest.json

@@ -0,0 +1,40 @@
+{
+  "id": "diagram-export",
+  "name": "Diagram Export",
+  "summary": "Create, validate, and export architecture, workflow, and sequence diagrams.",
+  "triggers": [
+    "diagram",
+    "mermaid",
+    "architecture",
+    "flow",
+    "sequence",
+    "draw.io",
+    "lucid"
+  ],
+  "roles": [
+    "architect",
+    "business_analyst",
+    "product_manager",
+    "tech_lead",
+    "technical_writer"
+  ],
+  "capabilities": [
+    "diagramming",
+    "architecture-communication"
+  ],
+  "riskAreas": [
+    "architecture",
+    "documentation"
+  ],
+  "sourceGroups": [
+    "architecture",
+    "product-backlog",
+    "agent-memory"
+  ],
+  "evidence": [
+    "file",
+    "report"
+  ],
+  "loadBudget": "normal",
+  "entry": "skills/diagram-export/SKILL.md"
+}

package/skills/model-evaluation/SKILL.md

@@ -0,0 +1,25 @@
+# Model Evaluation
+
+Run prompt, model, provider-routing, fallback, and rubric evaluations.
+
+## When To Load
+
+- Trigger: `model`
+- Trigger: `llm`
+- Trigger: `prompt`
+- Trigger: `provider`
+- Trigger: `fallback`
+- Trigger: `eval`
+- Trigger: `rubric`
+- Trigger: `routing`
+
+## Procedure
+
+- Define eval objectives, cases, rubric, and expected behavior before changing prompts or routing.
+- Compare model/provider behavior for material changes and record disagreements.
+- Avoid storing raw sensitive prompts or responses in provenance artifacts.
+
+## Evidence
+
+- `report`
+- `file`

package/skills/model-evaluation/manifest.json

@@ -0,0 +1,41 @@
+{
+  "id": "model-evaluation",
+  "name": "Model Evaluation",
+  "summary": "Run prompt, model, provider-routing, fallback, and rubric evaluations.",
+  "triggers": [
+    "model",
+    "llm",
+    "prompt",
+    "provider",
+    "fallback",
+    "eval",
+    "rubric",
+    "routing"
+  ],
+  "roles": [
+    "ai_evaluation_engineer",
+    "toolsmith",
+    "architect",
+    "parent"
+  ],
+  "capabilities": [
+    "llm-evaluation",
+    "provider-routing",
+    "prompt-quality"
+  ],
+  "riskAreas": [
+    "governance",
+    "quality"
+  ],
+  "sourceGroups": [
+    "vendor-docs",
+    "agent-memory",
+    "quality-security"
+  ],
+  "evidence": [
+    "report",
+    "file"
+  ],
+  "loadBudget": "normal",
+  "entry": "skills/model-evaluation/SKILL.md"
+}

package/skills/playwright-evidence/SKILL.md

@@ -0,0 +1,28 @@
+# Playwright Evidence
+
+Plan browser automation and attach screenshots, traces, videos, and reports.
+
+## When To Load
+
+- Trigger: `playwright`
+- Trigger: `browser`
+- Trigger: `e2e`
+- Trigger: `screenshot`
+- Trigger: `trace`
+- Trigger: `video`
+- Trigger: `responsive`
+- Trigger: `web`
+- Trigger: `ui`
+
+## Procedure
+
+- Plan user-value scenarios from acceptance criteria before writing tests.
+- Use resilient locators and page objects for repeated flows.
+- Attach screenshots, traces, videos, or reports as evidence for release decisions.
+
+## Evidence
+
+- `screenshot`
+- `trace`
+- `video`
+- `report`

package/skills/playwright-evidence/manifest.json

@@ -0,0 +1,46 @@
+{
+  "id": "playwright-evidence",
+  "name": "Playwright Evidence",
+  "summary": "Plan browser automation and attach screenshots, traces, videos, and reports.",
+  "triggers": [
+    "playwright",
+    "browser",
+    "e2e",
+    "screenshot",
+    "trace",
+    "video",
+    "responsive",
+    "web",
+    "ui"
+  ],
+  "roles": [
+    "qa",
+    "sdet",
+    "frontend_specialist",
+    "ux_ui_designer",
+    "ux_researcher_accessibility"
+  ],
+  "capabilities": [
+    "e2e-testing",
+    "browser-evidence",
+    "accessibility-check"
+  ],
+  "riskAreas": [
+    "ux",
+    "release"
+  ],
+  "sourceGroups": [
+    "quality-security",
+    "codebase",
+    "product-backlog",
+    "agent-memory"
+  ],
+  "evidence": [
+    "screenshot",
+    "trace",
+    "video",
+    "report"
+  ],
+  "loadBudget": "normal",
+  "entry": "skills/playwright-evidence/SKILL.md"
+}

package/skills/pr-review/SKILL.md

@@ -0,0 +1,23 @@
+# PR Review
+
+Produce review findings, PR summaries, risks, rollout notes, and missing-test gaps.
+
+## When To Load
+
+- Trigger: `pr`
+- Trigger: `pull request`
+- Trigger: `review`
+- Trigger: `diff`
+- Trigger: `merge`
+- Trigger: `release summary`
+
+## Procedure
+
+- Review behavior, tests, risks, rollout, rollback, and missing evidence before summaries.
+- Lead with findings and blockers, then summarize changes.
+- Reference local files, task context, reviews, and evidence rather than generated claims.
+
+## Evidence
+
+- `file`
+- `report`

package/skills/pr-review/manifest.json

@@ -0,0 +1,43 @@
+{
+  "id": "pr-review",
+  "name": "PR Review",
+  "summary": "Produce review findings, PR summaries, risks, rollout notes, and missing-test gaps.",
+  "triggers": [
+    "pr",
+    "pull request",
+    "review",
+    "diff",
+    "merge",
+    "release summary"
+  ],
+  "roles": [
+    "reviewer_critic",
+    "tech_lead",
+    "qa",
+    "security",
+    "release_manager",
+    "architect"
+  ],
+  "capabilities": [
+    "review",
+    "risk-summary",
+    "change-summary"
+  ],
+  "riskAreas": [
+    "release",
+    "security",
+    "maintainability"
+  ],
+  "sourceGroups": [
+    "codebase",
+    "quality-security",
+    "product-backlog",
+    "agent-memory"
+  ],
+  "evidence": [
+    "file",
+    "report"
+  ],
+  "loadBudget": "normal",
+  "entry": "skills/pr-review/SKILL.md"
+}

package/skills/prompt-registry/SKILL.md

@@ -0,0 +1,24 @@
+# Prompt Registry
+
+Read and update .generated-prompts registers for substantial AI-generated artifacts.
+
+## When To Load
+
+- Trigger: `prompt`
+- Trigger: `generated`
+- Trigger: `artifact`
+- Trigger: `code`
+- Trigger: `ui`
+- Trigger: `docs`
+- Trigger: `diagram`
+- Trigger: `eval`
+
+## Procedure
+
+- Before substantial generation, read the relevant .generated-prompts register.
+- After substantial changes, update one entry with task, role, decisions, evidence, and prompt summary.
+- Do not update the register for typo-only, formatting-only, or single-line mechanical fixes.
+
+## Evidence
+
+- `file`

package/skills/prompt-registry/manifest.json

@@ -0,0 +1,45 @@
+{
+  "id": "prompt-registry",
+  "name": "Prompt Registry",
+  "summary": "Read and update .generated-prompts registers for substantial AI-generated artifacts.",
+  "triggers": [
+    "prompt",
+    "generated",
+    "artifact",
+    "code",
+    "ui",
+    "docs",
+    "diagram",
+    "eval"
+  ],
+  "roles": [
+    "parent",
+    "developer",
+    "tech_lead",
+    "frontend_specialist",
+    "backend_specialist",
+    "mobile_specialist",
+    "sdet",
+    "qa",
+    "technical_writer",
+    "ai_evaluation_engineer"
+  ],
+  "capabilities": [
+    "prompt-memory",
+    "artifact-traceability",
+    "context-continuity"
+  ],
+  "riskAreas": [
+    "maintainability",
+    "governance"
+  ],
+  "sourceGroups": [
+    "agent-memory",
+    "codebase"
+  ],
+  "evidence": [
+    "file"
+  ],
+  "loadBudget": "small",
+  "entry": "skills/prompt-registry/SKILL.md"
+}

package/skills/release-readiness/SKILL.md

@@ -0,0 +1,25 @@
+# Release Readiness
+
+Validate gates, rollback, observability, support, and customer-impact evidence.
+
+## When To Load
+
+- Trigger: `release`
+- Trigger: `deploy`
+- Trigger: `rollback`
+- Trigger: `go-live`
+- Trigger: `readiness`
+- Trigger: `downtime`
+- Trigger: `observability`
+
+## Procedure
+
+- Validate gates, evidence, locks, reviews, rollback, observability, and support readiness.
+- Treat missing rollback or unresolved critical QA/security/SRE findings as blockers.
+- Record release evidence and accepted residual risks explicitly.
+
+## Evidence
+
+- `command`
+- `report`
+- `file`