Initial commit: PTC Integrity 10.7 si CLI skill

2026-08-17 13:38:43 +00:00
commit 78856aeb9b
1 changed files with 514 additions and 0 deletions
--- a/SKILL.md
+++ b/SKILL.md
@@ -0,0 +1,514 @@
+# PTC Integrity 10.7 CLI (`si`)
+
+## Purpose
+
+Use this skill when working with source code managed by **PTC Integrity 10.7**, using the `si` command-line client.
+
+Target version:
+
+```text
+PTC Integrity 10.7.0.7930
+```
+
+PTC Integrity is not Git. Do not apply Git concepts or Git commands to an Integrity Sandbox unless the user explicitly states that Git is also being used.
+
+The primary command-line tool is:
+
+```bash
+si
+```
+
+## Core Concepts
+
+### Project
+A Project is the server-side source configuration managed by Integrity.
+
+### Sandbox
+A Sandbox is a local working representation of an Integrity Project. It normally contains a `project.pj` file and working files corresponding to project members.
+
+### Member
+A Member is a version-controlled file belonging to an Integrity Project. A file existing on disk does not necessarily mean that it is a project member.
+
+### Working File
+The local filesystem copy of a Member inside a Sandbox. Do not infer Integrity state merely from filesystem permissions or timestamps.
+
+### Member Revision
+The revision currently selected by the Project. The working file may be based on a different revision.
+
+### Lock / Checkout
+`si co` / `si checkout` checks out a member. Depending on server configuration, checkout normally obtains a lock. Do not assume that making a file writable is equivalent to checking it out.
+
+### Change Package
+A Change Package (CP) records source changes associated with an Integrity item. Change package identifiers commonly look like `12345:1`. Never invent a Change Package ID.
+
+## General Rules
+
+1. Prefer `si` over manipulating Integrity metadata manually.
+2. Never modify `project.pj`.
+3. Never delete Integrity metadata manually.
+4. Never assume Git semantics.
+5. Determine Sandbox context before source-control operations.
+6. Inspect state before changing state.
+7. Operate on explicitly selected files whenever possible.
+8. Avoid recursive operations unless required.
+9. Never invent command options.
+10. If uncertain about Integrity 10.7 syntax, use local CLI help.
+
+Use:
+
+```bash
+si <command> --usage
+```
+
+or:
+
+```bash
+si <command> -?
+```
+
+The locally installed Integrity 10.7 client is authoritative.
+
+## Detecting an Integrity Sandbox
+
+Prefer:
+
+```bash
+si sandboxinfo
+```
+
+When necessary:
+
+```bash
+si sandboxinfo --cwd=/path/to/directory
+```
+
+Do not use `si sandboxinfo --xmlapi`; `--xmlapi` is not available in Integrity 10.7.
+
+A `project.pj` is an indicator of an Integrity-managed tree, but do not rely exclusively on filesystem inspection.
+
+## Read-Only Investigation
+
+Prefer read-only commands while investigating:
+
+```bash
+si sandboxinfo
+si viewsandbox
+si projectinfo
+si viewproject
+si memberinfo
+si history
+si diff
+```
+
+Use local help when exact options are uncertain:
+
+```bash
+si viewsandbox --usage
+si memberinfo --usage
+si history --usage
+si diff --usage
+```
+
+## Inspecting Members
+
+Before changing a file, determine its Integrity state:
+
+```bash
+si memberinfo path/to/file
+si viewsandbox path/to/file
+```
+
+Determine where relevant:
+
+- whether the file is a Member
+- working revision
+- member revision
+- lock state
+- whether the working file changed
+- whether a newer member revision exists
+- whether the member belongs to a variant/development path
+
+Do not infer these from the filesystem alone.
+
+## Viewing Differences
+
+Before overwriting, reverting, or checking in a modified file:
+
+```bash
+si diff path/to/file
+```
+
+If additional options are required:
+
+```bash
+si diff --usage
+```
+
+Do not replace this with `git diff` unless the directory is explicitly also managed by Git.
+
+## History
+
+Use:
+
+```bash
+si history path/to/file
+```
+
+For advanced queries:
+
+```bash
+si history --usage
+```
+
+## Checkout
+
+The common command is:
+
+```bash
+si co path/to/file
+```
+
+Before checkout, determine:
+
+- whether the file is already checked out or locked
+- whether the working file has local modifications
+- whether the member revision is current
+- whether a Change Package is required
+
+Never invent a Change Package ID.
+
+If unsure:
+
+```bash
+si co --usage
+```
+
+## Editing Files
+
+When a file needs modification:
+
+1. Determine Sandbox context.
+2. Determine member state.
+3. Check whether checkout/locking is required.
+4. Check out the member if appropriate.
+5. Modify only the requested files.
+6. Review the resulting diff.
+
+Do not automatically resynchronize a modified file merely because it is out of sync.
+
+## Check In
+
+The common command is:
+
+```bash
+si ci path/to/file
+```
+
+Before checking in:
+
+1. Inspect the member state.
+2. Inspect the diff.
+3. Determine the relevant Change Package.
+4. Ensure only intended files are included.
+5. Determine the check-in description.
+6. Verify that unrelated modifications are not included.
+
+Do not automatically check in changes merely because implementation work is complete. Unless the user explicitly requested a check-in, stop after making and reviewing the working-file changes.
+
+For exact options:
+
+```bash
+si ci --usage
+```
+
+## Change Packages
+
+A CP identifier typically has the form:
+
+```text
+ITEM:CP
+```
+
+For example:
+
+```text
+4711:1
+```
+
+An option may have a form such as:
+
+```text
+--changePackageId=4711:1
+```
+
+but always verify command-specific syntax using:
+
+```bash
+si <command> --usage
+```
+
+Never:
+
+- invent a CP
+- select an unrelated CP merely because it is open
+- close a CP without explicit instruction
+- create a CP without explicit instruction
+
+## Resynchronize
+
+`si resync` updates Sandbox working files from member revisions:
+
+```bash
+si resync path/to/file
+```
+
+This command is potentially destructive and may overwrite local working-file changes.
+
+Before resync:
+
+1. Inspect Sandbox/member state.
+2. Determine whether working files contain modifications.
+3. Inspect important differences.
+4. Determine exactly which members will be affected.
+5. Avoid recursive resync unless necessary.
+
+If the operation could destroy user changes, obtain explicit user approval.
+
+Before advanced use:
+
+```bash
+si resync --usage
+```
+
+## Resync by Change Package
+
+Features may include:
+
+```bash
+si resync --byCP ...
+si resynccp ...
+```
+
+Do not treat them as interchangeable.
+
+Before use:
+
+```bash
+si resync --usage
+si resynccp --usage
+```
+
+## Adding Files
+
+New files created inside a Sandbox are not automatically Integrity members.
+
+Before adding:
+
+1. Confirm the file is intended for source control.
+2. Determine the target Project/Sandbox.
+3. Determine whether a Change Package is required.
+4. Check exact Integrity 10.7 syntax.
+
+Use:
+
+```bash
+si add --usage
+```
+
+Do not add build output, temporary files, editor backup files, or generated files unless required.
+
+## Dropping Members
+
+Dropping a member removes it from the Integrity Project configuration and is destructive.
+
+Before dropping:
+
+1. Verify the target member.
+2. Inspect its state.
+3. Determine whether local modifications exist.
+4. Determine the required Change Package.
+5. Obtain explicit user approval if removal was not already explicitly requested.
+
+Check syntax:
+
+```bash
+si drop --usage
+```
+
+## Revert / Discarding Changes
+
+Discarding local changes can cause irreversible data loss. Do not assume Git semantics.
+
+Before using a revert/discard operation:
+
+```bash
+si revert --usage
+```
+
+Inspect current member state and diff first. If local modifications would be destroyed, obtain explicit user approval unless the user already explicitly requested that those modifications be discarded.
+
+## Recursive Operations
+
+Do not automatically use recursive options such as `-R`.
+
+Before a recursive operation:
+
+1. Determine the Sandbox root.
+2. Determine the expected affected scope.
+3. Prefer filters or explicit member lists where practical.
+4. Inspect the command with `--usage`.
+5. Avoid destructive recursive operations unless explicitly requested.
+
+## Selection Files
+
+Integrity may support selection files for commands accepting multiple members, using forms such as:
+
+```text
+-F file
+--selectionFile=file
+```
+
+Verify support first:
+
+```bash
+si <command> --usage
+```
+
+## `--cwd`
+
+Integrity commands can operate relative to another working directory. Example:
+
+```bash
+si <command> --cwd=/path/to/sandbox ...
+```
+
+Prefer `--cwd` over arbitrary shell `cd` sequences when it makes command context clearer.
+
+## Error Handling
+
+When an `si` command fails:
+
+1. Preserve the complete error output.
+2. Do not immediately retry with destructive flags.
+3. Determine whether the failure concerns authentication, Sandbox context, member state, locks, Change Packages, permissions, project ambiguity, development paths, server connectivity, or unsupported options.
+4. Query local command help if syntax is involved.
+
+Never solve an Integrity error by deleting `project.pj` or other Integrity metadata.
+
+## Version Compatibility
+
+This environment uses:
+
+```text
+PTC Integrity 10.7.0.7930
+```
+
+Do not assume documentation for Integrity 11, Integrity 12, or Windchill RV&S exactly matches this installation.
+
+Newer documentation may help explain concepts, but command-line options must be verified against the installed client.
+
+When there is a discrepancy, the local Integrity 10.7 CLI is authoritative:
+
+```bash
+si <command> --usage
+```
+
+## Safe Investigation Workflow
+
+For an unfamiliar working tree:
+
+```bash
+pwd
+find .. -name project.pj -print
+si sandboxinfo
+si viewsandbox --usage
+```
+
+For a file that needs modification:
+
+```bash
+si memberinfo path/to/file
+si diff path/to/file
+```
+
+If checkout is required:
+
+```bash
+si co --usage
+si co path/to/file
+```
+
+After modifying:
+
+```bash
+si diff path/to/file
+```
+
+Do not automatically check in.
+
+## Agent Safety Policy
+
+Normally safe for autonomous investigation:
+
+```text
+sandboxinfo
+projectinfo
+viewsandbox
+viewproject
+memberinfo
+history
+diff
+help / --usage
+```
+
+Commands altering local or server-side Integrity state require additional care:
+
+```text
+co / checkout
+ci / checkin
+add
+drop
+resync
+resynccp
+applycp
+revert
+lock
+unlock
+createsandbox
+dropsandbox
+```
+
+The agent may perform a checkout when clearly necessary for an explicitly requested code modification and doing so does not discard existing work.
+
+The agent must not autonomously:
+
+- destroy local modifications
+- drop members
+- perform destructive resyncs
+- close Change Packages
+- create arbitrary Change Packages
+- check in unrelated changes
+- recursively modify a large project without understanding scope
+- suppress safety confirmations merely to make a command succeed
+
+## Important Principle
+
+Integrity source-control state is more important than filesystem appearance.
+
+Never reason:
+
+> The file exists and is writable, therefore it is safe to edit.
+
+Instead reason:
+
+> This is an Integrity Sandbox. Determine the member and working-file state before deciding which operation is appropriate.
+
+When in doubt:
+
+```bash
+si sandboxinfo
+si memberinfo <member>
+si <command> --usage
+```
+
+before modifying source-control state.