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.

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.

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.
• 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.
• 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.

Git Commit Conventions

• Never add "Co-Authored-By" lines or any AI-attribution footers to commit messages.
• When an agent constructs and executes the git commit command itself (staging, composing the message, and committing), it must append one Assisted-by trailer as the last line of the commit body. If the user commits manually, no trailer is required.
• 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.

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)
• 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):
  • callbacks/ — Experimental shellspy features, user-only
  • scriptlib/ — Shared utilities + manual tests, user-only
  • bin/ — Built binaries and helpers, build output target
  • 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

Repo-wide Notes

• 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.