Skip to content

Commit e13433a

Browse files
mrjfmrjf
authored
Merge pull request #1 from githubnext/agentic-goal-workflow
Add Goal agentic workflow scaffold
2 parents f5f2cf2 + bc14c5c commit e13433a

9 files changed

Lines changed: 1257 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/goal.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: Goal
3+
about: Ask the Goal workflow to keep working until a verifiable outcome is done
4+
title: ''
5+
labels: goal
6+
---
7+
8+
<!-- GOAL:ISSUE -->
9+
<!-- Goal discovers open issues with the `goal` label. -->
10+
<!-- Make the completion contract concrete before relying on the workflow. -->
11+
12+
## Goal
13+
14+
<!-- What should be true when this is done? -->
15+
16+
REPLACE THIS with the desired outcome.
17+
18+
## Completion Contract
19+
20+
<!-- Define exactly when the workflow should add `goal-completed` and remove `goal`. -->
21+
22+
REPLACE THIS with the evidence-based definition of done.
23+
24+
## Evidence / Verification
25+
26+
<!-- List commands, tests, artifacts, screenshots, logs, or review checks that prove completion. -->
27+
28+
```bash
29+
REPLACE_WITH_VERIFICATION_COMMAND
30+
```
31+
32+
Completion requires: REPLACE THIS with the expected result.
33+
34+
## Scope and Constraints
35+
36+
<!-- List what the workflow may change and what must not regress. -->
37+
38+
Allowed files:
39+
- `REPLACE_WITH_PATH`
40+
41+
Do not change:
42+
- REPLACE THIS with protected behavior, files, APIs, or dependencies.
43+
44+
## Iteration Policy
45+
46+
<!-- How should the workflow choose the next checkpoint each run? -->
47+
48+
REPLACE THIS with the preferred iteration strategy.
49+
50+
## Blocked Stop Condition
51+
52+
<!-- When should the workflow stop substantive work and report a blocker instead of guessing? -->
53+
54+
REPLACE THIS with the condition and what information should be reported.

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
__pycache__/
2+
*.py[cod]

