From bdd47cd5d15049d46c38969e30b6f754356431ba Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Mon, 22 Jun 2026 02:37:18 +1000 Subject: [PATCH] further AGENTS.md refactor --- .fossil-settings/ignore-glob | 17 ++++++++++++++++- .gitignore | 2 ++ AGENTS.md | 2 ++ CLAUDE.md | 7 +++++++ src/AGENTS.md | 2 ++ src/modules/AGENTS.md | 13 +++++++++++++ 6 files changed, 42 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/.fossil-settings/ignore-glob b/.fossil-settings/ignore-glob index 2c3ee2d2..f33667c5 100644 --- a/.fossil-settings/ignore-glob +++ b/.fossil-settings/ignore-glob @@ -1,12 +1,24 @@ .git CVS -bin +bin/*.exe +bin/*.zip +bin/*.bak +bin/*.ps1 +bin/tools +bin/runtime +bin/*test* lib #The directory for compiled/built Tcl modules modules #The buildsuites output folder builds +localdoc + +.vscode +.claude +.omo + #Temporary files e.g from tests tmp @@ -15,6 +27,7 @@ _aside #working directories _build +src/_build src/docgen #Built documentation @@ -45,3 +58,5 @@ debug build build-* docgen_tmp + +~ diff --git a/.gitignore b/.gitignore index bb4bdacc..cc3fc2cd 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,8 @@ /tmp/ .vscode +.claude +.omo /logs/ **/_aside/ diff --git a/AGENTS.md b/AGENTS.md index 61c01c21..29edd2b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -113,6 +113,8 @@ 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. +- 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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..1465d6e7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# CLAUDE.md + +AGENTS.md is the source of truth for this repository, including for Claude harnesses. + +Before working, read and follow the root `AGENTS.md`, then read and follow any nested `AGENTS.md` files that apply to the paths being inspected or edited. + +If this file conflicts with `AGENTS.md`, `AGENTS.md` wins. diff --git a/src/AGENTS.md b/src/AGENTS.md index 96d75176..c0fc911b 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -13,6 +13,8 @@ The source tree root contains all editable source code, build scripts, test suit ## Local Contracts - `make.tcl` is the primary build entry point: `tclsh src/make.tcl `. +- The build system handles bootstrap loading, version assignment, module/library packaging, and VFS packaging. +- Shell launcher entry points include `tclsh src/make.tcl shell`, built launchers under the project `bin/` directory, scripts sourced from `src/scriptapps/`, and executable entry scripts under `src/vfs/_config/`. - Tcl 8.6+ is required and Tcl 9.0 is supported; gate 9.0-specific behavior behind version checks or existing `punk::lib::compat` helpers. - Primary target is Windows (`win32-x86_64`); Linux, macOS, and FreeBSD are secondary targets. - Tcl linting is available only through the VS Code Tcl lint plugin configured by `tclint.toml`; do not try to run `tclint` or `tcllint` as shell commands. diff --git a/src/modules/AGENTS.md b/src/modules/AGENTS.md index cd9dd217..70e6d36a 100644 --- a/src/modules/AGENTS.md +++ b/src/modules/AGENTS.md @@ -25,6 +25,15 @@ Source of truth for all editable Punk project modules. This is where agents shou - For optional features, probe with `if {[catch {package require foo}]} { ... }` and degrade gracefully. - Vendormodules, bootsupport snapshots, VFS modules, and built output modules do not use the magic version scheme unless their own local docs explicitly say otherwise. +### Module Subsystems + +- Terminal/display modules include `punk::ansi` for ANSI codes, cp437, and Sixel support; `punk::console`; `textblock` for text composition and framing; and `overtype` for text overlay. +- Shell modules include `punk::repl`, `punk::shellrun` for `run`/`runout`/`runerr`/`runx`, and `punk::nav::ns` for namespace browsing. +- Functional and pattern modules include `pattern` and `patterncmd`; treat them as experimental and use them only with user instruction or confirmation. +- Argument handling uses `punk::args` for processing, validation, and documentation generation; prefer it for public APIs and user-facing utilities unless the code path is performance critical. +- Networking modules include `punk::imap4`, `punk::netbox`, `punk::basictelnet`, and `punk::net::vxlan`. +- Plugin and capability provider/handler support uses `punk::cap`. + ## Work Guidance - Treat `src/modules/` as the source of truth for generic editable Punk modules. @@ -155,6 +164,10 @@ if {[catch {some_command} result]} { ### Pipeline And Functional Style Notes - Punk Pipeline functionality is experimental and should usually be avoided in agent-generated code unless the user specifically requests it. +- Pipeline syntax includes forms such as `var.= command1 |> command2 |> command3`. +- Pattern-match assignment syntax includes forms such as `x@0,y@1,z@2.= list a b c`, where `@` targets an index and `/` is range-safe. +- Destructuring examples include `x@end/@@k1.= list {k1 aaa} {k1 bb}`. +- `.=` means following args form a command; `=` accepts a single value. - Use `% var = ...` bindings to capture intermediate values; keep names meaningful. - `pipecase` should list specific patterns before catch-alls to avoid hidden matches. - `fun name pattern { ... }` definitions should remain side-effect light; treat them as pure functions unless otherwise documented.