sknext 0.1.0

Task status viewer for speckit projects

sknext

Task status viewer for speckit projects - a CLI tool to quickly view and track tasks from your project's tasks.md file.

Features

• 🚀 Fast: View next tasks in <2 seconds
• 🔍 Multiple Views: 6 different viewing modes for different workflows
• 📊 Auto-Discovery: Automatically finds latest tasks.md in specs/###-*/ directories
• 🎨 Rich Formatting: Color-coded output with priority and story tag highlighting
• ✅ Type Safe: 100% type-checked with mypy in strict mode
• 🧪 Well Tested: 97 tests with 94% coverage

Installation

From PyPI (Recommended)

Once published, install directly from PyPI:

pip install sknext

Or with uv:

uv pip install sknext

From Source

For development or to use the latest unreleased version:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/kenhia/sknext.git
cd sknext
uv sync

Usage

Auto-Discovery from Any Directory

sknext automatically detects your project's repository root and finds the latest tasks.md file:

# Run from any subdirectory in your project
cd src/mymodule
sknext

# Run from repository root
cd /path/to/project
sknext

# Run from a feature subdirectory
cd specs/001-my-feature
sknext

How it works:

1. Git Detection: Uses git rev-parse --show-toplevel to find repository root (fastest)
2. VCS Markers: Falls back to searching for .git, .hg, or .svn directories (up to 10 levels)
3. Specs Fallback: If no VCS found, searches for specs/ directory (for non-git projects)
4. Latest Discovery: Finds the highest numbered specs/###-*/tasks.md file

This means you can work deep in your codebase and quickly check task status without navigating to the project root!

Quick Status Check (Default)

Show the next 10 uncompleted tasks with full context:

sknext
# or
sknext path/to/tasks.md

Custom Task Count

Show a specific number of tasks:

sknext -n 5          # Show next 5 tasks
sknext -n 25         # Show next 25 tasks
sknext -n 0          # Show header only (no tasks)

Phase Overview

Show only phases with uncompleted work (no sections or tasks):

sknext --phases-only

Perfect for quick status updates or understanding high-level progress.

Structure View

Show phases and sections with uncompleted work (no individual tasks):

sknext --structure

Useful for sprint planning and understanding work distribution across sections.

Combined View

Show all incomplete phases followed by N tasks:

sknext --all-phases -n 10

Combines strategic overview with tactical next steps - perfect for standups!

Task-Only View

Show only task lines without any headings:

sknext --tasks-only -n 15

Great for copy-pasting into status reports or automated processing.

All Remaining Tasks

Show every uncompleted task with full context:

sknext --all

Perfect for final sprint planning or comprehensive project reviews.

Troubleshooting

No tasks.md found

If you get "Error: No Git repository or speckit project detected":

1. Run from within a project: Make sure you're inside a git repository or directory with a specs/ folder
2. Check your location: sknext searches up to 10 parent directories for repository markers
3. Verify project structure: Ensure you have either:
   • A .git directory (git repository)
   • A specs/###-feature-name/tasks.md file structure
4. Explicit path: You can always specify the path directly: sknext path/to/tasks.md

Project Detection

sknext uses a three-tier approach to find your project:

1. Git command (git rev-parse --show-toplevel) - preferred method
2. VCS markers (.git, .hg, .svn directories) - works in nested repos
3. Specs directory - fallback for non-git projects with specs/ folder

Empty output

If sknext shows no tasks:

• ✅ All your tasks are complete! Great job!
• Check if tasks are marked with - [X] instead of - [ ]

Performance issues

If sknext is slow:

• Check file size - files with >1000 tasks may take longer
• Expected: <2s for default view, <3s for files with 500 tasks
• Auto-discovery adds <200ms overhead for repository detection
• Report performance issues with file size and timing

Development

Setup Development Environment

# Clone and setup
git clone <repository-url>
cd sknext
uv sync

# Install pre-commit hooks (optional)
uv run pre-commit install

Run Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/sknext --cov-report=html

# Run specific test
uv run pytest tests/unit/test_parser.py -xvs

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type check
uv run mypy src/sknext

Architecture

src/sknext/
├── __init__.py       # Package initialization
├── __main__.py       # Entry point for python -m sknext
├── cli.py            # Typer CLI interface
├── constants.py      # Regex patterns and defaults
├── models.py         # Frozen dataclasses (Task, Section, Phase)
├── parser.py         # Line-by-line state machine parser
├── discovery.py      # Auto-discover tasks.md in specs/
└── formatter.py      # Rich console output formatters

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass and coverage stays >90%
5. Run ruff format and mypy
6. Submit a pull request

License

[Add your license here]

uv run ruff check --fix .

Type Check

uv run mypy src/

License

MIT