---
name: architecture-model-bootstrap
description: Use to refine a generated Better Harness architecture model into a confirmed one for the Impact pane. Trigger when a project has no .better-harness/architecture/model.json, when the Impact pane shows an "Auto-generated" model, or when a reader asks to name, merge, split, re-kind, or describe the derived Container/Component structure and propose external systems before saving it as declared.
title: architecture-model-bootstrap
canonical_url: https://skilld.dev/gh/qoderai/better-harness/architecture-model-bootstrap
last_updated: 2026-10-07T00:09:43.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/model-schema.md](https://skilld.dev/api/skills-raw/qoderai/better-harness/architecture-model-bootstrap/references/model-schema.md).
>
> If the user asked to install this Skill, run `npx skilld install qoderai/better-harness/architecture-model-bootstrap`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/architecture-model-bootstrap`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/qoderai/better-harness/architecture-model-bootstrap) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/architecture-model-bootstrap`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/architecture-model-bootstrap --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/architecture-model-bootstrap --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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](https://skilld.dev/api/skills-raw/qoderai/better-harness/architecture-model-bootstrap/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.
