Skip to content

Commit ea5eaf4

Browse files
committed
Merge remote-tracking branch 'origin/main' into openshell-unbundle-certs
Signed-off-by: politerealism <[email protected]> # Conflicts: # Cargo.lock
2 parents e2129cf + fde96f0 commit ea5eaf4

455 files changed

Lines changed: 71904 additions & 11504 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/build-from-issue/SKILL.md‎

Lines changed: 74 additions & 44 deletions
Large diffs are not rendered by default.

‎.agents/skills/create-github-issue/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,8 @@ EOF
114114

115115
GitHub built-in issue types (`Bug`, `Feature`, `Task`) should come from the matching issue template when possible, or be set manually afterward. Do not try to emulate them through labels.
116116

117+
Creating an issue does not accept it for roadmap work or queue agent work. Agents never apply the `roadmap` label, add issues to the roadmap project, or apply `agent:plan-requested` or `agent:implementation-requested`. Community issues proceed through `triage-issue`; a human decides whether technically validated work should be accepted and places it on the roadmap. The request labels queue work for unattended agents; a user may instead direct an agent to a specific issue.
118+
117119
## Useful Options
118120

119121
| Option | Description |

‎.agents/skills/create-github-pr/SKILL.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Create pull requests on GitHub using the `gh` CLI.
1111

1212
- The `gh` CLI must be authenticated (`gh auth status`)
1313
- You must have commits on a branch that's pushed to the remote
14-
- Branch should follow naming convention: `<issue-number>-<description>/<username>`
14+
- For issue-backed work, the branch should follow `<issue-number>-<description>/<username>`. Exempt issue-less changes may use `<description>/<username>`.
1515

1616
## Before Creating a PR
1717

@@ -24,6 +24,10 @@ in the same branch. If the change affects user-facing compute-driver setup,
2424
also update `docs/reference/sandbox-compute-drivers.mdx` or the relevant
2525
deployment docs.
2626

27+
### Check Agent Infrastructure
28+
29+
Use the `sync-agent-infra` skill's maintenance map to identify related skill updates when the branch changes behavior, commands, or development workflows. Run its full consistency check when the branch adds, removes, or renames skills or crates; changes workflow relationships or skill coverage; modifies issue or PR templates; or changes agent cross-references. Resolve any drift before creating the PR.
30+
2731
### Run Pre-commit Checks
2832

2933
Run the local pre-commit task before opening a PR:
@@ -43,7 +47,7 @@ Before creating a PR, verify:
4347
git branch --show-current
4448
```
4549

46-
2. **Branch follows naming convention** - Format: `<issue-number>-<description>/<initials>`
50+
2. **Branch follows naming convention** - Use `<issue-number>-<description>/<initials>` for issue-backed work or `<description>/<initials>` for an exempt issue-less change.
4751

4852
```bash
4953
# Example: 1234-add-pagination/jd
@@ -110,7 +114,7 @@ gh pr create --title "PR title" --body "PR description"
110114

111115
### Link to an Issue
112116

113-
Use `Closes #<issue-number>` in the body to auto-close the issue when merged:
117+
Features, user-visible behavior changes, public API changes, architecture changes, and multi-PR efforts must link an accepted issue. Use `Closes #<issue-number>` in the body to auto-close the issue when merged:
114118

115119
```bash
116120
gh pr create \
@@ -122,6 +126,8 @@ gh pr create \
122126
- Returns 400 instead of 500"
123127
```
124128

129+
Small documentation fixes, mechanical maintenance, and obvious localized bug fixes may omit a separate issue when the PR contains enough context to review the decision and implementation together. In that case, write `No issue required: <brief reason>` in the Related Issue section. Do not use this exception for security fixes; follow `SECURITY.md`.
130+
125131
### Create as Draft
126132

127133
For work-in-progress that's not ready for review:
@@ -153,7 +159,7 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
153159
<!-- 1-3 sentences: what this PR does and why -->
154160

