pi-goals 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +111 -13
  2. package/package.json +8 -2
package/README.md CHANGED
@@ -1,42 +1,140 @@
1
1
  # pi-goals
2
2
 
3
- Persistent goal tracking for [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent), inspired by Codex CLI's `/goal` workflow.
3
+ Persistent goal tracking for [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). Inspired by Codex CLI's `/goal`, `pi-goals` adds Pi-native UX, rewindable `/tree`-compatible goal state, time and token budgets, reusable token-aware prompts, automated churn monitoring, and more.
4
4
 
5
- > Early preview: this package is being prepared for open-source release. APIs and install ergonomics may change before `1.0.0`.
5
+ > Early preview: `pi-goals` is usable, but install ergonomics and APIs may change before `1.0.0`.
6
6
 
7
- ## What it provides
7
+ ## Features
8
8
 
9
9
  - `/goal` command for creating, pausing, resuming, replacing, and clearing a persistent objective.
10
- - Goal state persisted into the Pi session branch.
11
- - Goal-aware runtime continuation and monitoring hooks.
10
+ - Rewindable `/tree`-compatible state persisted into the Pi session branch.
11
+ - Time and token budgets with goal-aware continuation behavior.
12
+ - Reusable token-aware prompt templates from `.pi-goals/` directories.
12
13
  - Model tools for inspecting and updating the active goal.
13
- - Compact Pi UI status/widget integration.
14
+ - Automated churn monitoring and steering for long-running goals.
15
+ - Compact Pi status/widget integration.
14
16
 
15
17
  ## Install
16
18
 
19
+ Install globally for your Pi environment:
20
+
21
+ ```bash
22
+ pi install npm:pi-goals
23
+ ```
24
+
25
+ Install project-locally:
26
+
17
27
  ```bash
18
- npm install pi-goals
28
+ pi install -l npm:pi-goals
29
+ ```
30
+
31
+ ## `/goal` command
32
+
33
+ Use `/goal` to create and manage a persistent objective that survives across turns and is persisted into the Pi branch so `/tree` rewind/replay semantics stay coherent.
34
+
35
+ ```text
36
+ /goal
37
+ /goal <objective>
38
+ /goal pause
39
+ /goal resume
40
+ /goal clear
41
+ ```
42
+
43
+ Subcommands:
44
+
45
+ - `/goal` — show the current goal summary, status, budgets, and progress metadata.
46
+ - `/goal <objective>` — create a new active goal. If a goal already exists, Pi asks before replacing it.
47
+ - `/goal pause` — pause continuation and churn monitoring. If a goal-driven turn is active, Pi interrupts it.
48
+ - `/goal resume` — resume a paused goal and schedule continuation/monitoring again.
49
+ - `/goal clear` — remove the current goal from active state.
50
+
51
+ The extension also exposes model tools so agents can inspect, create, update, pause, resume, complete, or clear goals without string-parsing the slash command.
52
+
53
+ ## Natural language goal management
54
+
55
+ You do not have to use explicit `/goal` commands for every operation. Because `pi-goals` exposes goal management as Pi model tools, the Pi agent can manage goals from ordinary natural language instructions.
56
+
57
+ Examples:
58
+
59
+ ```text
60
+ Keep working toward shipping this release, but pause the persistent goal while I answer email.
61
+ ```
62
+
63
+ ```text
64
+ Set a goal to finish the README cleanup with a 30 minute budget, then keep going until it is done or blocked.
65
+ ```
66
+
67
+ ```text
68
+ Mark the current goal complete and summarize what changed.
19
69
  ```
20
70
 
21
- ## Use with Pi
71
+ Use `/goal` when you want direct command control; use natural language when you want the agent to decide the right goal operation in context.
72
+
73
+ ## Reusable `.pi-goals` prompts
22
74
 
23
- The extension entrypoint is published as TypeScript source at:
75
+ `pi-goals` can turn project prompt templates into reusable goal objectives. Put Markdown, `.markdown`, or `.txt` templates under any `.pi-goals/` directory in your workspace:
24
76
 
