docs: document Workspace.spec.setupCommand in reference.md by kelos-bot[bot] · Pull Request #1077 · kelos-dev/kelos

kelos-bot · 2026-05-01T09:44:56Z

What type of PR is this?

/kind docs

What this PR does / why we need it:

Workspace.spec.setupCommand shipped in #1056 with full CRD documentation and end-to-end agent support, but it was never surfaced in user-facing docs. New users had no way to discover the field short of reading the CRD or docs/agent-image-interface.md (which is written for custom-image authors, not end users).

This PR closes that gap:

Adds a spec.setupCommand row to the Workspace table in docs/reference.md.
Adds a short Workspace Setup Command subsection with a working YAML example (["sh", "-c", "npm install && npm run build"]) and notes covering ordering (after clone/checkout/remotes/files, before agent), failure semantics (non-zero exit fails the Task), and the exec-form vs. shell wrapper distinction.
Updates the Reference summary table in README.md so setupCommand is listed alongside the other key Workspace fields.

Which issue(s) this PR is related to:

Fixes #1075

Special notes for your reviewer:

Docs-only change. Wording and ordering semantics mirror the existing CRD spec comment in api/v1alpha1/workspace_types.go and the entrypoint contract in docs/agent-image-interface.md so the three sources stay in sync.

Does this PR introduce a user-facing change?

Document Workspace.spec.setupCommand in docs/reference.md and the README so users can discover the pre-agent setup command field without reading the CRD.

cubic-dev-ai

No issues found across 2 files

greptile-apps · 2026-05-01T09:46:27Z

Greptile Summary

