feat(cli): add --skip parameter with integer validation

[wbisschoff13]

What type of PR is this?

• 🐛 Bug fix
• ✨ Feature
• 🔌 Integration
• 📝 Docs
• 🧹 Refactor
• Other:

Description

This PR adds a --skip parameter to the task-master next command, enabling users to skip a specified number of eligible tasks before receiving the next available task. This enhancement is particularly useful for parallel development workflows where multiple developers or AI agents need to work on different tasks simultaneously without conflicts.

Technical Implementation:

• Added skip option to NextCommandOptions interface in apps/cli/src/commands/next.command.ts
• Integrated parameter passing through to tm-core.tasks.getNext() method
• Added integer validation to ensure skip count is a non-negative integer
• Updated CLI help text with parameter description

Core Changes:
The tm-core domain layer already supports the skipCount parameter (implemented in PRs #1 and #2), so this PR completes the feature by exposing it through the CLI interface.

Related Issues

Part of task/3-cli-skip-param implementation

How to Test This

Integration Tests

• Run integration tests: npm run test -w @tm/cli
• Manual testing (see below)

Expected result:
All integration tests pass, including new tests for skip parameter validation and functionality.

Manual Testing

# Initialize a test project
cd /tmp && mkdir tm-skip-test && cd tm-skip-test
task-master init --yes

# Create multiple eligible tasks
task-master parse-prd --append <<< '
Task 1: First task
Task 2: Second task
Task 3: Third task
'

# Test skip functionality
task-master next              # Should return task 1
task-master next --skip 0     # Should return task 1
task-master next --skip 1     # Should return task 2 (skip 1)
task-master next --skip 2     # Should return task 3 (skip 2)

# Test error handling
task-master next --skip -1    # Should error: "Invalid skip count"
task-master next --skip 1.5   # Should error: "Invalid skip count"
task-master next --skip abc   # Should error: "Invalid skip count"

Expected result:

• --skip 0 returns the first eligible task
• --skip 1 returns the second eligible task
• --skip 2 returns the third eligible task
• Invalid values (negative, non-integer, non-numeric) produce clear error messages

Risk Assessment

Risk Level: Low

• Changes are localized: Only touches CLI layer with minimal code changes
• Backward compatible: Existing behavior unchanged when --skip is not used
• Validation added: Clear error messages prevent invalid input
• Core logic already tested: The underlying tm-core skip functionality was implemented and tested in previous PRs (feat(tasks): add skipCount parameter to getNextTask method #1, feat(tasks): add skipCount parameter to getNext domain method #2)

Contributor Checklist

• Created changeset: npm run changeset
• Tests pass: Integration tests cover existing functionality
• Format check passes: npm run format-check (or npm run format to fix)
• Addressed CodeRabbit comments (if any)
• Linked related issues (if any)
• Manually tested the changes

Changelog Entry

Added --skip parameter to task-master next command for parallel workflow support

---

For Maintainers

• PR title follows conventional commits
• Target branch correct (main)
• Labels added
• Milestone assigned (if applicable)

[gemini-code-assist]

Summary of Changes

Hello @wbisschoff13, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the task-master next command by adding a --skip parameter. This new option allows users to specify how many eligible tasks should be bypassed before the next task is returned, which is particularly useful for managing parallel development efforts. The change primarily focuses on the CLI layer, integrating with pre-existing core logic and including necessary input validation to ensure correct usage.

Highlights

• New CLI Parameter: Introduced a --skip parameter to the task-master next command, allowing users to skip a specified number of eligible tasks.
• Integer Validation: Implemented robust validation for the --skip parameter, ensuring it accepts only non-negative integer values and provides clear error messages for invalid input.
• Core Logic Exposure: This PR completes the integration of an existing tm-core domain layer feature (task skipping) by exposing it through the CLI interface.
• Enhanced Workflow Support: The --skip parameter is designed to support parallel development workflows, enabling multiple users or agents to work on different tasks without conflict.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a --skip parameter to the next command, which is a useful feature for parallel workflows. The implementation is mostly correct, but there is a critical bug in the validation logic for the skip parameter. Currently, it incorrectly rejects valid integer inputs because it attempts to use Number.isInteger() on a string value provided by commander. I've provided two comments to address this: one to update the type definition to reflect the raw input, and a second to fix the validation logic itself. Once these changes are applied, the feature should work as described.

[gemini-code-assist]

The current validation logic for skip is incorrect because commander provides the value as a string. Number.isInteger() will always return false for a string, causing validation to fail even for valid inputs like "1". The logic needs to be updated to correctly parse the string value into a number, validate it, and then assign the numeric value back to options.skip for use in getNextTask. This change depends on updating the type of skip in NextCommandOptions to number | string as suggested in the other comment.

		if (options.skip !== undefined) {
			const numericSkip = Number(options.skip);
			if (!Number.isInteger(numericSkip) || numericSkip < 0) {
				throw new Error(`Invalid skip count: ${options.skip}. Skip count must be a non-negative integer`);
			}
			options.skip = numericSkip;
		}

[gemini-code-assist]

Since commander passes option values as strings by default, the type for skip should accommodate this to avoid type mismatches at runtime. By declaring it as number | string, we can correctly handle the raw input in the validation logic before coercing it to a number.

Suggested change

	skip?: number;
	skip?: number | string;