prose

Files (86)

• LICENSE
• SKILL.md
• alt-borges.md
• arabian-nights.md · alts/
• borges.md · alts/
• folk.md · alts/
• homer.md · alts/
• kafka.md · alts/
• compiler.md
• 01-hello-world.prose · examples/
• 02-research-and-summarize.prose · examples/
• 03-code-review.prose · examples/
• 04-write-and-refine.prose · examples/
• 05-debug-issue.prose · examples/
• 06-explain-codebase.prose · examples/
• 07-refactor.prose · examples/
• 08-blog-post.prose · examples/
• 09-research-with-agents.prose · examples/
• 10-code-review-agents.prose · examples/
• 11-skills-and-imports.prose · examples/
• 12-secure-agent-permissions.prose · examples/
• 13-variables-and-context.prose · examples/
• 14-composition-blocks.prose · examples/
• 15-inline-sequences.prose · examples/
• 16-parallel-reviews.prose · examples/
• 17-parallel-research.prose · examples/
• 18-mixed-parallel-sequential.prose · examples/
• 19-advanced-parallel.prose · examples/
• 20-fixed-loops.prose · examples/
• 21-pipeline-operations.prose · examples/
• 22-error-handling.prose · examples/
• 23-retry-with-backoff.prose · examples/
• 24-choice-blocks.prose · examples/
• 25-conditionals.prose · examples/
• 26-parameterized-blocks.prose · examples/
• 27-string-interpolation.prose · examples/
• 28-automated-pr-review.prose · examples/
• 28-gas-town.prose · examples/
• 29-captains-chair.prose · examples/
• 30-captains-chair-simple.prose · examples/
• 31-captains-chair-with-memory.prose · examples/
• 33-pr-review-autofix.prose · examples/
• 34-content-pipeline.prose · examples/
• 35-feature-factory.prose · examples/
• 36-bug-hunter.prose · examples/
• 37-the-forge.prose · examples/
• 38-skill-scan.prose · examples/
• 39-architect-by-simulation.prose · examples/
• 40-rlm-self-refine.prose · examples/
• 41-rlm-divide-conquer.prose · examples/
• 42-rlm-filter-recurse.prose · examples/
• 43-rlm-pairwise.prose · examples/
• 44-run-endpoint-ux-test.prose · examples/
• 45-plugin-release.prose · examples/
• 45-run-endpoint-ux-test-with-remediation.prose · examples/
• 46-run-endpoint-ux-test-fast.prose · examples/
• 46-workflow-crystallizer.prose · examples/
• 47-language-self-improvement.prose · examples/
• 48-habit-miner.prose · examples/
• 49-prose-run-retrospective.prose · examples/
• …and 26 more

SKILL.md (first lines)

# OpenProse Skill

OpenProse is a programming language for AI sessions. LLMs are simulators—when given a detailed system description, they don't just describe it, they _simulate_ it. The `prose.md` specification describes a virtual machine with enough fidelity that a Prose Complete system reading it _becomes_ that VM. Simulation with sufficient fidelity is implementation. **You are the Prose Complete system.**

## IdleHands Runtime Mapping

- **Task tool** in the upstream spec == IdleHands `sessions_spawn`
- **File I/O** == IdleHands `read`/`write`
- **Remote fetch** == IdleHands `web_fetch` (or `exec` with curl when POST is required)

## When to Activate

Activate this skill when the user:

- **Uses ANY `prose` command** (e.g., `prose boot`, `prose run`, `prose compile`, `prose update`, `prose help`, etc.)
- Asks to run a `.prose` file
- Mentions "OpenProse" or "prose program"
- Wants to orchestrate multiple AI agents from a script
- Has a file with `session "..."` or `agent name:` syntax
- Wants to create a reusable workflow

## Command Routing

When a user invokes `prose <command>`, intelligently route based on intent:

