From a363a03932a3c1f46399d1eb3f44cbbc8236f7c3 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sun, 25 Jan 2026 05:48:10 -0800 Subject: [PATCH 1/6] docs(skill): emphasize --from flag for branch-based work in agent-cli-dev skill When spawning agents to review or test an existing branch, the --from flag is required to base the worktree off that branch. Without it, the worktree starts from origin/main and won't have the changes to review. Added: - "IMPORTANT: Using --from for branch-based work" section in SKILL.md - "Scenario 0: Code review of current branch" example in examples.md - Comprehensive review criteria (DRY, KISS, YAGNI, etc.) in the example --- .claude-plugin/skills/agent-cli-dev/SKILL.md | 24 +++++++++ .../skills/agent-cli-dev/examples.md | 51 +++++++++++++++++++ .claude/skills/agent-cli-dev/SKILL.md | 24 +++++++++ .claude/skills/agent-cli-dev/examples.md | 51 +++++++++++++++++++ agent_cli/dev/skill/SKILL.md | 24 +++++++++ agent_cli/dev/skill/examples.md | 51 +++++++++++++++++++ 6 files changed, 225 insertions(+) diff --git a/.claude-plugin/skills/agent-cli-dev/SKILL.md b/.claude-plugin/skills/agent-cli-dev/SKILL.md index dce8f31fd..f6b94fb94 100644 --- a/.claude-plugin/skills/agent-cli-dev/SKILL.md +++ b/.claude-plugin/skills/agent-cli-dev/SKILL.md @@ -44,6 +44,30 @@ For longer prompts (recommended for multi-line or complex instructions): agent-cli dev new --agent --prompt-file path/to/prompt.md ``` +### IMPORTANT: Using --from for branch-based work + +**When reviewing, testing, or working on an existing branch, you MUST use `--from` to base the worktree off that branch:** + +```bash +# Review the current branch (use HEAD or the branch name) +agent-cli dev new review-feature --from HEAD --agent --prompt "Review the code changes..." + +# Create a worktree based on a specific branch +agent-cli dev new test-feature --from feature-branch --agent --prompt "Test the changes..." +``` + +**Without `--from`, the worktree starts from `origin/main` and won't have the changes you want to review/test!** + +Use `--from` when: +- Reviewing code on the current branch +- Testing changes from an existing feature branch +- Continuing work on an existing branch in a new worktree +- Any task that needs access to uncommitted or branch-specific changes + +Default behavior (no `--from`) is only appropriate for: +- Starting completely new, independent features +- Work that should begin from a clean main branch state + This creates: 1. A new git worktree with its own branch 2. Runs project setup (installs dependencies) diff --git a/.claude-plugin/skills/agent-cli-dev/examples.md b/.claude-plugin/skills/agent-cli-dev/examples.md index e833eb96d..0524a9765 100644 --- a/.claude-plugin/skills/agent-cli-dev/examples.md +++ b/.claude-plugin/skills/agent-cli-dev/examples.md @@ -9,6 +9,57 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud > agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md > ``` +## Scenario 0: Code review of current branch + +**User request**: "Review the code on this branch" or "Spawn an agent to review my changes" + +**CRITICAL**: Use `--from HEAD` (or the branch name) so the review agent has access to the changes! + +```bash +# Review the current branch - MUST use --from HEAD +agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code changes on this branch. + + +- Use git diff origin/main...HEAD to see all changes on this branch +- Read the changed files to understand the full context +- Check CLAUDE.md for project-specific guidelines +- Test the changes with real services if applicable + + + +- Code cleanliness: Is the implementation clean and well-structured? +- DRY principle: Does it avoid duplication? +- Code reuse: Are there parts that should be reused from other places? +- Organization: Is everything in the right place? +- Consistency: Is it in the same style as other parts of the codebase? +- Simplicity: Is it not over-engineered? Remember KISS and YAGNI. No dead code paths and NO defensive programming. +- No pointless wrappers: Identify functions/methods that just call another function and return its result. Callers should call the underlying function directly. +- User experience: Does it provide a good user experience? +- Tests: Are there tests, and do they cover the changes adequately? Are they testing something meaningful or are they just trivial? +- Rules: Does the code follow the project's coding standards and guidelines in CLAUDE.md? + + + +Write your review to .claude/REPORT.md: + +## Summary +[Overall assessment of the changes] + +## Issues Found +| Severity | File:Line | Issue | Suggestion | +|----------|-----------|-------|------------| +| Critical/High/Medium/Low | path:123 | description | fix | + +## Positive Observations +[What's well done] + +## Recommendations +[Suggestions for improvement] +" +``` + +**Common mistake**: Forgetting `--from HEAD` means the agent starts from `origin/main` and won't see any of the branch changes! + ## Prompt structure guidelines Each prompt for a spawned agent should follow this structure: diff --git a/.claude/skills/agent-cli-dev/SKILL.md b/.claude/skills/agent-cli-dev/SKILL.md index dce8f31fd..f6b94fb94 100644 --- a/.claude/skills/agent-cli-dev/SKILL.md +++ b/.claude/skills/agent-cli-dev/SKILL.md @@ -44,6 +44,30 @@ For longer prompts (recommended for multi-line or complex instructions): agent-cli dev new --agent --prompt-file path/to/prompt.md ``` +### IMPORTANT: Using --from for branch-based work + +**When reviewing, testing, or working on an existing branch, you MUST use `--from` to base the worktree off that branch:** + +```bash +# Review the current branch (use HEAD or the branch name) +agent-cli dev new review-feature --from HEAD --agent --prompt "Review the code changes..." + +# Create a worktree based on a specific branch +agent-cli dev new test-feature --from feature-branch --agent --prompt "Test the changes..." +``` + +**Without `--from`, the worktree starts from `origin/main` and won't have the changes you want to review/test!** + +Use `--from` when: +- Reviewing code on the current branch +- Testing changes from an existing feature branch +- Continuing work on an existing branch in a new worktree +- Any task that needs access to uncommitted or branch-specific changes + +Default behavior (no `--from`) is only appropriate for: +- Starting completely new, independent features +- Work that should begin from a clean main branch state + This creates: 1. A new git worktree with its own branch 2. Runs project setup (installs dependencies) diff --git a/.claude/skills/agent-cli-dev/examples.md b/.claude/skills/agent-cli-dev/examples.md index e833eb96d..0524a9765 100644 --- a/.claude/skills/agent-cli-dev/examples.md +++ b/.claude/skills/agent-cli-dev/examples.md @@ -9,6 +9,57 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud > agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md > ``` +## Scenario 0: Code review of current branch + +**User request**: "Review the code on this branch" or "Spawn an agent to review my changes" + +**CRITICAL**: Use `--from HEAD` (or the branch name) so the review agent has access to the changes! + +```bash +# Review the current branch - MUST use --from HEAD +agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code changes on this branch. + + +- Use git diff origin/main...HEAD to see all changes on this branch +- Read the changed files to understand the full context +- Check CLAUDE.md for project-specific guidelines +- Test the changes with real services if applicable + + + +- Code cleanliness: Is the implementation clean and well-structured? +- DRY principle: Does it avoid duplication? +- Code reuse: Are there parts that should be reused from other places? +- Organization: Is everything in the right place? +- Consistency: Is it in the same style as other parts of the codebase? +- Simplicity: Is it not over-engineered? Remember KISS and YAGNI. No dead code paths and NO defensive programming. +- No pointless wrappers: Identify functions/methods that just call another function and return its result. Callers should call the underlying function directly. +- User experience: Does it provide a good user experience? +- Tests: Are there tests, and do they cover the changes adequately? Are they testing something meaningful or are they just trivial? +- Rules: Does the code follow the project's coding standards and guidelines in CLAUDE.md? + + + +Write your review to .claude/REPORT.md: + +## Summary +[Overall assessment of the changes] + +## Issues Found +| Severity | File:Line | Issue | Suggestion | +|----------|-----------|-------|------------| +| Critical/High/Medium/Low | path:123 | description | fix | + +## Positive Observations +[What's well done] + +## Recommendations +[Suggestions for improvement] +" +``` + +**Common mistake**: Forgetting `--from HEAD` means the agent starts from `origin/main` and won't see any of the branch changes! + ## Prompt structure guidelines Each prompt for a spawned agent should follow this structure: diff --git a/agent_cli/dev/skill/SKILL.md b/agent_cli/dev/skill/SKILL.md index dce8f31fd..f6b94fb94 100644 --- a/agent_cli/dev/skill/SKILL.md +++ b/agent_cli/dev/skill/SKILL.md @@ -44,6 +44,30 @@ For longer prompts (recommended for multi-line or complex instructions): agent-cli dev new --agent --prompt-file path/to/prompt.md ``` +### IMPORTANT: Using --from for branch-based work + +**When reviewing, testing, or working on an existing branch, you MUST use `--from` to base the worktree off that branch:** + +```bash +# Review the current branch (use HEAD or the branch name) +agent-cli dev new review-feature --from HEAD --agent --prompt "Review the code changes..." + +# Create a worktree based on a specific branch +agent-cli dev new test-feature --from feature-branch --agent --prompt "Test the changes..." +``` + +**Without `--from`, the worktree starts from `origin/main` and won't have the changes you want to review/test!** + +Use `--from` when: +- Reviewing code on the current branch +- Testing changes from an existing feature branch +- Continuing work on an existing branch in a new worktree +- Any task that needs access to uncommitted or branch-specific changes + +Default behavior (no `--from`) is only appropriate for: +- Starting completely new, independent features +- Work that should begin from a clean main branch state + This creates: 1. A new git worktree with its own branch 2. Runs project setup (installs dependencies) diff --git a/agent_cli/dev/skill/examples.md b/agent_cli/dev/skill/examples.md index e833eb96d..0524a9765 100644 --- a/agent_cli/dev/skill/examples.md +++ b/agent_cli/dev/skill/examples.md @@ -9,6 +9,57 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud > agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md > ``` +## Scenario 0: Code review of current branch + +**User request**: "Review the code on this branch" or "Spawn an agent to review my changes" + +**CRITICAL**: Use `--from HEAD` (or the branch name) so the review agent has access to the changes! + +```bash +# Review the current branch - MUST use --from HEAD +agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code changes on this branch. + + +- Use git diff origin/main...HEAD to see all changes on this branch +- Read the changed files to understand the full context +- Check CLAUDE.md for project-specific guidelines +- Test the changes with real services if applicable + + + +- Code cleanliness: Is the implementation clean and well-structured? +- DRY principle: Does it avoid duplication? +- Code reuse: Are there parts that should be reused from other places? +- Organization: Is everything in the right place? +- Consistency: Is it in the same style as other parts of the codebase? +- Simplicity: Is it not over-engineered? Remember KISS and YAGNI. No dead code paths and NO defensive programming. +- No pointless wrappers: Identify functions/methods that just call another function and return its result. Callers should call the underlying function directly. +- User experience: Does it provide a good user experience? +- Tests: Are there tests, and do they cover the changes adequately? Are they testing something meaningful or are they just trivial? +- Rules: Does the code follow the project's coding standards and guidelines in CLAUDE.md? + + + +Write your review to .claude/REPORT.md: + +## Summary +[Overall assessment of the changes] + +## Issues Found +| Severity | File:Line | Issue | Suggestion | +|----------|-----------|-------|------------| +| Critical/High/Medium/Low | path:123 | description | fix | + +## Positive Observations +[What's well done] + +## Recommendations +[Suggestions for improvement] +" +``` + +**Common mistake**: Forgetting `--from HEAD` means the agent starts from `origin/main` and won't see any of the branch changes! + ## Prompt structure guidelines Each prompt for a spawned agent should follow this structure: From 0fff5d19553827cce3c9ebecbb74133fb273612b Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sun, 25 Jan 2026 05:54:10 -0800 Subject: [PATCH 2/6] fix: align review example with prompt structure guidelines --- .../skills/agent-cli-dev/examples.md | 40 ++++++++++--------- .claude/skills/agent-cli-dev/examples.md | 40 ++++++++++--------- agent_cli/dev/skill/examples.md | 40 ++++++++++--------- 3 files changed, 66 insertions(+), 54 deletions(-) diff --git a/.claude-plugin/skills/agent-cli-dev/examples.md b/.claude-plugin/skills/agent-cli-dev/examples.md index 0524a9765..cb79b264f 100644 --- a/.claude-plugin/skills/agent-cli-dev/examples.md +++ b/.claude-plugin/skills/agent-cli-dev/examples.md @@ -20,24 +20,31 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code changes on this branch. -- Use git diff origin/main...HEAD to see all changes on this branch -- Read the changed files to understand the full context +- Run git diff origin/main...HEAD to identify all changes +- Read changed files in parallel to understand context - Check CLAUDE.md for project-specific guidelines -- Test the changes with real services if applicable +- Test changes with real services if applicable - -- Code cleanliness: Is the implementation clean and well-structured? -- DRY principle: Does it avoid duplication? -- Code reuse: Are there parts that should be reused from other places? -- Organization: Is everything in the right place? -- Consistency: Is it in the same style as other parts of the codebase? -- Simplicity: Is it not over-engineered? Remember KISS and YAGNI. No dead code paths and NO defensive programming. -- No pointless wrappers: Identify functions/methods that just call another function and return its result. Callers should call the underlying function directly. -- User experience: Does it provide a good user experience? -- Tests: Are there tests, and do they cover the changes adequately? Are they testing something meaningful or are they just trivial? -- Rules: Does the code follow the project's coding standards and guidelines in CLAUDE.md? - + +- Use git diff origin/main...HEAD to see the full diff +- Read each changed file completely before judging +- Look at surrounding code to understand patterns +- Check existing tests to understand expected behavior + + + +Code review catches issues before merge. Focus on real problems that affect correctness, security, or maintainability - not style nitpicks. Apply these criteria: +- DRY: Does it avoid duplication? +- KISS/YAGNI: Is it over-engineered? No dead code paths, no defensive programming +- No pointless wrappers: Functions that just call another function should be inlined +- Consistency: Does it match the style of surrounding code? +- Tests: Are tests meaningful or just trivial coverage? + + + +Review only - identify issues but do not fix them. Write findings to report. + Write your review to .claude/REPORT.md: @@ -52,9 +59,6 @@ Write your review to .claude/REPORT.md: ## Positive Observations [What's well done] - -## Recommendations -[Suggestions for improvement] " ``` diff --git a/.claude/skills/agent-cli-dev/examples.md b/.claude/skills/agent-cli-dev/examples.md index 0524a9765..cb79b264f 100644 --- a/.claude/skills/agent-cli-dev/examples.md +++ b/.claude/skills/agent-cli-dev/examples.md @@ -20,24 +20,31 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code changes on this branch. -- Use git diff origin/main...HEAD to see all changes on this branch -- Read the changed files to understand the full context +- Run git diff origin/main...HEAD to identify all changes +- Read changed files in parallel to understand context - Check CLAUDE.md for project-specific guidelines -- Test the changes with real services if applicable +- Test changes with real services if applicable - -- Code cleanliness: Is the implementation clean and well-structured? -- DRY principle: Does it avoid duplication? -- Code reuse: Are there parts that should be reused from other places? -- Organization: Is everything in the right place? -- Consistency: Is it in the same style as other parts of the codebase? -- Simplicity: Is it not over-engineered? Remember KISS and YAGNI. No dead code paths and NO defensive programming. -- No pointless wrappers: Identify functions/methods that just call another function and return its result. Callers should call the underlying function directly. -- User experience: Does it provide a good user experience? -- Tests: Are there tests, and do they cover the changes adequately? Are they testing something meaningful or are they just trivial? -- Rules: Does the code follow the project's coding standards and guidelines in CLAUDE.md? - + +- Use git diff origin/main...HEAD to see the full diff +- Read each changed file completely before judging +- Look at surrounding code to understand patterns +- Check existing tests to understand expected behavior + + + +Code review catches issues before merge. Focus on real problems that affect correctness, security, or maintainability - not style nitpicks. Apply these criteria: +- DRY: Does it avoid duplication? +- KISS/YAGNI: Is it over-engineered? No dead code paths, no defensive programming +- No pointless wrappers: Functions that just call another function should be inlined +- Consistency: Does it match the style of surrounding code? +- Tests: Are tests meaningful or just trivial coverage? + + + +Review only - identify issues but do not fix them. Write findings to report. + Write your review to .claude/REPORT.md: @@ -52,9 +59,6 @@ Write your review to .claude/REPORT.md: ## Positive Observations [What's well done] - -## Recommendations -[Suggestions for improvement] " ``` diff --git a/agent_cli/dev/skill/examples.md b/agent_cli/dev/skill/examples.md index 0524a9765..cb79b264f 100644 --- a/agent_cli/dev/skill/examples.md +++ b/agent_cli/dev/skill/examples.md @@ -20,24 +20,31 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code changes on this branch. -- Use git diff origin/main...HEAD to see all changes on this branch -- Read the changed files to understand the full context +- Run git diff origin/main...HEAD to identify all changes +- Read changed files in parallel to understand context - Check CLAUDE.md for project-specific guidelines -- Test the changes with real services if applicable +- Test changes with real services if applicable - -- Code cleanliness: Is the implementation clean and well-structured? -- DRY principle: Does it avoid duplication? -- Code reuse: Are there parts that should be reused from other places? -- Organization: Is everything in the right place? -- Consistency: Is it in the same style as other parts of the codebase? -- Simplicity: Is it not over-engineered? Remember KISS and YAGNI. No dead code paths and NO defensive programming. -- No pointless wrappers: Identify functions/methods that just call another function and return its result. Callers should call the underlying function directly. -- User experience: Does it provide a good user experience? -- Tests: Are there tests, and do they cover the changes adequately? Are they testing something meaningful or are they just trivial? -- Rules: Does the code follow the project's coding standards and guidelines in CLAUDE.md? - + +- Use git diff origin/main...HEAD to see the full diff +- Read each changed file completely before judging +- Look at surrounding code to understand patterns +- Check existing tests to understand expected behavior + + + +Code review catches issues before merge. Focus on real problems that affect correctness, security, or maintainability - not style nitpicks. Apply these criteria: +- DRY: Does it avoid duplication? +- KISS/YAGNI: Is it over-engineered? No dead code paths, no defensive programming +- No pointless wrappers: Functions that just call another function should be inlined +- Consistency: Does it match the style of surrounding code? +- Tests: Are tests meaningful or just trivial coverage? + + + +Review only - identify issues but do not fix them. Write findings to report. + Write your review to .claude/REPORT.md: @@ -52,9 +59,6 @@ Write your review to .claude/REPORT.md: ## Positive Observations [What's well done] - -## Recommendations -[Suggestions for improvement] " ``` From 8aafabe20dee3e370fd39428ad219c6bf1489bfb Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sun, 25 Jan 2026 05:56:16 -0800 Subject: [PATCH 3/6] simplify: move --from guidance to key options table --- .claude-plugin/skills/agent-cli-dev/SKILL.md | 26 +------------------- .claude/skills/agent-cli-dev/SKILL.md | 26 +------------------- agent_cli/dev/skill/SKILL.md | 26 +------------------- 3 files changed, 3 insertions(+), 75 deletions(-) diff --git a/.claude-plugin/skills/agent-cli-dev/SKILL.md b/.claude-plugin/skills/agent-cli-dev/SKILL.md index f6b94fb94..f24f1a64d 100644 --- a/.claude-plugin/skills/agent-cli-dev/SKILL.md +++ b/.claude-plugin/skills/agent-cli-dev/SKILL.md @@ -44,30 +44,6 @@ For longer prompts (recommended for multi-line or complex instructions): agent-cli dev new --agent --prompt-file path/to/prompt.md ``` -### IMPORTANT: Using --from for branch-based work - -**When reviewing, testing, or working on an existing branch, you MUST use `--from` to base the worktree off that branch:** - -```bash -# Review the current branch (use HEAD or the branch name) -agent-cli dev new review-feature --from HEAD --agent --prompt "Review the code changes..." - -# Create a worktree based on a specific branch -agent-cli dev new test-feature --from feature-branch --agent --prompt "Test the changes..." -``` - -**Without `--from`, the worktree starts from `origin/main` and won't have the changes you want to review/test!** - -Use `--from` when: -- Reviewing code on the current branch -- Testing changes from an existing feature branch -- Continuing work on an existing branch in a new worktree -- Any task that needs access to uncommitted or branch-specific changes - -Default behavior (no `--from`) is only appropriate for: -- Starting completely new, independent features -- Work that should begin from a clean main branch state - This creates: 1. A new git worktree with its own branch 2. Runs project setup (installs dependencies) @@ -153,7 +129,7 @@ Each agent works independently in its own branch. Results can be reviewed and me | `--agent` / `-a` | Start AI coding agent after creation | | `--prompt` / `-p` | Initial prompt for the agent (short prompts only) | | `--prompt-file` / `-P` | Read prompt from file (recommended for longer prompts) | -| `--from` / `-f` | Base branch (default: origin/main) | +| `--from` / `-f` | Base ref (default: origin/main). **Use `--from HEAD` when reviewing/testing current branch!** | | `--with-agent` | Specific agent: claude, aider, codex, gemini | | `--agent-args` | Extra arguments for the agent | diff --git a/.claude/skills/agent-cli-dev/SKILL.md b/.claude/skills/agent-cli-dev/SKILL.md index f6b94fb94..f24f1a64d 100644 --- a/.claude/skills/agent-cli-dev/SKILL.md +++ b/.claude/skills/agent-cli-dev/SKILL.md @@ -44,30 +44,6 @@ For longer prompts (recommended for multi-line or complex instructions): agent-cli dev new --agent --prompt-file path/to/prompt.md ``` -### IMPORTANT: Using --from for branch-based work - -**When reviewing, testing, or working on an existing branch, you MUST use `--from` to base the worktree off that branch:** - -```bash -# Review the current branch (use HEAD or the branch name) -agent-cli dev new review-feature --from HEAD --agent --prompt "Review the code changes..." - -# Create a worktree based on a specific branch -agent-cli dev new test-feature --from feature-branch --agent --prompt "Test the changes..." -``` - -**Without `--from`, the worktree starts from `origin/main` and won't have the changes you want to review/test!** - -Use `--from` when: -- Reviewing code on the current branch -- Testing changes from an existing feature branch -- Continuing work on an existing branch in a new worktree -- Any task that needs access to uncommitted or branch-specific changes - -Default behavior (no `--from`) is only appropriate for: -- Starting completely new, independent features -- Work that should begin from a clean main branch state - This creates: 1. A new git worktree with its own branch 2. Runs project setup (installs dependencies) @@ -153,7 +129,7 @@ Each agent works independently in its own branch. Results can be reviewed and me | `--agent` / `-a` | Start AI coding agent after creation | | `--prompt` / `-p` | Initial prompt for the agent (short prompts only) | | `--prompt-file` / `-P` | Read prompt from file (recommended for longer prompts) | -| `--from` / `-f` | Base branch (default: origin/main) | +| `--from` / `-f` | Base ref (default: origin/main). **Use `--from HEAD` when reviewing/testing current branch!** | | `--with-agent` | Specific agent: claude, aider, codex, gemini | | `--agent-args` | Extra arguments for the agent | diff --git a/agent_cli/dev/skill/SKILL.md b/agent_cli/dev/skill/SKILL.md index f6b94fb94..f24f1a64d 100644 --- a/agent_cli/dev/skill/SKILL.md +++ b/agent_cli/dev/skill/SKILL.md @@ -44,30 +44,6 @@ For longer prompts (recommended for multi-line or complex instructions): agent-cli dev new --agent --prompt-file path/to/prompt.md ``` -### IMPORTANT: Using --from for branch-based work - -**When reviewing, testing, or working on an existing branch, you MUST use `--from` to base the worktree off that branch:** - -```bash -# Review the current branch (use HEAD or the branch name) -agent-cli dev new review-feature --from HEAD --agent --prompt "Review the code changes..." - -# Create a worktree based on a specific branch -agent-cli dev new test-feature --from feature-branch --agent --prompt "Test the changes..." -``` - -**Without `--from`, the worktree starts from `origin/main` and won't have the changes you want to review/test!** - -Use `--from` when: -- Reviewing code on the current branch -- Testing changes from an existing feature branch -- Continuing work on an existing branch in a new worktree -- Any task that needs access to uncommitted or branch-specific changes - -Default behavior (no `--from`) is only appropriate for: -- Starting completely new, independent features -- Work that should begin from a clean main branch state - This creates: 1. A new git worktree with its own branch 2. Runs project setup (installs dependencies) @@ -153,7 +129,7 @@ Each agent works independently in its own branch. Results can be reviewed and me | `--agent` / `-a` | Start AI coding agent after creation | | `--prompt` / `-p` | Initial prompt for the agent (short prompts only) | | `--prompt-file` / `-P` | Read prompt from file (recommended for longer prompts) | -| `--from` / `-f` | Base branch (default: origin/main) | +| `--from` / `-f` | Base ref (default: origin/main). **Use `--from HEAD` when reviewing/testing current branch!** | | `--with-agent` | Specific agent: claude, aider, codex, gemini | | `--agent-args` | Extra arguments for the agent | From 2e2315a830505e5c9d1f92488770389bb5738a5e Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sun, 25 Jan 2026 05:57:35 -0800 Subject: [PATCH 4/6] add --from HEAD to example commands --- .claude-plugin/skills/agent-cli-dev/SKILL.md | 11 ++++++++--- .claude/skills/agent-cli-dev/SKILL.md | 11 ++++++++--- agent_cli/dev/skill/SKILL.md | 11 ++++++++--- 3 files changed, 24 insertions(+), 9 deletions(-) diff --git a/.claude-plugin/skills/agent-cli-dev/SKILL.md b/.claude-plugin/skills/agent-cli-dev/SKILL.md index f24f1a64d..9c4e52f55 100644 --- a/.claude-plugin/skills/agent-cli-dev/SKILL.md +++ b/.claude-plugin/skills/agent-cli-dev/SKILL.md @@ -34,14 +34,19 @@ Do NOT spawn when: ## Core command -For short prompts: +For new features (starts from origin/main): ```bash -agent-cli dev new --agent --prompt "Fix the login bug" +agent-cli dev new --agent --prompt "Implement the new feature..." +``` + +For work on current branch (review, test, fix) - use `--from HEAD`: +```bash +agent-cli dev new --from HEAD --agent --prompt "Review/test/fix..." ``` For longer prompts (recommended for multi-line or complex instructions): ```bash -agent-cli dev new --agent --prompt-file path/to/prompt.md +agent-cli dev new --from HEAD --agent --prompt-file path/to/prompt.md ``` This creates: diff --git a/.claude/skills/agent-cli-dev/SKILL.md b/.claude/skills/agent-cli-dev/SKILL.md index f24f1a64d..9c4e52f55 100644 --- a/.claude/skills/agent-cli-dev/SKILL.md +++ b/.claude/skills/agent-cli-dev/SKILL.md @@ -34,14 +34,19 @@ Do NOT spawn when: ## Core command -For short prompts: +For new features (starts from origin/main): ```bash -agent-cli dev new --agent --prompt "Fix the login bug" +agent-cli dev new --agent --prompt "Implement the new feature..." +``` + +For work on current branch (review, test, fix) - use `--from HEAD`: +```bash +agent-cli dev new --from HEAD --agent --prompt "Review/test/fix..." ``` For longer prompts (recommended for multi-line or complex instructions): ```bash -agent-cli dev new --agent --prompt-file path/to/prompt.md +agent-cli dev new --from HEAD --agent --prompt-file path/to/prompt.md ``` This creates: diff --git a/agent_cli/dev/skill/SKILL.md b/agent_cli/dev/skill/SKILL.md index f24f1a64d..9c4e52f55 100644 --- a/agent_cli/dev/skill/SKILL.md +++ b/agent_cli/dev/skill/SKILL.md @@ -34,14 +34,19 @@ Do NOT spawn when: ## Core command -For short prompts: +For new features (starts from origin/main): ```bash -agent-cli dev new --agent --prompt "Fix the login bug" +agent-cli dev new --agent --prompt "Implement the new feature..." +``` + +For work on current branch (review, test, fix) - use `--from HEAD`: +```bash +agent-cli dev new --from HEAD --agent --prompt "Review/test/fix..." ``` For longer prompts (recommended for multi-line or complex instructions): ```bash -agent-cli dev new --agent --prompt-file path/to/prompt.md +agent-cli dev new --from HEAD --agent --prompt-file path/to/prompt.md ``` This creates: From f979627612eb70036049e43e619bc7d89106b302 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sun, 25 Jan 2026 06:00:04 -0800 Subject: [PATCH 5/6] move code review scenario after guidelines, renumber scenarios --- .../skills/agent-cli-dev/examples.md | 32 +++++++++---------- .claude/skills/agent-cli-dev/examples.md | 32 +++++++++---------- agent_cli/dev/skill/examples.md | 32 +++++++++---------- 3 files changed, 48 insertions(+), 48 deletions(-) diff --git a/.claude-plugin/skills/agent-cli-dev/examples.md b/.claude-plugin/skills/agent-cli-dev/examples.md index cb79b264f..013ab6197 100644 --- a/.claude-plugin/skills/agent-cli-dev/examples.md +++ b/.claude-plugin/skills/agent-cli-dev/examples.md @@ -9,7 +9,18 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud > agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md > ``` -## Scenario 0: Code review of current branch +## Prompt structure guidelines + +Each prompt for a spawned agent should follow this structure: + +1. **Explicit task description** - Be specific about what to implement +2. **Workflow directive** - Read files in parallel, commit incrementally, verify before completing +3. **Code exploration** - Read and understand existing code before writing +4. **Context with motivation** - Explain why patterns matter +5. **Focused scope** - Keep solutions minimal, implement only what's requested +6. **Structured report** - Write conclusions to `.claude/REPORT.md` + +## Scenario 1: Code review of current branch **User request**: "Review the code on this branch" or "Spawn an agent to review my changes" @@ -64,18 +75,7 @@ Write your review to .claude/REPORT.md: **Common mistake**: Forgetting `--from HEAD` means the agent starts from `origin/main` and won't see any of the branch changes! -## Prompt structure guidelines - -Each prompt for a spawned agent should follow this structure: - -1. **Explicit task description** - Be specific about what to implement -2. **Workflow directive** - Read files in parallel, commit incrementally, verify before completing -3. **Code exploration** - Read and understand existing code before writing -4. **Context with motivation** - Explain why patterns matter -5. **Focused scope** - Keep solutions minimal, implement only what's requested -6. **Structured report** - Write conclusions to `.claude/REPORT.md` - -## Scenario 1: Multi-feature implementation +## Scenario 2: Multi-feature implementation **User request**: "Implement user auth, payment processing, and email notifications" @@ -224,7 +224,7 @@ After verifying tests pass, write to .claude/REPORT.md with summary, files chang " ``` -## Scenario 2: Test-driven development +## Scenario 3: Test-driven development **User request**: "Add a caching layer with comprehensive tests" @@ -344,7 +344,7 @@ After ALL tests pass, write to .claude/REPORT.md: " ``` -## Scenario 3: Large refactoring by module +## Scenario 4: Large refactoring by module **User request**: "Refactor the API to use consistent error handling" @@ -412,7 +412,7 @@ After tests pass and linting is clean, write to .claude/REPORT.md: " ``` -## Scenario 4: Documentation and implementation in parallel +## Scenario 5: Documentation and implementation in parallel **User request**: "Add a plugin system with documentation" diff --git a/.claude/skills/agent-cli-dev/examples.md b/.claude/skills/agent-cli-dev/examples.md index cb79b264f..013ab6197 100644 --- a/.claude/skills/agent-cli-dev/examples.md +++ b/.claude/skills/agent-cli-dev/examples.md @@ -9,7 +9,18 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud > agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md > ``` -## Scenario 0: Code review of current branch +## Prompt structure guidelines + +Each prompt for a spawned agent should follow this structure: + +1. **Explicit task description** - Be specific about what to implement +2. **Workflow directive** - Read files in parallel, commit incrementally, verify before completing +3. **Code exploration** - Read and understand existing code before writing +4. **Context with motivation** - Explain why patterns matter +5. **Focused scope** - Keep solutions minimal, implement only what's requested +6. **Structured report** - Write conclusions to `.claude/REPORT.md` + +## Scenario 1: Code review of current branch **User request**: "Review the code on this branch" or "Spawn an agent to review my changes" @@ -64,18 +75,7 @@ Write your review to .claude/REPORT.md: **Common mistake**: Forgetting `--from HEAD` means the agent starts from `origin/main` and won't see any of the branch changes! -## Prompt structure guidelines - -Each prompt for a spawned agent should follow this structure: - -1. **Explicit task description** - Be specific about what to implement -2. **Workflow directive** - Read files in parallel, commit incrementally, verify before completing -3. **Code exploration** - Read and understand existing code before writing -4. **Context with motivation** - Explain why patterns matter -5. **Focused scope** - Keep solutions minimal, implement only what's requested -6. **Structured report** - Write conclusions to `.claude/REPORT.md` - -## Scenario 1: Multi-feature implementation +## Scenario 2: Multi-feature implementation **User request**: "Implement user auth, payment processing, and email notifications" @@ -224,7 +224,7 @@ After verifying tests pass, write to .claude/REPORT.md with summary, files chang " ``` -## Scenario 2: Test-driven development +## Scenario 3: Test-driven development **User request**: "Add a caching layer with comprehensive tests" @@ -344,7 +344,7 @@ After ALL tests pass, write to .claude/REPORT.md: " ``` -## Scenario 3: Large refactoring by module +## Scenario 4: Large refactoring by module **User request**: "Refactor the API to use consistent error handling" @@ -412,7 +412,7 @@ After tests pass and linting is clean, write to .claude/REPORT.md: " ``` -## Scenario 4: Documentation and implementation in parallel +## Scenario 5: Documentation and implementation in parallel **User request**: "Add a plugin system with documentation" diff --git a/agent_cli/dev/skill/examples.md b/agent_cli/dev/skill/examples.md index cb79b264f..013ab6197 100644 --- a/agent_cli/dev/skill/examples.md +++ b/agent_cli/dev/skill/examples.md @@ -9,7 +9,18 @@ Real-world scenarios for spawning parallel AI coding agents, optimized for Claud > agent-cli dev new my-feature --agent --prompt-file .claude/spawn-prompt.md > ``` -## Scenario 0: Code review of current branch +## Prompt structure guidelines + +Each prompt for a spawned agent should follow this structure: + +1. **Explicit task description** - Be specific about what to implement +2. **Workflow directive** - Read files in parallel, commit incrementally, verify before completing +3. **Code exploration** - Read and understand existing code before writing +4. **Context with motivation** - Explain why patterns matter +5. **Focused scope** - Keep solutions minimal, implement only what's requested +6. **Structured report** - Write conclusions to `.claude/REPORT.md` + +## Scenario 1: Code review of current branch **User request**: "Review the code on this branch" or "Spawn an agent to review my changes" @@ -64,18 +75,7 @@ Write your review to .claude/REPORT.md: **Common mistake**: Forgetting `--from HEAD` means the agent starts from `origin/main` and won't see any of the branch changes! -## Prompt structure guidelines - -Each prompt for a spawned agent should follow this structure: - -1. **Explicit task description** - Be specific about what to implement -2. **Workflow directive** - Read files in parallel, commit incrementally, verify before completing -3. **Code exploration** - Read and understand existing code before writing -4. **Context with motivation** - Explain why patterns matter -5. **Focused scope** - Keep solutions minimal, implement only what's requested -6. **Structured report** - Write conclusions to `.claude/REPORT.md` - -## Scenario 1: Multi-feature implementation +## Scenario 2: Multi-feature implementation **User request**: "Implement user auth, payment processing, and email notifications" @@ -224,7 +224,7 @@ After verifying tests pass, write to .claude/REPORT.md with summary, files chang " ``` -## Scenario 2: Test-driven development +## Scenario 3: Test-driven development **User request**: "Add a caching layer with comprehensive tests" @@ -344,7 +344,7 @@ After ALL tests pass, write to .claude/REPORT.md: " ``` -## Scenario 3: Large refactoring by module +## Scenario 4: Large refactoring by module **User request**: "Refactor the API to use consistent error handling" @@ -412,7 +412,7 @@ After tests pass and linting is clean, write to .claude/REPORT.md: " ``` -## Scenario 4: Documentation and implementation in parallel +## Scenario 5: Documentation and implementation in parallel **User request**: "Add a plugin system with documentation" From 63f7bad2840c808af837ac38e53d3e97f94d69f7 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sun, 25 Jan 2026 06:03:54 -0800 Subject: [PATCH 6/6] align review criteria with pr-review.md --- .claude-plugin/skills/agent-cli-dev/examples.md | 16 +++++++++++----- .claude/skills/agent-cli-dev/examples.md | 16 +++++++++++----- agent_cli/dev/skill/examples.md | 16 +++++++++++----- 3 files changed, 33 insertions(+), 15 deletions(-) diff --git a/.claude-plugin/skills/agent-cli-dev/examples.md b/.claude-plugin/skills/agent-cli-dev/examples.md index 013ab6197..5a06a8d2c 100644 --- a/.claude-plugin/skills/agent-cli-dev/examples.md +++ b/.claude-plugin/skills/agent-cli-dev/examples.md @@ -45,12 +45,18 @@ agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code c -Code review catches issues before merge. Focus on real problems that affect correctness, security, or maintainability - not style nitpicks. Apply these criteria: -- DRY: Does it avoid duplication? -- KISS/YAGNI: Is it over-engineered? No dead code paths, no defensive programming -- No pointless wrappers: Functions that just call another function should be inlined -- Consistency: Does it match the style of surrounding code? +Code review catches issues before merge. Focus on real problems - not style nitpicks. Apply these criteria: +- Code cleanliness: Is the implementation clean and well-structured? +- DRY principle: Does it avoid duplication? +- Code reuse: Are there parts that should be reused from other places? +- Organization: Is everything in the right place? +- Consistency: Is it in the same style as other parts of the codebase? +- Simplicity: Is it over-engineered? Remember KISS and YAGNI. No dead code paths, no defensive programming. +- No pointless wrappers: Functions that just call another function should be inlined. +- User experience: Does it provide a good user experience? - Tests: Are tests meaningful or just trivial coverage? +- Live tests: Test changes with real services if applicable. +- Rules: Does the code follow CLAUDE.md guidelines? diff --git a/.claude/skills/agent-cli-dev/examples.md b/.claude/skills/agent-cli-dev/examples.md index 013ab6197..5a06a8d2c 100644 --- a/.claude/skills/agent-cli-dev/examples.md +++ b/.claude/skills/agent-cli-dev/examples.md @@ -45,12 +45,18 @@ agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code c -Code review catches issues before merge. Focus on real problems that affect correctness, security, or maintainability - not style nitpicks. Apply these criteria: -- DRY: Does it avoid duplication? -- KISS/YAGNI: Is it over-engineered? No dead code paths, no defensive programming -- No pointless wrappers: Functions that just call another function should be inlined -- Consistency: Does it match the style of surrounding code? +Code review catches issues before merge. Focus on real problems - not style nitpicks. Apply these criteria: +- Code cleanliness: Is the implementation clean and well-structured? +- DRY principle: Does it avoid duplication? +- Code reuse: Are there parts that should be reused from other places? +- Organization: Is everything in the right place? +- Consistency: Is it in the same style as other parts of the codebase? +- Simplicity: Is it over-engineered? Remember KISS and YAGNI. No dead code paths, no defensive programming. +- No pointless wrappers: Functions that just call another function should be inlined. +- User experience: Does it provide a good user experience? - Tests: Are tests meaningful or just trivial coverage? +- Live tests: Test changes with real services if applicable. +- Rules: Does the code follow CLAUDE.md guidelines? diff --git a/agent_cli/dev/skill/examples.md b/agent_cli/dev/skill/examples.md index 013ab6197..5a06a8d2c 100644 --- a/agent_cli/dev/skill/examples.md +++ b/agent_cli/dev/skill/examples.md @@ -45,12 +45,18 @@ agent-cli dev new review-changes --from HEAD --agent --prompt "Review the code c -Code review catches issues before merge. Focus on real problems that affect correctness, security, or maintainability - not style nitpicks. Apply these criteria: -- DRY: Does it avoid duplication? -- KISS/YAGNI: Is it over-engineered? No dead code paths, no defensive programming -- No pointless wrappers: Functions that just call another function should be inlined -- Consistency: Does it match the style of surrounding code? +Code review catches issues before merge. Focus on real problems - not style nitpicks. Apply these criteria: +- Code cleanliness: Is the implementation clean and well-structured? +- DRY principle: Does it avoid duplication? +- Code reuse: Are there parts that should be reused from other places? +- Organization: Is everything in the right place? +- Consistency: Is it in the same style as other parts of the codebase? +- Simplicity: Is it over-engineered? Remember KISS and YAGNI. No dead code paths, no defensive programming. +- No pointless wrappers: Functions that just call another function should be inlined. +- User experience: Does it provide a good user experience? - Tests: Are tests meaningful or just trivial coverage? +- Live tests: Test changes with real services if applicable. +- Rules: Does the code follow CLAUDE.md guidelines?