lonely-lockley/archinsight/claude

Archinsight

Use this skill when creating, analyzing, or repairing Insight .ai models and .aiq custom views, or when importing an existing architecture description into Insight.

Insight is its own typed architecture-as-code language. Do not infer its syntax from YAML, Mermaid, PlantUML, Structurizr, or C4 DSL.

Claude Usage Notes

Treat this SKILL.md as the entrypoint and load routed references only when the task needs them. With shell access, run validation directly. Without it, ask the user to run the exact command and paste the output. Do not silently install npm packages or change machine configuration.

This package was generated by Archinsight CLI {{CLI_VERSION}}. Run archinsight --version before editing. If the installed version differs, regenerate the skill so its references, core sources, examples, and built-in queries match the runtime.

Required Tool

Use the Archinsight CLI as the validation source of truth:

archinsight --help
archinsight link . --format text

If archinsight is not available in Claude's environment, read references/cli.md. Do not install or update packages without the user's authorization.

Task modes

Choose one mode before acting:

• Analyze: stay read-only and follow references/analysis.md. Inspect

sources, run structure, link, and the relevant query, then separate authored facts, derived relationships, deployment projections, and rendered presentation in the findings. Lead with the verdict, then its model evidence; mention a limitation only when it could change the verdict. Search the whole project unless the user explicitly requests a context or source-file scope; only then add $context or $tab filtering.

• Repair: reproduce the defect first. For a visual defect, inspect

archinsight query ... --format json before treating the image as evidence that the model is wrong. Request the current image or rendered output when it is not available, make the smallest model or query change, and validate the same semantic path again before rendering.

• Build or rebuild: perform discovery before editing, then model from the

outside inward and validate after each architectural layer.

• Extend an existing model: inventory existing ids, imports, edges, and view

scope; preserve stable identities and compare linked/query results before and after each focused change.

• Import an existing model: follow references/importing-models.md.

Establish which source artifacts are authoritative, translate facts rather than drawing layout, record uncertain mappings, and validate one architectural layer at a time.

Before any build, rebuild, import, or structural edit, inspect the supplied context and every relevant source already available through the repository, attachments, configured skills, MCP integrations, or other authorized tools. Do not ask the user to repeat information the agent can retrieve reliably on its own. If a material fact is still missing after those sources are exhausted, ask one short, non-repetitive message containing only the one or two questions that could change the model. Do not use a questionnaire or ask about the audience by default. If the available evidence is sufficient, proceed without a discovery question. Use retrieved material as the source of truth; do not invent missing architecture.

Workflow

1. Read the existing .ai and .aiq files before editing.
2. Preserve indentation and the project's existing naming style.
3. Model architecture from the outside inward: context, external actors/systems,

systems, containers/services, components, project-defined code when needed, and deployment details.

1. Do not ask about deployment depth until the task touches infrastructure,

runtime placement, regions, brokers, gateways, storage, or deployment.

1. At that point, decide per system whether pragmatic mixed C2 or explicit

deployment modeling is appropriate. For explicit deployment, attach placement/storage to systems and containers (including services); components and code deploy with their container. Attach path infrastructure that needs $to to wires, and make pub/sub dependencies consumer-owned.

1. If a diagram becomes noisy, adjust scope/query before changing a correct

graph model.

1. Save reusable graph queries under views/ and reusable RETURN TABLE

reports under reports/. Use reserved view basenames only for intentional web-view overrides.

1. Prefer small, focused files connected by context, import, and extend.
2. Keep definition, context, and environment sources in separate files.
3. Use archinsight structure . --format text to inspect the current model

before broad edits when the CLI is available.

1. Validate every Insight change with archinsight link . --format text when

shell access is available; otherwise ask the user to run validation.

1. For C2, C3, C4, Deployment, or query changes, inspect the selected graph with

archinsight query ... --format json before rendering.

1. If validation fails, fix the first real syntax/type/linking error before

adding more model content.

Communication

When shell access is unavailable, give the user short copy-pasteable commands:

archinsight link . --format text
archinsight structure . --format text

If rendering is needed, ask for the source file when it is not obvious. The CLI infers the context declared by that source:

archinsight render . -s <source.ai> -v c2 -f svg -o diagram.svg

Report diagnostics by source, line, column, and message. Avoid rewriting large sections of Insight unless the existing layering is already understood.

Reference routing

• Read references/cli.md when the CLI is missing, its version differs from

the generated skill, or the skill package must be regenerated.

• Read references/modeling.md before creating or extending a

model.

• Read references/importing-models.md when translating an existing

architecture description, diagram, inventory, or foreign DSL into Insight.

• Read references/syntax.md before writing unfamiliar Insight syntax.
• Read references/layered-architecture.md when decomposing a system across

C1, C2, C3, C4, and Deployment views.

• Read references/c1-context.md when working with system context models.
• Read references/c2-containers.md when working with containers or services.
• Read references/c3-components.md when working with component internals.
• Infer and reuse an existing C4 Code vocabulary from the repository. Ask the

user about entity kinds only when creating the Code layer or extending that vocabulary, unless the current request already makes the choice.

• Read references/c4-code.md when defining or querying modules, packages,

classes, functions, schemas, or other project-specific code concepts.

• Read references/deployment.md when working with environments,

deployments, infrastructure inventory, profiles, or placement.

• Read references/deployment-projections.md when working with physical

paths, projection rules, or a missing or unexpected Deployment edge.

• Read references/scaling.md when splitting a repository into reusable

framework, environment, profile, system, or view files.

• Read references/project-structure.md before declaration lookup, imports,

or broad file changes.

• Read references/core.md and .core/*.ai before assuming built-in types,

constructors, attributes, presentations, or projections.

• Read references/queries.md before writing graph views or RETURN TABLE

reports, supplying parameters, or interpreting query JSON/CSV.

• Read references/custom-views.md before creating a saved .aiq view or

overriding a built-in query.

• Read references/query-recipes.md when a view hides expected content,

returns unexpected content, or needs customization.

• Read references/validation.md before validating semantic or rendered

results.

• Read references/analysis.md for inventories, dependency impact, paths,

topics, missing relationships, aggregation, and resource-bounded reports.

• Use examples/layered-architecture.ai as a compact valid model.