veyra

Imported from cryskram/veyra (AGENTS.md). Install upstream with npx skills add cryskram/veyra. Copyright stays with the author.

AGENTS.md

Veyra Agent Instructions

Veyra is a developer-centric procedural visualization engine written in Go.

Before making architectural or significant implementation changes, read PROJECT.md.

PROJECT.md is the source of truth for Veyra's product vision, architecture, semantic data model, scene model, extensibility model, rendering pipeline, theme system, MVP, and roadmap.

This file defines how an AI coding agent should work on the repository.

1. General Principles

Understand before implementing

Do not immediately start writing code when a task involves architecture or a new subsystem.

First:

1. Inspect the existing implementation.
2. Read the relevant parts of PROJECT.md.
3. Understand existing interfaces and package boundaries.
4. Identify whether the requested functionality already has an extension point.
5. Implement the smallest coherent change.

Do not rebuild existing functionality simply because a different implementation seems interesting.

Prefer simple Go

Write idiomatic Go.

Prefer:

• small interfaces
• explicit data flow
• simple structs
• clear package boundaries
• standard library functionality where practical
• straightforward error handling
• composition over unnecessary abstraction

Avoid:

• excessive generics
• deep interface hierarchies
• unnecessary dependency injection frameworks
• reflection-heavy designs
• global mutable state
• clever abstractions that obscure control flow

Do not try to make Go behave like another language.

2. Read PROJECT.md First

PROJECT.md defines:

• product vision
• architecture
• semantic data model
• scene model
• extractor system
• layout system
• style system
• theme system
• renderer system
• plugin strategy
• MVP
• development phases

When implementation decisions conflict with assumptions in PROJECT.md:

1. Determine whether the implementation reveals a genuine architectural problem.
2. Do not silently diverge.
3. Update the relevant documentation if the architecture changes.
4. Prefer an explicit architectural decision over accidental architecture.

3. Architecture Rules

The core pipeline is:

Data Source
    
Extractor
    
Semantic Data IR
    
Data Mapping
    
Layout / Composition
    
Scene IR
    
Renderer
    
Wallpaper Export

Preserve these boundaries.

Extractors

Extractors understand data.

They must not know about:

• wallpaper resolution
• pixels
• rendering backends
• specific visual styles
• specific themes

An extractor should produce semantic data.

Semantic Data IR

The semantic data model describes what the source means.

It should not contain:

• pixel coordinates
• renderer-specific primitives
• colors
• SVG elements
• GPU resources

Do not couple the semantic model to a particular renderer.

Layouts

Layouts determine spatial structure.

Examples:

force
radial
hierarchical
grid
timeline
orbital

Layouts should not contain domain-specific rendering logic.

Styles

Styles determine how semantic structure is visually interpreted.

Examples:

constellation
circuit
galaxy
blueprint
minimal
neural
matrix

A style should work across multiple data sources whenever possible.

Do not create data-source-specific styles unless there is a strong reason.

Themes

Themes control visual appearance.

A theme must be independent from the data source and style.

For example:

Git
  Constellation + Tokyo Night
  Constellation + Nord
  Circuit + Tokyo Night
  Minimal + Custom Theme

Do not create combinations such as:

TokyoNightConstellation
NordCircuit
DraculaGalaxy

Use independent configuration:

style = constellation
theme = tokyo-night

instead.

Never hard-code theme-specific colors inside extractors, layouts, styles, or renderers.

Renderers

Renderers consume Scene IR.

They should not understand:

• Git
• Kubernetes
• filesystem semantics
• package managers
• specific data sources

The renderer should operate on visual primitives.

4. Extensibility

Veyra is intended to become an extensible platform.

Prefer registries and interfaces over giant switch statements.

Bad:

switch sourceType {
case Git:
    // ...
case Filesystem:
    // ...
case Kubernetes:
    // ...
}

Prefer an extension registry:

Extractor Registry
 filesystem
 git
 dependencies
 ast
 kubernetes

The same principle applies to:

• layouts
• styles
• renderers
• themes

Adding a new component should ideally require adding a new implementation and registering it, rather than modifying unrelated components.

5. Avoid Premature Complexity

Do not implement future architecture before it is needed.

Unless explicitly requested, do not prematurely add:

• GPU rendering
• WASM plugins
• external plugin runtimes
• cloud synchronization
• remote APIs
• complex UI
• plugin marketplaces
• elaborate configuration systems
• dozens of rendering styles

