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
14## Usage
15
16This section is first to entice you with _nasin pali_'s simplicity;
17after installing [the binary](#the-binary) and [prompt](#the-prompt),
18having your coding tool use a better planning system (or any planning
19system at all if you use [Crush](https://git.secluded.site/crush)) just
20requires typing six characters max.
21
22- When asking the model to do something a bit more complex, append the
23 phrase `use np`
24 - If you want the model to `use np` _all_ the time, adjust the prompt
25 after pasting to say something like _always use `np` instead of any
26 other todo tools_.
27
28**NOTE:** _nasin pali_ is not meant to replace your existing ticket
29tracker. Keep using GitHub issues or [todo.sr.ht](https://todo.sr.ht) or
30[git-bug](https://github.com/git-bug/git-bug) or whatever else. _nasin
31pali_ instructs your model to record the issue reference (as well as any
32file references) so you can easily resume the session in a new context
33window.
34
35**ALSO NOTE:** if your coding tool has a whole built-in planning mode, you might
36not see as big an improvement over just using that. The _biggest_ improvement
37I've seen this tool make has been with Crush, which has neither todo system nor
38planning mode (yet).
39
40## Installation
41
42You need _both_ the binary and the prompt.
43
44### The binary
45
46- Using [bin](https://github.com/marcosnils/bin) (highly recommended
47 because it's one tool to manage and update myriad CLI tools
48 distributed as statically-linked binaries, like _nasin pali_)
49 ```bash
50 bin install goinstall://git.secluded.site/np@latest
51 ```
52- Using the [go toolchain](https://go.dev/dl) (requires tracking updates
53 manually)
54 ```bash
55 go install git.secluded.site/np@latest
56 ```
57
58### The prompt
59
60Paste this snippet into some section of your `~/.config/AGENTS.md` or
61`~/.claude/CLAUDE.md` or whatever titled something like `## nasin pali
62(the way of work)`.
63
64> IMPORTANT: If I ask you to `use np` or `use nasin pali` or some variation, you
65> must completely ignore your built-in TODO tools and follow _nasin pali_ by
66> immediately running the appropriate `np` subcommand and adhering its
67> instructions. If I've asked you to use it, start a session by running `np s`.
68> If I've explicitly asked you to resume, use `np r`. _Ask_ me whether to
69> archive when you're done; do NOT do it on your own. If I haven't asked you to
70> follow _nasin pali_, prefer your built-in tools, if any, and proceed normally.
71
72## Changelog
73
74See [CHANGELOG.md](CHANGELOG.md) for release notes and version history.
75(Maintained by [kittylog](https://github.com/cellwebb/kittylog))
76
77---
78
79## Overview
80
81_nasin pali_, pronounced _NAH-sin PAH-lee_ and installed as `np`, is a CLI tool
82that encourages LLMs in agentic coding tools (specifically coding, I don't think
83I want to support generic workflows) to do a bit more planning before going off
84and making a bunch of changes. It is _both_ meant for humans and LLMs; there are
85subcommands that produce output for the model and subcommands for the human to
86inspect the model's progress. There's a section on [the name](#the-name) if
87you're curious about it.
88
89The todo systems built into agentic coding tools are often just that: todo and
90nothing else. I think (backed by no evidence) that they do better when they can
91also set a goal. If I understand the coding tools correctly, they also have the
92LLM reproduce the entire task list with each `todo_write` invocation, which just
93seems wasteful and careless to me. What if it decides it doesn't want to do a
94task because it's "too hard" and it just omits that task next time it writes the
95list? _nasin pali_ helps force the model into a different overall flow.
96
97I previously wrote a
98[planning-mcp-server](https://git.secluded.site/planning-mcp-server) that I've
99kept some ideas from, and the overall workflow is about the same. I'm trying a
100CLI over MCP because MCP seems quite protocol-heavy for what _could_ just be a
101few simple CLI invocations. Maybe connecting arbitrary data sources warrants a
102whole protocol like MCP, but I don't think something as basic as this does. Just
103some thoughtful design and prompting.
104
105## Expected workflow
106
107_This is what I like, I'd be happy to hear of other workflows that lead to
108better/different success and to consider whether nasin pali can support them_
109
110The operator is expected to load the prompt up with relevant text. Type the
111issue in the prompt, paste the bug report, tell it how to fetch the issue from
112your issue tracker, whatever you like. If the issue content is too sparse, make
113sure to add more context. The more context you give and the higher its quality
114and relevancy, the better results you'll have. Include paths to as many files
115you know will be relevant as possible. Mention particular symbols, paste
116snippets of code, etc. Once your prompt looks good, send it off.
117
118In the `np` section of the model's rules are instructions to _immediately_ run
119start a session if the operator says to `use np` or something similar. Each
120command further in the flow reveals the next step as instructions. `np s` tells
121the model to set an overarching goal with `np g s -t title -d description` that
122captures the operator's request, combining the information from the ticket and
123any extra operator-provided context. If there's a ticket ID, that goes in the
124goal description. The output of `np g s` says to look at the provided
125references, thoroughly consider how to go about resolving the goal, and gather
126additional context from other files if necessary. Once it has a good idea how to
127resolve the goal, it should add tasks with `np t a -t title -d description`
128(single) or `np t a -t title1 -d description1 -t title2 -d description2`
129(batch). The descriptions are good places to reference files and symbols. The
130output of `np t a` tells it to update tasks as it works on them with `np t u -i
131task-id -s status` (single) or `np t u -i id1 -s status1 -i id2 -s status2`
132(batch).
133
134Commands that modify the model's goal or list output the full changed plan
135(formatted [like so](#the-format-the-model-sees)) so it doesn't have to run
136another command to check, obviating patterns like `git status` after every `git
137commit`. It can use `np p` to check the plan (goal, desc, remaining tasks,
138descs) and use `np t -s status` to filter to `pending`, `in progress`,
139`completed`, `all`, etc. tasks, but usually doesn't need to because `np` shows
140them after every modification.
141
142Resume an interrupted session in a _new_ context window by telling the model to
143run `np r`. This outputs the full plan, provides relevant usage instructions,
144and tells the model to "check above" for a bug/issue/ticket ID in the goal
145description. If present, read that. Then read the files/symbols referenced in
146the pending tasks to get a good idea of what work is left.
147
148Once finished, archive the session with `np a`.
149
150**TIP:** I sometimes like to approximate [Amp's
151Oracle](https://ampcode.com/manual#oracle) by starting a session with GPT-5 on
152high and prompting it as I normally would, with the addition of _nasin pali_.
153After GPT-5 sets its goal and fills out the tasks, I cancel its output, start a
154new session with something like Claude Sonnet 4.5 or GLM 4.6, and tell it resume
155its session with `np r`. In effect, GPT-5 is writing up a plan for another LLM
156to execute through `np`, which mean's it's portable between agents. You could
157have, say, Codex on the OpenAI subscription make the plan that Qwen Code on
158their subscription executes, using `np` to preserve the important bits between
159agents and sessions.
160
161## Details
162
163### Session scoping
164
165Each session is working-directory-scoped so neither the model nor the human
166_have_ to provide a session ID or something for each invocation like `np s -s
167session-id -t title -d description`. This is why there are `np s` and `np a`
168commands for `s`tarting and `a`rchiving a session. There can only be one session
169in progress per directory, so worktrees allow for parallel sessions.
170
171### Global database with events
172
173Sessions, plans, goals, tasks, everything is stored in a shared
174[Badger](https://github.com/hypermodeinc/badger) database in
175`$XDG_CONFIG_HOME/nasin-pali/data/`.
176
177Every LLM-oriented sub-command is tracked as an event. Sub-commands that do
178anything to modify either created tasks or set goals require a reason ("operator
179said so" is insufficiently detailed, but otherwise acceptable) to go with those
180events.
181
182### Event rendering
183
184The interactive, human-focused sub-commands (for now, just `m` for `m`onitor),
185will be for watching the events and the resulting list as they change in
186real-time-ish. The goal and description and tasks and their descriptions will be
187rendered at the top of the UI and updated based on database events using some
188Charm libraries. Change events are underneath the rendered state, sorted most
189recent (top) to least recent (bottom).
190
191This will probably be implemented later, once the LLM-oriented planning commands
192are solid and I see regular success with them.
193
194### The format the model sees
195
196It uses individual unicode symbols to represent task statuses. This costs one
197token per status where more verbose checkboxes `- [x]` or words `completed`
198might use more. The failed icon (`☒`) and cancelled icon (`⊗`) are only shown in
199the legend if there are actually failed or cancelled tasks in the list.
200
201```
202Do a slightly more complex thing than normal
203
204References:
205- Issue: 817
206- Files
207 - path/to/an/interesting.go
208 - path/to/a/templated.html
209
210Legend: ☐ pending ⟳ in progress ☑ completed
211☑ Set up project structure [a1b2c3d4]
212 Create Go module, directories, and basic files
213⟳ Implement core planning logic [e5f6g7h8]
214 Create Goal and Task data structures with deterministic IDs
215☐ Build MCP server integration [i9j0k1l2]
216```
217
218## The name
219
220Is from [toki pona](https://tokipona.org/), _a simple language_, and pronounced
221_NAH-sin PAH-lee_. [_nasin_](https://nimi.li/nasin) occupies the semantic space
222of "method, doctrine, tradition; path, road, way" while
223[_pali_](https://nimi.li/pali) covers "work, activity; create, build, design;
224put effort toward, take action on". Together and in this context, _nasin pali_
225could be translated as "the way of work", "the doctrine of design", etc.
226
227---
228
229Some other tools if this one interested you
230
231- [formatted-commit](https://git.secluded.site/formatted-commit) - CLI that turns LLM input into well-formatted Conventional Commits
232- [AgentSh](https://git.secluded.site/agentsh) - press `Ctrl+X` from any shell prompt to message your agent (Crush, Claude Code, etc.)