crucible-agent-build-phase-2/docs/agent-specification.md

Application landing zone agent specification

Purpose

Transform application requirements into a reviewable Technical Solution Design and an editable draw.io architecture diagram. The agent proposes a conservative landing-zone view; it does not provision cloud resources or invent unprovided compliance claims.

Input contract

JSON object:

• application_name (string, required)
• business_context (string, required)
• environments (array of strings, optional)
• components (array of objects with required name, optional type, technology, description)
• integrations (array of strings or objects, optional)
• constraints, non_functional_requirements, assumptions (arrays of strings, optional)

Unknown fields are preserved in the TSD assumptions section only when explicitly listed; malformed known fields fail validation.

Output contract

GenerationResult has tsd_markdown, drawio_xml, and validation (valid, errors, warnings). The CLI writes the configured filenames and a validation.json report.

Workflow

1. Validate and normalize requirements without making network calls.
2. Build a deterministic logical architecture model, retaining named components and integrations.
3. Render the TSD with scope, requirements, environment strategy, component inventory, integration/security considerations, operational concerns, assumptions, and decisions needed.
4. Render native draw.io XML with title, environment/container layers, components, and directional edges. IDs are stable (component-<index>, integration-<index>).
5. Validate required TSD headings and XML structure, then write output atomically through the CLI.

Diagram requirements

The diagram must open in draw.io/diagrams.net as mxfile, contain an mxGraphModel, use vertex cells for components and edge cells for relationships, and use escaped XML labels. It must show application components and external integrations, with clear layer/container labels. It may not contain executable code or credentials.

Validation and errors

Missing required strings, non-object components, blank component names, malformed integration objects, or empty arrays where a list is supplied produce actionable errors. The CLI prints the error and exits 2. Rendering failures exit 1. The library never silently drops a named component.