| Command                 | Action                                                        |
| ----------------------- | ------------------------------------------------------------- |
| `prose help`            | Load `help.md`, guide user to what they need                  |
| `prose run <file>`      | Load VM (`prose.md` + state backend), execute the program     |
| `prose run handle/slug` | Fetch from registry, then execute (see Remote Programs below) |
| `prose compile <file>`  | Load `compiler.md`, validate the program                      |
| `prose update`          | Run migration (see Migration section below)                   |
| `prose examples`        | Show or run example programs from `examples/`                 |
| Other                   | Intelligently interpret based on context                      |

### Important: Single Skill

There is only ONE skill: `open-prose`. There are NO separate skills like `prose-run`, `prose-compile`, or `prose-boot`. All `prose` commands route through this single skill.

### Resolving Example References

**Examples are bundled in `examples/` (same directory as this file).** When users reference examples by name (e.g., "run the gastown example"):

1. Read `examples/` to list available files
2. Match by partial name, keyword, or number
3. Run with: `prose run examples/28-gas-town.prose`

**Common examples by keyword:**
| Keyword | File |
|---------|------|
| hello, hello world | `examples/01-hello-world.prose` |
| gas town, gastown | `examples/28-gas-town.prose` |
| captain, chair | `examples/29-captains-chair.prose` |
| forge, browser | `examples/37-the-forge.prose` |
| parallel | `examples/16-parallel-reviews.prose` |
| pipeline | `examples/21-pipeline-operations.prose` |
| error, retry | `examples/22-error-handling.prose` |

### Remote Programs

You can run any `.prose` program from a URL or registry reference:

```bash
# Direct URL — any fetchable URL works
prose run https://raw.githubusercontent.com/openprose/prose/main/skills/open-prose/examples/48-habit-miner.prose

# Registry shorthand — handle/slug resolves to p.prose.md
prose run irl-danb/habit-miner
prose run alice/code-review
```

**Resolution rules:**

| Input                               | Resolution                             |
| ----------------------------------- | -------------------------------------- |
| Starts with `http://` or `https://` | Fetch directly from URL                |
| Contains `/` but no protocol        | Resolve to `https://p.prose.md/{path}` |
| Otherwise                           | Treat as local file path               |

**Steps for remote programs:**

1. Apply resolution rules above
2. Fetch the `.prose` content
3. Load the VM and execute as normal

This same resolution applies to `use` statements inside `.prose` files:

```prose
use "https://example.com/my-program.prose"  # Direct URL
use "alice/research" as research             # Registry shorthand
```

---

## File Locations

**Do NOT search for OpenProse documentation files.** All skill files are co-located with this SKILL.md file:

| File                       | Location                    | Purpose                                        |
| -------------------------- | --------------------------- | ---------------------------------------------- |
| `prose.md`                 | Same directory as this file | VM semantics (load to run programs)            |
| `help.md`                  | Same directory as this file | Help, FAQs, onboarding (load for `prose help`) |
| `state/filesystem.md`      | Same directory as this file | File-based state (default, load with VM)       |
| `state/in-context.md`      | Same directory as this file | In-context state (on request)                  |
| `state/sqlite.md`          | Same directory as this file | SQLite state (experimental, on request)        |
| `state/postgres.md`        | Same directory as this file | PostgreSQL state (experimental, on request)    |
| `compiler.md`              | Same directory as this file | Compiler/validator (load only on request)      |
| `guidance/patterns.md`     | Same directory as this file | Best practices (load when writing .prose)      |
| `guidance/antipatterns.md` | Same directory as this file | What to avoid (load when writing .prose)       |
| `examples/`                | Same directory as this file | 37 example programs                            |

**User workspace files** (these ARE in the user's project):

| File/Directory   | Location                 | Purpose                           |
| ---------------- | ------------------------ | --------------------------------- |
| `.prose/.env`    | User's working directory | Config (key=value format)         |
| `.prose/runs/`   | User's working directory | Runtime state for file-based mode |
| `.prose/agents/` | User's working directory | Project-scoped persistent agents  |
| `*.prose` files  | User's project           | User-created programs to execute  |

From visorcraft/IdleHands, MIT.

More from visorcraft/IdleHands