Projen GitHub Copilot Instructions

This skill provides comprehensive guidance for working with projen-managed projects, specifically tailored for ClickUp's development practices. It covers task execution, file modification rules, dependency management, and development workflows for TypeScript and CDK projects.

Core Principles

Task Execution Rules

**ALWAYS use projen for task execution**. Never run tasks directly with npm, yarn, or other package managers.

**Common tasks:**

File Modification Guidelines

**NEVER manually edit generated files**. Files marked with comments like "~~ Generated by projen. To modify..." are auto-generated.

**Workflow for configuration changes:**

1. Edit the `.projenrc.ts`, `.projenrc.py`, or `.projenrc.json` file

2. Run `npx projen` to regenerate project files

3. Review the changes

4. Commit both `.projenrc` and the generated files

**Before suggesting changes** to `package.json`, `tsconfig.json`, or other config files, check if they're projen-managed and suggest changes to `.projenrc` instead.

Dependency Management

Add dependencies through projen configuration, not by editing package.json directly.

In `.projenrc`, use methods like:

Then run `npx projen` to apply changes.

Development Best Practices

Task Completion Criteria

A task is NOT complete until:

**Always run build after changes** to ensure changes compile and pass all tests.

Testing

Run a single test file:

```bash

pnpm test path/to/test-file.test.ts

```

Run tests in watch mode:

```bash

pnpm test:watch

```

ClickUp Projen Project Types

Architecture Overview

This repository provides JSII library exports for custom Projen project classes with opinionated ClickUp configurations.

**Core modules:**

Project Types

#### ClickUpTypeScriptProject

Base class for TypeScript libraries with:

#### ClickUpCdkConstructLibrary

For reusable CDK construct libraries:

#### ClickUpCdkTypeScriptApp

For CDK applications:

Configuration Philosophy

This library is **highly opinionated**:

1. **Deep Merge Strategy** - Uses `ts-deepmerge` to overlay defaults → project options → forced overrides

2. **JSII Constraints** - Limited to JSII-compatible TypeScript features

3. **Bundled Dependencies** - `cson-parser`, `semver`, `ts-deepmerge` bundled to avoid consumer conflicts

Common Development Patterns

Testing Changes Locally

Build a local tarball and test in another project:

```bash

pnpm build

Creates: dist/js/[email protected]

In another project:

projen new --from /path/to/clickup-projen/dist/js/[email protected] <project-type>

```

Snapshot Testing

Tests use snapshot testing extensively. When making changes:

1. Update the code

2. Run `pnpm test` - snapshots may fail

3. Review snapshot diffs carefully

4. Run `pnpm test -- -u` to update snapshots if changes are intentional

5. Commit updated snapshots with your changes

Adding New Features

1. Create or modify a module in `src/`

2. Add corresponding test in `test/`

3. Export from `src/index.ts` if it's a public API

4. Run `pnpm projen` to regenerate API.md

5. Run `pnpm test -- -u` to update snapshots

6. Verify in a test project using local tarball

Creating Workflow Integrations

Follow the pattern in existing workflow modules:

1. Create a module that exports a function to add the workflow

2. Accept a project and optional configuration options

3. Use `project.github.addWorkflow()` or similar APIs

4. Add helper functions for common configurations

5. Call from project constructors in `clickup-cdk.ts` or `clickup-ts.ts`

Repository-Specific Notes

GitHub Packages Authentication

Consumers need GitHub Packages access:

```bash

cat >> ~/.npmrc <<EOF

//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT

@time-loop:registry=https://npm.pkg.github.com/

EOF

```

PAT requires `read:packages` scope minimum.

Naming Conventions

GitHub Actions Workflows

Generated projects include:

All workflows require GitHub Packages authentication in repository secrets.

Key Resources