Add CONTEXT.md for AI agent consumption

[Debashich]

Add a concise CONTEXT.md describing common tkn workflows,

conventions, output formats, and behavioral notes for AI agents.

Fixes #2856

Assisted-by: Claude Sonnet 4.6

Changes

• Add a new CONTEXT.md file documenting common tkn workflows, conventions, output formats, and behavioral guidance for AI agents.

• Ran make check locally. The command fails because of existing lint issues in unrelated files, no new issues were introduced by this documentation only change.

Submitter Checklist

These are the criteria that every PR should meet, please check them off as you
review them:

• Includes tests (if functionality changed/added)
• Run the code checkers with make check
• Regenerate the manpages, docs and go formatting with make generated
• Commit messages follow commit message best practices

See the contribution guide
for more details.

Release Notes

[tekton-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign vinamra28 after the PR has been reviewed.
You can assign the PR to them by writing /assign @vinamra28 in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: Debashich / name: Debashich (e59eb97)

[Debashich]

Hi @vdemeester, this PR is ready for review whenever you have a chance. It implements the CONTEXT.md proposed in #2856. Thanks!

[divyansh42]

Thanks for the PR @Debashich

I have added few comments. Please take a look and let me know what you think about it.

The document covers pipeline, task, pipelinerun, and taskrun. The CLI also supports other resources (customrun, eventlistener, triggerbinding, triggertemplate, clustertriggerbinding, bundle, hub). A brief one-liner acknowledging their existence would prevent agents from assuming these four are the only resources — something like:

Other resource types (eventlistener, triggerbinding, triggertemplate, customrun, clustertriggerbinding) support subsets of list, describe, and delete.

[divyansh42]

It seems export command is not present in the task. Can you please check once?
Ref: https://github.com/tektoncd/cli/blob/main/pkg/cmd/task/task.go#L40

[divyansh42]

It seems --output flag is supported for the start commands which has the option for json output.

[divyansh42]

This can be improved as:

`taskrun logs` has no equivalent of `-E`. To check TaskRun outcome,
inspect `.status.conditions[0].status`:

[divyansh42]

These exit codes (0/1/2) are not the default behavior — they only activate when you pass --exit-with-pipelinerun-error / -E. Without -E, pipelinerun logs exits 0 regardless of run outcome, same as taskrun logs.
An agent scripting around exit codes without passing -E would get silent false-positives (exit 0 on failed runs).

Suggested rewrite:

## Exit Codes

By default, `tkn pipelinerun logs` exits 0 after streaming logs, regardless
of run outcome.

With `--exit-with-pipelinerun-error` (`-E`), the exit code reflects run status:

| Code | Meaning |
|---|---|
| 0 | PipelineRun succeeded |
| 1 | PipelineRun failed |
| 2 | No status conditions available |

`-E` is also available on `pipeline start` when used with `--showlog`.

`taskrun logs` does not support this flag — it always exits 0.

[divyansh42]

Inaccurate scope: --last on describe is only available on run-level commands (pipelinerun describe, taskrun describe) — it does not exist on pipeline describe or task describe. An agent reading this would try tkn pipeline describe --last and get an unknown flag error.

| --last | logs, start, pipelinerun describe, taskrun describe | Target most recent run |

[divyansh42]

Missing an important flag for scripting/agent use: --exit-with-pipelinerun-error / -E, available on pipelinerun logs and pipeline start. This flag is essential for the Exit Codes section to be useful, and an agent doing CI automation would need it.

Consider adding:

--exit-with-pipelinerun-error, -E | pipelinerun logs, pipeline start | Exit with run status (0=success, 1=failed, 2=unknown)