docs: add AI agent guides (AGENTS.md) by plavjanik · Pull Request #894 · zowe/zowex

plavjanik · 2026-03-29T11:56:38Z

Summary

This PR introduces AGENTS.md files at the repository root and under native/ following
the AGENTS.md open-source convention — a project-level briefing
document for AI coding agents (supported by Cursor, Claude Code, GitHub
Copilot, and others).

The files were extracted from #867 to keep that PR focused on the USS issue-command
feature and allow broader discussion of the agent guide content here.

This document requires review of expects on Zowe Native Protocol!

Why AGENTS.md?

A README is written for human contributors. AGENTS.md is written for AI agents: it
documents the "tribal knowledge" a senior engineer carries — build commands, architectural
patterns, platform gotchas, and coding conventions — in a single predictable location that
AI tools discover automatically.

Top 5 general guidelines for AGENTS.md

These are the conventions recommended by the AGENTS.md specification:

Keep it concise — Aim for under 150 lines. Longer files reduce effectiveness; link
to full documentation rather than duplicating it inline.
Put it at the root — Place AGENTS.md at the repository root for automatic
discovery by all supported AI tools. Sub-project guides (e.g. native/AGENTS.md) are
linked from the root file.
Write for a new senior teammate — The goal is a quick briefing, not a wiki.
Include what a skilled engineer would need to be productive on day one: build/test
commands, architecture overview, and non-obvious conventions.
Focus on actionable instructions — Prefer "run npm run z:upload before
npm run z:test" over narrative descriptions. Agents act on instructions; they read
documentation for context.
Keep it current — Update AGENTS.md as part of the same PR that introduces an
architectural change or platform gotcha. A stale guide is worse than no guide because
it misleads agents confidently.

Top 5 best practices captured in these guides

Native logging via ZLogger — Use ZLOG_DEBUG/ZLOG_WARN/ZLOG_ERROR macros
instead of std::fprintf(stderr, ...). Raw fprintf calls are invisible to the logging
system and pollute test output. A git diff check is documented for catching forgotten
debug prints before a PR is merged.
Two-layer SDK errors — Errors surfaced to a client UI must use ImperativeError
with a jargon-free msg (shown in the VSCode notification bubble) and technical
additionalDetails (shown in "Show Details"). Never pass raw command strings or return
codes directly to the user.
Route errors through onError, throw as fallback — SDK utility functions that
accept an ISshCallbacks options object must call options.onError when it is
registered and fall back to throwing only when there is no callback. This keeps VSCE
and CLI error surfaces consistent.
z/OS process creation — prefer spawn() over fork() — On z/OS USS, fork()
creates a new address space (expensive). Use spawn() + _BPX_SHAREAS=YES to run
child processes as a new TCB in the same address space. Identity-changing commands
(newgrp, su, sg) are the documented exception.
Keep AGENTS.md current — When an architectural decision or platform-specific
gotcha is discovered, update the relevant AGENTS.md as part of the same change, not
in a follow-up. The guide is consumed by AI agents and human developers alike —
accuracy matters more than prose.

References

agents.md — the open-source AGENTS.md specification
feat(uss): add issue command for shell execution using spawn() #867 — the feature PR this was extracted from

Made with Cursor

Add AGENTS.md at the repo root and native/AGENTS.md for the native C++ sub-project, following the https://agents.md/ open-source convention. These files give AI coding agents (Cursor, Claude Code, OpenAI Codex, GitHub Copilot, etc.) the project-specific context they need to work effectively: build/test commands, architectural patterns, platform gotchas, and coding conventions in a single discoverable location. Key guidelines documented: - Native logging: use ZLogger macros, never std::fprintf(stderr) - SDK errors: ImperativeError with user-friendly msg + additionalDetails - Error routing: onError callback when registered, throw as fallback - z/OS process creation: spawn()+SHAREAS=YES preferred over fork() - Changelog, versioning, SonarCloud, and Biome formatting conventions Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor

