From 7a266f170117d8a1bb15573f97398ec9af8826d0 Mon Sep 17 00:00:00 2001 From: Kaja Date: Mon, 6 Jul 2026 23:46:27 +0200 Subject: [PATCH 1/3] Rewrite README as a getting started guide Replace the outdated clone+pip install flow with the current uv-based installer, add the 3-step spec-driven workflow, and refresh the intro copy and example links to match the current *codeplain platform. --- README.md | 109 +++++++++++++++++++++++------------------------------- 1 file changed, 46 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 3d4858b..c600ac7 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,10 @@ -# Codeplain plain2code renderer +# *codeplain renderer -Render \*\*\*plain source to software code using the Codeplain API. +## What is \*codeplain? -## Codeplain.ai - Code Generation as a Service +\*codeplain makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code — this repository is the renderer that powers that last step, turning \*\*\*plain specs into software using the Codeplain API. The result is a software development workflow centered on specifications, which are faster and more efficient for AI to produce and easier for developers to review and maintain than raw code. -Codeplain is a platform that generates software code using large language models based on requirements you specify in \*\*\*plain specification language. - -Schematic overview of the Codeplain's code generation service +Schematic overview of the *codeplain's code rendering: @@ -20,100 +18,85 @@ An example application in \*\*\*plain ## Getting started -### Prerequisites +Get started in 15 minutes. -#### System requirements +### 1. Install \*codeplain in the terminal -To run the plain2code client, you need Python 3.11 or a later version. +macOS and Linux: -**Windows users:** Please install WSL (Windows Subsystem for Linux) as this is currently the supported environment for running plain code on Windows. +```bash +curl -fsSL https://codeplain.ai/install.sh | bash +``` + +Windows PowerShell: -#### Authorization - Codeplain API Key +```powershell +irm https://codeplain.ai/install.ps1 | iex +``` + +**Windows users:** Please install WSL (Windows Subsystem for Linux) as this is currently the supported environment for running plain code on Windows. -We are using Codeplain API Key to authorize requests to the Codeplain API. To get your Codeplain API Key, please contact Codeplain.ai support at support@codeplain.ai. +Follow the installation instructions to complete setup. The installer installs the `codeplain` CLI and walks you through setting your `CODEPLAIN_API_KEY`. -In order to generate code, you need to export the following environment variable: +If you'd rather not run the installer, sign up at [platform.codeplain.ai](https://platform.codeplain.ai) to get your API key and export it yourself: ```bash export CODEPLAIN_API_KEY="your_actual_api_key_here" ``` -### Installation Steps +### 2. Let your agent work in specs, not code -1. Clone this repository -2. Set your Codeplain API key as an environment variable: - ``` - export CODEPLAIN_API_KEY=your_api_key_here - ``` -3. (Recommended) Create and activate a virtual environment: - ```bash - python -m venv .venv - source .venv/bin/activate - ``` -4. Install required libraries - ``` - pip install -r requirements.txt - ``` +You describe what you want in plain English, an agent helps you write a spec in \*\*\*plain language, and \*codeplain renders the actual code. -### Quick Start +```bash +npx plain-forge install +``` -After completing the installation steps above, you can immediately test the system with a simple "Hello World" example: +### 3. Convert specs into tested and validated code + +\*codeplain extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code. + +```bash +codeplain your-project.plain +``` + +### Try it now + +You can immediately test the system with a simple "Hello World" example: - Change to the example folder and run the example: - ``` + ```bash cd examples/example_hello_world_python - python ../../plain2code.py hello_world_python.plain + codeplain hello_world_python.plain ``` _Note: Rendering will take a few minutes to complete._ - The system will generate a Python application in the `build` directory. You can run it with: - ``` + ```bash cd build python hello_world.py ``` -### Crash reporting - -If the plain2code client crashes unexpectedly, it sends an anonymous crash report to Codeplain to help improve the tool. To disable crash reporting, set the `CODEPLAIN_NO_TELEMETRY=1` flag. +### VS Code / Cursor extension +If you're using Visual Studio Code or Cursor IDE, we also recommend installing the [plyn extension](https://marketplace.visualstudio.com/items?itemName=Codeplain.plyn). -## Releasing +### Community and support -Releases are built and published with [uv](https://docs.astral.sh/uv/). The version is read from `_version.py`. +Share what you're building! Join the [\*codeplain Discord](https://discord.gg/cgbynb9hFq) if you have questions, ideas, or want to share what you built. -1. Bump the version in `_version.py`, commit it and create new tag (`git tag v`). -2. Build the distributions: - ```bash - uv build --python 3.11 - ``` - This produces `dist/codeplain--py3-none-any.whl` and `dist/codeplain-.tar.gz`. -3. (Optional) Smoke-test the wheel: - ```bash - uv run --with dist/codeplain--py3-none-any.whl --no-project -- codeplain --status - ``` -4. (Optional) Publish to TestPyPI first: - ```bash - uv publish --publish-url https://test.pypi.org/legacy/ dist/codeplain-* - ``` -5. Publish to PyPI: - ```bash - uv publish dist/codeplain-* - ``` - Authenticate with `UV_PUBLISH_TOKEN=pypi-...` (recommended), `--token pypi-...`, or `--username __token__ --password pypi-...`. -6. Push the `main` branch (with version commit) and push the tag: `git push origin v`. +Hit an edge case or have feedback? Reach us at [support@codeplain.ai](mailto:support@codeplain.ai). ## Additional Resources ### Examples and Sample Projects -- See the [examples](examples) folder for sample projects in Golang, Python, and React. -- For example application how to implement task manager in \*\*\*plain see [example-task-manager](https://github.com/Codeplain-ai/example-task-manager) repository. -- For example application how to implement SaaS connectors in \*\*\*plain see [example-saas-connectors](https://github.com/Codeplain-ai/example-saas-connectors) repository. +- See the [examples](examples) folder for sample projects in Golang, Python, React, and Flutter. +- For an example of how to implement Pong in \*\*\*plain, see the [pong](https://github.com/Codeplain-ai/plainlang-examples/tree/main/pong) example. +- For an example of how to implement a task manager in \*\*\*plain, see the [task-manager](https://github.com/Codeplain-ai/plainlang-examples/tree/main/task-manager) example. ### Documentation - For more details on the ***plain format, see the [***plain language specification](https://www.plainlang.org/docs/). -- For step-by-step instructions for creating your first ***plain project see the [Kickstart your ***plain project](docs/starting_a_plain_project_from_scratch.md). -- For complete CLI documentation and usage examples, see [plain2code CLI documentation](docs/plain2code_cli.md). From cf00e7964e5d067983bffea2972a27c6e1d0f0d6 Mon Sep 17 00:00:00 2001 From: Kaja Date: Mon, 6 Jul 2026 23:52:23 +0200 Subject: [PATCH 2/3] Move and expand the ***plain section, break up long paragraphs --- README.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index c600ac7..2819a46 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,15 @@ ## What is \*codeplain? -\*codeplain makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code — this repository is the renderer that powers that last step, turning \*\*\*plain specs into software using the Codeplain API. The result is a software development workflow centered on specifications, which are faster and more efficient for AI to produce and easier for developers to review and maintain than raw code. +\*codeplain makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code. -Schematic overview of the *codeplain's code rendering: - - +This repository is the renderer that powers that last step, turning \*\*\*plain specs into software using the *codeplain API. -### Abstracting Away Code Generation Complexity with \*\*\*plain +The result is a software development workflow centered on specifications, which are faster and more efficient for AI to produce and easier for developers to review and maintain than raw code. -\*\*\*plain is a novel specification language that helps abstracting away complexity of using large language models for code generation. - -An example application in \*\*\*plain +Schematic overview of the *codeplain's code rendering: - + ## Getting started @@ -89,6 +85,20 @@ Share what you're building! Join the [\*codeplain Discord](https://discord.gg/cg Hit an edge case or have feedback? Reach us at [support@codeplain.ai](mailto:support@codeplain.ai). +## Abstracting Away Code Generation Complexity with \*\*\*plain + +\*\*\*plain is the language of spec-driven development — a specification language that combines the efficiency of natural language with the control and precision of code. + +Structured sections for definitions, functional specs, implementation requirements, test requirements, and acceptance tests let your specs (not scattered docs or ad hoc prompts) become the source of truth for your software's behavior, abstracting away the complexity of using large language models for code generation. + +Specs are plain text, so they fit into the workflows you already use — version control, pull requests, and code review. + +See the [\*\*\*plain language guide](https://www.plainlang.org/docs/language-guide/) to learn the full syntax. + +An example application in \*\*\*plain + + + ## Additional Resources ### Examples and Sample Projects From aeb731557b60e3f360b458f8e3cbfd7b76069441 Mon Sep 17 00:00:00 2001 From: Kaja Date: Tue, 7 Jul 2026 12:30:58 +0200 Subject: [PATCH 3/3] Updated spelling in README.md --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2819a46..723b9a1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## What is \*codeplain? -\*codeplain makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code. +\*codeplain platform makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code. This repository is the renderer that powers that last step, turning \*\*\*plain specs into software using the *codeplain API. @@ -32,7 +32,7 @@ irm https://codeplain.ai/install.ps1 | iex **Windows users:** Please install WSL (Windows Subsystem for Linux) as this is currently the supported environment for running plain code on Windows. -Follow the installation instructions to complete setup. The installer installs the `codeplain` CLI and walks you through setting your `CODEPLAIN_API_KEY`. +Follow the installation instructions to complete setup. The installer installs the `codeplain` CLI, walks you through setting your `CODEPLAIN_API_KEY`, and offers to set up [plain-forge](#2-let-your-agent-work-in-specs-not-code) and the [plyn editor extension](#vs-code--cursor-extension) for you in the same session. If you'd rather not run the installer, sign up at [platform.codeplain.ai](https://platform.codeplain.ai) to get your API key and export it yourself: @@ -42,7 +42,9 @@ export CODEPLAIN_API_KEY="your_actual_api_key_here" ### 2. Let your agent work in specs, not code -You describe what you want in plain English, an agent helps you write a spec in \*\*\*plain language, and \*codeplain renders the actual code. +You describe what you want in plain English, an agent helps you write a spec in \*\*\*plain language, and \*codeplain renders the actual code. This is what [plain-forge](https://github.com/Codeplain-ai/plain-forge) sets up: a toolkit of skills, rules, and docs that plugs into your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, or any other agent that reads from a standard skills directory — and turns a conversation into a complete `.plain` spec, then keeps maintaining it across the lifetime of the project. + +If you didn't install it during step 1, run it any time: ```bash npx plain-forge install @@ -77,7 +79,7 @@ You can immediately test the system with a simple "Hello World" example: ### VS Code / Cursor extension -If you're using Visual Studio Code or Cursor IDE, we also recommend installing the [plyn extension](https://marketplace.visualstudio.com/items?itemName=Codeplain.plyn). +If you're using Visual Studio Code or Cursor IDE, we also recommend installing the [plyn extension](https://marketplace.visualstudio.com/items?itemName=Codeplain.plyn) for `***plain` syntax highlighting. The installer in step 1 offers to install it automatically if it detects `code` or `cursor` on your `PATH`. ### Community and support