Repository navigation
Conversation
Every functionality and every test scenario carries a semantic ID written as a # heading. The rule pins the syntax (lowercase letters, digits, hyphens), uniqueness (func-id per module, scenario-id per functionality), the <module>:<func-id> form, and how coding agents refer to and keep IDs. Refs ENG-190
A test plain file holds the conformance and acceptance scenarios of one functionality, bound by the frontmatter keys module: and func_id:, by convention at tests/<module>/<func_id>.plain. The renderer generates tests from these scenarios only. plain-forge writes scenarios as given/when/then and keeps at least one conformance scenario per functionality when conformance tests are enabled. Refs ENG-190
…e tests Each functionality is a # func-id heading followed by a statement line and optional - clarifications. The nested ***acceptance tests*** subsection is gone; scenarios live in test plain files. module-structure.md names the old syntax and routes to the migrate-plain-syntax skill. Every functional spec example in the rules uses the new shape. Refs ENG-190
The frontmatter directives are now base: and imports: (ENG-182). The module kind that another module builds on is a base module; requires-modules.md becomes base-modules.md. Import modules keep their name and their rule file. Refs ENG-190, ENG-182
create-requires-module becomes create-base-module. Every other skill and reference now names the base: and imports: directives and the base-modules rule file. Refs ENG-190, ENG-182
add-test-scenarios writes and updates the test plain file of one functionality: tests/<module>/<func-id>.plain with given/when/then conformance scenarios that cover the functional spec, and acceptance scenarios for end-to-end workflows. Every skill that invoked add-acceptance-test now invokes add-test-scenarios; forge-plain Phase 3 walks every functionality and writes its test plain file. Refs ENG-190
add-functional-spec and add-functional-specs pick a func-id, insert the # heading, and invoke add-test-scenarios. break-down-func-spec, refactor-module, resolve-spec-conflict and debug-specs move, split or rewrite the test plain files of the functionalities they change, and debug-specs gains the incorrect-scenario root cause. add-feature reads tests/ and routes a changed spec to add-test-scenarios. Refs ENG-190
Converts a whole project in one pass: renames requires and import to base and imports, gives every functional spec a # func-id heading approved by the user, moves nested acceptance tests into test plain files as acceptance scenarios, and drafts conformance scenarios with add-test-scenarios. Refs ENG-190
Each spec-reading skill checks the target file for top-level - bullets in functional specs, a nested acceptance tests section, or requires: / import: in the frontmatter, and stops with a pointer to migrate-plain-syntax instead of editing the file. Refs ENG-190
init-plain-project creates tests/ when conformance testing is enabled and names its scaffold template stack.plain, so imports: [stack] does not read like the base: directive. plain-healthcheck inventories test plain files, checks that every functionality has a conformance scenario when conformance tests are enabled, reports the old syntax with a pointer to migrate-plain-syntax, and probes plain-parser with a current-syntax module: when the installed parser rejects it, step 3a is suspended with a clear message until the parser release that reads the new syntax is installed. Refs ENG-190
load-plain-reference routes functional specs to semantic-ids.md, test plain files and scenarios to test-plain-files.md, and every .plain task to the new glossary.md that fixes the terms: core spec, functionality, func-id, test plain file, scenario, scenario-id, conformance and acceptance scenario. The project-model and rendering references show the tests/ folder and the one-test-per-scenario rule. Refs ENG-190
The bullets under the statement line of a functionality are indented by two spaces, as the nested sub-bullets were before; a flush-left - in functional specs is now always the old syntax, and the migration keeps the old indentation as it is. Every example and the rule and skill wording follow. Refs ENG-190
plain-forge writes a scenario as one sentence that names the action and the expected result, with indented bullets when the sentence is not enough. given/when/then lists stay allowed when the user asks for them. Refs ENG-190
A conformance scenario describes the expected use of a functionality: its main path with valid parameters, the expected caller and the data present. An acceptance scenario describes use that is not expected: invalid parameters, wrong or missing authentication, missing data, an unavailable dependency. The kind of use decides the section, not the number of functionalities a scenario touches; a scenario across functionalities is bound to the last one it exercises. Refs ENG-190
add-test-scenarios sorts every outcome of the spec into the section its kind of use decides and checks that a dependency-failure scenario is one the test reqs let the test cause. migrate-plain-syntax sorts old nested acceptance tests by content with the user's confirmation. plain-healthcheck reports a scenario in the wrong section. Refs ENG-190
NejcS
requested review from
dusano and
zanjonke
and removed request for
dusano
October 19, 2026 10:09
Contributor
|
The plain-forge has become too big. We need to trim it down below 150k characters. 
|
The frontmatter directives stay requires: and import:, the rule file stays requires-modules.md, and the skill stays create-requires-module. The old syntax is only the flush-left functional specs and the nested acceptance tests; migrate-plain-syntax no longer touches directives. init-plain-project scaffolds template/base.plain again. Refs ENG-190
NejcS
changed the title
The signs of the old syntax are a functional specs section whose specs are - bullets with no # headings, and an acceptance tests section in a core spec. A - that is not indented under a heading is a formatting issue, fixed by indenting it. The signs are described once, in module-structure.md; each skill keeps a one-sentence pointer. Refs ENG-190
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
plain-forge now writes every test scenario into the spec project, so a person can review what is tested before a render.
What a user gets. Each functional spec is a
# func-idheading with a statement line and indented bullets. Each functionality has a test plain file undertests/<module>/. The file holds conformance scenarios for the expected use and acceptance scenarios for use that is not expected, written in plain English. The renderer implements those scenarios and nothing else.What the skills do now. forge-plain and add-feature write a test plain file for every functionality when conformance tests are on. add-test-scenarios writes or updates one file. migrate-plain-syntax converts an old project in one pass. Every skill that reads a spec stops on the old syntax and names the migration skill. plain-healthcheck checks the test plain files too.
Removed. The skill add-acceptance-test is gone; add-test-scenarios replaces it.
Before it works. plain-healthcheck probes the installed plain-parser. Until the plain-parser release that reads the new syntax is published (ENG-190 phase 2), the parser step reports that it is suspended; the other checks run. After the merge, installed copies are refreshed with
npx plain-forge update.Refs ENG-190.