@sov3rain/nota 0.1.0 → 0.2.1

package/README.md

@@ -1,52 +1,55 @@
-# nota
-
-A local annotation tool for AI agent implementation plans.
-
-`nota` opens a Markdown plan in a browser-based editor where you can highlight text and leave comments using [CriticMarkup](https://github.com/CriticMarkup/CriticMarkup-toolkit). The agent reads those comments back and adjusts the plan or implementation accordingly.
-
-## Install
-
-```bash
-npm install -g nota
-```
-
-## Usage
-
-### Annotate a plan
-
-```bash
-nota path/to/plan.md
-```
-
-Opens the file in a local web UI. Highlight any text to leave a comment. When you're done, click **Done** — the agent reads the annotated file and processes your feedback.
-
-Pass `--no-open` to start the server without opening the browser automatically:
-
-```bash
-nota --no-open path/to/plan.md
-```
-
-### Set up agent instructions
-
-```bash
-nota init          # all agents (Claude, Codex, Cursor)
-nota init claude   # Claude only
-nota init codex    # Codex only
-nota init cursor   # Cursor only
-```
-
-Writes the annotation workflow instructions into `CLAUDE.md`, `AGENTS.md`, or `.cursor/rules/nota.mdc`. Safe to re-run — existing files are updated in place, not overwritten.
-
-## How it works
-
-1. The agent creates a plan as `.agent-plans/<date>-<topic>.md` and runs `nota` on it
-2. You annotate the plan in the browser
-3. Feedback is stored as CriticMarkup inline in the file:
-   ```
-   {==highlighted text==}{>>your comment<<}
-   ```
-4. The agent reads the annotations and updates the plan or proceeds with implementation
-
-## License
-
-MIT
+# nota
+
+A local annotation tool for AI agent implementation plans.
+
+`nota` opens a Markdown plan in a browser-based editor where you can highlight text and leave comments using [CriticMarkup](https://github.com/CriticMarkup/CriticMarkup-toolkit). The agent reads those comments back and adjusts the plan or implementation accordingly.
+
+## Install
+
+```bash
+npm install -g nota
+```
+
+## Usage
+
+### Annotate a plan
+
+```bash
+nota path/to/plan.md
+```
+
+Opens the file in a local web UI. Highlight any text to leave a comment. When you're done, click **Done** — the agent reads the annotated file and processes your feedback.
+
+Pass `--no-open` to start the server without opening the browser automatically:
+
+```bash
+nota --no-open path/to/plan.md
+```
+
+### Set up agent instructions
+
+```bash
+nota init          # choose agents interactively
+nota init all      # all agents, non-interactive
+nota init claude   # Claude only
+nota init codex    # Codex only
+nota init cursor   # Cursor only
+```
+
+The interactive mode starts with no agents selected, so you explicitly choose the agent instructions to install.
+
+Writes the annotation workflow instructions into `CLAUDE.md`, `AGENTS.md`, or `.cursor/rules/nota.mdc`. Safe to re-run — existing files are updated in place, not overwritten.
+
+## How it works
+
+1. The agent creates a plan as `.agent-plans/<date>-<topic>.md` and runs `nota` on it
+2. You annotate the plan in the browser
+3. Feedback is stored as CriticMarkup inline in the file:
+   ```
+   {==highlighted text==}{>>your comment<<}
+   ```
+4. The agent reads the annotations and updates the plan or proceeds with implementation
+
+## License
+
+MIT

package/bin/agentInstructions.mjs

@@ -0,0 +1,60 @@
+export function getAgentInstructionBlock() {
+  return `<!-- nota:start -->
+## Plan Annotation Workflow
+
+When the user asks for an implementation plan, create a Markdown file in:
+
+\`\`\`text
+.agent-plans/<linux-epoch-seconds>-<topic>.md
+\`\`\`
+
+The filename must start with the current Unix epoch timestamp in seconds, not a formatted date.
+
+If you are running in a planning-only mode, read-only mode, or any mode where you cannot create files and keep a local command attached until it exits, do not attempt this workflow. Tell the user that the nota annotation workflow cannot run in the current mode, and ask them to switch to a mode that allows file writes and command execution.
+
+Then launch the local annotation tool and wait for the command to exit.
+
+On Windows/PowerShell, use the npm \`.cmd\` shim explicitly:
+
+\`\`\`powershell
+nota.cmd .agent-plans/<file>.md
+\`\`\`
+
+Run this command with a 60-minute timeout so the first Nota session has enough time to stay open while the user annotates.
+
+Do not use \`Start-Process -FilePath nota\` on Windows/PowerShell; it can resolve to the extensionless npm shim and trigger the Windows "open with" dialog instead of running the CLI.
+
+On macOS/Linux:
+
+\`\`\`bash
+nota .agent-plans/<file>.md
+\`\`\`
+
+Tell the user that the plan is open for annotation. Keep the command attached and do not continue with implementation until the \`nota\` process exits.
+
+When the \`nota\` process exits, treat that as the signal that the user has finished annotating. Read the same Markdown file again. User feedback is stored as CriticMarkup:
+
+\`\`\`md
+{==text being discussed==}{>>user comment<<}
+\`\`\`
+
+Treat those comments as direct user feedback. Update the plan or implementation accordingly.
+
+Once all annotations have been processed, remove every CriticMarkup annotation from the file, as well as the global annotations block if present:
+
+\`\`\`md
+<!-- nota:globals
+[...]
+-->
+\`\`\`
+
+Leave only the plain Markdown content.
+
+If the \`nota\` command is unavailable, tell the user to install it globally:
+
+\`\`\`bash
+npm install -g nota
+\`\`\`
+<!-- nota:end -->
+`;
+}

package/bin/agentInstructions.test.mjs

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { getAgentInstructionBlock } from './agentInstructions.mjs';
+
+describe('getAgentInstructionBlock', () => {
+  it('instructs agents to wait for the nota process to exit', () => {
+    const block = getAgentInstructionBlock();
+
+    expect(block).toContain('wait for the command to exit');
+    expect(block).toContain('do not continue with implementation until the `nota` process exits');
+    expect(block).toContain('When the `nota` process exits');
+    expect(block).not.toContain('until the user says they are done annotating');
+  });
+
+  it('keeps the Windows npm shim guidance', () => {
+    const block = getAgentInstructionBlock();
+
+    expect(block).toContain('nota.cmd .agent-plans/<file>.md');
+    expect(block).toContain('Run this command with a 60-minute timeout');
+    expect(block).toContain('Do not use `Start-Process -FilePath nota`');
+  });
+});