npm - pi-soly - Versions diffs - 0.5.9 → 0.6.0 - Mend

pi-soly 0.5.9 → 0.6.0

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 (21) hide show

package/README.md +218 -307
package/agents/soly-manager.md +124 -0
package/agents-install.ts +8 -12
package/commands.ts +1 -1
package/config.ts +5 -4
package/index.ts +9 -9
package/package.json +1 -1
package/switch/README.md +21 -24
package/switch/core.ts +4 -11
package/switch/index.ts +2 -2
package/switch/prompt.ts +24 -27
package/switch/tests/core.test.ts +1 -1
package/switch/tests/index.test.ts +3 -2
package/switch/tests/prompt.test.ts +26 -24
package/agents/soly-debugger.md +0 -60
package/agents/soly-documenter.md +0 -82
package/agents/soly-oracle.md +0 -69
package/agents/soly-refactor.md +0 -65
package/agents/soly-reviewer.md +0 -107
package/agents/soly-tester.md +0 -56
package/agents/soly-worker.md +0 -84

package/README.md CHANGED Viewed

@@ -1,372 +1,283 @@
-# soly — Project rules, intent, state, and project context for Pi
+<div align="center">
-A single pi extension that loads project context into the agent's system
-prompt and exposes workflow verbs for a plan → execute → close-out loop
-on phases (and features/tasks). Replaces gsd.
+# ⚡ pi-soly
-> **Note.** This README describes the *current* source tree. If you came
-> here from an older install, the layout moved from a single `soly.ts`
-> file (and `.planning/` paths) to a modular `soly/` directory using
-> `.soly/`. Old `soly.ts`-based installs are no longer shipped.
+**The project management framework for [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent).**
-## What it shows
+Plans · State · Subagents · Multi-question picker · Agent switcher · Live task list.
-Footer status line, set via `ctx.ui.setStatus("soly", ...)`:
+One `npm install`. Zero config. Pure magic.
-```
-soly · v1.6.1 p10 0/2 [░░░░░░░░░░] 0%   rules 6 · 2.4k
-─────   ───────────────────────────      ────────────────
-prefix              project state              rules
-```
+[![npm version](https://img.shields.io/npm/v/pi-soly.svg)](https://www.npmjs.com/package/pi-soly)
+[![npm downloads](https://img.shields.io/npm/dm/pi-soly.svg)](https://www.npmjs.com/package/pi-soly)
+[![CI](https://img.shields.io/github/actions/workflow/status/lowern1ght/pi-soly/ci.yml)](https://github.com/lowern1ght/pi-soly/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/lowern1ght/pi-soly/blob/master/LICENSE)
+[![Built with Bun](https://img.shields.io/badge/Built_with-Bun-f9f1e1?logo=bun)](https://bun.sh)
-The progress bar is the only white element (focal point). Everything else
-is dim gray. Segments that don't apply are omitted silently — no empty
-`p10` if there's no current phase, no `rules` if there are no rules, etc.
+[Install](#-install) · [Features](#-features) · [Docs](#-documentation) · [Architecture](#-architecture) · [Releases](#-releases)
-| Segment | Example | Source |
-|---|---|---|
-| `soly ·` | (literal) | prefix |
-| `<milestone>` | `v1.6.1` | `.soly/STATE.md` frontmatter |
-| `p<N>` | `p10` | current phase number |
-| `<done>/<total>` | `0/2` | completed plans / total plans |
-| `[<bar>]` | `[█████░░░░░]` | progress bar (10 block chars) — **only white** |
-| `<pct>%` | `50%` | progress percent (dim) |
-| `rules <n>` | `rules 6` (or `rules 3/6`) | active rules / total rules |
-| `· <tok>` (rules) | `· 2.4k` | estimated tokens for the rules section |
-| `session <n>t <tok>` | `session 12t 18.4k` | assistant-turn count + rough token usage |
+</div>
-Status is change-detected — `setStatus` is only called when the rendered
-line differs from the previous one (anti-flicker).
+---
-## What it loads
+## ⚡ Install
-### Rules (priority order, higher wins on duplicate `relPath`)
+```bash
+pi install npm:pi-soly
+```
-| Priority | Source | Path | Label |
-|---|---|---|---|
-| 5 (highest) | Project local | `<cwd>/.soly/rules.local/` | `[local]` |
-| 4 | Project soly | `<cwd>/.soly/rules/` | `[soly]` |
-| 3 | Phase-scoped | `<phase-dir>/rules/` | `[phase]` (loaded only when that phase is active) |
-| 2 (lowest) | Global soly | `~/.soly/rules/` | `[soly]` |
+That's it. Restart pi, and you have:
-**Override rules**:
-- **Project always beats global** — same `relPath` in `.soly/rules/foo.md` overrides `~/.soly/rules/foo.md`.
-- **Local beats project** — `.soly/rules.local/foo.md` overrides `.soly/rules/foo.md` (gitignored personal overrides).
-- **Soly beats phase** within the same scope, **phase beats project** when active.
+- **A complete project management engine** — plans, state, subagent-driven execution
+- **A multi-question picker** — `ask_pro` tool for the LLM
+- **An agent switcher** — `Ctrl+Tab` to cycle, footer pill always visible
+- **A live task list** — `todo_update` tool renders in the footer
+- **7 soly agents** installed on first run
-When a rule is overridden, it is **not** loaded into the system prompt
-(no duplication) and appears in `/rules list` with a `⊘` marker.
+---
-Rules with `globs:` in frontmatter are only included when the active
-prompt or context files match. Rules with `always: true` always load.
+## 🎯 Why pi-soly?
-### Intent docs (the "0-point")
+| Without pi-soly | With pi-soly |
+|---|---|
+| Write your own planning workflow | `/plan`, `/execute`, `/resume`, `/inspect` — ready |
+| Manually dispatch subagents | `useSolyWorkerSubagents: true` — automatic routing |
+| 3 different packages for pickers/tasks/agents | One package, one config, one install |
+| Agent name as free text in slash commands | Footer pill + `Ctrl+Tab` + `/agent` picker |
+| Re-invent the state machine | `.soly/STATE.md` + auto-managed phases |
-`.soly/docs/` is loaded as project intent — the user's vision written
-*BEFORE* any soly plans. `.md` and `.html` are both supported (parsed
-for `<title>` / `<h1>` / `<meta name="description">`). Nested directories
-are scanned (e.g. `.soly/docs/api/auth.md`).
+---
-Per-phase intent (`.soly/phases/<NN>/docs/`) is loaded only when that
-phase is currently active. Phase intent is tagged separately in the
-system prompt.
+## 🔥 Features
-### Project state
+### 📋 Project Management Engine
-`.soly/` layout (dual-mode — phases AND features+tasks can coexist):
+GSD-inspired planning and execution. State is the source of truth, not vibes.
+```bash
+/plan            # generate PLAN.md for the current phase
+/execute         # dispatch plan to soly-worker subagent
+/resume          # pick up a paused session
+/inspect         # show current state summary
+/discuss 3       # talk through decisions before planning phase 3
 ```
-your-project/
-├── .soly/
-│   ├── STATE.md                              ← current position, decisions log
-│   ├── ROADMAP.md                            ← phases / milestones
-│   ├── REQUIREMENTS.md                       ← requirement IDs
-│   ├── PROJECT.md                            ← project overview
-│   ├── docs/                                 ← 0-point intent (.md / .html)
-│   ├── rules/                                ← project rules
-│   │   ├── code-style.md
-│   │   └── ...
-│   ├── rules.local/                          ← gitignored personal overrides
-│   ├── phases/
-│   │   └── 10-foo/
-│   │       ├── 10-CONTEXT.md
-│   │       ├── 10-RESEARCH.md
-│   │       ├── 10-01-PLAN.md
-│   │       ├── 10-01-SUMMARY.md
-│   │       ├── 10-02-PLAN.md
-│   │       ├── rules/                        ← phase-scoped rules (priority 3)
-│   │       └── docs/                         ← phase-specific intent
-│   ├── features/                             ← feature-mode (dual with phases)
-│   │   └── auth/
-│   │       ├── README.md
-│   │       └── tasks/
-│   │           ├── auth-be-login-a3f9/
-│   │           │   ├── PLAN.md
-│   │           │   └── SUMMARY.md
-│   │           └── ...
-│   ├── HANDOFF.json                          ← written by `soly pause`
-│   ├── .continue-here.md                     ← written by `soly pause`
-│   └── milestones/
-│       └── v1.6.1.md
-```
-## System prompt composition
-On `before_agent_start`, six sections are appended to the system prompt
-in this order (all optional — missing input just omits the section):
-1. `## soly project rules` — all applicable rules, filtered by `globs:` match against active prompt + pi context files
-2. `## soly project state` — milestone, phase, plan, progress, current plan objective, working agreement
-3. `## project intent (from .soly/docs/)` — always-on intent docs (titles + previews + token sizes)
-4. `### intent: <relpath>` (per-doc) — full body of intent docs with `inline: true` frontmatter (with `@import` resolution)
-5. `## current git state` — branch, working tree status, last 5 commits
-6. `## project env` — package manager, runtimes, scripts, services, tooling flags
-7. `## project layout` — top-level tree + key files + CI hint
-8. `## soly behavioral nudge` — always-on; tells the LLM to ask clarifying questions for non-trivial prompts and to prefer background subagents for research
+State lives in `.soly/` — portable, git-friendly, human-readable.
-All sections chain — they combine with other extensions' system-prompt
-contributions without conflict.
+```
+.soly/
+├── ROADMAP.md           # phase table
+├── STATE.md             # current position + decisions log
+├── docs/                # 0-point intent docs (your vision, locked)
+└── phases/
+    └── 01-foundation/
+        ├── 01-CONTEXT.md    # domain + decisions for this phase
+        ├── 01-RESEARCH.md   # what we looked up
+        └── 01-PLAN.md       # ordered steps to execute
+```
-## Workflow verbs (plain text — NOT slash)
+### 🎤 Multi-Question Picker
+Claude Code-style `ask_pro` for the LLM. Single-select, multi-select, recommended ⭐, free-text Other.
+```ts
+ask_pro({
+  questions: [{
+    header: "Auth",
+    question: "How should we store the OAuth refresh token?",
+    options: [
+      { label: "Encrypted in SQLite",  description: "Survives restart, single-device.", recommended: true },
+      { label: "OS keychain",          description: "Native, multi-device via iCloud." },
+      { label: "Plain env var",         description: "Simplest, dev only." }
+    ]
+  }]
+})
+```
-Type them in interactive mode. The extension intercepts via the `input`
-event and either:
+### 🎛 Agent Switcher
-- **transforms** the input into a detailed LLM instruction (the LLM still sees it, but with full workflow context, and calls `subagent(...)` itself)
-- **handles** directly (no LLM round-trip; immediate UI notify)
+Footer pill that's always there. `Ctrl+Tab` to cycle. No popup, no friction.
-| Verb | Mode | Purpose |
-|---|---|---|
-| `soly execute <N>` | transform | Execute all plans in phase N (wave-based parallel) |
-| `soly execute <N.MM>` | transform | Execute one plan in phase N |
-| `soly execute <task-id>` | transform | Execute one task (feature-mode) |
-| `soly execute --all` | transform | Execute all ready tasks (sequential in v0.1) |
-| `soly execute --feature <name>` | transform | Execute all tasks in a feature |
-| `soly plan <N>` | transform | Produce PLAN.md for phase N |
-| `soly plan <task-id>` | transform | Refine PLAN.md for existing task |
-| `soly plan --new-task <slug> --feature <n>` | transform | Create new task + PLAN.md |
-| `soly plan --feature <n>` | transform | Plan all ready tasks in a feature |
-| `soly discuss <N>` | transform | Scoping discussion for phase N |
-| `soly pause` | transform | Write HANDOFF.json + .continue-here.md (no compaction) |
-| `soly compact` | transform + auto-compact | Same as pause, then `ctx.compact()` at end of turn |
-| `soly resume [N]` | transform | Restore from handoff (optionally scoped to phase N) |
-| `soly status` | handled | One-screen position summary + recent iteration activity |
-| `soly log [N]` | handled | Last N rows from STATE.md Decisions table |
-| `soly diff` | handled | git status + uncommitted `.soly/` changes |
-| `soly diff iterations <a> <b>` | handled | Diff two iteration files (line-level) |
-| `soly iterations [N]` | handled | List N most recent `.soly/iterations/*.md` files (default 10) |
-| `soly doctor` | handled | Health check: missing files, broken refs, stale iterations |
-| `soly phase delete <N>` | handled | Soft-delete phase N (moves to `.soly/phases/.trash/<slug>-<ts>/`) |
-| `soly help` | handled | Show all available verbs |
-When transforming, the prompt template is built from `.md` files in
-`workflows-data/` (plan-phase, plan-task, execute-phase, execute-plan,
-execute-task, discuss-phase, pause-work). The LLM launches a `worker`
-subagent with `context: "fresh"` and `maxSubagentDepth: 1`.
-## Slash commands
-| Command | Subcommands |
-|---|---|
-| `/rules` | `list`, `show <path>`, `analytics`, `reload`, `enable <path>`, `disable <path>`, `enable-all`, `disable-all`, `add <url>`, `new` |
-| `/soly` | `position` (default), `state`, `plan`, `context`, `research`, `roadmap`, `progress`, `phases`, `tasks`, `task <id>`, `features`, `milestone`, `config`, `reload`, `help` |
-| `/rulewizard` | (interactive guide, no subcommands) |
-| `/why` | (no subcommands — shows the basis for the last turn, incl. loaded rule files) |
+```
+[model]  · ⚡ worker    · todos 2/5: write tests   ← footer, always visible
+[model]  ▶ 🐢 oracle    · todos 2/5: write tests   ← after one Ctrl+Tab
+[model]  · 🔍 scout     · todos 2/5: write tests   ← after two
+```
-## Tools (LLM-callable)
+Agents:
+- `worker` — default, full read+write
+- `oracle` — read-only decision advisor
+- `scout` — codebase reconnaissance
+- `researcher` — external docs, ecosystem
+- `planner` — architecture and decomposition
+- `context-builder` — hands off context to other agents
+- `reviewer` — adversarial code review, read-only
+- `delegate` — chains agents together
+### 📝 Live Task List
+`todo_update` tool — renders in the footer as `todos 2/5: current action`.
+The LLM can update its own task list mid-turn. You watch progress without re-asking.
+```ts
+todo_update({
+  todos: [
+    { content: "Read existing config", status: "completed", priority: "high" },
+    { content: "Write new schema",     status: "in_progress", priority: "high" },
+    { content: "Add migration",        status: "pending",     priority: "medium" },
+    { content: "Update tests",         status: "pending",     priority: "medium" },
+    { content: "Run typecheck",        status: "pending",     priority: "low" }
+  ]
+})
+```
-The agent can call these directly without the user typing a command.
-The `soly_*` tools are the primary way the LLM explores project state
-without bloating the system prompt.
+---
-| Tool | Purpose |
-|---|---|
-| `soly_read` | Read any `.soly/` artifact (state / plan / context / research / roadmap / requirements / project / milestone / task) |
-| `soly_log_decision` | Append a row to STATE.md Decisions table |
-| `soly_list_phases` | List phases with C/R markers and current-position arrow |
-| `soly_list_tasks` | List tasks across all features with kind/status/priority/deps |
-| `soly_intent` | List the 0-point intent docs (always present, even when empty) |
-| `soly_doc_search` | Search `.md` / `.html` files with intent/phase-intent/project priority |
-| `soly_snippet` | Bounded file read with line numbers, HTML strip option |
-| `soly_env` | Detect package manager / scripts / services / tooling flags |
-| `soly_todos` | Scan for `TODO`/`FIXME`/`HACK`/`XXX`/`NOTE` comments (requires `rg`) |
-| `soly_scratchpad` | Compact summary of recent conversation turns |
-## Interactive vs worker rules
-Rules with `interactive: true` in frontmatter load for the interactive
-LLM session (you typing in pi) but **NOT** for the `worker` subagent
-that runs in `soly execute` / `soly plan`. Use this for meta-rules like
-"ask before acting" or "use background subagents" that describe the
-**user-facing conversation**, not the execution work.
-The worker subagent task explicitly lists which rules are out of scope:
+## 🏗 Architecture
 ```
-- Interactive-only rules are NOT in scope for you:
-  process/ask-first.md, process/use-subagents.md
+┌──────────────────────────────────────────────────────────────┐
+│                   pi-coding-agent (peer dep)                  │
+└────────────────────────┬─────────────────────────────────────┘
+                         │
+        ┌────────────────┴────────────────┐
+        │                                 │
+        ▼                                 ▼
+  ┌────────────┐                  ┌─────────────┐
+  │  ask_pro   │                  │  todo_      │
+  │  picker    │                  │  update     │
+  │  (tool)    │                  │  (tool)     │
+  └────────────┘                  └─────────────┘
+        │                                 │
+        └─────────────────┬───────────────┘
+                          │
+                          ▼
+                ┌──────────────────┐
+                │  Workflow engine │
+                │                  │
+                │  /plan /execute  │
+                │  /resume /inspect│
+                │  /discuss /quick │
+                └────────┬─────────┘
+                         │
+            ┌────────────┼────────────┐
+            ▼            ▼            ▼
+       .soly/STATE  phases/<N>/   iterations/
+       (current     CONTEXT,      (per-exec
+        position)   PLAN,         context
+                    RESEARCH)     bundle)
+                         │
+                         ▼
+                ┌──────────────────┐
+                │  switch/         │
+                │  agent switcher  │
+                │                  │
+                │  Ctrl+Tab        │
+                │  footer pill     │
+                │  /agent picker   │
+                └────────┬─────────┘
+                         │
+                         ▼
+                ┌──────────────────┐
+                │  7 soly agents   │
+                │                  │
+                │  soly-worker     │
+                │  soly-debugger   │
+                │  soly-tester     │
+                │  soly-reviewer   │
+                │  soly-refactor   │
+                │  soly-documenter │
+                │  soly-oracle     │
+                └──────────────────┘
 ```
-## Display rules
-1. **Footer status only** — `ctx.ui.setStatus("soly", ...)`. No chat
-   popups for passive info (chat shows errors and explicit command output).
-2. **No widget** — the multi-line widget above the editor was removed.
-3. **No flicker** — the status line is change-detected.
-4. **Static progress bar** — `█` / `░` block characters, no animation.
-## Startup analytics
-On `session_start`, if rules are loaded, the extension shows a one-line
-breakdown (e.g. `soly rules: 6 (4 soly + 2 phase-10)`). If a rule is
-overridden, you also see `soly: 2 rule(s) overridden by project (...)`.
-If rules changed since the last session, you see `soly: rules changed
-since last session (+1 ~2)`. If rules use >5% of the context window,
-you see a budget warning. Run `/rules analytics` any time for the full
-breakdown (per-file sizes, %-of-context, missing descriptions, duplicates).
+---
-## Cross-extension integrations (soly as a platform)
+## 📚 Documentation
-soly composes with sibling pi-soly.framework when they're loaded. The registry
-lives in `integrations.ts` — add a new entry there to make soly aware of
-another extension's tool.
+- **Slash commands** — `/plan`, `/execute`, `/resume`, `/inspect`, `/discuss <N>`, `/quick <task>`, `/agent`
+- **Tools** — `ask_pro(question[])` and `todo_update(todo[])`
+- **Events** — `session_start`, `before_agent_start`, `message_end`, `tool_call`, `tool_result`
+- **State files** — `.soly/STATE.md`, `.soly/ROADMAP.md`, `.soly/phases/<N>-<slug>/<N>-PLAN.md`
+- **Soly agents** — installed to `~/.pi/agent/agents/soly-*.md` on first run
-| Extension | Tool | What it adds | Auto-detected? |
-|---|---|---|---|
-| **`pi-ask`** | `ask_pro` | Tabbed multi-question picker (Claude Code style). `soly discuss` uses it as PREFERRED over the built-in `soly_ask_user` fallback. | yes (via `pi.getActiveTools()`) |
-| **`pi-todo`** | `todo_update` | Live, user-visible task list in the footer. `soly execute` workflow template seeds todos from `<task>` blocks. soly shows `todos N/M` in its own status line. | yes |
+---
-When any registered tool is loaded, soly injects a `## Cross-extension
-integrations (active in this session)` section into the system prompt
-explaining when to reach for it. When none are loaded, the section is
-omitted entirely (no noise about extensions the user hasn't installed).
+## 🛠 Development
-`soly doctor` also reports each known extension as a check — `(pass)` if
-loaded, `(info)` if not (it's optional, not a warn).
+### Requirements
-## Opt-in: soly-aware subagents
+- [Bun](https://bun.sh) ≥ 1.3
+- [pi-coding-agent](https://github.com/nicobailon/pi-coding-agent) ≥ 0.78
-Soly ships two soly-specialized agent configs in `soly/agents/`:
+### Setup
-- **`soly-worker`** — implementation agent that knows soly path discipline
-  (everything under `.soly/`), plan/task structure, close-out order, and
-  auto-tracks plan sub-tasks via `todo_update` when pi-todo is installed.
-- **`soly-oracle`** — decision-consistency agent that validates plans
-  against existing STATE.md commitments (catches drift, scope creep,
-  hidden assumptions).
+```bash
+git clone https://github.com/lowern1ght/pi-soly.git
+cd pi-soly
+bun install
+```
-By default, `soly execute` workflows use pi-subagents' generic `worker`
-(because the soly workflow template already contains all soly instructions
-in the task prompt). To switch to the soly-specialized agents:
+### Test + typecheck
-1. Set `agent.useSolyWorkerSubagents: true` in `.soly/config.json`
-2. Reload pi (or wait for next `session_start`)
-3. Soly auto-installs `soly-worker.md` and `soly-oracle.md` to
-   `~/.pi/agent/agents/` (idempotent — won't overwrite user-customized copies)
-4. `soly execute` now launches `agent: "soly-worker"` instead of `worker`
-5. `soly doctor` shows `soly-aware subagents` as `(pass)`
+```bash
+bun test          # 288 tests
+bun run typecheck # tsc --noEmit
+bun run ci        # both
+```
-`soly doctor` reports current state of these agents. The install is
-opt-in to keep the default install minimal — most users don't need them.
+### Live-reload in pi
-To add a new integration, append a `KnownIntegration` entry in
-`integrations.ts`. No other code changes needed.
+```bash
+pi install ./packages/pi-soly
+# edit files → /reload in pi to pick up changes
+```
-## Agent switcher (Shift+Tab)
+---
-soly lets you pick which subagent `soly execute` launches, and you can
-cycle through the available ones with **Shift+Tab** (Claude Code-style
-shortcut, but for AGENTS not modes — pi handles plan/auto-accept itself).
+## 🚢 Releases
-The cycle order is deterministic and discoverable:
+Tag-based, fully automated. Push a `pi-soly-v*` tag, get a publish.
-1. **Built-in pi-subagents** (always available): `worker` → `oracle` →
-   `scout` → `researcher` → `planner` → `context-builder` → `reviewer` →
-   `delegate`
-2. **Soly-augmented agents** (only if `useSolyWorkerSubagents: true`):
-   `soly-worker` → `soly-oracle`
-3. **User-defined agents** (from `~/.pi/agent/agents/*.md`): anything you
-   add yourself with a YAML `name:` frontmatter
+```bash
+./scripts/release.sh pi-soly 0.5.9
+git push origin master
+git push github master
+git push github pi-soly-v0.5.9 --force
+```
-The active agent shows in the status line as `[agent: name]`, except for
-`worker` (the default — silent). Cycle or set explicitly:
+CI runs on a self-hosted GitHub Actions runner:
-- **Shift+Tab** — cycle to next agent
-- **`/soly agent`** — show current + available
-- **`/soly agent soly-worker`** — set explicitly
-- **`.soly/agent` file** — persisted across sessions (auto-managed)
+| Trigger | Job | Action |
+|---|---|---|
+| Push to `master` | `test` | `bun install` + `bun test` + `bun run typecheck` |
+| PR to `master` | `test` | same |
+| Push tag `pi-soly-v*` | `test` → `publish` | tests + `npm publish` to npmjs |
-**Add your own agent.** Drop a markdown file with YAML frontmatter into
-`~/.pi/agent/agents/`:
+The `publish` job uses GitHub Environment `npm-publish` so `NPM_TOKEN` is only exposed during the publish step. **Zero secrets in workflow YAML.**
-```markdown
----
-name: my-reviewer
-description: Security-focused reviewer for auth code
-tools: read, grep, bash
 ---
-You are a security reviewer. Focus on auth, input validation, and secrets…
-```
-Restart pi (or Shift+Tab) — `my-reviewer` shows up in the cycle. Soly
-discovers agents on every Shift+Tab, so no install step required.
-## Setup
+## 🤝 Compatibility
-Drop the `soly/` directory in `~/.pi/agent/extensions/`. Both `.soly/`
-(or `~/.soly/`) and `.soly/rules/` are auto-discovered. The extension
-also depends on the `pi-subagents` package (already in
-`~/.pi/agent/settings.json` `packages` if you used the recommended
-install) — `soly execute` / `soly plan` workflows call `subagent(...)`.
+- **pi-coding-agent** ≥ 0.78
+- **Node** ≥ 20 (pre-installed on the runner)
+- **Bun** ≥ 1.3 (pre-installed on the runner)
+- **OS** — Linux, macOS, Windows (anywhere Bun runs)
-```bash
-ls ~/.pi/agent/extensions/soly/
-# codemap.ts commands.ts config.ts core.ts docs.ts env.ts git.ts hotreload.ts
-# html.ts index.ts integrations.ts intent.ts iteration.ts nudge.ts scratchpad.ts tools.ts
-# agents/ workflows/ workflows-data/ tests/ package.json tsconfig.json
-# agents/soly-worker.md, agents/soly-oracle.md  (opt-in; installed on session_start if config flag set)
-```
+---
-## Configuration (soly)
+## 📜 License
-Two-layer config, merged with defaults:
+MIT — see [LICENSE](LICENSE).
-- **Per-project** `.soly/config.json` — version-controlled, project-specific
-- **Global** `~/.soly/config.json` — machine-specific, user-specific
+---
-Use `/soly config` to see the resolved (merged) config + schema. Key knobs:
+<div align="center">
-| Path | Default | Purpose |
-|---|---|---|
-| `iteration.retentionDays` | `14` | Stale iteration files pruned on `session_start`. `0` = never. |
-| `iteration.includeResearch` | `true` | Bundle phase research in iteration context |
-| `iteration.includeAntiPatterns` | `true` | Bundle anti-patterns doc in iteration context |
-| `agent.preferAskPro` | `true` | If `pi-ask` is installed, use `ask_pro` picker for `soly discuss` |
-| `agent.autoCheckpointOnPause` | `true` | Write iteration context bundle on `soly pause` |
-| `agent.useSolyWorkerSubagents` | `false` | Opt-in: install soly-aware subagent configs (`soly-worker`, `soly-oracle`) to `~/.pi/agent/agents/` on `session_start` and use them in `soly execute` instead of the generic `worker`. Off by default because the soly workflow template already contains all soly instructions. Enable if you want a soly-specialized subagent system prompt. |
-| `display.maxPhasesInStatus` | `20` | Cap on phases shown in `soly status` |
-| `display.defaultRecommendedFirst` | `true` | Default first option is the ⭐ in pickers |
-| `paths.excludeGlobs` | `["**/node_modules/**","**/dist/**"]` | Extra globs to exclude from code map |
-| `hotReload.pollMs` | `2000` | Windows/network-mount polling fallback |
-| `notifyOnRuleChange` | `true` | Notify on rule hot-reload |
-| `editor.command` | `"code"` | Editor for `soly edit` (future) |
-## How it works
-1. **`session_start`** — builds rule source list (project-local → project → global), loads all rules, loads project state from `.soly/`, runs `detectEnv` + `buildCodeMap` + `readGitContext` (one-time, cached), starts the hot-reload watcher.
-2. **`before_agent_start`** — composes the system-prompt sections (rules filtered by globs, project state, intent, inline-intent, git, env, code map, behavioral nudge) and computes per-section token estimates.
-3. **`turn_end`** — re-reads rules and state; if either changed, refreshes the status line.
-4. **Status update** — every render compares to the previous line and only calls `setStatus` on change.
-5. **Hot reload** — `fs.watch` with 100 ms debounce + 2 s polling fallback (Windows / network mounts). The user-facing notify is coalesced over 500 ms to absorb editor save-bursts (`.tmp` → rename → touch).
-6. **Workflow input** — the `input` event intercepts plain text matching `soly <verb> ...`, then either transforms the prompt (with a workflow markdown template + worker subagent task) or shows a direct result.
-## Development
+**Built by [@lowern1ght](https://github.com/lowern1ght) · Powered by [pi](https://github.com/nicobailon/pi-coding-agent) + [Bun](https://bun.sh)**
-```bash
-cd ~/.pi/agent/extensions/soly
-bun test              # runs tests/parser.test.ts, tests/nudge.test.ts, tests/html.test.ts
-bun run typecheck     # tsc --noEmit
-```
+[⭐ Star on GitHub](https://github.com/lowern1ght/pi-soly) · [📦 View on npm](https://www.npmjs.com/package/pi-soly) · [🐛 Report a bug](https://github.com/lowern1ght/pi-soly/issues)
-CI: `.github/workflows/ci.yml` runs both on push and PR.
+</div>