diff --git a/README.md b/README.md index da83c7c7957c568820822b2d5cb57af1922859f4..c2cf1417200179f055fece31176aa6dcf8d93533 100644 --- a/README.md +++ b/README.md @@ -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 - )" - ```