1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# AGENTS.md
8
9This file provides guidance to AI coding agents when working with code in this repository.
10
11## Development Commands
12
13This project uses `just` for task automation. All commands should be run from the repository root.
14
15### Essential Commands
16
17- **Format code**: `just fmt` - Uses gofumpt (not standard go fmt)
18- **Lint**: `just lint` - Uses golangci-lint
19- **Static analysis**: `just staticcheck` - Uses staticcheck
20- **Run tests**: `just test` - Runs all tests with verbose output
21- **Vulnerability scan**: `just vuln` - Uses govulncheck
22- **License compliance**: `just reuse` - Checks REUSE compliance
23- **Full check**: `just` (default) - Runs all checks above in sequence
24- **Build binary**: `just build` - Produces `np` binary
25- **Run without building**: `just run <flags>` - Runs with ldflags
26
27### Running Single Tests
28
29```bash
30go test -v -run TestName ./path/to/package
31```
32
33## Project Purpose & Architecture
34
35**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.
36
37### Core Design Principles
38
391. **Working-directory scoping**: One active session per directory. Use git worktrees for parallel sessions.
402. **Token efficiency**: Uses single unicode symbols for task status (☐ ⟳ ☑ ☒ ⊗) instead of verbose markdown checkboxes or words.
413. **Immediate feedback**: Commands that modify state output the full changed plan immediately, avoiding extra commands like `git status` after every change.
424. **Event tracking**: All LLM-oriented commands are tracked with reasons in a Badger database at `$XDG_CONFIG_HOME/nasin-pali/`.
43
44### Command Structure
45
46Commands are organized using Cobra with subcommands in subdirectories:
47
48- **Root commands** (`cmd/*.go`): Session lifecycle (s, a, p, r)
49- **Goal commands** (`cmd/g/*.go`): `np g` and subcommands for goal management
50- **Task commands** (`cmd/t/*.go`): `np t` and subcommands for task management
51
52Each command is a separate file. Subcommands are in their own package/directory.
53
54### Command Reference
55
56```bash
57# Session management
58np s # Start new session
59np a # Archive current session
60np p # Check plan (goal + tasks)
61np r # Resume interrupted session
62
63# Goal management
64np g # View current goal
65np g s -t "title" -d "description" # Set goal
66
67# Task management
68np t # View all tasks
69np t -s pending # Filter by status (pending, in_progress, completed, all)
70np t a -t "title1" -d "desc1" \ # Add tasks (repeatable flags)
71 -t "title2" -d "desc2"
72np t u -i task-id -s status # Update task status
73```
74
75### Multi-line Input Pattern
76
77For multi-line descriptions/bodies, use heredoc syntax:
78
79```bash
80np g s -t "Title" -d "$(cat <<'EOF'
81Multi-line
82- Description
83- Here
84EOF
85)"
86```
87
88### Task Status Values
89
90- `pending` → ☐
91- `in_progress` → ⟳
92- `completed` → ☑
93- `failed` → ☒
94- `cancelled` → ⊗
95
96Only failed and cancelled icons appear in legend when those statuses exist in the task list.
97
98### Output Format for LLMs
99
100Commands produce token-efficient output:
101
102```
103Goal Title
104
105Legend: ☐ pending ⟳ in progress ☑ completed
106☑ Completed task [a1b2c3d4]
107 Task description with context
108⟳ Current work [e5f6g7h8]
109 More description
110☐ Pending task [i9j0k1l2]
111 References: main.go, cmd/root.go
112```
113
114## Code Style & Conventions
115
116### Go-Specific
117
118- **Formatting**: Use `gofumpt`, not standard `go fmt`
119- **Error handling**: Follow idiomatic Go patterns visible in existing code
120- **CLI framework**: Uses Cobra + Fang (charmbracelet/fang wraps Cobra execution)
121- **Module path**: `git.secluded.site/np`
122
123### Adding New Commands
124
1251. Create file in appropriate directory (`cmd/` for root commands, `cmd/g/` or `cmd/t/` for subcommands)
1262. Define cobra.Command with Use, Short, Long, and Run
1273. Register in init() or parent command
1284. Add flags using cobra's flag methods
1295. Mark required flags explicitly
1306. Stub implementation should print a clear message indicating it's a stub
131
132Example stub pattern:
133```go
134fmt.Println("[STUB] What this command will do")
135```
136
137### License Compliance
138
139All 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.
140
141```
142SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
143SPDX-License-Identifier: AGPL-3.0-or-later
144```
145
146## Implementation Status
147
148**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:
149
1501. Read the README to understand intended workflow
1512. Check cmd files to see current stub state
1523. Implement according to design principles above
1534. Maintain token-efficient output format
1545. Ensure event tracking for state changes (when implemented)
155
156## Future Features Not Yet Implemented
157
158- Badger database for event tracking
159- Interactive TUI for watching events in real-time
160- Actual session storage/retrieval
161- Task ID generation and management
162- Goal modification commands
163- Task modification beyond status updates