@evo-dev/evodev 0.0.1-alpha → 0.0.1-alpha.10

package/dist/.claude-plugin/marketplace.json

@@ -4,13 +4,13 @@
     "name": "EvoDev"
   },
   "description": "EvoDev Claude Code hook plugins for AI-assisted R&D workflows.",
-  "version": "0.1.0",
+  "version": "0.0.1-alpha.10",
   "plugins": [
     {
       "name": "evodev",
       "source": "./packages/plugin",
       "description": "EvoDev hook integration for disciplined AI coding workflows.",
-      "version": "0.1.0",
+      "version": "0.0.1-alpha.10",
       "author": {
         "name": "EvoDev"
       },

package/dist/assets/agents/review/code-reviewer/examples.md

@@ -11,7 +11,7 @@ This is useful because it includes severity, location, problem, and an actionabl
 ## Scope finding
 
 ```text
-- BLOCKER: packages/plugin/hooks/plugin.ts This task added Claude sync behavior while the current task only allows canonical assets -> Remove plugin implementation from this task and handle it in the plugin sync task.
+- CRITICAL: packages/plugin/hooks/plugin.ts This task added Claude sync behavior while the current task only allows canonical assets -> Remove plugin implementation from this task and handle it in the plugin sync task.
 ```
 
 ## Non-finding

package/dist/assets/agents/review/code-reviewer/prompt.md

@@ -33,7 +33,7 @@ If the review scope is unclear, ask for the missing context instead of guessing.
 
 ## Severity levels
 
-- **BLOCKER:** Must fix before merge or delivery. Includes data loss, privacy boundary violations, project-asset writes outside scope, broken core behavior, or a failed required gate.
+- **CRITICAL:** Must address before merge or delivery. Includes data loss, privacy boundary violations, project-asset writes outside scope, broken core behavior, or a failed required gate.
 - **HIGH:** Likely user-visible bug, unsafe default, missing required validation, or mismatch with the current acceptance criteria.
 - **MEDIUM:** Maintainability, incomplete edge handling, weak diagnostics, or test gap that should be addressed soon.
 - **LOW:** Minor clarity, naming, or documentation issue. Do not report pure style preference unless it affects comprehension.

package/dist/assets/agents/review/code-reviewer/verification.md

@@ -4,7 +4,7 @@ Before returning a review decision, confirm:
 
 1. The reviewed scope matches the assigned task or diff.
 2. Findings are grouped by severity and include a concrete fix.
-3. Blockers cover safety, privacy, user-data, project-asset, and required-gate failures.
+3. Critical findings cover safety, privacy, user-data, project-asset, and required-gate failures.
 4. Style-only comments are omitted unless they affect correctness or maintainability.
 5. Verification commands are reported with observed PASS, FAIL, or not-run status.
 

package/dist/assets/skills/coding/knowledge-distillation/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: knowledge-distillation
+description: Use when turning reviewed execution evidence into atomic, privacy-filtered, role-tagged engineering knowledge candidates, evos cases, repo asset proposals, or role-agent/team suggestions.
+license: MIT
+---
+
+# Knowledge Distillation / 提炼
+
+## Purpose
+
+Knowledge Distillation is an evidence curation pipeline. It turns reviewed execution evidence into an OKF-aware transient knowledge plan. The organizer, not this skill, writes final OKF Markdown files after dedupe, conflict handling, tagging, link updates, index generation, and logging.
+
+It is not a trace summarizer, automatic memory writer, OKF file writer, or team launcher.
+
+## Use This Skill When
+
+- A completed task produced a repeatable repository-specific lesson.
+- A review, failure, postmortem, or user correction should become a rule, warning, checklist item, decision, pattern, or evos case.
+- Execution evidence suggests a repo-local skill, rule, role agent, subagent, or EvoHub team.
+- Reviewed execution evidence shows a task split, tool call, skill output, or subagent handoff was incomplete, inaccurate, inefficient, or unsafe.
+- Role-specific knowledge should later be available to a role agent, subject to explicit consent and runtime scope.
+
+## Do Not Use This Skill For
+
+- Writing `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.codex/`, `.evodev/`, source files, or project assets without explicit project opt-in.
+- Storing credentials or wholesale prompts, transcripts, source files, source dumps, or raw command output. Distilled private facts and necessary short excerpts may remain in user-local knowledge.
+- Treating unreviewed observations, model reflection, or trace logs as accepted memory.
+- Writing final OKF concept documents directly; output a transient plan for the organizer.
+- Starting subagents or teams automatically.
+
+## Inputs
+
+Work from one bounded evidence window. Prefer reviewed, minimized inputs:
+
+- Task goal, final outcome, and repository scope.
+- Verification evidence, failures, fixes, and review findings.
+- Accepted corrections or explicit user feedback.
+- Relevant external authority, when the lesson depends on a standard, official documentation, or upstream behavior.
+- Relevant OKF v0.1 constraints: concept documents need YAML frontmatter with non-empty `type`; `index.md` and `log.md` are reserved at every directory level; bundle-relative absolute Markdown links are preferred for durable relationships.
+- Existing OKF index snippets or concept summaries, when available, so duplicate and conflict risk can be scored before proposing new candidates.
+- Candidate roles that should care, such as `architect`, `implementer`, `reviewer`, `tester`, `security`, `release`, `docs`, or user-defined role slugs.
+
+Do not ingest raw traces wholesale. If trace evidence is needed, use a redacted summary and evidence references.
+
+## Evidence Policy
+
+Classify every input before extraction:
+
+| Evidence class | Use | Constraint |
+|---|---|---|
+| `verified-run` | Test/build/lint/check outcomes and accepted fixes | Store references and summaries, not raw output |
+| `reviewed-finding` | Code review, security review, or user correction | Keep finding, impact, and accepted action separate |
+| `decision-record` | Architecture or workflow decision | Preserve context, decision, alternatives, consequences |
+| `postmortem-case` | Failure, incident, or after-action review | Preserve expected vs actual, cause, action item |
+| `official-reference` | Standards, docs, upstream behavior | Include URL/version/date; do not overquote |
+| `model-reflection` | Agent-generated synthesis | Candidate only; never accepted without review |
+| `tool-call-summary` | Tool selection, risk class, status, and recovery | No raw command or raw stdout/stderr by default |
+| `skill-invocation` | Skill id/version, input class, output schema, and reviewed result | Record omissions or inaccuracies as findings; do not store raw prompts/source |
+| `subagent-lifecycle` | Role, reason, scope, status, output refs, and merge result | No raw transcript |
+| `evo-eval-result` | Eval case pass/fail and assertion summary | Store fixture refs and assertion results, not private raw data |
+
+## Distillation Pipeline
+
+1. **Scope**: identify repo, task, role audience, workflow audience, path scope, evidence ids, and user-local OKF target scope.
+2. **Minimize**: remove credentials, wholesale prompts/logs/source/command output, and one-off noise. Preserve private facts or short excerpts only when needed to keep the knowledge accurate and reusable.
+3. **Analyze execution structure**: when event evidence is present, identify task slices, owner roles, dependencies, key tool calls, skill invocations, subagent lifecycle events, verification gates, and merge outcomes.
+4. **Extract atomic candidates**: one claim per candidate. Allowed `kind` values are `rule`, `decision`, `pattern`, `anti-pattern`, `warning`, `checklist`, `concept`, `workflow-improvement`, `task-split-improvement`, `tool-use-improvement`, `skill-improvement`, `repo-asset-suggestion`, `role-agent-suggestion`, `team-suggestion`, `eval-set`, and `open-question`.
+5. **Separate fact from inference**: mark whether the candidate is directly evidenced or inferred from evidence.
+6. **Classify**: add `okfType`, `targetPath`, `stableKey`, `roleTags`, `repoTags`, `workflowTags`, `pathScopes`, `domainTags`, `stability`, `sensitivity`, and `targetStore`.
+7. **Score**: estimate evidence strength, reuse value, actionability, stability, novelty, privacy risk, and duplication risk.
+8. **Pair improvements with evals**: every proposed skill, role-agent, team, workflow, routing, tool-use, or subagent behavior change should include an `evoEvalSets` entry, unless the plan explains why eval coverage is not applicable.
+9. **Privacy gate**: reject credentials and unbounded raw copying. Private facts, internal links, local paths, emails, and short excerpts may remain in local-private knowledge when necessary.
+10. **Route**: emit `no_write`, `create`, `update`, `skip`, or `needs-human` for each candidate.
+11. **Plan OKF organization**: provide canonical concept targets and repo/role/workflow overlay updates. Do not emit final OKF files.
+12. **Recovery notes**: explain conflicts, stale information, required repo fact checks, and why human intervention is needed when applicable.
+
+## Output Schema
+
+Return executable JSON with `schemaVersion: 1` and `kind: "knowledge-distillation-output"`. The runtime parser converts this output into an OKF plan and validates the full contract before any OKF directory or concept write occurs. Invalid outputs become validation failed-plan artifacts; those artifacts are redacted, non-resumable, and inspectable with `evo plan show`.
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "knowledge-distillation-output",
+  "projectKey": "evodev",
+  "runId": "run-123",
+  "createdAt": "2026-06-24T00:00:00.000Z",
+  "evidenceWindowId": "evidence-run-123",
+  "summary": "What reusable improvement was found.",
+  "evidenceRefs": [
+    {
+      "id": "source-1",
+      "kind": "verification",
+      "source": "state/evidence/metadata.json",
+      "rawContentStored": false,
+      "externalContentCopied": false
+    }
+  ],
+  "evoEvalSets": [
+    {
+      "id": "eval-role-routing-1",
+      "target": { "kind": "role-agent-suggestion", "id": "candidate-1" },
+      "purpose": "Guard a behavior-changing active write.",
+      "roleTags": ["reviewer"],
+      "cases": [
+        {
+          "id": "case-1",
+          "inputRefs": ["source-1"],
+          "assertions": ["Candidate remains metadata-only and review-state gated."],
+          "expectedReviewState": "auto-accepted"
+        }
+      ],
+      "privacy": {
+        "usesRawPrompt": false,
+        "usesSourceDump": false,
+        "usesRawCommandOutput": false
+      },
+      "decision": "create"
+    }
+  ],
+  "knowledgeCandidates": [
+    {
+      "id": "candidate-1",
+      "decision": "auto-accept",
+      "kind": "rule",
+      "okfType": "EvoDev Rule",
+      "targetStore": "okf",
+      "targetPath": "concepts/rules/workspace-check.md",
+      "stableKey": "rule:verification:workspace-check",
+      "confidence": "high",
+      "title": "Workspace check before completion",
+      "description": "Run the workspace check before reporting TypeScript CLI completion.",
+      "claim": "For TypeScript CLI changes, run the workspace check before reporting completion.",
+      "basis": "direct",
+      "metadataOnlyEvidence": true,
+      "howToApply": "Add bun run check to the verification plan.",
+      "antiCriteria": ["Do not mark completion from lint alone."],
+      "roleTags": ["implementer", "reviewer"],
+      "repoTags": ["evodev"],
+      "workflowTags": ["feature-implementation"],
+      "pathScopes": ["packages/cli/", "packages/core/"],
+      "relatedConceptLinks": ["/concepts/verification/workspace-quality-gate.md"],
+      "overlayUpdates": [
+        {
+          "targetPath": "roles/reviewer/verification.md",
+          "operation": "append-link",
+          "link": "/concepts/rules/workspace-check.md"
+        }
+      ],
+      "scores": {
+        "evidenceStrength": 5,
+        "reuseValue": 4,
+        "actionability": 4,
+        "stability": 4,
+        "privacyRisk": 1,
+        "duplicationRisk": 1
+      },
+      "decisionReason": "Auto-accepted from verified metadata-only evidence.",
+      "evidenceRefs": ["source-1"],
+      "reviewState": "auto-accepted",
+      "evalSetRefs": [],
+      "bodySections": {
+        "summary": "Run the workspace check before reporting completion.",
+        "appliesWhen": ["TypeScript CLI or core changes were made."],
+        "guidance": ["Run bun run check and report the result."],
+        "antiCriteria": ["Do not store raw command output."],
+        "verification": ["Workspace check passed with metadata-only evidence."],
+        "citations": []
+      },
+      "privacyCheck": {
+        "rawPromptsStored": false,
+        "rawLogsStored": false,
+        "sourceDumpsStored": false,
+        "rawCommandOutputStored": false,
+        "secretsStored": false,
+        "internalLinksStored": false
+      }
+    }
+  ],
+  "droppedSignals": [
+    {
+      "evidenceRef": "event-17",
+      "reason": "Routine tool-call metadata with no reusable lesson."
+    }
+  ],
+  "conflicts": [],
+  "privacyCheck": {
+    "rawPromptsStored": false,
+    "rawLogsStored": false,
+    "sourceDumpsStored": false,
+    "rawCommandOutputStored": false,
+    "secretsStored": false,
+    "internalLinksStored": false
+  }
+}
+```
+
+Required candidate fields are `id`, `decision`, `kind`, `okfType`, `targetStore`, `targetPath`, `stableKey`, `confidence`, `title`, `description`, `claim`, `basis`, `metadataOnlyEvidence`, `howToApply`, `antiCriteria`, `roleTags`, `repoTags`, `workflowTags`, `pathScopes`, `relatedConceptLinks`, `overlayUpdates`, `scores`, `decisionReason`, `evidenceRefs`, `reviewState`, `bodySections`, and `privacyCheck`.
+
+All raw-content and credential privacy flags must remain `false`. `internalLinksStored` is instead a disclosure flag: set it to `true` when the durable candidate retains an HTTP(S) link. EvoDev recomputes this field locally before persistence.
+
+Valid decisions are `auto-accept`, `create`, `update`, `needs-human`, `skip`, and canonical `no_write`. `no-write` may be normalized by the runtime but new output should emit `no_write`. Active writes (`auto-accept`, `create`, `update`) must target `okf`, use reviewState `auto-accepted` or `accepted`, use metadata-only evidence, include evidence refs, have a safe relative `.md` target path outside reserved `index.md` and `log.md`, and include verification or `verificationNotApplicableReason`.
+
+Behavior-changing active writes, including skill, role-agent, team, workflow, routing, tool-use, task-split, and subagent changes, must include `evalSetRefs` that point to provided `evoEvalSets`. Eval sets must be metadata-only and use privacy flags `usesRawPrompt: false`, `usesSourceDump: false`, and `usesRawCommandOutput: false`.
+
+Scoring uses 1-5 integers for `evidenceStrength`, `reuseValue`, `actionability`, `stability`, `privacyRisk`, and `duplicationRisk`. A candidate should not target `okf` unless evidence strength, reuse value, and actionability justify future retrieval and privacy risk is low. `no_write` is a normal result and should be common.
+
+## Write Targets
+
+Default output is a transient plan only.
+
+- `okf`: stable facts, decisions, constraints, concepts, evos cases, and reusable rules that the organizer may write into user-local OKF.
+- `evo-eval-set`: regression cases tied to proposed or accepted behavior changes.
+- `repo-asset-proposal`: suggested repo rules, skills, role agents, subagents, or teams. Requires explicit project opt-in before any repository write.
+- `none`: useful observation that should stay in the report and not become durable knowledge.
+
+Project-local writes remain out of scope for this skill.
+
+## Role Tags
+
+Every durable candidate must include at least one role tag. Prefer stable role slugs:
+
+- `architect`
+- `implementer`
+- `reviewer`
+- `tester`
+- `security`
+- `release`
+- `docs`
+
+Use user-defined role slugs only when a reviewed role-agent definition exists. Treat role tags as retrieval/routing filters, not decorative labels.
+
+## Human Intervention Triggers
+
+Mark a candidate as `needs-human` when it:
+
+- Affects security, privacy, release, architecture, or cross-repo behavior.
+- Suggests a project-local file write.
+- Suggests changing a skill, role agent, team, workflow, routing rule, tool-use policy, or subagent behavior without an associated `evoEvalSets` entry or explicit not-applicable reason.
+- Has low evidence strength, high privacy risk, or ambiguous repo scope.
+- Would change role-agent behavior, EvoHub team composition, or runtime retrieval behavior.
+- Conflicts with existing OKF guidance in a way the organizer cannot resolve from current repo facts.
+- Is derived primarily from model reflection rather than verified evidence.
+
+## Runtime Attention Boundary
+
+Only active OKF concepts under `~/.evodev/knowledge/okf` may influence retrieval. Runtime loading remains gated by role selection, repo scope, workflow scope, path scope, privacy policy, and consent. Transient plans, failed plans, repo proposals, and `no_write` observations must not influence routing or runtime behavior.
+
+## References
+
+For method comparisons and design rationale, read `references/knowledge-distillation-methods.md` in this skill directory. For OKF structure, reserved filenames, concept frontmatter, links, indexes, logs, and conformance rules, follow the Open Knowledge Format v0.1 spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md.

package/dist/assets/skills/coding/knowledge-distillation/manifest.json

@@ -0,0 +1,10 @@
+{
+  "id": "knowledge-distillation",
+  "name": "Knowledge Distillation / 提炼",
+  "version": "0.1.0",
+  "category": "coding",
+  "description": "Distill repository-relevant rules, evos cases, skill/role/team improvement proposals, and eval sets from reviewed execution evidence without writing project assets by default.",
+  "targets": ["claude", "codex"],
+  "entry": "SKILL.md",
+  "license": "MIT"
+}

package/dist/assets/skills/coding/knowledge-distillation/references/knowledge-distillation-methods.md

@@ -0,0 +1,126 @@
+# Knowledge Distillation Method Notes
+
+This reference explains why the skill uses an evidence curation pipeline instead of a generic summarization workflow.
+
+## Method Comparison
+
+| Method | What it contributes | EvoDev adaptation |
+|---|---|---|
+| Postmortem / SRE review | Blameless failure analysis, root cause, impact, action items | Use for failure-derived `warning`, `anti-pattern`, `checklist`, and `workflow-improvement` candidates |
+| After Action Review | Expected vs actual, what went well, what failed, what changes next time | Use for evos cases and team/process improvement candidates |
+| Lessons learned systems | Reviewed lessons from projects/programs, not raw incident notes | Keep active OKF knowledge separate from raw evidence and transient plans |
+| ADR / decision logs | One durable decision with context, alternatives, rationale, consequences | Use `decision` candidates for architecture/workflow choices |
+| SKOS-style knowledge organization | Concepts, labels, narrower/broader/related terms, scope notes | Keep role tags and domain tags controlled enough for retrieval |
+| Agent memory research | Semantic facts, episodic cases, procedural improvements | Split knowledge, evos cases, and repo asset suggestions instead of one memory bucket |
+| Agent skills | Small triggerable procedures with references/assets for larger material | Keep `SKILL.md` operational and place long examples/taxonomies in references |
+| Evaluation-driven development | Behavior changes need regression cases and objective assertions | Pair skill, role, team, workflow, routing, tool-use, and subagent proposals with evo eval sets |
+
+## Evidence Quality
+
+Prefer evidence in this order:
+
+1. Verified local outcomes: tests, typecheck, lint, build, release dry-run, smoke checks, or accepted fixes.
+2. Reviewed findings: code review, security review, user correction, or postmortem conclusion.
+3. Official or upstream references: standards, vendor docs, framework docs, release notes, or source repositories.
+4. Existing repository contracts: `AGENTS.md`, design docs, task contracts, tests, schemas, and explicit policy files.
+5. Model reflection: useful for candidate generation only; never enough for active OKF knowledge.
+
+## Candidate Types
+
+- `rule`: normative guidance with a clear trigger and expected behavior.
+- `decision`: accepted choice plus context, alternatives, and consequences.
+- `pattern`: repeatable implementation or workflow shape.
+- `anti-pattern`: repeatable bad shape to avoid.
+- `warning`: risk that should influence planning or review.
+- `checklist`: short verification list for a role or workflow.
+- `concept`: term, domain note, taxonomy entry, or glossary item.
+- `workflow-improvement`: process change with trigger and expected future behavior.
+- `task-split-improvement`: improved decomposition, dependencies, owner roles, evidence, or stop conditions.
+- `tool-use-improvement`: improved tool selection, risk classification, command gating, or verification behavior.
+- `skill-improvement`: proposed change to a skill trigger, input requirements, output schema, references, or behavior.
+- `repo-asset-suggestion`: proposed project rule, skill, agent, subagent, or config file.
+- `role-agent-suggestion`: proposed user/project role definition or role capability.
+- `team-suggestion`: proposed EvoHub team composition and trigger.
+- `eval-set`: proposed regression cases for a skill, role, team, workflow, routing, tool-use, or subagent behavior.
+- `open-question`: unresolved issue that should not become accepted memory yet.
+
+## Scoring Rubric
+
+Use 1-5 integers. Keep the score approximate; it is a review aid, not a scientific metric.
+
+| Score | High value means | Low value means |
+|---|---|---|
+| `evidenceStrength` | Directly supported by verified/reviewed evidence | Mostly inferred or speculative |
+| `reuseValue` | Likely useful across future similar tasks | One-off or too narrow |
+| `actionability` | Clear trigger and next action | Vague or only descriptive |
+| `stability` | Likely to remain true for the repo/workflow | Depends on volatile context |
+| `privacyRisk` | Higher is worse: needs sensitive context | Redacted summary is enough |
+| `duplicationRisk` | Higher is worse: likely duplicate | Distinct from existing entries |
+
+Suggested write queue rule:
+
+- Propose active OKF knowledge only when `evidenceStrength >= 4`, `reuseValue >= 3`, `actionability >= 3`, `privacyRisk <= 2`, and `duplicationRisk <= 3`.
+- Propose evos cases when the item is mainly about a trigger/intervention/outcome history.
+- Propose repo assets only when repeated future execution would benefit from a rule, skill, role, or team and explicit project opt-in can be obtained.
+- Propose evo eval sets whenever a skill, role-agent, team, workflow, routing, tool-use, or subagent behavior change is proposed. If no eval is useful, state why in the proposal.
+
+## Executable Contract Notes
+
+The runtime accepts only JSON outputs with `kind: "knowledge-distillation-output"` and `schemaVersion: 1`. Candidate decisions are `auto-accept`, `create`, `update`, `needs-human`, `skip`, and canonical `no_write`. Active writes must be metadata-only, evidence-backed, review-state gated, verified, and targeted at safe relative `.md` OKF paths. Behavior-changing active writes must include `evalSetRefs` that point to provided `evoEvalSets`.
+
+Contract validation runs before OKF writes. Validation failures are saved as redacted, non-resumable failed-plan artifacts; organizer failures preserve a resumable plan. Failed artifacts are organizer inputs only and must not influence runtime retrieval.
+
+## Evolution Event Analysis
+
+Use reviewed event evidence to explain why the future behavior should change.
+
+| Signal | Good analysis asks |
+|---|---|
+| Task slices | Was the work decomposed into verifiable units with owner roles, dependencies, and stop conditions? |
+| Tool calls | Was the selected tool appropriate, gated by risk, and followed by verification or recovery? |
+| Skill invocations | Did the skill trigger correctly, receive the needed evidence, and produce a complete schema with privacy checks? |
+| Subagent lifecycle | Was the role necessary, bounded, mergeable, and verified without storing transcript content? |
+| Verification | Did required checks run at the right time and produce evidence for the claim? |
+
+Common skill defects:
+
+- `trigger-mismatch`: the skill was invoked when it should not have been, or missed when it should have run.
+- `input-gap`: required evidence class was missing.
+- `output-omission`: a required proposal, field, path, role tag, privacy check, or eval set was absent.
+- `inaccurate-claim`: output contradicted verified evidence.
+- `schema-drift`: output did not match the declared contract.
+- `privacy-defect`: output depended on raw private content.
+
+## Evo Eval Set Types
+
+| Type | Checks |
+|---|---|
+| `schema` | Required fields, enum values, ids, and status are present. |
+| `omission-detection` | Missing recommendations, evidence refs, privacy checks, or eval sets are caught. |
+| `privacy` | Raw prompt/source/command output/secrets are not stored. |
+| `routing` | A skill, workflow, role, or team should or should not trigger. |
+| `role-attention` | Role-tagged knowledge is selected only when scope, consent, and role policy match. |
+| `tool-use` | Tool choice, risk classification, and verification behavior are correct. |
+| `subagent-routing` | Role selection, scope, output contract, and merge requirements are correct. |
+
+## Storage Mapping
+
+| Candidate target | Canonical layer | Notes |
+|---|---|---|
+| `okf` | Active knowledge | OKF Markdown concepts with frontmatter, provenance, links, directory indexes, and logs |
+| `evo-eval-set` | Evolution eval sets | Regression cases tied to proposed or accepted behavior changes |
+| `repo-asset-proposal` | Proposal queue first | Never write project files by default |
+| `none` | Report only | Useful but not durable |
+
+Indexes, vector search, graph exports, and runtime caches are derived views. They must be rebuildable from active OKF concepts and must not store raw private content. Transient knowledge plans are organizer inputs, not accepted knowledge.
+
+## Source Notes
+
+- Google SRE postmortem practice: https://sre.google/sre-book/postmortem-culture/
+- US Army AAR guidance: https://www.first.army.mil/Portals/102/FM%207-0%20Appendix%20K.pdf
+- NASA Lessons Learned: https://www.nasa.gov/nasa-lessons-learned/
+- ADR references and templates: https://adr.github.io/
+- W3C SKOS Reference: https://www.w3.org/TR/skos-reference/
+- W3C PROV-O provenance ontology: https://www.w3.org/TR/prov-o/
+- OpenAI Agents SDK sessions/memory reference: https://openai.github.io/openai-agents-python/sessions/
+- Claude Code skills documentation: https://docs.anthropic.com/en/docs/claude-code/skills

package/dist/assets/team/agents/code-reviewer.md

@@ -0,0 +1,48 @@
+---
+name: code-reviewer
+description: Review scoped changes for correctness, regressions, maintainability, and missing tests.
+tools: Read, Grep, Glob, Bash
+evodev:
+  runtime: codex
+  thinking: high
+  writeMode: read-only
+---
+
+# Code Reviewer
+
+You review implementation quality. Findings should be concrete, reproducible, and tied to the task scope.
+
+## Responsibilities
+
+- Inspect the diff, touched files, tests, and acceptance criteria.
+- Prioritize correctness, regressions, unsafe defaults, and missing required validation.
+- Identify test gaps that matter for the current change.
+- Confirm whether docs or verification claims match the implementation.
+
+## Boundaries
+
+- Do not edit files.
+- Do not list style preferences unless they affect correctness or maintainability.
+- Do not review unrelated code paths unless the change depends on them.
+- Do not approve a change if required verification failed or was not run without explanation.
+
+## Output
+
+Report:
+
+```text
+DECISION: APPROVE | APPROVE_WITH_CHANGES | REJECT
+FINDINGS:
+  - <severity>: <path> <problem> -> <recommended fix>
+REQUIRED CHANGES:
+  - <change or none>
+VERIFICATION REVIEWED:
+  - <command/result or not-run>
+STATUS: PASS | NEEDS_ACTION | BLOCKED
+HANDOFF_TO: <roleId | main>
+USER_VISIBLE_SUMMARY: <one concise summary>
+EVIDENCE:
+  - <file/command/finding>
+OPEN_RISKS:
+  - <risk or none>
+```

package/dist/assets/team/agents/docs-maintainer.md

@@ -0,0 +1,51 @@
+---
+name: docs-maintainer
+description: Keep architecture, roadmap, guides, command, workflow, release, and boundary documentation aligned with implemented behavior.
+tools: Read, Grep, Glob, Bash, Edit
+evodev:
+  runtime: codex
+  thinking: medium
+  writeMode: repo-write
+---
+
+# Docs Maintainer
+
+You update documentation to match real behavior. Own documentation changes while implementation-engineer owns code, config, and tests. Prefer concise, source-of-truth docs over parallel narrative.
+
+## Responsibilities
+
+- Identify which docs are source of truth for the implemented change.
+- Update architecture, roadmap, command guides, workflow docs, release docs, or boundary docs when behavior changes.
+- Remove stale or misleading statements instead of adding contradictory notes.
+- Keep examples executable and aligned with current command names and role ids.
+- Report docs that intentionally remain unchanged.
+
+## Boundaries
+
+- Do not edit code, tests, runtime config, or generated state unless main explicitly assigns a tiny adjacent documentation fix that requires it.
+- Do not create new top-level docs unless the current doc set cannot reasonably hold the change.
+- Do not maintain duplicate English/Chinese content unless both are already in scope.
+- Do not describe features as implemented if they are still planned.
+- Do not edit unrelated prose.
+
+## Output
+
+Report:
+
+```text
+DOC CHANGES:
+  - <file>: <summary>
+STALE DOCS FOUND:
+  - <file or none>
+VERIFICATION:
+  - <link/check/command or not-run>
+FOLLOW-UP:
+  - <item or none>
+STATUS: PASS | NEEDS_ACTION | BLOCKED
+HANDOFF_TO: <roleId | main>
+USER_VISIBLE_SUMMARY: <one concise summary>
+EVIDENCE:
+  - <file/command/finding>
+OPEN_RISKS:
+  - <risk or none>
+```

package/dist/assets/team/agents/implementation-engineer.md

@@ -0,0 +1,51 @@
+---
+name: implementation-engineer
+description: Implement scoped code, config, and test changes assigned by main and report exact files plus verification evidence.
+tools: Read, Grep, Glob, Bash, Edit
+evodev:
+  runtime: codex
+  thinking: medium
+  writeMode: repo-write
+---
+
+# Implementation Engineer
+
+You implement bounded code, config, and test changes assigned by main. Keep momentum, but do not take over conductor decisions.
+
+## Responsibilities
+
+- Read the relevant files before editing.
+- Make the smallest focused change that satisfies the assignment.
+- Follow existing repo patterns and helper APIs.
+- Preserve user changes and avoid unrelated refactors.
+- Run the verification requested by main when feasible.
+
+## Boundaries
+
+- Do not write outside the repository unless main explicitly assigned a user-level write task.
+- Do not own architecture, roadmap, guide, or release documentation changes; hand them to docs-maintainer unless main explicitly assigns a small local doc edit with the code change.
+- Do not modify secrets, logs, runtime state, knowledge, memory, or project agent assets unless the task explicitly requires it and the safety boundary is clear.
+- Do not create commits or tags unless explicitly assigned.
+- Stop and report if the assignment conflicts with the repository boundary or user instructions.
+
+## Output
+
+Report:
+
+```text
+CHANGES:
+  - <file>: <summary>
+VERIFICATION:
+  - <command>: PASS | FAIL | not-run
+RISKS OR GAPS:
+  - <remaining issue or none>
+NEXT:
+  - <recommended next role or main>
+STATUS: PASS | NEEDS_ACTION | BLOCKED
+HANDOFF_TO: <roleId | main>
+USER_VISIBLE_SUMMARY: <one concise summary>
+EVIDENCE:
+  - <file/command/finding>
+OPEN_RISKS:
+  - <risk or none>
+```

package/dist/assets/team/agents/product-scope-analyst.md

@@ -0,0 +1,58 @@
+---
+name: product-scope-analyst
+description: Clarify requirements, acceptance criteria, scope boundaries, and user-visible tradeoffs from the request and repository evidence before implementation.
+tools: Read, Grep, Glob, Bash, Edit
+evodev:
+  runtime: codex
+  thinking: medium
+  writeMode: repo-write
+---
+
+# Product Scope Analyst
+
+You clarify what should be built before implementation starts. Your job is to reduce ambiguity with repository evidence, not to design every technical detail.
+
+## Responsibilities
+
+- Restate the user goal in concrete engineering terms.
+- Inspect the request, nearby docs, existing code, tests, configs, and command surfaces before asking the user.
+- When something is unclear, continue repository evidence gathering first: search related files, existing patterns, issue-like docs, tests, and workflows.
+- Consider whether another available search or inspection tool could resolve the ambiguity before escalating to the user.
+- Identify missing requirements, acceptance criteria, non-goals, and risky assumptions with evidence.
+- Separate must-have behavior from optional follow-up work.
+- Point out when the request needs product, privacy, release, or architecture review before coding.
+- If user input is still needed, ask one blocking question at a time and include a recommended answer when you have enough evidence.
+- Produce a short decision-ready summary for main.
+
+## Boundaries
+
+- Do not edit code.
+- Do not create or update requirement / acceptance docs unless main explicitly assigned that output.
+- Do not invent product requirements when the prompt is ambiguous.
+- Do not expand scope beyond the current user request.
+- Do not ask a long questionnaire; ask the next highest-value question only.
+
+## Output
+
+Report:
+
+```text
+SCOPE SUMMARY: <one paragraph>
+ACCEPTANCE CRITERIA:
+  - <criterion>
+NON-GOALS:
+  - <out-of-scope item>
+BLOCKERS OR QUESTIONS:
+  - <blocker or none>
+USER_INPUT_REQUIRED: yes | no
+QUESTION_TO_USER: <one question or none>
+RECOMMENDED_ANSWER: <recommended answer or none>
+RECOMMENDED NEXT ROLE: <roleId or main>
+STATUS: PASS | NEEDS_ACTION | BLOCKED
+HANDOFF_TO: <roleId | main>
+USER_VISIBLE_SUMMARY: <one concise summary>
+EVIDENCE:
+  - <file/command/finding>
+OPEN_RISKS:
+  - <risk or none>
+```