‎AGENTS.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Goal
2+
3+
Goal is an agentic workflow for durable, evidence-based GitHub issue work. It is
4+
built on GitHub Agentic Workflows and keeps one long-running branch and draft PR
5+
per goal issue.
6+
7+
## Architecture
8+
9+
```text
10+
goal/
11+
|-- AGENTS.md
12+
|-- README.md
13+
|-- install.md
14+
|-- workflows/
15+
| |-- goal.md
16+
| |-- shared/
17+
| | `-- reporting.md
18+
| `-- scripts/
19+
| `-- goal_scheduler.py
20+
|-- .github/
21+
| `-- ISSUE_TEMPLATE/
22+
| `-- goal.md
23+
`-- tests/
24+
`-- test_goal_scheduler.py
25+
```
26+
27+
## Conventions
28+
29+
- The workflow source is `workflows/goal.md`.
30+
- Installed repositories copy workflow files into `.github/workflows/`.
31+
- The scheduler writes `/tmp/gh-aw/goal.json` for the agent step.
32+
- Active goal issues are open GitHub issues with the `goal` label.
33+
- Completed issues have `goal-completed` and no `goal` label.
34+
- Each issue uses the exact branch from scheduler output:
35+
`goal/<issue-number>-<slugified-title>`.
36+
- The branch name must not include run IDs, suffixes, hashes, or random tokens.
37+
- Each issue has one draft PR with title `[Goal #<issue>] <title>`.
38+
- Every workflow run posts a new comment on the issue and updates the status
39+
comment marked `<!-- GOAL:STATUS -->`.
40+
- Durable state lives in repo-memory on the `memory/goal` branch.
41+
42+
## Editing
43+
44+
After modifying any workflow markdown under `workflows/`, run tests. In an
45+
installed target repository, also run:
46+
47+
```bash
48+
gh aw compile
49+
apm compile
50+
```
51+
52+
Commit generated workflow files together with source workflow changes when they
53+
exist.
54+
55+
Run the local scheduler tests with:
56+
57+
```bash
58+
python3 -m unittest discover -s tests -q
59+
```

‎README.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Goal
2+
3+
Goal turns a GitHub issue into a durable agentic workflow. Open an issue with the
4+
`goal` label, define what "done" means, and the workflow keeps working on the
5+
same branch and pull request until the evidence satisfies the goal. When it is
6+
done, the workflow adds `goal-completed` and removes `goal`.
7+
8+
Goal runs on [GitHub Agentic Workflows](https://github.github.com/gh-aw/setup/quick-start/)
9+
and [GitHub Copilot](https://github.com/features/copilot).
10+
11+
## Quick Start
12+
13+
Paste this into your favorite coding agent session on the repo where you want to
14+
run Goal:
15+
16+
```text
17+
Install goal using https://github.com/githubnext/goal/blob/main/install.md
18+
```
19+
20+
The agent will install GitHub Agentic Workflows if needed, copy the Goal
21+
workflow, compile it, create labels and issue templates, and help you turn your
22+
first rough idea into a concrete goal issue.
23+
24+
## How It Works
25+
26+
1. Create a GitHub issue with the `goal` label.
27+
2. Describe the outcome, completion contract, verification evidence, scope, and
28+
blocked stop condition.
29+
3. On each scheduled run, Goal selects one active issue, reads the issue and new
30+
comments, and advances the work on the canonical branch `goal/<issue>-<slug>`.
31+
4. The workflow keeps exactly one draft PR for that issue and updates the PR body
32+
as evidence changes.
33+
5. Every run posts a new comment on the goal issue and updates a status comment.
34+
6. When the completion contract is satisfied by concrete evidence, Goal comments
35+
with the evidence, adds `goal-completed`, and removes `goal`.
36+
37+
Goal stores durable state in repo-memory on the `memory/goal` branch. The state
38+
file records the issue, branch, PR, last run, current checkpoint, lessons,
39+
blockers, and run history. Humans can edit the issue or comment with steering;
40+
the next run treats that input as part of the active contract.
41+
42+
## Goal Issues
43+
44+
A good goal issue is a compact contract, not a vague backlog item. It should
45+
answer:
46+
47+
- **Outcome**: what should be true when the work is done.
48+
- **Evidence**: which commands, tests, files, screenshots, logs, or artifacts
49+
prove the outcome.
50+
- **Constraints**: what must not change, regress, or be modified.
51+
- **Boundaries**: which files, tools, services, or data the workflow may use.
52+
- **Iteration policy**: how the agent should choose the next action after each
53+
run.
54+
- **Blocked stop condition**: when the workflow should stop substantive work and
55+
report what would unlock progress.
56+
57+
Use the included issue template, or write the sections directly:
58+
59+
````markdown
60+
## Goal
61+
62+
Ship the new checkout retry path.
63+
64+
## Completion Contract
65+
66+
The retry path is implemented, old checkout behavior still passes its tests, and
67+
the issue can be closed when the commands below pass on the PR branch.
68+
69+
## Evidence / Verification
70+
71+
```bash
72+
npm test -- checkout
73+
npm run lint
74+
```
75+
76+
## Scope and Constraints
77+
78+
Allowed files:
79+
- `src/checkout/**`
80+
- `tests/checkout/**`
81+
82+
Do not change public API names or payment provider configuration.
83+
84+
## Iteration Policy
85+
86+
Prefer the smallest checkpoint that can be verified in one run. Read new human
87+
comments before choosing the next checkpoint.
88+
89+
## Blocked Stop Condition
90+
91+
If the tests require credentials or fixtures unavailable to the workflow, stop
92+
and comment with the missing item and the smallest reproducible evidence.
93+
````
94+
95+
## Branches And PRs
96+
97+
Each goal issue owns one long-running branch:
98+
99+
```text
100+
goal/<issue-number>-<slugified-title>
101+
```
102+
103+
Examples:
104+
105+
- `goal/42-fix-checkout-retry`
106+
- `goal/108-migrate-auth-tests`
107+
108+
Goal always reuses the same branch and the same draft PR for an issue. It never
109+
creates per-run branch suffixes, run IDs, or random tokens.
110+
111+
## Repository Structure
112+
113+
```text
114+
goal/
115+
|-- install.md
116+
|-- workflows/
117+
| |-- goal.md
118+
| |-- scripts/
119+
| | `-- goal_scheduler.py
120+
| `-- shared/
121+
| `-- reporting.md
122+
|-- .github/
123+
| `-- ISSUE_TEMPLATE/
124+
| `-- goal.md
125+
`-- tests/
126+
`-- test_goal_scheduler.py
127+
```
128+
129+
## Built On
130+
131+
- [GitHub Agentic Workflows](https://github.com/github/gh-aw)
132+
- [GitHub Copilot](https://github.com/features/copilot)
133+
- Goal-command ideas from Codex and Claude Code: durable objectives, explicit
134+
evidence, scoped continuation, and evidence-based completion.

0 commit comments

Comments
 (0)