You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit ea5eaf4
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .agents/skills/create-github-issue/SKILL.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -114,6 +114,8 @@ EOF
114
114
115
115
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.
116
116
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.
Copy file name to clipboardExpand all lines: .agents/skills/create-github-pr/SKILL.md
+10-4Lines changed: 10 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ Create pull requests on GitHub using the `gh` CLI.
11
11
12
12
- The `gh` CLI must be authenticated (`gh auth status`)
13
13
- 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>`.
15
15
16
16
## Before Creating a PR
17
17
@@ -24,6 +24,10 @@ in the same branch. If the change affects user-facing compute-driver setup,
24
24
also update `docs/reference/sandbox-compute-drivers.mdx` or the relevant
25
25
deployment docs.
26
26
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
+
27
31
### Run Pre-commit Checks
28
32
29
33
Run the local pre-commit task before opening a PR:
2.**Branch follows naming convention** - Use`<issue-number>-<description>/<initials>` for issue-backed work or `<description>/<initials>` for an exempt issue-less change.
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:
114
118
115
119
```bash
116
120
gh pr create \
@@ -122,6 +126,8 @@ gh pr create \
122
126
- Returns 400 instead of 500"
123
127
```
124
128
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
+
125
131
### Create as Draft
126
132
127
133
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
153
159
<!-- 1-3 sentences: what this PR does and why -->
154
160
155
161
## Related Issue
156
-
<!-- Fixes #NNN or Closes #NNN -->
162
+
<!-- Fixes #NNN / Closes #NNN, or "No issue required: <reason>" for an exempt change-->
Copy file name to clipboardExpand all lines: .agents/skills/create-spike/SKILL.md
+27-11Lines changed: 27 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ description: Investigate a plain-language problem description by deeply explorin
5
5
6
6
# Create Spike
7
7
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.
9
9
10
10
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.
11
11
@@ -122,7 +122,9 @@ Based on the investigation results, select appropriate labels:
122
122
-**Do not add issue type labels** — GitHub built-in issue types come from issue templates or manual follow-up, not labels
123
123
-**Include area labels** if they exist in the repo (e.g., `area:sandbox`, `area:proxy`, `area:policy`, `area:cli`)
124
124
-**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
126
128
127
129
## Step 4: Create the GitHub Issue
128
130
@@ -131,7 +133,7 @@ Create the issue with a structured body containing both the stakeholder-readable
131
133
```bash
132
134
gh issue create \
133
135
--title "<type>: <concise description of the problem/feature>" \
- **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
+
198
206
## Test Considerations
199
207
200
208
- <what testing strategy makes sense for this change>
@@ -203,7 +211,7 @@ gh issue create \
203
211
- <what tests exist for the affected area today, what patterns should be followed, any test infrastructure gaps>
204
212
205
213
---
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.*
207
215
EOF
208
216
)"
209
217
```
@@ -225,7 +233,13 @@ After creating the issue, report:
225
233
3. Key risks or decisions that need human attention
226
234
4. Next steps:
227
235
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.
229
243
230
244
## Design Principles
231
245
@@ -239,6 +253,8 @@ After creating the issue, report:
239
253
240
254
5.**Cross-reference `build-from-issue`.** Mention it as the natural next step in the issue body footer.
241
255
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
+
242
258
## Useful Commands Reference
243
259
244
260
| Command | Description |
@@ -263,9 +279,9 @@ User says: "Allow sandbox egress to private IP space via networking policy"
263
279
- Reads `architecture/security-policy.md` and `architecture/sandbox.md`
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."
269
285
270
286
### Bug investigation spike
271
287
@@ -279,9 +295,9 @@ User says: "The proxy retry logic seems too aggressive — I'm seeing cascading
279
295
- Maps the failure propagation path
280
296
- Identifies that retries happen without backoff jitter, causing thundering herd
281
297
- Assesses: Low complexity, High confidence, ~2 files
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."
285
301
286
302
### Performance/refactoring spike
287
303
@@ -295,6 +311,6 @@ User says: "Policy evaluation is getting slow — can we cache compiled OPA poli
295
311
- Reads the policy reload/hot-swap mechanism
296
312
- Identifies that policies are recompiled on every evaluation
297
313
- Assesses: Medium complexity, Medium confidence (cache invalidation is a design decision), ~4 files
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