mirror of
https://github.com/earendil-works/pi.git
synced 2026-06-18 15:54:04 +08:00
Tighten AGENTS.md and extract LLM provider checklist to skill
- Tighten all sections (279 -> 159 lines) without dropping rules. - Reorganize: git rules moved next to issues/PRs. - Defer contributor gate details to CONTRIBUTING.md. - Replace stale npx tsx test command with node (strip-only mode); add ./test.sh + e2e warning. - Releasing: explicit WebAuthn briefing step, no bash timeout, stop on partial publish failure. - Move LLM provider checklist to .pi/skills/add-llm-provider.md.
This commit is contained in:
Mario Zechner
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: add-llm-provider
|
||||
description: Checklist for adding a new LLM provider to packages/ai. Covers core types, provider implementation, lazy registration, model generation, the full test matrix, coding-agent wiring, and docs.
|
||||
---
|
||||
|
||||
# Adding a New LLM Provider (packages/ai)
|
||||
|
||||
A new provider touches multiple files. Work through these steps in order.
|
||||
|
||||
## 1. Core Types (`packages/ai/src/types.ts`)
|
||||
|
||||
- Add API identifier to `Api` type union (e.g. `"bedrock-converse-stream"`).
|
||||
- Create options interface extending `StreamOptions`.
|
||||
- Add mapping to `ApiOptionsMap`.
|
||||
- Add provider name to `KnownProvider` type union.
|
||||
|
||||
## 2. Provider Implementation (`packages/ai/src/providers/`)
|
||||
|
||||
Create a provider file exporting:
|
||||
|
||||
- `stream<Provider>()` returning `AssistantMessageEventStream`.
|
||||
- `streamSimple<Provider>()` for `SimpleStreamOptions` mapping.
|
||||
- Provider-specific options interface.
|
||||
- Message/tool conversion functions.
|
||||
- Response parsing that emits standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`).
|
||||
|
||||
## 3. Provider Exports and Lazy Registration
|
||||
|
||||
- Add a package subpath export in `packages/ai/package.json` pointing at `./dist/providers/<provider>.js`.
|
||||
- Add `export type` re-exports in `packages/ai/src/index.ts` for provider option types that should remain available from the root entry.
|
||||
- Register the provider in `packages/ai/src/providers/register-builtins.ts` via lazy loader wrappers; do not statically import provider implementation modules there.
|
||||
- Add credential detection in `packages/ai/src/env-api-keys.ts`.
|
||||
|
||||
## 4. Model Generation (`packages/ai/scripts/generate-models.ts`)
|
||||
|
||||
- Add logic to fetch/parse models from the provider source.
|
||||
- Map to the standardized `Model` interface.
|
||||
|
||||
## 5. Tests (`packages/ai/test/`)
|
||||
|
||||
- Always add the provider to `stream.test.ts` with at least one representative model, even if it reuses an existing API impl such as `openai-completions`.
|
||||
- Add the provider to the broader matrix where applicable: `tokens.test.ts`, `abort.test.ts`, `empty.test.ts`, `context-overflow.test.ts`, `unicode-surrogate.test.ts`, `tool-call-without-result.test.ts`, `image-tool-result.test.ts`, `total-tokens.test.ts`, `cross-provider-handoff.test.ts`.
|
||||
- For `cross-provider-handoff.test.ts`, add at least one provider/model pair. If the provider exposes multiple model families (e.g. GPT and Claude), add at least one pair per family.
|
||||
- For non-standard auth, create a utility (e.g. `bedrock-utils.ts`) with credential detection.
|
||||
|
||||
## 6. Coding Agent (`packages/coding-agent/`)
|
||||
|
||||
- `src/core/model-resolver.ts`: add default model ID to `defaultModelPerProvider`.
|
||||
- `src/core/provider-display-names.ts`: add API-key login display name so `/login` and related UI show the provider for built-in API-key auth.
|
||||
- `src/cli/args.ts`: add env var documentation.
|
||||
- `README.md`: add provider setup instructions.
|
||||
- `docs/providers.md`: add setup instructions, env var, and `auth.json` key.
|
||||
|
||||
## 7. Documentation
|
||||
|
||||
- `packages/ai/README.md`: add to providers table, document options/auth, add env vars.
|
||||
- `packages/ai/CHANGELOG.md`: add entry under `## [Unreleased]`.
|
||||
@@ -4,202 +4,118 @@
|
||||
|
||||
- Keep answers short and concise
|
||||
- No emojis in commits, issues, PR comments, or code
|
||||
- No fluff or cheerful filler text
|
||||
- Technical prose only, be kind but direct (e.g., "Thanks @user" not "Thanks so much @user!")
|
||||
- No fluff or cheerful filler text (e.g., "Thanks @user" not "Thanks so much @user!")
|
||||
- Technical prose only, be direct
|
||||
- When the user asks a question, answer it first before making edits or running implementation commands.
|
||||
|
||||
## Code Quality
|
||||
|
||||
- Read files in full before making wide-ranging changes, before editing files you have not already fully inspected, and when the user asks you to investigate or audit something. Do not rely only on search snippets for broad changes.
|
||||
- No `any` types unless absolutely necessary
|
||||
- Single-line helper functions with a single call site are forbidden; inline them instead.
|
||||
- Check node_modules for external API type definitions instead of guessing
|
||||
- **NEVER use inline imports** - no `await import("./foo.js")`, no `import("pkg").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.
|
||||
- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead
|
||||
- Use only erasable TypeScript syntax compatible with Node strip-only mode in TypeScript checked by the root config (`packages/*/src`, `packages/*/test`, and `packages/coding-agent/examples`). Do not use constructor parameter properties, `enum`, `namespace`/`module`, `import =`, `export =`, or other TypeScript constructs that require JavaScript emit. Use explicit fields and constructor assignments instead of parameter properties.
|
||||
- Always ask before removing functionality or code that appears to be intentional
|
||||
- Do not preserve backward compatibility unless the user explicitly asks for it
|
||||
- Never hardcode key checks with, eg. `matchesKey(keyData, "ctrl+x")`. All keybindings must be configurable. Add default to matching object (`DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS`)
|
||||
- NEVER modify `packages/ai/src/models.generated.ts` directly. Update `packages/ai/scripts/generate-models.ts` instead.
|
||||
- Read files in full before wide-ranging changes, before editing files you have not fully inspected, and when asked to investigate or audit. Do not rely on search snippets for broad changes.
|
||||
- No `any` unless absolutely necessary.
|
||||
- Inline single-line helpers that have only one call site.
|
||||
- Check node_modules for external API types; don't guess.
|
||||
- **No inline imports** (`await import()`, `import("pkg").Type`, dynamic type imports). Top-level imports only.
|
||||
- Never remove or downgrade code to fix type errors from outdated deps; upgrade the dep instead.
|
||||
- Use only erasable TypeScript syntax (Node strip-only mode) in code checked by the root config (`packages/*/src`, `packages/*/test`, `packages/coding-agent/examples`): no parameter properties, `enum`, `namespace`/`module`, `import =`, `export =`, or other constructs needing JS emit. Use explicit fields with constructor assignments.
|
||||
- Always ask before removing functionality or code that appears intentional.
|
||||
- Do not preserve backward compatibility unless the user asks for it.
|
||||
- Never hardcode key checks (e.g. `matchesKey(keyData, "ctrl+x")`). Add defaults to `DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS` so they stay configurable.
|
||||
- Never modify `packages/ai/src/models.generated.ts` directly; update `packages/ai/scripts/generate-models.ts` instead.
|
||||
|
||||
## Commands
|
||||
|
||||
- After code changes (not documentation changes): `npm run check` (get full output, no tail). Fix all errors, warnings, and infos before committing.
|
||||
- Note: `npm run check` does not run tests.
|
||||
- NEVER run: `npm run build`, `npm test`
|
||||
- Only run specific tests if user instructs: `npx tsx ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts`
|
||||
- Run tests from the package root, not the repo root.
|
||||
- If you create or modify a test file, you MUST run that test file and iterate until it passes.
|
||||
- When writing tests, run them, identify issues in either the test or implementation, and iterate until fixed.
|
||||
- For `packages/coding-agent/test/suite/`, use `test/suite/harness.ts` plus the faux provider. Do not use real provider APIs, real API keys, or paid tokens.
|
||||
- Put issue-specific regressions under `packages/coding-agent/test/suite/regressions/` and name them `<issue-number>-<short-slug>.test.ts`.
|
||||
- For ad-hoc scripts, write the script to a temporary file (for example under `/tmp`) using `write`, run that file, edit it if needed, and remove it when it is no longer needed. Do not embed multi-line scripts directly in `bash` commands.
|
||||
- NEVER commit unless user asks
|
||||
- After code changes (not docs): `npm run check` (full output, no tail). Fix all errors, warnings, and infos before committing. Does not run tests.
|
||||
- Never run `npm run build` or `npm test` unless requested by the user.
|
||||
- Never run the full vitest suite directly: it includes e2e tests that activate when endpoint/auth env vars are present. For all non-e2e tests, run `./test.sh` from the repo root. Otherwise run specific tests from the package root: `node ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts`.
|
||||
- If you create or modify a test file, run it and iterate on test or implementation until it passes.
|
||||
- For `packages/coding-agent/test/suite/`, use `test/suite/harness.ts` + the faux provider. No real provider APIs, keys, or paid tokens.
|
||||
- Put issue-specific regressions under `packages/coding-agent/test/suite/regressions/` named `<issue-number>-<short-slug>.test.ts`.
|
||||
- For ad-hoc scripts, `write` them to a temp file (e.g. `/tmp`), run, edit if needed, remove when done. Don't embed multi-line scripts in `bash` commands.
|
||||
- Never commit unless the user asks.
|
||||
|
||||
## Dependency and Install Security
|
||||
|
||||
- Treat npm dependency and lockfile changes as reviewed code changes. Direct external dependencies must stay pinned to exact versions.
|
||||
- Use `npm install --ignore-scripts` to hydrate/update `node_modules` locally. Use `npm ci --ignore-scripts` for clean installs/CI-style verification. Do not run lifecycle scripts unless the user explicitly asks.
|
||||
- If dependency metadata changes, run `npm install --package-lock-only --ignore-scripts` to update `package-lock.json` without installing or running scripts.
|
||||
- If `packages/coding-agent/npm-shrinkwrap.json` needs regeneration, run `node scripts/generate-coding-agent-shrinkwrap.mjs`; verify with `node scripts/generate-coding-agent-shrinkwrap.mjs --check` or `npm run check`.
|
||||
- Pre-commit blocks accidental lockfile commits unless `PI_ALLOW_LOCKFILE_CHANGE=1` is set. Do not bypass it unless the user explicitly wants the lockfile change committed.
|
||||
- New dependencies with lifecycle scripts require review and an explicit allowlist entry in `scripts/generate-coding-agent-shrinkwrap.mjs`; do not add one silently.
|
||||
- Treat npm dep and lockfile changes as reviewed code. Direct external deps stay pinned to exact versions.
|
||||
- Hydrate/update locally with `npm install --ignore-scripts`; clean/CI-style with `npm ci --ignore-scripts`. Don't run lifecycle scripts unless the user asks.
|
||||
- If dep metadata changes, refresh `package-lock.json` with `npm install --package-lock-only --ignore-scripts`.
|
||||
- If `packages/coding-agent/npm-shrinkwrap.json` needs regen, run `node scripts/generate-coding-agent-shrinkwrap.mjs` (verify with `--check` or `npm run check`). New deps with lifecycle scripts require review and an explicit allowlist entry in that script; never add one silently.
|
||||
- Pre-commit blocks lockfile commits unless `PI_ALLOW_LOCKFILE_CHANGE=1`. Don't bypass unless the user wants the lockfile change committed.
|
||||
|
||||
## Contribution Gate
|
||||
## Git
|
||||
|
||||
- New issues from new contributors are auto-closed by `.github/workflows/issue-gate.yml`
|
||||
- New PRs from new contributors without PR rights are auto-closed by `.github/workflows/pr-gate.yml`
|
||||
- Maintainer approval comments are handled by `.github/workflows/approve-contributor.yml`
|
||||
- Maintainers review auto-closed issues daily
|
||||
- Issues that do not meet the quality bar in `CONTRIBUTING.md` are not reopened and do not receive a reply
|
||||
- `lgtmi` approves future issues
|
||||
- `lgtm` approves future issues and rights to submit PRs
|
||||
Multiple pi sessions may be running in this cwd at the same time, each modifying different files. Git operations that touch unstaged, staged, or untracked files outside your own changes will stomp on other sessions' work. Follow these rules:
|
||||
|
||||
Committing:
|
||||
|
||||
- Only commit files YOU changed in THIS session.
|
||||
- Stage explicit paths (`git add <path1> <path2>`); never `git add -A` / `git add .`.
|
||||
- Before committing, run `git status` and verify you are only staging your files.
|
||||
- `packages/ai/src/models.generated.ts` may always be included alongside your files.
|
||||
|
||||
Never run (destroys other agents' work or bypasses checks):
|
||||
|
||||
- `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash`, `git add -A`, `git add .`, `git commit --no-verify`.
|
||||
|
||||
If rebase conflicts occur:
|
||||
|
||||
- Resolve conflicts only in files you modified.
|
||||
- If a conflict is in a file you did not modify, abort and ask the user.
|
||||
- Never force push.
|
||||
|
||||
## Issues and PRs
|
||||
|
||||
See `CONTRIBUTING.md` for the contributor gate (auto-close workflows, `lgtm`/`lgtmi`, quality bar).
|
||||
|
||||
When creating issues:
|
||||
|
||||
- Add `pkg:*` labels to indicate which package(s) the issue affects
|
||||
- Available labels: `pkg:agent`, `pkg:ai`, `pkg:coding-agent`, `pkg:tui`
|
||||
- If an issue spans multiple packages, add all relevant labels
|
||||
- Add `pkg:*` labels for affected packages (`pkg:agent`, `pkg:ai`, `pkg:coding-agent`, `pkg:tui`); use all that apply.
|
||||
|
||||
When posting issue/PR comments:
|
||||
|
||||
- Write the full comment to a temp file and use `gh issue comment --body-file` or `gh pr comment --body-file`
|
||||
- Never pass multi-line markdown directly via `--body` in shell commands
|
||||
- Preview the exact comment text before posting
|
||||
- Post exactly one final comment unless the user explicitly asks for multiple comments
|
||||
- If a comment is malformed, delete it immediately, then post one corrected comment
|
||||
- Keep comments concise, technical, and in the user's tone
|
||||
- Write the comment to a temp file and post with `gh issue/pr comment --body-file` (never multi-line markdown via `--body`).
|
||||
- Keep comments concise, technical, in the user's tone.
|
||||
- End every AI-posted comment with the AI-generated disclaimer line specified by the originating prompt (e.g. `This comment is AI-generated by `/wr``).
|
||||
|
||||
When closing issues via commit:
|
||||
|
||||
- Include `fixes #<number>` or `closes #<number>` in the commit message
|
||||
- This automatically closes the issue when the commit is merged
|
||||
|
||||
## PR Workflow
|
||||
|
||||
- Analyze PRs without pulling locally first
|
||||
- If the user approves: create a feature branch, pull PR, rebase on main, apply adjustments, commit, merge into main, push, close PR, and leave a comment in the user's tone
|
||||
- You never open PRs yourself. We work in feature branches until everything is according to the user's requirements, then merge into main, and push.
|
||||
- Include `fixes #<number>` or `closes #<number>` in the message so merging auto-closes the issue. For multiple issues, repeat the keyword per issue (`closes #1, closes #2`); a shared keyword (`closes #1, #2`) only closes the first.
|
||||
|
||||
## Testing pi Interactive Mode with tmux
|
||||
|
||||
To test pi's TUI in a controlled terminal environment:
|
||||
Run the TUI in a controlled terminal (from the repo root):
|
||||
|
||||
```bash
|
||||
# Create tmux session with specific dimensions
|
||||
tmux new-session -d -s pi-test -x 80 -y 24
|
||||
|
||||
# Start pi from source
|
||||
tmux send-keys -t pi-test "cd /Users/badlogic/workspaces/pi-mono && ./pi-test.sh" Enter
|
||||
|
||||
# Wait for startup, then capture output
|
||||
sleep 3 && tmux capture-pane -t pi-test -p
|
||||
|
||||
# Send input
|
||||
tmux send-keys -t pi-test "./pi-test.sh" Enter
|
||||
sleep 3 && tmux capture-pane -t pi-test -p # capture after startup
|
||||
tmux send-keys -t pi-test "your prompt here" Enter
|
||||
|
||||
# Send special keys
|
||||
tmux send-keys -t pi-test Escape
|
||||
tmux send-keys -t pi-test C-o # ctrl+o
|
||||
|
||||
# Cleanup
|
||||
tmux send-keys -t pi-test Escape # special keys (also C-o for ctrl+o, etc.)
|
||||
tmux kill-session -t pi-test
|
||||
```
|
||||
|
||||
## Changelog
|
||||
|
||||
Location: `packages/*/CHANGELOG.md` (each package has its own)
|
||||
Location: `packages/*/CHANGELOG.md` (one per package).
|
||||
|
||||
### Format
|
||||
Sections under `## [Unreleased]`: `### Breaking Changes` (API changes requiring migration), `### Added`, `### Changed`, `### Fixed`, `### Removed`.
|
||||
|
||||
Use these sections under `## [Unreleased]`:
|
||||
Rules:
|
||||
|
||||
- `### Breaking Changes` - API changes requiring migration
|
||||
- `### Added` - New features
|
||||
- `### Changed` - Changes to existing functionality
|
||||
- `### Fixed` - Bug fixes
|
||||
- `### Removed` - Removed features
|
||||
- All new entries go under `## [Unreleased]`. Read the full section first and append to existing subsections; never duplicate them.
|
||||
- Released version sections (e.g. `## [0.12.2]`) are immutable; never modify them.
|
||||
|
||||
### Rules
|
||||
Attribution:
|
||||
|
||||
- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist
|
||||
- New entries ALWAYS go under `## [Unreleased]` section
|
||||
- Append to existing subsections (e.g., `### Fixed`), do not create duplicates
|
||||
- NEVER modify already-released version sections (e.g., `## [0.12.2]`)
|
||||
- Each version section is immutable once released
|
||||
|
||||
### Attribution
|
||||
|
||||
- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/earendil-works/pi-mono/issues/123))`
|
||||
- **External contributions**: `Added feature X ([#456](https://github.com/earendil-works/pi-mono/pull/456) by [@username](https://github.com/username))`
|
||||
|
||||
## Adding a New LLM Provider (packages/ai)
|
||||
|
||||
Adding a new provider requires changes across multiple files:
|
||||
|
||||
### 1. Core Types (`packages/ai/src/types.ts`)
|
||||
|
||||
- Add API identifier to `Api` type union (e.g., `"bedrock-converse-stream"`)
|
||||
- Create options interface extending `StreamOptions`
|
||||
- Add mapping to `ApiOptionsMap`
|
||||
- Add provider name to `KnownProvider` type union
|
||||
|
||||
### 2. Provider Implementation (`packages/ai/src/providers/`)
|
||||
|
||||
Create provider file exporting:
|
||||
|
||||
- `stream<Provider>()` function returning `AssistantMessageEventStream`
|
||||
- `streamSimple<Provider>()` for `SimpleStreamOptions` mapping
|
||||
- Provider-specific options interface
|
||||
- Message/tool conversion functions
|
||||
- Response parsing emitting standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`)
|
||||
|
||||
### 3. Provider Exports and Lazy Registration
|
||||
|
||||
- Add a package subpath export in `packages/ai/package.json` pointing at `./dist/providers/<provider>.js`
|
||||
- Add `export type` re-exports in `packages/ai/src/index.ts` for provider option types that should remain available from the root entry
|
||||
- Register the provider in `packages/ai/src/providers/register-builtins.ts` via lazy loader wrappers, do not statically import provider implementation modules there
|
||||
- Add credential detection in `packages/ai/src/env-api-keys.ts`
|
||||
|
||||
### 4. Model Generation (`packages/ai/scripts/generate-models.ts`)
|
||||
|
||||
- Add logic to fetch/parse models from provider source
|
||||
- Map to standardized `Model` interface
|
||||
|
||||
### 5. Tests (`packages/ai/test/`)
|
||||
|
||||
- Always add the provider to `stream.test.ts` with at least one representative model, even if it reuses an existing API implementation such as `openai-completions`.
|
||||
- Add the provider to the broader provider matrix where applicable: `tokens.test.ts`, `abort.test.ts`, `empty.test.ts`, `context-overflow.test.ts`, `unicode-surrogate.test.ts`, `tool-call-without-result.test.ts`, `image-tool-result.test.ts`, `total-tokens.test.ts`, `cross-provider-handoff.test.ts`.
|
||||
- For `cross-provider-handoff.test.ts`, add at least one provider/model pair. If the provider exposes multiple model families (for example GPT and Claude), add at least one pair per family.
|
||||
- For non-standard auth, create utility (e.g., `bedrock-utils.ts`) with credential detection.
|
||||
|
||||
### 6. Coding Agent (`packages/coding-agent/`)
|
||||
|
||||
- `src/core/model-resolver.ts`: Add default model ID to `defaultModelPerProvider`
|
||||
- `src/core/provider-display-names.ts`: Add API-key login display name so `/login` and related UI show the provider for built-in API-key auth.
|
||||
- `src/cli/args.ts`: Add env var documentation
|
||||
- `README.md`: Add provider setup instructions
|
||||
- `docs/providers.md`: Add setup instructions, env var, and `auth.json` key
|
||||
|
||||
### 7. Documentation
|
||||
|
||||
- `packages/ai/README.md`: Add to providers table, document options/auth, add env vars
|
||||
- `packages/ai/CHANGELOG.md`: Add entry under `## [Unreleased]`
|
||||
- Internal (from issues): `Fixed foo bar ([#123](https://github.com/earendil-works/pi-mono/issues/123))`
|
||||
- External contributions: `Added feature X ([#456](https://github.com/earendil-works/pi-mono/pull/456) by [@username](https://github.com/username))`
|
||||
|
||||
## Releasing
|
||||
|
||||
**Lockstep versioning**: All packages always share the same version number. Every release updates all packages together.
|
||||
**Lockstep versioning**: all packages share one version; every release updates all together. `patch` = fixes + additions, `minor` = breaking changes. No major releases.
|
||||
|
||||
**Version semantics** (no major releases):
|
||||
1. **Update CHANGELOGs**: ask the user whether they ran the `/cl` prompt on the latest commit on `main`. If not, they must run `/cl` first to audit and update each package's `[Unreleased]` section before releasing.
|
||||
|
||||
- `patch`: Bug fixes and new features
|
||||
- `minor`: API breaking changes
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Update CHANGELOGs**: Ensure all changes since last release are documented in the `[Unreleased]` section of each affected package's CHANGELOG.md
|
||||
|
||||
2. **Soft gate: local release smoke test**: Before running the real release script, build an unpublished local release and manually smoke test it from outside the repository so it cannot accidentally resolve workspace files:
|
||||
2. **Local smoke test**: build an unpublished release and smoke test from outside the repo (so it can't resolve workspace files):
|
||||
```bash
|
||||
npm run release:local -- --out /tmp/pi-local-release --force
|
||||
cd /tmp
|
||||
@@ -209,71 +125,35 @@ Create provider file exporting:
|
||||
/tmp/pi-local-release/bun/pi --help
|
||||
/tmp/pi-local-release/bun/pi --version
|
||||
```
|
||||
In the interactive smoke test, verify startup, model/account listing, and at least one real prompt with the intended default provider. Treat failures as release blockers unless the user explicitly accepts the risk.
|
||||
Verify startup, model/account listing, and at least one real prompt with the intended default provider. Failures are release blockers unless the user explicitly accepts the risk.
|
||||
|
||||
3. **Run release script until npm publish**:
|
||||
```bash
|
||||
npm run release:patch # Fixes and additions
|
||||
npm run release:minor # API breaking changes
|
||||
3. **Brief the user on the WebAuthn flow before running anything**. Print exactly the following message and then stop and wait for the user to confirm in their next message:
|
||||
|
||||
```
|
||||
Before I run the release script, read this carefully:
|
||||
|
||||
- `npm publish` uses WebAuthn 2FA.
|
||||
- A login URL will appear in the live bash output in this TUI. I will NOT see it until the command exits.
|
||||
- You must watch the bash output, cmd/ctrl-click the URL, log in in the browser, and select the "don't ask again for N minutes" option so publish can continue.
|
||||
- This may happen more than once during the release.
|
||||
|
||||
Reply "ready" once you have read this and are watching the bash output. I will not run the release script until you do.
|
||||
```
|
||||
|
||||
npm publishing requires the maintainer's npm WebAuthn/security-key 2FA and cannot be completed by an agent alone. If the release script stops at `npm publish` with an npm browser authentication URL, the maintainer must run or approve `npm run publish` locally. Do not rerun the version bump.
|
||||
Do not proceed to step 4 until the user explicitly confirms.
|
||||
|
||||
4. **After publish succeeds, finish release bookkeeping**:
|
||||
4. **Run the release script**:
|
||||
```bash
|
||||
npm run release:patch # fixes + additions
|
||||
npm run release:minor # breaking changes
|
||||
```
|
||||
Do not pass a `timeout` to the bash tool for this call. If publish fails partway, stop and report to the user what happened (which package failed, the error output) along with possible solutions. Never rerun the version bump on your own.
|
||||
|
||||
5. **After publish succeeds**:
|
||||
- Add fresh `## [Unreleased]` sections to package changelogs.
|
||||
- Commit with `Add [Unreleased] section for next cycle`.
|
||||
- Push `main` and the release tag.
|
||||
|
||||
The release script handles the full flow when npm publish auth is already satisfied. If npm requires WebAuthn during publish, continue manually from the existing release commit/tag using the steps above.
|
||||
## User Override
|
||||
|
||||
## **CRITICAL** Git Rules for Parallel Agents **CRITICAL**
|
||||
|
||||
Multiple agents may work on different files in the same worktree simultaneously. You MUST follow these rules:
|
||||
|
||||
### Committing
|
||||
|
||||
- **ONLY commit files YOU changed in THIS session**
|
||||
- ALWAYS include `fixes #<number>` or `closes #<number>` in the commit message when there is a related issue or PR
|
||||
- NEVER use `git add -A` or `git add .` - these sweep up changes from other agents
|
||||
- ALWAYS use `git add <specific-file-paths>` listing only files you modified
|
||||
- Before committing, run `git status` and verify you are only staging YOUR files
|
||||
- Track which files you created/modified/deleted during the session
|
||||
- It is always fine to include `packages/ai/src/models.generated.ts` in a commit alongside the actual files you want to commit
|
||||
|
||||
### Forbidden Git Operations
|
||||
|
||||
These commands can destroy other agents' work:
|
||||
|
||||
- `git reset --hard` - destroys uncommitted changes
|
||||
- `git checkout .` - destroys uncommitted changes
|
||||
- `git clean -fd` - deletes untracked files
|
||||
- `git stash` - stashes ALL changes including other agents' work
|
||||
- `git add -A` / `git add .` - stages other agents' uncommitted work
|
||||
- `git commit --no-verify` - bypasses required checks and is never allowed
|
||||
|
||||
### Safe Workflow
|
||||
|
||||
```bash
|
||||
# 1. Check status first
|
||||
git status
|
||||
|
||||
# 2. Add ONLY your specific files
|
||||
git add packages/ai/src/providers/transform-messages.ts
|
||||
git add packages/ai/CHANGELOG.md
|
||||
|
||||
# 3. Commit
|
||||
git commit -m "fix(ai): description"
|
||||
|
||||
# 4. Push (pull --rebase if needed, but NEVER reset/checkout)
|
||||
git pull --rebase && git push
|
||||
```
|
||||
|
||||
### If Rebase Conflicts Occur
|
||||
|
||||
- Resolve conflicts in YOUR files only
|
||||
- If conflict is in a file you didn't modify, abort and ask the user
|
||||
- NEVER force push
|
||||
|
||||
### User override
|
||||
|
||||
If the user instructions conflict with rules set out here, ask for confirmation that they want to override the rules. Only then execute their instructions.
|
||||
If the user's instructions conflict with any rule in this document, ask for explicit confirmation before overriding. Only then execute their instructions.
|
||||
|
||||
Reference in New Issue
Block a user