Skip to content

context.md

Latest commit

 

History

History
141 lines (90 loc) · 4.63 KB

context.md

File metadata and controls

141 lines (90 loc) · 4.63 KB

Context

.rabbit/context.yaml is the structured repo contract produced by dev.kit repo.

It should answer: what can be fetched from this repo programmatically, what was detected, what is missing, and what other repos or workflows this repo depends on.

Role

context.yaml is the machine-friendly map of the repository. It is not the place for agent policy, step-by-step behavior, or prompt-style instructions.

Its boundary is best understood as two layers combined into one artifact:

  • base repo context signals
  • deterministic tracing and mapping built from those signals

Use it for facts such as:

  • repo identity
  • priority refs
  • canonical commands
  • detected gaps
  • manifests that define behavior
  • traced dependencies and where they are used
  • GitHub-derived repo experience that can be serialized cleanly

How It Is Produced

Run:

dev.kit repo

That command inspects repo-native signals, resolves what it can deterministically, and writes .rabbit/context.yaml.

If the file is missing, dev.kit agent can generate it first before writing AGENTS.md.

What Feeds It

context.yaml comes from evidence dev.kit can fetch or derive from the repo and its configured integrations:

  • README and docs
  • manifests like package.json, composer.json, Dockerfile
  • .github/workflows/*
  • deploy.yml
  • tests and command surfaces
  • YAML config catalogs in src/configs/
  • GitHub repo signals when available

The important split is:

  • signals are the raw repo-facing inputs
  • tracing and mapping are the deterministic transforms dev.kit performs on top of them

Examples of tracing and mapping include:

  • detecting canonical verify, build, and run commands
  • mapping reusable workflows to upstream repos
  • mapping Docker images to likely source repos
  • mapping versioned YAML contracts to upstream modules or repos
  • mapping dependencies to the local files that use them

The key boundary is simple: if dev.kit can detect it, trace it, or serialize it, it belongs here.

Main Sections

The generated file in this repo currently includes:

  • repo
  • refs
  • commands
  • gaps
  • dependencies
  • manifests
  • lessons

Depending on available integrations, it may also include GitHub-derived data. GitHub belongs here only when it can be fetched and serialized as repo experience data. It does not replace the repo contract.

Examples of GitHub-derived data that fit here:

  • open pull requests
  • recent pull request history
  • linked issue references
  • repo URLs that anchor the current work

Those belong here because they can be serialized as current repo experience. Review decisions, step-by-step agent behavior, and how to respond to live findings still belong in AGENTS.md.

What Each Section Means

repo identifies the repository through values such as name, archetype, and profile.

refs is the priority reading list. It tells an agent or tool which files and directories matter first.

This is the only place refs should live. AGENTS.md should point to context.yaml, not repeat the ref list.

commands is the detected execution surface, such as verify, build, and run.

dependencies is cross-repo tracing. Each entry explains what external repo, package, or workflow was referenced and which local files use it.

gaps is a checklist of missing or partial factors dev.kit could detect programmatically.

manifests lists the config files that define repo behavior. In dev.kit, these are first-class interfaces.

lessons links prior session artifacts produced by dev.kit learn.

What Does Not Belong Here

context.yaml should not try to be the final agent prompt.

It is not where you explain:

  • how an agent should interpret ambiguity
  • how an agent should sequence work for a user
  • how an agent should balance repo context against current task context
  • how an agent should loop on bot review comments
  • how an agent should decide between local verification and GitHub workflow verification

That layer belongs in AGENTS.md.

Efficiency Goal

The point of context.yaml is compression without losing structure.

It should let an agent answer questions like:

  • What commands exist?
  • What docs and manifests matter first?
  • What repo signals were used?
  • What dependencies are real, and where are they used?
  • Which engineering factors are missing?
  • Which repo facts and traced signals are already available?

If that data is available in context.yaml, the agent does not need to rediscover it by scanning.

JSON Contract

For automation, the repo command JSON surface is defined by:

  • src/templates/repo.json

That JSON output and .rabbit/context.yaml are the stable structured surfaces from dev.kit repo.