Add agentic workflows context files by jkhelil · Pull Request #3387 · tektoncd/operator

jkhelil · 2026-05-04T11:24:38Z

Changes

Prepare the Tekton Operator repository for agentic workflows as part of SRVKP-11820.

Fix: align lint with CI and drop unused constants
Makefile: add a version check so the local golangci-lint binary is reinstalled when it diverges from the version pinned in ci.yaml (v2.7.2); add a PKG variable to lint-go so agents can lint a single package quickly (make lint-go PKG=./pkg/reconciler/kubernetes/tektonchain/...)
Remove unused resourceKind constants in tektonchain, tektonpipeline, and tektontrigger reconcilers that caused lint failures locally (pre-existing issues invisible to CI due to --new-from-merge-base)
Docs: add AGENTS.md and project skills
AGENTS.md: minimal agent-oriented context file covering single-command build/test, key conventions (InstallerSet types with cluster-observed naming, platform split, Knative runtime), architecture, and skill triggers. Confirmed acceptable in the upstream working group (29 April 2026)
.claude/skills/: commit-message and release-notes skills adapted from pipelines-as-code (PAC-specific references updated for this project)
.gitlint + make gitlint target for post-commit message validation

Submitter Checklist

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

Run make test lint before submitting a PR
Includes tests (if functionality changed/added)
Includes docs (if user facing)
Commit messages follow commit message best practices

See the contribution guide for more details.

Release Notes

NONE

tekton-robot · 2026-05-04T11:24:42Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please ask for approval from jkhelil after the PR has been reviewed.

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

jkhelil · 2026-05-04T11:54:23Z

/kind/cleanup

vdemeester

Few questions, otherwise looks good. The 'AGENTS.md` is a bit bigger than 60 lines but I feel it is needed 👼🏼

vdemeester · 2026-05-05T09:29:16Z

+`knative.dev/pkg/apis` (`condSet.Manage(status).MarkTrue/MarkFalse`). Do not use
+`controller-runtime` — it is not in this project.
+
+**API layout** — all CRD types live in `pkg/apis/operator/v1alpha1/`. Each component


Do we want to specify the version here ? (aka pkg/apis/operator/ should be good enough, isn't it ?)

vdemeester · 2026-05-05T09:29:56Z

+
+---
+
+## PR Conventions


We should have an entry stating that pull request have to follow the pull request template.

vdemeester · 2026-05-05T09:32:06Z

+
+For complete detection logic, see `references/footer-detection.md`.
+
+### Assisted-by


Naive question, Assisted-by or Co-authored ?

“Co-authored” seems to better reflect what actually happen.

This is subjective, but I lean towards Assisted-By. To me, authorship implies ownership and accountability. This is a broader discussion in the Open Source community though, e.g. in this VSCode issue, and was a recent point of discussion by the Linux kernel maintainers as well (who adopted "Assisted-by" in their contribution guidelines)

Yeah I saw that as well, I may lean toward Assisted-by for most cases I guess, we can / should accept both though.. Maybe it depends on the involvement of the agent in the commit 😅

looks like a chicken egg debate :) but yes lets use Assisted-By across all projects

A bit late to the discussion, sharing my thoughts nevertheless.
While I personally prefer Assisted-by as it more accurately describes the relationship, Co-authored-by has the practical advantage that GitHub natively recognizes it and surfaces it directly in the UI, making it immediately visible whether AI was involved - this built-in visibility is a meaningful benefit over what is treated as plain text.
Commit 67cfa52 - co-authored-by

Commit 32820cb - asssited-by

Interesting. From what I see, it only shows it on the commit and not on the PR, which is less visible IMO, at least the way I interact with PRs.
Anyway, I like Assisted-by: more.

True, it is only visible for commits. On a PR, it looks like this to show AI attribution

Using the same commits as above

vdemeester · 2026-05-05T09:37:41Z

@@ -0,0 +1,554 @@
+# Author Detection and Footer Generation
+
+Complete guide for detecting author information and generating required commit footers.


nit: these are called trailer(s) in the git realm (there is even git-interpret-trailers command to interact with it)

aThorp96

The suggestion for the (I assume, copy paste) error highlights an important point: AGENTS.md might be repository specific but commit types, trailers, release notes format, etc, are all pretty much standard across all of Tekton. If a 2k lines of skills has to be included in every repository it could result in maintenance issues as style guides change or skills need to be refined. Can the skill reference a shared skill in the plumbing more central repo? I think plumbing because it's vendored in every(?) repo, so an agent doesn't need to remotely fetch the skill reference/context.

aThorp96 · 2026-05-07T13:13:32Z

@@ -0,0 +1,269 @@
+# Commit Types Reference
+
+Complete reference for conventional commit types used in the Pipelines-as-Code project.


Suggested change

Complete reference for conventional commit types used in the Pipelines-as-Code project.

Complete reference for conventional commit types used in the Tekton Operator project.

Yes indeed, this skill is copy paste from pac, i wanted to have an uniformed shared skill for commit and release note, and +1 to have a shared thing

