adressing review comments

Author: vishwa-uber

README.md

@@ -2,6 +2,8 @@
 
 [Cadence](https://github.com/uber/cadence) is a distributed, scalable, durable, and highly available orchestration engine we developed at Uber Engineering to execute asynchronous long-running business logic in a scalable and resilient way.
 
+If you'd like to propose a new feature, first join the [CNCF Slack workspace](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to start a discussion.
+
 `cadence-python-client` is the Python framework for authoring workflows and activities.
 
 ## Disclaimer
@@ -16,34 +18,111 @@
 ```bash
 git clone https://github.com/cadence-workflow/cadence-python-client.git
 cd cadence-python-client
-uv venv
-uv pip install -e ".[dev]"
 ```
 
-For detailed setup instructions, development workflow, and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+## Development
 
-## Contributing
+### Setup
 
-We'd love your help in making Cadence great! Please review our [contribution guide](CONTRIBUTING.md).
+1. **Install protobuf (required):**
+   ```bash
+   # macOS
+   brew install protobuf@29
 
-If you'd like to propose a new feature, first join the [CNCF Slack workspace](https://communityinviter.com/apps/cloud-native/cncf) in the **#cadence-users** channel to start a discussion.
+   # Linux/Other
+   # Install protobuf 29.x via your package manager
+   ```
+
+2. **Install uv (recommended):**
+   ```bash
+   # macOS
+   brew install uv
+
+   # Linux/Other
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   source $HOME/.local/bin/env  # Add to your shell profile for persistence
+   ```
+
+3. **Create virtual environment and install dependencies:**
+   ```bash
+   uv venv
+   uv pip install -e ".[dev]"
+   ```
+
+   Or if you prefer traditional pip:
+   ```bash
+   python3.11 -m venv venv
+   source venv/bin/activate  # Windows: venv\Scripts\activate
+   pip install -e ".[dev]"
+   ```
 
-## Community
+### Generate Protobuf and gRPC Files
 
-- [GitHub Issues](https://github.com/cadence-workflow/cadence-python-client/issues)
-  - Best for reporting bugs and feature requests
-- [Stack Overflow](https://stackoverflow.com/questions/tagged/cadence-workflow)
-  - Best for Q&A and general discussion
-- [Slack](https://communityinviter.com/apps/cloud-native/cncf) - Join **#cadence-users** channel on CNCF Slack
-  - Best for contributing/development discussion
+Run the generation script:
+```bash
+# Using uv (recommended)
+uv sync --extra dev
+uv run python scripts/generate_proto.py
+
+# Or using traditional Python
+python scripts/generate_proto.py
+```
+
+This will:
+- Download protoc 29.1 binary
+- Install grpcio-tools if needed
+- Generate Python protobuf files in `cadence/api/v1/`
+- Generate gRPC service files in `cadence/api/v1/`
+- Create proper package structure with both protobuf and gRPC imports
 
-## Documentation
+### Test
 
-Visit [cadenceworkflow.io](https://cadenceworkflow.io) to learn more about Cadence.
+Verify the generated files work:
+```bash
+# Using uv (recommended)
+uv run python cadence/sample/simple_usage_example.py
+uv run python cadence/sample/grpc_usage_example.py
+
+# Or using traditional Python
+python cadence/sample/simple_usage_example.py
+python test_grpc_with_examples.py
+```
 
-- [Documentation](https://cadenceworkflow.io/docs/)
-- [Main Cadence Repository](https://github.com/uber/cadence)
-- [Cadence Samples](https://github.com/cadence-workflow/cadence-samples)
+### Development Script
+
+The project includes a development script that provides convenient commands for common tasks:
+
+```bash
+# Generate protobuf files
+uv run python scripts/dev.py protobuf
+
+# Run tests
+uv run python scripts/dev.py test
+
+# Run tests with coverage
+uv run python scripts/dev.py test-cov
+
+# Run linting
+uv run python scripts/dev.py lint
+
+# Format code
+uv run python scripts/dev.py format
+
+# Install in development mode
+uv run python scripts/dev.py install
+
+# Install with dev dependencies
+uv run python scripts/dev.py install-dev
+
+# Build package
+uv run python scripts/dev.py build
+
+# Clean build artifacts
+uv run python scripts/dev.py clean
+
+# Run all checks (lint + test)
+uv run python scripts/dev.py check
+```
 
 ## License