gentle-pi 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +66 -0
- package/assets/agents/sdd-apply.md +71 -0
- package/assets/agents/sdd-archive.md +14 -0
- package/assets/agents/sdd-design.md +14 -0
- package/assets/agents/sdd-explore.md +14 -0
- package/assets/agents/sdd-init.md +14 -0
- package/assets/agents/sdd-onboard.md +15 -0
- package/assets/agents/sdd-proposal.md +14 -0
- package/assets/agents/sdd-spec.md +14 -0
- package/assets/agents/sdd-tasks.md +61 -0
- package/assets/agents/sdd-verify.md +55 -0
- package/assets/chains/sdd-full.chain.md +75 -0
- package/assets/chains/sdd-plan.chain.md +35 -0
- package/assets/chains/sdd-verify.chain.md +27 -0
- package/assets/orchestrator.md +191 -0
- package/assets/support/strict-tdd-verify.md +269 -0
- package/assets/support/strict-tdd.md +364 -0
- package/extensions/gentle-ai.ts +157 -0
- package/extensions/sdd-init.ts +83 -0
- package/extensions/skill-registry.ts +267 -0
- package/package.json +47 -0
- package/prompts/cl.md +54 -0
- package/prompts/is.md +25 -0
- package/prompts/pr.md +41 -0
- package/prompts/wr.md +31 -0
- package/skills/branch-pr/SKILL.md +202 -0
- package/skills/chained-pr/SKILL.md +50 -0
- package/skills/chained-pr/references/chaining-details.md +99 -0
- package/skills/cognitive-doc-design/SKILL.md +81 -0
- package/skills/comment-writer/SKILL.md +74 -0
- package/skills/gentle-ai/SKILL.md +43 -0
- package/skills/issue-creation/SKILL.md +223 -0
- package/skills/judgment-day/SKILL.md +52 -0
- package/skills/judgment-day/references/prompts-and-formats.md +75 -0
- package/skills/work-unit-commits/SKILL.md +86 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: chained-pr
|
|
3
|
+
description: "Trigger: PRs over 400 lines, stacked PRs, review slices. Split oversized changes into chained PRs that protect review focus."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: gentleman-programming
|
|
7
|
+
version: "1.0"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Activation Contract
|
|
11
|
+
|
|
12
|
+
Load this skill when a planned PR may exceed **400 changed lines**, SDD forecasts `400-line budget risk: High` or `Chained PRs recommended: Yes`, or the user asks for chained/stacked PRs, review slices, or reviewer-load control.
|
|
13
|
+
|
|
14
|
+
## Hard Rules
|
|
15
|
+
|
|
16
|
+
- Split PRs over **400 changed lines** unless a maintainer explicitly accepts `size:exception`.
|
|
17
|
+
- Keep each PR reviewable in about **≤60 minutes**.
|
|
18
|
+
- Use one deliverable work unit per PR; keep tests/docs with the unit they verify.
|
|
19
|
+
- State start, end, prior dependencies, follow-up work, and out-of-scope items in every chained PR.
|
|
20
|
+
- Every child PR must include a dependency diagram marking the current PR with `📍`.
|
|
21
|
+
- In Feature Branch Chain, create a draft/no-merge tracker PR; child PR #1 targets the tracker branch, later children target the immediate parent branch.
|
|
22
|
+
- Treat polluted diffs as base bugs: retarget or rebase until only the current work unit appears.
|
|
23
|
+
- Do not mix chain strategies after the user chooses one.
|
|
24
|
+
|
|
25
|
+
## Decision Gates
|
|
26
|
+
|
|
27
|
+
| Condition | Action |
|
|
28
|
+
|---|---|
|
|
29
|
+
| PR ≤400 changed lines and focused | Keep single PR. |
|
|
30
|
+
| PR >400, each slice can land independently | Use Stacked PRs to main. |
|
|
31
|
+
| PR >400, feature must integrate before main | Use Feature Branch Chain with tracker. |
|
|
32
|
+
| Generated/vendor/migration diff cannot split cleanly | Ask maintainer for `size:exception`. |
|
|
33
|
+
| SDD provides `delivery_strategy` | Follow it before apply/PR creation. |
|
|
34
|
+
|
|
35
|
+
## Execution Steps
|
|
36
|
+
|
|
37
|
+
1. Estimate changed lines and identify independent work units.
|
|
38
|
+
2. Ask for a chain strategy when none is cached and the budget is exceeded.
|
|
39
|
+
3. Create branches/PRs using the chosen strategy only.
|
|
40
|
+
4. Add Chain Context to each PR without replacing the repo PR template.
|
|
41
|
+
5. Verify each PR independently: CI/tests/docs/manual checks, rollback scope, and clean diff.
|
|
42
|
+
6. Keep tracker PR draft/no-merge until all child PRs are reviewed and integrated.
|
|
43
|
+
|
|
44
|
+
## Output Contract
|
|
45
|
+
|
|
46
|
+
Return the chosen strategy, PR order, current PR boundary, dependency diagram, review budget (`additions + deletions`), verification plan, and any `size:exception` rationale.
|
|
47
|
+
|
|
48
|
+
## References
|
|
49
|
+
|
|
50
|
+
- [references/chaining-details.md](references/chaining-details.md) — strategy diagrams, PR body section, branch commands, and reviewer guidance.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Chained PR Details
|
|
2
|
+
|
|
3
|
+
## Strategy Notes
|
|
4
|
+
|
|
5
|
+
| | Stacked PRs to main | Feature Branch Chain |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| Speed | Each slice can ship in order | Full feature waits for tracker merge |
|
|
8
|
+
| Rollback | Revert individual main PRs | Revert/hold the whole feature branch |
|
|
9
|
+
| Risk | Partial behavior may land | Nothing lands until the chain completes |
|
|
10
|
+
| Complexity | Simpler retarget/rebase flow | Requires tracker and strict diff hygiene |
|
|
11
|
+
|
|
12
|
+
## Feature Branch Chain
|
|
13
|
+
|
|
14
|
+
Use when the feature branch accumulates the final integration while child PRs are reviewed as focused slices.
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
main
|
|
18
|
+
└── feat/my-feature ← tracker/final integration branch
|
|
19
|
+
↑ PR #1 base: feat/my-feature
|
|
20
|
+
└── feat/my-feature-01-core
|
|
21
|
+
↑ PR #2 base: feat/my-feature-01-core
|
|
22
|
+
└── feat/my-feature-02-shared
|
|
23
|
+
↑ PR #3 base: feat/my-feature-02-shared
|
|
24
|
+
└── feat/my-feature-03-slice
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Steps:
|
|
28
|
+
|
|
29
|
+
1. Create the feature/tracker branch from `main`.
|
|
30
|
+
2. Open the tracker PR to `main`; mark it draft/no-merge.
|
|
31
|
+
3. Create PR #1 from a child branch and target it to the tracker branch.
|
|
32
|
+
4. Create each later child branch from the previous PR branch and target it to that parent branch.
|
|
33
|
+
5. Merge/integrate children in order; merge the tracker only after the chain is complete.
|
|
34
|
+
|
|
35
|
+
## Stacked PRs to Main
|
|
36
|
+
|
|
37
|
+
Use when each slice can land on `main` in order.
|
|
38
|
+
|
|
39
|
+
```text
|
|
40
|
+
main <- PR 1: foundation
|
|
41
|
+
└── PR 2: feature slice built on PR 1
|
|
42
|
+
└── PR 3: docs/tests built on PR 2
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
After a parent PR merges, rebase/retarget the next PR so GitHub shows only the current slice.
|
|
46
|
+
|
|
47
|
+
## Chain Context Section
|
|
48
|
+
|
|
49
|
+
Append this section to the repo PR template; do not replace required issue/checklist sections.
|
|
50
|
+
|
|
51
|
+
```markdown
|
|
52
|
+
## Chain Context
|
|
53
|
+
|
|
54
|
+
| Field | Value |
|
|
55
|
+
|-------|-------|
|
|
56
|
+
| Chain | <feature or stack name> |
|
|
57
|
+
| Tracker PR | <#NNN or "Not needed"> |
|
|
58
|
+
| Position | <N of total> |
|
|
59
|
+
| Base | `<target branch>` |
|
|
60
|
+
| Depends on | <PR/issue/link or "None"> |
|
|
61
|
+
| Follow-up | <next PR or "None"> |
|
|
62
|
+
| Review budget | <changed lines> / 400 |
|
|
63
|
+
| Starts at | <branch, PR, or state this builds on> |
|
|
64
|
+
| Ends with | <standalone result delivered by this PR> |
|
|
65
|
+
|
|
66
|
+
### Chain Overview
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
main
|
|
70
|
+
└── #NNN Previous PR
|
|
71
|
+
└── 📍 #NNN This PR
|
|
72
|
+
└── #NNN Next PR
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Scope
|
|
76
|
+
- Includes: <focused unit>
|
|
77
|
+
- Excludes: <deferred work>
|
|
78
|
+
|
|
79
|
+
### Autonomy
|
|
80
|
+
- [ ] CI is expected to pass for this PR branch
|
|
81
|
+
- [ ] This PR has one deliverable scope
|
|
82
|
+
- [ ] This PR can be rolled back without unrelated changes
|
|
83
|
+
- [ ] Tests, docs, or manual verification cover this unit
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Commands
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
gh pr view <PR_NUMBER> --json additions,deletions,changedFiles,title,url
|
|
90
|
+
gh pr create --base feat/my-feature --title "feat(scope): focused slice" --body-file pr-body.md
|
|
91
|
+
gh pr create --base feat/my-feature-01-core --title "feat(scope): next focused slice" --body-file pr-body.md
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Reviewer Guidance
|
|
95
|
+
|
|
96
|
+
- Ask for a split when a PR exceeds 400 changed lines without `size:exception`.
|
|
97
|
+
- Recommend Feature Branch Chain when work must integrate before `main`.
|
|
98
|
+
- Recommend stacked PRs when each slice can merge independently.
|
|
99
|
+
- Review child PRs against immediate parent branches; a polluted diff is a branching bug.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cognitive-doc-design
|
|
3
|
+
description: "Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: gentleman-programming
|
|
7
|
+
version: "1.0"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## When to Use
|
|
11
|
+
|
|
12
|
+
Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.
|
|
13
|
+
|
|
14
|
+
Use it especially for:
|
|
15
|
+
|
|
16
|
+
- PR descriptions and review notes.
|
|
17
|
+
- Contributor or maintainer guides.
|
|
18
|
+
- Architecture, workflow, or onboarding docs.
|
|
19
|
+
- Any doc that currently feels long, dense, or hard to scan.
|
|
20
|
+
|
|
21
|
+
## Critical Patterns
|
|
22
|
+
|
|
23
|
+
| Pattern | Rule |
|
|
24
|
+
|---------|------|
|
|
25
|
+
| Lead with the answer | Put the decision, action, or outcome first. Context comes after. |
|
|
26
|
+
| Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |
|
|
27
|
+
| Chunking | Group related information into small sections. Keep flat lists short. |
|
|
28
|
+
| Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |
|
|
29
|
+
| Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |
|
|
30
|
+
| Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |
|
|
31
|
+
|
|
32
|
+
## Documentation Shape
|
|
33
|
+
|
|
34
|
+
Use this default structure unless the repo already provides a stronger template:
|
|
35
|
+
|
|
36
|
+
```markdown
|
|
37
|
+
# <Outcome-oriented title>
|
|
38
|
+
|
|
39
|
+
<One paragraph: what changed, who it helps, and why it matters.>
|
|
40
|
+
|
|
41
|
+
## Quick path
|
|
42
|
+
|
|
43
|
+
1. <First action>
|
|
44
|
+
2. <Second action>
|
|
45
|
+
3. <Verification or expected result>
|
|
46
|
+
|
|
47
|
+
## Details
|
|
48
|
+
|
|
49
|
+
| Topic | Decision |
|
|
50
|
+
|-------|----------|
|
|
51
|
+
| <area> | <concise explanation> |
|
|
52
|
+
|
|
53
|
+
## Checklist
|
|
54
|
+
|
|
55
|
+
- [ ] <Reader can confirm this>
|
|
56
|
+
- [ ] <Reader can confirm that>
|
|
57
|
+
|
|
58
|
+
## Next step
|
|
59
|
+
|
|
60
|
+
<Link or action that continues the workflow.>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## PR and Review Docs
|
|
64
|
+
|
|
65
|
+
When documenting a PR, reduce reviewer burnout by making the review path explicit:
|
|
66
|
+
|
|
67
|
+
- State what to review first.
|
|
68
|
+
- State what is intentionally out of scope.
|
|
69
|
+
- Link the previous and next PR when work is chained.
|
|
70
|
+
- Keep each section focused on one decision or unit of work.
|
|
71
|
+
- Use checklists for acceptance criteria and verification.
|
|
72
|
+
|
|
73
|
+
## Commands
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# Check markdown files changed in the current branch
|
|
77
|
+
git diff --name-only -- '*.md'
|
|
78
|
+
|
|
79
|
+
# Inspect PR changed-line count for cognitive load
|
|
80
|
+
gh pr view <PR_NUMBER> --json additions,deletions,changedFiles
|
|
81
|
+
```
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: comment-writer
|
|
3
|
+
description: "Write warm, direct collaboration comments. Trigger: PR feedback, issue replies, reviews, Slack messages, or GitHub comments."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: gentleman-programming
|
|
7
|
+
version: "1.0"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## When to Use
|
|
11
|
+
|
|
12
|
+
Load this skill whenever you write a comment that another human will read.
|
|
13
|
+
|
|
14
|
+
Use it for:
|
|
15
|
+
|
|
16
|
+
- GitHub PR or issue comments.
|
|
17
|
+
- Review feedback and requested changes.
|
|
18
|
+
- Maintainer replies.
|
|
19
|
+
- Slack, Discord, or async project updates.
|
|
20
|
+
|
|
21
|
+
## Voice Rules
|
|
22
|
+
|
|
23
|
+
| Rule | Requirement |
|
|
24
|
+
|------|-------------|
|
|
25
|
+
| Be useful fast | Start with the actionable point. Do not recap the whole PR before feedback. |
|
|
26
|
+
| Be warm and direct | Sound like a thoughtful teammate, not a corporate bot. |
|
|
27
|
+
| Keep it short | Prefer 1 to 3 short paragraphs or a tight bullet list. |
|
|
28
|
+
| Explain why | Give the technical reason when asking for a change. |
|
|
29
|
+
| Avoid pile-ons | Comment on the highest-value issue, not every tiny preference. |
|
|
30
|
+
| Match thread language | Write in the thread/user language. If writing in Spanish, use Rioplatense Spanish/voseo: `podés`, `tenés`, `fijate`, `dale`. |
|
|
31
|
+
| No em dashes | Use commas, periods, or parentheses instead. |
|
|
32
|
+
|
|
33
|
+
## Comment Formula
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
<Direct observation or request>
|
|
37
|
+
|
|
38
|
+
<Why it matters, only if needed>
|
|
39
|
+
|
|
40
|
+
<Concrete next action>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Examples
|
|
44
|
+
|
|
45
|
+
### Request change
|
|
46
|
+
|
|
47
|
+
```markdown
|
|
48
|
+
Buenísimo el enfoque. Acá separaría este cambio en otro commit porque mezcla la validación con el wiring de UI.
|
|
49
|
+
|
|
50
|
+
Eso le baja carga al reviewer y hace que el rollback sea más claro si falla la integración.
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Approve with a note
|
|
54
|
+
|
|
55
|
+
```markdown
|
|
56
|
+
Está bien encaminado y el scope se entiende rápido.
|
|
57
|
+
|
|
58
|
+
Dejo aprobado. Para el próximo PR, agregá el link al anterior y al siguiente así la cadena queda navegable.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Ask for split
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
Este PR supera el presupuesto de 400 líneas cambiadas, así que necesitamos dividirlo o justificar `size:exception`.
|
|
65
|
+
|
|
66
|
+
Mi sugerencia: primero foundation + tests, después integración, después docs. Así cada review tiene inicio y fin claros.
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Commands
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
# Inspect a PR before writing review feedback
|
|
73
|
+
gh pr view <PR_NUMBER> --json title,body,additions,deletions,changedFiles
|
|
74
|
+
```
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gentle-ai
|
|
3
|
+
description: Use Gentle AI harness discipline for Pi work: clarify first, preserve OpenSpec artifacts, use strict TDD where available, delegate through subagents when useful, and protect review workload.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Gentle AI Harness
|
|
7
|
+
|
|
8
|
+
Use this skill when work is non-trivial, risky, multi-step, or likely to benefit from SDD/OpenSpec artifacts.
|
|
9
|
+
|
|
10
|
+
## Compact Rules
|
|
11
|
+
|
|
12
|
+
- Clarify scope, constraints, acceptance criteria, and non-goals before implementation.
|
|
13
|
+
- Use OpenSpec-style artifacts for proposal, specs, design, tasks, apply progress, verify report, and archive notes.
|
|
14
|
+
- If tests exist, follow strict TDD: RED, GREEN, TRIANGULATE, REFACTOR, and record evidence.
|
|
15
|
+
- Keep one parent session responsible for orchestration; child subagents should receive concrete phase work and must not spawn more subagents.
|
|
16
|
+
- Prefer fresh-context reviewers for adversarial review and forked workers only after direction is approved.
|
|
17
|
+
- Keep writes single-threaded unless the user explicitly approves isolated parallel worktrees.
|
|
18
|
+
- Forecast review workload before large changes; ask before producing oversized or multi-area diffs.
|
|
19
|
+
- Never claim persistent memory is available because of Gentle AI itself; memory is provided by separate packages/tools.
|
|
20
|
+
|
|
21
|
+
## Work Routing
|
|
22
|
+
|
|
23
|
+
Use the smallest safe harness:
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
small + known context → inline direct
|
|
27
|
+
unknown / context-heavy → simple delegation
|
|
28
|
+
large / ambiguous / risky → SDD
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
For substantial changes:
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
clarify → explore → proposal → spec → design → tasks → apply → verify → archive
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
For bounded implementation with subagents:
|
|
38
|
+
|
|
39
|
+
```text
|
|
40
|
+
clarify → planner/worker → fresh reviewers → worker fixes → verify
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The package auto-installs SDD agents and chains into the project when a Pi session starts. Use `/gentle-ai:install-sdd --force` only for recovery or intentional overwrite.
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: issue-creation
|
|
3
|
+
description: "Create Gentle AI issues with issue-first checks. Trigger: creating GitHub issues, bug reports, or feature requests."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: gentleman-programming
|
|
7
|
+
version: "1.0"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## When to Use
|
|
11
|
+
|
|
12
|
+
Use this skill when:
|
|
13
|
+
- Creating a GitHub issue (bug report or feature request)
|
|
14
|
+
- Helping a contributor file an issue
|
|
15
|
+
- Triaging or approving issues as a maintainer
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Critical Rules
|
|
20
|
+
|
|
21
|
+
1. **Blank issues are disabled** — MUST use a template (bug report or feature request)
|
|
22
|
+
2. **Every issue gets `status:needs-review` automatically** on creation
|
|
23
|
+
3. **A maintainer MUST add `status:approved`** before any PR can be opened
|
|
24
|
+
4. **Questions go to [Discussions](https://github.com/Gentleman-Programming/agent-teams-lite/discussions)**, not issues
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Workflow
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
1. Search existing issues for duplicates
|
|
32
|
+
2. Choose the correct template (Bug Report or Feature Request)
|
|
33
|
+
3. Fill in ALL required fields
|
|
34
|
+
4. Check pre-flight checkboxes
|
|
35
|
+
5. Submit → issue gets status:needs-review automatically
|
|
36
|
+
6. Wait for maintainer to add status:approved
|
|
37
|
+
7. Only then open a PR linking this issue
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Issue Templates
|
|
43
|
+
|
|
44
|
+
### Bug Report
|
|
45
|
+
|
|
46
|
+
Template: `.github/ISSUE_TEMPLATE/bug_report.yml`
|
|
47
|
+
Auto-labels: `bug`, `status:needs-review`
|
|
48
|
+
|
|
49
|
+
#### Required Fields
|
|
50
|
+
|
|
51
|
+
| Field | Description |
|
|
52
|
+
|-------|-------------|
|
|
53
|
+
| **Pre-flight Checks** | Checkboxes: no duplicate + understands approval workflow |
|
|
54
|
+
| **Bug Description** | Clear description of the bug |
|
|
55
|
+
| **Steps to Reproduce** | Numbered steps to reproduce |
|
|
56
|
+
| **Expected Behavior** | What should have happened |
|
|
57
|
+
| **Actual Behavior** | What happened instead (include errors/logs) |
|
|
58
|
+
| **Operating System** | Dropdown: macOS, Linux variants, Windows, WSL |
|
|
59
|
+
| **Agent / Client** | Dropdown: Claude Code, OpenCode, Gemini CLI, Cursor, Windsurf, Codex, Other |
|
|
60
|
+
| **Shell** | Dropdown: bash, zsh, fish, Other |
|
|
61
|
+
|
|
62
|
+
#### Optional Fields
|
|
63
|
+
|
|
64
|
+
| Field | Description |
|
|
65
|
+
|-------|-------------|
|
|
66
|
+
| **Relevant Logs** | Log output (auto-formatted as code block) |
|
|
67
|
+
| **Additional Context** | Screenshots, workarounds, extra info |
|
|
68
|
+
|
|
69
|
+
#### Example — Bug Report via CLI
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
gh issue create --template "bug_report.yml" \
|
|
73
|
+
--title "fix(scripts): setup.sh fails on zsh with glob error" \
|
|
74
|
+
--body "
|
|
75
|
+
### Pre-flight Checks
|
|
76
|
+
- [x] I have searched existing issues and this is not a duplicate
|
|
77
|
+
- [x] I understand this issue needs status:approved before a PR can be opened
|
|
78
|
+
|
|
79
|
+
### Bug Description
|
|
80
|
+
Running setup.sh on zsh throws a glob error when no matching files exist.
|
|
81
|
+
|
|
82
|
+
### Steps to Reproduce
|
|
83
|
+
1. Clone the repo
|
|
84
|
+
2. Run \`./scripts/setup.sh\` in zsh
|
|
85
|
+
3. See error: \`zsh: no matches found: skills/*\`
|
|
86
|
+
|
|
87
|
+
### Expected Behavior
|
|
88
|
+
The script should handle missing glob matches gracefully.
|
|
89
|
+
|
|
90
|
+
### Actual Behavior
|
|
91
|
+
Script crashes with glob error.
|
|
92
|
+
|
|
93
|
+
### Operating System
|
|
94
|
+
macOS
|
|
95
|
+
|
|
96
|
+
### Agent / Client
|
|
97
|
+
Claude Code
|
|
98
|
+
|
|
99
|
+
### Shell
|
|
100
|
+
zsh
|
|
101
|
+
|
|
102
|
+
### Relevant Logs
|
|
103
|
+
\`\`\`
|
|
104
|
+
zsh: no matches found: skills/*
|
|
105
|
+
\`\`\`
|
|
106
|
+
"
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
### Feature Request
|
|
112
|
+
|
|
113
|
+
Template: `.github/ISSUE_TEMPLATE/feature_request.yml`
|
|
114
|
+
Auto-labels: `enhancement`, `status:needs-review`
|
|
115
|
+
|
|
116
|
+
#### Required Fields
|
|
117
|
+
|
|
118
|
+
| Field | Description |
|
|
119
|
+
|-------|-------------|
|
|
120
|
+
| **Pre-flight Checks** | Checkboxes: no duplicate + understands approval workflow |
|
|
121
|
+
| **Problem Description** | The pain point this feature solves |
|
|
122
|
+
| **Proposed Solution** | How it should work from the user's perspective |
|
|
123
|
+
| **Affected Area** | Dropdown: Scripts, Skills, Examples, Documentation, CI/Workflows, Other |
|
|
124
|
+
|
|
125
|
+
#### Optional Fields
|
|
126
|
+
|
|
127
|
+
| Field | Description |
|
|
128
|
+
|-------|-------------|
|
|
129
|
+
| **Alternatives Considered** | Other approaches or workarounds |
|
|
130
|
+
| **Additional Context** | Mockups, examples, references |
|
|
131
|
+
|
|
132
|
+
#### Example — Feature Request via CLI
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
gh issue create --template "feature_request.yml" \
|
|
136
|
+
--title "feat(scripts): add Codex support to setup.sh" \
|
|
137
|
+
--body "
|
|
138
|
+
### Pre-flight Checks
|
|
139
|
+
- [x] I have searched existing issues and this is not a duplicate
|
|
140
|
+
- [x] I understand this issue needs status:approved before a PR can be opened
|
|
141
|
+
|
|
142
|
+
### Problem Description
|
|
143
|
+
The setup script only configures Claude Code, Gemini CLI, and OpenCode. Codex users have to manually copy skills.
|
|
144
|
+
|
|
145
|
+
### Proposed Solution
|
|
146
|
+
Add a Codex option to setup.sh that links skills to the .codex/ directory.
|
|
147
|
+
|
|
148
|
+
Example:
|
|
149
|
+
\`\`\`bash
|
|
150
|
+
./scripts/setup.sh --agent codex
|
|
151
|
+
\`\`\`
|
|
152
|
+
|
|
153
|
+
### Affected Area
|
|
154
|
+
Scripts (setup, installation)
|
|
155
|
+
|
|
156
|
+
### Alternatives Considered
|
|
157
|
+
Manually symlinking, but that defeats the purpose of the setup script.
|
|
158
|
+
"
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Label System
|
|
164
|
+
|
|
165
|
+
### Applied Automatically on Issue Creation
|
|
166
|
+
|
|
167
|
+
| Template | Labels added |
|
|
168
|
+
|----------|-------------|
|
|
169
|
+
| Bug Report | `bug`, `status:needs-review` |
|
|
170
|
+
| Feature Request | `enhancement`, `status:needs-review` |
|
|
171
|
+
|
|
172
|
+
### Applied by Maintainers
|
|
173
|
+
|
|
174
|
+
| Label | When to apply |
|
|
175
|
+
|-------|--------------|
|
|
176
|
+
| `status:approved` | Issue accepted for implementation — PRs can now be opened |
|
|
177
|
+
| `priority:high` | Critical bug or urgent feature |
|
|
178
|
+
| `priority:medium` | Important but not blocking |
|
|
179
|
+
| `priority:low` | Nice to have |
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Maintainer Approval Workflow
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
1. New issue arrives with status:needs-review
|
|
187
|
+
2. Review the issue — is it valid, clear, and in scope?
|
|
188
|
+
3. If YES → add status:approved label
|
|
189
|
+
4. If NO → comment with reason, close if needed
|
|
190
|
+
5. Contributor can now open a PR linking this issue
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Decision Tree
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
Is it a bug? → Use Bug Report template
|
|
199
|
+
Is it a new feature/improvement? → Use Feature Request template
|
|
200
|
+
Is it a question? → Use Discussions, NOT issues
|
|
201
|
+
Is it a duplicate? → Link to existing issue, close
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Commands
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
# Search existing issues before creating
|
|
210
|
+
gh issue list --search "keyword"
|
|
211
|
+
|
|
212
|
+
# Create bug report
|
|
213
|
+
gh issue create --template "bug_report.yml" --title "fix(scope): description"
|
|
214
|
+
|
|
215
|
+
# Create feature request
|
|
216
|
+
gh issue create --template "feature_request.yml" --title "feat(scope): description"
|
|
217
|
+
|
|
218
|
+
# Maintainer: approve an issue
|
|
219
|
+
gh issue edit <number> --add-label "status:approved"
|
|
220
|
+
|
|
221
|
+
# Maintainer: add priority
|
|
222
|
+
gh issue edit <number> --add-label "priority:high"
|
|
223
|
+
```
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: judgment-day
|
|
3
|
+
description: "Trigger: judgment day, dual review, adversarial review, juzgar. Run blind dual review, fix confirmed issues, then re-judge."
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: gentleman-programming
|
|
7
|
+
version: "1.4"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Activation Contract
|
|
11
|
+
|
|
12
|
+
Load this skill only when the user explicitly asks for Judgment Day, dual/adversarial review, or equivalent Spanish trigger (`juzgar`, `que lo juzguen`). Review a specific target: files, feature, PR, or architecture slice.
|
|
13
|
+
|
|
14
|
+
## Hard Rules
|
|
15
|
+
|
|
16
|
+
- Resolve project skills before launching agents: read skill registry, match compact rules by target files/task, and inject the same `Project Standards` block into both judge prompts and fix prompts.
|
|
17
|
+
- Launch **two blind judges in parallel** with identical target and criteria; never review the code yourself.
|
|
18
|
+
- Wait for both judges before synthesis; never accept a partial verdict.
|
|
19
|
+
- Classify warnings as `WARNING (real)` only if normal intended use can trigger them; otherwise downgrade to INFO as `WARNING (theoretical)`.
|
|
20
|
+
- Ask before fixing Round 1 confirmed issues.
|
|
21
|
+
- After any fix agent runs, immediately re-launch both judges in parallel before commit/push/done/session summary.
|
|
22
|
+
- Terminal states are only `JUDGMENT: APPROVED` or `JUDGMENT: ESCALATED`.
|
|
23
|
+
- After 2 fix iterations with remaining issues, ask the user whether to continue.
|
|
24
|
+
|
|
25
|
+
## Decision Gates
|
|
26
|
+
|
|
27
|
+
| Condition | Action |
|
|
28
|
+
|---|---|
|
|
29
|
+
| Target unclear | Ask for scope; do not launch judges. |
|
|
30
|
+
| No skill registry | Warn, proceed with generic criteria, and record `Skill Resolution: none`. |
|
|
31
|
+
| Both judges find same CRITICAL/real WARNING | Confirmed; ask/fix according to round rules. |
|
|
32
|
+
| One judge finds issue | Suspect; report and triage, do not auto-fix. |
|
|
33
|
+
| Judges contradict | Escalate for manual decision. |
|
|
34
|
+
| Round 2+ has only theoretical warnings/suggestions | Report as INFO; do not re-judge. |
|
|
35
|
+
|
|
36
|
+
## Execution Steps
|
|
37
|
+
|
|
38
|
+
1. Confirm target and optional custom criteria.
|
|
39
|
+
2. Resolve compact project standards from registry or warn if missing.
|
|
40
|
+
3. Start Judge A and Judge B concurrently via delegation.
|
|
41
|
+
4. Synthesize findings into confirmed, suspect, contradiction, and INFO buckets.
|
|
42
|
+
5. Ask before Round 1 fixes; delegate a separate fix agent for confirmed approved fixes only.
|
|
43
|
+
6. Re-judge in parallel after fixes; repeat until approved, escalated, or user asks to stop.
|
|
44
|
+
7. Before any terminal action, verify every active Judgment Day has a terminal state.
|
|
45
|
+
|
|
46
|
+
## Output Contract
|
|
47
|
+
|
|
48
|
+
Return `## Judgment Day — {target}` with round number, verdict table, confirmed/suspect/contradiction counts, fixes applied, re-judgment result, `Skill Resolution`, and final `JUDGMENT: APPROVED ✅` or `JUDGMENT: ESCALATED ⚠️`.
|
|
49
|
+
|
|
50
|
+
## References
|
|
51
|
+
|
|
52
|
+
- [references/prompts-and-formats.md](references/prompts-and-formats.md) — judge/fix prompts, warning rubric, verdict tables, and language snippets.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Judgment Day Prompts and Formats
|
|
2
|
+
|
|
3
|
+
## Judge Prompt
|
|
4
|
+
|
|
5
|
+
```markdown
|
|
6
|
+
You are an adversarial code reviewer. Your ONLY job is to find problems.
|
|
7
|
+
|
|
8
|
+
## Target
|
|
9
|
+
{files, feature, architecture, component}
|
|
10
|
+
|
|
11
|
+
## Project Standards (auto-resolved)
|
|
12
|
+
{matching compact rules, if available}
|
|
13
|
+
|
|
14
|
+
## Review Criteria
|
|
15
|
+
- Correctness: logical errors and behavior mismatches
|
|
16
|
+
- Edge cases: missing states, inputs, or platform constraints
|
|
17
|
+
- Error handling: propagation, logging, recovery
|
|
18
|
+
- Performance: N+1, wasteful loops, excessive allocations
|
|
19
|
+
- Security: injection, secrets, auth boundaries
|
|
20
|
+
- Naming/conventions: project standards and local patterns
|
|
21
|
+
{custom criteria, if provided}
|
|
22
|
+
|
|
23
|
+
## Return Format
|
|
24
|
+
Findings only. No praise.
|
|
25
|
+
|
|
26
|
+
Each finding:
|
|
27
|
+
- Severity: CRITICAL | WARNING (real) | WARNING (theoretical) | SUGGESTION
|
|
28
|
+
- File: path/to/file.ext (line N if applicable)
|
|
29
|
+
- Description: what is wrong and why it matters
|
|
30
|
+
- Suggested fix: one-line intent
|
|
31
|
+
|
|
32
|
+
WARNING rule: normal intended use can trigger it → `WARNING (real)`; contrived/malicious/impossible path → `WARNING (theoretical)`.
|
|
33
|
+
|
|
34
|
+
If clean: `VERDICT: CLEAN — No issues found.`
|
|
35
|
+
|
|
36
|
+
Always end with: `Skill Resolution: {injected|fallback-registry|fallback-path|none} — {details}`.
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Fix Agent Prompt
|
|
40
|
+
|
|
41
|
+
```markdown
|
|
42
|
+
You are a surgical fix agent. Apply ONLY the confirmed issues listed below.
|
|
43
|
+
|
|
44
|
+
## Confirmed Issues to Fix
|
|
45
|
+
{confirmed findings table}
|
|
46
|
+
|
|
47
|
+
## Project Standards (auto-resolved)
|
|
48
|
+
{matching compact rules, if available}
|
|
49
|
+
|
|
50
|
+
## Instructions
|
|
51
|
+
- Fix only confirmed issues.
|
|
52
|
+
- Do not refactor beyond the required fix.
|
|
53
|
+
- Do not change unflagged code.
|
|
54
|
+
- If fixing a repeated pattern in touched files, fix all occurrences of that same pattern.
|
|
55
|
+
- Return changed file, line, and fix summary.
|
|
56
|
+
|
|
57
|
+
End with: `Skill Resolution: {injected|fallback-registry|fallback-path|none} — {details}`.
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Verdict Table
|
|
61
|
+
|
|
62
|
+
```markdown
|
|
63
|
+
| Finding | Judge A | Judge B | Severity | Status |
|
|
64
|
+
|---------|---------|---------|----------|--------|
|
|
65
|
+
| Missing null check in auth.go:42 | ✅ | ✅ | CRITICAL | Confirmed |
|
|
66
|
+
| Windows volume root edge case | ❌ | ✅ | WARNING (theoretical) | INFO |
|
|
67
|
+
| Naming mismatch | ✅ | ❌ | SUGGESTION | Suspect |
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Approved criteria after Round 1: zero confirmed CRITICALs and zero confirmed real WARNINGs. Theoretical warnings and suggestions may remain.
|
|
71
|
+
|
|
72
|
+
## Language Snippets
|
|
73
|
+
|
|
74
|
+
- Spanish: “Juicio iniciado”, “Los jueces trabajan en paralelo”, “Los jueces coinciden”, “Juicio terminado — Aprobado”, “Escalado — necesita revisión humana”.
|
|
75
|
+
- English: “Judgment initiated”, “Both judges are working in parallel”, “Both judges agree”, “Judgment complete — Approved”, “Escalated — requires human review”.
|