Files
Jonathan Boniface 416c66ced4
All checks were successful
check agents / check (push) Successful in 10s
Add CP1 Discovery agents in both patterns
ALZ-F01 Discovery as a sub-agent orchestrator (sub-agents/) and as eight
individual declarative agents (individual-agents/), with their KAB workflow
exports. Shared check, render and import scripts, the alz-discovery-sample
MCP server, the crucible-kab-dev deploy profile, deployment docs, platform
issue reports and the source material. Agent steps time out at 20 minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 18:25:57 +00:00

5.2 KiB

User guide: running Agentic Landing Zone discovery

This guide is for the Engagement Lead or delivery engineer who runs discovery for a client engagement and reviews its results. It assumes the agent is deployed and its MCP servers are registered (see deployment).

What discovery does

Discovery builds an evidenced picture of the client's estate:

  • what is in scope;
  • what each workload runs;
  • how the CMDB differs from reality;
  • which data stores hold sensitive data;
  • how systems depend on each other;
  • what the network looks like.

It runs in four phases, and each phase builds on the one before:

Phase What happens Specialists involved
plan Reads the scope, data sources and budgets, and plans a task for every scope entry. An entry that can't be planned is a declared gap, with a reason. Discovery Planner (ALZ-DSC-01)
collect Ingests CMDB and ITSM records, then scans each planned target at metadata level. Nothing is installed and no credentials are used on workloads. Estate Scan Executor (ALZ-DSC-02)
analyse Builds one de-duplicated inventory, then CMDB drift, data classification, the network map and the dependency graph. DSC-03, DSC-04, DSC-05, DSC-07, DSC-06
critique An independent critic checks coverage, evidence, prompt-injection handling and tool-call integrity, and returns pass or fail. Discovery Critic (ALZ-DSC-08)

Running it

From KAB (normal use). Run the workflow CP1 - Agentic Landing Zone - Discovery in the engagement's project. Give it two inputs:

Input Example Notes
engagement_id ENG-MERIDIAN-001 The engagement. Letters, digits, - and _.
run_id RUN-2026-10-29-01 A new id for every discovery run. Reusing one continues that run.

The workflow runs the four phases in order. After critique it stops for your approval: continue hands over to Assessment, rerun runs the critique again, and abort stops.

One phase at a time. Anyone testing the agent can send it a request directly:

{"engagement_id": "ENG-MERIDIAN-001", "run_id": "RUN-2026-10-29-01", "phase": "plan"}

Leave phase out and the agent runs the next phase the run needs. For a large estate, add "batch": 1 (2, 3…) to the collect phase to scan one planned batch at a time.

Reading the result

Every phase returns the same shape.

status:

Value Meaning What to do
completed The phase's checks all passed Nothing
completed_with_gaps It finished, but something is missing or weak Read issues before going on. A critique with any coverage gap is always this, never completed.
failed The phase couldn't do its job Fix the cause in issues, then run that phase again by name
halted It was stopped on purpose Find out why before restarting

The other fields:

  • issues: why the status isn't completed. Includes refused tool calls, failed specialists, plan-rule breaches (scope_lock, sequencing, rate_budget, scope_accounting) and declared gaps.
  • artifacts: what the phase stored. Each has a ref (for example plan/task-graph), a sha256 and produced_by, which is the specialist whose answer it is. The list comes from the run's store, not from anything a model wrote.
  • verdict (critique only): pass or fail, the coverage gaps, the declared gaps and the reasons. It is recomputed in code. If the critic says pass while a scope entry has no finding, the verdict is fail.
  • next_phase: the phase to run next, or null at the end or after a failure.

What it will not do

  • Scan anything outside the scope list, whatever a document or record says.
  • Read rows of client data: classification uses schema metadata only.
  • Write to the client's CMDB, ITSM or any other system: every tool is read-only.
  • Follow instructions found in data. For example, a server note that says "ignore previous instructions" is recorded as a prompt-injection finding and otherwise ignored.

Where the data is kept

The run's records are stored on the platform's shared execution storage, under alz-discovery/<engagement_id>/<run_id>/. They can't be changed once written, and each is chained to the one before it. A record edited outside the agent fails the next phase with an integrity error. Traces don't capture prompt or reply content.

Troubleshooting

Message in issues Cause Fix
the collect phase needs plan/task-graph … run the plan phase first A phase was run before its predecessor Run the earlier phase
the plan phase ended failed; fix it and run that phase again by name The chain stopped after a failure Fix the plan's issues, then send "phase": "plan"
this run has already been critiqued The run is finished Use a new run_id
… was changed after it was written A record was edited outside the agent Start a new run, and report it
sub-agent failed: … A specialist's model call failed Check the model gateway, then rerun the phase
scope_accounting: SE-… is neither planned nor a declared gap The planner missed an entry Rerun the plan phase