@agentfile/core

Core engine for agentfile — schema validation, YAML loading, template rendering, file generation, manifest ownership tracking, drift detection, and backup utilities.

Use this package if you want to integrate agentfile into your own tooling or build scripts.

Usage

import { generate, validateContract } from '@agentfile/core'

// Validate only
const contract = validateContract({ contractPath: 'ai/contract.yaml' })

// Full generation
const result = generate({
  root:   process.cwd(),
  agents: ['claude', 'cursor'],
  dryRun: false
})

for (const r of result.results) {
  if (r.status === 'ok')      console.log(`Generated ${r.output}`)
  if (r.status === 'error')   console.error(r.error.message)
  if (r.status === 'skipped') console.warn(r.reason)
}

Manifest and backup APIs are also available:

import {
  readManifest,
  writeManifest,
  buildManifest,
  detectDrift,
  captureBackup,
  writeBackup,
  readBackup,
  restoreBackup,
} from '@agentfile/core'

API

generate(options)

Generates agent instruction files for the given agents.

generate({
  root:    string,   // project root
  agents:  string[], // agent names to generate
  dryRun?: boolean   // render without writing files
})
// returns: { results: AgentResult[], success: boolean }

validateContract(options)

Validates contract.yaml against the schema. Throws on invalid input.

validateContract({ contractPath: string })
// returns: Contract

renderTemplate(template, context, skillsFormat?)

Pure template rendering — no I/O.

renderTemplate(template: string, ctx: RenderContext, skillsFormat?: SkillsFormat)
// returns: string

Manifest helpers

Track generated-file ownership and detect drift:

• readManifest(root)
• writeManifest(root, manifest)
• buildManifest(ownedFiles, previous)
• detectDrift(root, manifest)
• staleFiles(previous, current)

Backup and restore generated files:

• captureBackup(root, paths)
• writeBackup(root, entries, tag)
• readBackup(root, tag)
• restoreBackup(root, entries)
• listBackups(root)

Benchmark

Use the built-in benchmark to measure template rendering and dry-run generation performance against a larger synthetic contract:

npm run bench -w packages/core

Links

• Full documentation
• CLI

License

MIT