mirror of
https://github.com/harivansh-afk/clanker-agent.git
synced 2026-04-15 05:02:07 +00:00
move pi-mono into companion-cloud as apps/companion-os
- Copy all pi-mono source into apps/companion-os/ - Update Dockerfile to COPY pre-built binary instead of downloading from GitHub Releases - Update deploy-staging.yml to build pi from source (bun compile) before Docker build - Add apps/companion-os/** to path triggers - No more cross-repo dispatch needed Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
commit
0250f72976
579 changed files with 206942 additions and 0 deletions
254
AGENTS.md
Normal file
254
AGENTS.md
Normal file
|
|
@ -0,0 +1,254 @@
|
|||
# Development Rules
|
||||
|
||||
## First Message
|
||||
|
||||
If the user did not give you a concrete task in their first message,
|
||||
read README.md, then ask which module(s) to work on. Based on the answer, read the relevant README.md files in parallel.
|
||||
|
||||
- packages/ai/README.md
|
||||
- packages/tui/README.md
|
||||
- packages/agent/README.md
|
||||
- packages/coding-agent/README.md
|
||||
- packages/web-ui/README.md
|
||||
|
||||
## Code Quality
|
||||
|
||||
- No `any` types unless absolutely necessary
|
||||
- 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
|
||||
- Always ask before removing functionality or code that appears to be intentional
|
||||
- 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`)
|
||||
|
||||
## 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 dev`, `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.
|
||||
- When writing tests, run them, identify issues in either the test or implementation, and iterate until fixed.
|
||||
- NEVER commit unless user asks
|
||||
|
||||
## GitHub Issues
|
||||
|
||||
When reading issues:
|
||||
|
||||
- Always read all comments on the issue
|
||||
- Use this command to get everything in one call:
|
||||
```bash
|
||||
gh issue view <number> --json title,body,comments,labels,state
|
||||
```
|
||||
|
||||
When creating issues:
|
||||
|
||||
- Add `pkg:*` labels to indicate which package(s) the issue affects
|
||||
- Available labels: `pkg:agent`, `pkg:ai`, `pkg:coding-agent`, `pkg:mom`, `pkg:pods`, `pkg:tui`, `pkg:web-ui`
|
||||
- If an issue spans multiple packages, add all relevant labels
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
## Tools
|
||||
|
||||
- GitHub CLI for issues/PRs
|
||||
- Add package labels to issues/PRs: pkg:agent, pkg:ai, pkg:coding-agent, pkg:mom, pkg:pods, pkg:tui, pkg:web-ui
|
||||
|
||||
## Testing pi Interactive Mode with tmux
|
||||
|
||||
To test pi's TUI in a controlled terminal environment:
|
||||
|
||||
```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 "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 kill-session -t pi-test
|
||||
```
|
||||
|
||||
## Style
|
||||
|
||||
- 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!")
|
||||
|
||||
## Changelog
|
||||
|
||||
Location: `packages/*/CHANGELOG.md` (each package has its own)
|
||||
|
||||
### Format
|
||||
|
||||
Use these sections under `## [Unreleased]`:
|
||||
|
||||
- `### Breaking Changes` - API changes requiring migration
|
||||
- `### Added` - New features
|
||||
- `### Changed` - Changes to existing functionality
|
||||
- `### Fixed` - Bug fixes
|
||||
- `### Removed` - Removed features
|
||||
|
||||
### Rules
|
||||
|
||||
- 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/badlogic/pi-mono/issues/123))`
|
||||
- **External contributions**: `Added feature X ([#456](https://github.com/badlogic/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`
|
||||
- Message/tool conversion functions
|
||||
- Response parsing emitting standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`)
|
||||
|
||||
### 3. Stream Integration (`packages/ai/src/stream.ts`)
|
||||
|
||||
- Import provider's stream function and options type
|
||||
- Add credential detection in `getEnvApiKey()`
|
||||
- Add case in `mapOptionsForApi()` for `SimpleStreamOptions` mapping
|
||||
- Add provider to `streamFunctions` map
|
||||
|
||||
### 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/`)
|
||||
|
||||
Add provider to: `stream.test.ts`, `tokens.test.ts`, `abort.test.ts`, `empty.test.ts`, `context-overflow.test.ts`, `image-limits.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 `DEFAULT_MODELS`
|
||||
- `src/cli/args.ts`: Add env var documentation
|
||||
- `README.md`: Add provider setup instructions
|
||||
|
||||
### 7. Documentation
|
||||
|
||||
- `packages/ai/README.md`: Add to providers table, document options/auth, add env vars
|
||||
- `packages/ai/CHANGELOG.md`: Add entry under `## [Unreleased]`
|
||||
|
||||
## Releasing
|
||||
|
||||
**Lockstep versioning**: All packages always share the same version number. Every release updates all packages together.
|
||||
|
||||
**Version semantics** (no major releases):
|
||||
|
||||
- `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. **Run release script**:
|
||||
```bash
|
||||
npm run release:patch # Fixes and additions
|
||||
npm run release:minor # API breaking changes
|
||||
```
|
||||
|
||||
The script handles: version bump, CHANGELOG finalization, commit, tag, publish, and adding new `[Unreleased]` sections.
|
||||
|
||||
## **CRITICAL** Tool Usage Rules **CRITICAL**
|
||||
|
||||
- NEVER use sed/cat to read a file or a range of a file. Always use the read tool (use offset + limit for ranged reads).
|
||||
- You MUST read every file you modify in full before editing.
|
||||
|
||||
## **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
|
||||
|
||||
### 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue