@@ -47,22 +47,73 @@ 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 `np s`, which outputs some LLM-oriented instructions for use.
-It first 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. Then it should 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.
-
-As it works through the tasks, it's expected to update statuses by ID with
-something like `np t u -i id -s status`. Commands that modify the model's plan
-output the revision so it can immediately see the result of its invocation
-without running another command (obviating patterns like running `git status`
-after every `git commit`). Format the list something like this, using individual
-unicode symbols to represent task statuses using one token per status instead of
-more verbose checkboxes `- [x]` or words `completed` that might use more tokens.
-The failed icon (`☒`) and cancelled icon (`⊗`) are only shown in the legend if
-there are actually failed or cancelled tasks in the list.
+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. 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 some tasks with `np t a -t title -d
+description -t title2 -d description2`. The descriptions are good places to
+references files and symbols. The output of `np t a` tells it to update tasks as
+it works on them with something like `np t u -i task-id -s status`.
+
+Commands that modify the model's goal or list output the full changed plan
+(formatted [like so](#the-format)) 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.
+
+Resume an interrupted session in a new context window by typing your own
+instructions on what to do next _and_ telling the model to run `np r`. This
+outputs the full plan, provides relevant usage instructions, and tells the model
+to 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`.
+
+## Details
+
+### Session scoping
+
+Each session is working-directory-scoped so neither the model nor the human
+_have_ to provide a session ID or something for each invocation like `np s -s
+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.
+
+### Event tracking
+
+Every LLM-oriented sub-command is tracked as an event in a global SQLite
+database in `$XDG_CONFIG_HOME/nasin-pona/`. Sub-commands that do anything to
+modify either created tasks or set goals require a reason ("operator said so" is
+insufficiently detailed, but otherwise acceptable).
+
+### Event rendering
+
+The interactive, human-focused sub-commands are for watching these events and
+the resulting list as they change in real-time-ish. The goal and description and
+tasks and their descriptions are 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).
+
+### The format the model sees
+
+It uses individual unicode symbols to represent task statuses. This costs one
+token per status where more verbose checkboxes `- [x]` or words `completed`
+might use more. The failed icon (`☒`) and cancelled icon (`⊗`) are only shown in
+the legend if there are actually failed or cancelled tasks in the list.
```
Create a comprehensive MCP server for task planning and management
@@ -75,33 +126,6 @@ Legend: ☐ pending ⟳ in progress ☑ completed
☐ Build MCP server integration [i9j0k1l2]
```
-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 session. Maybe telling it about the
-archival command, but to never run it without operator interaction, would be
-sufficient.
-
-Every LLM-oriented sub-command is tracked as an event in a global SQLite
-database in `$XDG_CONFIG_HOME/nasin-pona/`. Sub-commands that do anything to
-modify either created tasks or set goals require a reason ("operator said so" is
-insufficiently detailed, but otherwise acceptable).
-
-The interactive, human-focused sub-commands are for watching these events and
-the resulting list as they change in realtime, and for exporting a session with
-all of its events as Markdown. The goal and description and tasks and their
-descriptions are 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).
-
-Each session is working-directory-scoped so the model doesn't have to provide a
-session ID or something for each invocation. This is why there are `np s` and
-`np a` commands for `s`tarting and `a`rchiving a session. Worktrees allow for
-parallel sessions.
-
## The name
Is [toki pona](https://tokipona.org/). [_nasin_](https://nimi.li/nasin) occupies
@@ -115,7 +139,7 @@ could be translated as "the way of work", "the doctrine of design", etc.
- When providing multiple lines for the body, use
```bash
- np goal set "Sentence case title" "$(cat <<'EOF'
+ np g s -t "Sentence case title" -d "$(cat <<'EOF'
Multi-line
- Body
- Here
@@ -123,27 +147,3 @@ could be translated as "the way of work", "the doctrine of design", etc.
EOF
)"
```
-
-- 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`. <mark>How to provide/require/validate for pairs of -t and -d
- flags?</mark>
-- Have the model update task statuses by ID and render the goal, the updated
- task, and the _remaining_ tasks in the same format as planning-mcp-server. By
- default, `planning-mcp-server` returned all tasks, but I think it would be
- better to just return the modified one, so the model can see its previous
- command worked, and the still-open ones. Include a flag or something so it can
- look at all tasks including the completed ones.