---
summary: "Overview and quickstart for {{ repo_name }}."
read_when:
  - "Starting work in this repository."
system4d:
  container: "Repository scaffold for a pi extension package."
  compass: "Ship small, safe, testable extension iterations."
  engine: "Plan -> implement -> verify with docs and hooks in sync."
  fog: "Unknown runtime integration edge cases until first live sync."
---

# @{{ npm_org }}/{{ repo_name }}

A pi extension package for {{ command_name }} workflows.

## Install

```bash
pi install npm:@{{ npm_org }}/{{ repo_name }}
```

## Development

1. Clone and install:

   ```bash
   git clone https://github.com/{{ github_maintainer }}/{{ repo_name }}.git
   cd {{ repo_name }}
   npm install
   ```

2. Pi auto-discovers extensions when working in this directory.

## Runtime dependencies

This extension expects pi host runtime APIs and declares them as `peerDependencies`:

- `@mariozechner/pi-coding-agent`
- `@mariozechner/pi-ai`

When using UI APIs (`ctx.ui`), guard interactive-only behavior with `ctx.hasUI` so `pi -p` non-interactive runs stay stable.

## Repository checks

Run:

```bash
npm run check
```

`check` routes to `quality:ci` via [scripts/quality-gate.sh](scripts/quality-gate.sh).
It enforces structure validation, Biome lint checks, optional TypeScript typechecks, and npm pack dry-run.

## Quality gate lane (TS)

- formatter/lint baseline:
  - [biome.jsonc](biome.jsonc)
  - [.vscode/settings.json](.vscode/settings.json) (Biome formatter + code actions on save for JS/TS/JSON)
  - pinned local binary via `@biomejs/biome` in `devDependencies`
- [scripts/quality-gate.sh](scripts/quality-gate.sh) stages:
  - `pre-commit`
  - `pre-push`
  - `ci`
- npm script entry points:
  - `npm run quality:pre-commit`
  - `npm run quality:pre-push`
  - `npm run quality:ci`
- helper scripts:
  - `npm run fix` (auto-fix)
  - `npm run lint` (check-only)
  - `npm run typecheck`
- lane metadata:
  - [policy/stack-lane.json](policy/stack-lane.json)

## Release + security baseline

This scaffold defaults to **release-please** for single-package release PR + tag flow (`vX.Y.Z`), npm trusted publishing via OIDC, and deterministic release artifact checks.

Included files:

- [CI workflow](.github/workflows/ci.yml)
- [release-check workflow](.github/workflows/release-check.yml)
- [release-please workflow](.github/workflows/release-please.yml)
- [publish workflow](.github/workflows/publish.yml)
- [release-check script](scripts/release-check.sh)
- [Dependabot config](.github/dependabot.yml)
- [CODEOWNERS](.github/CODEOWNERS)
- [release-please config](.release-please-config.json)
- [release-please manifest](.release-please-manifest.json)
- [Security policy](SECURITY.md)

Trusted-publishing defaults captured in this scaffold:

- release-please uses `vX.Y.Z` tags (`include-component-in-tag: false`) to align with publish trigger logic.
- release-please action is pinned to an immutable v4.4.0 SHA.
- publish workflow and release-check workflow both upgrade npm (`>=11.5.1`) for consistent trusted publishing behavior.
- setup-node uses `package-manager-cache: false` to avoid implicit caching behavior changes from setup-node v5+.
- setup-node v6 / setup-python v6 / upload-artifact v6 require Actions Runner `>=2.327.1` on self-hosted runners (GitHub-hosted runners already satisfy this).
- release-check script tolerates npm `already published version` dry-run responses for post-release idempotency.
- package metadata must include `repository.url` matching the GitHub repo for npm provenance verification.

Recommended before release:

```bash
npm run release:check
# quick mode for CI / no local pi smoke
npm run release:check:quick
```

Optional: add an executable `scripts/release-smoke.sh` for extension-specific smoke checks.
`release-check.sh` will run it with isolated `PI_CODING_AGENT_DIR` and `PACKAGE_SPEC` env vars.

Before first production release:

1. Confirm/adjust owners in [.github/CODEOWNERS](.github/CODEOWNERS).
2. Enable branch protection on `main`.
3. Confirm GitHub Actions repo settings:
   - workflow permissions: `Read and write`
   - allow GitHub Actions to create/approve PRs
   - allowed actions policy permits marketplace actions used by workflows
