@itsautomata/prism 0.1.2 → 0.3.0

package/README.md

@@ -5,9 +5,12 @@
 Prism is an open source coding assistant that runs locally on your machine through Ollama, or cloud through OpenRouter (300+ models).
 
 
-> actively built and tested. expect breaking changes. decentralized intelligence is cool
+> actively built and tested. expect breaking changes. decentralized intelligence is cool.
+
+**prism building a working terminal tetris from one prompt with deepseek-v4-pro**
+
+https://github.com/user-attachments/assets/3451a4ec-1a4f-431d-bd15-aba799b9cdf4
 
-![prism](https://raw.githubusercontent.com/itsautomata/prism/main/assets/prism_3.png)
 
 ## quick start
 
@@ -50,14 +53,14 @@ prism --install-completion bash      # explicit
 
 ## choose your model
 
-### local (free, ollama)
+**local (free, ollama)**
 
 ```bash
 prism                       # deepseek-r1:14b (default)
 prism qwen3:14b
 ```
 
-### cloud (openrouter, 300+ models)
+**cloud (openrouter, 300+ models)**
 
 add your API key to `~/.prism/config.toml` (created on first run), then:
 
@@ -98,10 +101,13 @@ sessions saved at `~/.prism/sessions/`.
 | Glob | find files by pattern |
 | Grep | search file contents |
 | Agent | spawn read-only subagents for parallel research |
+| useSkill | invoke a named workflow from skills/<name>.md |
+| WebFetch | fetch and convert web pages to markdown |
+| WebSearch | query a search backend, return ranked results |
 
 ## permissions
 
-write operations ask before executing. read operations auto-allow. subagents inherit read-only access; they cannot escalate to write operations.
+write operations ask before executing. read operations auto-allow. by default, subagents are read-only. user-defined agents can declare `permissions: inherit` to write through the parent's permission prompt.
 
 ```
 ◆ Bash wants to: run: git push
@@ -110,6 +116,50 @@ write operations ask before executing. read operations auto-allow. subagents inh
     [n] no
 ```
 
+## agents
+
+prism ships with a built-in read-only research subagent. define your own at `./agents/<name>.md` (project) or `~/.prism/agents/<name>.md` (user), with YAML frontmatter:
+
+```markdown
+---
+description: refactorer focused on extracting React hooks
+tools: ['Read', 'Edit', 'Grep']
+permissions: inherit
+max_turns: 8
+---
+
+you are a refactoring specialist. read the file first, propose the
+extraction, then apply it. do not touch tests.
+```
+
+`permissions: deny-writes` (default) blocks writes. `permissions: inherit` lets the subagent write through the parent's permission prompt. list with `/agent`, invoke directly with `/agent <name> <task>`, or have the model call `Agent` with `agent: "<name>"`. deny-writes agents spawned in the same turn run in parallel.
+
+## skills
+
+reusable workflows the model follows on demand. drop a markdown file at `./skills/<name>.md` or `~/.prism/skills/<name>.md`:
+
+```markdown
+---
+mode: invoke
+require-permission: true
+---
+
+scan the staged diff for security issues. report findings as a table
+with file:line and severity.
+
+## quick
+do a fast pass only.
+
+## thorough
+trace data flow from input boundaries.
+```
+
+- `mode: invoke` (default): one-shot. trigger with `/run <name> [section] [task]` or let the model call `useSkill`.
+- `mode: passive`: ambient. toggle with `/skill <name>`, the body lands in the system prompt every turn until toggled off.
+- `require-permission: true`: prompts before the model can invoke it.
+
+`##` headings become section targets, so `/run review thorough` run just that block. `/skill` lists all skills (passive in cyan, invoke in green).
+
 ## teach it
 
 prism learns per model. rules persist across sessions.
@@ -129,6 +179,9 @@ rules saved at `~/.prism/models/<model>.json`.
 /plan             enter plan mode (model proposes before executing)
 /exec-plan        exit plan mode and execute the plan
 /cancel-plan      exit plan mode without executing
+/agent [name]     list agents, show one, or invoke a named subagent
+/skill [name]     list skills or toggle a passive skill on/off
+/run <name>       invoke a skill one-shot (optional section, task)
 /remember <fact>  add a timestamped fact to project memo
 /teach <rule>     teach the model a rule
 /rules            show learned rules
@@ -156,7 +209,7 @@ iteration: typing feedback without `/exec-plan` keeps you in plan mode and lets
 
 prism remembers per project across sessions in two layers:
 
-- **lens.md** at your project root: rules you enforce. git-committed, ships with the repo so collaborators inherit them.
+- **lens** at `./lens.md` or any `.prism/*.md` file (multiple files supported): rules you enforce, extra context...
 - **memo** at `~/.prism/projects/<id>/memo.md`: facts the model and you accumulate as you work. lives outside the repo. add an entry with `/remember <fact>`. each entry is timestamped with the date so the model can spot stale info.
 
 example `lens.md`:
@@ -197,11 +250,14 @@ git clone https://github.com/itsautomata/prism.git
 cd prism
 npm install
 npm run dev               # run from source via tsx
-npm run build             # produce dist/cli.js (required before global install from this dir)
+npm run build             # produce dist/cli.js (required before global install from the local dir)
 npm install -g .          # symlink your local build as the global `prism`
 ```
 
-`dist/` is git-ignored, so `npm run build` is required before any `npm install -g .` in a fresh clone.
+you can run prism on itself to make itself better, and shape it to your workflow
+
+![apple](https://raw.githubusercontent.com/itsautomata/prism/main/assets/apple_eating_itself.gif)
+
 
 ## tests (on going)
 
@@ -215,12 +271,18 @@ covering:
 - CLI parsing
 - sessions and `--resume`
 - shell completion
-- slash command autocomplete
+- slash command autocomplete and prompt input
 - plan mode dispatch
 - memo persistence (per-project memory)
 - git context detection
-- token counting
-- tools and permissions
+- context compaction (token counting + summary fallback)
+- subagent registry, runner, and parallel-safety
+- skill loader (frontmatter, sections, name sanitization)
+- lens loader (`.prism` directory)
+- command-injection guards (grep, glob)
+- permission prompt mount and key handling
+- tools, permissions, subagent permission contract
+- web fetching
 - `!cmd` shell escape