docs: add agentic workflow context files

.agents/skills

@@ -0,0 +1 @@
+../.claude/skills

.claude/.gitignore

@@ -0,0 +1 @@
+*.local.json

.claude/rules/task-yaml.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "task/**/*.yaml"
+  - "stepaction/**/*.yaml"
+  - "pipeline/**/*.yaml"
+---
+
+# Task YAML Rules
+
+- Never use `$(params.*)` inside `script` blocks — pass via `env` or `args`
+- Reference images by digest (`@sha256:...`), not by tag
+- Run steps as non-root unless explicitly required
+- Include `app.kubernetes.io/version` label matching the directory version
+- Include `tekton.dev/pipelines.minVersion` annotation
+- Include `spec.description` with one-line summary + detailed paragraph
+- Provide default values for parameters wherever reasonable
+- Use `set -e` (or `set -euo pipefail`) in bash scripts

.claude/rules/test-infra.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "test/**"
+  - "hack/**"
+  - "task/**/tests/**"
+---
+
+# Test Infrastructure Rules
+
+- Hook scripts (`pre-apply-task-hook.sh`, `pre-apply-taskrun-hook.sh`) are
+  sourced via `source`, so they can export environment variables
+- Use helper functions: `add_sidecar_registry`, `add_sidecar_secure_registry`,
+  `add_task`
+- For external API mocking, place fixture rules in `tests/fixtures/` and
+  override the API URL parameter to `http://localhost:8080`
+- Test YAMLs in `tests/` are applied in a random namespace — do not hardcode
+  namespace names
+- CI only tests tasks modified in the PR unless `TEST_RUN_ALL_TESTS` is set

