@miadi/rispecs-builder

Compile a repository's RISE specification corpus into deterministic Markdown that a person or agent can carry into implementation work.

The package has one compiler and three entry points:

• library: buildRispecs() and inspectRispecs();
• CLI: miadi-rispecs-builder;
• MCP stdio server: miadi-rispecs-builder-mcp or the CLI's mcp command.

Default contract

Run the CLI from a repository root:

miadi-rispecs-builder

It reads regular *.md files recursively from ./rispecs, in stable source-path order, and writes:

.miadi/rispecs/
├── manifest.json
├── full/
│   └── all.md
└── per-subfolder/
    ├── _root.md        # only when rispecs/*.md exists
    ├── a2a.md
    ├── miadi-code.md
    └── ...             # one file per immediate rispecs/ subfolder

Each source begins with a visible ## Source: <relative path> boundary. This keeps provenance intact when the compilation becomes an agent's context. Symlinks and non-Markdown files are not followed or copied.

No timestamp is written. With unchanged source bytes and paths, a rebuild produces unchanged Markdown.

CLI

Install globally:

npm install --global @miadi/rispecs-builder
miadi-rispecs-builder build

Or run without a global installation:

npx -y -p @miadi/rispecs-builder miadi-rispecs-builder build

Commands and modes:

# Build both projections (the default command and default mode)
miadi-rispecs-builder
miadi-rispecs-builder build --mode all

# Build one projection
miadi-rispecs-builder build --mode full
miadi-rispecs-builder build --mode per-subfolder

# Discover the compilation plan without writing
miadi-rispecs-builder inspect

# Use another working directory or source/output root
miadi-rispecs-builder build --cwd /work/project
miadi-rispecs-builder build --source ./specifications --output ./.agent/rispecs

# Machine-readable result
miadi-rispecs-builder inspect --json

Relative --source and --output values resolve from --cwd. Source and output trees cannot overlap. Existing unrelated files are not deleted.

MCP

Example client configuration using the published package:

{
  "mcpServers": {
    "miadi-rispecs-builder": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@miadi/rispecs-builder",
        "miadi-rispecs-builder-mcp"
      ],
      "cwd": "/path/to/repository"
    }
  }
}

The MCP server exposes:

| Kind | Name | Purpose | |---|---|---| | tool | rispecs_inspect | Resolve paths and list source/group counts without writing | | tool | rispecs_build | Build full, per-subfolder, or all projections | | resource | rispecs://manifest | Read the latest manifest or pre-build inspection | | resource | rispecs://compiled/full | Read full/all.md | | resource template | rispecs://compiled/per-subfolder/{name} | Enumerate/read per-subfolder compilations | | prompt | implementation_from_rispecs | Guide RISE-to-code parity work with source traceability |

miadi-rispecs-builder mcp --cwd /path/to/repository starts the same server. The resources are rooted at the server's configured working directory. Tool path overrides are useful for one-off builds; restart the server with that working directory when those outputs should become its resource surface.

Library

import { buildRispecs, inspectRispecs } from "@miadi/rispecs-builder";

const plan = await inspectRispecs({ cwd: process.cwd() });
const result = await buildRispecs({
  cwd: process.cwd(),
  mode: "all",
});

Both functions return absolute resolved paths and deterministic source/group metadata. buildRispecs() also returns every output and writes manifest.json.

RISE parity workflow

1. Inspect the corpus and choose the smallest adequate projection.
2. Build it and read the manifest plus compiled Markdown.
3. Name the Desired Outcome and Current Reality before editing code.
4. Trace each implementation decision to the preserved source path.
5. Verify behavior with the codebase's own tests and state remaining parity.

The builder assembles prose-code; it does not invent, summarize, rank, or rewrite specifications. That boundary keeps the source corpus authoritative.

Development

From the Miadi workspace:

pnpm install
pnpm --filter @miadi/rispecs-builder build
pnpm --filter @miadi/rispecs-builder type-check
pnpm --filter @miadi/rispecs-builder test

Issue and RISE contracts: jgwill/Miadi#627 and SPEC-LINKS.md.

🌸 One corpus can now become a whole horizon or a set of smaller paths, while every sentence remembers the source relation it came from.