pi-soly

v1.9.3

Published

21 hours ago

Project management + workflow engine for pi-coding-agent. Plans, state, MANDATORY rules, multi-question picker — one npm install, zero config. LLM is the executor (no subagent layer).

0High
0Medium
0Low

lowern1ght

pi pi-extension pi-package project-management planning multi-question workflow-engine rules-engine intent-docs ai-coding

⚡ pi-soly

The project management + workflow engine for pi-coding-agent.

Plans · State · Rules · Multi-question picker. One npm install. Zero config.

Install · Commands · Rules & Docs · Architecture · Releases

⚡ Install

pi install npm:pi-soly

Restart pi (/reload), and you have:

Project management — plans, state, phases, decisions
Workflow engine — /plan, /execute, /resume, /inspect, /discuss, /quick
Mandatory rules — strict-mode directives injected every turn
Multi-question picker — ask_pro tool for the LLM
Skill-based execution — LLM reads the soly-framework skill on demand

No agents, no rotors, no mode cycling. The LLM is the executor. You focus on the work.

🎯 Why pi-soly?

| Without pi-soly | With pi-soly | |---|---| | Re-invent plan/state/resume from scratch | /plan, /execute, /resume, /inspect ready | | Forget rules mid-session | ## ⚠️ MANDATORY header in every system prompt | | Wonder which rules eat context | /rules stats — Claude-memory-style breakdown | | Wonder which docs eat context | /docs stats — same for intent docs | | Ask the LLM the same clarifying question 5 times | ask_pro multi-question picker |

📋 Commands

Workflow

/plan              # generate PLAN.md for the current phase
/execute           # execute plan directly (LLM does the work)
/resume            # pick up a paused session
/inspect           # show current state summary
/discuss 3         # talk through decisions before planning phase 3
/quick "fix typo"  # one-shot task with HANDOFF-style context

State inspection (`/soly`)

/soly              # interactive picker (📍📄📋💡🔬🗺️📊📁✅⭐🎯🔄⚙️)
/soly position     # where am I in the plan
/soly state        # current STATE.md content
/soly roadmap      # all phases
/soly progress     # phases/plans/tasks done vs total
/soly phases       # list phases
/soly plan [N]     # show plan for phase N

Rules & Docs

/rules             # interactive list
/rules stats       # context breakdown (always-on vs glob-matched)
/rules analytics   # token analytics + warnings + duplicates
/rules show <name> # show rule body
/rules reload      # re-read all rules
/rules enable <name> / disable <name>

/docs stats        # context breakdown (inline vs preview vs phase-specific)

Setup

/soly-init                # scaffold .soly/ (templates: minimal|web-app|library|cli)
/soly-migrate             # atomic .soly/ → .agents/ rename (vendor-neutral)
/soly-status              # one-screen health report
/soly-log                 # recent notifications

Debug

/why              # rules + project state that grounded the last turn
/rulewizard       # interactive guide: rule vs .editorconfig vs linter

🧠 Rules & Docs

Two system-prompt injections, both opt-in and fully observable.

Rules — `.soly/rules/` or `~/.soly/rules/`

Markdown files with frontmatter. Three modes:

---
description: TypeScript code style
always: true            # loaded every turn
---

Always use `strict` mode. Never use `any`...

---
description: React component rules
globs: ["**/*.tsx", "**/*.jsx"]   # loaded only when prompt mentions matching file
---

Hooks only at top level. Use memo only for expensive renders...

System prompt injection (every turn, after before_agent_start):

## ⚠️ MANDATORY: soly project rules

**These rules are NON-NEGOTIABLE. Before writing or editing ANY code,
re-read the rules above that apply to the file path you are about to
modify. If a rule contradicts your instinct, the rule wins.**

See context breakdown anytime: /rules stats.

Docs — `.soly/docs/` or `~/.soly/docs/`

Zero-point intent docs (your vision, business context). Loaded as preview only (180 chars per doc) — cheap. Add inline: true to opt-in to full body injection.

---
title: Core principles
inline: true     # full body loaded every turn (expensive!)
---

Our core principles are...

See context breakdown: /docs stats.

🎤 Multi-Question Picker