155161
## Related Issue
156-
<!-- Fixes #NNN or Closes #NNN -->
162+
<!-- Fixes #NNN / Closes #NNN, or "No issue required: <reason>" for an exempt change -->
157163

158164
## Changes
159165
<!-- Bullet list of key changes -->

‎.agents/skills/create-spike/SKILL.md‎

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Investigate a plain-language problem description by deeply explorin
55

66
# Create Spike
77

8-
Investigate a problem, map it to the codebase, and produce a structured GitHub issue ready for `build-from-issue`.
8+
Investigate a problem, map it to the codebase, and produce a structured GitHub issue ready for human disposition and roadmap placement.
99

1010
A **spike** is an exploratory investigation. The user has a vague idea — a feature they want, a bug they've noticed, a performance concern — but hasn't mapped it to code, assessed feasibility, or structured it as a buildable issue. This skill does that mapping.
1111

@@ -122,7 +122,9 @@ Based on the investigation results, select appropriate labels:
122122
- **Do not add issue type labels** — GitHub built-in issue types come from issue templates or manual follow-up, not labels
123123
- **Include area labels** if they exist in the repo (e.g., `area:sandbox`, `area:proxy`, `area:policy`, `area:cli`)
124124
- **Do not invent labels** — only use labels that already exist in the repo
125-
- **Add `state:review-ready`** — the issue is ready for human review upon creation
125+
- **Add `state:validated` only when the evidence is sufficient for human disposition** — the spike established a coherent problem or proposal and completed the factual assessment needed for a human yes/no decision
126+
- **Add `state:needs-info` instead when material evidence is missing** — identify the exact evidence, reproduction details, or decision input still needed in the issue body
127+
- **Never add `state:accepted`, an `agent:*` label, or the `roadmap` label** — acceptance, roadmap placement, and requests for agent work require a human decision
126128

127129
## Step 4: Create the GitHub Issue
128130

@@ -131,7 +133,7 @@ Create the issue with a structured body containing both the stakeholder-readable
131133
```bash
132134
gh issue create \
133135
--title "<type>: <concise description of the problem/feature>" \
134-
--label "<area:component>" --label "state:review-ready" \
136+
--label "<area:component>" --label "<state:validated|state:needs-info>" \
135137
--body "$(cat <<'EOF'
136138
## Problem Statement
137139
@@ -195,6 +197,12 @@ gh issue create \
195197
- <design decision that could go either way>
196198
- ...
197199
200+
## Disposition Readiness
201+
202+
- **State:** `<state:validated|state:needs-info>`
203+
- **Assessment:** <why the available evidence is or is not sufficient for a human accept/decline decision>
204+
- **Missing evidence:** <specific evidence still needed, or "None">
205+
198206
## Test Considerations
199207
200208
- <what testing strategy makes sense for this change>
@@ -203,7 +211,7 @@ gh issue create \
203211
- <what tests exist for the affected area today, what patterns should be followed, any test infrastructure gaps>
204212
205213
---
206-
*Created by spike investigation. Use `build-from-issue` to plan and implement.*
214+
*Created by spike investigation. `state:validated` means the issue is ready for human disposition; `state:needs-info` means specific evidence is still required. A human applies `state:accepted` if OpenShell should pursue the work and places it on the roadmap separately. To queue unattended agent planning, a human applies `agent:plan-requested`; a direct request to an agent does not require that label.*
207215
EOF
208216
)"
209217
```
@@ -225,7 +233,13 @@ After creating the issue, report:
225233
3. Key risks or decisions that need human attention
226234
4. Next steps:
227235

228-
> Review the issue. Refine the proposed approach if needed, then use `build-from-issue` on the issue to create an implementation plan and build it.
236+
For `state:validated`:
237+
238+
> Review the issue and decide whether OpenShell should pursue it. If yes, replace `state:validated` with `state:accepted` and separately associate it with a roadmap item. The work may remain human-owned. Apply `agent:plan-requested` to queue planning for an unattended agent, or directly ask an agent to use `build-from-issue`. If no, close it as not planned and record the rationale.
239+
240+
For `state:needs-info`:
241+
242+
> Collect the missing evidence identified in the issue. Leave it off the roadmap. Once the evidence is sufficient, replace `state:needs-info` with `state:validated` for human disposition.
229243
230244
## Design Principles
231245

