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.
2. Workspace manifests. package.json (root and nested), plus any Cargo.toml, go.mod, pyproject.toml, or similar boundary markers.
3. Directory evidence. The tracked path list and the top-level source layout, so a proposed boundary points at real paths.
4. 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.
2. 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.
3. 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).
4. 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.
5. 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.
6. 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.
7. Validate the shape against Model Schema, 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.