Skip to content

Commit f8cf261

Browse files
chakrrischakrris
committed
Add Claude Code and Cursor IDE configuration
- Add Claude Code settings with permissions for web search, docs access, and rye commands - Add comprehensive Cursor rules for repository tooling, architecture, and development workflow - Add CLAUDE.md with detailed development commands and architecture overview - Update CONTRIBUTING.md with vibe coding setup instructions for both Claude Code and Cursor
1 parent f9ef768 commit f8cf261

12 files changed

+299
-0
lines changed

‎.claude/settings.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"WebSearch",
5+
"WebFetch(domain:docs.temporal.io)",
6+
"Bash(rye run pytest:*)",
7+
"Bash(rye run lint:*)",
8+
"Bash(rye run typecheck:*)",
9+
"Bash(rye run sync:*)",
10+
"Bash(rye run build:*)"
11+
],
12+
"deny": [],
13+
"ask": []
14+
}
15+
}

‎.cursor/rules/00_repo_tooling.mdc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
description: Project-wide tooling, env, and command conventions
3+
globs: "**/*"
4+
alwaysApply: true
5+
---
6+
7+
Use Rye for Python dependency management and workflows. Prefer these commands:
8+
9+
- Setup env: `./scripts/bootstrap` or `rye sync --all-features` [[Use Rye in this repo]]
10+
- Run tests: `rye run pytest` or `./scripts/test`
11+
- Run a specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v`
12+
- Format: `rye run format` or `./scripts/format`
13+
- Lint: `rye run lint` or `./scripts/lint`
14+
- Type check: `rye run typecheck` (runs pyright and mypy)
15+
- Build: `rye build`
16+
17+
Environment requirements:
18+
19+
- Python 3.12+ is required
20+
- A mock server auto-starts for tests on port 4010
21+
22+
Notes:
23+
24+
- 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‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
description: Cursor agent permissions and allowed tools aligned with Claude settings
3+
globs: "**/*"
4+
alwaysApply: true
5+
---
6+
7+
When invoking external tools or the terminal, follow these constraints:
8+
9+
- Web search is allowed when needed for docs and references
10+
- Prefer fetching docs from `docs.temporal.io` when researching Temporal topics
11+
- Allowed bash commands should go through Rye workflows:
12+
- `rye run pytest:*`
13+
- `rye run lint:*`
14+
- `rye run typecheck:*`
15+
- `rye run sync:*`
16+
- `rye run build:*`
17+
18+
Default to Rye; only use other tools when explicitly required by the codebase.

‎.cursor/rules/10_architecture.mdc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: Repository architecture overview and code navigation hints
3+
globs: "src/agentex/**, examples/**, tests/**, README.md"
4+
alwaysApply: false
5+
---
6+
7+
Code structure expectations:
8+
9+
- `src/agentex/` contains the core SDK and generated API client code
10+
- `src/agentex/lib/` contains manually maintained code that should not be overwritten by the code generator
11+
- `cli/` Typer-based CLI implementation
12+
- `core/` Core services, adapters, and Temporal workflows
13+
- `sdk/` SDK utilities and FastACP implementation
14+
- `types/` Custom type definitions
15+
- `utils/` Utility functions
16+
- `examples/` provides example implementations and tutorials
17+
- `tests/` contains the test suites
18+
19+
Key components quick reference:
20+
21+
- Client Layer: HTTP client for AgentEx API in `_client.py` and `resources/`
22+
- CLI Layer: Typer-based commands under `lib/cli/`
23+
- Core Services: Temporal workflows and services under `lib/core/`
24+
- FastACP: Protocol implementation in `lib/sdk/fastacp/`
25+
- State Machine: Workflow state management in `lib/sdk/state_machine/`
26+
27+
Generated vs manual code:
28+
29+
- Treat `src/agentex/lib/**` as manual code; avoid edits in generated areas unless regenerating consistently
30+
- Expect merge conflicts between generator outputs and manual patches; keep custom logic in `lib/`

‎.cursor/rules/20_codegen_boundaries.mdc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Keep manual code separate from generated SDK code
3+
globs: "src/agentex/**"
4+
alwaysApply: true
5+
---
6+
7+
Guideline:
8+
9+
- Avoid modifying auto-generated files in `src/agentex/` except where explicitly intended. Place custom logic, extensions, and higher-level abstractions in `src/agentex/lib/`.
10+
- When adding features, prefer adding new modules under `src/agentex/lib/**` rather than changing generated files directly.
11+
- 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‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
description: Guidance for working with the agentex CLI and commands
3+
globs: "src/agentex/lib/cli/**, src/agentex/lib/core/**"
4+
alwaysApply: false
5+
---
6+
7+
The `agentex` CLI exposes:
8+
9+
- `agentex agents` for get/list/run/build/deploy agents
10+
- `agentex tasks` for get/list/delete tasks
11+
- `agentex secrets` for sync/get/list/delete secrets
12+
- `agentex uv` as a UV wrapper with AgentEx-specific enhancements
13+
- `agentex init` to initialize new agent projects
14+
15+
Development tips:
16+
17+
- For agent development, use `agentex agents run --manifest manifest.yaml`
18+
- For debugging, append `--debug-worker` and optionally `--debug-port 5679`

‎.cursor/rules/40_temporal_and_agents.mdc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
description: Temporal workflows, activities, and agent development guidance
3+
globs: "src/agentex/lib/core/temporal/**, examples/**/10_temporal/**"
4+
alwaysApply: false
5+
---
6+
7+
Temporal integration:
8+
9+
- Workflow definitions live in `lib/core/temporal/`
10+
- Include activity definitions for different providers and worker implementations
11+
- Keep workflow logic deterministic and side-effect free; move I/O into activities
12+
13+
Agent framework:
14+
15+
- Agents are manifest-driven and support multiple agent types (sync and Temporal-based)
16+
- Use the examples under `examples/10_agentic/` and `examples/10_temporal/` for patterns
17+
- For debugging agents, use the CLI flags `--debug-worker` and `--debug-port`

‎.cursor/rules/50_tests_and_mocking.mdc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
description: Testing workflow and mock server details
3+
globs: "tests/**, scripts/test, scripts/mock"
4+
alwaysApply: true
5+
---
6+
7+
Testing:
8+
9+
- Run tests with `rye run pytest` or `./scripts/test`
10+
- To run a specific test: `rye run pytest path/to/test_file.py::TestClass::test_method -v`
11+
- A mock server is automatically started for tests on port 4010
12+
13+
When writing tests:
14+
15+
- Prefer deterministic unit tests that do not depend on external services
16+
- Use the mock server and fixtures provided in the repository

‎.cursor/rules/60_style_lint_typecheck.mdc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
description: Formatting, linting, and type checking standards
3+
globs: "src/**, tests/**"
4+
alwaysApply: true
5+
---
6+
7+
Standards:
8+
9+
- Format code via `rye run format` or `./scripts/format`
10+
- Lint via `rye run lint` or `./scripts/lint`
11+
- Type check via `rye run typecheck` (pyright + mypy)
12+
13+
Guidance:
14+
15+
- Keep code readable and consistent; prefer small, focused functions
16+
- Avoid introducing style or type violations; fix before committing

‎.cursor/rules/70_examples_and_docs.mdc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: How to use examples and documentation for development
3+
globs: "examples/**, README.md"
4+
alwaysApply: false
5+
---
6+
7+
Use the `examples/` directory as reference implementations and tutorials. When creating new features:
8+
9+
- Mirror patterns from the closest matching example
10+
- Keep examples runnable with the documented commands
11+
- Prefer adding or updating examples alongside significant feature changes

0 commit comments

Comments
 (0)