1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# nasin pali (the way of work)
8
9[](https://api.reuse.software/info/git.secluded.site/np)
10[](https://goreportcard.com/report/git.secluded.site/np)
11
12_Upgrade your coding tool's todo system_
13
14The software this README describes exists on the `dev` branch, but requires some
15testing and polish before I'm willing to merge it into main and cut a "real"
16release.
17
18## Usage
19
20This section is first to entice you with _nasin pali_'s simplicity; after
21installing the binary and prompt, having your coding tool using a better
22planning system just requires typing six (or fewer!) characters.
23
24- When asking the model to do something a bit more complex, just append the
25 phrase `use np`
26 - If you want the model to `use np` _all_ the time, adjust the prompt after
27 pasting to say something like _always use `np` instead of any other todo
28 tools_.
29- Once implemented, the `monitor` subcommand will show the model's plan and its
30 realtime progress and the `export` subcommand will export the rendered plan
31 and event log as Markdown. Should the model mark tasks failed/cancelled or
32 change the goal/task content, it's required to provide a reason.
33
34## Installation
35
36You need both the binary and the prompt.
37
38### The binary
39
40- Using [bin](https://github.com/marcosnils/bin) (highly recommended
41 because of centralised management/updates for statically-linked CLI tools like
42 this)
43 ```bash
44 bin install goinstall://git.secluded.site/np@latest
45 ```
46- Using the [go toolchain](https://go.dev/dl) (requires
47 tracking updates manually)
48 ```bash
49 go install git.secluded.site/np@latest
50 ```
51
52### The prompt
53
54Paste this into some section of your `~/.config/AGENTS.md` or
55`~/.claude/CLAUDE.md` or whatever titled something like `## nasin pali (the way
56of work)`.
57
58- Using `bin`
59 ```markdown
60 IMPORTANT: If I ask you to `use np` or `use nasin pali` or some variation, you must completely ignore your built-in TODO tools and exclusively use what `np` provides. Try to use it, but if it's not in my PATH, ask me to install it with `bin install goinstall://git.secluded.site/np@latest`. If I've ask you to use it, start a session with `np s` and it'll guide you from there. If I haven't asked you to use it, proceed normally.
61 ```
62- Using `go install`
63 ```markdown
64 IMPORTANT: If I ask you to `use np` or `use nasin pali` or some variation, you must completely ignore your built-in TODO tools and exclusively use what `np` provides. Try to use it, but if it's not in my PATH, ask me to install it with `go install git.secluded.site/np@latest`. If I've ask you to use it, start a session with `np s` and it'll guide you from there. If I haven't asked you to use it, proceed normally.
65 ```
66
67---
68
69## Overview
70
71_nasin pali_, pronounced _NAH-sin PAH-lee_ and installed as `np`, is a CLI tool
72that encourages LLMs in agentic coding tools (specifically coding, I don't think
73we want to support generic workflows) to do a bit more planning before going off
74and making a bunch of changes. It is _both_ meant for humans and LLMs; there are
75subcommands that produce output for the model and subcommands for the human to
76inspect the model's progress. There's a section on [the name](#the-name) if
77you're curious about it.
78
79The todo systems built into agentic coding tools are often just that: todo and
80nothing else. I think (backed by no evidence) that they do better when they can
81also set a goal. If I understand the coding tools correctly, they also have the
82LLM reproduce the entire task list with each `todo_write` invocation, which just
83seems wasteful and careless to me. What if it decides it doesn't want to do a
84task because it's "too hard" and it just omits that task next time it writes the
85list? _nasin pali_ helps force the model into a different overall flow.
86
87I previously wrote a
88[planning-mcp-server](https://git.secluded.site/planning-mcp-server) that I've
89kept some ideas from, and the overall workflow is about the same. I'm trying a
90CLI over MCP because MCP seems quite protocol-heavy for what _could_ just be a
91few simple CLI invocations. Maybe connecting arbitrary data sources warrants a
92whole protocol like MCP, but I don't think something as basic as this does. Just
93some thoughtful design and prompting.
94
95## Expected workflow
96
97_This is what I like, I'd be happy to hear of other workflows that lead to
98better/different success and to consider whether nasin pali can support them_
99
100The operator is expected to load the prompt up with relevant text. Type the
101issue in the prompt, paste the bug report, tell it how to fetch the issue from
102your issue tracker, whatever you like. If the issue content is too sparse, make
103sure to add more context. The more context you give and the higher its quality
104and relevancy, the better results you'll have. Include paths to as many files
105you know will be relevant as possible. Mention particular symbols, paste
106snippets of code, etc. Once your prompt looks good, send it off.
107
108In the `np` section of the model's rules, we'll have instructions to
109_immediately_ run start a session if the operator says to `use np` or something
110similar. Each command further in the flow reveals the next step as instructions.
111`np s` tells the model to set an overarching goal with `np g s -t title -d
112description` that captures the operator's request, combining the information
113from the ticket and any extra operator-provided context. If there's a ticket ID,
114that goes in the goal description. The output of `np g s` says to look at the
115provided references, thoroughly consider how to go about resolving the goal, and
116gather additional context from other files if necessary. Once it has a good idea
117how to resolve the goal, it should add some tasks with `np t a -t title -d
118description -t title2 -d description2`. The descriptions are good places to
119reference files and symbols. The output of `np t a` tells it to update tasks as
120it works on them with something like `np t u -i task-id -s status`.
121
122Commands that modify the model's goal or list output the full changed plan
123(formatted [like so](#the-format-the-model-sees)) so it doesn't have to run
124another command to check, obviating patterns like `git status` after every `git
125commit`. It can use `np p` to check the plan (goal, desc, remaining tasks,
126descs) and use `np t -s status` to filter to `pending`, `in progress`,
127`completed`, `all`, etc. tasks, but usually doesn't need to because we
128immediately show it after every modification.
129
130Resume an interrupted session in a _new_ context window by telling the model to
131run `np r`. This outputs the full plan, provides relevant usage instructions,
132and tells the model to "check above" for a bug/issue/ticket ID in the goal
133description. If present, read that. Then read the files/symbols referenced in
134the pending tasks to get a good idea of what work is left.
135
136Once finished, the operator or model (I'm not sure which yet, see next section)
137archives the session with `np a`.
138
139## Details
140
141### Session scoping
142
143Each session is working-directory-scoped so neither the model nor the human
144_have_ to provide a session ID or something for each invocation like `np s -s
145session-id -t title -d description`. This is why there are `np s` and `np a`
146commands for `s`tarting and `a`rchiving a session. There can only be one session
147in progress per directory, so worktrees allow for parallel sessions.
148
149I'm unsure who should archive the session. I like the idea of requiring the
150operator to, meaning we can leave that bit out of the model's rules, but maybe
151the coding tool has no way for the operator to execute shell commands. In that
152case, they'd have to type the whole thing to the model or quit/open a new shell
153to archive themselves before the model can start a new session. Maybe telling
154the model about the archival command, but to never run it without explicit
155instruction from the operator, would be sufficient.
156
157### Global database with events
158
159Sessions, plans, goals, tasks, everything is stored in a shared
160[Badger](github.com/hypermodeinc/badger) database in
161`$XDG_CONFIG_HOME/nasin-pali/`.
162
163Every LLM-oriented sub-command is tracked as an event. Sub-commands that do
164anything to modify either created tasks or set goals require a reason ("operator
165said so" is insufficiently detailed, but otherwise acceptable) to go with those
166events.
167
168### Event rendering
169
170The interactive, human-focused sub-commands (for now, just `m` for `m`onitor),
171are for watching the events and the resulting list as they change in
172real-time-ish. The goal and description and tasks and their descriptions are
173rendered at the top of the UI and updated based on database events using some
174Charm libraries. Change events are underneath the rendered state, sorted most
175recent (top) to least recent (bottom).
176
177This will probably be implemented later, once the LLM-oriented planning commands
178are solid and I see regular success with them.
179
180### The format the model sees
181
182It uses individual unicode symbols to represent task statuses. This costs one
183token per status where more verbose checkboxes `- [x]` or words `completed`
184might use more. The failed icon (`☒`) and cancelled icon (`⊗`) are only shown in
185the legend if there are actually failed or cancelled tasks in the list.
186
187```
188Create a comprehensive MCP server for task planning and management
189
190Legend: ☐ pending ⟳ in progress ☑ completed
191☑ Set up project structure [a1b2c3d4]
192 Create Go module, directories, and basic files
193⟳ Implement core planning logic [e5f6g7h8]
194 Create Goal and Task data structures with deterministic IDs
195☐ Build MCP server integration [i9j0k1l2]
196```
197
198## The name
199
200Is from [toki pona](https://tokipona.org/), _a simple language_, and pronounced
201_NAH-sin PAH-lee_. [_nasin_](https://nimi.li/nasin) occupies the semantic space
202of "method, doctrine, tradition; path, road, way" while
203[_pali_](https://nimi.li/pali) covers "work, activity; create, build, design;
204put effort toward, take action on". Together and in this context, _nasin pali_
205could be translated as "the way of work", "the doctrine of design", etc.
206
207## Random thoughts
208
209- When providing multiple lines for the body, use
210
211 ```bash
212 np g s -t "Sentence case title" -d "$(cat <<'EOF'
213 Multi-line
214 - Body
215 - Here
216
217 EOF
218 )"
219 ```