punkshell/AGENTS.md

DOX framework

• DOX is highly performant AGENTS.md hierarchy installed here
• Agent must follow DOX instructions across any edits

Core Contract

• AGENTS.md files are binding work contracts for their subtrees
• Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it

Read Before Editing

1. Read the root AGENTS.md
2. Identify every file or folder you expect to touch
3. Walk from the repository root to each target path
4. Read every AGENTS.md found along each route
5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX

Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.

Re-reading on Recheck Queries

When asked to "recheck", "re-verify", "look again at", or similar re-query language for a topic, re-read the canonical source for that topic rather than relying on session memory. Session content is a cache, not a source of truth; the canonical file may have changed since it was last read. Examples: GOALS.md for goals, the nearest owning AGENTS.md for a subtree, punkproject.toml for project version. Re-scanning a directory for files not yet read this session is complementary, not a substitute for re-reading the canonical index.

Update After Editing

Every meaningful change requires a DOX pass before the task is done.

Update the closest owning AGENTS.md when a change affects:

• purpose, scope, ownership, or responsibilities
• durable structure, contracts, workflows, or operating rules
• required inputs, outputs, permissions, constraints, side effects, or artifacts
• user preferences about behavior, communication, process, organization, or quality
• AGENTS.md creation, deletion, move, rename, or index contents

Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.

Doc Restructures

Rules for any bulk restructure, normalisation, or migration of documentation (index reshapes, field-format normalisation, file moves/renames across many docs):

• Conservation check before committing: extract the deleted lines from the diff and account for every non-blank one - it must be relocated verbatim somewhere in the new tree, be pure boilerplate/stub text (e.g. "see index (canonical)" placeholders), or be a deliberate drop named explicitly in the commit message. A preservation claim in a commit message ("bodies preserved untouched") must be backed by this check, not intent. Mechanics: git diff | grep '^-[^-]' (or the VCS equivalent), then grep -F each deleted line against the restructured files.
• Structured-field normalisation is the highest-risk step: prose riding a structured line (a status field, a header mirror) is invisible to a "preserve bodies" intent and is exactly what normalisation deletes. Relocate such prose to a body section first, then normalise.
• Separate moves from edits: a file move/rename commit is content-identical; any reconciliation edits land in an adjacent commit. Combined move+edit diffs are where losses hide.

Hierarchy

• Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
• Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
• Each parent explains what its direct children cover and what stays owned by the parent
• The closer a doc is to the work, the more specific and practical it must be

Child Doc Shape

• Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
• Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
• Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists

Default section order:

• Purpose
• Ownership
• Local Contracts
• Work Guidance
• Verification
• Child DOX Index

Style

• Keep docs concise, current, and operational
• Document stable contracts, not diary entries
• Put broad rules in parent docs and concrete details in child docs
• Prefer direct bullets with explicit names
• Do not duplicate rules across many files unless each scope needs a local version
• Delete stale notes instead of explaining history
• Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist

Closeout

1. Re-check changed paths against the DOX chain
2. Update nearest owning docs and any affected parents or children
3. Refresh every affected Child DOX Index
4. Remove stale or contradictory text
5. Re-check modified .tm files for new procs lacking PUNKARGS argdoc blocks
6. Run existing verification when relevant
7. Report any docs intentionally left unchanged and why

User Preferences

When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md

