Merge pull request #203 from EvolvingAgentsLabs/ccr-c0eed325-5wd271

repo: CLAUDE.md, the director plugin enabled here, and a memory compiled for this repository

Author: matiasmolinas

.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
       "name": "director",
       "source": "./packages/director",
       "description": "Your CLAUDE.md, actually followed: compile your instructions into linked atomic statements, plan every task by walking them, and learn from corrections through gated, versioned edits.",
-      "version": "0.2.4",
+      "version": "0.2.5",
       "category": "productivity"
     }
   ]

.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "extraKnownMarketplaces": {
+    "evolvingagentslabs": {
+      "source": { "source": "github", "repo": "EvolvingAgentsLabs/evolving-agents" }
+    }
+  },
+  "enabledPlugins": {
+    "director@evolvingagentslabs": true
+  }
+}

.director/.gitignore

@@ -0,0 +1,5 @@
+# Only the memory is shared through the repository; the journal, proposals and checks stay local.
+*
+!.gitignore
+!memory/
+!memory/**

.director/memory/Director_Code.md

@@ -0,0 +1,68 @@
+# Director_Code
+Rules for changing the director's code, plugin and the independent benchmark.
+
+## #memory_stdlib_only
+**When:** editing or adding an import in `director/memory/`.
+**Do:** Use only the Python standard library.
+**Because:** `director/memory/` is standard library only.
+**Links:** [[Director_Code#memory_no_model_calls]] · [[Director_Code#memory_no_package_imports]]
+
+## #memory_no_model_calls
+**When:** writing code in `director/memory/`.
+**Do:** Never call a model from it.
+**Because:** The memory module never calls a model.
+**Links:** [[Director_Code#memory_stdlib_only]] · [[Director_Code#memory_no_package_imports]]
+
+## #memory_no_package_imports
+**When:** about to import something from the rest of the director package inside `director/memory/`.
+**Do:** Don't; `director/memory/` imports nothing from the rest of the package. Keep `tests/test_memory_boundary.py` passing.
+**Because:** `tests/test_memory_boundary.py` holds this boundary.
+**Links:** [[Director_Code#memory_stdlib_only]] · [[Director_Code#run_tests_before_push]]
+
+## #lessons_through_gate
+**When:** writing or changing an interface that accepts a lesson into memory.
+**Do:** Route the lesson through `memory.gate`.
+**Because:** Every interface accepts a lesson through `memory.gate`.
+**Links:** [[Director_Code#person_yes_required]] · [[Director_Code#headless_records_policy]]
+
+## #person_yes_required
+**When:** a lesson is about to be accepted into memory from an interactive interface.
+**Do:** Require the person's yes (`memory_accept`) before accepting it.
+**Because:** A person's yes is required to accept a lesson.
+**Links:** [[Director_Code#lessons_through_gate]] · [[Director_Code#headless_records_policy]]
+
+## #headless_records_policy
+**When:** a lesson is accepted through `director.headless`, where no person answers.
+**Do:** Record `decided_by: policy:<name>` on it instead of a person's yes.
+**Because:** `director.headless` is the one exception to the person's-yes rule.
+**Links:** [[Director_Code#person_yes_required]]
+
+## #run_tests_before_push
+**When:** about to push a change to the director.
+**Do:** Run `cd packages/director && python -m pytest tests -q`; expect the 3 agentvcs tests to skip if the Rust CLI is absent.
+**Because:** Required before pushing a director change; the 3 agentvcs tests skip without the Rust CLI.
+**Links:** [[Director_Code#validate_plugin_before_push]] · [[Privacy#never_commit_key_or_private_term]]
+
+## #validate_plugin_before_push
+**When:** about to push a change that touches the plugin.
+**Do:** Also run `claude plugin validate .` and `claude plugin test .`.
+**Because:** Required before pushing a plugin change.
+**Links:** [[Director_Code#run_tests_before_push]] · [[Director_Code#bump_both_versions]]
+
+## #bump_both_versions
+**When:** making any change to the plugin.
+**Do:** Bump `version` in `packages/director/.claude-plugin/plugin.json` and in the root `.claude-plugin/marketplace.json`, together in the same change.
+**Because:** The two versions must move together.
+**Links:** [[Director_Code#validate_plugin_before_push]]
+
+## #bench_no_director_imports
+**When:** editing code in `benchmarks/director-bench/`.
+**Do:** Never import director code; drive the director only as one configuration that calls its CLI.
+**Because:** The benchmark is independent of the director.
+**Links:** [[Director_Code#bench_tests_in_place]]
+
+## #bench_tests_in_place
+**When:** testing a change to `benchmarks/director-bench/`.
+**Do:** Run its tests in place: `cd benchmarks/director-bench && python -m pytest -q`; don't expect the repository's CI to run them.
+**Because:** Its tests are not part of this repository's CI.
+**Links:** [[Director_Code#bench_no_director_imports]]

.director/memory/Index.md

@@ -0,0 +1,20 @@
+# Index
+- Starting a task and deciding where the work goes → [[Scope#active_project_director]]
+- About to edit something in legacy/, ai-os/, plugin/, packages/memory/ or packages/agentvcs/ → [[Scope#leave_legacy_alone]]
+- About to launch a run, eval or anything that spends money or calls a model → [[Measurements#brief_before_run]], [[Measurements#brief_contents]], [[Measurements#verdict_fixed_before_run]]
+- About to measure whether a change is an improvement → [[Measurements#headroom_first]], [[Measurements#compare_against_replaced]]
+- Baseline came back near the ceiling → [[Measurements#stop_at_ceiling]]
+- Run finished; writing up the result → [[Measurements#record_result_in_brief]], [[Measurements#name_planner_and_judge]], [[Writing#update_citing_docs]]
+- Result is below the bar, or tempted to change the bar → [[Measurements#flat_result_published_flat]], [[Measurements#verdict_fixed_before_run]]
+- Reporting numbers measured with Sonnet → [[Measurements#label_sonnet_numbers]]
+- Run used one seed or a handful of cases → [[Measurements#smoke_run_not_measurement]]
+- Saving memory, plans, transcripts or lanes config → [[Privacy#private_stays_private]]
+- Writing a public file or publishing run results → [[Privacy#placeholders_for_private_names]], [[Privacy#publish_scores_only]]
+- About to commit → [[Privacy#never_commit_key_or_private_term]]
+- Public guard refused a commit → [[Privacy#respect_public_guard]]
+- Editing code in director/memory/ → [[Director_Code#memory_stdlib_only]], [[Director_Code#memory_no_model_calls]], [[Director_Code#memory_no_package_imports]]
+- Writing an interface that accepts lessons into memory → [[Director_Code#lessons_through_gate]], [[Director_Code#person_yes_required]], [[Director_Code#headless_records_policy]]
+- About to push a director change → [[Director_Code#run_tests_before_push]]
+- Changing or pushing the plugin → [[Director_Code#bump_both_versions]], [[Director_Code#validate_plugin_before_push]]
+- Working in benchmarks/director-bench/ → [[Director_Code#bench_no_director_imports]], [[Director_Code#bench_tests_in_place]]
+- Writing a doc or code comment → [[Writing#plain_outcome_first]], [[Writing#numbers_carry_brief_link]]

.director/memory/Measurements.md

@@ -0,0 +1,68 @@
+# Measurements
+How runs that spend money or call models are planned, compared, judged and recorded.
+
+## #brief_before_run
+**When:** about to launch anything that spends money or calls a model on the lab's behalf (a run, eval, benchmark).
+**Do:** First write `packages/director/docs/BRIEF-<ID>.md`; do not start the run until it exists.
+**Because:** The lab requires a brief before any run.
+**Links:** [[Measurements#brief_contents]] · [[Measurements#verdict_fixed_before_run]] · [[Measurements#headroom_first]]
+
+## #brief_contents
+**When:** writing a `BRIEF-<ID>.md` before a run.
+**Do:** Include: what is run, why, the model and provider, the verdict table, what would falsify it, the stopping condition and a spending cap.
+**Because:** These are the required parts of a brief.
+**Links:** [[Measurements#brief_before_run]] · [[Measurements#verdict_fixed_before_run]] · [[Measurements#name_planner_and_judge]]
+
+## #record_result_in_brief
+**When:** a run has finished (or been stopped) and its result is known.
+**Do:** Write the result into the same brief under `## Result` / `## Outcome`, dated, stating what was spent.
+**Because:** The brief is the single record of a run, and the public site checks its numbers against the briefs.
+**Links:** [[Writing#update_citing_docs]] · [[Measurements#flat_result_published_flat]] · [[Measurements#smoke_run_not_measurement]]
+
+## #verdict_fixed_before_run
+**When:** setting the bar that decides whether a run succeeded, or tempted to adjust it after seeing numbers.
+**Do:** Fix the verdict table in the brief before the run, and never move it after seeing the numbers.
+**Because:** The lab rule: the verdict table is fixed before the run.
+**Links:** [[Measurements#brief_contents]] · [[Measurements#flat_result_published_flat]]
+
+## #flat_result_published_flat
+**When:** a result came in below the bar of the verdict table and you are writing it up.
+**Do:** Publish it as flat; never reword it into a win.
+**Because:** The lab rule: a result below the bar is published as flat.
+**Links:** [[Measurements#verdict_fixed_before_run]] · [[Measurements#record_result_in_brief]]
+
+## #headroom_first
+**When:** about to measure whether a change improves something.
+**Do:** Measure the baseline first, before measuring the improvement.
+**Because:** If the baseline is already near the ceiling there is no room to show an improvement.
+**Links:** [[Measurements#stop_at_ceiling]] · [[Measurements#brief_before_run]]
+
+## #stop_at_ceiling
+**When:** the baseline you just measured is already near the ceiling.
+**Do:** Stop the measurement and say so in the write-up.
+**Because:** C0, D0O and PG were stopped there for this reason.
+**Links:** [[Measurements#headroom_first]] · [[Measurements#record_result_in_brief]]
+
+## #compare_against_replaced
+**When:** choosing what to compare a new version against in a measurement.
+**Do:** Compare against the version it replaces; never against a frontier model alone.
+**Because:** The lab rule for measurements.
+**Links:** [[Measurements#name_planner_and_judge]] · [[Measurements#brief_contents]]
+
+## #name_planner_and_judge
+**When:** writing up a measurement or its brief.
+**Do:** State which model planned and which model judged.
+**Because:** Results depend on the models used; since 2026-10-21 the person plans with Opus.
+**Links:** [[Measurements#label_sonnet_numbers]] · [[Measurements#compare_against_replaced]]
+
+## #label_sonnet_numbers
+**When:** reporting or citing numbers that were measured with Sonnet.
+**Do:** Label them as Sonnet's numbers.
+**Because:** Since 2026-10-21 the person plans with Opus, so Sonnet numbers must not be read as the current setup's.
+**Links:** [[Measurements#name_planner_and_judge]]
+
+## #smoke_run_not_measurement
+**When:** a run used one seed or only a handful of cases (a smoke run) and you are writing it up.
+**Do:** Treat it as deciding nothing, and say in the write-up that it is a smoke run, not a measurement.
+**Because:** One seed or a handful of cases decides nothing.
+**Links:** [[Measurements#record_result_in_brief]]

.director/memory/Privacy.md

@@ -0,0 +1,32 @@
+# Privacy
+What stays private, what may be published, and how commits are guarded.
+
+## #private_stays_private
+**When:** about to save or move the lab's memory, plans, transcripts or lanes config.
+**Do:** Keep them in the private locations, `~/.config/director/` or a project's `.director/`, never in public files.
+**Because:** The lab's memory, plans, transcripts and lanes config are private.
+**Links:** [[Privacy#placeholders_for_private_names]] · [[Privacy#never_commit_key_or_private_term]]
+
+## #placeholders_for_private_names
+**When:** writing a public file that would mention a private name.
+**Do:** Use a placeholder instead of the private name.
+**Because:** Public files use placeholders for private names.
+**Links:** [[Privacy#publish_scores_only]] · [[Privacy#never_commit_key_or_private_term]]
+
+## #publish_scores_only
+**When:** publishing what a run produced.
+**Do:** Publish its scores; keep transcripts, plans and memory private.
+**Because:** What a run publishes is its scores.
+**Links:** [[Privacy#private_stays_private]] · [[Measurements#record_result_in_brief]]
+
+## #never_commit_key_or_private_term
+**When:** about to commit any change.
+**Do:** Check that it contains no key and no private term; never commit one.
+**Because:** Keys and private terms must not become public.
+**Links:** [[Privacy#respect_public_guard]] · [[Director_Code#run_tests_before_push]]
+
+## #respect_public_guard
+**When:** the plugin's public guard refuses a commit.
+**Do:** Remove the key or private term it flagged; do not work around the guard.
+**Because:** The guard exists to refuse such commits.
+**Links:** [[Privacy#never_commit_key_or_private_term]]

.director/memory/README.md

@@ -0,0 +1,48 @@
+# The operational memory's format
+
+The memory is a small wiki of **operational** knowledge — how the lab works — in the shape of the lab's
+memory design: a **page** is a collection of **atomic statements**, the smallest verifiable unit; links live
+inside statements, and a task is planned by walking from an entry statement along its links. Encyclopedic
+facts (what a project is, what a number was) appear only as support for an operational statement.
+
+## Files
+
+```
+memory/
+  Index.md            situations → entry statements (where a walk starts)
+  <Page_Name>.md      one page per subject: a practice, a tool, a project, a kind of task
+```
+
+## A page
+
+```markdown
+# Experiment_Briefs
+How an experiment is set up before anything runs.
+
+## #brief_before_run
+**When:** a run on Colab, a GPU, a paid API or the user's machine is about to start.
+**Do:** write `results/<run>/BRIEF.md` first — what, why, model, provider, what falsifies it, the verdict table, the stopping condition.
+**Because:** the briefing goes before the `nohup`, not beside the report (user's rule).
+**Links:** [[Measurement#headroom_first]] · [[Colab#one_session_one_training]]
+```
+
+- A statement id is `Page_Name#snake_case`, unique, stable once written.
+- **When** is the trigger, phrased as a situation an agent will recognise mid-task, not as a topic.
+- **Do** is an action, concrete enough to check: a command, a file, a question to the user, a refusal.
+- **Because** is the reason or the evidence (a run, an incident, the user's decision), so a statement can
+  be verified or retired.
+- **Links** name the statements that apply next or alongside; a walk follows them while they apply.
+
+## Index.md
+
+One line per situation, pointing at the statements a walk should start from:
+
+```markdown
+- About to launch a run (Colab, GPU, paid API, local model) → [[Experiment_Briefs#brief_before_run]], [[Local_Hardware#ask_before_heavy_runs]]
+```
+
+## What a walk is
+
+Index → the matching entry statements → their links, while each applies → a plan whose actions cite the
+statements they follow (`[[Page#id]]`). A plan that cites nothing either found no applicable statement and
+says so, or did not walk.

.director/memory/Scope.md

@@ -0,0 +1,14 @@
+# Scope
+Which parts of the repository are active and which must be left alone.
+
+## #active_project_director
+**When:** starting a task in the evolving-agents repository and deciding where the work belongs.
+**Do:** Do the work in the director, `packages/director/`; it is the active project.
+**Because:** The lab states the director is the active project; everything else is legacy, paused or frozen.
+**Links:** [[Scope#leave_legacy_alone]] · [[Director_Code#run_tests_before_push]]
+
+## #leave_legacy_alone
+**When:** about to edit a file under `legacy/`, `ai-os/`, `plugin/`, `packages/memory/` or `packages/agentvcs/`.
+**Do:** Do not change it unless the person explicitly asked for that change.
+**Because:** These directories are legacy, paused or frozen.
+**Links:** [[Scope#active_project_director]]

.director/memory/Writing.md

@@ -0,0 +1,20 @@
+# Writing
+How docs and comments are written and kept in sync with runs.
+
+## #plain_outcome_first
+**When:** writing a doc or a code comment.
+**Do:** Use plain words, put the outcome first, keep it short.
+**Because:** The lab's writing rule.
+**Links:** [[Writing#numbers_carry_brief_link]]
+
+## #numbers_carry_brief_link
+**When:** putting a number (a score or result) in a doc.
+**Do:** Attach the link to the brief it came from.
+**Because:** Numbers carry their brief link; the public site checks its numbers against the briefs.
+**Links:** [[Measurements#record_result_in_brief]] · [[Writing#update_citing_docs]]
+
+## #update_citing_docs
+**When:** something has run and its result is recorded.
+**Do:** In the same change, update every doc that cites it: the brief, `packages/director/README.md`, `ROADMAP.md`, `docs/EVOLUTION.md` and the RUNBOOK.
+**Because:** The public site (`evolvingagentslabs.github.io`) checks its numbers nightly against the briefs.
+**Links:** [[Measurements#record_result_in_brief]] · [[Writing#numbers_carry_brief_link]]