punkshell/goals/AGENTS.md

goals/

Purpose

Holds optional detail prose for goals in the root GOALS.md index that need more than a one-line summary to state properly. The index entry is canonical; a detail file only elaborates and never contradicts its index entry.

Ownership

• Files here are owned by the goal authoring workflow described in root GOALS.md.
• Only the user adds or edits goals. Agents may draft detail files for user review but must not invent goals.
• The root GOALS.md index entry is the source of truth. If index and detail disagree, the index wins; fix the detail.

Local Contracts

When a detail file is warranted

A goal earns a detail file when it has any of:

• Non-obvious rationale (rejected alternatives, constraints discovered, why it is not done the obvious way)
• Multi-phase plan with sub-acceptance criteria
• External references or prior art worth citing
• More than ~3 lines of prose to state properly

Simple goals with a clear one-liner and measurable acceptance stay index-only. Do not create empty detail files for completeness.

Naming

G-<id>-<slug>.md — e.g. G-007-bytecompiler.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 (suggested)

# G-<id> <short title>

Status: <as in index>
Scope: <as in index>
Acceptance: <as in index>

## 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>

Archive

• goals/archive/ holds detail files for goals that have been achieved and moved to GOALS-archive.md.
• On archive: move goals/G-<id>-<slug>.md → goals/archive/G-<id>-<slug>.md. Do not rename the ID prefix.
• No orphan detail files: every file under goals/ (excluding archive/ and this AGENTS.md) must correspond to an active or proposed entry in the root GOALS.md index.

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)