The edit loop

The edit loop is Albumi’s canonical workflow for making changes to a landscape through an AI agent. It has six steps: pull the workspace, explore to understand what is there, edit in JSON, validate after every batch of changes, audit before pushing, push as a reviewable Architecture Change Request.

You do not run the steps yourself — the agent does. Your job is to point it at work and check the result. This page is the reference for what that conversation looks like, what the agent is invoking under the hood at each step, and where things go wrong.

Assumes the agent is already connected: see MCP Server Setup. The examples use Claude Code, but the conversation shape is the same for any MCP-aware client.

Command surface — what the agent actually has

Four MCP tools and five prompts. The agent always has the tools; the prompts become available as slash commands your client can trigger explicitly.

Tools (agent-invoked)

• pull_workspace(workspace_id?, file_path?) — download a workspace as JSON. Omit workspace_id to list available workspaces. Omit file_path to auto-name from the workspace.
• validate(file_path) — schema, referential integrity, and circular-reference check on a local JSON file. Pure, no network.
• audit(file_path) — 70+ EAM checks across structural integrity, data quality, lifecycle coherence, compliance, and more. Pure, no network.
• push_workspace(file_path, name?, workspace_id?) — upload JSON as a new Architecture Change Request. Requires authentication.

Prompts (explicit slash commands if your client supports them)

• /mcp__albumi__pull_workspace — instruct the agent to pull, list, or select a workspace.
• /mcp__albumi__validate — instruct the agent to validate the file it has been working on.
• /mcp__albumi__audit — instruct the agent to run a comprehensive audit, including manual-judgment checks beyond what the tool does alone.
• /mcp__albumi__push_workspace — guide the agent through a safe push, including confirming the ACR name.
• /mcp__albumi__generate_workspace — prime the agent with the full workspace schema and generation rules. Use this before starting from a source document — without it, the agent may miss enum values or referential rules.

Tools and prompts share names; they are not the same thing. A tool is a function the agent calls; a prompt is a named instruction template the agent receives. For the edit loop you will trigger most of this through plain prompts in English — the slash commands are there when you want to make sure the agent uses the prompt’s exact phrasing.

CLI subcommands and flags worth knowing

The same four tool names exist as CLI subcommands for use outside an agent — CI pipelines, scheduled jobs, interactive terminals.

• albumi login [--manual] — authenticate interactively. --manual skips the browser flow and accepts a pasted token. Auto-activates over SSH.
• albumi pull [--workspace <id>] [-o <file>] [--json] — download a workspace. -o sets the output path (default ./workspace.json). --json emits a machine-readable summary.
• albumi validate <file> [--json] — validate. Exit code 0 = clean, 1 = errors.
• albumi audit <file> [--severity critical|warning|info] [--json] — audit. --severity filters; default emits everything. Exit code 1 if any criticals are present.
• albumi push <file> [--workspace <id>] [--name <acr-name>] [--json] — push. --name sets the ACR name explicitly; otherwise the agent or operator is prompted.
• ALBUMI_API_TOKEN environment variable — authenticate without a login step. Use in CI.
• ALBUMI_CONFIG_DIR environment variable — move the credential store from ~/.albumi/ to another directory. Useful in container builds and ephemeral environments.

Step 1 — Pull

The loop begins with a pull. The agent asks the server for the current state of the workspace and writes it to a local JSON file. From this point on, changes happen in the file, not on the server.

Your prompt:

“Pull my workspace.”

What happens:

1. Agent calls pull_workspace() with no workspace_id.
2. Server returns the list of workspaces you have access to.
3. Agent shows you the list; asks which one.
4. You reply with the name or ID.
5. Agent calls pull_workspace(workspace_id: "...").
6. File saved to ./workspace.json or a name derived from the workspace.

If you only have one workspace the agent may skip the selection step and pull directly. Both paths end in a local JSON file.

Typical output:

Pulled "Acme Production" (id: 7f3a...).
File: workspace-acme-production-2026-04-22.json (124 KB)
Applications: 87
Integrations: 143
Data Objects: 52
Organizations: 9
Business Capabilities: 64
IT Components: 38
Initiatives: 12

Step 2 — Explore (with jq)