4. Configure npm Trusted Publishing for this repo + [publish workflow](.github/workflows/publish.yml).
5. Merge release PR from release-please, then publish from GitHub release.

## Issue + PR intake baseline

Included files:

- [Bug report form](.github/ISSUE_TEMPLATE/bug-report.yml)
- [Feature request form](.github/ISSUE_TEMPLATE/feature-request.yml)
- [Docs request form](.github/ISSUE_TEMPLATE/docs.yml)
- [Issue template config](.github/ISSUE_TEMPLATE/config.yml)
- [PR template](.github/pull_request_template.md)
- [Code of conduct](CODE_OF_CONDUCT.md)
- [Support guide](SUPPORT.md)
- [Top-level contributing guide](CONTRIBUTING.md)

## Vouch trust gate baseline

Included files:

- [Vouched contributors list](.github/VOUCHED.td)
- [PR trust gate workflow](.github/workflows/vouch-check-pr.yml)
- [Issue-comment trust management workflow](.github/workflows/vouch-manage.yml)

Default behavior:

- PR workflow runs on `pull_request_target` (`opened`, `reopened`).
- `require-vouch: true` and `auto-close: true` are enabled by default.
- Maintainers can comment `vouch`, `denounce`, or `unvouch` on issues to update trust state.
- Vouch actions are SHA pinned for reproducibility and supply-chain review.

Bootstrap step:

- Confirm/adjust entries in [.github/VOUCHED.td](.github/VOUCHED.td) before enforcing production policy.

## Docs discovery

Run:

```bash
npm run docs:list
npm run docs:list:workspace
npm run docs:list:json
```

Wrapper script: [scripts/docs-list.sh](scripts/docs-list.sh)

Resolution order:
1. `DOCS_LIST_SCRIPT`
2. `./scripts/docs-list.mjs` (if vendored)
3. `~/ai-society/core/agent-scripts/scripts/docs-list.mjs`

TypeScript lane reference for pi extensions:

```bash
uv tool run --from ~/ai-society/core/tech-stack-core tech-stack-core show pi-ts --prefer-repo
```

Pinned lane metadata lives in [policy/stack-lane.json](policy/stack-lane.json).

## Copier lifecycle policy

- Keep `.copier-answers.yml` committed.
- Do not edit `.copier-answers.yml` manually.
- Run from a clean destination repo (commit or stash pending changes first).
- Use `copier update --trust` when `.copier-answers.yml` includes `_commit` and update is supported.
- In non-interactive shells/CI, append `--defaults` to update/recopy.
- Use `copier recopy --trust` when update is unavailable (for example local non-VCS source) or cannot reconcile cleanly.
- After recopy, re-apply local deltas intentionally and run `npm run check`.

## Hook behavior

- Git hooks path is configured to `.githooks` by [scripts/install-hooks.sh](scripts/install-hooks.sh).
- [.githooks/pre-commit](.githooks/pre-commit) runs:
  - `scripts/quality-gate.sh pre-commit`
  - check-only (auto-fix with `npm run fix`)
- [.githooks/pre-push](.githooks/pre-push) runs:
  - `scripts/quality-gate.sh pre-push`
- Repo-local commit workflow prompt:
  - [`.pi/prompts/commit.md`](.pi/prompts/commit.md)

## Live sync helper

Use [scripts/sync-to-live.sh](scripts/sync-to-live.sh) to copy extension entrypoints plus
shared `src/` modules into `~/.pi/agent/extensions/{{ repo_name }}/`.

Optional flags:

- `--with-prompts`
- `--with-policy`
- `--all` (prompts + policy)

After sync, run `/reload` in pi.

## Docs map

- [Organization operating model](docs/org/operating_model.md)
- [Project foundation model](docs/project/foundation.md)
- [Project vision](docs/project/vision.md)
- [Project incentives](docs/project/incentives.md)
- [Project resources](docs/project/resources.md)
- [Tech stack local override](docs/tech-stack.local.md)
- [Contributor guide](docs/dev/CONTRIBUTING.md)
- [Extension SOP](docs/dev/EXTENSION_SOP.md)
- [Trusted publishing runbook](docs/dev/trusted_publishing.md)
- [Next session prompt](NEXT_SESSION_PROMPT.md)