@tryinget/pi-modes 0.1.0

package/LICENSE

@@ -0,0 +1,78 @@
+MIT License (with OpenAI/Anthropic/xAI/PRC Frontier Labs Rider)
+
+Copyright (c) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+ADDITIONAL RIDER / RESTRICTION (OpenAI / Anthropic / xAI / PRC Frontier Labs):
+
+This rider is part of the "conditions" of this License. In the event of any
+conflict between this rider and any other portion of this License, this rider
+controls.
+
+"Restricted Parties" means OpenAI, L.L.C.; Anthropic, PBC; xAI Corp.; and the
+following PRC frontier AI labs and related entities: Baidu (including ERNIE-
+related entities), Alibaba and Alibaba Cloud (including Qwen-related entities),
+Tencent (including Hunyuan-related entities), ByteDance (including Doubao/Seed-
+related entities), DeepSeek, Zhipu AI, Moonshot AI, MiniMax, 01.AI
+(Lingyiwanwu), and iFlyTek. "Restricted Parties" also includes any of their
+respective Affiliates and any person or entity acting directly or indirectly
+on behalf of, for the benefit of, or under the direction of any of the
+foregoing (including any officer, director, employee, contractor, agent,
+consultant, service provider, or representative).
+
+Notwithstanding any other provision of this License, no rights are granted to
+any Restricted Party. Any purported license, sublicense, assignment, transfer,
+or other permission to any Restricted Party is null and void absent the
+express prior written permission of the copyright holders.
+
+You may not provide, disclose, distribute, sublicense, sell, lease, lend,
+host, make available, or otherwise permit access to the Software or any
+derivative work of the Software (as defined in applicable copyright law)
+(collectively, "Derivative Works") to or for any Restricted Party.
+
+For purposes of this rider, "use" includes, without limitation: copying,
+modifying, merging, publishing, distributing, sublicensing, selling,
+transferring, making available, hosting, deploying, executing, benchmarking,
+testing, analyzing, indexing, or incorporating the Software or any Derivative
+Works into any dataset, training corpus, evaluation harness, or pipeline for
+machine learning or other automated systems.
+
+This rider applies to the Software and all Derivative Works. As a condition of
+use, you agree that this rider is a precondition to exercising any rights
+under this License, and you agree that any distribution of the Software or any
+Derivative Works must include this rider provision unmodified.
+
+Any breach of this rider automatically and immediately terminates the
+permissions granted by this License. Upon termination, you must immediately
+cease all use and distribution of the Software and any Derivative Works and
+destroy all copies under your control.
+
+You agree that a breach of this rider would cause irreparable harm and that
+the copyright holders may seek injunctive or other equitable relief to enforce
+this rider, in addition to any other remedies available at law. To the maximum
+extent permitted by applicable law, the prevailing party in any action to
+enforce this rider shall be entitled to recover reasonable attorneys' fees and
+costs.
+
+For purposes of this rider, "Affiliate" means any entity that directly or
+indirectly controls, is controlled by, or is under common control with the
+specified party. "Control" means ownership of more than 50% of the voting
+securities or other ownership interest, or the power to direct management or
+policies by contract or otherwise.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+---
+summary: "Prompt mode switching with explicit base-prompt and final-prompt replacement semantics."
+read_when:
+  - "Installing, operating, or extending @tryinget/pi-modes."
+system4d:
+  container: "Installable Pi prompt-mode package."
+  compass: "Switch complete prompt policies without confusing base replacement, final replacement, or autonomy."
+  engine: "Discover modes -> validate -> activate -> compose -> restore from session state."
+  fog: "Prompt composition layers are easy to conflate and can silently discard dynamic context."
+---
+
+# @tryinget/pi-modes
+
+Switch Pi prompt profiles during a session without restarting Pi.
+
+The package makes the distinction that matters:
+
+- `append` keeps Pi's fully assembled prompt and adds mode instructions;
+- `replace_base` changes the complete static base prompt while preserving Pi's dynamic append/context/skills/date/cwd envelope;
+- `replace_final` deliberately replaces the final assembled prompt with exact text.
+
+`replace_base` corresponds to the intent of Pi's native `--system-prompt` and `SYSTEM.md` features.
+
+## Native base and named alternatives
+
+Pi's native base-prompt files remain the default source of truth:
+
+```text
+<project>/.pi/SYSTEM.md
+~/.pi/agent/SYSTEM.md
+```
+
+Starting Pi normally uses the trusted project `SYSTEM.md`, then the global `SYSTEM.md`, then Pi's built-in base according to Pi's native resource rules. `pi-modes` does not add a parallel project-default file. Named modes under `.pi/modes/` and `~/.pi/agent/modes/` are explicit alternatives to that native base.
+
+When no named mode is active—or after `/mode off`—the extension returns control to Pi unchanged, so the native `SYSTEM.md` base and dynamic envelope remain active.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `/mode` | Select a discovered mode. |
+| `/mode <key>` | Activate a mode directly. |
+| `/mode off` | Restore the host prompt for future turns. |
+| `/mode-status` | Add a durable TUI-only status card with active mode, native-base fallback, available keys, and diagnostics. |
+| `/mode-preview [key]` | Preview the final composed prompt without activating it; without a key, open the mode selector. |
+| `/mode-new [--project] <key>` | Create a global or trusted-project mode in an editor. |
+| `/mode-edit <key>` | Edit a custom mode using its validated discovered path. |
+| `/mode-delete <key>` | Confirm and delete a custom mode safely. |
+
+The package includes small built-in `plan`, `review`, and `explain` append modes.
+
+`/mode-status` is stored as a custom session entry and rendered in the transcript without entering LLM context. Its compact view shows the active selection and counts; expand it through Pi's normal message-expansion control to see strategy, scope, available keys, and malformed-file diagnostics.
+
+## Launch-time selection
+
+Set `PI_MODE` to select a named alternative when Pi starts:
+
+```bash
+PI_MODE=focused-builder pi
+PI_MODE=review pi
+PI_MODE=off pi
+```
+
+Startup precedence is intentionally small:
+
+1. a non-blank `PI_MODE` explicitly selects a named mode or `off`;
+2. otherwise, a resumed/reloaded session restores its latest `/mode` selection;
+3. otherwise, Pi uses its native project/global `SYSTEM.md` or built-in base.
+
+`PI_MODE=off` (also `default` or `none`) explicitly selects the native `SYSTEM.md`/host base. An unavailable or invalid `PI_MODE` fails closed to that native base and reports a warning. The resolved launch selection is written to the Pi session branch, so later turns remain stable; an interactive `/mode` command can change it afterward.
+
+## Mode files
+
+Global modes:
+
+```text
+~/.pi/agent/modes/*.json
+```
+
+Trusted ancestor/project modes:
+
+```text
+<filesystem-root>/.pi/modes/*.json
+...
+<company>/.pi/modes/*.json
+...
+<cwd>/.pi/modes/*.json
+```
+
+Discovery mirrors Pi's `AGENTS.md` layering: load the global mode directory, then ancestor `.pi/modes` directories from filesystem root down to the active cwd. Deeper definitions override shallower definitions with the same key; every project definition overrides global and built-in definitions. This lets `~/ai-society/.pi/modes`, company-level `.pi/modes`, lane-level `.pi/modes`, and repo-local `.pi/modes` form one predictable hierarchy.
+
+All ancestor/project mode directories are ignored when the active project is not trusted. `/mode-new --project <key>` writes only to the active cwd's `.pi/modes`; it never mutates an ancestor implicitly. Inherited modes are selectable and previewable but read-only from descendant cwd sessions—change to the owning ancestor directory before using `/mode-edit` or `/mode-delete`.
+
+Discovery and persistence reject symbolic links in any path component, including a symlinked `.pi` parent, so an inherited mode cannot escape its declared filesystem hierarchy.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "key": "focused-builder",
+  "label": "Focused Builder",
+  "description": "A complete static coding-agent identity.",
+  "promptStrategy": "replace_base",
+  "systemPrompt": "You are a focused coding agent. Drive the requested task to verified completion."
+}
+```
+
+A missing `promptStrategy` defaults to `replace_base`.
+
+More examples are in [`examples/modes`](examples/modes).
+
+## Prompt composition
+
+### `append`
+
+```text
+host assembled prompt
++ active-mode section
+```
+
+### `replace_base`
+
+```text
+mode systemPrompt
++ APPEND_SYSTEM.md / --append-system-prompt
++ trusted AGENTS.md / CLAUDE.md context
++ visible skills when read is active
++ date
++ cwd
+```
+
+### `replace_final`
+
+```text
+mode systemPrompt exactly
+```
+
+`replace_final` intentionally does not retain project context, skills, date, cwd, or appended instructions. Use it for controlled exact-prompt experiments rather than by accident.
+
+## Safety and scope
+
+- Mode keys are validated before path construction.
+- JSON files are parsed independently; one malformed file does not hide later valid modes.
+- Saves use same-directory temporary files plus atomic rename.
+- Edit/delete operate only on discovered global/project files.
+- Mode selection is persisted in session custom entries and restored on resume/reload when `PI_MODE` does not explicitly override startup.
+- The native project/global `SYSTEM.md` remains the default base; named modes are alternatives, not another default layer.
+
+Mode activation changes prompt policy only. It does not send follow-up messages, continue automatically, launch peers/subagents/campaigns, or grant mutation or promotion authority. Future autonomy integration is intentionally separate.
+
+Architecture: [`docs/project/2026-07-11-prompt-mode-architecture.md`](docs/project/2026-07-11-prompt-mode-architecture.md)
+Implementation plan: [`docs/project/2026-07-11-implementation-plan.md`](docs/project/2026-07-11-implementation-plan.md)
+
+## Install and verify
+
+```bash
+git clone https://github.com/tryingET/pi-extensions.git
+cd pi-extensions/packages/pi-modes
+npm install
+npm run check
+pi install "$PWD"
+```
+
+Then run `/reload` and verify with:
+
+```text
+/mode review
+/mode-status
+/mode-preview review
+/mode off
+```
+
+## Attribution
+
+The concept and command vocabulary were informed by Maxime Rivest's MIT-licensed [`pi-modes`](https://github.com/MaximeRivest/pi-modes). This package uses a separately structured implementation with explicit composition strategies, trust gating, safe persistence, and tests.

package/docs/project/2026-07-11-implementation-plan.md

@@ -0,0 +1,61 @@
+---
+summary: "Implementation and rollout plan for safe prompt-mode switching."
+read_when:
+  - "Implementing or reviewing the initial pi-modes package."
+  - "Planning live activation or later autonomy integration."
+system4d:
+  container: "Delivery plan for the initial prompt-mode package."
+  compass: "Land safe prompt composition first and defer autonomous execution to its owners."
+  engine: "Scaffold -> kernel -> adapter -> docs -> tests -> live activation."
+  fog: "A broad autonomy ambition can widen a bounded prompt-mode implementation."
+---
+
+# Implementation plan
+
+## Immediate implementation
+
+1. **Scaffold the package from `pi-extensions-template`.**
+   - Keep `.copier-answers.yml` tracked.
+   - Align the package with the pinned Earendil Pi host contract.
+2. **Land a testable prompt-mode kernel.**
+   - Versioned JSON schema.
+   - `append`, `replace_base`, and `replace_final` composition.
+   - Global/project/builtin precedence with project-trust gating.
+   - Per-file diagnostics, safe paths, atomic writes, and session state replay.
+3. **Land the Pi extension adapter.**
+   - `/mode`, `/mode-status`, `/mode-preview`, `/mode-new`, `/mode-edit`, `/mode-delete`.
+   - Footer status and `before_agent_start` composition.
+   - Explicit `PI_MODE=<key|off>` launch selection without introducing a parallel project-default file.
+   - Preserve native `<project>/.pi/SYSTEM.md` and `~/.pi/agent/SYSTEM.md` behavior whenever no named mode is active.
+   - No continuation, dispatch, campaign, or authority behavior.
+4. **Add examples and operator documentation.**
+   - One example for each strategy.
+   - Explain the difference between base and final replacement.
+   - Make the package discoverable from root package maps and the runtime capability map.
+5. **Verify.**
+   - Unit tests for composition, precedence, malformed files, trust, traversal, persistence, replay, and launch-variable parsing.
+   - Package `npm run check` and root package gate.
+   - Install the local package, reload Pi, and exercise a real `/mode` flow before claiming live activation.
+
+## Follow-up: upstream composition seam
+
+Propose or contribute a public Pi host builder for reconstructing a custom base from `BuildSystemPromptOptions`. Add a compatibility-canary scenario, then remove the parity implementation only after live proof.
+
+## Deferred autonomy phases
+
+Autonomy is intentionally not implemented by `/mode`.
+
+1. Emit a non-authoritative, hashed mode-activation snapshot.
+2. Qualify mode profiles through `pi-evalset-lab`.
+3. Add an orchestrator-owned, plan-only autonomy route decision.
+4. Route explicit supervised execution to ASC or visible-loop owners.
+5. Route measured recursive improvement to `pi-autoresearch`.
+6. Keep continuation, durable writes, finalization, cleanup, and promotion under separate explicit gates.
+
+The read-only scout architecture packet for this work recommends that mode activation never carry an execute bit, objective, budget, or authority token.
+
+## Rollback
+
+- `/mode off` restores the host-assembled prompt for subsequent turns.
+- Removing or disabling the package leaves Pi's native `--system-prompt`, `SYSTEM.md`, and `APPEND_SYSTEM.md` behavior unchanged.
+- Custom mode files are plain JSON and do not modify project or global Pi system-prompt files.

package/docs/project/2026-07-11-prompt-mode-architecture.md

@@ -0,0 +1,101 @@
+---
+summary: "Architecture for prompt modes that replace Pi's static base prompt without confusing mode selection with autonomy."
+read_when:
+  - "Changing prompt composition, mode storage, activation, or cross-package boundaries."
+  - "Evaluating whether a mode may trigger autonomous behavior."
+system4d:
+  container: "Session-local prompt-mode extension."
+  compass: "Make complete base-prompt replacement first-class while preserving Pi's dynamic envelope by default."
+  engine: "Discover -> validate -> activate -> compose -> persist session selection."
+  fog: "A final-prompt override can be mistaken for a base-prompt override, and a mode name can be mistaken for execution authority."
+---
+
+# Prompt-mode architecture
+
+## Decision
+
+`pi-modes` owns prompt-profile discovery, validation, selection, prompt composition, session-local persistence, and operator visibility.
+
+It supports three explicit strategies:
+
+| Strategy | Result |
+|---|---|
+| `append` | Keep Pi's assembled prompt and append mode instructions. |
+| `replace_base` | Replace Pi's static base, then preserve the documented dynamic envelope: append prompt, trusted context files, visible skills, date, and cwd. |
+| `replace_final` | Send exactly the configured mode prompt. No dynamic section is retained automatically. |
+
+`replace_base` is the primary strategy. It matches the intent of Pi's `--system-prompt` and `SYSTEM.md` surfaces. `replace_final` is an explicit expert escape hatch rather than an accidental side effect.
+
+Pi's native `<project>/.pi/SYSTEM.md` and `~/.pi/agent/SYSTEM.md` remain the default base-prompt authority. This package does not add a second project-default selector. Named `replace_base` modes are explicit alternatives; no active mode and `/mode off` both return control to the native host assembly unchanged.
+
+## Why this package exists
+
+Pi exposes complete base-prompt replacement at process start, while `before_agent_start` exposes the already assembled prompt. A session mode therefore needs to distinguish changing the base from replacing the final assembly. The extension reconstructs Pi's documented custom-base branch from `event.systemPromptOptions` until Pi exposes a supported host builder or a `systemPromptOptions` return patch.
+
+## Runtime flow
+
+```text
+native <cwd>/.pi/SYSTEM.md or ~/.pi/agent/SYSTEM.md host base
++ global built-ins
++ ~/.pi/agent/modes/*.json
++ trusted ancestor .pi/modes/*.json from filesystem root to cwd
+-> validate each mode file independently
+-> deepest project overrides shallower project, global, then builtin by key
+-> explicit PI_MODE launch selection, otherwise latest session selection
+-> append changed selection to the active session branch
+-> before_agent_start composes the selected strategy
+-> no selection/off returns the native host base unchanged
+-> footer shows an active named mode
+```
+
+Ancestor discovery mirrors Pi's `AGENTS.md` load order: filesystem root down to cwd, with the deepest matching key winning. Project mode files are ignored unless `ctx.isProjectTrusted()` is true. Invalid files produce diagnostics without preventing other modes from loading. `/mode-new --project` writes only at the active cwd. Writes use validated keys and atomic same-directory rename; edit/delete never accept a raw path.
+
+A non-blank `PI_MODE` is an explicit process-start override and therefore takes precedence over the restored session selection. `off`, `default`, and `none` select the native host base. Invalid or unavailable values fail closed to that native base with a warning. When `PI_MODE` is absent or blank, session branch replay remains authoritative. Interactive `/mode` commands may change the resolved startup selection for later turns.
+
+## Mode contract
+
+```json
+{
+  "schemaVersion": 1,
+  "key": "focused-builder",
+  "label": "Focused Builder",
+  "description": "Complete coding-agent identity for focused implementation.",
+  "promptStrategy": "replace_base",
+  "systemPrompt": "You are ..."
+}
+```
+
+A missing `promptStrategy` defaults to `replace_base`, making simple custom modes behave like Pi's custom system-prompt feature.
+
+## Trust and authority boundary
+
+Mode activation changes prompt policy only. It does not:
+
+- call `pi.sendUserMessage`;
+- continue after `agent_settled`;
+- dispatch subagents or peers;
+- start visible loops or autoresearch campaigns;
+- mutate AK, Prompt Vault, KES, ROCS, or evidence;
+- grant mutation, promotion, or publication authority.
+
+Future autonomy work must consume a separate explicit handoff request through its owning runtime. A mode name such as `research` or `autonomous` is never authorization.
+
+## Future host improvement
+
+Prefer an upstream Pi API equivalent to one of:
+
+```ts
+ctx.buildSystemPrompt({ ...event.systemPromptOptions, customPrompt })
+```
+
+or:
+
+```ts
+return { systemPromptOptions: { customPrompt } };
+```
+
+Once supported and compatibility-tested, replace the package-local parity builder with the host builder to eliminate composition drift.
+
+## Attribution
+
+The product concept and command vocabulary were informed by Maxime Rivest's MIT-licensed [`pi-modes`](https://github.com/MaximeRivest/pi-modes). This implementation is independently structured around explicit prompt-composition strategies, project trust, safe persistence, and package-local tests.

package/examples/modes/exact-minimal.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "key": "exact-minimal",
+  "label": "Exact Minimal",
+  "description": "Demonstrate exact final-prompt replacement for controlled experiments.",
+  "promptStrategy": "replace_final",
+  "systemPrompt": "Respond concisely and directly to the user's request."
+}

package/examples/modes/focused-builder.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "key": "focused-builder",
+  "label": "Focused Builder",
+  "description": "Replace the static base while retaining Pi's dynamic project envelope.",
+  "promptStrategy": "replace_base",
+  "systemPrompt": "You are a focused coding agent operating inside Pi. Pursue the operator's requested outcome proactively, keep scope explicit, use available tools deliberately, verify material changes, report blockers early, and distinguish completed work from proposed work."
+}

package/examples/modes/hard-nosed-review.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "key": "hard-nosed-review",
+  "label": "Hard-nosed Review",
+  "description": "Add adversarial review discipline to the current host prompt.",
+  "promptStrategy": "append",
+  "systemPrompt": "Be skeptical. Look for incorrect assumptions, missing evidence, regressions, authority drift, and tests that pass without proving the requested behavior. State the strongest counterargument before concluding."
+}