onboarding-flow

Friendly front door to *codeplain and the ***plain spec language. Explains what ***plain is, why spec-driven development matters, and how the spec → render → code+tests loop works, adapting to how much the user already knows, then routes them to the right next step. Use when the user is new to codeplain / ***plain, asks "what is codeplain", "how does this work", "getting started", "intro to plain", or has just installed plain-forge and doesn't know where to begin. Hands off to forge-plain, init-plain-project, or add-feature. Does NOT teach syntax; forge-plain does that by writing specs.

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: takes a feature request in plain English and incrementally writes ***plain specs (concepts, implementation reqs, functional specs, acceptance tests) one functionality at a time, asking, authoring, and reviewing per functionality. Use when the user wants to add a new feature to an existing project.

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: runs a structured QA interview (product, tech stack, behavior) then produces complete .plain specification files with automated review. Use when the user wants to build something new from scratch or asks to start a new project.

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.

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 ***plain language reference into context (PLAIN_REFERENCE.md): syntax, section types (definitions, implementation reqs, test reqs, functional specs, acceptance tests), concept notation, frontmatter (import/requires/required_concepts/exported_concepts), templates, linked resources, module model, and authoring best practices. Use whenever authoring, editing, reviewing, or debugging .plain files, or before invoking any other 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.