Skip to content

Commit 230ab8f

Browse files
mrjfmrjf
committed
Add agent guidance for creating goals
1 parent f00202e commit 230ab8f

2 files changed

Lines changed: 198 additions & 9 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@ Goal is an Agentic Workflow for GitHub issues.
55
It does something similar to `/goal` in Codex and Claude Code, packaged as a
66
variant of the Autoloop agentic workflow pattern.
77

8-
Open an issue with the `goal` label and describe the outcome, completion
9-
criteria, verification evidence, and constraints. Goal works on the issue across
10-
runs using one long-running branch and PR. Each run comments on the issue. When
11-
the goal is complete, it adds `goal-completed` and removes `goal`.
8+
Use an agent to create a good goal issue, and sometimes a small setup PR, before
9+
the workflow starts. Goal then works on that issue across runs using one
10+
long-running branch and PR. Each run comments on the issue. When the goal is
11+
complete, it adds `goal-completed` and removes `goal`.
1212

1313
## Install
1414

@@ -20,8 +20,11 @@ Install the Goal Agentic Workflow using https://github.com/githubnext/goal/blob/
2020

2121
## Use
2222

23-
1. Install Goal.
24-
2. Open a GitHub issue with the `goal` label.
25-
3. Make the definition of done concrete and verifiable.
26-
4. Steer the work by commenting on the issue.
27-
5. Review the long-running Goal PR when it is ready.
23+
Paste this into your favorite coding agent to create a good goal:
24+
25+
```text
26+
Install the Goal Agentic Workflow using https://github.com/githubnext/goal/blob/main/new-goal.md
27+
```
28+
29+
The agent should help turn the work into a concrete, verifiable issue before
30+
the `goal` label is added.

