UiGraph Artifact Generation Skill

uigraph sync

.uigraph.yaml

Mandatory Workflow

1. Discover project evidence from the user's request and repository files. Look for existing API specs, route definitions, migrations, database schemas, docs, diagrams, tests, deployment config, and service metadata.
2. Ask what to generate before writing anything. Ask the user which artifact categories they want: APIs, database schemas, architecture diagrams, docs, test packs, maps, and optional helper scripts.
3. Propose a final plan after the user selects artifact categories. The plan must list files to create or update, detected project sources, assumptions, validation steps, and any scripts that will be written under

   .uigraph/scripts/

   .
4. Wait for the exact trigger phrase. Do not create or modify

   .uigraph.yaml

   ,

   .uigraph/**

   , or

   .uigraph/scripts/**

   until the user says

   Generate Artifacts Now

   .
5. Generate the approved artifacts only after that exact phrase is received. Generate only the files included in the final approved plan.
6. Validate and reset generated structure after generation. The LLM/agent must inspect the generated files directly and reason through validity. Check that created files are syntactically valid where possible, every

   .uigraph.yaml

   path points to an existing file, links are internally consistent, and generated artifacts match the approved structure. Fix only files generated in this execution.

Hard Approval Gate

• Generate Artifacts Now

  is the only phrase that authorizes generation.
• General requests like "generate artifacts", "create UiGraph files", or "go ahead" are not enough. Ask for the exact phrase before writing artifacts.
• Before approval, only inspect files and ask questions. Do not write

  .uigraph.yaml

  ,

  .uigraph/**

  , or project helper scripts.
• If there is not enough evidence for an artifact category, say so and propose only artifacts that can be supported by discovered evidence or explicit user input.

Repository Layout Convention

repo-root/
├── .uigraph.yaml
└── .uigraph/
    ├── scripts/
    ├── openapi/
    ├── graphql/
    ├── grpc/
    ├── diagrams/
    │   └── <diagram-name>/
    │       ├── <name>.mmd
    │       └── context.json
    ├── db/
    └── docs/

.uigraph/

.uigraph.yaml

.uigraph/scripts/

Repository URL Discovery

.uigraph.yaml

origin

• Use the discovered remote URL for

  service.repository.url

  .
• Normalize SSH GitHub/GitLab/Bitbucket remotes to HTTPS when possible.
• Set

  service.repository.provider

  from the remote host:

  github

  ,

  gitlab

  , or

  bitbucket

  .
• If no remote exists, the remote host is unsupported, or multiple plausible remotes conflict, ask the user for the repository URL before generating artifacts.
• During validation, confirm

  service.repository.url

  matches the detected git remote or an explicit user-provided URL.

Optional Helper Scripts

• Helper scripts must directly generate approved UiGraph artifacts.
• Helper scripts must be written only in JavaScript, Python, or Bash (

  .sh

  ).
• Use JavaScript for JavaScript-based projects, Python for Python-based projects, and Bash (

  .sh

  ) when neither JavaScript nor Python is clearly the project language.
• Do not create scripts whose only purpose is exploration, discovery, inspection, inventory, or reporting.
• If a script inspects project data, it must also write the approved artifact as its direct output.
• Useful generation scripts include generating OpenAPI from known route metadata or generating database schema files from known schema sources.
• Prefer checked-in sources over live infrastructure introspection.
• Do not run live database dump commands such as

  pg_dump

  unless the project clearly supports it and the user explicitly approves that action.
• Scripts must be safe by default and must not overwrite unrelated files without confirmation.
• Post-generation validation is an LLM/agent responsibility.

Post-Generation Validation

• Confirm

  .uigraph.yaml

  exists when it was part of the approved plan.
• Confirm every

  path

  ,

  contextPath

  ,

  schemaPath

  , and frame

  imagePath

  referenced by

  .uigraph.yaml

  exists.
• Confirm every

  databases[*].schemaPath

  file extension matches the dialect:

  .sql

  for SQL dialects (

  postgres

  ,

  mysql

  ,

  sqlite

  ,

  other

  when SQL-like) and

  .json

  for NoSQL dialects (

  dynamodb

  ,

  mongodb

  ).
• Confirm

  service.repository.url

  matches the detected git remote or an explicit user-provided URL.
• Validate YAML and JSON syntax when applicable.
• Check OpenAPI, GraphQL, gRPC, SQL, Mermaid, and docs files are structurally plausible when generated.
• Check test case and map component references use matching API group names, operation IDs, doc names, test pack names, and architecture diagram names.
• Fix only files generated in the current execution. Do not rewrite unrelated user files.

What the LLM Already Knows vs. What This Skill Provides

• OpenAPI 3.0/3.1 specs
• GraphQL SDL
• gRPC proto3
• SQL schemas

• The exact

  .uigraph.yaml

  schema and validation rules
• How to link artifacts together (test cases → APIs, maps → test cases, etc.)
• The

  context.json

  format for architecture diagrams
• The DynamoDB/MongoDB JSON schema format
• Map/Frame/FocalPoint/Component structure
• Domain-to-artifact mapping patterns

Reference Documents

references/uigraph-yaml-schema.md

.uigraph.yaml

references/validation-rules.md

references/architecture-diagrams.md

references/database-schemas.md

references/test-packs-and-cases.md

references/maps-frames-focalpoints.md

references/docs.md

references/ci-cd-integration.md

references/domain-mapping-guide.md

references/confirmation-workflow.md

Templates

assets/templates/