From 5082fee4c595c7db96b13a2fa1ef9b7b14b288f2 Mon Sep 17 00:00:00 2001 From: Amolith Date: Wed, 22 Oct 2025 12:42:56 -0600 Subject: [PATCH] docs: moar elaboration --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 52 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 3e417e0235022521561b3c1e09303b615f4cfd59..e5e886cb01b273bb4363657ef9220472d0a8521a 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ my ideas down. --- +## Overview + _nasin pali_, 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 and making a bunch of @@ -22,26 +24,38 @@ also set a goal. If I understand the coding tools correctly, they also have the LLM reproduce the entire task list with each `todo_write` invocation, which just seems wasteful and careless to me. What if it decides it doesn't want to do a task because it's "too hard" and it just omits that task next time it writes the -list? _nasin pali_ helps force the model into a different flow. +list? _nasin pali_ helps force the model into a different overall flow. -- Start a new session with `np s` . It adds details to the global sqlite - database and produces output to guide the LLM through its next steps. Instead - of telling the model up-front about everything it can do with _nasin pali_ - though AGENTS.md or tool definitions or something, we only reveal the - sub-commands and flags it might actually need once it needs them. It shouldn't - ever use the interactive commands, so we never tell them model about them. +## Expected workflow - - There can be one active session per working directory and the previous - session must be archived before starting a new one. This is so the model - doesn't have to provide a session ID or something for each invocation. +_This is what I like, I'd be happy to hear of other workflows that lead to +better/different success and to consider whether nasin-pali can support them_ -- `np s` tells the model about the goal and task sub-commands and their flags - and to begin the session by turning the user's request, bug report, issue - contents, spec, etc. into a concise overarching goal with a thorough - description -- `np g s` accepts title and description arguments and tells the model to, if - necessary, look around at additional relevant files before adding some tasks - with `np t a` +The operator is expected to load the prompt up with relevant text. Type the +issue in the prompt, paste the bug report, tell it how to fetch the issue from +your issue tracker, whatever you like. If the issue content is too sparse, make +sure to add more context. The more context you give and the higher its quality +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_ 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. It should then go off and look at the +provided references and thoroughly consider how to go about resolving the goal. +After gathering that context, it adds tasks with `np t a -t title -d description +-t title2 -d description2` and gets started on them. + +I'm unsure how to handle session archival (mentioned in [random +thoughts](#random-thoughts)). We could tell the model how to archive sessions in +the rules, but I don't know that the model even needs to know about sessions; +maybe archival should require human interaction. If the model can't archive +sessions, and the agentic coding tool doesn't have a way for the operator to +execute shell commands, they'd have to quit or open a new shell to run that +command before the model can create a new one session. Maybe telling it about +the archival command, but to never run it without operator interaction, would be +sufficient. ## The name @@ -64,3 +78,24 @@ could be translated as "the way of work", "the doctrine of design", etc. EOF )" ``` + +- I like the way + [planning-mcp-server](https://git.secluded.site/planning-mcp-server#tracking-progress) + renders the task list in unicode characters. `☑` is one token while `- [x]` is + probably like five. +- Start a new session with `np s`. It adds details to the global sqlite database + and produces output to guide the LLM through its next steps. Instead of + telling the model up-front about everything it can do with _nasin pali_ though + AGENTS.md or tool definitions or something, we only reveal the sub-commands + and flags it might actually need once it needs them. It shouldn't ever use the + interactive commands, so we never tell them model about them. + - There can be one active session per working directory and the previous + session must be archived before starting a new one. This is so the model + doesn't have to provide a session ID or something for each invocation. +- `np s` tells the model about the goal and task sub-commands and their flags + and to begin the session by turning the user's request, bug report, issue + contents, spec, etc. into a concise overarching goal with a thorough + description +- `np g s` accepts title and description arguments and tells the model to, if + necessary, look around at additional relevant files before adding some tasks + with `np t a`. Would something like this work?