@ -105,6 +105,10 @@ When the user requests a durable behavior change, record it here or in the relev
- `src/runtime/` — Build runtimes and VFS config (see src/runtime/AGENTS.md)
- `src/doc/` — Generated documentation (see src/doc/AGENTS.md)
- `src/testansi/` — Sample ANSI art files (do not modify)
- `GOALS.md` — Top-level technical goal index; required read for non-trivial work (no child AGENTS.md; the file documents its own format and the agent goal-authoring workflow)
- `GOALS-archive.md` — One-line records of achieved goals moved out of the active index (historical context only)
- `goals/` — Optional detail prose for goals needing more than a one-line summary (see goals/AGENTS.md)
- `goals/archive/` — Detail files for achieved/archived goals
- Directories agents should not directly modify (no child DOX needed):
@ -116,9 +120,10 @@ When the user requests a durable behavior change, record it here or in the relev
## Repo-wide Notes
- ShellSpy (Punk Shell) is an experimental, alpha-level alternative Tcl shell under the BSD license; its primary language is Tcl.
- Punkshell (a.k.a. Punk Shell) is an experimental, alpha-level alternative Tcl shell under the BSD license; its primary language is Tcl. Note: "shellspy" (lowercase) refers only to the experimental `shellspy` subcommand available at launch — it is not the project name.
- The project extends Tcl with ANSI terminal capabilities, functional and pattern-matching language features, and a comprehensive module ecosystem.
- This root file is intentionally limited to DOX governance, global ownership boundaries, and the top-level Child DOX Index.
- Source-tree build, testing, linting, and file-resolution workflow lives in `src/AGENTS.md`.
- Tcl module authoring conventions live in `src/modules/AGENTS.md` and closer module child docs.
- If AGENTS.md conflicts with CLAUDE.md, AGENTS.md wins.
- Technical project goals live in root `GOALS.md` (index) with optional detail prose in `goals/G-<id>-<slug>.md`. Only the user adds or edits goals. Agents auto-flip a goal to `achieved <date>` when its stated acceptance criterion is met as part of the DOX closeout pass, and must flag `proposed`→`active` transitions in their completion report for user confirmation. See `GOALS.md` for the full workflow, including how to author a new goal when asked.
