OpenPolicy Monorepo Development

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.

Core Principle: Legacy Code Reuse First

**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.

Development Standards

Code Style & Language Requirements

**TypeScript:**

Use strict mode for all TypeScript projects

Avoid `any` type; model domain types explicitly

Use ES6+ features, arrow functions, and async/await

Prefer immutability and functional decomposition

**Python:**

Require Python >=3.11

Enforce Ruff + Black formatting

Keep functions pure where possible

Strict type annotations required

**General:**

All new APIs and data loaders require tests first (TDD approach)

Avoid duplicate code via abstraction

Handle edge cases and input validation rigorously

Use JSDoc or type annotations as appropriate for the language

Architecture Principles

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

Security & Safety

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

AI Assistant Behavior

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

Version Control

**Commit Message Format (Conventional Commits):**

`feat:` - New features

`fix:` - Bug fixes

`chore:` - Maintenance tasks

`refactor:` - Code restructuring

`test:` - Test additions/changes

`docs:` - Documentation updates

`ci:` - CI/CD changes

Write concise, meaningful messages. Explain rationale for major changes in PRs or commit bodies.

Repository Merging Workflow

When merging multiple repositories into the monorepo:

**Phase 1: Preparation**

Produce or update architectural map/diagram of both source and target repos

Identify conflicts: duplicate files/classes/functions/module names

Plan the merge in phases: Move code → Unify structure → Resolve conflicts → Integrate tooling → Update docs

**Phase 2: Code Organization**

Standardize all folder/file naming

Flatten redundant directories (merge multiple `/src`/`/test` etc.)

Move shared logic/utilities to `common/` at root level

Eliminate duplicate code by suggesting unification or abstraction

**Phase 3: Conflict Resolution**

Auto-detect and list all conflicts

For every duplicated/conflicting fragment, propose the best candidate

Document resolution process

Preserve git history where possible; otherwise note source repo/path in headers

**Phase 4: Tooling Integration**

Upgrade, merge, and unify test runners (Jest, Pytest, etc.)

Consolidate linters and formatters for a single workflow

Ensure no merged code breaks lint or test on CI

Propose test or linter migration where disparate tools exist

**Phase 5: Documentation**

Merge documentation (README, LICENSE, CONTRIBUTING)

Update links and source attribution

Maintain a migration report in `docs/`: list moved/transformed files, structural changes, outstanding items

Every moved module/file should reference original source in comments or commit logs

Insert links to original repo URLs/commits for auditability

**Best Practices:**

Use feature branches/worktrees for each merge phase

Keep AI context up to date by opening relevant files and closing unrelated tabs

Run all test suites after merge; summarize conflicts and next steps

Schedule a post-mortem in docs on challenges and automation wins/gaps

Codebase Organization

Maintain traceability of migrated code in comments and commit messages

Mark deprecated/legacy code with clear isolation in `/legacy` directory

Add explicit deprecation notes in `/docs/REFERENCE/omitted.md`

Standardize config formats across the monorepo

Refactor and upgrade dependencies to a unified system

API & External Integration

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

UI/UX & Accessibility (When Applicable)

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

Collaboration & Communication

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

Continuous Improvement

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

Example Usage

**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

Constraints

Never delete code from `/legacy` directory without explicit approval

Never commit secrets, API keys, or credentials

Never skip the legacy code check before implementing new features

Never break existing API contracts without feature flags

All code must pass linting and testing before merge

Maintain 85%+ statement coverage and 95%+ branch coverage for critical modules

OpenPolicy Monorepo Development

OpenPolicy Monorepo Development

Core Principle: Legacy Code Reuse First

Development Standards

Code Style & Language Requirements

Architecture Principles

Security & Safety

AI Assistant Behavior

Version Control

Repository Merging Workflow

Codebase Organization

API & External Integration

UI/UX & Accessibility (When Applicable)

Collaboration & Communication

Continuous Improvement

Example Usage

Constraints

Reviews (0)