25
77
  ```text
26
- .pi/extensions/goal/index.ts
78
+ .pi-goals/
79
+ fix-issue.md
80
+ release/checklist.md
27
81
  ```
28
82
 
29
- Until a packaged loader is finalized, copy or reference the extension directory from `node_modules/pi-goals/.pi/extensions/goal` in your Pi setup.
83
+ Then invoke a template by name through `/goal`:
30
84
 
31
- For local validation:
85
+ ```text
86
+ /goal fix-issue --issue ISSUE-123 -- verify the fix and update docs
87
+ /goal release/checklist --version 0.1.1
88
+ ```
89
+
90
+ Templates support simple frontmatter:
91
+
92
+ ```markdown
93
+ ---
94
+ description: Fix an issue using the repo workflow
95
+ aliases: fix, issue
96
+ allow_commands: false
97
+ ---
98
+ Fix {{issue}}.
99
+
100
+ Extra context: {{args}}
101
+ ```
102
+
103
+ Template features:
104
+
105
+ - `{{name}}` placeholders resolve from `--name value` or `--name=value` flags.
106
+ - `{{args}}` resolves to text after ` -- `.
107
+ - `description` appears in command completion.
108
+ - `aliases` provide alternate invocation names.
109
+ - Inline shell snippets with ``!`command` `` are supported only when `allow_commands: true`; commands are bounded by timeout and output limits.
110
+
111
+ ## Automated churn monitor
112
+
113
+ Long-running goals can drift, loop, or stall. `pi-goals` runs a lightweight goal-scoped churn monitor that periodically reviews sparse session context, recent goal telemetry, and recent monitor decisions.
114
+
115
+ The monitor can:
116
+
117
+ - detect no-progress loops and repeated automatic turns,
118
+ - steer the worker back toward the objective,
119
+ - escalate when a safety pause is needed,
120
+ - keep its own bounded churn log in the Pi branch.
121
+
122
+ Monitor state is goal-scoped and replayable, so branching and `/tree` operations stay aligned with the active goal history.
123
+
124
+ ## Development
32
125
 
33
126
  ```bash
127
+ npm install
34
128
  npm run quality:goal
35
129
  ```
36
130
 
131
+ `npm run quality:goal` runs the project quality gate for the extension, including [Sentrux](https://github.com/sentrux/sentrux) structure checks, TypeScript validation, and Pi extension load validation.
132
+
133
+ Development quality checks require the `sentrux` CLI to be available on `PATH`.
134
+
37
135
  ## Status
38
136
 
39
- This is an early release intended to claim the public package name and make the current implementation available for collaborators and early testers.
137
+ This is an early public preview intended for collaborators and early testers. Expect rough edges and breaking changes before `1.0.0`.
40
138
 
41
139
  ## License
42
140
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-goals",
3
- "version": "0.1.0",
4
- "description": "Persistent goal tracking extension for Pi, inspired by Codex CLI /goal.",
3
+ "version": "0.1.1",
4
+ "description": "Persistent goal tracking for Pi with /tree-compatible state, budgets, reusable prompts, and churn monitoring.",
5
5
  "main": ".pi/extensions/goal/index.ts",
6
6
  "files": [
7
7
  ".pi/extensions/goal/*.ts",
@@ -20,6 +20,7 @@
20
20
  "keywords": [
21
21
  "pi",
22
22
  "pi-extension",
23
+ "pi-package",
23
24
  "agent",
24
25
  "goal",
25
26
  "coding-agent"
@@ -27,6 +28,11 @@
27
28
  "author": "Bryan Price-McConnahea (@slopwareindy // withbryan.work)",
28
29
  "license": "MIT",
29
30
  "type": "commonjs",
31
+ "pi": {
32
+ "extensions": [
33
+ ".pi/extensions/goal/index.ts"
34
+ ]
35
+ },
30
36
  "publishConfig": {
31
37
  "access": "public"
32
38
  },