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