.claude/skills/code-review/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: code-review
+description: >-
+  Review a pull request or code change in tektoncd/catalog. Use when asked to
+  review a PR, evaluate a diff, or assess code quality. Applies Tekton community
+  standards, TEP-0003 catalog organization, task authoring recommendations, and
+  catalog-specific conventions (directory structure, metadata, tests).
+license: Apache-2.0
+metadata:
+  project: tekton-catalog
+allowed-tools: Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(yamllint:*)
+---
+
+# Code Review
+
+tektoncd/catalog follows [Tekton community review standards](https://github.com/tektoncd/community/blob/main/standards.md)
+and [TEP-0003 Catalog Organization](https://github.com/tektoncd/community/blob/master/teps/0003-tekton-catalog-organization.md).
+
+## Review Checklist
+
+### Catalog Organization (TEP-0003)
+
+- [ ] File path follows `<kind>/<name>/<version>/name.yaml` (kind = task, stepaction, or pipeline)
+- [ ] Resource YAML file name matches the resource name
+- [ ] `README.md` exists at `<kind>/<name>/<version>/README.md`
+- [ ] `OWNERS` file exists at `<kind>/<name>/OWNERS` (or version-level)
+- [ ] Version directory name is a valid semver-like format (e.g. `0.1`, `0.2`)
+
+### Mandatory Metadata
+
+- [ ] Label `app.kubernetes.io/version` matches the directory version
+- [ ] Annotation `tekton.dev/pipelines.minVersion` is present and accurate
+- [ ] Annotation `tekton.dev/categories` is present (e.g. Git, Build, Deploy, CLI)
+- [ ] Annotation `tekton.dev/tags` is present with comma-separated tags
+- [ ] Annotation `tekton.dev/displayName` is present (optional but recommended)
+- [ ] Annotation `tekton.dev/platforms` lists supported platforms (optional)
+- [ ] `spec.description` follows the convention: one-line summary followed by
+  detailed paragraph(s)
+
+### Task Authoring Quality
+
+- [ ] **No `$(params.*)` interpolation inside `script` blocks** — this is a
+  security vulnerability (code injection) and reliability issue. Parameters
+  must be passed via `env` or `args` and referenced as `$ENV_VAR` or `$1`.
+  See [recommendations.md](../../../recommendations.md)
+- [ ] Images are referenced by digest (`image@sha256:...`) where possible,
+  not by mutable tags (`:latest`)
+- [ ] Steps run as non-root and non-privileged unless explicitly required.
+  If root is needed, use `securityContext.runAsUser: 0` explicitly
+- [ ] Parameters have default values where reasonable
+- [ ] Workspaces have clear descriptions. Tasks should use **at most one
+  writeable workspace** (Tekton recommendation)
+- [ ] Script steps use `#!/usr/bin/env bash` (or appropriate shebang)
+  with `set -e` for error handling
+- [ ] No hardcoded values that should be parameters
+- [ ] Results are documented and used only for small data (commit SHAs,
+  branch names). Large data should use a Workspace instead
+- [ ] Tasks are idempotent — safe to re-execute
+- [ ] `tekton.dev/pipelines.minVersion` is set to the lowest version that
+  supports the features used (portability across Pipeline versions)
+
+### YAML Quality
+
+- [ ] `yamllint` passes with the project's `.yamllint` config
+- [ ] No trailing whitespace
+- [ ] Consistent indentation (2 spaces)
+- [ ] Proper quoting of strings where needed
+
+### Testing
+
+- [ ] New tasks or changed functionality include tests in `tests/` directory
+- [ ] Test directory contains `run.yaml` (TaskRun or PipelineRun)
+- [ ] Pre-apply hook scripts (`pre-apply-task-hook.sh`,
+  `pre-apply-taskrun-hook.sh`) are used where setup is needed
+- [ ] For tasks calling external APIs, fixtures are provided in
+  `tests/fixtures/` for go-rest-api-test
+- [ ] Tests do not depend on external services without fixture mocking
+
+### New Version Workflow
+
+- [ ] If bumping a version (e.g. 0.1 to 0.2), the old version was
+  copied first in a separate commit, then modified in a subsequent commit
+- [ ] Changes from the previous version are clearly visible in the diff
+  (not buried in a full copy)
+
+### Documentation
+
+- [ ] `README.md` documents all parameters with types and defaults
+- [ ] `README.md` documents all workspaces
+- [ ] `README.md` documents all results (if any)
+- [ ] `README.md` includes usage example(s)
+- [ ] `samples/` directory contains example TaskRun/PipelineRun YAMLs
+
+### Security
+
+- [ ] **No `$(params.*)` interpolation in scripts** — critical injection risk
+  (repeat check — this is the most common security issue in catalog tasks)
+- [ ] No secrets or credentials hardcoded in YAML
+- [ ] Sensitive data passed via Kubernetes Secrets or workspaces
+- [ ] Container images come from trusted registries
+- [ ] No use of `privileged: true` without justification
+
+## What to Approve
+
+Approve when:
+- All checklist items pass
+- Tests cover the changed behavior
+- The change is focused (one concern per PR)
+- Commit messages follow [Tekton commit conventions](https://github.com/tektoncd/community/blob/main/standards.md#commit-messages)
+- New version workflow is followed (copy + modify in separate commits)
+
+## What to Block
+
+Block (request changes) when:
+- `$(params.*)` is used inside `script` blocks (injection vulnerability)
+- TEP-0003 structure is not followed
+- Mandatory metadata labels/annotations are missing
+- Images use mutable tags without justification
+- Tests are missing for new or changed tasks
+- Security issues (hardcoded secrets, unnecessary privileges)
+- `yamllint` fails
+- Version copy and modifications are squashed into a single commit

.claude/skills/commit-message/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: commit-message
+description: This skill should be used when the user asks to "create a commit", "generate commit message", "commit changes", "make a commit", mentions "conventional commits", or discusses commit message formatting. Provides guided workflow for creating properly formatted commit messages with line length validation and required trailers.
+version: 0.3.0
+---
+
+# Commit Messages for tektoncd/catalog
+
+This skill covers only catalog-specific commit conventions. Standard
+conventional commits format is assumed as prior knowledge.
+
+## Scope Rules (Catalog-Specific)
+
+Derive scope from staged file paths:
+
+| File pattern | Scope | Example |
+|---|---|---|
+| `task/<name>/*` | task name | `feat(git-clone): add depth param` |
+| `stepaction/<name>/*` | stepaction name | `feat(git-clone): add stepaction` |
+| `pipeline/<name>/*` | pipeline name | `fix(buildpacks): fix workspace` |
+| `test/*` | `test` or resource name | `test(git-clone): add SSH e2e` |
+| `hack/*` | `hack` or script name | `fix(setup-kind): update K8s ver` |
+| `.github/workflows/*` | `ci` | `ci(github): add matrix version` |
+| Root files | filename | `docs(CONTRIBUTING): update` |
+
+If files span multiple resources, ask the user.
+
+## Required Trailer
+
+Every commit **must** include this trailer (tektoncd upstream requirement):
+
+```text
+Signed-off-by: Full Name <email@example.com>
+```
+
+**Signed-off-by** certifies the Developer Certificate of Origin (DCO).
+Detect from `$GIT_AUTHOR_NAME`/`$GIT_AUTHOR_EMAIL` first, then
+`git config user.name`/`git config user.email`. Ask user if neither is set.
+
+## Optional Trailer (AI-Assisted Work)
+
+When a commit is authored with AI assistance, add:
+
+```text
+Assisted-by: Claude Sonnet 4 (via Claude Code)
+```
+
+Use the actual model name. This is not a Tekton requirement — it is
+optional attribution for AI-assisted contributions.
+
+## Version Copy Convention
+
+When a task is copied from version X to Y, commit the copy separately:
+
+```text
+chore(git-clone): copy task from 0.9 to 0.10
+
+Signed-off-by: ...
+```
+
+Then make changes in a follow-up commit with `feat`/`fix`/etc. type.
+This is critical for clean diffs during review.
+
+## Gitlint Enforcement
+
+The project uses `.gitlint` with these rules:
+- Subject hard limit: 72 chars (target 50)
+- Body wrap: 72 chars per line
+- No `WIP`/`TODO` in subject
+- `body-is-missing` is ignored (body optional)
+
+## Workflow
+
+1. `git diff --cached --name-only` to determine scope
+2. Generate message with proper type and scope
+3. Add required Signed-off-by; add Assisted-by when AI-assisted
+4. **Display to user and wait for confirmation before committing**
+5. Use heredoc format: `git commit -m "$(cat <<'EOF' ... EOF)"`