AGENTS.md and native/AGENTS.md are extracted to a separate PR (#894) for focused review. No functional changes. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor

github-actions · 2026-03-29T11:58:15Z

Client artifacts:

traeok

Thanks Petr, left a few suggestions

traeok · 2026-03-30T18:01:20Z

+- Use `zut_spawn_shell_command()` for shell commands (uses `spawn()` + `_BPX_SHAREAS=YES`)
+- `zut_run_program()` exists but uses `fork()`/`execvp()` — avoid for new command execution paths
+
+**Identity-changing commands (newgrp, su, sg):** Commands that change real/effective UID or GID are not supported in a shared address space ([IBM newgrp doc](https://www.ibm.com/docs/en/zos/3.2.0?topic=descriptions-newgrp-change-new-group)). `zut_spawn_shell_command()` detects when the user's command is one of `newgrp`, `su`, or `sg` (by parsing the first token) and in that case does **not** pass `_BPX_SHAREAS=YES` to the child, so the child runs in its own address space. To support additional such commands, add the command basename to `ZUT_NOSHAREAS_COMMANDS` in `zut.cpp`.


ZUT_NOSHAREAS_COMMANDS does not exist within the code on this branch. Is this added in a separate PR?

traeok · 2026-03-30T18:05:57Z

+
+### Expired password detection
+
+When an SSH session connects with an expired password, z/OS emits `FOTS1668`/`FOTS1669` on stderr. This can masquerade as SFTP failures or generic command errors. `ZSshUtils.routeExpiredPasswordError()` checks for these codes after every `execCommand` call: if an `onError` callback is registered it is called with an `ImperativeError` using `SshErrors.FOTS1668.summary` as the message (so the VSCE notification bubble shows a readable string); otherwise the error is thrown directly (preserving CLI behavior). The `errorCode` is always `"EPASSWD_EXPIRED"`.


The routeExpiredPasswordError function does not exist in the ZSshUtils class. The detection is currently handled inline in AbstractConfigManager.ts and SshCommonApi.ts.

traeok · 2026-03-30T18:07:47Z

+- **RPC dispatch**: `native/c/server/rpc_commands.cpp` maps JSON-RPC method names to native handler functions
+- **SDK bindings**: `packages/sdk/src/RpcClientApi.ts` maps client API methods to RPC method names
+- **SDK types**: `packages/sdk/src/doc/rpc/` contains TypeScript interfaces for each RPC request/response
+- **Command domains**: ds (data sets), uss (USS files), job (JES jobs), tso (TSO commands), tool (utilities)


(nitpick) Consider factoring in console and system groups from zowex to the list in the final bulleted item.

traeok · 2026-03-30T18:08:50Z

+
+## Test Framework
+
+- CLI tests: `c/test/zowex.<domain>.test.cpp` — use `execute_command_with_output()`


This doesn't apply to all test files, for example: zds.test.cpp, zjb.test.cpp, zut.test.cpp, etc.
Consider separating these into two points:

Suggested change

- CLI tests: `c/test/zowex.<domain>.test.cpp` — use `execute_command_with_output()`

- CLI-focused tests: `c/test/zowex.<domain>.test.cpp` — use `execute_command_with_output()`

- API tests: `c/test/<api>.test.cpp` — use direct API calls

traeok · 2026-03-30T18:11:54Z

+
+This applies to: code comments, usage examples, test scripts, markdown docs, commit messages, and any other checked-in artifact.
+
+## Maintaining This Guide


Since we are now enabling more AI interoperability through the AGENTS file, would we be opposed to adding rules as well? Most of the team leverages AI and could benefit from shared rules.

It doesn't have to be this PR, but just curious to know if the team would enjoy having them - I have a couple I could contribute

* feat(uss): add `issue` command for shell execution using spawn() Add `zut_spawn_shell_command()` utility using `spawn()` with `_BPX_SHAREAS=YES` for efficient same-address-space execution. Implement `uss issue` CLI subcommand, `unixCommand` RPC method, and corresponding SDK `uss.issueCmd()` with tests. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * Share the AGENTS.md files Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * fix: address SonarCloud issues in spawn utility - Extract poll-read loop into helper functions to reduce cognitive complexity and nesting depth in zut_spawn_shell_command - Replace C-style arrays with std::array - Use std::make_shared for Command construction Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor * fix: remove const_cast and fix environ declaration for SonarCloud - Remove const_cast by using types matching spawn() signature directly - Move extern environ declaration to file scope (standard POSIX pattern) - Use C-style argv array matching spawn() const char *argv[] parameter Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor * fix: resolve remaining SonarCloud issues in spawn utility - Replace C-style argv array with std::vector<const char *> - Extract environ access into static helper to isolate extern declaration - Remove file-scope extern for environ Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor * fix: remove explicit extern for environ (provided by unistd.h) Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor * fix: restore extern environ declaration for z/OS compilation z/OS unistd.h does not expose environ without an explicit extern declaration. Added NOSONAR comment since this is a POSIX-mandated global that cannot be const-qualified. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor * docs: Add SDK packaging and rebuild instructions to README and AGENTS.md Document the different SDK rebuild workflows depending on whether TypeScript, native code, or both have changed. Also remove the packages/sdk/.gitignore that was ignoring *.tgz files. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * feat(sdk): detect expired z/OS passwords during server install/uninstall Detect FOTS1668/FOTS1669 error codes in `ZSshUtils.installServer` and `uninstallServer`, throwing `ImperativeError` with `errorCode: "EPASSWD_EXPIRED"` to provide clear error messages instead of generic failures. Add `SshErrors` definition for FOTS1668 with troubleshooting tips. Update `AGENTS.md` with z/OS SSH file transfer, encoding, and maintenance guidelines. Include `test-install.ts` manual integration test and add unit tests for install/uninstall flows. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * docs(agents): Add z/OS binary build/run compatibility section Explain CEE3561S errors when running CA32-built binaries on older z/OS levels and provide mitigation strategies. Update VSCE test correlation count to include expired password detection. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * fix(sdk): correct error code display and improve test maintainability - Fix SFTP upload error to display RC=0 (was hidden by falsy check) - Refactor ZSshUtils tests to use setupSftpMocks helper reducing duplication - Improve type safety in test-install.ts using unknown instead of any - Add jscpd report to .gitignore and update VSCE test comments Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * Increase z/OS Build timeout to 30 Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * Add license Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * Update AGENTS.md Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * fix(native): prevent _BPX_SHAREAS for identity-changing commands Skip setting _BPX_SHAREAS=YES when spawning newgrp, su, or sg commands as they require UID/GID changes incompatible with shared address spaces. Also add bounds checking and debug logging to parmlib listing. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * wip! Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * chore(sdk): enable bundled dependencies for packaging Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * chore: add *.tgz to .gitignore Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * chore(sdk): remove bundled dependencies configuration Remove the `bundleDependencies` setting from package.json that was recently enabled, along with routine lockfile maintenance. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * refactor(native): eliminate duplicate poll-read loop in zut_private_run_program Use the shared zut_private_drain_fd/zut_private_drain_pipes helpers (already used by zut_spawn_shell_command) in zut_private_run_program, removing ~40 lines of duplicated inline poll-read logic. Add forward declarations so the helpers are visible before their definition. Add three regression tests verifying stdout/stderr separation, large output draining (>4096-byte pipe buffer), and merged-stream overload. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor * fix: address SonarCloud code quality issues - Replace C-style array with std::array for ZUT_NOSHAREAS_COMMANDS (cpp:S5945) - Flip negated condition in SFTP error handler to positive case (typescript:S7735) - Fix potential [object Object] stringification in test-install error message (typescript:S6551) - Add NOSONAR for async IIFE: top-level await is unavailable with module:commonjs (typescript:S7785) - Move setupSftpMocks helper to module scope in ZSshUtils tests (typescript:S7721) Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor * fix(native): append newlines to TSO and USS command output Add missing newline characters to the end of command responses in handle_tso_issue and handle_uss_issue_cmd to ensure proper terminal formatting. Include comment explaining expected TTY behavior differences when USS commands are executed via pipes (non-interactive defaults). Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * chore(sdk): format long lines for readability Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * docs(agents): add Biome TypeScript formatting section Document Biome formatting and linting requirements for TypeScript files, including CI enforcement, local development commands, and inline rule suppression examples. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * docs: update changelogs and AGENTS.md for PR #867 Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor * fix(build): simplify regex patterns and ensure stderr warnings are printed Remove unnecessary backslash escapes from hyphen characters in test failure regex patterns. Add logic to print stderr output (warnings) that wasn't already streamed live when running shell commands. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * docs(agents): document compiler warning checking for z/OS builds Add instructions for viewing compiler warnings from z/OS builds and identifying whether they are pre-existing or introduced by the current PR. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * docs(agents): add hygiene guidelines and sanitize internal system references Add "Code & Documentation Hygiene" section prohibiting real hostnames, system names, and user IDs in source code and documentation. Replace specific infrastructure references with generic terms in the binary compatibility section. Update test-install.ts examples to use placeholder values. Remove packages/vsce/AGENTS.md. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * unify run_program and spawn_shell Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> * finish implementation, fix broken tests Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> * fallback to $SHELL env Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> * refactor(native): replace fprintf with ZLogger macros Add logging guidelines to AGENTS.md and migrate native C++ source and test files to use ZLOG_DEBUG/ZLOG_WARN macros instead of std::fprintf/std::fflush for diagnostic output. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * chore(sdk): remove manual test scripts Delete temporary integration test files (test-install.ts and test.ts) that were used for manual validation but are not part of the automated test suite. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * refactor(sdk): route errors through onError with user-friendly messages Standardize SDK error handling to use ImperativeError with msg/additionalDetails and route through onError callbacks when available (preserving CLI throw behavior as fallback). Update expired password detection to use SshErrors.FOTS1668.summary for consistent user-facing messages. Add SDK error handling guidelines to AGENTS.md documenting the two-layer error pattern for UI surfaces. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> * docs: move AGENTS.md files to dedicated PR #894 AGENTS.md and native/AGENTS.md are extracted to a separate PR (#894) for focused review. No functional changes. Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Made-with: Cursor --------- Signed-off-by: Petr Plavjanik <petr.plavjanik@broadcom.com> Signed-off-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Signed-off-by: Fernando Rijo Cedeno <37381190+zFernand0@users.noreply.github.com> Co-authored-by: MarkAckert <35308966+MarkAckert@users.noreply.github.com> Co-authored-by: Fernando Rijo Cedeno <37381190+zFernand0@users.noreply.github.com>

zFernand0

Curious if we could incorporate some of the Metal C and Function parameter count 🙏

I believe those could prove useful in the future 🙏

zFernand0 · 2026-03-30T21:26:34Z

It seems as though these were generated at different times with slightly different context/prompts 🤔
Perhaps that's why there seems to be some information missing here.

I'm just going off the file in:

feat(system): Add view-syslog with relative time, pagination, and end timestamp #884 (comment)

Original: AGENTS.md

sonarqubecloud · 2026-04-13T15:44:20Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

github-project-automation bot moved this to New Issues in Zowe CLI Squad Mar 29, 2026

github-project-automation bot added this to Zowe CLI Squad Mar 29, 2026

pull-request-size bot added the size/L label Mar 29, 2026

zowe-robot moved this from New Issues to Review/QA in Zowe CLI Squad Mar 29, 2026

github-actions bot assigned plavjanik Mar 29, 2026

Merge branch 'main' into docs/agents-md

72259ea

plavjanik mentioned this pull request Mar 29, 2026

feat(uss): add issue command for shell execution using spawn() #867

Merged

4 tasks

traeok self-requested a review March 30, 2026 15:16

zFernand0 self-requested a review March 30, 2026 15:17

MarkAckert self-requested a review March 30, 2026 15:17

t1m0thyj self-requested a review March 30, 2026 17:59

traeok reviewed Mar 30, 2026

View reviewed changes

zFernand0 requested changes Mar 30, 2026

View reviewed changes

plavjanik added 2 commits April 10, 2026 20:33

Merge branch 'main' into docs/agents-md

6a7ee62

Merge branch 'main' into docs/agents-md

b34edbd

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add AI agent guides (AGENTS.md)#894

docs: add AI agent guides (AGENTS.md)#894
plavjanik wants to merge 4 commits intomainfrom
docs/agents-md

plavjanik commented Mar 29, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 29, 2026 •

edited

Loading

Uh oh!

traeok left a comment

Uh oh!

traeok Mar 30, 2026

Uh oh!

traeok Mar 30, 2026 •

edited

Loading

Uh oh!

traeok Mar 30, 2026

Uh oh!

traeok Mar 30, 2026

Uh oh!

traeok Mar 30, 2026

Uh oh!

zFernand0 left a comment

Uh oh!

zFernand0 Mar 30, 2026

Uh oh!

sonarqubecloud bot commented Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		### Expired password detection

		When an SSH session connects with an expired password, z/OS emits `FOTS1668`/`FOTS1669` on stderr. This can masquerade as SFTP failures or generic command errors. `ZSshUtils.routeExpiredPasswordError()` checks for these codes after every `execCommand` call: if an `onError` callback is registered it is called with an `ImperativeError` using `SshErrors.FOTS1668.summary` as the message (so the VSCE notification bubble shows a readable string); otherwise the error is thrown directly (preserving CLI behavior). The `errorCode` is always `"EPASSWD_EXPIRED"`.


		## Test Framework

		- CLI tests: `c/test/zowex.<domain>.test.cpp` — use `execute_command_with_output()`

	- CLI tests: `c/test/zowex.<domain>.test.cpp` — use `execute_command_with_output()`
	- CLI-focused tests: `c/test/zowex.<domain>.test.cpp` — use `execute_command_with_output()`
	- API tests: `c/test/<api>.test.cpp` — use direct API calls


		This applies to: code comments, usage examples, test scripts, markdown docs, commit messages, and any other checked-in artifact.

		## Maintaining This Guide

Conversation

plavjanik commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why AGENTS.md?

Top 5 general guidelines for AGENTS.md

Top 5 best practices captured in these guides

References

Uh oh!

github-actions bot commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

traeok left a comment

Choose a reason for hiding this comment

Uh oh!

traeok Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

traeok Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

traeok Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

traeok Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

traeok Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

zFernand0 left a comment

Choose a reason for hiding this comment

Uh oh!

zFernand0 Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Apr 13, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

plavjanik commented Mar 29, 2026 •

edited

Loading

github-actions bot commented Mar 29, 2026 •

edited

Loading

traeok Mar 30, 2026 •

edited

Loading