Add agentic workflows context files

Agent configuration goes to generic files: AGENTS.md and .agents/.
CLAUDE.md is a symlink to AGENTS.md so all agents share the same context.

Includes:
- AGENTS.md: project overview, build/test commands, architecture, pattern references
- .agents/guidelines.md: generic LLM coding guidelines
- .claude/skills: symlink to .agents/skills for repo-local skills
- .pre-commit-config.yaml: pre-commit hooks for Go formatting and linting
- docs/adr/: architecture decision records linking to TEPs and capturing core invariants
- .gitignore: add coverage files, editor swap files, agentready artifacts

AgentReady assessment: 77.6/100 (Gold, up from 58.4/100 Bronze)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

.agents/guidelines.md

@@ -0,0 +1,66 @@
+# Coding Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- If you disagree with a specific decision from the user, explain why. Ask the user to confirm their decision.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, typos or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

.agents/skills/.gitkeep

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

.claude/skills

@@ -51,3 +51,19 @@ cmd/*/kodata/source.tar.gz
 # Temporary GOPATH used during code gen if user's Tekton checkout is
 # not already in GOPATH.
 .gopath
+
+# AgentReady assessment artifacts
+.agentready/
+.agentready-config.yaml
+
+# Coverage and test output
+cover.out
+coverage.txt
+coverage_raw.out
+
+# Editor swap files
+*.swo
+*.swp
+
+# macOS
+.DS_Store

.gitignore

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-json
+      - id: detect-private-key
+
+  - repo: https://github.com/dnephin/pre-commit-golang
+    rev: v0.5.1
+    hooks:
+      - id: go-fmt
+      - id: go-imports
+      - id: go-vet
+      - id: go-unit-tests
+
+  - repo: https://github.com/golangci/golangci-lint
+    rev: v2.8.0
+    hooks:
+      - id: golangci-lint

.pre-commit-config.yaml

@@ -0,0 +1,141 @@
+# Tekton Triggers
+
+Event-driven CI/CD controller for Kubernetes. Listens for events (GitHub webhooks, etc.),
+maps them to Tekton PipelineRuns/TaskRuns via TriggerBindings and TriggerTemplates, and
+creates Kubernetes resources through EventListeners.
+
+**Behavioral guidelines**: See [.agents/guidelines.md](./.agents/guidelines.md) for generic coding principles.
+
+---
+
+## Build & Test Commands
+
+```bash
+# Build all binaries
+make all
+
+# Build specific component
+make bin/controller
+make bin/eventlistenersink
+make bin/interceptors
+make bin/webhook
+make bin/tkn-triggers
+
+# Unit tests — no cluster required
+make test-unit
+
+# End-to-end tests — requires a running cluster
+make test-e2e
+
+# YAML tests
+make test-yamls
+
+# Format code — required before PR submission
+make fmt
+
+# Lint — must pass before every PR
+make golangci-lint
+
+# Code generation — required after modifying types or CRD schemas
+./hack/update-codegen.sh
+```
+
+---
+
+## Single-File Verification
+
+```bash
+# Lint a single Go file
+golangci-lint run path/to/file.go
+
+# Type-check using staticcheck
+staticcheck ./path/to/pkg/...
+
+# Format a single file in place
+gofmt -w path/to/file.go
+
+# Vet the package containing the file
+go vet ./path/to/pkg/...
+```
+
+---
+
+## Key Conventions
+
+1. **Dependencies are vendored.** All Go dependencies live in `vendor/`. Review agents
+   should ignore the `vendor/` directory — it contains third-party code.
+
+2. **Use structured logging.** Import `knative.dev/pkg/logging` and use context-aware
+   loggers. Never use `fmt.Printf` or `log.Print` in production code.
+
+3. **CRD types live in `pkg/apis/`.** After modifying any type definition, run
+   `./hack/update-codegen.sh` to regenerate deepcopy, client, and informer code.
+
+4. **Interceptors are the request/response processing layer.** Core interceptors
+   (CEL, GitHub, GitLab, Bitbucket, Slack) live in `pkg/interceptors/` and run as a
+   dedicated HTTPS service (port 8443). Custom interceptors are registered via the
+   `ClusterInterceptor` CRD and called by the sink over HTTP(S). The `pkg/interceptors/webhook/`
+   package handles the deprecated `Interceptor.Webhook` field for calling arbitrary
+   external URLs directly from the sink — distinct from `ClusterInterceptor`.
+
+5. **Test coverage is enforced.** PRs adding functionality must include tests.
+   E2E tests are tagged and require a cluster — unit tests should not.
+
+6. **Config lives in `config/`.** Kubernetes manifests (CRDs, RBAC, deployments)
+   are generated/managed there. Do not hand-edit generated CRD YAML.
+
+---
+
+## Architecture
+
+**Controller** (`cmd/controller`, `pkg/reconciler/`): Reconciles EventListener,
+TriggerBinding, TriggerTemplate, ClusterTriggerBinding, ClusterInterceptor CRDs.
+Uses Knative's controller framework.
+
+**EventListener Sink** (`cmd/eventlistenersink`, `pkg/sink/`): HTTP server
+that receives events and processes them through trigger bindings, templates, and
+interceptors to create Kubernetes resources.
+
+**Interceptors** (`cmd/interceptors`, `pkg/interceptors/`): HTTPS service (port 8443)
+handling core interceptors (CEL, GitHub, GitLab, Bitbucket, Slack). The sink calls interceptors
+via HTTP POST. ClusterInterceptors can extend this for custom logic.
+
+**Webhook** (`cmd/webhook`): Kubernetes admission webhook for validating and
+defaulting CRD resources.
+
+**tkn-triggers CLI** (`cmd/tkn-triggers`): CLI plugin for `tkn` to interact
+with Triggers resources.
+
+**Utility CLIs** (`cmd/binding-eval`, `cmd/cel-eval`, `cmd/triggerrun`): Developer
+tools for evaluating bindings, CEL expressions, and trigger processing locally.
+
+---
+
+## Pattern References for Common Changes
+
+- **New interceptor type**: Follow `pkg/interceptors/cel/` as the reference implementation
+- **New reconciler**: Follow `pkg/reconciler/eventlistener/` for structure and patterns
+- **New CRD type**: Add to `pkg/apis/triggers/`, update `./hack/update-codegen.sh`
+- **Sink event processing**: See `pkg/sink/sink.go` for the main event handling path
+- **E2E tests**: Follow examples in `test/eventlistener_test.go`
+- **CEL expressions**: See `pkg/interceptors/cel/` and `docs/cel_expressions.md`
+
+---
+
+## PR Conventions
+
+- Pull requests must follow the repository PR template in `.github/pull_request_template.md`.
+- Run `make fmt` before submitting for review.
+- `make golangci-lint` must pass with zero issues.
+- Tests required for any functionality changes.
+- Follow [Tekton commit message standards](https://github.com/tektoncd/community/blob/main/standards.md#commits).
+- Add `/kind <type>` label (bug, feature, cleanup, etc.).
+- Update release notes block if user-facing changes.
+- Run `./hack/update-codegen.sh` after modifying CRD types.
+- Ignore `vendor/` directory in reviews — contains vendored dependencies only.
+
+---
+
+## Skills
+
+None configured yet. Repo-local skills can be added to `.agents/skills/`.

AGENTS.md

@@ -0,0 +1 @@
+AGENTS.md

CLAUDE.md

@@ -0,0 +1,45 @@
+# ADR-0001: Event-Driven Architecture and Component Responsibilities
+
+**Status:** Accepted
+**Date:** 2024-01-01
+
+## Context
+
+Tekton Triggers needs to bridge external events (webhooks, CloudEvents) to Tekton
+PipelineRun/TaskRun creation in a Kubernetes-native way.
+
+## Decision
+
+Triggers is structured around four distinct responsibilities with strict separation:
+
+1. **EventListener** — receives and routes incoming HTTP events
+2. **Interceptors** — validate and transform event payloads before trigger evaluation
+3. **TriggerBinding** — extracts parameters from event payloads
+4. **TriggerTemplate** — defines the Kubernetes resources to create
+
+## Architectural Invariants
+
+- **Only the EventListener sink creates Kubernetes resources.** Interceptors, bindings,
+  and templates are pure transformation steps with no side effects.
+- **Interceptors are stateless.** Each interceptor processes a request independently.
+  No interceptor stores state between requests.
+- **TriggerBindings are read-only.** They extract data from the event payload but never
+  mutate it.
+- **Tekton Pipelines must be installed before Triggers.** Triggers depends on the
+  Pipeline CRDs (PipelineRun, TaskRun) being present in the cluster.
+- **EventListener is the only network ingress point.** All external events enter the
+  system exclusively through the EventListener HTTP endpoint.
+
+## Preconditions
+
+- A Kubernetes cluster with RBAC enabled
+- Tekton Pipelines installed and healthy
+- For TLS: valid certificates configured on the EventListener
+
+## Consequences
+
+- Interceptors can be developed and tested independently without a cluster
+- The sink is the single point of Kubernetes API interaction, simplifying RBAC requirements
+- Core and custom interceptors are both called via HTTP(S) from the sink; core interceptors
+  run as a separate in-cluster service (not in-process with the sink)
+- Custom interceptors can be implemented in any language that can serve HTTP(S)

docs/adr/0001-event-driven-architecture.md

@@ -0,0 +1,46 @@
+# ADR-0002: Interceptor Communication via HTTP(S) Webhook
+
+**Status:** Accepted
+**Date:** 2024-01-01
+**TEPs:** [TEP-0026](https://github.com/tektoncd/community/blob/main/teps/0026-interceptor-plugins.md)
+
+## Context
+
+Triggers needs to support both built-in interceptors (CEL, GitHub, GitLab, Bitbucket, Slack)
+and user-defined custom interceptors, while keeping the extension model language-agnostic.
+
+## Decision
+
+All interceptors — core and custom — are invoked by the sink via **HTTP(S) POST** using
+a JSON `InterceptorRequest`/`InterceptorResponse` contract:
+
+- **Core interceptors** (CEL, GitHub, GitLab, Bitbucket, Slack) run as a dedicated
+  in-cluster HTTPS service (`cmd/interceptors`, port 8443) separate from the sink.
+- **Custom interceptors** are deployed as separate services and registered via the
+  `ClusterInterceptor` CRD; the sink calls them at the configured HTTP(S) URL.
+
+## Architectural Invariants
+
+- The `InterceptorRequest`/`InterceptorResponse` JSON contract over HTTP(S) is the
+  canonical interface. Any interceptor — core or custom — must implement this contract.
+- Interceptors are called sequentially in the order defined in the `EventListener` spec.
+  A failed interceptor short-circuits the chain; subsequent interceptors are not called.
+- An interceptor that returns `continue: false` stops processing without creating
+  any Kubernetes resources.
+- Core interceptors share a single process and must not share mutable state between
+  requests.
+
+## Preconditions
+
+- Core interceptors service must be reachable from the sink within the cluster.
+- Custom interceptors must be reachable from the EventListener sink via the address
+  specified in the `ClusterInterceptor` resource.
+- TLS is used by default for core interceptors (port 8443); recommended for custom
+  interceptors in production.
+
+## Consequences
+
+- Custom interceptors can be implemented in any language with an HTTP server
+- Core interceptors incur an in-cluster network hop from the sink (not in-process)
+- Adding a new core interceptor requires a change to the interceptors binary
+- Custom interceptor failures surface as EventListener processing errors

docs/adr/0002-interceptor-communication.md

@@ -0,0 +1,19 @@
+# Architecture Decision Records
+
+Architectural decisions for Tekton Triggers are tracked as **Tekton Enhancement Proposals (TEPs)**
+in the [tektoncd/community](https://github.com/tektoncd/community/tree/main/teps) repository.
+
+TEPs follow a lightweight RFC process and cover cross-cutting concerns across all Tekton projects.
+Triggers-specific TEPs are tagged accordingly in the community repo.
+
+## Core Design Decisions
+
+Key architectural decisions captured locally:
+
+- [ADR-0001: Event-Driven Architecture and Component Responsibilities](./0001-event-driven-architecture.md)
+- [ADR-0002: Interceptor Communication via HTTP(S) Webhook](./0002-interceptor-communication.md)
+
+## How to Propose Changes
+
+Open a TEP in [tektoncd/community](https://github.com/tektoncd/community/blob/main/process/tep-process.md)
+following the TEP process for any change that affects the public API, CRD schema, or cross-component behavior.