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

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.

Fix two issues found during agentic workflow setup: - Makefile: add version check so local golangci-lint binary is reinstalled when it diverges from the version in ci.yaml (v2.7.2); add PKG variable to lint-go for fast single-package iteration - Remove unused resourceKind constants in tektonchain, tektonpipeline, and tektontrigger reconcilers that caused lint failures locally Signed-off-by: Jawed khelil <jkhelil@redhat.com> Assisted-by: Claude Sonnet 4.6 (via Cursor) Co-authored-by: Cursor <cursoragent@cursor.com>

Adds tooling and documentation to support agentic workflows: - AGENTS.md: minimal context file following agent-readiness principles (single-command tests, fast single-package lint, conventions, architecture, InstallerSet details, skills) - .claude/skills/: commit-message and release-notes skills adapted from pipelines-as-code; PAC-specific references updated for the Tekton Operator project - .agents/skills/: same skills in Cursor agent format - .gitlint: commit message linting config with dependabot exclusion Signed-off-by: Jawed khelil <jkhelil@redhat.com> Assisted-by: Claude Sonnet 4.6 (via Cursor) Co-authored-by: Cursor <cursoragent@cursor.com>

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

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

jkhelil and others added 2 commits May 28, 2026 10:50

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


		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.


		---

		## 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jkhelil commented May 4, 2026 •

edited

Loading

jkhelil commented May 29, 2026 •

edited

Loading