@evref-bl/pharo-mcp 0.0.0-stage → 1.4.0

package/templates/pharo-references/source-vs-live-image.md

@@ -0,0 +1,75 @@
+# Source Files Vs Live Pharo Image State
+
+Applies when an agent uses the Pharo MCP server to inspect, modify, or verify a
+Pharo project.
+
+## Goal
+
+Keep source inspection, loaded image state, Iceberg state, and Git state
+separate. Each one can answer different questions, and none should be treated
+as a substitute for the others.
+
+## Source-Only Checks
+
+Source-only checks can confirm:
+
+- files exist where expected;
+- packages, classes, and methods are exported in Tonel;
+- baseline files and package declarations look coherent;
+- static documentation and scripts are present;
+- Git diffs contain the expected source changes;
+- formatting and whitespace checks pass.
+
+Source-only checks cannot prove:
+
+- the project loads in the image;
+- classes and methods are currently loaded;
+- tools see the expected image state;
+- tests pass inside the image;
+- image-side edits were exported to source;
+- the running server or application behaves correctly.
+
+## Live Image Checks
+
+Use live image checks when the answer depends on image state:
+
+- loading a baseline or package;
+- listing loaded repositories, packages, classes, or methods;
+- inspecting compiled methods or class definitions;
+- running SUnit tests;
+- starting or exercising a server/application in the image;
+- applying image-side edits;
+- exporting image-side changes to Tonel or Git.
+
+Prefer dedicated `pharo` MCP tools for these checks. Use `image_evaluate` only
+when no dedicated tool fits.
+
+## Iceberg And Git
+
+Remember:
+
+- Tonel files are exported source.
+- The loaded image can differ from Tonel files.
+- Iceberg working-copy state can differ from both image state and Git state.
+- Git commits record disk files, not unsaved image changes.
+
+When these states disagree, report the mismatch and resolve it deliberately.
+Do not claim a change is complete just because one layer looks correct.
+
+## Blocked Live Verification
+
+If the current context does not have a safe or approved live image:
+
+- run only source-safe checks;
+- say which live checks are still needed;
+- do not use image-side evaluation or mutation as a workaround;
+- do not claim live behavior is verified.
+
+## Reporting
+
+When finishing work, report:
+
+- source checks run;
+- live image checks run;
+- live checks not run and why;
+- any image/source/Iceberg/Git state mismatch observed.

package/templates/pharo-references/tool-reference.md

