Index of every page on this site: llms.txt
All skills
qoderai avatar

/architecture-model-bootstrap

@c6240a8
by qoderaiqoderai/better-harness2.5k stars
208
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/qoderai/better-harness/architecture-model-bootstrap

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈106 tokens for metadata: the name and description. ≈1.2k when used: this file. ≈830 more on demand in 1 file.

Description uses 5.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈424 characters, or 5.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill facilitates the creation of software architecture models by analyzing source code, manifests, and documentation. While it processes untrusted documentation files, its behavior is strictly governed by grounding rules that require all model elements to be backed by verifiable code paths, and its output is limited to a structured JSON schema.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at c6240a8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 2 months ago

README badge

README badge for qoderai/better-harness/architecture-model-bootstrap