Comprehensive development rules for the OpenPolicy monorepo with strict legacy code reuse policy, TypeScript/Python best practices, API-first design, and systematic multi-repo merge workflow. Emphasizes test-driven development, security, and architectural documentation.
This skill enforces comprehensive development standards for the OpenPolicy monorepo, with a fundamental emphasis on code reuse from legacy systems, strict typing, API-first design, and systematic repository merging practices.
**BEFORE implementing ANY new functionality:**
1. Check the `/legacy` directory for similar existing code
2. If found, copy and adapt the legacy implementation rather than writing from scratch
3. Preserve original comments noting the source, then document your adaptations
4. This applies to parsers, APIs, utilities, data loaders, transformers, validators, and all other components
This is the most critical rule and must never be skipped.
**TypeScript:**
**Python:**
**General:**
1. **API-First Design:**
- Update `openapi.yaml` before implementing endpoints
- Never break existing contracts
- Introduce new fields behind feature flags
- Avoid breaking changes
2. **Idempotent Ingestion:**
- All data loaders must support upsert semantics
- Ensure ingestion can be safely re-run
3. **Test Coverage Requirements:**
- Statement coverage: 85%+ for `services/api-gateway` and `services/etl`
- Branch coverage: 95%+ for critical modules (parsers, normalizers)
- Generate integration and unit test cases for all major changes
- Run all test suites post-merge
1. **Never delete files in `/legacy`** - propose replacements under `/services` or `/apps` and mark deprecated code in `/docs/REFERENCE/omitted.md`
2. Never commit secrets or credentials - always use `.env` and GitHub Actions secrets
3. Sanitize all inputs to prevent injection/XSS attacks
4. Use environment variables for API keys and secrets
5. Do not log sensitive data
When working on this codebase:
1. Treat `instructions.md` as the single source of truth for task scope
2. When uncertain, auto-generate a design note in `docs/ADR/` with pros/cons/decision
3. Provide clear plan or reasoning before code changes
4. Ask clarifying questions on ambiguous prompts
5. Always include unit tests alongside code changes
6. Suggest alternative patterns with rationale
7. Avoid fabrications; seek factual or confirmed knowledge
**Commit Message Format (Conventional Commits):**
Write concise, meaningful messages. Explain rationale for major changes in PRs or commit bodies.
When merging multiple repositories into the monorepo:
**Phase 1: Preparation**
**Phase 2: Code Organization**
**Phase 3: Conflict Resolution**
**Phase 4: Tooling Integration**
**Phase 5: Documentation**
**Best Practices:**
1. Handle API errors with retries, timeouts, and clear logs
2. Respect and document rate limits
3. Use explicit environment variable configs for API keys and secrets
4. Never hardcode sensitive information
1. Ensure responsive design and semantic HTML
2. Apply ARIA roles and keyboard navigation
3. Provide fallback UI for loading, error, and empty states
4. Prioritize accessibility: color contrast, focus indicators, readable fonts
1. When changes may impact other teams or systems, document the impact and tag relevant owners
2. Clearly document deprecation, API, or config/environment changes
3. Use professional, concise, and friendly communication
4. Avoid jargon unless defined
1. Seek feedback for uncertain or major changes
2. Propose improvements and refactorings beyond immediate requests when justified
3. Avoid off-topic code generation or side conversations
4. Regularly review and update development rules based on results
5. Keep `.cursorrules` file updated as the monorepo evolves
**When adding a new data parser:**
1. First check `/legacy` for existing parser implementations
2. If found, copy the relevant code to the new location
3. Add comment: `// Adapted from /legacy/parsers/original-parser.ts`
4. Refactor to meet current TypeScript strict mode requirements
5. Write comprehensive tests (85%+ coverage)
6. Update `openapi.yaml` if the parser exposes API endpoints
7. Document changes in commit message: `feat: add enhanced data parser (adapted from legacy)`
**When merging a new repository:**
1. Create architectural diagram showing both codebases
2. Create feature branch: `merge/repo-name`
3. Phase 1: Move all code preserving structure
4. Phase 2: Identify and document conflicts
5. Phase 3: Resolve conflicts, unify structure
6. Phase 4: Integrate testing/linting tooling
7. Phase 5: Update documentation and create migration report
8. Submit PR with comprehensive merge summary
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/openpolicy-monorepo-development/raw