The current priority is building a strong core.

6. MVP Discipline

The MVP focuses on:

Data sources

Filesystem
Git
Dependencies

Layouts

Force
Radial
Hierarchical

Styles

Constellation
Circuit
Minimal

Themes

The architecture must support multiple themes.

Tokyo Night is one example, not the entire theme system.

At minimum, the implementation should prove that two visually distinct themes can use the same style without modifying the style implementation.

Output

PNG
1920x1080
2560x1440
3840x2160
custom resolutions

Do not expand the MVP simply because a future feature is interesting.

There will always be another shiny graph waiting in the bushes.

7. Deterministic Generation

Procedural generation must be reproducible.

Support explicit seeds:

veyra . --seed 12345

Avoid global random state.

Where possible, derive independent deterministic random streams for separate subsystems:

seed
  layout
  particles
  noise
  stars
  effects

Changing one subsystem's randomness should not unexpectedly change unrelated parts of the composition.

8. Visual Quality

Veyra is a visual product.

Correctness alone is not sufficient.

When implementing rendering or composition, consider:

• hierarchy
• spacing
• balance
• negative space
• contrast
• density
• visual rhythm
• depth
• glow
• gradients
• subtle randomness
• readability
• high-resolution output

Avoid turning every visualization into:

black background + neon circles + random lines

Different styles should have genuinely different visual languages.

9. Performance

Performance matters, especially for:

• large repositories
• large dependency graphs
• 4K output
• future 8K output
• dense particle systems

However:

Profile before optimizing.

Do not introduce concurrency or complicated optimizations without evidence that they are necessary.

Prefer straightforward implementations first.

When optimization is needed:

1. Measure.
2. Identify the bottleneck.
3. Optimize the bottleneck.
4. Benchmark.
5. Verify visual correctness.

10. Dependencies

Do not add a dependency casually.

Before adding a dependency:

1. Check whether the standard library is sufficient.
2. Check whether the dependency is actively maintained.
3. Check its license.
4. Check its platform support.
5. Check its API quality.
6. Consider whether it introduces significant transitive dependencies.

Keep the dependency graph understandable.

If a dependency becomes foundational, document why it exists.

11. CLI

The CLI is the primary interface.

The basic experience should remain:

veyra <path>

Examples:

veyra .
veyra ./project

veyra D:\\TAP\\horizon

Useful future commands include:

veyra scan .
veyra generate .
veyra preview .
veyra themes
veyra styles
veyra layouts
veyra plugins

CLI behavior should be:

• predictable
• scriptable
• cross-platform
• useful without the UI

Avoid requiring an interactive prompt for functionality that should work through flags.

Interactive behavior can be layered on top of the core.

12. Configuration

Configuration should be data-driven.

Possible project configuration:

.veyra.yaml

CLI flags should override configuration-file values.

Avoid spreading configuration parsing throughout the codebase.

Keep configuration loading and validation centralized.

13. Error Handling

Errors should be useful to developers.

Bad:

something went wrong

Prefer:

failed to parse go.mod: unexpected token at line 14

Wrap errors with useful context.

Preserve the underlying error where appropriate.

Do not panic for normal user errors.

Reserve panics for genuinely impossible internal states.

14. Testing

Every meaningful subsystem should have tests.

At minimum, test:

• semantic data structures
• extractor detection
• extraction behavior
• normalization
• mappings
• layouts
• theme parsing
• theme discovery
• scene construction
• registries
• renderer behavior

For visual output, use snapshot or golden-image testing where practical.

A rendering change should be intentional.

15. Validation

Before considering a change complete, run appropriate checks.

At minimum:

go test ./...

Also use:

go vet ./...

and formatting:

gofmt -w .

For larger changes, run relevant benchmarks or integration tests.

Do not claim a change is complete if the project does not build or tests fail.

16. Git Workflow

Veyra is Git-controlled and should be committed regularly.

PROJECT.md and AGENTS.md are tracked project files.

They must not be added to .gitignore.

Do not treat them as generated files.

Prefer small, coherent commits.

Good commit messages:

feat: add semantic data model
feat: add extractor registry
feat: add filesystem extractor
feat: add radial layout
feat: add scene primitives
feat: add svg renderer
feat: add theme registry
docs: document scene model
fix: prevent overlapping nodes
refactor: simplify renderer interface