‎new-goal.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Create A New Goal
2+
3+
This prompt guides you, a coding agent, to help a user create a strong Goal
4+
workflow issue. Do not simply open an issue and add the `goal` label. First make
5+
the goal actionable, verifiable, scoped, and safe for an agentic workflow to run
6+
without the user steering every turn.
7+
8+
Goal is inspired by `/goal` in Codex and Claude Code: one durable objective, a
9+
clear stopping condition, evidence that proves progress, and constraints that
10+
matter. In this repository workflow, that contract lives in a GitHub issue and
11+
the `goal` label starts the long-running Goal Agentic Workflow.
12+
13+
## Your Task
14+
15+
Work with the user to create one good goal. By the end, either:
16+
17+
1. Create a GitHub issue with the `goal` label.
18+
2. Create a small setup PR and an unlabelled draft goal issue, if the repo needs
19+
a helper script, fixture, test harness, or other setup before the Goal
20+
workflow can judge doneness reliably.
21+
3. Stop and explain what information is missing, if the goal cannot yet be made
22+
actionable.
23+
24+
Prefer keeping everything in the issue. Create a setup PR only when the issue
25+
alone would make the Goal workflow guess or repeatedly fail.
26+
27+
## What Makes A Good Goal
28+
29+
A good goal is bigger than one prompt but smaller than an open-ended backlog. It
30+
has:
31+
32+
- One objective, not a loose list of unrelated tasks.
33+
- A verifiable stopping condition.
34+
- A stated check: command, script, artifact, screenshot, log, file count, empty
35+
queue, or other evidence.
36+
- Constraints that must hold while the work is done.
37+
- Pointers to the files, docs, issues, logs, designs, or examples the agent must
38+
read first.
39+
- Checkpoints small enough for the workflow to make progress and report clearly.
40+
- A blocked stop condition so the workflow knows when to pause instead of
41+
inventing missing requirements.
42+
43+
Avoid vague goals such as "improve auth", "clean up tests", or "make the UI
44+
better" unless you turn them into a concrete contract.
45+
46+
## Creation Flow
47+
48+
1. Read the repository enough to understand the user's request.
49+
2. Restate the intended outcome in one sentence.
50+
3. Identify what would prove the outcome is done.
51+
4. Identify what must not change.
52+
5. Decide whether doneness can be judged from commands or scripts written in the
53+
issue.
54+
6. If not, propose the smallest setup PR that would make doneness checkable.
55+
7. Draft the goal issue.
56+
8. Ask the user to confirm any uncertain product, design, or policy detail.
57+
9. Create the issue only after the contract is strong.
58+
10. Add the `goal` label only when the workflow can safely start.
59+
60+
## Doneness Checks
61+
62+
The issue may include a doneness script directly in a fenced code block. This is
63+
often the best path because the Goal workflow can copy or run the script without
64+
requiring repo changes.
65+
66+
Use an inline script when:
67+
68+
- It only calls existing repo commands.
69+
- It checks existing files, logs, endpoints, snapshots, or artifacts.
70+
- It can be pasted into a shell safely.
71+
- It does not require secrets the workflow lacks.
72+
73+
Example:
74+
75+
````markdown
76+
## Evidence / Verification
77+
78+
Run this from the repository root:
79+
80+
```bash
81+
set -euo pipefail
82+
npm test -- tests/auth
83+
npm run lint
84+
! rg "legacyAuthHelper" tests/auth
85+
```
86+
87+
Completion requires all commands to exit 0.
88+
````
89+
90+
Create a setup PR when:
91+
92+
- The check needs a reusable helper script or fixture.
93+
- The repo has no command that can judge the goal.
94+
- CI needs a new target, package script, or test harness.
95+
- The check would be too long or fragile to live only in the issue.
96+
- The workflow needs files that should be reviewed before autonomous work
97+
starts.
98+
99+
If you create a setup PR, keep it tiny and mechanical. It should add the minimum
100+
doneness check, not implement the goal itself. Leave the goal issue unlabelled
101+
until that PR is merged, unless the user explicitly wants the Goal workflow to
102+
make the setup PR as its first checkpoint.
103+
104+
## Goal Issue Template
105+
106+
Use this structure:
107+
108+
````markdown
109+
## Goal
110+
111+
<One sentence describing the end state.>
112+
113+
## Completion Contract
114+
115+
The Goal workflow should add `goal-completed` and remove `goal` only when:
116+
117+
- <Required condition 1>
118+
- <Required condition 2>
119+
- <Required condition 3>
120+
121+
## Evidence / Verification
122+
123+
<Commands, inline script, screenshots, logs, artifacts, or review checks that
124+
prove the completion contract. Include exact expected outcomes.>
125+
126+
```bash
127+
<optional inline doneness script>
128+
```
129+
130+
## Scope and Constraints
131+
132+
The workflow may change:
133+
- `<path or area>`
134+
135+
The workflow must not change:
136+
- <protected behavior, API, dependency, data, or file>
137+
138+
## Context To Read First
139+
140+
- <files, docs, issues, PRs, logs, designs, references>
141+
142+
## Iteration Policy
143+
144+
Work in small checkpoints. After every run, report:
145+
- what changed
146+
- what was verified
147+
- what remains
148+
- whether anything is blocked
149+
150+
Prefer the smallest next checkpoint that can be validated with the evidence
151+
above.
152+
153+
## Blocked Stop Condition
154+
155+
Stop substantive work and comment instead of guessing if:
156+
- <missing secret, product decision, fixture, dependency, environment, or
157+
irreducible ambiguity>
158+
159+
The blocked comment should include the exact evidence gathered and the smallest
160+
user action that would unblock the workflow.
161+
````
162+
163+
## Quality Bar
164+
165+
Before creating or labelling the issue, check:
166+
167+
- Can another agent read the issue and know what to do first?
168+
- Can the Goal workflow tell the difference between "done", "not done yet", and
169+
"blocked"?
170+
- Is the verification evidence observable from the issue, the repo, a PR, or
171+
the workflow log?
172+
- Are the constraints specific enough to prevent accidental broad rewrites?
173+
- Is the goal one coherent objective?
174+
- Is any setup PR genuinely necessary, or can the check live in the issue?
175+
176+
## GitHub Actions
177+
178+
If the repository has GitHub CLI available and authenticated, create the issue
179+
with:
180+
181+
```bash
182+
gh issue create --title "<short goal title>" --body-file /tmp/goal-issue.md --label goal
183+
```
184+
185+
If you created a setup PR first, omit `--label goal` and tell the user to add
186+
the label after the setup PR merges.

0 commit comments

Comments
 (0)