Archinsight

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.

Codex Usage Notes

Treat this SKILL.md as the entrypoint and load routed reference files only when the task needs them. Use shell access to run validation. Do not silently install global 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, 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.
• 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.
4. Do not ask about deployment depth until the task touches infrastructure, runtime placement, regions, brokers, gateways, storage, or deployment.
5. 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.
6. If a diagram becomes noisy, adjust scope/query before changing a correct graph model.
7. Save reusable custom views as .aiq. Unless the user specifies another location, create views/ and write views/<descriptive-name>.aiq.
8. Prefer small, focused files connected by context, import, and extend.
9. Keep definition, context, and environment sources in separate files.
10. Use archinsight structure . --format text before broad edits when the project shape is unclear.
11. Validate every Insight change with archinsight link . --format text.
12. For C2, C3, C4, Deployment, or query changes, inspect the selected graph with archinsight query ... --format json before rendering.
13. If validation fails, fix the first real syntax/type/linking error before adding more model content.

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 queries or interpreting query JSON.
• 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 read-only architecture analysis, dependency questions, impact exploration, and the boundary between Insight queries and analysis of their JSON output.
• Use examples/layered-architecture.ai as a compact valid model.