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