Add Claude Code and Cursor IDE configuration

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:docs.temporal.io)",
+      "Bash(rye run pytest:*)",      
+      "Bash(rye run lint:*)",
+      "Bash(rye run typecheck:*)",
+      "Bash(rye run sync:*)",
+      "Bash(rye run build:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

.cursor/rules/00_repo_tooling.mdc

@@ -0,0 +1,24 @@
+---
+description: Project-wide tooling, env, and command conventions
+globs: "**/*"
+alwaysApply: true
+---
+
+Use Rye for Python dependency management and workflows. Prefer these commands:
+
+- Setup env: `./scripts/bootstrap` or `rye sync --all-features` [[Use Rye in this repo]]
+- Run tests: `rye run pytest` or `./scripts/test`
+- Run a specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v`
+- Format: `rye run format` or `./scripts/format`
+- Lint: `rye run lint` or `./scripts/lint`
+- Type check: `rye run typecheck` (runs pyright and mypy)
+- Build: `rye build`
+
+Environment requirements:
+
+- Python 3.12+ is required
+- A mock server auto-starts for tests on port 4010
+
+Notes:
+
+- Only use `uv` inside of tutorial folders which have their own virtualenv (managed by a tutorial specific pyproject.toml inside the relevant tutorial folder). Otherwise use rye at the top level.

.cursor/rules/05_permissions_and_tools.mdc

@@ -0,0 +1,18 @@
+---
+description: Cursor agent permissions and allowed tools aligned with Claude settings
+globs: "**/*"
+alwaysApply: true
+---
+
+When invoking external tools or the terminal, follow these constraints:
+
+- Web search is allowed when needed for docs and references
+- Prefer fetching docs from `docs.temporal.io` when researching Temporal topics
+- Allowed bash commands should go through Rye workflows:
+  - `rye run pytest:*`
+  - `rye run lint:*`
+  - `rye run typecheck:*`
+  - `rye run sync:*`
+  - `rye run build:*`
+
+Default to Rye; only use other tools when explicitly required by the codebase.

.cursor/rules/10_architecture.mdc

@@ -0,0 +1,30 @@
+---
+description: Repository architecture overview and code navigation hints
+globs: "src/agentex/**, examples/**, tests/**, README.md"
+alwaysApply: false
+---
+
+Code structure expectations:
+
+- `src/agentex/` contains the core SDK and generated API client code
+- `src/agentex/lib/` contains manually maintained code that should not be overwritten by the code generator
+  - `cli/` Typer-based CLI implementation
+  - `core/` Core services, adapters, and Temporal workflows
+  - `sdk/` SDK utilities and FastACP implementation
+  - `types/` Custom type definitions
+  - `utils/` Utility functions
+- `examples/` provides example implementations and tutorials
+- `tests/` contains the test suites
+
+Key components quick reference:
+
+- Client Layer: HTTP client for AgentEx API in `_client.py` and `resources/`
+- CLI Layer: Typer-based commands under `lib/cli/`
+- Core Services: Temporal workflows and services under `lib/core/`
+- FastACP: Protocol implementation in `lib/sdk/fastacp/`
+- State Machine: Workflow state management in `lib/sdk/state_machine/`
+
+Generated vs manual code:
+
+- Treat `src/agentex/lib/**` as manual code; avoid edits in generated areas unless regenerating consistently
+- Expect merge conflicts between generator outputs and manual patches; keep custom logic in `lib/`

.cursor/rules/20_codegen_boundaries.mdc

@@ -0,0 +1,11 @@
+---
+description: Keep manual code separate from generated SDK code
+globs: "src/agentex/**"
+alwaysApply: true
+---
+
+Guideline:
+
+- Avoid modifying auto-generated files in `src/agentex/` except where explicitly intended. Place custom logic, extensions, and higher-level abstractions in `src/agentex/lib/`.
+- When adding features, prefer adding new modules under `src/agentex/lib/**` rather than changing generated files directly.
+- If a change to generated code is required, document the reason and ensure the generator configuration or upstream schema is updated to make the change reproducible.

.cursor/rules/30_cli_and_commands.mdc

@@ -0,0 +1,18 @@
+---
+description: Guidance for working with the agentex CLI and commands
+globs: "src/agentex/lib/cli/**, src/agentex/lib/core/**"
+alwaysApply: false
+---
+
+The `agentex` CLI exposes:
+
+- `agentex agents` for get/list/run/build/deploy agents
+- `agentex tasks` for get/list/delete tasks
+- `agentex secrets` for sync/get/list/delete secrets
+- `agentex uv` as a UV wrapper with AgentEx-specific enhancements
+- `agentex init` to initialize new agent projects
+
+Development tips:
+
+- For agent development, use `agentex agents run --manifest manifest.yaml`
+- For debugging, append `--debug-worker` and optionally `--debug-port 5679`

.cursor/rules/40_temporal_and_agents.mdc

@@ -0,0 +1,17 @@
+---
+description: Temporal workflows, activities, and agent development guidance
+globs: "src/agentex/lib/core/temporal/**, examples/**/10_temporal/**"
+alwaysApply: false
+---
+
+Temporal integration:
+
+- Workflow definitions live in `lib/core/temporal/`
+- Include activity definitions for different providers and worker implementations
+- Keep workflow logic deterministic and side-effect free; move I/O into activities
+
+Agent framework:
+
+- Agents are manifest-driven and support multiple agent types (sync and Temporal-based)
+- Use the examples under `examples/10_agentic/` and `examples/10_temporal/` for patterns
+- For debugging agents, use the CLI flags `--debug-worker` and `--debug-port`

.cursor/rules/50_tests_and_mocking.mdc

@@ -0,0 +1,16 @@
+---
+description: Testing workflow and mock server details
+globs: "tests/**, scripts/test, scripts/mock"
+alwaysApply: true
+---
+
+Testing:
+
+- Run tests with `rye run pytest` or `./scripts/test`
+- To run a specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v`
+- A mock server is automatically started for tests on port 4010
+
+When writing tests:
+
+- Prefer deterministic unit tests that do not depend on external services
+- Use the mock server and fixtures provided in the repository

.cursor/rules/60_style_lint_typecheck.mdc

@@ -0,0 +1,16 @@
+---
+description: Formatting, linting, and type checking standards
+globs: "src/**, tests/**"
+alwaysApply: true
+---
+
+Standards:
+
+- Format code via `rye run format` or `./scripts/format`
+- Lint via `rye run lint` or `./scripts/lint`
+- Type check via `rye run typecheck` (pyright + mypy)
+
+Guidance:
+
+- Keep code readable and consistent; prefer small, focused functions
+- Avoid introducing style or type violations; fix before committing

.cursor/rules/70_examples_and_docs.mdc

@@ -0,0 +1,11 @@
+---
+description: How to use examples and documentation for development
+globs: "examples/**, README.md"
+alwaysApply: false
+---
+
+Use the `examples/` directory as reference implementations and tutorials. When creating new features:
+
+- Mirror patterns from the closest matching example
+- Keep examples runnable with the documented commands
+- Prefer adding or updating examples alongside significant feature changes

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Package Management in the top level repo
+- Use `rye` for dependency management (preferred)
+- Run `./scripts/bootstrap` to set up the environment
+- Or use `rye sync --all-features` directly
+
+Special note: the individual tutorials maintain their own tutorial specific virtualenv using `uv`. So when testing/running tutorials, you `uv run` instead of `rye run`.  Everything else is similar.
+
+#### Testing
+- Run tests: `rye run pytest` or `./scripts/test`
+- Run specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v`
+- Mock server is automatically started for tests, runs on port 4010
+
+#### Linting and Formatting
+- Format code: `rye run format` or `./scripts/format`
+  * The repository is still in flux, so running format might accidentally change files that aren't part of your scope of changes. So always run `run rye format` with additional arguments to constrain the formatting to the files that you are modifying.
+- Lint code: `rye run lint` or `./scripts/lint`
+- Type check: `rye run typecheck` (runs both pyright and mypy)
+
+### Building and Running
+- Build package: `rye build`
+
+
+
+### CLI Commands
+The package provides the `agentex` CLI with these main commands:
+- `agentex agents` - Get, list, run, build, and deploy agents
+- `agentex tasks` - Get, list, and delete tasks  
+- `agentex secrets` - Sync, get, list, and delete secrets
+- `agentex uv` - UV wrapper with AgentEx-specific enhancements
+- `agentex init` - Initialize new agent projects
+
+### Agent Development
+- Run agents: `agentex agents run --manifest manifest.yaml`
+- Debug agents: `agentex agents run --manifest manifest.yaml --debug-worker`
+- Debug with custom port: `agentex agents run --manifest manifest.yaml --debug-worker --debug-port 5679`
+
+## Architecture Overview
+
+### Code Structure
+- `/src/agentex/` - Core SDK and generated API client code
+- `/src/agentex/lib/` - Custom library code (not modified by code generator)
+  - `/cli/` - Command-line interface implementation
+  - `/core/` - Core services, adapters, and temporal workflows
+  - `/sdk/` - SDK utilities and FastACP implementation
+  - `/types/` - Custom type definitions
+  - `/utils/` - Utility functions
+- `/examples/` - Example implementations and tutorials
+- `/tests/` - Test suites
+
+### Key Components
+
+**SDK Architecture:**
+- **Client Layer**: HTTP client for AgentEx API (`_client.py`, `resources/`)
+- **CLI Layer**: Typer-based command interface (`lib/cli/`)
+- **Core Services**: Temporal workflows, adapters, and services (`lib/core/`)
+- **FastACP**: Fast Agent Communication Protocol implementation (`lib/sdk/fastacp/`)
+- **State Machine**: Workflow state management (`lib/sdk/state_machine/`)
+
+**Temporal Integration:**
+- Workflow definitions in `lib/core/temporal/`
+- Activity definitions for different providers
+- Worker implementations for running temporal workflows
+
+**Agent Framework:**
+- Manifest-driven agent configuration
+- Support for multiple agent types (sync, temporal-based)
+- Debugging support with VS Code integration
+
+### Code Generation
+Most SDK code is auto-generated. Manual changes are preserved in:
+- `src/agentex/lib/` directory
+- `examples/` directory
+- Merge conflicts may occur between manual patches and generator changes
+
+### Key Dependencies
+- `temporalio` - Temporal workflow engine
+- `typer` - CLI framework  
+- `pydantic` - Data validation
+- `httpx` - HTTP client
+- `fastapi` - Web framework
+- `ruff` - Linting and formatting
+- `pytest` - Testing framework
+
+### Environment Requirements
+- Python 3.12+ required
+- Uses Rye for dependency management
+- Supports both sync and async client patterns

CONTRIBUTING.md

@@ -126,3 +126,33 @@ You can release to package managers by using [the `Publish PyPI` GitHub action](
 
 If you need to manually release a package, you can run the `bin/publish-pypi` script with a `PYPI_TOKEN` set on
 the environment.
+
+## 🤖 **Vibe Coding Setup**
+
+This repository is setup with some pre-canned prompts for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as well as [Cursor](https://cursor.com/).
+
+### Cursor
+
+Access to Cursor can be acquired by asking for it in #it-help.  Then just loading this repo in the Cursor IDE should enable the prompts.
+
+### Claude Code
+
+### 1. Install Claude Code
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+### 2. Request a LiteLLM API Key
+Visit the [LiteLLM User Guide](https://scale.atlassian.net/wiki/spaces/EPD/pages/1490354189/LiteLLM+User+Guide#Requesting-LiteLLM-Key-for-Generic-Usage) to request your API key.
+
+### 3. Set Environment Variables
+```bash
+export ANTHROPIC_AUTH_TOKEN=${LITELLM_PROXY_API_KEY}
+export ANTHROPIC_BASE_URL="https://litellm.ml-serving-internal.scale.com"
+```
+
+### 4. Start Claude Code
+```bash
+claude
+```
+This should be run from inside the main repo directory. If you run the command from a terminal inside VSCode, then Claude will use the VSCode editor to show diffs etc.