Analyse Agentic System

---
name: analyse-agentic-system
description: "Use when asked to analyse, review, or refresh an external agent runtime, orchestration system, agent operating layer, agent memory/knowledge/context-engineering system, or narrower model-dependent operational mechanism from inspectable sources."
type: types/instruction.md
user-invocable: true
argument-hint: "<system identifier> plus source input (repository, checkout, snapshot/bundle, or documents), optional Git commit and public review path"
allowed-tools: Read, Write, Grep, Glob, Bash, Task
model: opus
---

# Analyse an Agentic System

Analyse one external agentic system at one frozen evidence boundary and publish its retained set and compact generated review. 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 run directory under `kb/agentic-systems/reports/state/`, one generated review under `kb/agentic-systems/reviews/`, and the retained set under `kb/agentic-systems/reports/retained/<run-id>/`; 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.

Run the orchestrator from the repository root and keep that working directory throughout the run. Workers must inherit it: `commonplace-validate` discovers the root there, and the boundary job uses `related-systems/`.

## Isolated run setup

Run each analysis in a dedicated Commonplace worktree at a committed method
revision. Prepare it from the originating checkout before starting the run:

```bash
commonplace-workflow prepare-analysis --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 with the worktree, commit, command paths and setup status.
`--worktree <new-path>` overrides the location; `--revision <commit>` selects
a committed method revision instead of `HEAD`. Existing destinations are refused.
Failed installations retain the worktree and a sibling `.preparation.json`
record for diagnosis; they do not open an analysis or launch a harness.

By default, uncommitted changes stop preparation. `--allow-dirty-origin` permits
unrelated changes in the originating checkout and excludes them from the new
worktree. 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. Runtime
locks, caches and top-level harness README files are not startup inputs; files
inside protected resource directories remain conservatively covered. Source
and publication checks remain unchanged.
The Git comparison covers repository files, not user-wide harness settings.

To prepare and launch a fresh harness in one command, append its executable
and arguments after `--`, for example:

```bash
commonplace-workflow prepare-analysis --name letta-code -- pi
```

Code starts that process in the new worktree with its local commands first on
`PATH` and inherited Python import overrides removed. Do not pass harness
arguments that change its working directory or resume an earlier session.
A coordinator may prepare the worktree, but must not continue the analysis in
its existing session: startup instructions already loaded from the origin
cannot be cleared by changing directory. Start a fresh harness in the prepared
worktree. Its workers must inherit that directory and command environment,
including after network escalation. Do not reinstall the shared user-level
tool to point at the run.

When preparation was run without a harness command, use the returned worktree
and `path-prefix` to start a fresh harness there. Preparation alone is not proof
that an IDE or remote harness inherited the environment.

Before opening a run, check inside the harness:

```bash
command -v commonplace-workflow
command -v commonplace-validate
python3 -c 'import commonplace.lib.agentic_workflow as m; print(m.__file__)'
```

Both commands must resolve under this worktree's `.venv/bin/`, and the module
must resolve under its `src/commonplace/`. If they do not, stop before opening
the run and ask the operator to repair the harness environment. A separate
working directory alone does not isolate the shared editable installation.

Keep the worktree's code, method files, lockfile and environment unchanged
until the run finishes; develop and merge method changes elsewhere. On resume,
restore the same environment before following the worker-recovery rules.
After completion, transfer the retained set and review back when the operator
authorizes merging the results.

## 1. Open the run

1. Commit any pending method change first: the run pins the method commit when it opens, and publication requires it unchanged.
2. From the repository root, start the run:

   ```bash
   commonplace-workflow start commonplace.lib.agentic_workflow:AnalyseAgenticSystem \
     --param system="<source-native system name>" \
     --param source-identity="<stable source identity, e.g. https://github.com/owner/repo>" \
     --param source="<the caller's source input, as given>"
   ```

   Code normalizes the source identity (no surrounding whitespace, trailing `/` or trailing `.git`; a lowercase URL scheme and host), and the run uses that form throughout. The run ID takes its name from the source identity's last path segment (the repository name for a GitHub URL), or from the system name when the identity is not a URL. Add `--param review-path=kb/agentic-systems/reviews/<name>.md` only when the caller supplied a review path; it must be directly under `reviews/`. The command allocates the run ID and prints the run directory, `kb/agentic-systems/reports/state/<run-id>`.

   For a GitHub source, code freezes `related-systems/<owner>--<repo>/`
   before the boundary job. Without a revision it clones a missing checkout,
   or fetches an existing clean one, and detaches it at the tip of the
   default branch. Add `--param source-revision=<full 40-hex commit>` when
   the caller requests that 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. A missing checkout is then cloned at that commit, and a
   clean existing one is moved to it. A dirty checkout, a foreign origin, or
   an unavailable commit stops the run for the operator. The option requires
   a GitHub identity.

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

## 2. Drive the run

Follow [drive a code-scheduled run](./drive-a-code-scheduled-run.md) with `<run>` = the directory `start` printed. The run is new: you started it in this session.

## 3. Report

When `step` gives `done`, run `commonplace-agentic-analysis-handoff <run>/run-state.md` and include its output unchanged in your final response. After a published review, 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.

When the run stopped, the loop's stop report is your final response; do not run the handoff. A correctable pre-publication failure keeps the run `running`: the operator repairs the condition and a later session resumes the loop. Set `run-status: failed` with one concise reason only when abandoning the run or when publication left public state uncertain. Never resume a failed run; use a new run ID.

A transfer scan is separate: run [`scan-agentic-system-transfer`](../../../instructions/scan-agentic-system-transfer/SKILL.md) only when separately commissioned and only after the complete run state validates.

---

- [Agent-runtime analysis should separate scheduling, context assembly, and external state](../../../notes/agent-runtime-analysis-should-separate-scheduling-context-state.md) — rests-on: the causal runtime responsibilities of the runtime job
- [Agent orchestration occupies a multi-dimensional design space](../../../notes/agent-orchestration-occupies-a-multi-dimensional-design-space.md) — rests-on: why the runtime inventory remains open
- [Agent memory is a crosscutting concern, not a separable niche](../../../notes/agent-memory-is-a-crosscutting-concern-not-a-separable-niche.md) — rests-on: why every run has a memory analyst
- [Knowledge storage does not imply contextual activation](../../../notes/knowledge-storage-does-not-imply-contextual-activation.md) — rests-on: the retention, read-back, presence, and activation distinctions
- [Behavioral authority](../../../notes/definitions/behavioral-authority.md) — rests-on: the consumer, channel, force, and horizon record
- [Tentative theory](../../../notes/definitions/tentative-theory.md) — rests-on: the status of the theory, independent of structure or retention
- [Theory builder](../../../notes/definitions/theory-builder.md) — rests-on: localized, consumed, criticized, and retained theories, and the reflective and autonomous qualifiers
- [Addressable theory](../../../notes/definitions/addressable-theory.md) — rests-on: separately inspectable and editable parts as an additional property
- [A complete theory path does not establish improved capacity](../../../notes/a-complete-theory-path-does-not-establish-improved-capacity.md) — rests-on: the separate evidence claims and stronger requirements for later or recurrent use
- [Reflective system](../../../notes/definitions/reflective-system.md) — rests-on: the causally connected self-representation required for reflection
- [Self-improving system](../../../notes/definitions/self-improving-system.md) — rests-on: the operative, evidence-responsive change the revision-admission records describe