sknext 0.1.1
Task status viewer for speckit projects
License: MIT
Requires Python: >=3.11
Keywords: task, project-management, cli, speckit, development-tools

# 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:

```bash
pip install sknext
```

Or with uv:

```bash
uv pip install sknext
```

### From Source

For development or to use the latest unreleased version:

```bash
# 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:

```bash
# 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:

```bash
sknext
# or
sknext path/to/tasks.md
```

### Custom Task Count

Show a specific number of tasks:

```bash
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):

```bash
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):

```bash
sknext --structure
```

Useful for sprint planning and understanding work distribution across sections.

### Combined View

Show all incomplete phases followed by N tasks:

```bash
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:

```bash
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:

```bash
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

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

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

### Run Tests

```bash
# 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

```bash
# 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]

```bash
uv run ruff check --fix .
```

### Type Check

```bash
uv run mypy src/
```

## License

MIT