Analyse an Agentic System

Type: types/instruction.md

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/.

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 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 only when separately commissioned and only after the complete run state validates.