# Contributing

Thanks for your interest in contributing to `pi-compound-engineering`.

## Development setup

```bash
cd packages/pi-compound-engineering
npm install
npm run check
```

The package is source-distributed: Pi loads the TypeScript extension files directly. There is no build step for runtime use. The `preinstall` and `postinstall` scripts are pure-Node ESM and run during `npm install` to fetch and convert the upstream CE release into the install directory.

## Local testing

Install this checkout into a temporary Pi project:

```bash
mkdir -p <test-project>
cd <test-project>
pi install -l /path/to/pi-mono/packages/pi-compound-engineering
pi install npm:pi-subagents
pi install npm:pi-ask-user
pi
```

Then run `/ce-status` inside Pi and verify the `[Skills]` list shows 39 `ce-*` entries.

To exercise the install-time scripts in isolation:

```bash
# Stage into $TMP/pi-compound-engineering-staging-<pid>/
node scripts/stage.mjs

# Move the staged content into the install dir
node scripts/commit.mjs
```

The lifecycle is idempotent — re-running either script is safe.

## Pull request checklist

Before opening a pull request:

- Run `npm run check`.
- Run `npm run verify` and confirm counts + content match the expected pin.
- Run `npm run pack:dry-run` and confirm the package contents are intentional.
- Update `README.md` if user-facing behavior changes.
- Update `CHANGELOG.md` for notable changes.
- Keep examples and paths generic; do not commit machine-specific paths or credentials.

## Updating the upstream pin

This is the most common contribution. When CE upstream tags a new release (e.g. `cli-v3.14.0`):

1. Bump `CE_VERSION` in `src/ce-version.ts` **and** the `"version"` field in `package.json` to the new upstream version string. The version of `pi-compound-engineering` is identical to the upstream CE component version; the dual write is the lockstep contract.
2. Compute the new SHA256 locally:
   ```bash
   curl -sL "https://codeload.github.com/EveryInc/compound-engineering-plugin/tar.gz/refs/tags/cli-v<NEW_VERSION>" | sha256sum
   ```
3. Replace the contents of `scripts/expected-sha256.txt` with the new SHA.
4. Run `npm run verify` locally to confirm the fetch + convert works end-to-end. If counts have changed (CE added/removed skills or agents), update the expected counts in `src/ce-version.ts`.
5. Add a `CHANGELOG.md` entry under a new `## [<version>] - <date>` heading, summarising the upstream changes.
6. Commit (small diff: `src/ce-version.ts`, `package.json`, `scripts/expected-sha256.txt`, `CHANGELOG.md`).
7. Open a PR to `main`. CI runs `verify` against the upstream tag.
8. Tag the merge commit as `pi-compound-engineering@<version>` and push the tag. The publish workflow handles the rest.

## Divergence handling

If a Pi-specific change is needed (e.g. upstream adds a new `Task` primitive that the port doesn't yet handle, or a skill references a tool that doesn't exist in Pi and needs a workaround):

1. **First, send the fix upstream** as a PR to [`EveryInc/compound-engineering-plugin`](https://github.com/EveryInc/compound-engineering-plugin). CE accepts contributions; the maintainers have explicitly said as much in the README. The upstream converter change is the right place for "translate CE to Pi" fixes; the workaround paragraph (if any) belongs in the skill body upstream so every target benefits.
2. If the upstream PR is not merged in time, the workaround lives in `scripts/converter.mjs` (e.g. a Pi-specific string substitution) and is documented in `CHANGELOG.md` under a `### Notes` subsection. The structure check in `verify` keeps the workaround honest: if the converter port produces wrong output, the representative-content assertions fail and CI blocks the release.
3. If a skill itself needs a Pi-specific paragraph that cannot be sent upstream (e.g. a paragraph explaining how to invoke a Pi-only tool), record it in `CHANGELOG.md` and tell the user to read it. The recipe-only model means we have no in-tree place to put such a paragraph that survives the next postinstall.

The default is: zero in-tree modifications of CE content.

## Coding guidelines

- Keep extensions small and focused.
- Prefer Pi's documented extension APIs and TUI primitives over private internals.
- Do not introduce npm dependencies in `scripts/*.mjs`. The install-time scripts must run with `node` alone, no `node_modules/` lookups.
- Be careful with `THIRD-PARTY-NOTICES`: it is generated by the converter and overwritten on every install. Do not commit it.
- The `AGENTS.md` block written by `src/agents-block.ts` is gated by `<!-- BEGIN COMPOUND PI TOOL MAP -->` / `<!-- END COMPOUND PI TOOL MAP -->` markers and is idempotent across reloads. Do not change the marker text without coordinating with the upstream CE maintainers — it is the same marker used by the Codex target.

## Code of conduct

This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).