@juancr11/sibu 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "templateVersion": "135",
+  "templateVersion": "136",
   "templates": {
     "AGENTS.md": {
       "version": "35",
@@ -140,10 +140,10 @@
       ]
     },
     "skills/react/SKILL.md": {
-      "version": "3",
+      "version": "4",
       "description": "Selectable React skill for component design, props, state ownership, and presentational boundaries.",
       "changes": [
-        "Adds broadly applicable React screen componentization guidance so route and feature entry files stay thin while meaningful UI regions move into focused nearby files."
+        "Strengthens React guidance to require one component per nearby file by default, disallow same-file helper subcomponents, and add a before-finish component-boundary self-check."
       ]
     },
     "skills/scrum-master-planner/SKILL.md": {

package/templates/skills/react/SKILL.md

@@ -61,19 +61,21 @@ This skill covers React componentization, component responsibility, state owners
 ### 7. Prefer composition over configuration-heavy components
 - Compose smaller components instead of building one component with many modes and flags.
 - If a component needs many boolean props, consider whether it is doing too much.
-- Use `children` or named subcomponents when composition makes the API clearer.
+- Use `children` or named child component APIs when composition makes the API clearer, but keep each component implementation in its own nearby file.
 
 ### 8. Make component boundaries visible
 - Name components by what they represent in the UI or product.
 - Keep server-interacting, stateful, and presentational responsibilities easy to identify from the component shape.
 - Avoid mixing data fetching, mutation, layout, formatting, and low-level UI rendering in one component.
-- Each component should live in its own file by default; do not define multiple components in the same file just because they are currently small.
-- If a helper component is only temporary, promote it to its own file as soon as it represents a meaningful UI responsibility.
+- Each React component belongs in its own nearby file by default.
+- Do not define helper subcomponents in a parent component file, even when they are small, file-local, currently unreused, named only for readability, or part of a compound component API.
+- Same-file helpers are acceptable only when they are not React components, do not return JSX, and do not represent a UI responsibility. Constants, type aliases, and pure non-JSX helpers such as `formatStatusLabel()` may stay when they support the component without becoming UI.
+- A function that returns JSX, represents a named UI region, renders a repeated unit, or owns UI state/interaction is a component. Move it to its own nearby file before finishing.
 
 ### 9. Build screens as composition roots, not component dumping grounds
 - Treat page-level components, route-level containers, and major feature components as composition roots: they should assemble focused child components, not define every section, repeated item, overlay, menu, state, helper, and interaction inline.
 - A top-level screen component may own data loading, high-level layout, route states, and wiring, but should delegate meaningful UI regions to named components.
-- If a UI region has its own state, interaction, repeated rendering, overlay, menu, empty/error/loading state, or domain formatting concern, strongly prefer extracting it to a focused nearby file.
+- If a UI region has its own state, interaction, repeated rendering, overlay, menu, empty/error/loading state, or domain formatting concern, extract it to a focused nearby file.
 - Keep route entry files especially thin: they should fetch or prepare data, handle route-level states, and compose the screen. Avoid placing substantial presentational or interactive subcomponents directly inside them.
 - Route-local or feature-local components are good defaults for UI that belongs to one screen or feature. Shared components should be extracted only when reuse is real, not speculative.
 
@@ -103,6 +105,59 @@ feature-format.ts
 feature-types.ts
 ```
 
+Prefer separated component files:
+
+```tsx
+// feature-shell.tsx
+export function FeatureShell() {
+  return <FeatureList />;
+}
+
+// feature-list.tsx
+export function FeatureList() {
+  return <FeatureListItem />;
+}
+
+// feature-list-item.tsx
+export function FeatureListItem() {
+  return <li>Item</li>;
+}
+```
+
+Avoid multiple component implementations in one parent file:
+
+```tsx
+export function FeatureShell() {
+  return <FeatureList />;
+}
+
+function FeatureList() {
+  return <FeatureListItem />;
+}
+
+function FeatureListItem() {
+  return <li>Item</li>;
+}
+```
+
+Allowed same-file helpers are non-components:
+
+```tsx
+const statusLabels = { active: "Active" };
+
+function formatStatusLabel(status: string) {
+  return statusLabels[status] ?? "Unknown";
+}
+```
+
+Avoid same-file JSX helpers:
+
+```tsx
+function StatusBadge({ status }: { status: string }) {
+  return <span>{formatStatusLabel(status)}</span>;
+}
+```
+
 ## Decision rule
 
 When unsure, prefer:
@@ -110,7 +165,7 @@ When unsure, prefer:
 2. route-level or feature-level containers that own only the interaction state they coordinate
 3. one clear responsibility per component
 4. more focused components instead of fewer overloaded components
-5. one meaningful component per file by default
+5. one React component per nearby file by default
 6. nearby component files before shared abstractions
 7. stateless presentational components that render from props
 8. stateful components only where local interaction state is genuinely owned
@@ -121,10 +176,12 @@ When unsure, prefer:
 
 ## Componentization self-review
 
-Before finishing a React change, ask:
+Before finishing a React change, inspect every changed React file and ask:
 
 - Can I understand the screen structure from the top-level file without reading repeated item, action surface, overlay, state, or formatting internals?
 - Are meaningful UI regions and repeated units in named components?
 - Does each file have one obvious reason to change?
+- Does any changed file define more than one React component implementation, including small, file-local, currently unreused, named helper, or compound subcomponents?
+- If multiple component implementations remain, did I split them into nearby files before finishing or explicitly explain why the remaining same-file helper is not a React component, does not return JSX, and does not represent UI responsibility?
 - Are server/client boundaries still as small as practical?
 - Did I avoid creating shared abstractions before there is real reuse?