ZenCODE AGENTS.md

AGENTS.md

Project

• ZenCODE is a Swift 6.3 package whose main executable is zen; it runs on macOS, Linux, and WSL with remote model providers.
• Package.swift is authoritative for the root products, target dependencies, platforms, and build settings. The packages under Sources/Features have their own manifests and are outside the root graph.
• Docs/architecture.md is the compatibility and dependency-direction contract. Preserve public modules, executable names, wire formats, persisted formats, feature identities, and task-graph ownership unless an explicit migration changes them.
• Update CHANGELOG.md whenever a change is user-visible or otherwise warrants a release note.
• Composition starts at Sources/zen/CLI/ZenCODEMain.swift; shared session coordination is centered on AgentCoreSessionRunner, backend state is behind AgentCoreBackend, and direct-tool dispatch is behind DirectToolExecutor.

Build and Validation

• Every root Swift target enables MemberImportVisibility; source files must import the modules that define the members they use.
• Fast shared-runtime compile: swift build --target ZenCODECore.
• Use swift test --filter with the affected Swift Testing suite or test name. The full non-live suite is swift test; the CI and release gates use swift test --no-parallel for process-global lifecycle coverage. Validate Linux behaviour in the container machine described under Linux Validation.
• For memory-engine changes, run swift test --filter MemoryEngineTests; memory-facade changes additionally exercise swift test --filter MemoryServiceTests and swift test --filter MemoryEnhancementTests in ZenCODECoreTests.
• Main release product: swift build -c release --product zen.
• Root commands intentionally do not build optional feature executables. For an optional-feature change, run swift test --filter BundledFeatureCatalogParityTests, validate the package from its own directory according to its Package.swift, and check its installed executable's --list-tools output.
• For sensitive-manifest changes, run swift test --filter SensitiveManifestPermissionsTests; add the affected provider or setup suites when their persistence flows change.
• Package.resolved is tracked and pins CI/release dependencies. Do not update it incidentally; for an intentional dependency change, run swift package resolve, review the exact pins, and include the lockfile.
• Finish source changes with git diff --check. Validate script edits with bash -n Scripts/*.sh; network, provider, and installer executions are dedicated checks rather than routine validation.
• Release tags follow Docs/release.md: strict vX.Y.Z, matching ZenPackageMetadata.version, with the same immutable tag or full commit SHA passed through --ref.