AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Development Commands

This project uses just for task automation. All commands should be run from the repository root.

Essential Commands

  • Format code: just fmt - Uses gofumpt (not standard go fmt)
  • Lint: just lint - Uses golangci-lint
  • Static analysis: just staticcheck - Uses staticcheck
  • Run tests: just test - Runs all tests with verbose output
  • Vulnerability scan: just vuln - Uses govulncheck
  • License compliance: just reuse - Checks REUSE compliance
  • Full check: just (default) - Runs all checks above in sequence
  • Build binary: just build - Produces np binary
  • Run without building: just run <flags> - Runs with ldflags

Running Single Tests

go test -v -run TestName ./path/to/package

Project Purpose & Architecture

nasin pali (installed as np) is a CLI tool that guides LLM coding agents through structured task planning workflows. It's designed to encourage planning before code changes, reducing context waste and preventing tasks from being silently dropped.

Core Design Principles

  1. Working-directory scoping: One active session per directory. Use git worktrees for parallel sessions.
  2. Token efficiency: Uses single unicode symbols for task status (☐ ⟳ ☑ ☒ ⊗) instead of verbose markdown checkboxes or words.
  3. Immediate feedback: Commands that modify state output the full changed plan immediately, avoiding extra commands like git status after every change.
  4. Event tracking: All LLM-oriented commands are tracked with reasons in a SQLite database at $XDG_CONFIG_HOME/nasin-pali/.

Command Structure

Commands are organized using Cobra with subcommands in subdirectories:

  • Root commands (cmd/*.go): Session lifecycle (s, a, p, r)
  • Goal commands (cmd/g/*.go): np g and subcommands for goal management
  • Task commands (cmd/t/*.go): np t and subcommands for task management

Each command is a separate file. Subcommands are in their own package/directory.

Command Reference

# Session management
np s                                    # Start new session
np a                                    # Archive current session
np p                                    # Check plan (goal + tasks)
np r                                    # Resume interrupted session

# Goal management
np g                                    # View current goal
np g s -t "title" -d "description"     # Set goal

# Task management
np t                                    # View all tasks
np t -s pending                         # Filter by status (pending, in_progress, completed, all)
np t a -t "title1" -d "desc1" \        # Add tasks (repeatable flags)
       -t "title2" -d "desc2"
np t u -i task-id -s status            # Update task status

Multi-line Input Pattern

For multi-line descriptions/bodies, use heredoc syntax:

np g s -t "Title" -d "$(cat <<'EOF'
Multi-line
- Description
- Here
EOF
)"

Task Status Values

  • pending → ☐
  • in_progress → ⟳
  • completed → ☑
  • failed → ☒
  • cancelled → ⊗

Only failed and cancelled icons appear in legend when those statuses exist in the task list.

Output Format for LLMs

Commands produce token-efficient output:

Goal Title

Legend: ☐ pending  ⟳ in progress  ☑ completed
☑ Completed task [a1b2c3d4]
  Task description with context
⟳ Current work [e5f6g7h8]
  More description
☐ Pending task [i9j0k1l2]
  References: main.go, cmd/root.go

Code Style & Conventions

Go-Specific

  • Formatting: Use gofumpt, not standard go fmt
  • Error handling: Follow idiomatic Go patterns visible in existing code
  • CLI framework: Uses Cobra + Fang (charmbracelet/fang wraps Cobra execution)
  • Module path: git.secluded.site/np

Adding New Commands

  1. Create file in appropriate directory (cmd/ for root commands, cmd/g/ or cmd/t/ for subcommands)
  2. Define cobra.Command with Use, Short, Long, and Run
  3. Register in init() or parent command
  4. Add flags using cobra's flag methods
  5. Mark required flags explicitly
  6. Stub implementation should print a clear message indicating it's a stub

Example stub pattern:

fmt.Println("[STUB] What this command will do")

License Compliance

All files must include SPDX license headers. Check with just reuse. All source files use AGPLv3 and all documentation, configuration, task runner config, etc. is CC0-1.0.

SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
SPDX-License-Identifier: AGPL-3.0-or-later

Implementation Status

This project is in early development. Most commands are stubs that print placeholder output. The README is intentionally aspirational, documenting the intended behavior. When implementing features:

  1. Read the README to understand intended workflow
  2. Check cmd files to see current stub state
  3. Implement according to design principles above
  4. Maintain token-efficient output format
  5. Ensure event tracking for state changes (when implemented)

Future Features Not Yet Implemented

  • SQLite database for event tracking
  • Interactive TUI for watching events in real-time
  • Actual session storage/retrieval
  • Task ID generation and management
  • Goal modification commands
  • Task modification beyond status updates