diff --git a/.agents/skills/tcl-nslist/SKILL.md b/.agents/skills/tcl-nslist/SKILL.md index 05b20db9..785d3ac2 100644 --- a/.agents/skills/tcl-nslist/SKILL.md +++ b/.agents/skills/tcl-nslist/SKILL.md @@ -1,6 +1,6 @@ --- name: tcl-nslist -description: Use when you need to discover what exists in a Tcl namespace or package in this repo - what commands/procs a namespace exposes, whether a helper already exists before writing one, or what an ensemble's implementation namespace contains. No specific command name needed (that's tcl-whatis). Runtime listing via punkshell using punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses. Auto-loads the package; sees runtime-generated commands grep cannot. +description: Use BEFORE writing any new Tcl helper and BEFORE starting work in a punk namespace/package in this repo - to discover what already exists: what commands/procs a namespace exposes, or what an ensemble's implementation namespace contains. Run it first; reserve grep for full-text source-pattern searches - this lists the live interpreter, so it sees runtime-generated commands, aliases and imports grep cannot. Cost: one sub-1s side-effect-free punkshell invocation. Via punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses; auto-loads the package. No specific command name needed - for a named command's definition site/interface use the tcl-whatis skill. --- # tcl-nslist @@ -14,9 +14,13 @@ auto-loads the providing package when the namespace is not yet populated. ## Command -Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works): +Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the +Bash tool; any punkshell kit works). Cost: sub-1s, no side effects. - punk91 src script scriptlib/developer/nslist.tcl ?-synopsis? ?-pathcommands? ... + punk91 src script lib:developer/nslist ?-synopsis? ?-pathcommands? ... + +`lib:developer/nslist` is punkshell script-path shorthand for +`scriptlib/developer/nslist.tcl`. - `` - namespace name or glob, qualified or not: `punk::ns` is listed as `::punk::ns::*`. If the namespace does not exist, `package require` of @@ -70,6 +74,9 @@ itself. executable answer instead. - Load noise ("src mode: registered ...") goes to stderr; read stdout only (append `2>/dev/null` in bash, `2>$null` in PowerShell). +- Prefer the Bash tool over the PowerShell tool for these invocations: + PowerShell-tool children get an attached console, which can flip punkshell's + colour/terminal detection and change output classification. - Only what is loaded in that session is reported. The script auto-requires the queried package, but a namespace can be populated further by other packages (e.g plugins) - an unexpectedly sparse listing may mean a related @@ -80,6 +87,6 @@ itself. - From Tcl code, the same data is available structurally: `punk::ns::get_ns_dicts ::the::ns::* ?-allbelow ? ?-nspathcommands ?` returns a list of dicts (keys documented - see - `punk91 src script scriptlib/developer/whatis.tcl -doc punk::ns::get_ns_dicts`), + `punk91 src script lib:developer/whatis -doc punk::ns::get_ns_dicts`), and `punk::ns::nslist_dict` accepts caller-relative globs. In an interactive punkshell the `n//` / `n///` aliases render the same information. diff --git a/.agents/skills/tcl-whatis/SKILL.md b/.agents/skills/tcl-whatis/SKILL.md index f1abaa67..4f5bd3eb 100644 --- a/.agents/skills/tcl-whatis/SKILL.md +++ b/.agents/skills/tcl-whatis/SKILL.md @@ -1,6 +1,6 @@ --- name: tcl-whatis -description: Use when you need to know how to call a Tcl command in this repo (including ensemble subcommands like 'string is'), where a proc is defined (file and line number), which module version is actually loaded, or what a proc's runtime body is. Runtime introspection via punkshell - reports resolved name, kind (proc/alias/ensemble), providing package + version, origin file, def file:line, and punk::args synopsis. Cheaper and more accurate than grep+read for interface questions, and the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill. +description: Use BEFORE reviewing, testing, editing, porting or relocating any Tcl command in this repo, and for any question about a command's definition site, calling interface, loaded module version, or runtime body (including ensemble subcommands like 'string is'). Run it first; reserve grep for full-text source-pattern searches - this repo has several coexisting copies of many modules and grep cannot tell you which copy is actually loaded. Cost: one sub-1s side-effect-free punkshell invocation. Reports resolved name, kind (proc/alias/ensemble), providing package + loaded version, origin file, def file:line, and punk::args synopsis; the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill. --- # tcl-whatis @@ -13,9 +13,13 @@ zipfs) is actually loaded. ## Command -Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works): +Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the +Bash tool; any punkshell kit works). Cost: sub-1s, no side effects. - punk91 src script scriptlib/developer/whatis.tcl ?-body? ?-doc? ?subcommand?... + punk91 src script lib:developer/whatis ?-body? ?-doc? ?subcommand?... + +`lib:developer/whatis` is punkshell script-path shorthand for +`scriptlib/developer/whatis.tcl`. - `` - Tcl command name, qualified or not (e.g. `punk::args::parse`, `corp`). If not already loaded, the longest namespace-prefix package match @@ -64,7 +68,7 @@ Ensembles report their namespace and subcommand map instead of `def:`. whatis needs a command name. For the discovery question - what commands and child namespaces a namespace or package exposes at all - use the tcl-nslist -skill (scriptlib/developer/nslist.tcl). whatis prints a redirect hint when the +skill (lib:developer/nslist). whatis prints a redirect hint when the queried name turns out to be a namespace rather than a command. ## Caveats @@ -76,6 +80,9 @@ queried name turns out to be a namespace rather than a command. in a `warning:` line. - Load noise ("src mode: registered ...") goes to stderr; read stdout only (append `2>/dev/null` in bash, `2>$null` in PowerShell). +- Prefer the Bash tool over the PowerShell tool for these invocations: + PowerShell-tool children get an attached console, which can flip punkshell's + colour/terminal detection and change output classification. - To edit a proc, go to the `def:` file:line and Read the file there; do not build edits from `-body` output text. - `def: (no proc definition found ...)` means the proc was generated at diff --git a/.claude/settings.json b/.claude/settings.json index c5c3710c..26ac10da 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -18,6 +18,16 @@ "Bash(tclsh90 scriptlib/developer/goals_lint.tcl *)", "Bash(/c/Users/sleek/AppData/Local/Apps/Tcl903/bin/tclsh90 scriptlib/developer/goals_lint.tcl *)", "Bash(\"C:/Users/sleek/AppData/Local/Apps/Tcl903/bin/tclsh.exe\" scriptlib/developer/goals_lint.tcl *)", + "Bash(bin/punk91 src script lib:developer/whatis *)", + "Bash(bin/punk91 src script lib:developer/nslist *)", + "Bash(./bin/punk91 src script lib:developer/whatis *)", + "Bash(./bin/punk91 src script lib:developer/nslist *)", + "Bash(punk91 src script lib:developer/whatis *)", + "Bash(punk91 src script lib:developer/nslist *)", + "PowerShell(bin/punk91 src script lib:developer/whatis *)", + "PowerShell(bin/punk91 src script lib:developer/nslist *)", + "PowerShell(./bin/punk91 src script lib:developer/whatis *)", + "PowerShell(./bin/punk91 src script lib:developer/nslist *)", "PowerShell(tclsh scriptlib/developer/goals_lint.tcl *)", "PowerShell(tclsh90 scriptlib/developer/goals_lint.tcl *)", "PowerShell(& \"C:\\Users\\sleek\\AppData\\Local\\Apps\\Tcl903\\bin\\tclsh90.exe\" scriptlib/developer/goals_lint.tcl *)", diff --git a/.claude/skills/tcl-nslist/SKILL.md b/.claude/skills/tcl-nslist/SKILL.md index 05b20db9..785d3ac2 100644 --- a/.claude/skills/tcl-nslist/SKILL.md +++ b/.claude/skills/tcl-nslist/SKILL.md @@ -1,6 +1,6 @@ --- name: tcl-nslist -description: Use when you need to discover what exists in a Tcl namespace or package in this repo - what commands/procs a namespace exposes, whether a helper already exists before writing one, or what an ensemble's implementation namespace contains. No specific command name needed (that's tcl-whatis). Runtime listing via punkshell using punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses. Auto-loads the package; sees runtime-generated commands grep cannot. +description: Use BEFORE writing any new Tcl helper and BEFORE starting work in a punk namespace/package in this repo - to discover what already exists: what commands/procs a namespace exposes, or what an ensemble's implementation namespace contains. Run it first; reserve grep for full-text source-pattern searches - this lists the live interpreter, so it sees runtime-generated commands, aliases and imports grep cannot. Cost: one sub-1s side-effect-free punkshell invocation. Via punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses; auto-loads the package. No specific command name needed - for a named command's definition site/interface use the tcl-whatis skill. --- # tcl-nslist @@ -14,9 +14,13 @@ auto-loads the providing package when the namespace is not yet populated. ## Command -Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works): +Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the +Bash tool; any punkshell kit works). Cost: sub-1s, no side effects. - punk91 src script scriptlib/developer/nslist.tcl ?-synopsis? ?-pathcommands? ... + punk91 src script lib:developer/nslist ?-synopsis? ?-pathcommands? ... + +`lib:developer/nslist` is punkshell script-path shorthand for +`scriptlib/developer/nslist.tcl`. - `` - namespace name or glob, qualified or not: `punk::ns` is listed as `::punk::ns::*`. If the namespace does not exist, `package require` of @@ -70,6 +74,9 @@ itself. executable answer instead. - Load noise ("src mode: registered ...") goes to stderr; read stdout only (append `2>/dev/null` in bash, `2>$null` in PowerShell). +- Prefer the Bash tool over the PowerShell tool for these invocations: + PowerShell-tool children get an attached console, which can flip punkshell's + colour/terminal detection and change output classification. - Only what is loaded in that session is reported. The script auto-requires the queried package, but a namespace can be populated further by other packages (e.g plugins) - an unexpectedly sparse listing may mean a related @@ -80,6 +87,6 @@ itself. - From Tcl code, the same data is available structurally: `punk::ns::get_ns_dicts ::the::ns::* ?-allbelow ? ?-nspathcommands ?` returns a list of dicts (keys documented - see - `punk91 src script scriptlib/developer/whatis.tcl -doc punk::ns::get_ns_dicts`), + `punk91 src script lib:developer/whatis -doc punk::ns::get_ns_dicts`), and `punk::ns::nslist_dict` accepts caller-relative globs. In an interactive punkshell the `n//` / `n///` aliases render the same information. diff --git a/.claude/skills/tcl-whatis/SKILL.md b/.claude/skills/tcl-whatis/SKILL.md index f1abaa67..4f5bd3eb 100644 --- a/.claude/skills/tcl-whatis/SKILL.md +++ b/.claude/skills/tcl-whatis/SKILL.md @@ -1,6 +1,6 @@ --- name: tcl-whatis -description: Use when you need to know how to call a Tcl command in this repo (including ensemble subcommands like 'string is'), where a proc is defined (file and line number), which module version is actually loaded, or what a proc's runtime body is. Runtime introspection via punkshell - reports resolved name, kind (proc/alias/ensemble), providing package + version, origin file, def file:line, and punk::args synopsis. Cheaper and more accurate than grep+read for interface questions, and the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill. +description: Use BEFORE reviewing, testing, editing, porting or relocating any Tcl command in this repo, and for any question about a command's definition site, calling interface, loaded module version, or runtime body (including ensemble subcommands like 'string is'). Run it first; reserve grep for full-text source-pattern searches - this repo has several coexisting copies of many modules and grep cannot tell you which copy is actually loaded. Cost: one sub-1s side-effect-free punkshell invocation. Reports resolved name, kind (proc/alias/ensemble), providing package + loaded version, origin file, def file:line, and punk::args synopsis; the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill. --- # tcl-whatis @@ -13,9 +13,13 @@ zipfs) is actually loaded. ## Command -Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works): +Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the +Bash tool; any punkshell kit works). Cost: sub-1s, no side effects. - punk91 src script scriptlib/developer/whatis.tcl ?-body? ?-doc? ?subcommand?... + punk91 src script lib:developer/whatis ?-body? ?-doc? ?subcommand?... + +`lib:developer/whatis` is punkshell script-path shorthand for +`scriptlib/developer/whatis.tcl`. - `` - Tcl command name, qualified or not (e.g. `punk::args::parse`, `corp`). If not already loaded, the longest namespace-prefix package match @@ -64,7 +68,7 @@ Ensembles report their namespace and subcommand map instead of `def:`. whatis needs a command name. For the discovery question - what commands and child namespaces a namespace or package exposes at all - use the tcl-nslist -skill (scriptlib/developer/nslist.tcl). whatis prints a redirect hint when the +skill (lib:developer/nslist). whatis prints a redirect hint when the queried name turns out to be a namespace rather than a command. ## Caveats @@ -76,6 +80,9 @@ queried name turns out to be a namespace rather than a command. in a `warning:` line. - Load noise ("src mode: registered ...") goes to stderr; read stdout only (append `2>/dev/null` in bash, `2>$null` in PowerShell). +- Prefer the Bash tool over the PowerShell tool for these invocations: + PowerShell-tool children get an attached console, which can flip punkshell's + colour/terminal detection and change output classification. - To edit a proc, go to the `def:` file:line and Read the file there; do not build edits from `-body` output text. - `def: (no proc definition found ...)` means the proc was generated at diff --git a/AGENTS.md b/AGENTS.md index 7761f55f..7f6bc413 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -213,7 +213,7 @@ The project version is fully independent of module versions. A module bump (even - 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`. -- Runtime Tcl command introspection for agents (resolved name/kind, subcommand-chain resolution e.g `string is`, providing package + loaded version, origin file, def file:line, punk::args synopsis; `-doc` = full plain-text argdoc of all forms): `punk91 src script scriptlib/developer/whatis.tcl ?-body? ?-doc? ?subcommand?...` - full usage and caveats in `.agents/skills/tcl-whatis/SKILL.md`. Its discovery counterpart for namespace/package contents (child namespaces with loadable-package markers, commands classified by kind, punk::args-documented commands, `-synopsis` whole-namespace usage lines - via `punk::ns::get_ns_dicts`, the `n//` machinery): `punk91 src script scriptlib/developer/nslist.tcl ?-synopsis? ?-pathcommands? ...` - see `.agents/skills/tcl-nslist/SKILL.md`. +- Runtime Tcl introspection DIRECTIVE for agents: to locate or characterize a Tcl command (definition site, calling interface, loaded module version, runtime body - including subcommand-chain resolution e.g `string is`), run `punk91 src script lib:developer/whatis ?-body? ?-doc? ?subcommand?...` FIRST; to discover what a namespace/package exposes (before writing a new helper, or when starting work in a namespace), run `punk91 src script lib:developer/nslist ?-synopsis? ?-pathcommands? ...` FIRST. Reserve grep for full-text/source-pattern searches: this repo has several coexisting copies of many modules, and grep alone cannot tell you which copy is actually loaded. Both are single sub-1s side-effect-free invocations from the repo root (`punk91` lives in `bin/`; `lib:developer/` = `scriptlib/developer/.tcl`). Full usage and caveats: `.agents/skills/tcl-whatis/SKILL.md` and `.agents/skills/tcl-nslist/SKILL.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--.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 ` 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.