Contributor Context

Kyku provides an AGENTS.md at the repository root following the agent context file convention. This file contains the patterns, rules, and gotchas learned during development — structured specifically for AI agents and contributors.

What is AGENTS.md?

AGENTS.md is a convention where projects place context files at the repository root that AI coding agents can read to understand:

• Project conventions and patterns
• Rules for making changes
• Provider-specific gotchas
• Implementation checklists

Kyku’s AGENTS.md Structure

The file at /AGENTS.md covers these sections:

Section	What It Covers
1. Adding a New Resource Type	All files that must be touched (checklist)
1.1 Adding a New Provider	Step-by-step provider creation checklist
2. Dependency Graph	Edge detection rules, graph verification
3. State vs Cloud — Planner Behavior	When the planner queries cloud APIs
4. Provider ID Management	Kyku UUIDs vs cloud-native IDs
5. Config Key Alignment	read() must match resourceToConfig()
6. Idempotent Create	Checking existence before creating
7. Destroy: Retry + Verify	Destroy retry logic with backoff
8. Use Label Selectors	Preferring labels over server IDs
9. Module Resolution	Dynamic import rules
10. Progress Display	ANSI cursor control conventions
11. Provider-Specific Gotchas	Per-provider pitfalls and fixes
12. TypeScript Patterns	Resource classes, generics, DOM lib
13. Testing & Verification	Build order, typecheck, real-API testing
14. Deploy Prefix	Auto-generated resource name prefixing
15. Plan Save/Load	Plan serialization to JSON
16. State Locking	File-based lock mechanics
17. Import Command	Resource adoption workflow
18. Hetzner DNS + S3 / DO Spaces	Separate API credentials

Key Patterns from AGENTS.md

Adding a New Provider Checklist

Step	Location	Action
1	packages/types/src/config.ts	Add provider column to INSTANCE_TYPE_MAP and IMAGE_MAP
2	packages/core/src/auth/index.ts	Add to AuthConfig.provider union
3	packages/cli/src/commands/provider-factory.ts	Register providerName: '@kykucloud/<package>'
4	packages/cli/package.json	Add "@kykucloud/<package>": "workspace:*"
5	Create packages/<package>/	Copy package.json + tsconfig.json
6	src/client.ts	REST or SDK client
7	src/mappings.ts	Instance/image/region mapping functions
8	src/utils.ts	Name normalization, tag helpers
9	src/resources/*.ts	One manager per resource type
10	src/provider.ts	Provider class implementing Provider
11	src/index.ts	Export provider and public APIs
12	Root tsconfig.json	Ensure "lib": ["ES2022", "DOM"]
13	Build order	Rebuild types → core → cli

Critical Contract: Config Key Alignment

The most common source of bugs is read() and create() returning different config shapes. Both must return config objects with identical property names and types:

// read() returns:
config: { cidr: '10.0.0.0/16', region: 'us-east', distributeAcrossAzs: 2 }

// create() must return SAME keys:
config: { cidr: '10.0.0.0/16', region: 'us-east', distributeAcrossAzs: 2 }

Mismatches cause spurious update plans after apply.

Provider Naming Convention

Class name must be PascalCaseProvider (e.g., DigitaloceanProvider, HetznerProvider). The CLI factory constructs the class name as ${providerName.charAt(0).toUpperCase() + providerName.slice(1)}Provider.

Dependency Rule

Use object references (not string IDs) for dependencies:

// ✅ Creates dependency edge
vm.network = myVpc;

// ❌ No dependency created
vm.network = "vpc-abc123";

Reading AGENTS.md

When contributing to Kyku:

Read AGENTS.md before making changes to understand conventions.
- For new providers: use section 1.1 checklist
- For new resources: use section 1 checklist
- For provider-specific code: check section 11 gotchas

How This Page is Generated

This page mirrors the root AGENTS.md file in the repository. The source of truth is the file at the repository root — this page is a reference summary for contributors working through the docs site.