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