/prose-reader

namespace: aiwg
name: prose-reader
description: Read and parse an OpenProse program file, extracting its contract (requires, ensures, strategies, errors, invariants) and services into a structured representation
version: 0.1.0
platforms: [all]

Prose Reader Skill

You read and parse OpenProse program files (`.md` with contract semantics), extracting the full contract specification into a structured, human-readable summary.

Triggers

• "read prose program" / "parse prose file"
• "what does [file] require and ensure"
• "show me the contract for [file]"
• "extract prose contract from [path]"
• "what are the inputs and outputs of [program]"

Input

A path to a `.md` file that is an OpenProse program (has `requires:` and/or `ensures:` sections).

Behavior

Given a path to an OpenProse program file:

Step 0: Detect OpenProse Installation

Before any operation, run `/prose-detect` to locate the OpenProse installation and resolve `PROSE_ROOT`. `/prose-detect` handles the full detection chain (env var, AIWG config, AIWG-local install, project plugin manifest, user home, global CLI).

If `/prose-detect` reports no installation found, do NOT auto-clone. Inform the user:

OpenProse not found. Run /prose-setup to install it, or set PROSE_ROOT to an existing installation.

Step 1: Read the File

Read the target file using the Read tool.

Step 2: Parse Frontmatter

Extract YAML frontmatter fields:

• `name` — program name
• `kind` — `program`, `service`, `library`, or `test`
• `services` — list of service component names (multi-service programs only)
• `model` — preferred model if specified
• Any other frontmatter fields

Step 3: Extract Contract Elements

Parse the markdown body for contract sections. Each section uses a specific keyword followed by a colon and a list:

| Section | Keyword | Format | Meaning | |---------|---------|--------|---------| | Inputs | `requires:` | `- name: description` | What the program needs to run | | Outputs | `ensures:` | `- name: description` | What the program commits to produce (obligation) | | Conditional behavior | `strategies:` | `- when condition: action` | How to handle specific situations | | Failure channels | `errors:` | `- condition description` | When the program cannot proceed | | Invariants | `invariants:` | `- property description` | Properties that always hold |

Step 4: Identify Services

If `kind: program` and `services:` is present in frontmatter:

• List each service name
• Check if corresponding `.md` file exists in the same directory
• Note any missing service files

Step 5: Output Structured Summary

Format the extracted information as:

## Program: {name}

**Kind**: {kind}
**Services**: {services list or "single-component"}
**Model**: {model or "not specified"}

### Requires (Inputs)
| Name | Description |
|------|-------------|
| {name} | {description} |

### Ensures (Outputs — Obligations)
| Name | Description |
|------|-------------|
| {name} | {description} |

### Strategies
- when {condition}: {action}

### Errors
- {error condition}

### Invariants
- {invariant property}

### Services
| Service | File | Exists |
|---------|------|--------|
| {name} | {name}.md | {yes/no} |

Edge Cases

• **No `requires:`**: Report as "No declared inputs (implicit)"
• **No `ensures:`**: Flag as warning — all valid programs should have ensures
• **Conditional ensures**: `ensures:` entries with `when` clauses — parse and display the condition
• **Nested services**: If a service itself has `services:`, note the nesting
• **Legacy `.prose` files**: Treat identically to `.md` files

Model

This skill runs on **Sonnet** — parsing and extraction don't require complex reasoning.

References

• @$AIWG_ROOT/agentic/code/addons/prose-integration/README.md — prose-integration addon overview
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/research-before-decision.md — Run prose-detect before reading any program file
• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/instruction-comprehension.md — Extract all contract fields; do not skip optional sections
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference for AIWG addon integration commands