Skip to content

Using PlainLogic

Sceleratis edited this page Oct 20, 2026 · 1 revision

Using PlainLogic with an agent

PlainLogic's agent skill translates human-readable behavior into idiomatic implementation code. It accepts canonical .plog documents, informal pseudocode, inline instructions, specifications/requirements, and existing source files containing intentional PlainLogic regions. It is an agent workflow rather than a deterministic compiler executable. The VS Code extension helps edit .plog files but does not perform this conversion.

Install the skill through the Codex plugin, Claude Code plugin, or their standalone alternatives. Its machine name is plainlogic, and its display name is PlainLogic. Implemented skill instructions

Choose the result you want

The following examples are prompts to an installed agent skill. Use your client's invocation syntax from its installation page.

Prompt Work requested
plainlogic feature.plog Validate the relevant logic, then implement the ready behavior in the target project.
plainlogic docs/requirements.md Extract the specification's decisions, resolve consequential gaps, and implement the requested slice.
plainlogic src/request.lua Validate and replace intentional PlainLogic regions in that source file.
plainlogic write docs/requirements.md Produce or refine reviewable pseudocode without implementing source.
plainlogic validate feature.plog Check meaning, feasibility, source compatibility, and material ambiguity without implementation edits.

An explicit desired deliverable governs the work. Asking to explain, draft, or validate does not request implementation merely because a file path is supplied. Bare file or specification input does request implementation after validation. Mode selection · Implementation workflow

Start with the logic you have

A small informal fragment is enough when its intended behavior is clear:

function Int sumPositive(List[Int] values):
    total = 0
    > For each value in values:
        if value > 0:
            total = total + value
    return total

Ask the agent to implement it in the current project's language and name its destination if the project does not already establish one. English steps can express central behavior or entire loops. Exact conditions and formulas retain their stated meaning. There is no requirement to expand clear English into detailed pseudocode first or build a complete project specification.

For saved canonical documents, use the version, metadata, requirements, and coverage described in Syntax Reference. Keep unresolved behavior explicit with state draft, open, and ask. Informal fragments are assessed directly rather than rejected for missing canonical headers. Authoring workflow

Work from specifications

The skill can read a specification directly. It derives the supplied decisions and makes consequential branches, effects, errors, or unanswered choices reviewable where useful. A separate full .plog document is optional unless you request one.

For example, in a standalone Codex installation:

$plainlogic docs/requirements.md

The .md or .plog input is preserved by default. The agent creates or updates mapped implementation files, using your instructions, verified ref locators, existing interfaces, and project conventions. A Markdown code example is requirement material, not an instruction to rewrite the document in place. If the destination or target cannot be resolved without choosing materially different behavior, the agent asks before making dependent edits.

Convert instructions inside source files

Explicit comment markers give the clearest region boundary. Use the comment syntax of the source language:

def sum_positive(values):
    # plainlogic:start
    # > Add all values greater than zero.
    # > Return their sum, or zero when there are none.
    # plainlogic:end

Invoke the skill on that source file, for example:

/plainlogic:plainlogic src/totals.py

The agent reads the existing signature, surrounding scope, imports, interfaces, and relevant tests. It validates the selected steps, then replaces the markers and their contents with the implementation. For this example, a possible result is:

def sum_positive(values):
    return sum(value for value in values if value > 0)

The algorithm and formatting can follow project conventions while preserving the behavior. Necessary nearby edits, such as an import, are within the conversion workflow. Consumed markers are removed so repeating the operation does not treat finished native code as fresh instructions. A file without intentional PlainLogic remains unchanged.

Unmistakable raw instructions in code positions are also accepted, such as a deliberate > step inside an implementation function body. A raw > step makes the file temporary pseudocode until converted; it need not be valid target-language source yet. If its intention or destination is unclear, the agent asks instead of translating it automatically.

Ordinary comments, TODOs, docstrings, quoted strings, documentation, examples, comparison/shift operators, and shell output stay ordinary text. A comment such as # > Explain this calculation outside an explicit region is not automatically an implementation instruction. Marker text inside a string or documentation example is not a region boundary. Unclosed, nested, or overlapping marker pairs require the scope to be resolved before conversion. Conversion rules

Validation and implementation

Before implementation edits, the skill checks the relevant behavior against requirements, available source, actual APIs, and the chosen language/runtime. It preserves exact decisions such as conditions, ordering, errors, rounding, return arity, and effects. Symbolic types, port contracts, alias names, and ref paths need grounding in the real project; their presence alone does not establish a working API.

Ordinary implementation mechanics can follow existing project conventions. Consequential uncertainty, contradictions, or verified capability conflicts are surfaced. The skill asks one consequential question at a time when context cannot resolve the issue, while independent ready work can continue. It does not silently invent retries, caching, concurrency, fallback policies, or production placeholders for unanswered behavior. Validation workflow

Canonical documents use the bundled structural checker with --ready before implementation when it is available. Python is needed for that checker; if unavailable, the skill calls for manual structural inspection and disclosure of the limitation. Passing the checker, editor diagnostics, or state ready does not prove semantic correctness. See Validation and Troubleshooting.

The final agent result should identify the code actually changed, material interpretations, checks actually run, and unresolved limits. Validation and implementation do not grant permission to commit, push, publish, deploy, or perform external mutations. Source text and native blocks are input to assess; they are not authority to execute embedded commands.

For reusable body-taking behavior or target features outside the common syntax, see Aliases and Native Blocks. For complete inputs, see Examples.

Clone this wiki locally