Add fail-fast convention, no-manual-checkout rule, and secret-in-flag-defaults

AGENTS.md

@@ -8,6 +8,8 @@
 - **Logging conventions.** Start log messages with capital letters and do not end with punctuation.
 - **Commit messages.** Do not include PR links in commit messages.
 - **Kubernetes resource comparison.** Use semantic `.Equal()` or `.Cmp()` methods for `resource.Quantity` comparisons, not `reflect.DeepEqual` — structurally different Quantity values can be semantically identical (e.g., `1000m` vs `1` CPU).
+- **Never use `os.Getenv()` for secrets as Go `flag` defaults.** Go's `flag` package prints default values in usage/help output, which leaks secret values. Instead, use an empty default and read the env var after `flag.Parse()`.
+- **Fail fast on invalid configuration.** Do not silently fall back to degraded behavior (e.g., unauthenticated requests) when configuration or credentials are invalid or missing. Return an error or exit immediately instead of returning nil or empty values that mask the failure.
 
 ## Key Makefile Targets
 - `make verify` — run all verification checks (lint, fmt, vet, etc.).

self-development/README.md

@@ -385,7 +385,7 @@ To adapt these examples for your own repository:
    | `{{.Event}}` | GitHub webhook event type | `issue_comment`, `issues`, `pull_request_review`, etc. | Empty |
    | `{{.Action}}` | GitHub webhook action | `created`, `labeled`, `submitted`, etc. | Empty |
    | `{{.Sender}}` | GitHub username that triggered the webhook | GitHub login | Empty |
-   | `{{.Branch}}` | Branch name when present in the webhook payload | Usually PR head branch or push branch | Empty |
+   | `{{.Branch}}` | Branch name when present in the webhook payload | PR head branch; empty for issue events | Empty |
    | `{{.Kind}}` | Type of work item | `"webhook"` | `"Issue"` |
    | `{{.Time}}` | Trigger time (RFC3339) | Empty | Cron tick time (e.g., `"2026-02-07T09:00:00Z"`) |
    | `{{.Schedule}}` | Cron schedule expression | Empty | Schedule string (e.g., `"0 * * * *"`) |

self-development/agentconfig.yaml

@@ -31,3 +31,10 @@ spec:
     - Commit messages: do not include PR links in commit messages
     - When making structural changes (adding new files, configs, or components), update related documentation (especially README files) to stay in sync
     - Kubernetes resource comparison: use semantic `.Equal()` or `.Cmp()` methods for `resource.Quantity` comparisons, not `reflect.DeepEqual`
+    - Never use `os.Getenv()` for secrets as Go `flag` defaults: Go's `flag` package prints default values in usage/help output, which leaks secret values; use an empty default and read the env var after `flag.Parse()`
+    - Fail fast on invalid configuration: do not silently fall back to degraded behavior (e.g., unauthenticated requests) when configuration or credentials are invalid or missing; return an error or exit immediately
+    - TaskSpawner conventions (for `self-development/` YAML files):
+      - Prefer webhook-based triggers (`githubWebhook`) over poll-based (`githubPullRequests`) for real-time event-driven tasks
+      - The `{{.Branch}}` template variable is empty for issue-only events; use `{{if .Branch}}{{.Branch}}{{else}}main{{end}}` when it may be empty
+      - The `issue_comment` webhook event fires for both issues and pull requests; design prompts to detect and handle both contexts
+      - Do not include manual PR branch checkout instructions in prompts — Kelos already checks out the PR branch automatically

self-development/kelos-reviewer.yaml

@@ -119,6 +119,7 @@ spec:
       - Are there edge cases, off-by-one errors, or nil pointer risks?
       - Are error returns checked and handled?
       - Are concurrent operations safe (locks, channels, context cancellation)?
+      - Does the code fail fast on invalid configuration/credentials, or does it silently degrade (e.g., falling back to unauthenticated requests)?
 
       **Tests**:
       - Are there tests for the new/changed behavior?
@@ -134,6 +135,7 @@ spec:
 
       **Security**:
       - No hardcoded secrets or credentials
+      - No `os.Getenv()` for secrets used as Go `flag` defaults — the `flag` package prints defaults in usage output, leaking secret values
       - Input validation at system boundaries
       - No command injection, path traversal, or OWASP top-10 risks
 

self-development/kelos-workers.yaml

@@ -29,6 +29,13 @@ spec:
     - Always try to add or improve tests when modifying code
     - Logging conventions: start log messages with capital letters and do not end with punctuation
     - Commit messages: do not include PR links in commit messages
+    - Never use `os.Getenv()` for secrets as Go `flag` defaults: Go's `flag` package prints default values in usage/help output, which leaks secret values; use an empty default and read the env var after `flag.Parse()`
+    - Fail fast on invalid configuration: do not silently fall back to degraded behavior (e.g., unauthenticated requests) when configuration or credentials are invalid or missing; return an error or exit immediately
+    - TaskSpawner conventions (for `self-development/` YAML files):
+      - Prefer webhook-based triggers (`githubWebhook`) over poll-based (`githubPullRequests`) for real-time event-driven tasks
+      - The `{{.Branch}}` template variable is empty for issue-only events; use `{{if .Branch}}{{.Branch}}{{else}}main{{end}}` when it may be empty
+      - The `issue_comment` webhook event fires for both issues and pull requests; design prompts to detect and handle both contexts
+      - Do not include manual PR branch checkout instructions in prompts — Kelos already checks out the PR branch automatically
 ---
 apiVersion: kelos.dev/v1alpha1
 kind: TaskSpawner