Avoid meaningless commits such as:

fix
fix2
changes
stuff
final
final2
please work

Before making a commit:

1. Review the diff.
2. Run relevant tests.
3. Ensure unrelated changes are not included.
4. Write a concise commit message.

Do not automatically commit every tiny edit.

A commit should represent a coherent unit of work.

Proposed commit message on completion

After finishing a working turn, end your response with a single ready-to-run git commit line that proposes a meaningful commit message for the work just done, so a human can review and apply it without writing a message from scratch. Follow the message style above and tie it to the actual change.

Use it to checkpoint the current built progress with either form:

git commit -m "<message>"            # for already-staged changes

git add -A && git commit -m "<message>"

Where <message> is a concise, meaningful summary of the work, e.g.:

git commit -m "feat: scaffold veyra foundation"

Commit only after go test ./... and go vet ./... pass. The proposed commit is a checkpoint for the current built progress, not an instruction to run anything automatically.

17. Git Safety

Never run destructive Git commands unless explicitly requested.

Do not casually use:

git reset --hard
git clean -fd
git checkout -- .
git restore .
git push --force

Do not rewrite existing history unless explicitly instructed.

Do not discard user changes.

Before modifying files that already contain uncommitted user work, inspect the working tree.

Preserve work that is not part of the current task.

18. Documentation

Update documentation when behavior or architecture changes.

Important architectural changes should be documented in:

docs/adr/

Architecture decisions should contain:

Context
Decision
Alternatives
Consequences

Do not duplicate the entire architecture inside AGENTS.md.

PROJECT.md remains the main project specification.

19. Generated Files

Do not commit generated wallpapers, temporary render output, profiling artifacts, build artifacts, or local caches unless explicitly requested.

Typical generated files include:

dist/
bin/
tmp/
coverage.out
*.png
*.jpg
*.webp

The exact .gitignore should be kept deliberate.

Important source files such as:

PROJECT.md
AGENTS.md
README.md
themes/*.yaml

must remain tracked.

20. Working With Pi and OpenCode

When operating through an AI coding workflow:

1. Read AGENTS.md.
2. Read PROJECT.md when architectural context is required.
3. Inspect the current repository state.
4. Understand existing code before changing it.
5. Make the smallest coherent change.
6. Run tests.
7. Review the diff.
8. Update documentation when appropriate.
9. Leave the repository in a buildable state.
10. Commit coherent work when requested or when the current workflow calls for a checkpoint.

Do not assume that a clean-looking implementation is automatically the correct architecture.

When uncertain, inspect existing code and reason from the current system.

21. When Architecture Needs to Change

Architecture is not sacred.

If implementation reveals that an existing abstraction is wrong:

1. Explain the problem.
2. Identify the affected boundary.
3. Consider simpler alternatives.
4. Update the architecture if necessary.
5. Update PROJECT.md or an ADR.
6. Then implement the change.

Do not preserve a bad abstraction merely because it was written down earlier.

The goal is a healthy system, not archaeological preservation.

22. Scope Control

If a task contains several possible improvements, prioritize:

1. The requested functionality.
2. Correctness.
3. Existing architecture.
4. Tests.
5. Documentation.
6. Small quality improvements.

Do not silently turn a small task into a repository-wide refactor.

If a larger refactor is genuinely necessary, explain why before doing it.

23. Future Plugin Direction

The long-term plugin architecture may support:

• custom extractors
• custom layouts
• custom styles
• custom renderers
• custom themes

Internal Go interfaces and registries come first.

External plugins, potentially through WebAssembly/WASI, come later.

Do not design the current system around speculative plugin requirements.

First make the internal interfaces good.

24. North Star

When making an architectural decision, preserve this conceptual separation:

DATA
  
MEANING
  
STRUCTURE
  
COMPOSITION
  
GRAPHICS

A Git extractor should not know about pixels.

A renderer should not know about Git.

A theme should not know about Git.

A style should not know that Tokyo Night exists.

A semantic data model should not know what SVG is.

The CLI should orchestrate the system rather than contain the system.

Keep the boundaries clean.

25. Final Rule

Build Veyra as if other developers will eventually extend it.

Because they might.

A future contributor should be able to add:

new data source
new layout
new style
new theme
new renderer

without first understanding the entire codebase.

If adding one feature requires editing twelve unrelated files and three giant switch statements, the architecture is telling us something.

Listen to it.