Skip to content

AGENTS.md

Latest commit

 

History

History
190 lines (157 loc) · 9.27 KB

AGENTS.md

File metadata and controls

190 lines (157 loc) · 9.27 KB
Raw

AllAgents Repository Guidelines

This is the allagents CLI: a tool for managing AI coding assistant plugins, workspaces, and client synchronization across Claude Code, GitHub Copilot, Cursor, and related clients.

High-Level Goals

AllAgents should stay predictable, scriptable, and safe for users who manage real local workspaces:

  • Keep workspace and plugin operations deterministic.
  • Prefer straightforward filesystem transforms over hidden state.
  • Make sync/install/update behavior easy to reason about from CLI output alone.
  • Preserve user-owned config where ownership boundaries matter.

Working Style

Worktree Setup

  • For any feature, bug fix, or non-trivial repo change, work from a dedicated git worktree based on the latest origin/main.
  • Before starting implementation, run git fetch origin and verify your worktree HEAD is based on the current origin/main commit.
  • Do not implement from the primary checkout, from a stale local main, or from a branch created off an outdated base.
  • Default setup:
git fetch origin
git worktree add ../allagents.worktrees/<type>-<short-desc> -b <type>/<issue-or-topic>-<short-desc> origin/main
cd ../allagents.worktrees/<type>-<short-desc>
bun install
  • If you discover you are not on a fresh worktree from the latest origin/main, stop and fix that first before changing code.

Planning

  • Use plan mode for any non-trivial task (5+ steps or architectural decisions).
  • If something goes sideways, STOP and re-plan immediately instead of pushing through a broken approach.
  • For non-trivial changes, pause and ask: "Is there a more elegant solution?" before diving in.
  • Check in with the user before starting implementation on ambiguous tasks.
  • Prefer automation: execute the requested work without extra confirmation unless blocked by missing information, safety concerns, or an irreversible/destructive action the user has not approved.

Bug Fixes

  • Before writing code for a bug fix, confirm you understand the actual problem.
  • Ask clarifying questions when the issue is vague, not reproducible from the description, could be user error, or suggests a solution that may not match the real failure.
  • Do not assume the first plausible code path is the root cause. Verify the exact commands, environment, and expected versus actual behavior first.

Subagent Strategy

  • Use subagents aggressively to keep the main context window clean.
  • Subagents are useful for research, file exploration, tests, and code review.
  • For complex problems, parallelize independent investigation and validation work where possible.
  • Run a final code review after implementation is complete and before the final green E2E when the task is substantial.

Simplicity

  • Every change should be as simple as possible. Reuse existing code before introducing new abstractions.
  • Fix root causes directly. Avoid shotgun debugging and speculative infrastructure.
  • Prefer changes that keep ownership boundaries obvious, especially around synced config and generated artifacts.

Progress Updates

  • Provide high-level status updates at natural milestones.
  • When scope changes mid-task, communicate the shift and adjust the plan.
  • Use parallel tool calls when applicable, especially for independent reads, checks, and validation steps.

Plans

  • Temporary plans and design notes may live under .claude/plans/ while work is in progress.
  • Once implementation is complete, delete stale plan files and update durable docs for any user-facing behavior changes.

PR & Commit Titles

  • Prefer conventional commit style for branch-facing titles: type(scope): summary.
  • Use the repository's normal types where they fit, such as feat, fix, docs, style, refactor, test, and chore.
  • Use the most relevant area as scope, such as cli, sync, plugin, workspace, docs, or mcp.
  • Do not prefix PR titles with [codex] unless the user explicitly requests it.
  • Do not add Co-Authored-By attribution unless explicitly requested.

Branch & PR Workflow

Branching

  • Never implement directly on main for feature or bug-fix work. Use a branch and PR.
  • When working from an issue, create the branch from a fresh worktree:
git worktree add ../allagents.worktrees/<type>-<short-description> -b <type>/<issue-number>-<short-description> origin/main
cd ../allagents.worktrees/<type>-<short-description>

Pull Requests

  • Push the branch and open a PR once the change is validated.
  • When referencing an issue, include Closes #<issue-number> in the PR body.
  • Before merging, ensure CI passes, the branch is up to date enough to merge cleanly, and any required review has happened.
  • Include the exact E2E steps in the PR description so a reviewer can reproduce what was validated.

Merge Policy

  • Always use squash merge when merging PRs to main.
  • Do not use regular merge or rebase merge unless the user explicitly asks for it.
gh pr merge <PR_NUMBER> --squash --delete-branch --admin

After Squash Merge

  • After a PR is squash-merged, do not continue working from the old branch.
  • For follow-up fixes, start from fresh main on a new branch:
git checkout main
git pull origin main
git checkout -b fix/<short-description>

Worktree Cleanup

  • The default worktree location is ../allagents.worktrees/ (already ignored by git).
  • When done, remove the worktree explicitly:
git worktree remove ../allagents.worktrees/<name>

Tech Stack & Tools

  • Runtime and package manager: Bun
  • Language: TypeScript
  • Tests: bun:test plus shell integration tests
  • Lint/format: Biome

Testing & Verification

Core Commands

  • Build: bun run build
  • Unit tests: bun test
  • Integration tests: bun run test:integration
  • Typecheck: bun run typecheck
  • Lint: bun run lint

Test Approach

  • Prefer one test per distinct code path.
  • Avoid redundant tests that exercise the same branch with cosmetic input changes.
  • Test behavior rather than implementation details.
  • Keep tests fast enough to stay practical in CI.
  • Avoid mocks that drift from the real interface and create false confidence.
  • Prefer testing actual outcomes over asserting that internal helpers were called with specific arguments.

Manual E2E Testing

  • Run a red E2E before implementation to confirm current behavior.
  • Run a green E2E after implementation to verify the end-to-end fix.
  • Build the CLI and test the real commands affected by the change:
bun run build
./dist/index.js update
./dist/index.js plugin update
  • Create a temporary workspace in /tmp/, configure it to exercise the change, run the built CLI, and verify the filesystem result matches expectations.
  • Include the E2E steps in the PR description so a reviewer can reproduce them.
  • Document the exact commands you ran and what behavior you verified.

Development Workflow Summary

  1. Red E2E — build the CLI, test current behavior, confirm the problem
  2. Implement — write code and unit or integration tests
  3. Code review — review the implementation for correctness, DRY, and coverage
  4. Green E2E — rebuild and confirm the fix works end to end
  5. Push — commit, push, and let CI validate the branch

Code Review

  • Run a final review after implementation and before finalizing the PR when the task is substantial.
  • Fix important review findings before treating the change as done.

Git Config Safety

  • Never run git config in the repo root when testing.
  • If test setup needs git identity, scope it to the temp directory with git config --local.

Architecture Notes

MCP Server Sync

  • MCP servers from plugins are synced into VS Code's mcp.json.
  • Only track servers that AllAgents added.
  • If a server already existed in the user's config before plugin install, do not track it and do not remove it on uninstall.
  • trackedServers means "servers we own and are responsible for updating or removing."

CLI Output Paths

  • Sync results are surfaced from multiple entry points, including workspace sync, plugin install/uninstall/update, and TUI sync actions.
  • Shared formatting should live in the common sync formatting module rather than being duplicated at call sites.
  • The key call sites are:
    • update / workspace sync in src/cli/commands/workspace.ts
    • plugin install|uninstall|update in src/cli/commands/plugin.ts
    • TUI sync actions in src/cli/tui/actions/sync.ts
  • Shared formatting lives in src/cli/format-sync.ts.

VS Code / Copilot Alias

  • vscode is a display alias for copilot for artifact counts only.
  • MCP output should continue using the raw client name because VS Code and Copilot have separate MCP support.
  • Internally, vscode and copilot remain distinct client types with separate path mappings.

Publishing

  • Never run npm publish directly.
  • Use the GitHub Actions Publish workflow for release tagging and npm publishing.
  • For recovery, dispatch Publish with channel=existing and the release tag/ref.
  • prepublishOnly exists to prevent untested direct publishes outside the workflow.

Interactive Testing

agent-tui

  • Use agent-tui when you need to exercise interactive terminal behavior manually.
  • Prefer testing the built CLI inside a temporary workspace so the interaction matches real user conditions.
  • When documenting manual verification, record the exact command, the temp workspace setup, and what terminal behavior you confirmed.