@jterrats/open-orchestra 0.1.0 → 0.2.1

package/docs/open-orchestra-dogfooding-findings.md

@@ -0,0 +1,66 @@
+# Open Orchestra Dogfooding Findings
+
+This file records what Open Orchestra contributed while building Open Orchestra
+itself, plus issues found by using the CLI as the local control plane.
+
+## What Helped
+
+- **Backlog alignment:** GitHub issues, local `.agent-workflow/tasks.json`, and
+  semantic commits stayed tied to backlog IDs such as `ROLE-003`, `WFLOW-001`,
+  and `BUG-087`.
+- **Explicit delegation:** `orchestra delegation decide` made role selection
+  visible before implementation, including write scopes and expected outputs.
+- **Evidence discipline:** fixes were closed with command evidence,
+  reviewer records, and `npm run precommit` results instead of relying on a
+  prose claim.
+- **Bug discovery:** concurrent state writes exposed real bugs in task and lock
+  mutation safety. Those became tracked fixes instead of one-off manual repairs.
+- **Context control:** skills, source-of-truth, lessons, protocols, and workflow
+  templates kept primary instruction files smaller while preserving task-specific
+  context.
+- **Runtime portability:** the same workflow state supported Codex, CLI, web/API,
+  VS Code extension scaffolding, and future Claude/Cursor instruction renders.
+
+## Finding: Parallel Independent Commands Are Safe So Far
+
+- **Date checked:** 2026-05-06
+- **Workspace:** `/tmp/oo-parallel-dogfood`
+- **Commands tested in parallel:** `task add`, `delegation decide`,
+  duplicate `task add`, same-path `lock claim`, `validate`, `task list`, and
+  concurrent `evidence add`.
+- **Observed behavior:** independent writes serialized correctly. Duplicate
+  tasks failed with `task already exists`. Same-path locks allowed one winner
+  and blocked the second. Concurrent evidence writes produced distinct artifacts
+  and a valid event log.
+- **Validation:** `orchestra validate --json` returned valid after the stress
+  run.
+
+## Finding: Parallel Dependent Commands Need DAG Semantics
+
+- **Date found:** 2026-05-06
+- **Observed behavior:** when a parent agent schedules `task add` and an
+  immediate dependent command such as `delegation decide --task <id>` in the
+  same parallel batch, the dependent command can run before the task exists and
+  fail with `unknown task`.
+- **Impact:** this is not state corruption, but it creates noisy false failures
+  when the parent agent treats dependent steps as independent parallel work.
+- **Recommended product fix:** add a future batch runner with explicit
+  `dependsOn` ordering, or make dependent command failures retryable when the
+  missing task is being created in the same batch.
+- **Current workaround:** only run independent Open Orchestra commands in
+  parallel. Run `task add` before `context`, `delegation`, `plan`, `review`, or
+  `evidence` for that task.
+
+## Finding: Renamed Project Paths Must Be Revalidated Before Generation
+
+- **Date found:** 2026-05-06
+- **Observed behavior:** after the project directory moved from `cursor-rules`
+  to `open-orchestra`, a file-generation tool attempted to write new files
+  through stale path context.
+- **Impact:** generated files can be created outside the intended repo, leaving
+  imports in the current repo pointing at missing files.
+- **Recommended product fix:** add a workspace guard that verifies `cwd`,
+  `package.json`, and `.git` root before generated file writes.
+- **Current workaround:** after a rename or context transition, run
+  `pwd`, `git status --short`, and `ls` for every newly generated file before
+  continuing.

package/docs/orchestra-mvp.md

@@ -11,6 +11,31 @@ It stores workflow state in `.agent-workflow/` and coordinates agents through fi
 - Existing `AGENTS.md`, `CLAUDE.md`, Cursor rules, and generated instruction files remain supported entry points.
 - `ORCHESTRA.md` is the intended future primary guide name; it is not required for existing projects.
 