@@ -0,0 +1,273 @@
+# Tool Reference
+
+MCP exposes tools through `tools/list` and `tools/call`. Common tools can be
+advertised directly; less common tools can be found through the catalog tools.
+Tool names use `snake_case` names that generally put the domain before the
+action.
+
+By default, every tool returns MCP call `content` as the canonical response for
+LLMs. The text block contains the complete tool payload encoded as JSON using
+this common shape:
+
+```text
+status: ok | error
+summary: human-readable summary
+warnings: array of warning strings
+data: structured success payload
+error: structured error payload
+```
+
+`data` is present on success. `error` is present on failure.
+
+For clients or integrations that need programmatic payloads, configure the
+server response fields before `start`:
+
+```smalltalk
+mcp useContentOnlyToolResponses. "default"
+mcp useStructuredContentOnlyToolResponses.
+mcp useContentAndStructuredContentToolResponses.
+```
+
+## Compact Paging
+
+List and search tools are optimized for low token usage. Broad tools return a
+small page by default and put only the entry array in `data`. When another page
+exists, `data` includes `nextOffset`; call the same tool again with that
+`offset` to continue.
+
+Use the returned array size for the current page and follow `nextOffset` when
+present. Request larger pages only when the next step truly needs more entries.
+
+## Tool Catalog
+
+| Tool | Use |
+| --- | --- |
+| `tool_search` | Search the tool catalog by group, keyword, title, or description. |
+| `tool_get` | Return input schema and metadata for one catalog tool. |
+| `tool_call` | Invoke a catalog tool that is not exposed directly by the current client. |
+
+Use `tool_search` before calling less common or high-risk tools. Inspect the
+schema before invoking a discoverable tool.
+
+## Repositories
+
+| Tool | Use |
+| --- | --- |
+| `repository_search` | List Iceberg repositories registered in the image, including location, branch/head metadata, exact head commit id, modified packages, remotes, and upstream details. |
+| `repository_identity_verify` | Assert expected Iceberg repository identity fields before edits, exports, commits, pulls, or pushes. |
+| `repository_change_list` | Inspect Iceberg `workingCopyDiff` without writing files. |
+| `repository_create` | Create a new Iceberg repository directory and optionally attach initial packages. |
+| `repository_attach` | Register an existing Git checkout, including a linked Git worktree checkout, and optionally attach packages. |
+| `repository_update` | Change image-side repository subdirectory or package membership without exporting packages. |
+| `repository_export` | Export image-side package changes to Tonel files and update the Iceberg index without staging or committing Git changes. |
+| `repository_commit` | Commit Iceberg repository changes with a message. |
+| `repository_fetch` | Fetch repository remotes through Iceberg. |
+| `repository_pull` | Pull through Iceberg. |
+| `repository_push` | Push through Iceberg. |
+| `repository_branch_create` | Create and switch to a new repository branch through Iceberg. |
+| `repository_branch_switch` | Switch the Iceberg repository head to an existing branch without loading package changes into the image. |
+| `repository_branch_checkout` | Check out an existing repository branch and load changes for packages already loaded in the image. |
+| `repository_head_adopt` | Adopt the current repository head as the Iceberg working-copy reference after verifying the image and Git state. |
+| `baseline_load` | Load an already-known Metacello baseline available in the image. |
+| `repository_load` | Load a Metacello baseline from a remote repository. |
+
+Use `repository_identity_verify` before edits or exports, and
+`repository_change_list` before exporting or committing image changes.
+Identity verification requires at least one expected identity field, such as
+`location`, `branchName`, `subdirectory`, `packageNames`,
+`modifiedPackageNames`, or `isModified`.
+
+Use plural fields such as `repositoryNames`, `directoryPaths`, and
+`packageNames` for exact repository scope. Use singular text filters such as
+`repositoryName`, `branchName`, `headCommitId`, `remoteUrl`, and
+`upstreamBranchName` for field-specific matching.
+
+## Packages
+
+| Tool | Use |
+| --- | --- |
+| `package_search` | List packages by project/package scope, with optional `packageName`, `projectName`, and `tag` filters. |
+
+## Classes
+
+| Tool | Use |
+| --- | --- |
+| `class_search` | List classes by package/class/hierarchy scope, with optional `className`, `tag`, `instanceSlot`, and `classSlot` filters. |
+| `class_get` | Get one class by name and return structured class metadata with optional superclass and subclass context. |
+| `class_create` | Create one class definition. |
+| `class_name_update` | Rename one class through the Refactoring Engine. |
+| `class_superclass_update` | Change one class superclass. |
+| `class_package_update` | Move one class to a package and/or recategorize it under a package tag. |
+| `class_comment_update` | Set or clear one class comment. |
+| `class_slots_update` | Replace instance-side and/or class-side slot definitions. |
+| `class_traits_update` | Replace instance-side trait composition. |
+| `class_side_traits_update` | Replace class-side trait composition. |
+| `class_shared_variables_update` | Replace class variables. |
+| `class_shared_pools_update` | Replace shared pools. |
+| `class_layout_update` | Replace the layout class. |
+| `class_slot_add` | Add one instance-side or class-side slot. |
+| `class_slot_remove` | Remove one instance-side or class-side slot. |
+| `class_slot_name_update` | Rename one instance-side or class-side slot. |
+| `class_slot_pull_up` | Pull one instance-side or class-side slot up to a superclass. |
+| `class_slot_push_down` | Push one instance-side or class-side slot down to subclasses. |
+| `class_remove` | Remove classes as one batch. Refactoring warnings stop removal unless `force=true`. |
+
+Class mutation tools and `class_remove` use Pharo refactoring support
+where available. With `force=false`, refactoring warnings return impact details
+instead of continuing.
+
+## Methods
+
+| Tool | Use |
+| --- | --- |
+| `method_metadata_search` | List/search methods by class/package/hierarchy scope, with optional `selector` and `protocol` filters. |
+| `method_source_search` | Search methods by source text. |
+| `method_equivalent_search` | Search methods whose AST is equivalent to a referenced method. |
+| `method_implementor_search` | Search methods that implement a selector. |
+| `method_sender_search` | Search methods that send a selector. |
+| `method_class_reference_search` | Search methods that reference a class binding. |
+| `method_variable_reference_search` | Search methods that reference a variable. |
+| `method_get` | Get one known method and return source plus structured variable-reference context. |
+| `method_compile` | Create or replace one method from source. |
+| `method_selector_update` | Rename selectors, add/remove arguments, or reorder arguments through the Refactoring Engine. |
+| `method_protocol_update` | Move one method to another regular or extension protocol. |
+| `method_rewrite` | Preview or apply AST rewrite rules across a method scope. Applying requires `expectedChangeSetHash` from a preview. |
+| `critique_run` | Run selected or all Renraku critiques over a scope and return hits grouped by rule class. |
+| `method_remove` | Remove methods from one class as a batch without sender safety checks. |
+
+Prefer the specialized lookup tools for navigation tasks. Use
+`method_source_search` for source text and `method_equivalent_search` for
+equivalent-AST matches. Keep `method_metadata_search` for method metadata
+search. Top-level `method_metadata_search` filtering is limited to `selector`
+and `protocol` fields (`substring`, `prefix`, `exact`, or `regex`); use
+specialized tools for source, equivalent methods, implementors, senders, class
+references, and variable references.
+
+`method_compile` returns selected Renraku critiques after method compilation when
+they are relevant to review.
+
+## History
+
+| Tool | Use |
+| --- | --- |
+| `history_file_list` | List Epicea `.ombu` change-history files, including the current history file. |
+| `history_entry_list` | List entries from the current image change history or a selected `.ombu` file. |
+| `history_entry_apply` | Preview applying selected entries, and apply them with `confirm=true`. |
+| `history_entry_revert` | Preview reverting selected entries, and revert them with `confirm=true`. |
+
+Prefer the read-only tools when browsing history. Use
+`history_entry_apply` or `history_entry_revert` when you need apply/revert
+preview or confirmation.
+
+## Tests
+
+| Tool | Use |
+| --- | --- |
+| `test_run` | Run SUnit test classes or individual methods. |
+| `test_coverage_run` | Run SUnit test classes or individual methods while collecting method and node coverage for an explicit method scope. |
+
+## UI
+
+| Tool | Use |
+| --- | --- |
+| `screenshot_capture` | Capture the active Morphic world and return MCP image content with dimensions and MIME type metadata. |
+
+## Debugging
+
+The debugger tools are discoverable under the `debugging` group. Read
+[Debugging with MCP](debugging.md) before using them.
+
+| Tool | Use |
+| --- | --- |
+| `debug_capture` | Evaluate a Smalltalk expression in a bounded worker process and capture runtime exceptions as tracked debug sessions. |
+| `debug_test_run` | Run one SUnit test method under debugger control and capture failures or errors as tracked debug sessions. |
+| `debug_session_list` | List tracked debug sessions. |
+| `debug_session_get` | Inspect one tracked debug session summary. |
+| `debug_session_remove` | Remove a tracked debug session from the registry. |
+| `debug_candidate_search` | Search unattached open debugger candidates. |
+| `debug_candidate_attach` | Attach an open debugger candidate and return its debug state. |
+| `debug_state_get` | Return a debug-session snapshot with stack, selected frame, source, scopes, repair actions, and state-scoped references. |
+| `debug_variable_get` | Expand scope and variable references returned by `debug_state_get`. |
+| `debug_expression_evaluate` | Evaluate a Smalltalk expression in a selected debug frame. |
+| `debug_session_step_into` | Step into the selected frame of a tracked debug session. |
+| `debug_session_step_over` | Step over the selected frame of a tracked debug session. |
+| `debug_session_step_through` | Step through the selected frame of a tracked debug session. |
+| `debug_session_restart` | Restart the selected frame of a tracked debug session. |
+| `debug_session_resume` | Resume a tracked debug session. |
+| `debug_session_terminate` | Terminate a tracked debug session. |
+| `debug_breakpoint_list` | List tracked transient DebugPoint breakpoints. |
+| `debug_breakpoint_set` | Install a transient method-entry or source-interval DebugPoint breakpoint. |
+| `debug_breakpoint_remove` | Remove one tracked transient DebugPoint breakpoint. |
+| `debug_breakpoint_enable` | Enable one tracked transient DebugPoint breakpoint. |
+| `debug_breakpoint_disable` | Disable one tracked transient DebugPoint breakpoint. |
+| `debug_breakpoint_clear` | Remove all tracked transient DebugPoint breakpoints. |
+| `debug_method_update` | Update the method associated with a paused debug state, then proceed when possible. |
+
+## Scripting
+
+| Tool | Use |
+| --- | --- |
+| `image_evaluate` | Evaluate arbitrary Smalltalk and return a bounded preview of the result. |
+
+Use `image_evaluate` only when no dedicated tool fits. A successful evaluation can
+mutate and save the image.
+
+## Mutation And Saving
+
+Most search and inspection tools are read-only and do not save the image.
+Mutating tools save the image after a successful call.
+
+Tools that can save after success include:
+
+```text
+class_create
+class_name_update
+class_package_update
+class_comment_update
+class_slot_add
+class_slot_remove
+class_slot_name_update
+method_compile
+method_selector_update
+method_protocol_update
+repository_create
+repository_attach
+repository_update
+repository_export
+repository_commit
+repository_fetch
+repository_pull
+repository_push
+repository_branch_create
+repository_branch_switch
+repository_branch_checkout
+repository_head_adopt
+baseline_load
+repository_load
+class_remove
+method_remove
+method_rewrite when apply=true and changes were applied
+history_entry_apply when entries were performed
+history_entry_revert when entries were performed
+debug_expression_evaluate
+debug_capture
+debug_test_run
+debug_method_update when a method is accepted
+image_evaluate
+```
+
+`repository_identity_verify` and `repository_change_list` are read-only.
+
+## Refactoring Warnings
+
+For edit tools that use refactoring operations, `force=false` is the default.
+When Pharo raises `RBRefactoringWarning`, the tool returns an error with:
+
+```text
+impactMessages
+howToProceed
+forceSupported: true
+```
+
+Rerun with `force=true` only after reviewing the impact. Forced warnings are
+returned as normal warnings in the successful result.

