Analyse an Agentic System

Type: types/instruction.md

Analyse one external agentic system at one frozen evidence boundary and publish its accepted artifact with the overview as the public entry point. Code runs the analysis as a workflow: it names each job, judges each result, and publishes. You open the run, launch the workers it names, and report.

Invocation authorizes the artifact-run directory under kb/agentic-system-analyses/state/, the retained analysis under kb/agentic-system-analyses/retained/<system-slug>/; code writes all of them. Code acquires and freezes a GitHub source's checkout under related-systems/; the boundary job may freeze other sources under its source rules; later jobs read them read-only. Invocation does not authorize editing source content, auxiliary indexes or surveys, transfer scans, landscape synthesis, other retained reports, or Git staging and commits.

Isolated run setup

Run each analysis in a dedicated Commonplace worktree at a committed method revision. Prepare it first, from the checkout this session started in:

commonplace-analysis prepare --name <system-label>

Code creates a detached worktree under .commonplace/worktrees/, installs its local commands from the committed lockfile, verifies their binding, and prints a JSON record. Keep its worktree and path-prefix values. --worktree <new-path> overrides the location. Existing destinations are refused. Failed installations retain the worktree and a sibling .preparation.json record for diagnosis. Preparation writes Git metadata and may download packages: when the sandbox blocks it, request escalation for this command alone. If preparation fails, stop and give the operator its message; do not open a run in the originating checkout.

Preparation uses HEAD. It stops when HEAD is behind the default branch: this session then loaded an older method. Stop and tell the operator; only the operator selects another method with --revision <commit>.

By default, uncommitted changes stop preparation. --allow-dirty-origin permits unrelated changes in the originating checkout and excludes them from the new worktree; use it only when the operator asks. It never permits changed startup instructions or configuration: instruction files such as AGENTS.md, project harness settings and system prompts, skill and agent directories, extensions, hooks and prompt resources, and repository-local targets of skill symlinks must match the selected commit. Staged, unstaged, untracked and ignored startup files are checked, except an ignored settings.local.json, which holds one user's harness permissions. Runtime locks, caches and top-level harness README files are not startup inputs. The Git comparison covers repository files, not user-wide harness settings.

A successful preparation establishes that the instructions this session loaded are the worktree's. Continue in this session:

  • Run every later command of this skill with worktree as its working directory, calling it as <path-prefix>/commonplace-….
  • Every path this skill names is relative to worktree.
  • Launch workers as the driver says. Code gives each worker the command directory in its invocation.

Code refuses a run's command when it is called from another checkout or runs another checkout's code, and the refusal names the directory to use. Follow it; do not reinstall the shared user-level tool to point at the run.

Keep the worktree's code, method files, lockfile and environment unchanged until the run finishes; develop and merge method changes elsewhere. On resume, use the same worktree and command directory before following the worker-recovery rules. A completed published run stays in this worktree until the operator separately authorizes integration. Keep using the prepared worktree's command directory and working directory for commonplace-analysis integrate <run> after the report; its recorded origin checkout must be clean and on main. An agent also supplies --model <model-id>. The command commits the publication on analysis/<run-id> from the method commit and merges that branch into main. If Git reports a conflict, the command aborts the merge, keeps the branch and worktree, and stops for the operator. Do not copy the retained analysis into main.

Worktree removal is a separate operator decision. It is permitted only when every run in it has completed with verified publication merged into main, no integration branch awaits a merge or conflict decision, and every audit has extracted its evidence record or the operator has said none needs it. Then use git worktree remove, remove the sibling preparation record, and delete merged analysis branches. Never remove a worktree containing a failed run through this routine: failures, rejected outputs and traces are evidence. Completed local blocked/out-of-scope results also need a separate disposition decision, not this published-run cleanup route. Disposing of such evidence needs a separate explicit operator decision after reviewing the failure and any uncertain public state. Removal is never automatic.

A command after -- instead starts a separate harness in the prepared worktree with its commands on PATH; the operator may use it to run this skill there. This session then stops after preparation.

1. Open the run

Allocate the run:

commonplace-analysis start \
  --system "<source-native system name>" \
  --source-identity "<stable source identity, e.g. https://github.com/owner/repo>" \
  --source "<the caller's source input, as given>" \
  --harness <this harness> [--worker-profile <operator-named worker profile>]

Code normalizes the source identity and allocates AAS-<date>-<source-slug>-<worktree-token>-<nn> under kb/agentic-system-analyses/state/. The token comes from the ready preparation record, including with --worktree. The source slug determines the stable publication directory; there is no public-path override. The command pins the plan and prints the run path. It does not advance, acquire sources or launch workers. The first advance opens the analysis and pins the prepared method commit; publication requires it unchanged.

For a GitHub source, add --source-revision <full 40-hex commit> when the caller requests a revision or asks to keep the existing checkout's commit. For the latter, read git -C <checkout> rev-parse HEAD and pass that full commit. The option requires a GitHub identity. During advance, code freezes related-systems/<owner>--<repo>/ before the boundary job. Without a revision it clones a missing checkout or fetches a clean existing one and detaches it at the default branch tip. With a revision it uses that commit. A dirty checkout, foreign origin or unavailable commit stops the run for the operator.

Every worker of a run uses one worker profile from worker-profiles.yaml: a harness, launch-model and effort. Pass commonplace-analysis start this session's harness with --harness <name> (claude-code, codex or pi), and the worker profile the operator names with --worker-profile <name>. Without one, code uses the harness's default; it refuses a worker profile of another harness. Opening records it and publication writes it to the retained manifest. If this harness can launch workers neither with the profile's model and effort nor with verified inherited settings, as the driver defines them, stop before starting the run and tell the operator.

Do not read kb/agentic-systems/reviews/ or kb/agentic-system-analyses/retained/ at any point; the jobs analyse from sources only.

2. Drive the run

Follow drive a code-scheduled run with <run> = the path commonplace-analysis start printed. The run is new: you started it in this session.

3. Report

Run commonplace-analysis inspect <run> and include its JSON output unchanged in the final response, together with any stops from the last advance. The report does not reconstruct invocation-specific scheduling stops or audit retained files. publishable is engine coverage, not proof of publication. state: completed means the bound publication job completed on current inputs. For blocked or out-of-scope dispositions, completion: local means no retained publication. completion: publication-job-completed is still not a fresh filesystem audit; separately authorized integration independently verifies exact evidence before committing.

If the loop stops or reports an uncertain effect, preserve its evidence and give the operator the exact command output and error. Do not edit engine state or claim completion. After a published analysis, add that outputs under kb/agentic-systems/comparisons/ are stale unless rebuilt under separate authority, and a prior landscape synthesis is historical unless refreshed under separate authority. Transfer scans and landscape synthesis need separate commissions; this run does not launch them.

Coordinator publication and method edits

Before publication, the coordinator reads publication. Only coordinators load that instruction; worker packets do not supply it. Before editing this method, read method maintenance.