Skip to content

Ship a CONTEXT.md for AI agent consumption #2856

@vdemeester

Description

@vdemeester

Summary

Following the pattern from gws CLI, ship a CONTEXT.md (or AGENTS.md) file that AI agents can read to understand tkn conventions, common patterns, and pitfalls.

Motivation

This is the highest value-to-effort ratio improvement. No code changes — just a markdown file that agents load as context. It teaches agents:

  • Which commands to use for common tasks
  • Output format conventions
  • How to avoid common mistakes
  • Preferred patterns (e.g., use --last for most recent run)

Example Content

# tkn CLI — Agent Context

## Common Patterns
- List pipeline runs: `tkn pipelinerun list --output json`
- Get logs for latest run: `tkn pipelinerun logs --last`
- Start a pipeline: `tkn pipeline start my-pipeline --param key=value`
- Check run status: `tkn pipelinerun describe my-run --output json`

## Conventions
- Use `--output json` for machine-readable output
- Use `--last` to reference the most recent run
- Logs stream to stdout, status messages to stderr
- Use `--namespace` or set KUBECONFIG context

## Pitfalls
- `tkn pipeline start` is interactive by default — always pass all params explicitly
- `delete` commands require `--force` to skip confirmation

Acceptance Criteria

  • Ship CONTEXT.md (or AGENTS.md) in the repo root
  • Cover common workflows, conventions, and pitfalls
  • Keep it concise (agents pay per token)

/kind feature

Metadata

Metadata

Assignees

No one assigned

    Labels

    kind/featureCategorizes issue or PR as related to a new feature.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions