Skip to content

docs: add AGENTS.md with worktree-based workflow guidelines#3

Merged
timvw merged 1 commit into
mainfrom
docs/add-agents-guide
Nov 29, 2025
Merged

docs: add AGENTS.md with worktree-based workflow guidelines#3
timvw merged 1 commit into
mainfrom
docs/add-agents-guide

Conversation

@timvw
Copy link
Copy Markdown
Owner

@timvw timvw commented Nov 29, 2025

Summary

Add AGENTS.md with comprehensive guidelines for AI coding agents working on the wt project.

Key principle: Agents should use wt to create worktrees for each task, not switch branches in the user's main repository.

Changes

  • ✅ Created AGENTS.md with agent-specific workflow guidelines
  • ✅ Documents worktree-based workflow (practice what we preach!)
  • ✅ Includes complete workflow examples
  • ✅ Covers interactive commands and PR/MR workflows
  • ✅ Lists common pitfalls to avoid
  • ✅ Provides project conventions (branch naming, commits)

Why This Matters

AI agents often switch branches in the main repo, which:

  • ❌ Disrupts the user's workspace
  • ❌ Leaves them on unexpected branches
  • ❌ Can cause confusion with uncommitted changes

Using worktrees:

  • ✅ Keeps user's main repo on main branch
  • ✅ Each feature isolated in its own directory
  • ✅ Non-disruptive to user's workflow
  • ✅ Demonstrates the tool's best practices

Example Agent Workflow

# Instead of: git checkout -b feature-branch
# Agents should do:
wt create feature-branch
# Work in: ~/dev/worktrees/wt/feature-branch/

Meta Note

This PR itself was created using a worktree! 🎯

wt create docs/add-agents-guide
# Worked in the worktree, not main repo

🤖 Generated with Claude Code

@codecov
Copy link
Copy Markdown

codecov Bot commented Nov 29, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 7.49%. Comparing base (d9f4c26) to head (1320f6d).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

Impacted file tree graph

@@          Coverage Diff          @@
##            main      #3   +/-   ##
=====================================
  Coverage   7.49%   7.49%           
=====================================
  Files          1       1           
  Lines        387     387           
=====================================
  Hits          29      29           
  Misses       357     357           
  Partials       1       1           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Create comprehensive guidelines for AI coding agents working on this project.
Key principle: Agents should use wt to create worktrees for each task instead
of switching branches in the main repository.

Benefits:
- User's main repo stays on main branch (non-disruptive)
- Each feature gets isolated directory
- Demonstrates best practices for the tool itself
- Enables parallel work on multiple features

Includes:
- Golden rule: use worktrees, not branch switching
- Complete agent workflow examples
- Interactive command usage
- PR/MR workflow
- Common pitfalls to avoid
- Project-specific conventions

This ensures agents practice what wt preaches - proper worktree usage!

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@timvw timvw force-pushed the docs/add-agents-guide branch from 4bb04ed to 1320f6d Compare November 29, 2025 15:13
@timvw timvw merged commit 9bb5b2a into main Nov 29, 2025
8 checks passed
@timvw timvw deleted the docs/add-agents-guide branch November 29, 2025 15:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant