punkshell/goals/AGENTS.md

goals/

Purpose

Holds the per-goal detail files for the root GOALS.md index. Every goal has a detail file: it carries the goal's canonical contract prose (Goal: and Acceptance:) plus any supporting detail (context, approach, decisions, verification records). The index entry in root GOALS.md stays summary-only (ID, status, title, Scope, detail pointer).

Ownership

• Files here are owned by the goal authoring workflow described in root GOALS.md.
• Goals are user-owned: agents add or edit goals only at the user's request or with explicit approval, proposal-first for any contract element (see the root GOALS.md maintenance rules). The contract spans both tiers: the index entry (title, status, Scope) and this folder's Goal:/Acceptance: lines. Agents must not write goals on their own initiative - suggesting candidate goals for user approval is welcome and encouraged.
• Non-contract content (Context, Approach, Alternatives, Notes, Progress, findings, decisions, verification artifacts) may be updated without pre-approval during user-directed work on the goal or its subject matter; report such updates in the completion summary.
• Canonicality split: a detail file is canonical for its Goal: and Acceptance:; the root index is canonical for ID, status, title and Scope. The Status:/Scope: lines here mirror the index - if they disagree, the index wins and the mirror here is fixed.

Local Contracts

One detail file per goal

Every entry in root GOALS.md has exactly one detail file here. A minimal detail file is just the header block below - do not pad it with empty sections; add Context/Approach/etc. only when there is real content.

Naming

G-<id>-<slug>.md — e.g. G-013-raw-mode-default.md. The <id> is the stable reference (taken from the G-<id> in the root index); the slug is human-readable and may change without breaking links as long as the ID prefix is preserved. Sortable by ls goals/.

Detail file structure

Required header (the first lines of every detail file):

# G-<id> <short title>

Status: <as in index>
Scope: <as in index>
Goal: <canonical - outcome-focused statement of what done looks like>
Acceptance: <canonical measurable, verifiable pass/fail criterion>

Optional sections after the header, only when they have real content:

## Context
<why this goal exists, what problem it solves>

## Approach
<chosen direction, key design decisions>

## Alternatives considered
- <alt A> — rejected because <reason>
- <alt B> — deferred, see G-NNN

## Notes
<implementation notes, references, links, findings, verification records>

## Progress
<active goals worked incrementally: what landed (dated), what remains for acceptance>

Progress tracking (active goals)

When user-directed work on an active goal lands without satisfying its Acceptance:, record it in the detail file's ## Progress section: what landed (dated) and what remains for acceptance. Progress is non-contract content — updatable without pre-approval, reported in the completion summary. The achieved flip requires the remaining-work list to be resolved (empty, or each item verified satisfied); a partial increment never flips a goal. Increment numbering in commit messages is free-form and carries no contract meaning.

Archive

• goals/archive/ holds detail files for achieved goals. Archiving happens as part of the achieved flip (see the root GOALS.md maintenance rules): the detail file moves goals/G-<id>-<slug>.md → goals/archive/G-<id>-<slug>.md and the index entry moves to GOALS-archive.md. Do not rename the ID prefix.
• No orphan detail files: every file here (excluding archive/ and this AGENTS.md) corresponds to a proposed, active, abandoned or superseded entry in root GOALS.md; every file under archive/ corresponds to a record in GOALS-archive.md.

Work Guidance

LF line endings (per root AGENTS.md user preferences).

Verification

None — this folder is documentation only.

Child DOX Index

• archive/ — detail files for achieved/archived goals (no child AGENTS.md needed; this file's archive rules cover it)