@@ -11,10 +11,6 @@ SPDX-License-Identifier: CC0-1.0
_Upgrade your coding tool's todo system_
-The software this README describes exists in the `dev` branch, but requires
-some testing and polish before I'm willing to merge it into `main` and cut a
-"real" release.
-
## Usage
This section is first to entice you with _nasin pali_'s simplicity;
@@ -31,10 +27,15 @@ requires typing six characters max.
**NOTE:** _nasin pali_ is not meant to replace your existing ticket
tracker. Keep using GitHub issues or [todo.sr.ht](https://todo.sr.ht) or
-[git-bug](https://github.com/git-bug/git-bug) or whatever else. _nasin
+[git-bug](https://github.com/git-bug/git-bug) or whatever else. _nasin
pali_ instructs your model to record the issue reference (as well as any
file references) so you can easily resume the session in a new context
-window without having to provide all the information again.
+window.
+
+**ALSO NOTE:** if your coding tool has a whole built-in planning mode, you might
+not see as big an improvement over just using that. The _biggest_ improvement
+I've seen this tool make has been with Crush, which has neither todo system nor
+planning mode (yet).
## Installation
@@ -77,7 +78,7 @@ Paste this snippet into some section of your `~/.config/AGENTS.md` or
_nasin pali_, pronounced _NAH-sin PAH-lee_ and installed as `np`, is a CLI tool
that encourages LLMs in agentic coding tools (specifically coding, I don't think
-we want to support generic workflows) to do a bit more planning before going off
+I want to support generic workflows) to do a bit more planning before going off
and making a bunch of changes. It is _both_ meant for humans and LLMs; there are
subcommands that produce output for the model and subcommands for the human to
inspect the model's progress. There's a section on [the name](#the-name) if
@@ -112,28 +113,29 @@ and relevancy, the better results you'll have. Include paths to as many files
you know will be relevant as possible. Mention particular symbols, paste
snippets of code, etc. Once your prompt looks good, send it off.
-In the `np` section of the model's rules, we'll have instructions to
-_immediately_ run start a session if the operator says to `use np` or something
-similar. Each command further in the flow reveals the next step as instructions.
-`np s` tells the model to set an overarching goal with `np g s -t title -d
-description` that captures the operator's request, combining the information
-from the ticket and any extra operator-provided context. If there's a ticket ID,
-that goes in the goal description. The output of `np g s` says to look at the
-provided references, thoroughly consider how to go about resolving the goal, and
-gather additional context from other files if necessary. Once it has a good idea
-how to resolve the goal, it should add tasks with `np t a -t title -d description`
-(single) or `np t a -t title1 -d description1 -t title2 -d description2` (batch).
-The descriptions are good places to reference files and symbols. The output of
-`np t a` tells it to update tasks as it works on them with `np t u -i task-id -s
-status` (single) or `np t u -i id1 -s status1 -i id2 -s status2` (batch).
+In the `np` section of the model's rules are instructions to _immediately_ run
+start a session if the operator says to `use np` or something similar. Each
+command further in the flow reveals the next step as instructions. `np s` tells
+the model to set an overarching goal with `np g s -t title -d description` that
+captures the operator's request, combining the information from the ticket and
+any extra operator-provided context. If there's a ticket ID, that goes in the
+goal description. The output of `np g s` says to look at the provided
+references, thoroughly consider how to go about resolving the goal, and gather
+additional context from other files if necessary. Once it has a good idea how to
+resolve the goal, it should add tasks with `np t a -t title -d description`
+(single) or `np t a -t title1 -d description1 -t title2 -d description2`
+(batch). The descriptions are good places to reference files and symbols. The
+output of `np t a` tells it to update tasks as it works on them with `np t u -i
+task-id -s status` (single) or `np t u -i id1 -s status1 -i id2 -s status2`
+(batch).
Commands that modify the model's goal or list output the full changed plan
(formatted [like so](#the-format-the-model-sees)) so it doesn't have to run
another command to check, obviating patterns like `git status` after every `git
commit`. It can use `np p` to check the plan (goal, desc, remaining tasks,
descs) and use `np t -s status` to filter to `pending`, `in progress`,
-`completed`, `all`, etc. tasks, but usually doesn't need to because we
-immediately show it after every modification.
+`completed`, `all`, etc. tasks, but usually doesn't need to because `np` shows
+them after every modification.
Resume an interrupted session in a _new_ context window by telling the model to
run `np r`. This outputs the full plan, provides relevant usage instructions,
@@ -141,8 +143,18 @@ and tells the model to "check above" for a bug/issue/ticket ID in the goal
description. If present, read that. Then read the files/symbols referenced in
the pending tasks to get a good idea of what work is left.
-Once finished, the operator or model (I'm not sure which yet, see next section)
-archives the session with `np a`.
+Once finished, archive the session with `np a`.
+
+**TIP:** I sometimes like to approximate [Amp's
+Oracle](https://ampcode.com/manual#oracle) by starting a session with GPT-5 on
+high and prompting it as I normally would, with the addition of _nasin pali_.
+After GPT-5 sets its goal and fills out the tasks, I cancel its output, start a
+new session with something like Claude Sonnet 4.5 or GLM 4.6, and tell it resume
+its session with `np r`. In effect, GPT-5 is writing up a plan for another LLM
+to execute through `np`, which mean's it's portable between agents. You could
+have, say, Codex on the OpenAI subscription make the plan that Qwen Code on
+their subscription executes, using `np` to preserve the important bits between
+agents and sessions.
## Details
@@ -154,14 +166,6 @@ session-id -t title -d description`. This is why there are `np s` and `np a`
commands for `s`tarting and `a`rchiving a session. There can only be one session
in progress per directory, so worktrees allow for parallel sessions.
-I'm unsure who should archive the session. I like the idea of requiring the
-operator to, meaning we can leave that bit out of the model's rules, but maybe
-the coding tool has no way for the operator to execute shell commands. In that
-case, they'd have to type the whole thing to the model or quit/open a new shell
-to archive themselves before the model can start a new session. Maybe telling
-the model about the archival command, but to never run it without explicit
-instruction from the operator, would be sufficient.
-
### Global database with events
Sessions, plans, goals, tasks, everything is stored in a shared
@@ -176,8 +180,8 @@ events.
### Event rendering
The interactive, human-focused sub-commands (for now, just `m` for `m`onitor),
-are for watching the events and the resulting list as they change in
-real-time-ish. The goal and description and tasks and their descriptions are
+will be for watching the events and the resulting list as they change in
+real-time-ish. The goal and description and tasks and their descriptions will be
rendered at the top of the UI and updated based on database events using some
Charm libraries. Change events are underneath the rendered state, sorted most
recent (top) to least recent (bottom).
@@ -193,7 +197,13 @@ might use more. The failed icon (`☒`) and cancelled icon (`⊗`) are only show
the legend if there are actually failed or cancelled tasks in the list.
```
-Create a comprehensive MCP server for task planning and management
+Do a slightly more complex thing than normal
+
+References:
+- Issue: 817
+- Files
+ - path/to/an/interesting.go
+ - path/to/a/templated.html
Legend: ☐ pending ⟳ in progress ☑ completed
☑ Set up project structure [a1b2c3d4]
@@ -211,17 +221,3 @@ of "method, doctrine, tradition; path, road, way" while
[_pali_](https://nimi.li/pali) covers "work, activity; create, build, design;
put effort toward, take action on". Together and in this context, _nasin pali_
could be translated as "the way of work", "the doctrine of design", etc.
-
-## Random thoughts
-
-- When providing multiple lines for the body, use
-
- ```bash
- np g s -t "Sentence case title" -d "$(cat <<'EOF'
- Multi-line
- - Body
- - Here
-
- EOF
- )"
- ```