Merge remote-tracking branch 'origin/main' into refactor/migrate-to-connector-based-naming

Author: ryoppippi

.claude/rules/development-workflow.md

@@ -0,0 +1,63 @@
+---
+description: Code style, file naming, and project conventions. (project)
+alwaysApply: true
+---
+
+# Development Workflow
+
+This rule provides code style guidelines and project conventions for the StackOne AI Python SDK.
+
+## Code Style
+
+- Use [ruff](https://docs.astral.sh/ruff/) for linting and formatting
+- Follow PEP 8 style guidelines
+- Maximum line length: 88 characters (ruff default)
+- Run `just lint` to check, `just lint-fix` to auto-fix
+
+## Type Annotations
+
+- Full type annotations required for all public APIs
+- Use Python 3.11+ typing features
+- Run `just mypy` to verify type correctness
+- Strict mypy configuration is enforced
+
+## Pre-commit Hooks
+
+Pre-commit hooks are configured for:
+
+- ruff linting
+- mypy type checking
+
+Run `just install` to set up hooks.
+
+## Essential Commands
+
+```bash
+just install       # Install dependencies and pre-commit hooks
+just lint          # Run ruff linting
+just lint-fix      # Auto-fix linting issues
+just mypy          # Run type checking
+just test          # Run all tests
+just test-tools    # Run tool-specific tests
+just test-examples # Run example tests
+```
+
+## File Naming
+
+- Use snake_case for Python files
+- Use `.yaml` extension instead of `.yml` for YAML files
+- Keep file names concise but meaningful
+
+## Import Organization
+
+- Standard library imports first
+- Third-party imports second
+- Local imports last
+- Use absolute imports (see no-relative-imports rule)
+
+## Working with Tools
+
+- Use semantic tools for code exploration (avoid full file reads when possible)
+- Leverage symbol indexing for fast navigation
+- Use grep/ripgrep for pattern matching
+- Read only necessary code sections

.claude/rules/examples-standards.md

@@ -0,0 +1,75 @@
+---
+description: Standards for creating and maintaining examples for all functionality. (project)
+globs: examples/**/*
+paths: examples/**/*
+---
+
+# Examples Standards
+
+Standards for creating and maintaining examples in the StackOne repository.
+
+## Location Requirements
+
+```
+examples/
+├── basic_usage/
+│   ├── basic_tool_usage.py      # Basic usage examples
+│   └── error_handling.py        # Error handling examples
+├── integrations/                # Integration examples
+│   ├── openai_integration.py
+│   └── other_integration.py
+└── README.md                    # Examples documentation
+```
+
+## Example Requirements
+
+- Every public function/class needs at least one example
+- Examples should be runnable Python scripts
+- Include error handling cases
+- Load credentials from .env
+- Include type hints
+- Follow the same code style as the main codebase
+
+## Documentation
+
+- Each example file should start with a docstring explaining its purpose
+- Include expected output in comments
+- Document any prerequisites (environment variables, etc)
+
+## Testing
+
+- Examples should be tested as part of CI
+- Examples should work with the latest package version
+- Include sample responses in comments
+
+## Good Example Structure
+
+```python
+import os
+from dotenv import load_dotenv
+from stackone_ai import StackOneToolSet
+
+def main():
+    """Example showing basic usage of StackOneToolSet."""
+    load_dotenv()
+
+    api_key = os.getenv("STACKONE_API_KEY")
+    if not api_key:
+        raise ValueError("STACKONE_API_KEY not found")
+
+    # Example code...
+
+if __name__ == "__main__":
+    main()
+```
+
+## Bad Example (avoid)
+
+```python
+# Missing error handling, docs, types
+from stackone_ai import StackOneToolSet
+
+toolset = StackOneToolSet("hardcoded_key")
+tools = toolset.get_tools("crm")
+result = tools["some_tool"].execute()
+```

.claude/rules/git-workflow.md

@@ -0,0 +1,97 @@
+---
+description: Git workflow, commit conventions, and pull request guidelines. (project)
+alwaysApply: true
+---
+
+# Git Workflow
+
+This rule provides guidance on git workflow, commit conventions, and pull request guidelines.
+
+## Branch Strategy
+
+- **Never push directly to main** without permission
+- Create a new branch for changes
+- Create a pull request to merge into main
+- Use `git switch -c feature-name` to start
+
+## Development Flow
+
+1. Create feature branch: `git switch -c feature-name`
+2. Make changes to source files
+3. Run linter: `just lint`
+4. Run tests: `just test`
+5. Fix linting issues: `just lint-fix`
+6. Commit with detailed messages
+7. Push and create PR: `gh pr create`
+
+## Commit Strategy
+
+Keep commits tiny but meaningful:
+
+- Use git hunks (`-p` flag) to selectively commit changes
+- Write detailed commit messages
+- Ensure each commit is logically complete
+- Use English for all commit messages
+
+## Commit Message Format
+
+Format: `type(scope): description`
+
+Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `perf`
+
+Example:
+
+```
+feat(parser): add support for custom parameter transformers
+
+- Add new transformer hooks to OpenAPI parser
+- Enable pre-processing of tool parameters
+- Implement docs for custom transformers
+```
+
+### Guidelines
+
+- Keep each commit as tiny as possible
+- Write detailed commit messages explaining the "why"
+- Each commit should be meaningful (not just a single line change)
+- Use git hunks (`-p` flag) to selectively commit related changes
+- **Always use English** for commit messages
+- Reference issues and PRs when relevant
+
+### When Committing
+
+1. Run `git diff` to review all changes
+2. Use `git add -p` to review and stage hunks selectively
+3. Write comprehensive message explaining the purpose
+4. Verify with `git status` before committing
+
+### File Moves for History Preservation
+
+When moving files (e.g., migrating from skills to rules), combine the deletion and creation in a single commit so git treats it as a rename. This preserves file history.
+
+```bash
+# Instead of separate add/delete commits:
+git add .claude/rules/new-file.md
+git rm .claude/skills/old-file/SKILL.md
+git commit -m "refactor(rules): migrate old-file to rules directory"
+```
+
+## Pull Request Guidelines
+
+### PR Title Format
+
+Use the same format as commit messages: `type(scope): description`
+
+Examples:
+
+- `feat(tools): add support for custom OpenAPI specs`
+- `fix(parser): handle empty response bodies`
+- `refactor(rules): unify cursor rules and claude rules`
+
+### PR Body
+
+Include:
+
+- **Summary**: 1-3 bullet points describing changes
+- **Test plan**: How to verify the changes work
+- Reference related issues with `Closes #123` or `Fixes #123`

.claude/rules/no-relative-imports.md

@@ -0,0 +1,27 @@
+---
+description: Enforce the use of absolute imports instead of relative imports in Python files. (project)
+globs: "**/*.py"
+paths: "**/*.py"
+---
+
+# No Relative Imports
+
+Standards for using absolute imports instead of relative imports in Python files.
+
+## Guidelines
+
+- Always use absolute imports starting with the full package name (`stackone_ai`)
+- Never use relative imports (`.` or `..`)
+- Keep imports organized and grouped
+
+## Examples
+
+```python
+# Good - absolute imports
+from stackone_ai.tools import ToolDefinition
+from stackone_ai.constants import OAS_DIR
+
+# Bad - relative imports (don't use)
+from .tools import ToolDefinition
+from ..constants import OAS_DIR
+```

.claude/rules/package-installation.md

@@ -0,0 +1,59 @@
+---
+description: Standards for installing packages with UV in StackOne. (project)
+globs: "**/pyproject.toml"
+paths: "**/pyproject.toml"
+---
+
+# Package Installation Standards
+
+Standards for installing packages with UV in the StackOne repository.
+
+## Root Level Dev Dependencies
+
+```bash
+# Install dev dependencies at root level
+uv add --dev pytest
+uv add --dev pytest-cov
+uv add --dev black
+```
+
+## Package Level Dependencies
+
+```bash
+# Install package dependencies
+uv add pydantic
+uv add requests
+```
+
+## Never Use
+
+```bash
+# ❌ Don't use pip install
+uv pip install package-name
+
+# ❌ Don't use -e or editable installs
+uv pip install -e .
+```
+
+## Running Tests
+
+```bash
+# Run from root directory
+uv run pytest
+
+# Run specific package tests
+uv run pytest stackone_ai
+
+# Run tests on examples
+uv run pytest examples
+```
+
+## Package Dependencies in pyproject.toml
+
+```toml
+[project]
+dependencies = [
+    "pydantic>=2.10.6",
+    "requests>=2.32.3",
+]
+```

.claude/rules/release-please-standards.md

@@ -0,0 +1,63 @@
+---
+description: Standards for using release-please in the repository. (project)
+alwaysApply: true
+---
+
+# Release Please Standards
+
+Standards for managing releases with release-please in the repository.
+
+## Configuration Files
+
+```
+.release-please-config.json    # Release configuration
+.release-please-manifest.json  # Version tracking
+.github/workflows/release.yml  # Release workflow
+```
+
+## Commit Message Format
+
+```bash
+# Features (0.1.0 -> 0.2.0)
+feat: add new feature
+feat!: breaking change feature
+
+# Bug Fixes (0.1.0 -> 0.1.1)
+fix: bug fix description
+
+# No Version Change
+docs: update readme
+chore: update dependencies
+test: add new tests
+```
+
+## Release Process
+
+1. Push to main branch triggers release-please
+2. Release-please creates/updates release PR
+3. Merging release PR:
+   - Updates CHANGELOG.md
+   - Creates GitHub release
+   - Publishes to PyPI using UV
+
+## Required Secrets
+
+```
+PYPI_API_TOKEN  # For publishing to PyPI
+```
+
+## Good Commit Messages
+
+```bash
+docs: update installation guide
+fix: handle API timeout errors
+feat: add new CRM integration
+```
+
+## Bad Commit Messages (avoid)
+
+```bash
+updated readme
+fixed bug in api
+added feature
+```