• LF line endings are strongly preferred for all files in this repository. Converting a CRLF text file to LF when an edit touches it is correct and welcome - do not preserve CRLF for diff-minimisation. Preserve existing line endings only for files with deliberately mixed/CRLF endings (e.g. line-ending round-trip test data) or when explicitly instructed for a file.
• If the active editor is on a source-derived snapshot, bootstrap copy, or build output path such as src/bootsupport/, root modules/, root lib/, modules_tcl8/, modules_tcl9/, lib_tcl8/, or lib_tcl9/, confirm the intended target before editing unless the user explicitly named that path.
• cmd.exe PATH truncation (this machine, and any Windows machine with a heavily populated PATH): cmd.exe truncates a long PATH, so a tool that resolves fine in PowerShell may be "not found" when invoked via cmd.exe /c. Use absolute executable paths inside any cmd /c command line, and prefer PowerShell-native invocation unless a console host is specifically required (e.g. hidden-console test harnesses). If a tool is missing only under cmd.exe, suspect truncation before absence.
• Agent-authored text is plain ASCII by default: no em/en dashes, curly quotes, arrow or ellipsis characters, or other typographic Unicode - use ASCII equivalents (" - ", straight quotes, "->", "..."). This applies with extra force to outward-bound artifacts (ticket drafts, bug reports, emails, commit messages, anything likely to be pasted into an external system): those must be pure ASCII, verified before handover (e.g. grep for [^\x00-\x7F]). Legitimate exceptions: content whose subject matter is itself non-ASCII (encoding/Unicode/ANSI-art test data, or documentation demonstrating such behaviour), verbatim quotes of existing material, and cases where the user explicitly requests non-ASCII. Existing files are not to be bulk-retrofitted - the rule governs newly written text.
• Tcl has no -e/-c one-liner flag (a reflex agents carry over from perl/python/node). Stock tclsh/tclsh86/tclsh90 recognise only -encoding name as a leading option; any other argument starting with - is NOT treated as a script file - all arguments land in $argv and tclsh reads commands from stdin. On a console that hangs forever at an interactive prompt; with piped/redirected stdin it exits 0 having silently ignored the supposed one-liner and executed stdin instead. (The punk kits differ: they treat -e as a script filename and error out immediately - no hang, but still no one-liner.) To run ad-hoc Tcl: write a temp .tcl file and run tclsh path/to/file.tcl, or pipe the script to stdin (echo 'puts hi' | tclsh, or a bash heredoc). Defensive habit regardless: when exec'ing tclsh non-interactively, redirect stdin (</dev/null, < NUL) so a mis-invocation exits at EOF instead of hanging.
• Throwaway fossil repositories (test/experiment repos an agent creates, e.g. in a session scratchpad) must not register in the user's real global fossil config-db: fossil init/fossil open write persistent repo:/ckout: rows into %LOCALAPPDATA%\_fossil, which is the enumeration source for dev projects.work project discovery (G-016/G-017). Set FOSSIL_HOME to a disposable scratch directory for the duration of such fossil commands (both fossil and punk::repo::fossil_get_configdb honour it first). If pollution has already occurred: fossil all ignore <repo-path>, delete the directory, then any fossil all command prunes the orphaned ckout: row.
• Do not commit new executable binaries (shared libs, .exe, native .so/.dll/.dylib, bare ELF/Mach-O, or zip-based .tm modules embedding executables) to the repository. Existing binaries in bin/, src/vfs/, src/vendorlib/, src/vendormodules/, and src/bootsupport/ are there intentionally pending the build/retrieval infrastructure tracked by goals G-004/G-005/G-006; do not flag, "fix", or hassle the developer about these — they are known and will be removed once G-005 (zig build) or G-006 (pre-built download) provides an alternative. This rule stops agents from adding new binaries; it does not block the developer's interim commits of existing vendor/vfs binaries. It is workflow policy only - deliberately NOT enforced at the local VCS layer: fossil binary-glob is * (versioned in .fossil-settings/) so binary checkins proceed without warnings/prompts, here and in sub-projects like tomlish.

Commit Conventions (any VCS)

These conventions apply to every VCS commit an agent makes - git commits and fossil checkins alike. Projects generated from punkshell layouts start fossil-only but may adopt git (punkshell itself is currently git-primary); the conventions are VCS-neutral by design and are seeded into generated projects, where the project developer may change them.

• Never add "Co-Authored-By" lines or any AI-attribution footers to commit messages.
• When an agent constructs and executes the commit command itself (git commit, fossil commit - staging, composing the message, and committing), it must append one Assisted-by trailer as the last line of the commit message. If the user commits manually, no trailer is required. (git parses trailers structurally; fossil checkin comments are free text - in both cases the convention is simply the last line of the message.)
• Trailer format (single line, semicolon-separated key=value): Assisted-by: harness=<harness>; primary-model=<model-id>; api-location=<domain|localhost|localnet|unknown> Examples: Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai Assisted-by: harness=opencode; primary-model=lmstudio/qwen3-coder-next; api-location=localnet
• harness: derived from the agent identity / system prompt. Values: opencode, claude, pi, hermes, codex, or unknown.
• primary-model: the exact model ID string from the system prompt (e.g. openrouter/z-ai/glm-5.2). No transformation.
• api-location: best-effort, derived in this order:
  1. If the provider prefix (segment before / in the model ID) is in the table below, use the listed domain.
  2. Else if the provider is a known local-LLM provider (lmstudio, ollama, llamacpp, vllm, koboldcpp, llama.cpp), attempt to read the harness config for the baseURL: RFC1918 address → localnet; 127.0.0.1 or localhost → localhost; otherwise the hostname from the URL.
  3. Else → unknown. Known public provider table:

     Provider prefix	api-location
     openrouter	openrouter.ai
     anthropic	anthropic.com
     openai	openai.com
     google	googleapis.com
     mistral	mistral.ai
     groq	groq.com
     together	together.ai
     deepseek	deepseek.com
     x-ai / xai	x.ai