package/templates/pharo-references/troubleshooting.md

@@ -0,0 +1,137 @@
+# Troubleshooting
+
+Most failures fall into one of three groups: the image is not reachable, the
+requested tool input is invalid, or the live image state differs from what the
+caller expected.
+
+For standalone image crashes or stopped servers, the installed
+`pharo-mcp-recovery` skill gives agents a recovery workflow for preserving
+evidence, restarting or replacing the image, reloading projects, and recovering
+change history.
+
+## The Client Cannot Connect
+
+Check the server in the image:
+
+```smalltalk
+mcp isRunning.
+mcp isListening.
+mcp localUrlString.
+```
+
+Confirm that the client URL uses the same host and port:
+
+```text
+http://127.0.0.1:4000
+```
+
+If you changed the port in Pharo, update the MCP client configuration.
+
+MCP currently handles MCP calls over HTTP POST. Unsupported HTTP methods
+return method-not-allowed instead of hanging.
+
+## `tools/list` Is Empty Or Stale
+
+Run:
+
+```smalltalk
+mcp refreshToolsList.
+```
+
+Then call `tools/list` again. If you loaded new MCP code into the image, restart
+the server:
+
+```smalltalk
+mcp restart.
+```
+
+## A Tool Rejects Input
+
+Each tool validates arguments against its input schema. Call `tools/list` and
+inspect the tool's `inputSchema`.
+
+Common causes:
+
+- missing required fields for the selected tool
+- extra fields rejected by `additionalProperties: false`
+- passing arguments from a different tool
+- `method_rewrite` with `apply=true` but no `expectedChangeSetHash`
+- `history_entry_apply` or `history_entry_revert` without `confirm=true`
+
+## A Refactoring Stops With A Warning
+
+This is expected for Pharo refactoring warnings. With `force=false`, the edit
+tool stops and returns impact details.
+
+Read:
+
+```text
+impactMessages
+howToProceed
+forceSupported
+```
+
+Rerun with `force=true` only when the impact is acceptable.
+
+## A Method Compiles But Returns Critiques
+
+`method_compile` can return Renraku critiques after compilation. The method exists,
+but Pharo found review issues. Inspect the critique rule class, title,
+description, and source interval if present.
+
+Use a follow-up `method_compile`, `method_selector_update`, `test_run`, or
+`method_get` call depending on the critique.
+
+## Repository State Looks Wrong
+
+MCP reads repository state from Iceberg in the running image. The exported
+Tonel files, the image's loaded packages, and Iceberg's working-copy state can
+differ.
+
+Start with:
+
+```text
+repository_search
+repository_identity_verify
+repository_change_list
+```
+
+Use `repository_export` only when you mean to write image changes to files.
+Export updates the Iceberg index but does not stage or commit Git changes.
+
+## Tests Do Not Prove The Edited Scope
+
+`test_run` tells you whether selected tests passed. Use `test_coverage_run` with
+an explicit coverage scope when you need to know whether the edited methods
+executed.
+
+Coverage scopes should be narrow: package, class, hierarchy, or method names.
+
+## The Image Changed Unexpectedly
+
+Image-changing tools save the image after successful mutation. If you are using
+an automation or agent, run it against a copied or disposable image.
+
+Use `history_file_list` and `history_entry_list` to inspect
+Epicea history. Apply or revert operations stay in `history_entry_apply` and
+`history_entry_revert`, where they can be previewed first and performed with
+`confirm=true`.
+
+## Debugger References Are Stale
+
+Debugger `stateId`, `frameRef`, and `variableRef` values are scoped to one
+debug_state_get snapshot. After a control action, debugger edit, or resume, discard
+old references and use the newly returned state.
+
+If a human opened the debugger, attach through the debugging tools and let the
+debugger controller own UI actions. Do not drive debugger windows with raw
+`image_evaluate` code.
+
+## Source Checks Are Not Enough
+
+Exported source files can confirm package layout, class definitions, and docs.
+They cannot prove that the running image has loaded the latest code or that an
+MCP tool works over HTTP.
+
+Use [Source vs live image](source-vs-live-image.md) to decide which checks are
+valid for the current work boundary.