@@ -239,6 +253,8 @@ After creating the issue, report:
239253

240254
5. **Cross-reference `build-from-issue`.** Mention it as the natural next step in the issue body footer.
241255

256+
6. **Treat validation as an evidence threshold, not an automatic spike outcome.** Apply `state:validated` only when the investigation supports a human accept/decline decision. Otherwise apply `state:needs-info`, state what is missing, and leave the issue off the roadmap.
257+
242258
## Useful Commands Reference
243259

244260
| Command | Description |
@@ -263,9 +279,9 @@ User says: "Allow sandbox egress to private IP space via networking policy"
263279
- Reads `architecture/security-policy.md` and `architecture/sandbox.md`
264280
- Identifies exact insertion points: policy field addition, SSRF check bypass path, OPA rule extension
265281
- Assesses: Medium complexity, High confidence, ~6 files
266-
3. Fetch labels — select `area:sandbox`, `area:proxy`, `area:policy`, `state:review-ready`
282+
3. Fetch labels — select `area:sandbox`, `area:proxy`, `area:policy`, `state:validated`
267283
4. Create issue: `feat: allow sandbox egress to private IP space via networking policy` — body includes both the summary and full investigation (code references, architecture context, alternative approaches)
268-
5. Report: "Created issue #59. The investigation found that private IP blocking is enforced at the SSRF check layer in the proxy. The proposed approach adds a policy-level override. Review the issue and use `build-from-issue` when ready."
284+
5. Report: "Created issue #59. The investigation found that private IP blocking is enforced at the SSRF check layer in the proxy. The proposed approach adds a policy-level override. A human must now accept or decline it and place it on the roadmap if accepted."
269285

270286
### Bug investigation spike
271287

@@ -279,9 +295,9 @@ User says: "The proxy retry logic seems too aggressive — I'm seeing cascading
279295
- Maps the failure propagation path
280296
- Identifies that retries happen without backoff jitter, causing thundering herd
281297
- Assesses: Low complexity, High confidence, ~2 files
282-
3. Fetch labels — select `area:proxy`, `state:review-ready`
298+
3. Fetch labels — select `area:proxy`, `state:validated`
283299
4. Create issue: `fix: proxy retry logic causes cascading failures under load` — body includes both the summary and full investigation (retry code references, current behavior trace, comparison to standard backoff patterns)
284-
5. Report: "Created issue #74. The proxy retries without jitter or circuit breaking, which amplifies failures under load. Straightforward fix. Review and use `build-from-issue` when ready."
300+
5. Report: "Created issue #74. The proxy retries without jitter or circuit breaking, which amplifies failures under load. A human must now accept or decline it and place it on the roadmap if accepted."
285301

286302
### Performance/refactoring spike
287303

@@ -295,6 +311,6 @@ User says: "Policy evaluation is getting slow — can we cache compiled OPA poli
295311
- Reads the policy reload/hot-swap mechanism
296312
- Identifies that policies are recompiled on every evaluation
297313
- Assesses: Medium complexity, Medium confidence (cache invalidation is a design decision), ~4 files
298-
3. Fetch labels — select `area:policy`, `state:review-ready`
314+
3. Fetch labels — select `area:policy`, `state:validated`
299315
4. Create issue: `perf: cache compiled OPA policies to reduce evaluation latency` — body includes both the summary and full investigation (compilation hot path, per-request overhead, cache invalidation strategies with trade-offs)
300-
5. Report: "Created issue #81. Policies are recompiled per-request with no caching. The main design decision is the cache invalidation strategy — flagged as an open question. Review and use `build-from-issue` when ready."
316+
5. Report: "Created issue #81. Policies are recompiled per-request with no caching. The main design decision is the cache invalidation strategy. A human must now accept or decline it and place it on the roadmap if accepted."

0 commit comments

Comments
 (0)