Delegation means a harness-provided sub-agent/worker tool only. Never start a nested agent by running codex, codex exec, claude, or any other agent CLI from the shell. If the current agent cannot access the required harness sub-agent tool or an agent slot is unavailable, stop or wait and report the blocking condition; do not work around the limit with a command-line agent process.
If the system has no reachable source code, stop and write a lightweight note instead.
-
Normalize the repository target. Derive:
repo_url - canonical full GitHub repository URL for citations, https://github.com/{owner}/{repo} with no trailing slash or .gitowner - GitHub owner or organizationrepo_name - final path segmentrepo_slug - default review slug, usually repo_namecheckout_slug - owner-qualified checkout slug: {owner}--{repo_name}checkout_dir - related-systems/{checkout_slug}/source_dir - same path as checkout_dir; this is the directory passed to the review type contractnote_path - kb/agent-memory-systems/reviews/{repo_slug}.md
-
Resolve same-name collisions. Use the repository name as the default review filename unless there is already an established house-style variant. If kb/agent-memory-systems/reviews/{repo_name}.md already exists for a different GitHub repository with the same final path segment, use kb/agent-memory-systems/reviews/{owner}--{repo_name}.md. Do not overwrite or update a same-name review unless its **Repository:** line or frontmatter resolves to the same owner/repo.
-
Choose the checkout path. Use the owner-qualified checkout directory for new clones. Existing reviews may have legacy basename-only checkouts such as related-systems/{repo_name}/; use a legacy checkout only when its origin remote resolves to the same GitHub owner/repo you are reviewing. If a legacy checkout points to a different owner with the same repository name, do not pull it, delete it, or repurpose it; clone the requested repo into the owner-qualified checkout_dir.
-
Check main repo state. Run git status --short in the main repo before cloning or writing so you know whether unrelated changes already exist.
-
Clone or refresh. Run checkout-local git commands from checkout_dir using the Bash working directory, a subshell, or cd first. Do not spell checkout-local commands as git -C "{checkout_dir}" ...; permission rules match command prefixes such as git fetch, and git -C ... fetch can unnecessarily trigger approval prompts. After checkout git operations, return to the Commonplace root before metadata capture, archive moves, index refresh, QA, or validation.
If checkout_dir does not exist:
git clone "{repo_url}" "{checkout_dir}"
If checkout_dir exists:
(
cd "{checkout_dir}"
git fetch --all --prune
git status --short
git merge --ff-only @{upstream}
)
If using cd in the current shell instead of a subshell, save the Commonplace root first and cd back to it immediately after the checkout git commands.
Use git fetch rather than git pull so the refresh uses the agent-approved fetch permission path. If the merge cannot fast-forward because of local commits or conflicts, stop and report the state. Do not force, delete, or overwrite an existing checkout.
-
Capture source metadata. Record the top-level listing, most recent commit, README, and package/manifest files for the writer's context. The parent establishes GitHub-specific metadata before delegation:
source_dir: checkout_dirsource_url: repo_urlreviewed_commit: output of git rev-parse HEAD run from checkout_dircommit_url: {repo_url}/commit/{reviewed_commit}- citation format:
- files:
{repo_url}/blob/{reviewed_commit}/{path}
- directories:
{repo_url}/tree/{reviewed_commit}/{path}
Write the refresh marker immediately after a successful clone or fetch-and-fast-forward:
(
cd "{checkout_dir}"
git_dir="$(git rev-parse --absolute-git-dir)"
date -Iseconds > "$git_dir/commonplace-checkout-refreshed-at"
)
If the marker is more than 1 hour old by the time drafting starts, carry a checkout freshness warning into the final report. If it is more than 24 hours old, refresh again before drafting.
-
Archive an existing review before writing. If note_path exists, archive it before drafting or delegating:
git mv "{note_path}" "{note_path%.md}.replaced.{YYYY-MM-DD}.md"
If that target path already exists (a same-day rerun already archived one), do not overwrite it: append a numeric suffix starting at 2 and increment until the path is free — {note_path%.md}.replaced.{YYYY-MM-DD}.2.md, then .3.md, and so on.
Then mark the archived file:
- Set
tags: [] (clearing any trace-learning tag).
- Add after the title:
> Replaced {YYYY-MM-DD}. See [{name}](./{name}.md) for the current review.
- Remove
user-verified if present; archiving is a substantive lifecycle edit and the replacement banner carries the supersession fact.
Do not read the archived .replaced.*.md file while writing the replacement.
-
Draft the review by delegation. Use kb/agent-memory-systems/types/agent-memory-system-review.md as the worker's artifact contract for required sections and fields. Do not ask the worker to load the full designing-agent-memory-systems note during ordinary review writing — its comparison lens is already condensed into the contract.
Before delegating: if the harness cannot launch a sub-agent or worker, stop after setup and report that delegated drafting is unavailable. Do not draft locally unless the user explicitly authorizes a local fallback for this run; if authorized, report drafting was local, not delegated as a workflow exception. This is a parent-only decision, made before any worker exists — a worker that has actually been launched is, by construction, the delegated drafting worker and never needs to reason about fallback authorization itself.
Launch one fresh sub-agent or worker with a minimal task-local context. Do not fork the parent's full context when the harness offers a clean-context option. Use only the harness sub-agent mechanism for this delegation; do not launch an agent CLI from Bash. Give the worker exactly this task, with the bracketed values filled in — this task text is the worker's complete brief; do not also hand it this skill file.
The worker warning below is a load-bearing mitigation, not optional explanation; rationale: skill discovery re-fires in every sub-agent context.
Draft review content for {note_path}.
You are a delegated drafting worker; this task text is your complete and only brief. Your environment may surface `write-agent-memory-system-review` or another skill as available or auto-loaded because this task resembles its trigger — if so, do not invoke or follow it. Its steps (checkout, archiving, indexes, QA, final validation) are written for the parent that dispatched you, not for you. Ignore it entirely and follow only the instructions below.
Read, in this order:
- kb/agent-memory-systems/COLLECTION.md
- kb/agent-memory-systems/types/agent-memory-system-review.md — the artifact contract; authoritative for required sections and fields. Use its current retained-artifact vocabulary, including `knowledge-artifact` and `system-definition-artifact` as behavioral-authority families.
- 1-2 current reviews in kb/agent-memory-systems/reviews/ and kb/agent-memory-systems/README.md, for style
Your inputs:
- source_dir: {source_dir} (already prepared; do not mutate it)
- note_path: {note_path}
- reviewed_revision / source identity: {reviewed_revision}
- source_url: {source_url}
- reviewed_commit: {reviewed_commit}
- commit_url: {commit_url}
- citation format — files: {repo_url}/blob/{reviewed_commit}/{path}; directories: {repo_url}/tree/{reviewed_commit}/{path} (unless the caller supplies a different format)
If any input above is missing, stop and report which. Verify source_dir is readable (e.g. test -d); if it isn't, stop and report. Never update last-checked without actually reading source_dir.
Ground the review in primary sources in source_dir — README, architecture/design docs, CLAUDE.md/AGENTS.md, package manifests, and the core source files implementing the central claims. Where the implementation clarifies or contradicts the README, report what the code does and note the divergence. Decide trace-learning status from implementation evidence and either include both the placement section and the trace-learning tag, or omit both.
Do not add `user-verified`; drafting and semantic review cannot grant human attestation.
Write note_path from the code outward.
Then run: commonplace-validate {note_path}
Fix any structural or description-quality issues it reports and re-run until clean — you own this file, so fix it directly rather than reporting it back.
Do not edit indexes, archived reviews, the trace-learning survey, checkout state, or any file other than note_path. Do not run any commonplace-* command other than commonplace-validate on note_path. Do not spawn further agents unless a proper sub-agent/worker tool is available to you; if you need one and none is available, pause and report the blocker — never run codex, codex exec, claude, or another agent CLI as a substitute.
Report: your commonplace-validate result and whether trace-learning applies.
The parent owns checkout, archive moves, curated index edits, taxonomy QA, semantic QA, and the final report — none of that is the worker's concern. After verifying the worker-owned draft and validation result, close, terminate, or release the drafting worker; do not retain it for semantic QA or any follow-up task.
-
Update the README only if needed. Only edit kb/agent-memory-systems/README.md when:
- the system was named in the
## Coverage "Review backlog" callout — remove it there, or
- the repo adds a genuinely new cross-system pattern worth a line in
## Patterns Across Systems.
Keep the edit minimal and specific.
-
Update the trace-learning survey if needed. If the review's trace-learning placement adds meaningfully to the survey, update kb/agent-memory-systems/trace-learning-techniques-in-related-systems.md.
-
Run taxonomy QA. Re-read the drafted review and check whether it makes the artifact contract clear where relevant. Work from the type contract's artifact-analysis field list (plus its trace-learning split, when the system learns from traces) — the contract is authoritative for which fields exist and what each means; do not QA against a remembered list. For each contract field, ask: does the review make that mechanism clear where it affects the comparison? Do not force a rigid section into every review; add or revise prose only when the existing text leaves a mechanism ambiguous.
If a field is absent because the reviewed system has no distinctive mechanism there, leave it absent. If the absence hides an important tradeoff, fix the review before semantic QA.
If semantic QA cannot be completed through the current harness, report it as a blocked QA step rather than substituting a shell-launched agent.