jkhelil · 2026-05-21T07:26:34Z

@vdemeester @anithapriyanatarajan can you have another look here please ?

anithapriyanatarajan · 2026-05-21T14:09:07Z

+```markdown
+* **Bold title:** One-sentence description of the change.
+  * Link: <PR_OR_COMMIT_URL>
+  * Jira: [SRVKP-XXXX](https://issues.redhat.com/browse/SRVKP-XXXX)


@jkhelil Do we need JIRA reference upstream?

+1 to remove the Jira references. I assume it's coming from PaC from the time it was downstream only. Non Red Hat contributions won't have srvkp issue anyway. Dependabot PRs as well.

jkhelil · 2026-05-29T06:17:50Z

➜  operator git:(SRVKP-11820) echo "y" | docker run --rm -i \
  -v tektoncd/operator:/repo:ro \
  -v ~/agentready-reports:/reports \
  ghcr.io/ambient-code/agentready:latest assess /repo --output-dir /reports
⚠️  Warning: Large repository detected (14,309 files). Assessment may take several minutes. Continue? [y/N]: y
Subprocess error: [Errno 2] No such file or directory: 'gocyclo'

Assessment complete!
  Score: 64.6/100 (Silver)
  Assessed: 26
  Skipped: 7
  Total: 33
  Duration: 164.4s

Assessment Results:
----------------------------------------------------------------------------------------------------
Test Name                           Test Result    Notes
----------------------------------------------------------------------------------------------------
architecture_decisions              ❌ FAIL         no ADR directory (need: ADR directory with deci...
branch_protection                   ⏭️ NOT_APPLICABLE Requires GitHub API integration for branch prot...
ci_quality_gates                    ❌ FAIL         missing quality gates (need: CI with lint + tes...
claude_md_file                      ✅ PASS         100/100
code_smells                         ❌ FAIL         golangci-lint (need: ≥60% of applicable linters...
concise_documentation               ❌ FAIL         79 lines, 7 headings, 12 bullets (need: <500 li...
container_setup                     ⏭️ NOT_APPLICABLE Not applicable to ['Markdown', 'YAML', 'Shell',...
conventional_commits                ❌ FAIL         not configured (need: configured)
cyclomatic_complexity               ⏭️ SKIPPED     Missing tool: gocyclo
dbt_data_tests                      ⏭️ NOT_APPLICABLE Not applicable to ['Markdown', 'YAML', 'Shell',...
dbt_model_documentation             ⏭️ NOT_APPLICABLE Not applicable to ['Markdown', 'YAML', 'Shell',...
dbt_project_config                  ⏭️ NOT_APPLICABLE Not applicable to ['Markdown', 'YAML', 'Shell',...
dbt_project_structure               ⏭️ NOT_APPLICABLE Not applicable to ['Markdown', 'YAML', 'Shell',...
dependency_security                 ✅ PASS         60/100
design_intent                       ❌ FAIL         not documented (need: design docs with precondi...
deterministic_enforcement           ❌ FAIL         not configured (need: configured)
file_size_limits                    ❌ FAIL         438 huge, 655 large out of 11903 (need: <5% fil...
gitignore_completeness              ❌ FAIL         6/19 patterns (need: ≥70% of language-specific ...
inline_documentation                ❌ FAIL         59.1% (need: ≥80%)
issue_pr_templates                  ❌ FAIL         PR:True, Issues:0 (need: PR template + ≥2 issue...
lock_files                          ✅ PASS         100/100
one_command_setup                   ❌ FAIL         multi-step setup (need: single command)
openapi_specs                       ❌ FAIL         OpenAPI 2.0 (need: OpenAPI 3.x with paths and s...
pattern_references                  ✅ PASS         60/100
progressive_disclosure              ✅ PASS         70/100
readme_structure                    ❌ FAIL         2/3 sections (need: 3/3 sections)
repomix_config                      ❌ FAIL         not configured (need: configured)
separation_of_concerns              ✅ PASS         100/100
single_file_verification            ❌ FAIL         not documented (need: single-file lint + type-c...
standard_layout                     ✅ PASS         95/100
structured_logging                  ✅ PASS         100/100
test_execution                      ✅ PASS         100/100
type_annotations                    ✅ PASS         85/100
----------------------------------------------------------------------------------------------------

Reports generated:
  JSON: /reports/assessment-20260529-060739.json
  HTML: /reports/report-20260529-060739.html
  Markdown: /reports/report-20260529-060739.md

enarha

We use symlinks, CLAUDE.md -> AGENTS.md and that works on Linux and Mac and GitHub properly renders it, but it won't work on Windows. A simple workaround is to document for Windows users to use core.symlinks=true e.g. git clone -c core.symlinks=true https://github.com/tektoncd/operator.git.
Another thing is the vendor neutral locations. We have CLAUDE.md pointing to AGENTS.md which is fine. For the skills though we have .agents/skills pointing to .claude/skills instead the other way around. Not crucial, but it's an easy fix.

enarha · 2026-05-27T15:43:01Z

+
+- Fixing crashes or errors
+- Resolving incorrect behavior
+- Patching security vulnerabilities


No strictly a bug fix. As discussed at one of the upstream calls, we agreed to introduce few new labels, we can have one for security fixes. IMO we better drop this now than forget about it and create ambiguity when we introduce a proper security specific label.

enarha · 2026-05-27T15:45:54Z

+**Examples**:
+
+- `fix(controller): resolve pipeline race condition`
+- `fix(SRVKP-456): correct webhook payload parsing`


As discussed further down, if agreed, we should avoid SRVKP references. It could be nice if we can include GitHub specific format and point to GitHub issues, so they are automatically closed when the PR is merged.

enarha · 2026-05-27T15:47:22Z

+- `refactor(SRVKP-234): reorganize package structure`
+
+**When to use**:
+


We might add an extra line about not changing existing behavior.

enarha · 2026-05-27T15:54:18Z

+
+- Makefile changes
+- Docker/container build changes
+- Dependency management (major)


This sounds vague to me. Instead we might focus on golang version and tooling e.g. updating go version in go.mod.

enarha · 2026-05-27T16:04:07Z

+
+**When to use**:
+
+- GitHub Actions updates


Isn't it more straightforward if we say changes of .github/workflows/ directory?
We might also include as a separate entry changes of the .tekton directory.

- Makefile: reinstall golangci-lint when local version diverges from ci.yaml (v2.7.2) - Makefile: add PKG variable to lint-go for single-package lint - Remove unused resourceKind constants in tektonchain, tektonpipeline, and tektontrigger reconcilers Signed-off-by: Jawed khelil <jkhelil@redhat.com> Assisted-by: Claude Sonnet 4.6 (via Cursor)

- AGENTS.md: agent-oriented context for build, test, conventions, and architecture - .agents/skills/: commit-message and release-notes skills - .claude/skills -> .agents/skills, CLAUDE.md -> AGENTS.md - .gitlint: dependabot exclusion Signed-off-by: Jawed khelil <jkhelil@redhat.com> Assisted-by: Claude Sonnet 4.6 (via Cursor)

jkhelil · 2026-06-03T12:44:46Z

/retest

tekton-robot added the release-note-none Denotes a PR that doesnt merit a release note. label May 4, 2026

tekton-robot requested review from khrm and mbpavan May 4, 2026 11:24

tekton-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label May 4, 2026

jkhelil force-pushed the SRVKP-11820 branch 2 times, most recently from 82e0bf0 to c44001f Compare May 4, 2026 14:16

vdemeester reviewed May 5, 2026

View reviewed changes

jkhelil force-pushed the SRVKP-11820 branch from c44001f to 57c581c Compare May 7, 2026 08:14

aThorp96 reviewed May 7, 2026

View reviewed changes

jkhelil force-pushed the SRVKP-11820 branch from 57c581c to 7e8b0b1 Compare May 11, 2026 06:30

jkhelil force-pushed the SRVKP-11820 branch from 7e8b0b1 to 59ea6d6 Compare May 21, 2026 11:48

anithapriyanatarajan reviewed May 21, 2026

View reviewed changes

jkhelil force-pushed the SRVKP-11820 branch from 59ea6d6 to 85df7ac Compare May 28, 2026 08:42

ab-ghosh mentioned this pull request May 28, 2026

docs: add agentic workflow context files tektoncd/catalog#1375

Open

12 tasks

jkhelil force-pushed the SRVKP-11820 branch from 85df7ac to 8f2bd34 Compare May 29, 2026 05:53

enarha reviewed May 31, 2026

View reviewed changes

jkhelil force-pushed the SRVKP-11820 branch from 8f2bd34 to 47002b4 Compare June 1, 2026 05:00

jkhelil force-pushed the SRVKP-11820 branch from 47002b4 to 0fdd9a2 Compare June 3, 2026 10:44

jkhelil force-pushed the SRVKP-11820 branch from 0fdd9a2 to 6126b18 Compare June 3, 2026 10:47

This was referenced Jun 3, 2026

chore: add AGENTS.md and AI skills for agentic workflows openshift-pipelines/manual-approval-gate#986

Open

Add agentic workflow context files tektoncd/cli#2890

Open


		For complete detection logic, see `references/footer-detection.md`.

		### Assisted-by

		@@ -0,0 +1,554 @@
		# Author Detection and Footer Generation

		Complete guide for detecting author information and generating required commit footers.

		@@ -0,0 +1,269 @@
		# Commit Types Reference

		Complete reference for conventional commit types used in the Pipelines-as-Code project.

		- `refactor(SRVKP-234): reorganize package structure`

		When to use:


		---

		## PR Conventions

Conversation

jkhelil commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Submitter Checklist

Release Notes

Uh oh!

tekton-robot commented May 4, 2026

Uh oh!

jkhelil commented May 4, 2026

Uh oh!

vdemeester left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aThorp96 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkhelil commented May 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkhelil commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

enarha left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkhelil commented Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jkhelil commented May 4, 2026 •

edited

Loading

jkhelil commented May 29, 2026 •

edited

Loading