+## Prompt Registry
+
+Open Orchestra initializes `.generated-prompts/` beside `.agent-workflow/`. The prompt registry stores the latest prompt intent and generation context by artifact type so future agents can preserve conventions without loading all history into the main instruction files.
+
+Generated register files:
+
+```text
+.generated-prompts/
+  cicd.md
+  code.md
+  diagrams.md
+  docs.md
+  evals.md
+  services.md
+  tests.md
+  ui.md
+```
+
+Existing register files are preserved unless `orchestra init --force` is used.
+
+## Skills and Context Loading
+
+Open Orchestra should treat skills as demand-loaded capabilities. Main files such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, and `ORCHESTRA.md` should contain a compact index and activation rules, while detailed procedures live in skill files. See [skill-loading-strategy.md](skill-loading-strategy.md).
+
+
 ## Commands
 
 ```bash
@@ -41,6 +66,22 @@ node bin/orchestra.js lock list
 node bin/orchestra.js lock release --id lock-123
 node bin/orchestra.js roles list
 node bin/orchestra.js roles list --json
+node bin/orchestra.js skills list
+node bin/orchestra.js skills list --json
+node bin/orchestra.js skills plan --task TASK-1
+node bin/orchestra.js skills plan --task TASK-1 --json
+node bin/orchestra.js skills render --target generic --task TASK-1
+node bin/orchestra.js skills render --target claude --task TASK-1
+node bin/orchestra.js skills render --target cursor --skills static-analysis,playwright-evidence
+node bin/orchestra.js skills render --target codex --task TASK-1
+node bin/orchestra.js skills render --target vscode --task TASK-1 --json
+node bin/orchestra.js skills validate
+node bin/orchestra.js skills validate --json
+node bin/orchestra.js sources list
+node bin/orchestra.js sources list --json
+node bin/orchestra.js lessons list
+node bin/orchestra.js lessons add --operation "shell edit" --failed-action "bad escaping" --error-signature "syntax error" --root-cause "unescaped token" --fix "escape token" --prevention "dry run first" --applies-to node,markdown --verified-by precommit
+node bin/orchestra.js lessons promote --to doc --filter escaping
 node bin/orchestra.js readiness --task TASK-1
 node bin/orchestra.js gate --gate architecture --task TASK-1
 node bin/orchestra.js gate --gate qa-release --task TASK-1
@@ -92,6 +133,8 @@ node bin/orchestra.js model provenance list --task TASK-1 --json
   tasks.json
   locks.json
   events.jsonl
+  source-of-truth.json
+  agent-lessons.jsonl
   approvals/
   decisions/
   handoffs/
@@ -121,7 +164,9 @@ The role catalog JSON includes capabilities, required handoff fields, blocking a
 
 Open Orchestra initializes a broad role catalog but does not require every role to participate in every task. The parent/orchestrator should activate roles based on task type, risk, touched paths, impact areas, and gate requirements.
 
-Default roles include delivery roles such as Product Manager, Product Owner, Business Analyst, Architect, Developer, QA, Security, DevOps, SRE, DBA, UX/UI Designer, Release Manager, Compliance/Privacy, and Technical Writer. They also include orchestration roles for modern multi-agent systems: Planner, Reviewer/Critic, Toolsmith, Context Curator, Policy/Governance, Observability/Incident Response, Data/Privacy Officer, Domain Expert, UX Researcher/Accessibility Reviewer, Performance Engineer, and Game Designer.
+Default roles include delivery and specialist roles such as Product Manager, Product Owner, Business Analyst, Architect, Developer, Tech Lead, Frontend Specialist, Backend Specialist, Mobile Specialist, QA, SDET, Security, DevOps, Platform Engineer, SRE, DBA, UX/UI Designer, Release Manager, Compliance/Privacy, Technical Writer, AI Evaluation Engineer, and Support/Customer Operations. They also include orchestration roles for modern multi-agent systems: Planner, Reviewer/Critic, Toolsmith, Context Curator, Policy/Governance, Observability/Incident Response, Data/Privacy Officer, Domain Expert, UX Researcher/Accessibility Reviewer, Performance Engineer, and Game Designer.
+
+Specialist profiles and their source rationale are documented in [dev-team-specialist-role-profiles.md](dev-team-specialist-role-profiles.md).
 
 Each default role declares:
 

package/docs/runtime-adapters.md

@@ -0,0 +1,86 @@
+# Runtime Adapters
+
+Open Orchestra uses one adapter catalog for LLM runtimes, IDEs, and CLI agents.
+The catalog keeps target names, default files, managed-block support, structured
+payload support, and usage guidance in one place.
+
+## Adapter Catalog
+
+```bash
+node bin/orchestra.js runtime adapters --json
+```
+
+Current targets:
+
+- `generic`: provider-agnostic Markdown in `ORCHESTRA.md`.
+- `claude`: Claude project memory in `CLAUDE.md`.
+- `cursor`: Cursor MDC rules in `.cursor/rules/open-orchestra.mdc`.
+- `codex`: Codex instructions in `AGENTS.md`.
+- `vscode`: extension/chat payloads in `.vscode/open-orchestra.runtime.json`
+  and `.vscode/open-orchestra.md`.
+- `windsurf`: Windsurf rules in `.windsurf/rules/open-orchestra.md`.
+
+## Init Modes
+
+Default project init keeps the current compact bootstrap behavior:
+
+```bash
+node bin/orchestra.js init
+```
+
+Generate only selected runtime files:
+
+```bash
+node bin/orchestra.js init --target claude,cursor,windsurf
+```
+
+Advisory mode creates workflow state without root instruction files unless a
+target is explicit:
+
+```bash
+node bin/orchestra.js init --advisory
+node bin/orchestra.js init --advisory --target claude
+```
+
+Unsafe roots are blocked before writes. Unknown non-temp directories require an
+explicit confirmation:
+
+```bash
+node bin/orchestra.js init --confirm-unknown
+```
+
+## Runtime Loop
+
+After init, any runtime should use the same local control-plane loop:
+
+```bash
+node bin/orchestra.js health --json
+node bin/orchestra.js task list --json
+node bin/orchestra.js context --task STORY-001 --json
+node bin/orchestra.js delegation decide --task STORY-001 --json
+node bin/orchestra.js skills render --target codex --task STORY-001
+node bin/orchestra.js protocol render --target codex --task STORY-001
+node bin/orchestra.js workflow render --target codex --task STORY-001
+```
+
+Change `--target` to the runtime that is executing the work. The workflow state,
+roles, evidence, reviews, and gates remain runtime-agnostic.
+
+## Web And VS Code
+
+The local web console exposes workspace classification and supported runtime
+targets through:
+
+```bash
+node bin/orchestra.js web
+```
+
+The API contracts are:
+
+```bash
+curl -s http://127.0.0.1:3717/api/workspace/classification
+curl -s http://127.0.0.1:3717/api/runtime/adapters
+```
+
+These endpoints are intended for VS Code, Cursor-like extensions, and other
+clients that need to show safe next actions without parsing human CLI output.

package/docs/runtime-llm-flow.md

@@ -0,0 +1,124 @@
+# Runtime LLM Flow
+
+Open Orchestra is the local control plane. The active LLM runtime is the parent
+agent today.
+
+That means Claude, Codex, Cursor, VS Code, Windsurf, or another LLM starts the
+work, reads the relevant project instructions, and calls `orchestra` commands to
+coordinate tasks, roles, skills, handoffs, reviews, evidence, gates, and model
+routing metadata. Open Orchestra does not yet spawn real provider-backed
+subagents by itself.
+
+## Startup Flow
+
+Use this sequence for a new project or a new task:
+
+```bash
+node bin/orchestra.js init
+node bin/orchestra.js health --json
+node bin/orchestra.js task add --id STORY-001 --title "Short title" --owner developer --goal "Outcome"
+node bin/orchestra.js context --task STORY-001 --json
+node bin/orchestra.js delegation decide --task STORY-001 --json
+node bin/orchestra.js plan --task STORY-001 --json
+node bin/orchestra.js skills plan --task STORY-001 --json
+node bin/orchestra.js skills render --target codex --task STORY-001
+node bin/orchestra.js protocol render --target codex --task STORY-001
+node bin/orchestra.js workflow render --target codex --task STORY-001
+node bin/orchestra.js commands manifest --json
+node bin/orchestra.js runtime bootstrap --target codex
+node bin/orchestra.js evidence add --task STORY-001 --role developer --type command --summary "npm run precommit passed" --command "npm run precommit" --exit-code 0
+node bin/orchestra.js gate --gate architecture --task STORY-001
+node bin/orchestra.js summary --json
+```
+
+Use `--target claude`, `--target cursor`, `--target codex`, `--target vscode`,
+`--target windsurf`, or `--target generic` when rendering skills, protocol, or
+workflow instructions for a specific runtime.
+
+`orchestra init` also refreshes compact managed bootstrap blocks in
+`ORCHESTRA.md` and `AGENTS.md`. These blocks tell the active LLM how to discover
+commands and which task loop to run without copying the full manual into the
+always-loaded context.
+
+Use explicit init targets when a project should generate runtime-specific files:
+
+```bash
+node bin/orchestra.js runtime adapters --json
+node bin/orchestra.js init --target claude,cursor,windsurf
+```
+
+## Parent Agent Prompts
+
+Claude:
+
+```text
+Use Open Orchestra as the local control plane for this repo. Treat yourself as
+the parent agent. Start by running health, context, delegation, plan, skills
+plan, and target-specific skill/protocol render commands. Do not spawn or claim
+subagents unless the local workflow state and user approval make that explicit.
+Record evidence and reviews before saying work is complete.
+```
+
+Codex:
+
+```text
+Use the local orchestra CLI before implementation. Confirm the task exists,
+inspect context and delegation, render Codex skills/protocol/workflow context,
+implement with focused tests, run precommit, then record evidence and review
+artifacts in Open Orchestra.
+```
+
+Cursor:
+
+```text
+Use Open Orchestra for task state and context. Render Cursor-targeted skills and
+protocol instead of copying large rule files. Keep generated MDC/MD blocks
+managed, record test evidence, and do not overwrite user-authored content.
+```
+
+Generic LLM runtime:
+
+```text
+Act as the parent agent. Use Open Orchestra commands as the source of truth for
+tasks, roles, skills, workflow templates, evidence, reviews, and gates. Ask the
+user before changing architecture or spending budget. Treat provider execution
+as future capability unless the project exposes an approved adapter.
+```
+
+## Model Routing
+
+Current model routing is metadata and policy plumbing. These commands inspect
+or update routing state, but they do not yet execute real provider-backed
+subagents:
+
+```bash
+node bin/orchestra.js model providers --json
+node bin/orchestra.js model set-role --role qa --provider fake --model fake-model
+node bin/orchestra.js model provenance list --json
+node bin/orchestra.js budget check --json
+```
+
+Future multi-model delegation should route by role capability, risk, budget,
+latency, and required evidence. For example, a parent agent could keep planning
+local, route security review to a stronger security model, route Playwright
+analysis to a browser-capable runtime, and request user approval before any
+budget fallback.
+
+## Current Limits
+
+- Open Orchestra has fake/provider-routing primitives, not real autonomous
+  provider execution.
+- It records delegation decisions, but it does not automatically spawn
+  subagents yet.
+- Parallel independent CLI commands are expected to work, but dependent commands
+  still need parent-agent ordering or future DAG semantics.
+- Workflow files are local state. Promote durable lessons into docs, skills, or
+  managed instruction blocks only after review.
+
+## Related Docs
+
+- [Skill Loading Strategy](skill-loading-strategy.md)
+- [Runtime Adapters](runtime-adapters.md)
+- [Open Orchestra MVP](orchestra-mvp.md)
+- [Source of Truth and Agent Learning](source-of-truth-and-agent-learning.md)
+- [Dogfooding Findings](open-orchestra-dogfooding-findings.md)

package/docs/setup-agents-dogfooding-findings.md

@@ -0,0 +1,101 @@
+# Setup Agents Dogfooding Findings
+
+This file tracks issues found while using Open Orchestra to coordinate the
+`setup-agents` improvement backlog.
+
+## Finding 1: Concurrent `task add` commands can corrupt `tasks.json`
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/85
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Command pattern:** multiple `node_modules/.bin/orchestra task add ...` commands executed concurrently
+- **Observed behavior:** `.agent-workflow/tasks.json` ended up with trailing partial JSON and subsequent Orchestra commands failed with `Unexpected non-whitespace character after JSON`.
+- **Impact:** users or automation that parallelize CLI calls can corrupt workflow state.
+- **Expected behavior:** state writes should be serialized, locked, or written atomically so concurrent commands either succeed safely or fail without corrupting existing state.
+- **Workaround used:** manually rewrote `.agent-workflow/tasks.json` as valid JSON and continued with sequential state-changing commands.
+- **Suggested fix:** introduce file-level locking plus atomic write through a temp file and rename for all workflow state mutations.
+- **Resolution:** workflow state writes are serialized with per-file lock directories and JSON state files are written through temporary files followed by atomic rename.
+
+## Finding 2: Evidence type validation is stricter than the CLI help implies
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/84
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Command pattern:** `orchestra evidence add --type validation ...`
+- **Observed behavior:** the command failed with `type must be one of: command, file, screenshot, trace, video, log, report`.
+- **Impact:** users must know the closed evidence type list before calling the command.
+- **Expected behavior:** CLI help should show the allowed values, and validation failures should suggest the nearest valid type when possible.
+- **Workaround used:** recorded validation evidence as `--type command`.
+- **Suggested fix:** update command help to include the enum and consider aliases such as `validation -> command`.
+- **Resolution:** `validation` is accepted as an alias for `command`; CLI help lists canonical types and the alias; invalid type errors include valid types and aliases.
+
+## Finding 3: `reviewer` is not accepted as a review role
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/86
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Command pattern:** `orchestra review --task SA-90 --role reviewer --result approve ...`
+- **Observed behavior:** the command failed with `unknown reviewer role: reviewer`.
+- **Impact:** the role catalog and README describe a Reviewer / Critic capability, but the review command does not accept the intuitive `reviewer` role id.
+- **Expected behavior:** `reviewer` should either be a valid role alias or the error should list accepted role ids.
+- **Workaround used:** record the approval with an existing valid role.
+- **Suggested fix:** add `reviewer` as a role alias or expose accepted roles in validation errors and CLI help.
+- **Resolution:** `reviewer` is accepted as an alias for `reviewer_critic`; CLI help lists the alias; unknown reviewer role errors include accepted role ids and aliases.
+
+## Finding 4: Concurrent `lock claim` commands can create duplicate lock ids
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/87
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Command pattern:** multiple `node_modules/.bin/orchestra lock claim ...` commands executed concurrently
+- **Observed behavior:** two distinct locks were created with the same id, `lock-1778052846730`, for different paths.
+- **Impact:** `lock release --id <id>` becomes ambiguous and can release the wrong lock or require manual state repair.
+- **Expected behavior:** lock ids should be collision-resistant even when lock claims happen in the same millisecond.
+- **Workaround used:** avoid concurrent state-mutating Orchestra commands and continue sequentially.
+- **Suggested fix:** generate lock ids with a random suffix or monotonic per-process sequence in addition to the timestamp.
+- **Resolution:** lock ids now include a timestamp plus `crypto.randomUUID()`, and concurrent lock claim regression coverage verifies uniqueness.
+
+## Finding 5: Runtime bootstrap examples are not portable after package install
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/96
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/setup-agents`
+- **Command pattern:** `node_modules/.bin/orchestra init --force`
+- **Observed behavior:** generated `AGENTS.md` and `ORCHESTRA.md` bootstrap blocks recommend commands such as `node bin/orchestra.js health --json` and `node bin/orchestra.js task list --json`.
+- **Impact:** those examples only work inside the Open Orchestra repository layout. When Open Orchestra is installed into another repository as a package or local file install, the consumer repo does not have `bin/orchestra.js`, so agents following the generated bootstrap will run the wrong command.
+- **Expected behavior:** generated runtime bootstrap guidance should use the installed executable form, such as `orchestra health --json`, or derive a target-appropriate command prefix from the runtime/install context.
+- **Workaround used:** run `node_modules/.bin/orchestra ...` directly from the consuming repo.
+- **Suggested fix:** update command manifest examples and runtime bootstrap rendering to prefer `orchestra` for installed usage, with repo-local `node bin/orchestra.js` reserved for Open Orchestra development docs.
+- **Resolution:** command manifest examples and generated runtime bootstrap blocks now use the portable installed executable form, `orchestra ...`; regression coverage verifies generated bootstrap content does not include `node bin/orchestra.js`.
+
+## Finding 6: Concurrent `evidence add` commands can overwrite artifact files
+
+- **Open Orchestra issue:** https://github.com/jterrats/open-orchestra/issues/98
+- **Status:** fixed in Open Orchestra
+
+- **Date found:** 2026-05-06
+- **Source repo:** `/Users/polux/dev/open-orchestra`
+- **Command pattern:** multiple `orchestra evidence add ...` commands executed concurrently
+- **Observed behavior:** two distinct `EVIDENCE_ADDED` events pointed to the same artifact file when they were created in the same millisecond.
+- **Impact:** the later evidence write overwrote the earlier evidence content, leaving one event pointing to mismatched artifact content.
+- **Expected behavior:** every evidence event should keep a unique artifact path even under concurrent CLI usage.
+- **Workaround used:** rerun evidence recording sequentially.
+- **Suggested fix:** include a collision-resistant suffix in generated evidence artifact filenames.
+- **Resolution:** evidence artifact filenames now include a UUID in addition to task, timestamp, and type; concurrent CLI regression coverage verifies unique artifact paths.
+
+## Workspace State Safety Notes
+
+- Open Orchestra serializes local workflow state writes with per-file lock directories next to the target file.
+- JSON state files are written through temporary files and atomic rename to avoid partial JSON on interruption.
+- The lock mechanism is intended for local filesystems. Network filesystems or stale lock directories after a killed process may require manual cleanup if a command times out waiting for a lock.
+- State-mutating Orchestra commands should still prefer explicit task/path locks when multiple agents edit code, because file serialization protects workflow metadata, not source-code merge conflicts.

package/docs/skill-loading-strategy.md

@@ -0,0 +1,114 @@
+# Skill Loading Strategy
+
+Open Orchestra should keep primary agent instruction files small. AGENTS.md, CLAUDE.md, Cursor rules, and ORCHESTRA.md should act as an entry point, not as the full operating manual for every capability.
+
+## Goal
+
+Load detailed capability instructions only when the current task needs them, while keeping core governance rules always available.
+
+## Core Pattern
+
+Use a two-layer model:
+
+- **Core instructions:** short, always-loaded rules for safety, user alignment, engineering standards, gates, and how to select skills.
+- **Skills:** focused sub-files with task-specific procedures, examples, scripts, templates, and evidence rules.
+
+The main files should include a compact Skill Index instead of embedding every procedure inline.
+
+## Skill Manifest
+
+Each skill should expose metadata that allows a parent agent or middleware to decide whether to load it.
+
+```json
+{
+  "id": "static-analysis",
+  "name": "Static Analysis",
+  "summary": "Run and interpret local quality, type, dependency, secret, and security checks.",
+  "triggers": ["lint", "typecheck", "secret", "sast", "precommit", "dependency"],
+  "roles": ["developer", "tech_lead", "qa", "sdet", "security", "devops"],
+  "capabilities": ["quality-gate", "security-review", "commit-readiness"],
+  "riskAreas": ["security", "release", "maintainability"],
+  "entry": "skills/static-analysis/SKILL.md",
+  "assets": ["skills/static-analysis/checklist.md"],
+  "evidence": ["command", "report"],
+  "sourceGroups": ["codebase", "quality-security", "agent-memory"],
+  "loadBudget": "normal"
+}
+```
+
+## Source Selection
+
+Before loading full skill instructions, the parent agent should select authoritative source groups for the task. The source catalog lives in `.agent-workflow/source-of-truth.json` and is documented in [source-of-truth-and-agent-learning.md](source-of-truth-and-agent-learning.md).
+
+Skill manifests should be able to declare `sourceGroups` so the orchestrator can load the right local files, docs, official vendor references, and prior lessons without pulling unrelated context.
+
+## Loading Flow
+
+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.
+
+## Built-in Skill Candidates
+
+- `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.
+- `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.
+- `release-readiness`: validate gates, rollback, observability, support, and customer-impact evidence.
+- `model-evaluation`: run prompt/model/provider-routing evaluations and compare outputs.
+- `source-of-truth`: select authoritative project, vendor, and workflow sources before acting.
+- `agent-learning`: record reusable failure lessons and promote repeated lessons into skills or rules.
+
+## Fallback for LLMs Without Native Skills
+
+If an LLM platform cannot load skills dynamically, Open Orchestra should provide middleware behavior:
+
+- A parent orchestrator reads the manifest and selects skills.
+- The orchestrator injects only the selected skill text into the child agent prompt.
+- The orchestrator keeps full skill content out of the base system prompt.
+- The loaded skill IDs are written to `.agent-workflow/` events and handoff artifacts.
+
+This keeps the project portable across Cursor, Claude, Codex, VS Code, GitHub Actions, and future web clients.
+
+## Main File Budget
+
+Primary MD files should stay bounded:
+
+- Keep role and skill catalogs as indexes with links.
+- Move long procedures into skills or docs.
+- Prefer activation criteria over exhaustive instructions.
+- Keep examples inside the skill that owns them.
+- Review file size when a main MD crosses a practical context threshold.
+
+## 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 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.
+- `orchestra sources list` exposes the source-of-truth catalog.
+- `orchestra lessons list/add/promote` manages local agent learning and promotes repeated lessons into reviewable artifacts.
+
+The CLI render path is the universal fallback for environments without native skill support.
+
+## Generated Markdown Update Policy
+
+Generated `.md`, `.mdc`, and agent instruction files should be managed through explicit ownership rules instead of blind rewrites.
+
+- Use generated block markers such as `<!-- open-orchestra:start skill-index -->` and `<!-- open-orchestra:end skill-index -->` for sections the CLI owns.
+- Keep user-authored sections outside managed blocks and never overwrite them during generation.
+- Store generator metadata: generator name, version, source manifest, target file, managed block id, and last rendered hash.
+- Default to idempotent updates: rerunning the generator without source changes should produce no diff.
+- Provide `--dry-run` and `--check` modes before writing generated docs.
+- If a generated section was manually edited, detect drift and require explicit `--force` or emit a conflict.
+- Promote stable runtime lessons or prompts into versioned docs/rules/skills only through reviewed generated blocks.
+
+This keeps Claude, Cursor, Codex, VS Code, and generic CLI outputs synchronized without turning primary instruction files into unbounded generated blobs.

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

@@ -0,0 +1,83 @@
+# Source of Truth and Agent Learning
+
+Open Orchestra should make context provenance explicit. Agents and subagents should know where to look before acting, and they should record repeatable failure lessons after an action fails.
+
+## Source of Truth Catalog
+
+The source catalog answers: which document, file, or external reference is authoritative for a decision?
+
+Default source groups:
+
+- `project-instructions`: `AGENTS.md`, `ORCHESTRA.md`, `CLAUDE.md`, Cursor rules, and local agent rules.
+- `product-backlog`: GitHub issues, local backlog docs, acceptance criteria, user stories, and task graph state.
+- `architecture`: ADRs, architecture docs, service boundaries, diagrams, domain models, and integration contracts.
+- `codebase`: source files, tests, package manifests, config, generated types, and local command contracts.
+- `quality-security`: static analysis config, pre-commit hooks, SAST reports, dependency scans, secret scans, QA plans, and Playwright evidence.
+- `devops-runtime`: CI/CD workflows, deployment docs, IaC, observability, rollback, incident, and release artifacts.
+- `vendor-docs`: official provider, framework, package, cloud, and browser documentation.
+- `agent-memory`: decisions, handoffs, evidence, prompt registry entries, and lessons learned.
+
+Rules:
+
+- Prefer local project sources before generic external guidance.
+- Prefer primary vendor documentation over blogs, examples, or generated answers.
+- For current or fast-changing APIs, verify against official docs before implementation.
+- Record which source group justified a material decision in decisions, handoffs, evidence, or final summaries.
+- If sources conflict, stop and record the conflict instead of silently choosing one.
+
+## Versioning Policy
+
+- Track the schema, documentation, examples, and promoted rules or skills.
+- Do not track the live `.agent-workflow/agent-lessons.jsonl` file by default; it is local runtime state and can contain machine-specific commands, timestamps, paths, or sensitive context.
+- Do not track the live `.generated-prompts/` directory by default; prompt registers are generated local runtime memory unless a project explicitly promotes selected entries into versioned docs, rules, or skills.
+- Track `source-of-truth.json` only when a project intentionally wants shared authoritative sources. Otherwise regenerate it through `orchestra init` and project config.
+- Promote repeated lessons into versioned skills or rules after review.
+
+## Agent Lessons Log
+
+The lessons log captures operational mistakes that an agent can avoid next time. It is not a blame log; it is a repeat-prevention mechanism.
+
+Store lessons as JSONL in `.agent-workflow/agent-lessons.jsonl`.
+
+Example entry:
+
+```json
+{
+  "timestamp": "2026-05-03T00:00:00.000Z",
+  "taskId": "SKILL-001",
+  "actor": "parent",
+  "operation": "edit-doc-with-node-script",
+  "failedAction": "embedded Markdown fences inside a JavaScript template literal",
+  "errorSignature": "SyntaxError: Unexpected identifier",
+  "rootCause": "unescaped backticks in generated script content",
+  "fix": "build long Markdown content as an array of lines or escape fences explicitly",
+  "prevention": "before running generated edit scripts, scan for nested template literals and Markdown fences",
+  "appliesTo": ["node", "markdown", "code-generation"],
+  "verifiedBy": ["reran edit script successfully"]
+}
+```
+
+Record a lesson when:
+
+- The same class of failure is likely to happen again.
+- A command failed because of quoting, escaping, shell behavior, permissions, cwd, missing dependency, or stale assumption.
+- A test failure revealed a reusable project convention.
+- A provider, tool, or runtime behaved differently than expected.
+
+Do not record a lesson for:
+
+- One-off typos with no reusable prevention value.
+- Secrets, raw credentials, private customer data, or sensitive prompt/response content.
+- Failures already covered by a current lesson unless the prevention changed.
+
+## Learning Flow
+
+1. Before acting, select relevant source groups and load only the necessary files or docs.
+2. Before repeating a risky operation, search `.agent-workflow/agent-lessons.jsonl` for matching operation, error signature, or tool.
+3. After a failure, classify whether it is reusable knowledge.
+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.
+
+## 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.