plain-forge 1.0.17 → 1.0.19

package/forge/skills/analyze-2-func-specs/SKILL.md

@@ -31,8 +31,8 @@ Work through each question. If any answer is "yes", the specs likely conflict.
 Do the two specs make mutually exclusive assertions about the same behavior?
 
 ```
-Spec A: The system should return :Resource: items sorted by name in ascending order.
-Spec B: The system should return :Resource: items sorted by creation date in descending order.
+Spec A: :Resource: items are returned sorted by name in ascending order.
+Spec B: :Resource: items are returned sorted by creation date in descending order.
 
 Verdict: CONFLICTING — both define the sort order for the same response,
 but specify different fields and directions. A single implementation cannot
@@ -44,8 +44,8 @@ satisfy both unless scoped to different contexts.
 Does one spec set a state or value that the other spec assumes is different?
 
 ```
-Spec A: :TaskList: should initially be empty.
-Spec B: :TaskList: should contain a default "Welcome" :Task: on first load.
+Spec A: :TaskList: is initially empty.
+Spec B: :TaskList: contains a default "Welcome" :Task: on first load.
 
 Verdict: CONFLICTING — both define the initial state of :TaskList: differently.
 ```
@@ -55,8 +55,8 @@ Verdict: CONFLICTING — both define the initial state of :TaskList: differently
 Does the later spec silently replace behavior established by the earlier spec without acknowledging it?
 
 ```
-Spec A: The system should validate :User: credentials using an API key.
-Spec B: The system should validate :User: credentials using OAuth 2.0.
+Spec A: :User: credentials are validated using an API key.
+Spec B: :User: credentials are validated using OAuth 2.0.
 
 Verdict: CONFLICTING — both define the authentication mechanism but pick
 different approaches. The later spec overrides the earlier one.
@@ -67,8 +67,8 @@ different approaches. The later spec overrides the earlier one.
 Are the two specs ambiguous enough that a renderer could interpret them as conflicting, even if the user intends them to be complementary?
 
 ```
-Spec A: The system should return all :Resource: items.
-Spec B: The system should return only active :Resource: items.
+Spec A: All :Resource: items are returned.
+Spec B: Only active :Resource: items are returned.
 
 Verdict: CONFLICTING (ambiguous) — "all" vs "only active" appear contradictory.
 Could be resolved by scoping each to different conditions (e.g., filtered vs unfiltered).
@@ -79,8 +79,8 @@ Could be resolved by scoping each to different conditions (e.g., filtered vs unf
 Do both specs impose constraints on the same `:Concept:` that cannot coexist?
 
 ```
-Spec A: :BatchSize: should be 100 items.
-Spec B: :BatchSize: should be 50 items for :Resource: types with attachments.
+Spec A: :BatchSize: is 100 items.
+Spec B: :BatchSize: is 50 items for :Resource: types with attachments.
 
 Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
 ```

package/forge/skills/analyze-func-specs/SKILL.md

@@ -41,8 +41,8 @@ Work through each question for the pair under inspection. If any answer is "yes"
 Do the two specs make mutually exclusive assertions about the same behavior?
 
 ```
-Spec A: The system should return :Resource: items sorted by name in ascending order.
-Spec B: The system should return :Resource: items sorted by creation date in descending order.
+Spec A: :Resource: items are returned sorted by name in ascending order.
+Spec B: :Resource: items are returned sorted by creation date in descending order.
 
 Verdict: CONFLICTING — both define the sort order for the same response,
 but specify different fields and directions. A single implementation cannot
@@ -54,8 +54,8 @@ satisfy both unless scoped to different contexts.
 Does one spec set a state or value that the other spec assumes is different?
 
 ```
-Spec A: :TaskList: should initially be empty.
-Spec B: :TaskList: should contain a default "Welcome" :Task: on first load.
+Spec A: :TaskList: is initially empty.
+Spec B: :TaskList: contains a default "Welcome" :Task: on first load.
 
 Verdict: CONFLICTING — both define the initial state of :TaskList: differently.
 ```
@@ -65,8 +65,8 @@ Verdict: CONFLICTING — both define the initial state of :TaskList: differently
 Does the later spec silently replace behavior established by the earlier spec without acknowledging it?
 
 ```
-Spec A: The system should validate :User: credentials using an API key.
-Spec B: The system should validate :User: credentials using OAuth 2.0.
+Spec A: :User: credentials are validated using an API key.
+Spec B: :User: credentials are validated using OAuth 2.0.
 
 Verdict: CONFLICTING — both define the authentication mechanism but pick
 different approaches. The later spec overrides the earlier one.
@@ -77,8 +77,8 @@ different approaches. The later spec overrides the earlier one.
 Are the two specs ambiguous enough that a renderer could interpret them as conflicting, even if the user intends them to be complementary?
 
 ```
