architecture-model-bootstrap

Architecture Model Bootstrap

Turn the deterministic candidate the Impact pane generates into a model a reader

can confirm. The server already derives a bounded, grounded skeleton from the

worktree (one SoftwareSystem, a Container per workspace, Components for source

directories). This skill does the semantic half a static analyzer cannot:

naming, grouping, kinding, describing, and proposing the external systems the

code only hints at — without inventing structure the evidence does not support.

Default to the repository's reply language. Keep edits grounded and reversible:

the output is a proposal a human saves, never a fact you assert.

When to use

• A project declares no model and the Impact pane falls back to a generated one.
• A reader wants the generated skeleton refined before saving it as declared.
• An existing declared model needs elements renamed, merged, split, re-kinded, or

described against current code.

Do not use it to invent business capabilities, runtime traffic, or external

systems that no evidence supports. L1 system context and external systems stay

proposed and human-confirmed, per the parent spec's non-goal.

Inputs (the evidence pack)

Gather these before proposing anything:

1. The generated candidate. Open the Impact pane on any commit, or read the

model the server would generate — one SoftwareSystem, Containers per

workspace manifest, Components per source directory, every element tagged

generated, plus bindings mapping path globs to element ids.

1. Workspace manifests. package.json (root and nested), plus any

Cargo.toml, go.mod, pyproject.toml, or similar boundary markers.

1. Directory evidence. The tracked path list and the top-level source layout,

so a proposed boundary points at real paths.

1. Prose evidence. README.md, AGENTS.md, docs/, ADRs — for names,

ownership, and declared external dependencies only, never for structure the

code contradicts.

Workflow

1. Read the candidate and the manifests. Establish the real boundaries the

generator found before changing any of them.

1. Name and describe. Replace generic ids/names (packages-api, src) with

the project's own vocabulary. Give each kept element a one-line description

grounded in what its files do.

1. Re-kind where evidence warrants. A deployable/independently owned unit is

a Container; an internal building block inside one is a Component. Do not

promote a directory to a Container without a boundary marker (a manifest, an

entrypoint, a deploy target).

1. Merge and split. Fold sibling directories that are one component; split a

directory that clearly hosts two. Every resulting element keeps at least one

real path glob.

1. Propose relationships you can ground in imports, HTTP clients, or declared

dependencies. Mark each with its kind (Contains, Imports, ResolvedCall,

DeclaredHttp, DeclaredRelationship). Leave an unresolved edge out rather

than guessing a target.

1. Propose external systems and people only as clearly-labelled candidates,

with the evidence (a client, an env var, a README claim) named in the

description. These are the L1 scale the parent spec keeps human-confirmed.

1. Validate the shape against [Model Schema](references/model-schema.md), then

hand the model and bindings back for the reader to save through the Impact

pane's Save as declared model action. Never write the file yourself unless

the reader asks.

Grounding rules (hard constraints)

• Every element you keep must have at least one binding whose path glob matches a

real tracked path. No element without evidence.

• Never invent a binding to a path that does not exist in the worktree.
• Keep the arch-core shape exactly: elements (snake_case parent_id) +

relationships (source_id/target_id). This is what the Impact host

consumes and what discovery validates.

• A directory is not a component and a repository is not a container. Boundaries

need a marker, not just a folder.

• Proposed external systems, people, and L1 context are candidates a human

confirms, labelled as such in their descriptions.

Output

Return two artifacts, ready for Save as declared model:

• model.json — the refined { elements, relationships } in arch-core's shape.
• bindings.json — [{ "path_glob": "...", "element_id": "..." }], every glob

resolvable in the worktree.

State briefly what you renamed, merged, split, re-kinded, and proposed, and which

elements remain low-confidence candidates a reader should check first.