• secondary-models is intentionally omitted (not reliably introspectable). May be added later if a harness surfaces subagent model info.
• The Assisted-by trailer describes tooling, not authorship; it does not replace or conflict with the Co-Authored-By ban above.

Project Versioning

The punkshell project version is tracked in punkproject.toml ([project] version) at the repo root and is independent of individual module versions (those live in src/modules/*-buildversion.txt per src/modules/AGENTS.md "Versioning And Releases"). The project version describes the user-visible punkshell product, not any single module.

Bump policy (change-driven)

An agent must bump the punkproject.toml version as part of its DOX closeout pass whenever its change ships user-visible shell behaviour. This is change-driven, not release-driven — the version stays honest between releases.

• Patch — bug fixes, internal refactors, doc-only updates that ship in a build without changing user-facing shell behaviour.
• Minor — new shell commands, new launchers, new default modules visible at the REPL, backward-compatible behaviour additions.
• Major — removed commands, changed default behaviour, changed launch invocation, breaking changes to the shell's user-facing contract.

Changes confined to tests, build tooling internals, or non-shipped surfaces do not require a bump. When in doubt, bump patch.

The make.tcl command interface is part of the product surface: new subcommands, changed subcommand behaviour, or removed subcommands warrant at least a patch bump. Internal refactors of an existing subcommand's implementation that leave its interface and output unchanged stay exempt as build tooling internals.

Changelog

Every version bump must add a corresponding entry to CHANGELOG.md at the repo root. The latest ## [X.Y.Z] header in that file must match the version field in punkproject.toml. Entries are newest-first, one bullet per notable change.

Enforcement

tclsh src/make.tcl projectversion is a read-only check (never aborts, only warns) that:

1. Verifies the CHANGELOG.md latest version header matches punkproject.toml.
2. Checks whether src/ has git commits since the last commit touching punkproject.toml; if so, warns that a project-version bump may be overdue.

The check is advisory — it catches forgotten bumps, not hard errors. Agents should run it during closeout for any src/ change that ships behaviour, alongside existing make.tcl verification.

Relationship to module versions

The project version is fully independent of module versions. A module bump (even a major one) does not force a project bump unless the module's change is itself user-visible at the shell level. Conversely, a project bump does not require bumping any module.

Child DOX Index

• src/ — Source tree root; editable source code, build scripts, tests, VFS payloads, vendor deps, docs (see src/AGENTS.md)
  • src/modules/ — Main editable module source (see src/modules/AGENTS.md)
    • src/modules/punk/ — Core punk namespace modules (see src/modules/punk/AGENTS.md)
    • src/modules/test/ — Installed-module test packages (see src/modules/test/AGENTS.md)
    • src/modules/opunk/ — Alternative punk namespace, voo-based classes (see src/modules/opunk/AGENTS.md)
    • src/modules/punkcheck/ — Build/check system
  • src/modules_tcl8/ — Tcl 8 specific modules (see src/modules_tcl8/AGENTS.md)
  • src/modules_tcl9/ — Tcl 9 specific modules (see src/modules_tcl9/AGENTS.md)
  • src/lib/ — Editable library source (see src/lib/AGENTS.md)
  • src/lib_tcl8/ — Tcl 8 specific libraries
  • src/lib_tcl9/ — Tcl 9 specific libraries
  • src/bootsupport/ — Early-load bootstrap modules (see src/bootsupport/AGENTS.md)
  • src/tests/ — Source-tree test harness and tests (see src/tests/AGENTS.md)
  • src/vfs/ — Virtual file system images for builds (see src/vfs/AGENTS.md)
  • src/scriptapps/ — Entry-point scripts for Punk apps (see src/scriptapps/AGENTS.md)
  • src/vendormodules/ — Third-party bundled modules (see src/vendormodules/AGENTS.md)
  • src/vendorlib/ — Third-party bundled libraries (see src/vendorlib/AGENTS.md)
  • src/vendorlib_tcl8/ — Tcl 8 specific vendor libraries
  • src/vendorlib_tcl9/ — Tcl 9 specific vendor libraries
  • 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)
• bin/ — Built punk shell executables, launch package modes (incl. src mode for working-tree verification), plain runtime kits (see bin/AGENTS.md)
• .fossil-settings/ — Versioned fossil settings and the git+fossil dual-VCS coexistence contract: ignore-sync rules, files neither system may track (see .fossil-settings/AGENTS.md)
• GOALS.md — Top-level technical goal index, summary-only (ID, status, title, scope, detail pointer per goal); required read for non-trivial work (no child AGENTS.md; the file documents its own format, read workflow, and the agent goal-authoring workflow)
• GOALS-archive.md — Summary records of achieved goals moved out of the active index (historical context only)
• goals/ — Per-goal detail files carrying the canonical Goal/Acceptance contract prose plus supporting detail (see goals/AGENTS.md)
  • goals/archive/ — Detail files for achieved/archived goals
• Directories agents should not directly modify (no child DOX needed):
  • callbacks/ — Experimental shellspy features, user-only
  • scriptlib/ — Shared utilities + manual tests, user-only. EXCEPTIONS: scriptlib/_punktest/ is test-owned (fixtures for src/tests/shell/testsuites/punkexe/scriptexec.test, resolved via lib:_punktest/<name>); agents may manage that subfolder as part of test work. scriptlib/developer/ holds agent-authored developer showcase/demo apps and developer utility scripts (created at user request 2026-07-11, e.g tkconsole_demo.tcl for the G-001 tk console backend, goals_lint.tcl for the goals doc contracts per goals/AGENTS.md Verification); agents may add or update entries there when the user asks for one. The rest of scriptlib/ stays user-only.
  • bin/ — Built binaries and helpers, build output target. This includes the polyglot .cmd launcher/utility scripts (e.g bin/runtime.cmd): they are GENERATED by the punk::mix scriptwrap machinery from sources under src/scriptapps/ — a request to "fix bin/.cmd" means editing src/scriptapps/<name>.* + <name>_wrap.toml and re-wrapping (see bin/AGENTS.md), never editing the output
  • modules/ (root) — Build output target for tclsh src/make.tcl modules
  • lib/ (root) — Build output target for tclsh src/make.tcl libs
  • modules_tcl8/, modules_tcl9/ — Tcl version-specific build output targets
  • lib_tcl8/, lib_tcl9/ — Tcl version-specific build output targets
  • src/project_layouts/ — Project layout templates; partly updated by make.tcl bootsupport but full synchronisation requires manual work or future make.tcl improvements. Agents must not directly edit files under src/project_layouts/ unless the user explicitly names a path there or specifically requests layout changes. When a src/make.tcl change affects layout make.tcl files, note it in the completion report for the user to handle — do not attempt manual synchronisation.

Repo-wide Notes

• Punkshell (a.k.a. Punk Shell) is an experimental, alpha-level alternative Tcl shell licensed under BSD-2-Clause (see LICENSE.txt at the repo root); 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 (summary index: ID, status, title, scope, detail pointer per goal) with the canonical Goal/Acceptance contract prose in goals/G-<id>-<slug>.md detail files - read the detail file of every goal whose scope intersects paths being edited. Goals are user-owned: agents add or edit goal contract elements (in either tier) only at the user's request, proposal-first (show the proposed wording, get explicit approval before writing - see the GOALS.md maintenance rules); never on their own initiative. Suggesting candidate goals when work surfaces something goal-worthy is welcome and encouraged - as a flagged proposal, not a file edit. Non-contract detail-file updates from user-directed work need only be reported in the completion summary. Agents auto-flip a goal to achieved <date> when its detail-file acceptance criterion is met as part of the DOX closeout pass - the flip includes archiving the entry to GOALS-archive.md and the detail file to goals/archive/ - 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.