-Spec A: The system should return all :Resource: items.
-Spec B: The system should return only active :Resource: items.
+Spec A: All :Resource: items are returned.
+Spec B: Only active :Resource: items are returned.
 
 Verdict: CONFLICTING (ambiguous) — "all" vs "only active" appear contradictory.
 Could be resolved by scoping each to different conditions (e.g., filtered vs unfiltered).
@@ -89,8 +89,8 @@ Could be resolved by scoping each to different conditions (e.g., filtered vs unf
 Do both specs impose constraints on the same `:Concept:` that cannot coexist?
 
 ```
-Spec A: :BatchSize: should be 100 items.
-Spec B: :BatchSize: should be 50 items for :Resource: types with attachments.
+Spec A: :BatchSize: is 100 items.
+Spec B: :BatchSize: is 50 items for :Resource: types with attachments.
 
 Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
 ```

package/forge/skills/analyze-if-func-spec-too-complex/SKILL.md

@@ -31,20 +31,40 @@ A drafted functional spec (not yet inserted into the file), plus the full contex
 
 Work through each indicator. A single "yes" does not automatically mean the spec is too complex, but multiple "yes" answers are a strong signal.
 
+### 0. First-Spec Bootstrap Cost
+
+Is this the first functional spec in a new root module with no implementation baseline supplied by
+`requires`? If so, include the implicit cost of creating the project structure, package metadata,
+framework configuration, entry point, initial source files, and unit-test infrastructure.
+
+The first spec must be substantially simpler than a later spec. It should expose one minimal,
+deterministic capability that can be invoked and tested. Setup without an observable result is not
+acceptable, but combining bootstrap work with persistence, integrations, multiple interfaces,
+branching workflows, or cross-cutting behavior is a strong `TOO COMPLEX` signal.
+
 ### 1. Number of Distinct Behaviors
 
 Does the spec describe more than one independently testable behavior?
 
-```
 Too complex:
-- :User: should be able to create, edit, delete, and archive :Task: items,
-  with validation on all fields and confirmation dialogs for destructive actions.
+```plain
+***functional specs***
+
+- A :User: can create, edit, delete, and archive :Task: items, with validation on all fields and confirmation dialogs for destructive actions.
+```
 
 Acceptable (one behavior each):
-- :User: should be able to create :Task:. Only valid :Task: items can be added.
-- :User: should be able to edit :Task:.
-- :User: should be able to delete :Task:.
-- :User: should be able to archive :Task:.
+```plain
+***functional specs***
+
+- A :User: can create :Task:. Only valid :Task: items can be added.
+
+- A :User: can edit :Task:.
+
+- A :User: can delete :Task:.
+
+- A :User: can archive :Task:.
+
 ```
 
 ### 2. Number of Concepts Introduced or Modified
@@ -59,18 +79,23 @@ Does the spec require introducing new data structures, UI components, API endpoi
 
 Does the spec describe multiple conditional paths, modes, or special cases?
 
-```
+
 Too complex:
-- The system should process :Order: differently based on :OrderType:.
-  Standard orders are validated and stored. Express orders skip validation
-  and are queued for immediate dispatch. Bulk orders are split into
-  sub-orders of 100 items each, validated individually, and processed
-  in parallel with progress tracking.
+```plain
+***functional specs***
+
+- :Order: processing depends on :OrderType:. Standard orders are validated and stored. Express orders skip validation and are queued for immediate dispatch. Bulk orders are split into sub-orders of 100 items each, validated individually, and processed in parallel with progress tracking.
+```
 
 Acceptable (separate the modes):
-- The system should process standard :Order: by validating and storing it.
-- The system should process express :Order: by queuing it for immediate dispatch without validation.
-- The system should process bulk :Order: by splitting it into sub-orders of 100 items each.
+```plain
+***functional specs***
+
+- A standard :Order: is validated and stored.
+
+- An express :Order: is queued for immediate dispatch without validation.
+
+- A bulk :Order: is split into sub-orders of 100 items each.
   - Each sub-order is processed individually.
 ```
 
@@ -78,32 +103,43 @@ Acceptable (separate the modes):
 
 Does the spec bundle core functionality with cross-cutting concerns like error handling, logging, retry logic, pagination, or caching?
 
-```
 Too complex:
-- The system should fetch :Resource: items from the external API with
-  pagination support, retry on transient errors with exponential backoff,
-  cache results for 5 minutes, and log all API calls.
+```plain
+***functional specs***
+
+- :Resource: items are fetched from the external API with pagination support, retry on transient errors with exponential backoff, caching for 5 minutes, and logging of all API calls.
+```
 
 Acceptable (separate concerns):
-- The system should fetch :Resource: items from the external API.
-- The system should paginate when fetching :Resource: items from the external API.
-- The system should retry fetching :Resource: on transient errors using exponential backoff.
+```plain
+***functional specs***
+- :Resource: items are fetched from the external API.
+
+- :Resource: items are fetched from the external API in pages.
+
+- Fetching :Resource: items is retried on transient errors using exponential backoff.
 ```
 
 ### 5. UI Complexity
 
 Does the spec describe a complete screen or page with multiple interactive elements, layouts, and state transitions?
 
-```
 Too complex:
-- Display a dashboard showing :User: profile, recent :Task: items in a
-  sortable table, a notification bell with unread count, and a sidebar
-  with navigation links that highlights the active page.
+```plain
+***functional specs***
+
+- The dashboard shows :User: profile, recent :Task: items in a sortable table, a notification bell with unread count, and a sidebar with navigation links that highlights the active page.
+```
 
 Acceptable (build incrementally):
-- Display a dashboard page for :User:.
-- Show recent :Task: items in a sortable table on the dashboard.
-- Show a notification indicator with the unread count on the dashboard.
+```plain
+***functional specs***
+
+- A dashboard page is shown for :User:.
+
+- Recent :Task: items are shown in a sortable table on the dashboard.
+
+- A notification indicator with the unread count is shown on the dashboard.
 ```
 
 ### 6. Data Transformation Complexity
@@ -113,14 +149,40 @@ Does the spec involve complex data mapping, aggregation, or transformation acros
 - Simple field mapping or filtering → likely fine
 - Multi-step transformations, joins across entities, or aggregations → likely too complex
 
-### 7. Rough LOC Estimation
+### 7. Implied Technical Component
+
+Does the spec imply building a substantial technical component — an engine, parser, scheduler, layout algorithm, state machine, or sync mechanism — **in addition to** the behavior it describes? A component is not a free primitive: code must be generated for it too, so it counts toward the 200-LOC budget and must be evaluated as part of the estimate. A spec that needs a component **and** wires up behavior on top of it is really two bodies of code in one spec — a strong "too complex" signal. Count the component's implementation, not just the glue that calls it.
+
+Too complex (builds the component and uses it in one spec):
+```plain
+***functional specs***
+
+- A :Report: is exported to PDF, laying out multi-page tables with repeating headers and page numbers, and charts rendered from :Report: data.
+```
+
+Acceptable (component in its own spec, then referenced):
+```plain
+***functional specs***
+
+- :PdfRenderer: lays out multi-page tables from structured content.
+  - Table headers repeat at the top of each page.
+  - Each page shows its page number.
+
+- A :Report: is exported to PDF using :PdfRenderer:, embedding charts rendered from :Report: data.
+```
+
+When this indicator fires, the fix is `break-down-func-spec` Strategy 6 — extract the component into its own earlier spec and reference it.
+
+### 8. Rough LOC Estimation
 
 Mentally estimate the implementation. Consider:
 - New files that need to be created
 - New functions/methods
+- Code for any implied technical component (engine, parser, algorithm), not just the glue that uses it
 - Data model changes (schema, migrations, types)
 - UI components (if applicable)
 - Test setup and assertions (unit tests are auto-generated alongside)
+- For the first spec in a new root module, all project and test scaffold implied by implementation requirements
 - Error handling paths
 - Import statements and boilerplate
 

package/forge/skills/break-down-func-spec/SKILL.md

@@ -31,6 +31,7 @@ The functional spec to break down, plus the full `.plain` file it belongs to.
    - Cross-cutting concerns mixed with core functionality?
    - A full UI screen described in one spec?
    - Complex data transformations across multiple entities?
+   - Implies one substantial technical component (engine, parser, scheduler, algorithm, state machine, sync mechanism) that must be built in code?
 4. **Identify the split boundaries** — find the natural seams where the spec can be divided. Each resulting spec must be:
    - Independently meaningful (makes sense on its own with previous specs as context)
    - Self-contained (does not require a later spec to be useful)
@@ -50,15 +51,20 @@ If the spec bundles multiple independently testable actions, split each into its
 
 **Before:**
 ```plain
-- :User: should be able to create, edit, and delete :Recipe: items, with
-  validation on all fields.
+***functional specs***
+
+- A :User: can create, edit, and delete :Recipe: items, with validation on all fields.
 ```
 
 **After:**
 ```plain
-- :User: should be able to create a :Recipe:. Only valid :Recipe: items can be created.
-- :User: should be able to edit an existing :Recipe:. Validation rules apply to the edited fields.
-- :User: should be able to delete a :Recipe:.
+***functional specs***
+
+- A :User: can create a :Recipe:. Only valid :Recipe: items can be created.
+
+- A :User: can edit an existing :Recipe:. Validation rules apply to the edited fields.
+
+- A :User: can delete a :Recipe:.
 ```
 
 ### Strategy 2: Separate Setup from Behavior
@@ -67,16 +73,20 @@ If the spec introduces a new construct and immediately defines complex behavior
 
 **Before:**
 ```plain
-- The system should provide a :MealPlan: screen that displays a weekly grid of
-  :Slot: items, allows drag-and-drop reordering, and shows nutritional totals
-  per day.
+***functional specs***
+
+- The :MealPlan: screen displays a weekly grid of :Slot: items, allows drag-and-drop reordering, and shows nutritional totals per day.
 ```
 
 **After:**
 ```plain
-- The system should provide a :MealPlan: screen that displays a weekly grid of :Slot: items.
-- :User: should be able to reorder :Slot: items within a day on the :MealPlan: screen using drag-and-drop.
-- The :MealPlan: screen should display nutritional totals for each day.
+***functional specs***
+
+- The :MealPlan: screen displays a weekly grid of :Slot: items.
+
+- A :User: can reorder :Slot: items within a day on the :MealPlan: screen using drag-and-drop.
+
+- The :MealPlan: screen displays nutritional totals for each day.
 ```
 
 ### Strategy 3: Separate Core Logic from Cross-Cutting Concerns
@@ -85,15 +95,20 @@ If the spec mixes primary functionality with error handling, retries, caching, p
 
 **Before:**
 ```plain
-- The system should fetch :Ingredient: data from the external API with
-  pagination, retry on transient errors, and cache results for 10 minutes.
+***functional specs***
+
+- :Ingredient: data is fetched from the external API with pagination, retry on transient errors, and caching for 10 minutes.
 ```
 
 **After:**
 ```plain
-- The system should fetch :Ingredient: data from the external API.
-- The system should paginate when fetching :Ingredient: data from the external API.
-- The system should retry fetching :Ingredient: data on transient errors.
+***functional specs***
+
+- :Ingredient: data is fetched from the external API.
+
+- :Ingredient: data is fetched from the external API in pages.
+
+- Fetching :Ingredient: data is retried on transient errors.
 ```
 
 ### Strategy 4: Separate Conditional Paths
@@ -102,19 +117,22 @@ If the spec describes different modes or branches, give each its own spec.
 
 **Before:**
 ```plain
-- The system should process :MealPlan: generation differently based on :DietType:.
-  Standard plans use round-robin assignment. Restrictive plans filter out
-  excluded ingredients first, then apply round-robin. Custom plans allow manual
-  slot-by-slot selection.
+***functional specs***
+
+- :MealPlan: generation depends on :DietType:. Standard plans use round-robin assignment. Restrictive plans filter out excluded ingredients first, then apply round-robin. Custom plans allow manual slot-by-slot selection.
 ```
 
 **After:**
 ```plain
-- The system should generate a standard :MealPlan: using round-robin :Recipe: assignment.
-- The system should generate a restrictive :MealPlan:.
+***functional specs***
+
+- A standard :MealPlan: is generated using round-robin :Recipe: assignment.
+
+- A restrictive :MealPlan: is generated.
   - Excluded :Ingredient: items are filtered out first.
   - Round-robin :Recipe: assignment is then applied.
-- The system should allow :User: to manually assign :Recipe: items to :Slot: items for a custom :MealPlan:.
+
+- A :User: can manually assign :Recipe: items to :Slot: items for a custom :MealPlan:.
 ```
 
 ### Strategy 5: Build UI Incrementally
@@ -123,18 +141,48 @@ If the spec describes a full screen, split into layout + individual interactive
 
 **Before:**
 ```plain
-- Display the :Dashboard: screen showing a summary card with stats, a scrollable
-  list of recent :MealPlan: items, a floating action button to create a new plan,
-  and a bottom navigation bar.
+***functional specs***
+
+- The :Dashboard: screen shows a summary card with stats, a scrollable list of recent :MealPlan: items, a floating action button to create a new plan, and a bottom navigation bar.
 ```
 
 **After:**
 ```plain
-- Display the :Dashboard: screen with a summary card showing :MealFrameStats:.
-- The :Dashboard: screen should show a scrollable list of recent :MealPlan: items.
-- The :Dashboard: screen should include a button to create a new :MealPlan:.
+***functional specs***
+
+- The :Dashboard: screen shows a summary card with :MealFrameStats:.
+
+- The :Dashboard: screen shows a scrollable list of recent :MealPlan: items.
+
+- The :Dashboard: screen includes a button to create a new :MealPlan:.
 ```
 
+### Strategy 6: Extract a Reusable Technical Component
+
+Sometimes a spec is too complex not because it bundles many behaviors, but because it implies building one substantial technical component inline — an engine, parser, scheduler, layout algorithm, state machine, or sync mechanism. Splitting the behavior sideways does not help when the weight sits in that single component. Instead, pull the component out: define a concept for it, build it in its own dedicated spec placed **earlier** in the chain, then rewrite the original to use the component **by reference**. Because specs render incrementally top-to-bottom, the original now implies far less code — it wires up a component that already exists rather than implementing it from scratch.
+
+Define the component concept in `***definitions***` (via `add-concept`) before the first spec that references it.
+
+**Before:**
+```plain
+***functional specs***
+
+- A :Report: is exported to PDF, laying out multi-page tables with repeating headers, page numbers, and charts rendered from :Report: data.
+```
+
+**After:**
+```plain
+***functional specs***
+
+- :PdfRenderer: lays out multi-page tables from structured content.
+  - Table headers repeat at the top of each page.
+  - Each page shows its page number.
+
+- A :Report: is exported to PDF using :PdfRenderer:, embedding charts rendered from :Report: data.
+```
+
+The extracted component spec and the rewritten original must together still cover 100% of the original functionality (step 6): the original must **reference** the component, never re-describe it. Keep the component's technology and architecture choices in `***implementation reqs***`, not in the functional spec. If the component is a self-contained subsystem or will be reused across modules, promote it to its own module with `create-requires-module` / `refactor-module` instead of a sibling spec.
+
 ## Preserving Chronological Order
 
 The replacement specs take the position of the original spec. Earlier specs remain unchanged. The first replacement spec should make sense given only the specs above it. Each subsequent replacement spec can reference behavior from the ones before it.
@@ -151,6 +199,7 @@ If the original spec had acceptance tests, redistribute them to the most appropr
 - [ ] Replacement specs are in correct chronological order
 - [ ] Each replacement spec is independently meaningful
 - [ ] All `:Concepts:` referenced in replacement specs are defined
+- [ ] Any extracted technical component is defined as a concept, built by its own earlier spec, and only **referenced** (not re-described) by the original
 - [ ] Replacement specs are language-agnostic
 - [ ] All external interfaces remain explicit
 - [ ] Acceptance tests (if any) have been redistributed or rewritten

package/forge/skills/create-import-module/SKILL.md

@@ -44,14 +44,19 @@ description: Shared API definitions and reqs
 ---
 
 ***definitions***
+
 - :ApiClient: is the HTTP client used to communicate with external services.
+
 - :ApiResponse: is the response returned by :ApiClient:.
 
 ***implementation reqs***
+
 - :Implementation: should handle HTTP errors by raising appropriate exceptions.
+
 - :ApiClient: should support configurable timeouts.
 
 ***test reqs***
+
 - :ConformanceTests: should mock all external HTTP calls made by :ApiClient:.
 ```
 
@@ -71,7 +76,9 @@ import:
 > So this module must define them:
 
 ***definitions***
+
 - :AuthSchema: is the JSON schema describing the authentication data structure.
+
 - :AuthApiSpec: is the OpenAPI specification for the external service's auth endpoint.
 ```
 

package/forge/skills/create-requires-module/SKILL.md

@@ -50,11 +50,12 @@ description: Extended module that builds on base_module
 ---
 
 ***definitions***
+
 - :NewFeature: is a feature added by this module.
 
 ***functional specs***
 
-- The system should support :NewFeature:.
+- :NewFeature: is available.
 ```
 
 A module can use both `requires` and `import` together. `requires` points to other root-level modules; `import` resolves from the default `template/` directory (no prefix needed).