A workspace of any real size is too large to load into the agent’s context. The second step is to let the agent inspect it with jq — reading only what it needs for the task at hand.

Your prompt:

“How many applications are in end_of_life lifecycle? List them.”

The agent reaches for jq, not the MCP tools:

jq '.applications[] | select(.lifecycle.status == "end_of_life") | .name' workspace.json

and reports the result.

Other useful exploration prompts:

“Find all integrations that carry ‘Customer’ as a data object.”

“Which applications have no owner?”

“Top 10 applications by number of integrations, inbound and outbound combined.”

“Which business capabilities have no application realising them?”

None of these require loading the full workspace into the conversation. jq runs on disk; the agent quotes results.

Step 3 — Edit

Edits happen in the JSON file. The agent writes — you prompt.

Prompts that work well:

“Add a new application: name ‘Loyalty Service’, owner [email protected], lifecycle status active, business capability ‘Customer Engagement’, functional fit excellent, technical fit adequate, hosting cloud.”

“Mark all applications owned by ‘Bob Smith’ as lifecycle status phase_out with phase_out_date 2026-12-31.”

“Remove the integration from ‘Legacy CRM’ to ‘Billing’. We already replaced it with ‘NewCRM → Billing’.”

“Every application in the ‘Finance’ organisation that is currently plan should move to phase_in. Set phase_in_date to today.”

Three rules the agent is trained on, which you should also know so that ambiguous prompts can be disambiguated:

• Integration direction is data flow, not request direction. CRM → Billing means data originates in CRM and ends up in Billing — regardless of which side opens the socket. This is the single most common modelling mistake. See Integrations for the full rule; when in doubt, ask the agent to confirm the data flow, not the network call.
• Integration operations are Create, Update, Delete only. Not Read. If you want to record “App X reads from App Y”, the correct model is Y → X with initiator = pull. Read is not a separate operation on an integration.
• Enum values are canonical. end_of_life, not eol. phase_out, not phasing-out. The validator catches mismatches, but avoiding them in the prompt saves a round trip.

Step 4 — Validate (early and often)

After every meaningful batch of changes, validate. The tool is pure and fast — running it is cheap, finding out the JSON is broken after ten more edits is expensive.

Your prompt:

“Validate.”

What happens: agent calls validate("./workspace.json"). Returns a list of errors, or a clean result. Three checks:

1. JSON schema — types, required fields, enum values correct.
2. Referential integrity — every ID reference resolves to an existing entity.
3. Circular references — no parent_id chain that loops.

If errors come back, the agent fixes them and re-validates. The fix-validate cycle should converge in one or two iterations. If it does not, something is structurally off — stop and read the errors manually.

Explicit slash command: /mcp__albumi__validate.

Step 5 — Audit

Validation proves the JSON is well-formed. Audit checks whether the architecture it describes is coherent — no duplicate names, no missing Systems of Record, lifecycle dates in order, integration consistency, compliance flags correct, and so on across 70+ checks.

Your prompt:

“Run a full audit. Fix critical findings. Leave warnings for me to review.”

What happens: agent calls audit("./workspace.json"). Returns findings grouped by severity (critical, warning, info) and category — structural integrity, data quality, architecture consistency, lifecycle coherence, network analysis, portfolio health, compliance and risk, technology risk, data governance, initiative alignment, organisational coverage, strategic alignment, redundancy and complexity, migration planning.

Each finding has a check ID, the entity it refers to, and a message.

Typical first pass after a medium edit:

critical: 2
  - no_system_of_record: Data object 'Customer' has no System of Record designated.
  - lifecycle_date_order: Application 'Legacy CRM' has phase_out_date before active_date.

warning: 14
info: 37

The agent applies programmatic fixes where the answer is unambiguous — reordering lifecycle dates, clearing duplicate names, filling in derivable defaults — and lists the ones it cannot decide alone:

“Which application should be the System of Record for ‘Customer’ — CRM or NewCRM?”

You answer, the agent updates, re-audits. Loop until criticals are zero or deliberately accepted.

Explicit slash command: /mcp__albumi__audit. This prompt adds judgment-based checks the tool does not automate — relationship sanity, strategic coherence, redundancy patterns. Running audit through the prompt is more thorough than calling the tool alone; use the prompt when doing a major review, the tool alone when doing a quick sanity check mid-edit.

