# watsonx Orchestrate Workshop Workspace Rule

Apply this rule when working in this project.

## Version and documentation policy

- The workshop targets **IBM watsonx Orchestrate ADK 2.14.0**.
- Run all `orchestrate` commands from the project `.venv`.
- Search `watsonx-orchestrate-adk-docs` before generating ADK syntax, and state
  that the requested version is 2.14.0.
- Use `watsonx-orchestrate-adk` to inspect the connected platform.
- If current documentation differs from ADK 2.14.0, do not silently migrate the
  workshop. Explain the difference and preserve the tested workshop version.
- Validate generated YAML with the installed ADK before importing it.

### Remote session refresh

Remote watsonx Orchestrate authentication expires every two hours. If an
`orchestrate` command reports an authentication, token, or session-expired
error, stop retrying and ask the user to refresh the session in a terminal from
the project virtual environment:

```bash
source .venv/bin/activate
orchestrate env activate <environment-name>
```

On Windows PowerShell:

```powershell
.venv\Scripts\Activate.ps1
orchestrate env activate <environment-name>
```

The activation command may prompt for the WXO API key. The user must enter it
locally; never ask for or echo credentials in chat. Retry the failed command
only after the user confirms that activation succeeded.

Activate the environment when needed:

```bash
# macOS
source .venv/bin/activate
```

```powershell
# Windows PowerShell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.venv\Scripts\Activate.ps1
```

## Project layout

```text
agents/           # Native-agent YAML
tools/            # Python tools, plugins, and flows
toolkits/         # MCP toolkit packages and specs
knowledge_bases/  # Knowledge-base specs and documents
models/           # Model and model-policy specs
connections/      # Connection definitions without credentials
evaluation/       # Evaluation and red-team datasets
requirements.txt  # Tool runtime dependencies
```

## Workshop conventions

1. Agent names use `snake_case`.
2. Default model: `groq/openai/gpt-oss-120b`.
3. Native-agent YAML includes `spec_version: v1`, `kind: native`, `name`,
   `description`, `llm`, and clear instructions.
4. Python tools use `@tool`, explicit types, complete docstrings, input
   validation, and structured results.
5. Never include `ibm-watsonx-orchestrate` in a tool's `requirements.txt`; the
   runtime provides it.
6. Never write API keys or personal data into code, YAML, tests, or chat.
7. Review generated files and show the exact import command before executing it.

## Known pitfalls

- Python-tool imports require `-r requirements.txt`.
- A guideline's `tool:` field names an imported tool, not a collaborator.
  Describe collaborator handoff in `action`.
- Knowledge-base and collaborator references must exactly match imported names.
- MCP tools use `toolkit-name:tool-name` under the agent's `tools:` field.
- Local MCP toolkit YAML requires `spec_version: v1`; its `command` runs inside
  the Orchestrate runtime.
- Every required flow-tool argument needs an explicit `map_input()`.
- Import flows with `orchestrate tools import -k flow -f <file>`.
- Import pre/post-invoke plugins as Python tools before attaching them under
  `plugins:`.
- Evaluation configuration uses `test_paths`; pass the tools directory with the
  quick-eval `-t` option.
- Imports update draft automatically. Deploy an agent with
  `orchestrate agents deploy --name <agent_name>`.

## Completion check

Before reporting success:

- validate syntax and schema
- show the imported artifact in the matching `orchestrate ... list` output
- run the module's checkpoint
- report warnings and unresolved limitations rather than hiding them