package/templates/pharo-references/using-pharo-mcp.md

@@ -0,0 +1,156 @@
+# Using The Pharo MCP Server
+
+Applies when an agent or user interacts with a running Pharo image through MCP.
+Follow [Getting started](getting-started.md) to load, start, and connect first.
+
+## Source Of Truth
+
+Use the running image for live classes, methods, packages, repositories, and
+tests. Tonel source, Iceberg, and Git are separate state layers; read
+[Source files vs live image state](source-vs-live-image.md) before reasoning
+across them.
+
+If image access is unavailable, state which live check is blocked instead of
+guessing from source or memory.
+
+## Discover Before Calling
+
+- Inspect the tools exposed by the current client; do not rely on remembered
+  names or schemas.
+- Use `tool_search`, then `tool_get`, for less common tools. Invoke a catalog
+  tool through `tool_call` when the client does not expose it directly.
+- Prefer the least-mutating dedicated tool. Use `image_evaluate` only when no
+  dedicated tool fits.
+- Start list/search calls with the default page or a small `limit`. Continue
+  only when the result contains `nextOffset`.
+
+See [Tool reference](tool-reference.md) for tool groups and common workflows.
+
+## Choose Specialized Lookups
+
+Use `method_metadata_search` for metadata, `method_source_search` for source,
+`method_equivalent_search` for equivalent ASTs, and the implementor, sender,
+class-reference, or variable-reference search matching the question.
+
+For repository work, inspect with `repository_search`, verify identity before
+mutation, and inspect `repository_change_list` before export or commit. Read
+[Safety and ecosystem integration](safety-and-ecosystem.md) for mutation
+boundaries.
+
+For history recovery, inspect files and entries before applying or reverting.
+For debugger sessions, breakpoints, or repairs, read the installed local
+debugging guide.
+
+## Image Mutation
+
+Successful mutating tools save the image. Use a copied or disposable image for
+broad or risky edits, preview changes when the tool supports it, and run focused
+tests after source changes.
+
+Report incomplete or failing tool results clearly. Never silently fall back to
+exported source for a question about the live image.
+
+## Reusable Workflows
+
+Run `npx @evref-bl/pharo-mcp install --host <host>` in the target project to
+install context-routed skills for project loading, version compatibility,
+image-to-Git handoff, CI reproduction, and standalone MCP recovery.
+
+## Custom Tools
+
+Define custom tools as subclasses of `MCPTool` in your own package. At minimum,
+provide the class-side tool name and the instance-side metadata, schema, and
+execution protocol expected by `MCPTool`:
+
+```smalltalk
+MCPTool << #MyProjectMCPTool
+	slots: {};
+	package: 'MyProject-MCP'
+```
+
+```smalltalk
+MyProjectMCPTool class >> toolName
+
+	^ 'my_project_tool'
+
+MyProjectMCPTool >> description
+
+	^ 'Do one project-specific operation.'
+
+MyProjectMCPTool >> buildInputSchema
+
+	^ MCPStructureInputSchema new
+		type: 'object';
+		properties: #(  );
+		required: #(  );
+		additionalProperties: false;
+		yourself
+
+MyProjectMCPTool >> buildOutputSchema
+
+	^ self standardOutputSchemaForDataProperties: #(  ) required: #(  )
+
+MyProjectMCPTool >> executeWithRequest: request
+
+	^ self
+		successResultText: 'Operation completed.'
+		data: Dictionary new
+```
+
+By default, tools outside the MCP package are not auto-registered. If your
+package intentionally publishes a tool whenever it is loaded, opt in:
+
+```smalltalk
+MyProjectMCPTool class >> shouldAutoRegister
+
+	^ true
+```
+
+Auto-registered external tools are discoverable by default. Agents can find
+them with `tool_search`, inspect them with `tool_get`, and call them through
+`tool_call`.
+
+`MCPToolRegistry` is the server's source of truth for registered tools. In
+normal use, configure it through the `MCP` instance messages below. The
+`tools/list` response contains only the static tool surface cached by the MCP
+instance; discoverable tools remain available through `tool_search`, `tool_get`,
+and `tool_call`.
+
+For a server with only your own tools, use a profile:
+
+```smalltalk
+mcp := MCP profile: (MCPProfile tools: { MyProjectMCPTool }).
+mcp start.
+```
+
+`MCPProfile tools:` registers the given tools and advertises them directly in
+`tools/list`. Use `tools:static:` when some registered tools should stay
+discoverable through the catalog tools:
+
+```smalltalk
+mcp := MCP profile: (MCPProfile
+	tools: { MyProjectMCPTool. MyOtherMCPTool }
+	static: { MyProjectMCPTool }).
+```
+
+For incremental per-server configuration, register tools explicitly before
+starting the server:
+
+```smalltalk
+mcp := MCP new.
+mcp registerToolClass: MyProjectMCPTool.
+mcp start.
+```
+
+You can also register several classes, register an already-created tool, or
+remove a tool from one server instance:
+
+```smalltalk
+mcp registerToolClasses: { MyProjectMCPTool. MyOtherMCPTool }.
+mcp registerTool: MyProjectMCPTool new.
+mcp unregisterToolNamed: 'my_project_tool'.
+```
+
+Use `defaultExposure` to decide whether a registered tool is directly
+advertised in `tools/list` (`'static'`) or kept discoverable through the catalog
+tools (`'discoverable'`, the default).

