Skip to content

Getting Started

Sceleratis edited this page Oct 20, 2026 · 1 revision

Getting started

Choose the part you need:

Goal Start with
Write and inspect .plog files VS Code extension
Turn logic or requirements into code Codex or Claude Code plugin
Check a canonical document's structure Optional Python checker below
Describe behavior without learning the whole format An informal function with English steps

You do not need both the extension and the skill. A full project specification is also unnecessary: start with one routine or feature slice.

A small informal input

function Int sum_positive(List[Int] values):
    > Start a local total at zero.
    > For each value in values:
        if value > 0:
            > Add value to total.
    > Return total.

The agent can interpret this directly. It does not need a metadata header or a second draft expanding every sentence into code. The editor recognizes informal signatures, but the canonical Python checker expects a full document.

A complete canonical document

Save the following as sum-positive.plog in the project where you want its implementation. The target here is an explicit example choice.

plainlogic 0.3
unit SumPositive
state ready

target "Python 3"
intent "Sum strictly positive integer inputs."
scope "Pure arithmetic over caller-supplied integers; no validation or I/O."
require R1 "Return the sum of positive values, or zero when none qualify."

fn sum_positive(values: List[Int]) -> Int:
    covers R1
    total = 0
    for value in values:
        if value > 0:
            > Add value to total.
    return total

case empty:
    given values = []
    expect sum_positive(values) == 0

case mixed:
    given values = [-4, 0, 3, 5]
    expect sum_positive(values) == 8

The exact comparison fixes the positive boundary. The English step supplies the accumulation operation. Cases record expected behavior; the tools do not run them as tests.

Ask an agent to implement it

With a Codex plugin installation, select PlainLogic from the skill picker or write:

Use PlainLogic on sum-positive.plog in this project.

With the Claude Code plugin:

/plainlogic:plainlogic sum-positive.plog

A standalone Codex skill uses $plainlogic sum-positive.plog; a standalone Claude skill uses /plainlogic sum-positive.plog. These are agent invocations, not shell compiler commands.

Bare input selects validated implementation. The agent uses the target declaration and project context to map the routine to code. It preserves the input document by default, reuses existing interfaces where applicable, and asks about material output or behavior choices that the context cannot settle.

To stop at logic or review, say so:

Use PlainLogic to write logic from docs/requirements.md.
Use PlainLogic to validate sum-positive.plog without implementing it.

See Using PlainLogic for specifications and source-file conversion.

Optionally check the canonical document

From a checkout of the main PlainLogic repository:

python tools/check_plainlogic.py path/to/sum-positive.plog --ready

Use the document's actual path, including an absolute path if it is in another project. A standalone installed skill contains the same checker under its scripts/ directory.

This example should report no structural errors and an advisory about prose. That advisory is expected: the English still needs semantic review. The ready label and a clean structural check do not establish implementation correctness or approve external actions.

Next: Syntax reference · Examples

Source: main skill, checker, and mixed example.

Clone this wiki locally