Skip to content

CLAUDE.md

Latest commit

 

History

History
199 lines (124 loc) · 8.66 KB

CLAUDE.md

File metadata and controls

199 lines (124 loc) · 8.66 KB

AllAgents

A CLI tool for managing AI coding assistant plugins across multiple clients (Claude Code, GitHub Copilot, Cursor, etc.).

Bug Reports and Issue Requirements

Before writing any code for a bug fix, confirm you understand the actual problem. Ask the user clarifying questions when:

  • The issue description is vague or could have multiple root causes
  • You cannot reproduce the reported behavior from the description alone
  • The proposed solution in the issue doesn't clearly match the described problem
  • The bug could be a user error (e.g., running a command from the wrong directory) rather than a code defect

Do NOT assume the first plausible-looking code path is the root cause. Verify the user's environment, exact commands run, and expected vs actual output before proposing a fix.

Plans

Design documents and implementation plans are stored in .claude/plans/. These are temporary working documents - once implementation is complete, delete the plan and update official docs with any user-facing behavior.

Git Workflow

Commit Convention

Follow conventional commits: type(scope): description

Types: feat, fix, docs, style, refactor, test, chore

Do NOT add Co-Authored-By attribution to commit messages.

Issue Workflow

When working on a GitHub issue, ALWAYS follow this workflow:

  1. Create a worktree with a feature branch from main:

    git worktree add ../allagents.worktrees/<type>-<short-description> -b <type>/<issue-number>-<short-description>
# Example: git worktree add ../allagents.worktrees/feat-add-new-embedder -b feat/42-add-new-embedder
cd ../allagents.worktrees/<type>-<short-description>

  2. Implement the changes and commit following the commit convention

  3. Push the branch and create a Pull Request:

    git push -u origin <branch-name>
gh pr create --title "<type>(scope): description" --body "Closes #<issue-number>"

  4. Before merging, ensure:

    • CI pipeline passes (all checks green)
    • Code has been reviewed if required
    • No merge conflicts with main

IMPORTANT: Never push directly to main. Always use branches and PRs.

Pull Requests

Always use squash merge when merging PRs to main. This keeps the commit history clean with one commit per feature/fix.

# Using GitHub CLI to squash merge a PR
gh pr merge <PR_NUMBER> --squash --delete-branch --admin

Do NOT use regular merge or rebase merge, as these create noisy commit history with intermediate commits.

After Squash Merge

Once a PR is squash-merged, its source branch diverges from main. Do NOT try to push additional commits from that branch—you will get merge conflicts.

For follow-up fixes:

git checkout main
git pull origin main
git checkout -b fix/<short-description>
# Apply fixes on the fresh branch

Testing

Tests use bun:test. Run with bun test or target a specific file with bun test tests/unit/core/foo.test.ts.

Approach

  • One test per distinct code path. Avoid testing the same branch with slightly different inputs — if the code path is the same, one test is enough.
  • Prefer covering the input matrix (e.g. config present/absent across scopes) but collapse cases that exercise identical logic.
  • Tests should be fast and not slow down CI. Remove redundant tests rather than keeping them for completeness.

Manual E2E Testing

Manual E2E testing is required at two points in the development workflow:

1. Red E2E (before implementation)

ALWAYS run a red E2E test first to understand the current behavior before writing any code. Build the CLI from the current branch, set up a temp workspace that exercises the feature/fix you're about to implement, and document what happens today. This establishes the baseline and confirms you understand the problem.

2. Green E2E (after implementation, before finalization)

ALWAYS run a green E2E test after implementation to verify the change works end-to-end. Use the same temp workspace from the red test and confirm the behavior now matches expectations.

How to E2E test

# Build the CLI in your worktree
bun run build

# Test the specific behavior your change affects
./dist/index.js update
./dist/index.js plugin update

Create a temporary workspace in /tmp/, configure it with a workspace.yaml that exercises your change, run the built CLI against it, and verify the filesystem result matches expectations. Clean up after.

IMPORTANT: Never run git config in the repo directory. If tests need git user config (e.g., for commits in a temp repo), always scope it to the temp directory: git config --local user.name "Test" inside the temp dir. Running git config user.name or git config user.email in the project root will silently override the user's identity for all future commits.

Include E2E steps in the PR description so human reviewers can reproduce the test. Document the exact commands you ran and what you verified.

Unit tests with mocks verify internal logic but miss integration bugs. Mocks that don't match real interfaces create false confidence.

Code Review

ALWAYS run a code review after implementation is complete and before final E2E. Use the superpowers:code-reviewer agent to review changed files against the plan and CLAUDE.md coding standards. Fix all important issues before proceeding to the green E2E test.

Development Workflow Summary

The full workflow for any feature or fix is:

  1. Red E2E — build CLI, test current behavior, confirm the problem
  2. Implement — write code and unit/integration tests
  3. Code review — review implementation for correctness, DRY, test coverage
  4. Green E2E — build CLI, test new behavior, confirm the fix
  5. Push — commit and push, verify CI passes

Unit Test Anti-patterns

Avoid tests that verify implementation details rather than behavior:

  • Bad: "verify updateMarketplace was called with 'test-marketplace'" — breaks on refactors, misses real bugs
  • Good: "plugin updates successfully when marketplace exists" — tests actual outcome

If a mock doesn't match the real interface (e.g., missing a name field the real function returns), the test passes but production breaks. When writing mocks, match the actual return type.

Git Worktrees

Use the default allagents.worktrees/ directory (sibling to the repo, already in .gitignore). After creating a worktree, run bun install since worktrees do not share node_modules.

When done:

git worktree remove ../allagents.worktrees/<name>

Architecture Notes

MCP Server Sync

MCP servers from plugins are synced to VS Code's mcp.json. Key ownership rule:

  • We only track servers we added. If a server already exists in the user's mcp.json before a plugin is installed, we must NOT track it — otherwise uninstalling the plugin would delete the user's manually-configured server.
  • trackedServers in sync state = "servers we own and are responsible for updating/removing"
  • Skipped servers (user-managed conflicts) must never be added to trackedServers

CLI Output Paths

User-facing output for sync results is displayed from multiple entry points:

  • update command (src/cli/commands/workspace.ts) — also available as workspace sync
  • plugin install/uninstall/update commands (src/cli/commands/plugin.ts)
  • TUI interactive sync (src/cli/tui/actions/sync.ts)

Shared formatting lives in src/cli/format-sync.ts. When adding new sync output, update the shared module — not individual call sites.

VSCode / Copilot Display Alias

vscode is a display alias for copilot for artifact counts only (skills, commands, agents, hooks). Since VS Code and Copilot share skill paths, their counts are merged under the copilot label.

MCP output uses the raw client name — no aliasing. This is because vscode and copilot have independent MCP support.

Internally, vscode and copilot remain distinct client types with separate path mappings (see resolveClientMappings() in client-mapping.ts).

Publishing

Never run npm publish directly. Always use the two-step workflow:

  1. bun run publish:next — publishes to the next tag
  2. bun run promote:latest — promotes next to latest after testing

A prepublishOnly guard in package.json blocks direct npm publish. This prevents untested releases from going to latest.

Troubleshooting

agent-browser

If agent-browser open fails with "Missing X server or $DISPLAY" errors on Linux, the installed version may be outdated. Update to the latest version:

sudo npm update -g agent-browser
agent-browser --version  # Verify update

The browser runs in headless mode by default and should not require X11.