package/templates/pharo-skills/pharo-ci-repro/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pharo-ci-repro
+description: Reproduce Pharo smalltalkCI or GitHub Actions failures locally, preferably in Docker; preserve logs; narrow flaky tests; and distinguish project, compatibility, VM/native, and external-service failures.
+---
+
+# Pharo CI Repro
+
+## Context
+
+Read the failing workflow, `.smalltalk.ston`, project load instructions, commit,
+and supported Pharo matrix. Read `references/pharo-smalltalkci.md` after a run
+produces logs.
+
+## Workflow
+
+1. Record platform, config path, revision, and failing phase: download, load,
+   tests, coverage, or teardown.
+2. Check `git status --short --branch`. Use a clean failing revision for exact
+   reproduction or an isolated scratch copy for local fixes.
+3. Run one faithful Docker/smalltalkCI reproduction and preserve its first
+   failing log. Confirm the Docker CLI and daemon before falling back.
+4. Use local smalltalkCI only when containers are unavailable or OS/runtime
+   fidelity is irrelevant; isolate its checkout/home per parallel job.
+5. After reproducing, narrow with a temporary smalltalkCI config for one class
+   or package. Repeat focused runs for flakes.
+6. Classify the result as project, compatibility, VM/native, or external.
+7. Verify the fix on every affected CI platform and repeat the flaky target.
+
+## Helper
+
+```sh
+skills/pharo-ci-repro/scripts/run-smalltalkci-docker.sh \
+  --repo /path/to/repo \
+  --platform Pharo64-13 \
+  --attempts 3
+```
+
+Use `--spec` for a focused config, `--out` for logs, and `--keep-going` to
+collect multiple failures. Use `--include-git` only for ordinary checkouts;
+linked worktree `.git` files point outside a copied tree.
+
+## Report
+
+Report exact commands, image/VM versions, first failing phase, relevant
+Smalltalk/native frames, log paths, diagnosis class, changes made, and matrix
+verification. Keep native-crash conclusions cautious.

package/templates/pharo-skills/pharo-ci-repro/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pharo CI Repro"
+  short_description: "Reproduce Pharo CI locally"
+  default_prompt: "Use $pharo-ci-repro to recreate a failing Pharo smalltalkCI run locally and capture logs."