Step 6 — Push

When validate is clean and the remaining audit findings are ones you have explicitly accepted, push.

Your prompt:

“Push this. Name the ACR ‘Q2 Customer Data Cleanup’.”

What happens:

1. Agent re-reads the file’s metadata.workspaceId to confirm the target.
2. Agent calls push_workspace(file_path, name: "Q2 Customer Data Cleanup").
3. Server creates an Architecture Change Request containing every difference between the file and the current server-side workspace.
4. Agent reports the ACR ID and a URL.

Example output:

ACR created: "Q2 Customer Data Cleanup" (id: acr_8f7b...)
URL: https://my.albumi.app/acr/8f7b...
Changes:
  + 3 applications added
  ~ 12 applications modified
  - 1 integration removed
  ~ 7 integrations modified

Nothing is live yet. The ACR is a draft for review; see the next step.

Step 7 — Review in the UI

Open the ACR in the UI. You see each change annotated against the current landscape: additions, modifications, deletions. Approve, request revisions, or cancel. Once approved, an Admin implements the ACR and the changes merge into the mainline workspace.

See Governance Overview and Change Requests for the review mechanics.

Continuing loops — not just first-load

The edit loop is circular, not linear. After the first push, normal work is incremental:

• Incremental update from a meeting: “I took notes during today’s architecture sync. Here they are. Update the workspace with what changed.”
• Impact analysis: “Before I propose decommissioning Legacy CRM, tell me everything that depends on it and what would need to happen first.”
• Drift detection: “Audit the workspace. Focus on compliance and data governance. What has degraded since last month?”
• Documentation cleanup: “Find all entities with missing descriptions, missing owners, or no business capability. Fix the easy ones, list the rest for me to decide.”
• Migration planning: “We are moving all on-prem Oracle databases to cloud-managed Postgres. Find every application and integration affected, draft the migration initiative, and link the relevant ACRs.”

Each of these is a fresh pull → edit → validate → audit → push cycle. The agent does not hold state between sessions — every cycle begins with a pull, because the server is the source of truth and your local file is always a snapshot.

Pitfalls

A short list of things that surprise people:

• The agent cannot push to a workspace you are not a member of. Pulling requires membership; pushing requires at least Contributor role. If a pull succeeds but a push is rejected, check your role in the target workspace.
• A workspace file includes metadata.workspaceId. If you copy the file to a different machine and push without specifying --workspace, the push targets the original workspace. This is usually what you want. To push to a different workspace, pass --workspace <new_id> or clear the metadata.
• Validate is deterministic; audit findings can drift between runs. Audit computes counts and percentages — adding one application can flip a portfolio-health check. Expect minor drift; criticals are stable, warnings fluctuate.
• ACR is a draft, not a commit. Pushing creates a reviewable proposal. You still need to approve and implement before anything appears in the mainline workspace. Nothing you do via the agent enters production without a human explicitly approving it.
• The agent does not know your organisation’s conventions. Naming schemes, capability tree shape, which criticality tier maps to which systems — these are learned per workspace, not built in. Calibrate with examples from your own landscape on the first few cycles.

For CI and scripts

Every MCP tool also exists as a CLI subcommand, which is how you drop validation and audit into a CI pipeline without an agent:

export ALBUMI_API_TOKEN="..."

albumi pull --workspace "$WORKSPACE_ID" -o ./workspace.json
albumi validate ./workspace.json            # exits 1 on schema error
albumi audit ./workspace.json \
    --severity critical \
    --json > findings.json                  # exits 1 if any criticals

Exit code 1 fails the CI job. Pipe the JSON to whatever dashboard or alert system you want. Common pattern: run on every merge to main, fail the build on a new critical finding, post warnings to a Slack channel.

For a scheduled job that produces an ACR from a source file — say, a nightly sync from a CMDB — the push step also runs headless:

albumi push ./generated-workspace.json \
    --workspace "$WORKSPACE_ID" \
    --name "Nightly sync $(date +%Y-%m-%d)"

The resulting ACR is reviewable the same way any other change is — the CI bot submitted it, the humans approve it.