plain-forge

Authors and structures professional-grade agent skills following the agentskills.io spec. Use when creating new skill directories, drafting procedural instructions, or optimizing metadata for discoverability. Don't use for general documentation, non-agentic library code, or README files.

Add acceptance tests under a functional spec in a ***plain spec file. Use when the user wants to add verification criteria for a specific functional spec, or after adding a functional spec that needs testable success criteria.

Add a concept to the ***definitions*** section of a ***plain spec file. Use when the user wants to define a new concept, entity, or domain term in a .plain file.

End-to-end feature addition on an existing ***plain project: runs a short feature-intent interview, then takes the confirmed request and, one question at a time, incrementally writes ***plain specs (concepts, implementation reqs, functional specs, test reqs, acceptance tests) to disk — asking, authoring, and reviewing per functionality — then closes with a plain-healthcheck gate. Use when the user wants to add a feature to an existing project. Not for bootstrapping a new project from scratch (use forge-plain) or for editing generated code (the .plain specs are the source of truth).

Add a single functional spec to the ***functional specs*** section of a ***plain spec file. Use whenever exactly one new functional spec is being added — whether the user explicitly asks, or another skill/workflow (e.g. forge-plain, add-feature) needs to author a new functional spec. Every new entry under ***functional specs*** must go through either this skill or `add-functional-specs` (the bulk variant for adding multiple specs in one pass); hand-authoring functional specs without invoking one of these skills is forbidden.

Add multiple functional specs to the ***functional specs*** section of a ***plain spec file in a single batch. Use whenever more than one new functional spec is being added — whether the user explicitly asks, or another skill/workflow (e.g. forge-plain, add-feature) needs to author several specs in one pass. Bulk-writing or hand-authoring functional specs without invoking this skill is forbidden; for adding a single spec, use add-functional-spec instead.

Add an implementation requirement to the ***implementation reqs*** section of a ***plain spec file. Use when the user wants to add non-functional requirements like technology choices, architectural constraints, coding standards, data formats, error handling strategies, or any HOW-to-build guidance to a .plain file.

Add a linked resource (external file reference) to a ***plain spec. Use when the user wants to reference a JSON schema, API spec, data file, or other external file from within a functional spec, definition, or implementation requirement.

Add a test requirement to the ***test reqs*** section of a ***plain spec file. Use when the user wants to specify conformance testing instructions like test frameworks, execution methods, or testing constraints in a .plain file.

Analyze two functional specs from a ***plain spec file to determine if they conflict. Use when the user wants to check whether two specific functional requirements are compatible, or when debugging a suspected conflict between two specs.

Analyze a batch of functional specs from a ***plain spec file to determine which pairs conflict. Replaces the pair-by-pair `analyze-2-func-specs` flow when a caller wants to check many specs at once (e.g. a new spec against every existing spec, or a freshly inserted batch against itself).

Analyze a functional spec to determine if it is too complex for the renderer. A spec is too complex if it would produce more than 200 lines of code changes. Use after drafting a new functional spec (during `add-functional-spec`, or per spec during `add-functional-specs`) to verify it fits within the complexity limit before inserting it.

Break down a functional spec that is too complex into smaller specs that each imply ≤ 200 lines of code. Use when analyze-if-func-spec-too-complex flags a spec as TOO COMPLEX, or when a spec is suspected of being too large.

Create a ***plain import module that provides shared definitions, implementation reqs, and test reqs for other modules to import. Use when the user wants to create a new .plain file that contains only definitions, implementation reqs, and/or test reqs — no functional specs.

Create a ***plain module that uses requires to depend on another module in the build chain. Use when the user wants to create a new .plain file that builds on top of a previously built module, inheriting its functional specs and generated code as a starting point.

End-to-end `***plain` spec authoring workflow: a short intent interview followed by a gated, one-question-at-a-time interview (product, tech stack, testing) that writes complete .plain specification files to disk incrementally, reviews each addition, and validates the specs with a dry-run before handoff. Use when the user starts a new project or wants to build something new from scratch. Not for adding a feature to an existing project (use add-feature) or for editing generated code (the .plain specs are the source of truth).

Build / finalize the `config.yaml` file(s) that the `codeplain` renderer consumes. Pulls together every decision made during Phase 3 of `forge-plain` (script paths, template directory, build folders, copy/dest behavior, log settings) and emits one canonical `config.yaml` per part of the project. Run this at the **end of `forge-plain`** (just before `plain-healthcheck`), at the end of `add-feature` whenever the testing surface or template directory changed, and any time the user wants to regenerate / consolidate a project's `config.yaml`.