ask_pro tool for the LLM. Tabbed UI: single-select, multi-select, recommended ⭐, free-text Other.

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." }
    ]
  }]
})

The LLM calls ask_pro when it needs structured input. Tab through questions, pick ⭐ options, confirm.

🏗 Architecture

┌──────────────────────────────────────────────────────────────┐
│                   pi-coding-agent (peer dep)                 │
└────────────────────────┬─────────────────────────────────────┘
                         │
        ┌────────────────┴────────────────┐
        ▼                                 ▼
  ┌────────────┐                  ┌─────────────┐
  │  ask_pro   │                  │  soly_read  │
  │  picker    │                  │  soly_log_  │
  │  (tool)    │                  │  decision   │
  └────────────┘                  └─────────────┘
        │                                 │
        └─────────────────┬───────────────┘
                          │
                          ▼
                ┌──────────────────┐
                │  Workflow engine │
                │                  │
                │  /plan /execute  │
                │  /resume /inspect│
                │  /discuss /quick │
                │  /soly /why      │
                │  /rules /docs    │
                └────────┬─────────┘
                         │
            ┌────────────┼────────────┐
            ▼            ▼            ▼
       .soly/STATE  phases/<N>/   rules/
       (current     CONTEXT,      docs/
        position)   PLAN,         (system
                    RESEARCH)     prompt)
                         │
                         ▼
                ┌──────────────────┐
                │  soly-framework  │
                │  SKILL.md        │
                │                  │
                │  LLM loads on    │
                │  demand \u2014 no  │
                │  subagent layer  │
                └──────────────────┘

State lives in .soly/ — portable, git-friendly, human-readable. Migrate to vendor-neutral .agents/ with /soly-migrate (both supported, .soly/ shows deprecation warning).

.soly/
├── ROADMAP.md           # phase table
├── STATE.md             # current position + decisions log
├── docs/                # 0-point intent docs (preview-loaded)
├── rules/               # rules (glob-matched or always-on)
└── 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

📚 Events

| Event | When | What we do | |---|---|---| | session_start | session opens | Install soly-framework skill, build initial state | | before_agent_start | every turn | Inject rules + docs sections into system prompt | | tool_call (edit/write) | LLM edits file | Track edited files (silent — used by /why) | | turn_end | turn finishes | Refresh rules/state, hot-reload changes | | session_shutdown | session closes | Flush iterators, cleanup |

🛠 Development

Requirements

Bun ≥ 1.3
pi-coding-agent ≥ 0.78

Setup

git clone https://github.com/lowern1ght/pi-soly.git
cd pi-soly
bun install

Test + typecheck

bun test          # 366 tests across 24 files
bun run typecheck # tsc --noEmit
bun run ci        # both

Live-reload in pi

pi install ./packages/pi-soly
# edit files → /reload in pi to pick up changes

🚢 Releases

Tag-based, fully automated. Push a pi-soly-v* tag, get a publish.

./scripts/release.sh pi-soly 1.9.1
git push github master
git push github pi-soly-v1.9.1 --force

CI runs on a self-hosted GitHub Actions runner:

| 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 |

The publish job uses GitHub Environment npm-publish so NPM_TOKEN is only exposed during the publish step. Zero secrets in workflow YAML.

🤝 Compatibility

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)

📜 License

MIT — see LICENSE.

Built by @lowern1ght · Powered by pi + Bun

⭐ Star on GitHub · 📦 View on npm · 🐛 Report a bug

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

⚡ pi-soly

⚡ Install

🎯 Why pi-soly?

📋 Commands

Workflow

State inspection (/soly)

Rules & Docs

Setup

Debug

🧠 Rules & Docs

Rules — .soly/rules/ or ~/.soly/rules/

Docs — .soly/docs/ or ~/.soly/docs/

🎤 Multi-Question Picker

🏗 Architecture

📚 Events

🛠 Development

Requirements

Setup

Test + typecheck

Live-reload in pi

🚢 Releases

🤝 Compatibility

📜 License

State inspection (`/soly`)

Rules — `.soly/rules/` or `~/.soly/rules/`

Docs — `.soly/docs/` or `~/.soly/docs/`