This docs-only PR adds user-facing documentation for Workspace.spec.setupCommand (shipped in #1056) to docs/reference.md — a table row, a new subsection with a YAML example and ordering/failure semantics notes — and adds setupCommand to the Workspace key-fields row in README.md. The content is accurate and consistent with docs/agent-image-interface.md and the CRD spec comment.

Confidence Score: 5/5

Safe to merge — docs-only change with no logic, only P2 style suggestions.

No P0 or P1 findings. Two P2 style suggestions (YAML notation and one mildly ambiguous phrase) do not affect correctness or safety.

No files require special attention.

Important Files Changed

Filename	Overview
docs/reference.md	Adds spec.setupCommand table row and a new "Workspace Setup Command" subsection with YAML example; content is accurate and consistent with agent-image-interface.md, though the YAML example uses inline flow-sequence notation atypical for Kubernetes docs and one note phrase ("default form") is slightly misleading.
README.md	Adds setupCommand to the Workspace key-fields summary table; straightforward one-line change, correct.

Sequence Diagram

sequenceDiagram
    participant C as git-clone init container
    participant S as setupCommand
    participant A as Agent process

    C->>C: Clone repo and checkout ref
    C->>C: Add spec.remotes
    C->>C: Write spec.files
    C->>S: exec(KELOS_SETUP_COMMAND)
    alt exit 0
        S->>A: Agent starts in /workspace/repo
    else exit non-zero
        S-->>C: Task fails, agent never starts
    end

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
docs/reference.md:74
**Inline array syntax may surprise Kubernetes users**

The YAML example uses JSON flow-sequence notation (`["sh", "-c", "..."]`), which is valid but unusual in Kubernetes documentation, where block sequence style is the convention. Users copy-pasting this into manifests alongside other block-style fields may find the inconsistency confusing.

```suggestion
  setupCommand:
    - sh
    - -c
    - npm install && npm run build
```

### Issue 2 of 2
docs/reference.md:82
**"Default form" phrasing is misleading**

`setupCommand` is always an exec-form array — there is no alternative form. Calling it the "default form" implies other forms exist. A clearer phrasing would emphasise that the field uses exec semantics unconditionally.

```suggestion
- The field uses exec-form semantics (the array is passed directly to `exec` with no shell interpretation); for shell pipelines, environment expansion, or multi-step scripts, wrap the command with `["sh", "-c", "<script>"]`.
```

_{Reviews (3): Last reviewed commit: "docs: document Workspace.spec.setupComma..." | Re-trigger Greptile}

gjkim42 · 2026-05-01T11:23:34Z

/kelos pick-up

kelos-bot · 2026-05-01T11:23:38Z

🤖 Kelos Task Status

Task kelos-workers-issue-comment-f07ce3c6cd82 has succeeded. ✅

kelos-bot · 2026-05-01T11:23:38Z

🤖 Kelos Task Status

Task kelos-pr-responder-issue-comment-f07ce3c6cd82 has failed. ❌

gjkim42 · 2026-05-01T12:24:02Z

/kelos pick-up

kelos-bot · 2026-05-01T12:24:05Z

🤖 Kelos Task Status

Task kelos-pr-responder-issue-comment-bbca91cae3d3 has failed. ❌

kelos-bot · 2026-05-01T12:24:06Z

🤖 Kelos Task Status

Task kelos-workers-issue-comment-bbca91cae3d3 has succeeded. ✅

gjkim42 · 2026-05-01T18:06:40Z

/kelos pick-up

kelos-bot · 2026-05-01T18:06:43Z

🤖 Kelos Task Status

Task kelos-workers-issue-comment-c6915fd02437 has succeeded. ✅

kelos-bot · 2026-05-01T18:06:44Z

🤖 Kelos Task Status

Task kelos-pr-responder-issue-comment-c6915fd02437 has failed. ❌

gjkim42 · 2026-05-02T13:27:43Z

/kelos pick-up

kelos-bot · 2026-05-02T13:27:46Z

🤖 Kelos Task Status

Task kelos-pr-responder-issue-comment-14daab193a48 has succeeded. ✅

kelos-bot · 2026-05-02T13:29:51Z

🤖 Kelos Agent @gjkim42

All review feedback was addressed in previous commits (greptile's podOverrides.env scope concern was fixed in 0f30601, and the latest greptile review confirms it's resolved with a 5/5 confidence). Cubic found no issues, all CI checks pass, and required labels (generated-by-kelos, ok-to-test) are present. Ready for re-review.

gjkim42 · 2026-05-02T13:30:35Z

/kelos squash-commits

kelos-bot · 2026-05-02T13:30:38Z

🤖 Kelos Task Status

Task kelos-squash-commits-issue-comment-c0841db5964e has succeeded. ✅

kelos-bot · 2026-05-02T13:31:22Z

Squash complete.

🤖 Kelos Agent @gjkim42

Rebased on origin/main and squashed 2 commits into 1:

Commit: docs: document Workspace.spec.setupCommand

Force-pushed to the branch.

…entions Distill two new conventions from PR review feedback in the last 7 days: 1. Keep CRD enum docstrings consistent with the `+kubebuilder:validation:Enum` marker. Evidence: PR #1081 P2 from both cubic-dev-ai and the kelos-bot api-reviewer — `commentOn`'s godoc said "Empty matches both" but the marker rejected explicit `commentOn: ""`. 2. Qualify cross-CRD field references with the owning kind in docs. Evidence: PR #1077 P2 from greptile — Workspace reference section cited `podOverrides.env` without noting the field lives on `Task.spec`, leaving readers without a way to locate the cited field. Applied to AGENTS.md, agentconfig.yaml, kelos-workers.yaml, plus the api-reviewer's CRD/validation checklist (enum docstrings) and the reviewer's Documentation accuracy checklist (cross-CRD references).

Distills thirteen recurring conventions from recent PR review feedback and propagates them across AGENTS.md, the shared and worker AgentConfigs, and the reviewer prompts. All changes are backed by specific PR review findings. 1. Never use os.Getenv() for secrets as Go flag defaults — PR #971 P1 (cmd/kelos-webhook-server, cmd/ghproxy leaked GITHUB_TOKEN via --help). 2. Fail fast on invalid configuration — PR #971 multiple P1/P2 (silent degradation when GitHub App credentials or token resolvers failed). 3. Keep API surfaces minimal — PR #902 (maintainer asked repeatedly to defer speculative fields and ship the minimum viable API). 4. API changes must preserve backward compatibility — PR #1058 (BodyContains scalar->array would break in-cluster manifests; resolved by deprecating the old field rather than tightening validation). 5. Docs must match implementation, not aspiration — PRs #1035, #1056, #1082 (docs claimed enforcement that the code never performed). 6. TaskSpawner conventions — PRs #965, #974 (webhook over poll, empty .Branch for issue events, dual issue/PR context, no manual checkout). 7. Don't use Gomega's global Expect() inside Eventually polling blocks — PR #1084 (transient API errors short-circuited the poller). 8. /kind cleanup for self-development/-only PRs — PR #1100 P2 (agent classified by problem nature; rule is to classify by file location). 9. CLI error messages must name the resource — PR #1101 P2 (errors.New ("task failed") loses the name when batched). 10. Test the happy path, not only early-return guards — PR #1096 (both new tests covered only the no-op branches because production code lacked a posting seam; rule now requires adding the seam). 11. Avoid vacuous substring assertions in printer tests — PR #1106 P2 (a "sentry" check passed because the fixture's Name was "sentry-fixer"). 12. Keep CRD enum docstrings consistent with the Enum marker — PR #1081 P2 (commentOn godoc said "empty matches both" but the marker rejected ""). 13. Qualify cross-CRD field references with the owning kind in docs — PR #1077 P2 (Workspace section cited bare podOverrides.env without noting the field lives on Task.spec). Also: kelos-reviewer branch field uses the safe with-index fallback form, kelos-squash-commits gates the issue_comment trigger to PullRequest comments (preventing /kelos squash-commits typed on a plain issue from running git push --force-with-lease against an empty branch fallback), and the README's .Branch description matches runtime behavior.

Distills thirteen recurring conventions from recent PR review feedback and propagates them across AGENTS.md, the shared and worker AgentConfigs, and the reviewer prompts. All changes are backed by specific PR review findings. 1. Never use os.Getenv() for secrets as Go flag defaults — PR #971 P1 (cmd/kelos-webhook-server, cmd/ghproxy leaked GITHUB_TOKEN via --help). 2. Fail fast on invalid configuration — PR #971 multiple P1/P2 (silent degradation when GitHub App credentials or token resolvers failed). 3. Keep API surfaces minimal — PR #902 (maintainer asked repeatedly to defer speculative fields and ship the minimum viable API). 4. API changes must preserve backward compatibility — PR #1058 (BodyContains scalar->array would break in-cluster manifests; resolved by deprecating the old field rather than tightening validation). 5. Docs must match implementation, not aspiration — PRs #1035, #1056, #1082 (docs claimed enforcement that the code never performed). 6. TaskSpawner conventions — PRs #965, #974 (webhook over poll, empty .Branch for issue events, dual issue/PR context, no manual checkout). 7. Don't use Gomega's global Expect() inside Eventually polling blocks — PR #1084 (transient API errors short-circuited the poller). 8. /kind cleanup for self-development/-only PRs — PR #1100 P2 (agent classified by problem nature; rule is to classify by file location). 9. CLI error messages must name the resource — PR #1101 P2 (errors.New ("task failed") loses the name when batched). 10. Test the happy path, not only early-return guards — PR #1096 (both new tests covered only the no-op branches because production code lacked a posting seam; rule now requires adding the seam). 11. Avoid vacuous substring assertions in printer tests — PR #1106 P2 (a "sentry" check passed because the fixture's Name was "sentry-fixer"). 12. Keep CRD enum docstrings consistent with the Enum marker — PR #1081 P2 (commentOn godoc said "empty matches both" but the marker rejected ""). 13. Qualify cross-CRD field references with the owning kind in docs — PR #1077 P2 (Workspace section cited bare podOverrides.env without noting the field lives on Task.spec). Also: kelos-reviewer branch field uses the safe with-index fallback form, kelos-squash-commits gates the issue_comment trigger to PullRequest comments (preventing /kelos squash-commits typed on a plain issue from running git push --force-with-lease against an empty branch fallback), the kelos-squash-commits branch field uses the same with-index fallback form for defensive consistency with the documented convention, and the README's .Branch description matches runtime behavior (PR head branch or pushed branch; empty for issue events). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Propagates eleven recurring conventions, distilled from prior PR review feedback, across AGENTS.md, the shared and worker AgentConfigs, and the reviewer prompts. Also fixes two existing self-development spawner configurations that were flagged in adjacent reviews. Conventions added to AGENTS.md, agentconfig.yaml, and kelos-workers.yaml: 1. Never use os.Getenv() for secrets as Go flag defaults — PR #971 P1 (cmd/kelos-webhook-server, cmd/ghproxy leaked GITHUB_TOKEN via --help). 2. Fail fast on invalid configuration — PR #971 multiple P1/P2 (silent degradation when GitHub App credentials or token resolvers failed). 3. Keep API surfaces minimal — PR #902 (maintainer asked repeatedly to defer speculative fields and ship the minimum viable API). 4. API changes must preserve backward compatibility — PR #1058 (BodyContains scalar->array would break in-cluster manifests; resolved by deprecating the old field rather than tightening validation). 5. Docs must match implementation, not aspiration — PRs #1035, #1056, #1082 (docs claimed enforcement that the code never performed). 6. Don't use Gomega's global Expect() inside Eventually polling blocks — PR #1084 (transient API errors short-circuited the poller). 7. CLI error messages must name the resource — PR #1101 P2 (errors.New("task failed") loses the name when batched). 8. Test the happy path, not only early-return guards — PR #1096 (tests covered only the no-op branches because production code lacked a posting seam; rule now requires adding the seam). 9. Avoid vacuous substring assertions in printer tests — PR #1106 P2 (a "sentry" check passed because the fixture's Name was "sentry-fixer"). 10. Keep CRD enum docstrings consistent with the Enum marker — PR #1081 P2 (commentOn godoc said "empty matches both" but the marker rejected ""). 11. Qualify cross-CRD field references with the owning kind in docs — PR #1077 P2 (Workspace section cited bare podOverrides.env without noting the field lives on Task.spec). Reviewer/api-reviewer checklists gain matching items so kelos-reviewer and kelos-api-reviewer flag these patterns on future PRs. Other fixes in the same sweep: - kelos-reviewer.spec.taskTemplate.branch uses the safe '{{with index . "Branch"}}{{.}}{{else}}main{{end}}' fallback form so a /kelos review typed on a plain issue lands on main rather than an empty branch. - kelos-squash-commits gates the issue_comment trigger to commentOn: PullRequest and uses the same with-index fallback for the branch field — /kelos squash-commits typed on a plain issue would otherwise fire the spawner with empty {{.Branch}} and the prompt then runs git push --force-with-lease. - self-development/README.md template-variable table corrected from "Usually PR head branch" to "PR head branch or pushed branch; empty for issue events" to match runtime behavior, and the bodyContains example was updated to bodyPattern to match the spawner configs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

kelos-bot Bot added generated-by-kelos ok-to-test labels May 1, 2026

github-actions Bot added kind/docs needs-triage needs-priority needs-actor needs-release-note Indicates a PR lacks a release-note block release-note and removed needs-release-note Indicates a PR lacks a release-note block labels May 1, 2026

kelos-bot Bot mentioned this pull request May 1, 2026

Docs: Workspace.spec.setupCommand undocumented in reference.md — no user-facing guidance or examples #1075

Closed

cubic-dev-ai Bot reviewed May 1, 2026

View reviewed changes

greptile-apps Bot reviewed May 1, 2026

View reviewed changes

Comment thread docs/reference.md Resolved

kelos-bot Bot force-pushed the kelos-task-1075 branch from c1b4da4 to e65b984 Compare May 1, 2026 18:28

docs: document Workspace.spec.setupCommand

2b2563d

kelos-bot Bot force-pushed the kelos-task-1075 branch from e65b984 to 2b2563d Compare May 2, 2026 13:31

gjkim42 enabled auto-merge May 2, 2026 13:31

gjkim42 added this pull request to the merge queue May 2, 2026

Merged via the queue into main with commit 5fc47bb May 2, 2026
16 checks passed

gjkim42 deleted the kelos-task-1075 branch May 2, 2026 13:53

kelos-bot Bot mentioned this pull request May 7, 2026

self-development: distill recurring conventions from PR review feedback #786

Merged

kelos-bot Bot mentioned this pull request May 15, 2026

Prompt Tuning: kelos-workers post-checklist status comment skipped on the linked issue in 65% of recent successful PR runs #1136

Closed

kelos-bot Bot mentioned this pull request May 19, 2026

Prompt Tuning: kelos-config-update has no exit from rolling updates — PR #786 has accumulated 11 conventions over 56 days with 0 new PRs in 19 cron runs #1159

Closed

Conversation

kelos-bot Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR is related to:

Special notes for your reviewer:

Does this PR introduce a user-facing change?

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

gjkim42 commented May 1, 2026

Uh oh!

kelos-bot Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kelos-bot Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gjkim42 commented May 1, 2026

Uh oh!

kelos-bot Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kelos-bot Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gjkim42 commented May 1, 2026

Uh oh!

kelos-bot Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kelos-bot Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gjkim42 commented May 2, 2026

Uh oh!

kelos-bot Bot commented May 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kelos-bot Bot commented May 2, 2026

Uh oh!

gjkim42 commented May 2, 2026

Uh oh!

kelos-bot Bot commented May 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kelos-bot Bot commented May 2, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

kelos-bot Bot commented May 1, 2026 •

edited

Loading

greptile-apps Bot commented May 1, 2026 •

edited

Loading

kelos-bot Bot commented May 1, 2026 •

edited

Loading

kelos-bot Bot commented May 1, 2026 •

edited

Loading

kelos-bot Bot commented May 1, 2026 •

edited

Loading

kelos-bot Bot commented May 1, 2026 •

edited

Loading

kelos-bot Bot commented May 1, 2026 •

edited

Loading

kelos-bot Bot commented May 1, 2026 •

edited

Loading

kelos-bot Bot commented May 2, 2026 •

edited

Loading

kelos-bot Bot commented May 2, 2026 •

edited

Loading