Lightweight initializer for a new ***plain project. Asks about the base technology and project kind, asks whether conformance testing is enabled, then scaffolds a template import module (with base implementation reqs and test reqs), a stub top-level module, the unit testing script, and (optionally) the conformance and prepare-environment scripts plus a config.yaml. Does NOT run `codeplain --dry-run`. Use when the user wants a quick project skeleton to start writing functional specs against, without the full forge-plain interview.

Loads the full `codeplain` CLI reference into context: the render command and its positional plain-file argument, every flag (render control, config, folders, test-script wiring, output copying, API, logging, headless mode), path-resolution rules, the CODEPLAIN_API_KEY environment variable, the config.yaml mapping, and the success/failure render banners. Use whenever running, configuring, resuming, or reasoning about a `codeplain` render or its config.yaml. Not for the ***plain language syntax itself (use load-plain-reference) or for supervising a live render (use run-codeplain).

Loads the applicable ***plain authoring rules and operational references for the current task. Covers section ownership, concepts, modules, resources, integrations, rendering, testing, and codeplain CLI behavior without loading unrelated guidance. Use when authoring, editing, reviewing, or debugging .plain files, or before invoking another skill that reads or writes .plain content.

Verification gate for a ***plain project. Verifies that every `config.yaml` exists, points at scripts that actually live in `test_scripts/`, and that `codeplain <top_module>.plain --dry-run` passes for every top module in the project. Run this whenever anything in the project is finalized — including (but not limited to) the end of `forge-plain`, the end of `add-feature`, after `debug-specs`, after any single-skill edit that finalizes a concept, functional spec, requirement, template, or config — and any time the user asks "is the project ready to render?".

Resolve a conflict between two functional specs in a ***plain spec file. Use when conformance tests for a previously passing spec start failing after a new spec is rendered, or when a potential conflict is detected while adding a new functional spec (via `add-functional-spec` or `add-functional-specs`).

Launch a `codeplain` render and supervise it end-to-end. Tails the log file, watches generated code appear under `plain_modules/`, and inspects the live TUI/process. Detects pathologies (stuck conformance loops, complexity errors, missing concepts, render failures), and — with user approval — stops the renderer, hands off to a spec-edit skill, and resumes with `--render-from`. Use whenever the user wants to actually render specs (not just dry-run) and wants supervision of the run.

Implement a conformance-test runner script (Bash on macOS/Linux, PowerShell on Windows) for an arbitrary programming language, in one of two variants: install-inline (when no prepare_environment_<lang> script exists) or activate-only (when one does). Use when the user wants to add a conformance-test runner for a new language (Node.js, Go, Rust, Flutter, etc.) to a ***plain project, or wants to regenerate / adapt one of the existing runners.

Implement a prepare-environment script (Bash on macOS/Linux, PowerShell on Windows) for an arbitrary programming language, following the same conceptual pattern as the bundled Java reference script in assets/. Use when the user wants to add a one-time per-build setup step (install deps, pre-build artifacts, populate caches) for a new language (Python, Node.js, Go, Rust, Flutter, etc.) to a ***plain project, or wants to regenerate / adapt the existing Java runner.

Implement a unit-test runner script (Bash on macOS/Linux, PowerShell on Windows) for an arbitrary programming language, following the same conceptual pattern as the bundled Java reference script in assets/. Use when the user wants to add a testing script for a new language (Python, Node.js, Go, Rust, etc.) to a ***plain project, or wants to regenerate / adapt the existing Java runner.

Read a ***plain project — its `.plain` files, `test_scripts/`, `config.yaml`(s), and `resources/` — and determine every command-line tool, runtime, package manager, and external service the project needs on the host machine. Probe the host for each one, then emit a `PASS` / `FAIL` report listing what's installed (with versions), what's missing, and concrete OS-specific install commands for the gaps. Run this any time someone is about to render, test, or onboard onto a ***plain project for the first time.

Investigate a bug observed in the running application by reading the generated code in plain_modules/, tracing the issue back to the specs, and fixing only the .plain files. Generated code is never modified. Use when the user reports unexpected behavior, visual glitches, crashes, or incorrect logic in the app.

Create or include a Liquid template in a ***plain spec file using {% include %} syntax. Use when the same spec content needs to be reused across multiple .plain files with different parameters.

Gather concept definitions scattered across multiple modules into a single shared import module in template/. Removes the moved definitions from the original modules and adds the new import to their frontmatter. Use when concepts are duplicated or spread across modules and should be centralized.

Split a large ***plain module into smaller modules grouped by logical domain. The resulting modules are connected via a requires chain so that functionality is 100% preserved. Use when a module has grown too large and its functional specs span multiple distinct concerns that would be clearer as separate modules.