Merge pull request #3 from githubnext/terse-readme-install

Tighten Goal README and creation flow

Author: mrjf

.github/ISSUE_TEMPLATE/goal.md

@@ -0,0 +1,136 @@
+name: Goal
+description: Create a verifiable Goal workflow issue
+title: "[Goal] "
+labels:
+  - goal
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form for one coherent Goal workflow objective with a clear stopping condition.
+
+        A good goal is bigger than one prompt but smaller than an open-ended backlog. It should tell the workflow what to do, what not to change, how to prove progress, and when to stop as blocked instead of guessing.
+
+        If the goal needs a helper script, fixture, package script, CI target, or other setup before doneness can be judged, ask an agent to use `new-goal.md` first and create the setup PR before submitting this form.
+
+  - type: input
+    id: goal
+    attributes:
+      label: Goal
+      description: State the desired end state in one sentence.
+      placeholder: "Migrate tests/auth from legacyAuthHelper to createTestSession."
+    validations:
+      required: true
+
+  - type: textarea
+    id: completion-contract
+    attributes:
+      label: Completion Contract
+      description: Define exactly when Goal should add `goal-completed` and remove `goal`.
+      placeholder: |
+        Goal is complete only when:
+        - Every test in tests/auth uses createTestSession.
+        - legacyAuthHelper has no remaining call sites in tests/auth.
+        - The auth test suite and lint pass.
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence / Verification
+      description: List the commands, scripts, artifacts, screenshots, logs, or checks that prove the completion contract.
+      placeholder: |
+        Run from the repository root:
+
+        ```bash
+        set -euo pipefail
+        npm test -- tests/auth
+        npm run lint
+        ! rg "legacyAuthHelper" tests/auth
+        ```
+
+        Completion requires every command to exit 0.
+    validations:
+      required: true
+
+  - type: textarea
+    id: doneness-script
+    attributes:
+      label: Optional Inline Doneness Script
+      description: If a compact script can judge completion, put it here. Prefer an inline script over a setup PR when it only calls existing repo commands.
+      render: bash
+      placeholder: |
+        set -euo pipefail
+        npm test -- tests/auth
+        npm run lint
+        ! rg "legacyAuthHelper" tests/auth
+    validations:
+      required: false
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope and Constraints
+      description: Say what the workflow may change and what must not change or regress.
+      placeholder: |
+        The workflow may change:
+        - tests/auth/**
+        - test/helpers/auth.ts
+
+        The workflow must not change:
+        - production authentication behavior
+        - public API names
+        - payment provider configuration
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context To Read First
+      description: Point the workflow at the files, docs, issues, PRs, logs, designs, references, or examples it should inspect before changing code.
+      placeholder: |
+        - tests/auth/session.test.ts
+        - test/helpers/auth.ts
+        - docs/testing/auth.md
+        - #123
+    validations:
+      required: true
+
+  - type: textarea
+    id: iteration-policy
+    attributes:
+      label: Iteration Policy
+      description: Explain how the workflow should choose each next checkpoint and report progress.
+      placeholder: |
+        Work in one coherent test group at a time. After each run, report what changed, what was verified, what remains, and whether anything is blocked. Prefer the smallest next checkpoint that can be validated with the evidence above.
+    validations:
+      required: true
+
+  - type: textarea
+    id: blocked-stop-condition
+    attributes:
+      label: Blocked Stop Condition
+      description: Define when the workflow should stop substantive work and comment instead of guessing.
+      placeholder: |
+        Stop and comment if tests require unavailable secrets, fixtures, product decisions, or external services. The blocked comment should include the exact command output, what is known, and the smallest user action that would unblock the workflow.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: readiness
+    attributes:
+      label: Ready To Start
+      description: Submitting this form applies the `goal` label and may start the workflow.
+      options:
+        - label: This goal does not need a setup PR before the workflow starts.
+          required: true
+        - label: This is one coherent objective, not a loose backlog.
+          required: true
+        - label: The completion contract has observable evidence.
+          required: true
+        - label: The constraints are specific enough to prevent accidental broad rewrites.
+          required: true
+        - label: The workflow can tell the difference between done, not done yet, and blocked.
+          required: true

.github/ISSUE_TEMPLATE/goal.yml

@@ -1,134 +1,30 @@
 # Goal
 
-Goal turns a GitHub issue into a durable agentic workflow. Open an issue with the
-`goal` label, define what "done" means, and the workflow keeps working on the
-same branch and pull request until the evidence satisfies the goal. When it is
-done, the workflow adds `goal-completed` and removes `goal`.
+Goal is an Agentic Workflow for GitHub issues.
 
-Goal runs on [GitHub Agentic Workflows](https://github.github.com/gh-aw/setup/quick-start/)
-and [GitHub Copilot](https://github.com/features/copilot).
+It does something similar to `/goal` in Codex and Claude Code, packaged as a
+variant of the Autoloop agentic workflow pattern.
 
-## Quick Start
+Use an agent to create a good goal issue, and sometimes a small setup PR, before
+the workflow starts. Goal then works on that issue across runs using one
+long-running branch and PR. Each run comments on the issue. When the goal is
+complete, it adds `goal-completed` and removes `goal`.
 
-Paste this into your favorite coding agent session on the repo where you want to
-run Goal:
+## Install
 
-```text
-Install goal using https://github.com/githubnext/goal/blob/main/install.md
-```
-
-The agent will install GitHub Agentic Workflows if needed, copy the Goal
-workflow, compile it, create labels and issue templates, and help you turn your
-first rough idea into a concrete goal issue.
-
-## How It Works
-
-1. Create a GitHub issue with the `goal` label.
-2. Describe the outcome, completion contract, verification evidence, scope, and
-   blocked stop condition.
-3. On each scheduled run, Goal selects one active issue, reads the issue and new
-   comments, and advances the work on the canonical branch `goal/<issue>-<slug>`.
-4. The workflow keeps exactly one draft PR for that issue and updates the PR body
-   as evidence changes.
-5. Every run posts a new comment on the goal issue and updates a status comment.
-6. When the completion contract is satisfied by concrete evidence, Goal comments
-   with the evidence, adds `goal-completed`, and removes `goal`.
-
-Goal stores durable state in repo-memory on the `memory/goal` branch. The state
-file records the issue, branch, PR, last run, current checkpoint, lessons,
-blockers, and run history. Humans can edit the issue or comment with steering;
-the next run treats that input as part of the active contract.
-
-## Goal Issues
-
-A good goal issue is a compact contract, not a vague backlog item. It should
-answer:
-
-- **Outcome**: what should be true when the work is done.
-- **Evidence**: which commands, tests, files, screenshots, logs, or artifacts
-  prove the outcome.
-- **Constraints**: what must not change, regress, or be modified.
-- **Boundaries**: which files, tools, services, or data the workflow may use.
-- **Iteration policy**: how the agent should choose the next action after each
-  run.
-- **Blocked stop condition**: when the workflow should stop substantive work and
-  report what would unlock progress.
-
-Use the included issue template, or write the sections directly:
-
-````markdown
-## Goal
-
-Ship the new checkout retry path.
-
-## Completion Contract
-
-The retry path is implemented, old checkout behavior still passes its tests, and
-the issue can be closed when the commands below pass on the PR branch.
-
-## Evidence / Verification
-
-```bash
-npm test -- checkout
-npm run lint
-```
-
-## Scope and Constraints
-
-Allowed files:
-- `src/checkout/**`
-- `tests/checkout/**`
-
-Do not change public API names or payment provider configuration.
-
-## Iteration Policy
-
-Prefer the smallest checkpoint that can be verified in one run. Read new human
-comments before choosing the next checkpoint.
-
-## Blocked Stop Condition
-
-If the tests require credentials or fixtures unavailable to the workflow, stop
-and comment with the missing item and the smallest reproducible evidence.
-````
-
-## Branches And PRs
-
-Each goal issue owns one long-running branch:
+Paste this into your favorite coding agent to install Goal in your repo:
 
 ```text
-goal/<issue-number>-<slugified-title>
+Install the Goal Agentic Workflow using https://github.com/githubnext/goal/blob/main/install.md
 ```
 
-Examples:
+## Use
 
-- `goal/42-fix-checkout-retry`
-- `goal/108-migrate-auth-tests`
-
-Goal always reuses the same branch and the same draft PR for an issue. It never
-creates per-run branch suffixes, run IDs, or random tokens.
-
-## Repository Structure
+Paste this into your favorite coding agent to create a good goal:
 
 ```text
-goal/
-|-- install.md
-|-- workflows/
-|   |-- goal.md
-|   |-- scripts/
-|   |   `-- goal_scheduler.py
-|   `-- shared/
-|       `-- reporting.md
-|-- .github/
-|   `-- ISSUE_TEMPLATE/
-|       `-- goal.md
-`-- tests/
-    `-- test_goal_scheduler.py
+Install the Goal Agentic Workflow using https://github.com/githubnext/goal/blob/main/new-goal.md
 ```
 
-## Built On
-
-- [GitHub Agentic Workflows](https://github.com/github/gh-aw)
-- [GitHub Copilot](https://github.com/features/copilot)
-- Goal-command ideas from Codex and Claude Code: durable objectives, explicit
-  evidence, scoped continuation, and evidence-based completion.
+The agent should help turn the work into a concrete, verifiable issue before
+the `goal` label is added.