@aacombarro89/praxis 0.1.0

package/packages/layer2/python-backend-recipes/rules.md

@@ -0,0 +1,37 @@
+---
+paths: ["**/*.py"]
+---
+
+## Python backend authoring recipes (Layer 2)
+
+Stack-specific craft for Python backend code. These say *how to add something
+well in this stack*; the concrete shape lives in this repo's own prior art, not
+here. Find the nearest existing module and mirror it.
+
+- **Mirror the nearest module.** Before adding a feature, open the closest
+  existing file that already does the same kind of thing (a sibling in the same
+  directory, an adjacent route/handler/service). Copy its structure — imports,
+  class/function layout, error handling, naming — rather than inventing a new
+  shape. The prior art is the template; matching it is verifiable, following
+  prose is not.
+- **One module, one responsibility.** A new `.py` file exports the smallest
+  coherent unit. Keep pure logic separate from I/O (filesystem, network, database)
+  so the logic is testable without mocks — mirror how the existing modules here
+  already split the two.
+- **Use the stdlib and installed deps before adding one.** Python stdlib
+  (`pathlib`, `dataclasses`, `typing`, `json`, `os`) and a dependency already in
+  `pyproject.toml` / `requirements*.txt` cover most needs. A new dependency for
+  what a few lines do is debt; justify it against what is already imported in
+  neighbouring files.
+- **Type hints are the contract.** Annotate inputs and outputs at module
+  boundaries; validate external/untrusted input where it enters (a schema
+  validator if the repo already uses one, e.g. pydantic). Don't re-validate data
+  already typed and checked upstream.
+- **Surgical change.** Touch only what the task needs; match the surrounding
+  style and the repo's lint/format config (`black`/`ruff` if present). Don't
+  reformat or "improve" adjacent code. Every changed line should trace to the
+  task.
+- **Follow the repo's packaging conventions.** Match the module layout, import
+  style (absolute vs relative), and packaging already in use — don't introduce a
+  second convention. If the project uses `src/` layout, honour it; if it uses
+  flat packages, honour that.

package/packages/layer2/python-testing/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md). Layer 2: a stack-specific
+# decision recipe for Python backend codebases — how to choose the right test
+# layer (unit vs integration/e2e) and honour the harness-before-features
+# ordering — pointing at the target repo's own test suites for the concrete shape.
+# Craft, not domain: portable across any Python project. Applies only when
+# praxis.yaml declares the `python-backend` stack.
+name: python-testing
+layer: layer2
+stack: python-backend
+provides: [rules]

package/packages/layer2/python-testing/rules.md

@@ -0,0 +1,33 @@
+---
+paths: ["**/*.py", "**/test_*.py", "**/*_test.py"]
+---
+
+## Python test-layer recipe (Layer 2)
+
+Choosing *where* a test belongs matters as much as writing it. Pick the layer
+that fails for the right reason, and mirror the repo's existing tests of that
+kind for structure and fixtures.
+
+- **Harness before features.** A rule that matters has a test. Write (or extend)
+  the test that pins the new behaviour *before or with* the code that satisfies
+  it — never land logic whose only check is "it looked right". Make the failing
+  test the prompt: it states what is missing.
+- **Pick the layer by what could break.**
+  - *Unit* — pure logic, branches, parsing, a single module's contract. Fast, no
+    I/O, no fixtures. Default here; most logic belongs at this layer.
+  - *Integration* — two or more modules composed, or real I/O (filesystem, a
+    spawned process, a database). Use when the bug would live in the seam between
+    units, not inside one.
+  - *End-to-end* — an invariant the whole application must honour, or a contract
+    a future change must not break. Use for the rails, not for every feature.
+- **Mirror the existing suite.** Find the nearest test of the same layer and copy
+  its setup — `pytest` is the default, its file location (`tests/` or alongside
+  source), naming convention (`test_*.py`), how it builds fixtures (`conftest.py`,
+  `@pytest.fixture`) and asserts. Don't introduce a second runner or a new fixture
+  style.
+- **Assert behaviour, not implementation.** Test observable inputs→outputs and
+  error cases at the boundary; avoid asserting private internals that refactors
+  will churn. One clear failing assertion beats five brittle ones.
+- **No new framework for one test.** The repo's installed runner and plain
+  `assert` statements cover almost everything. Reach for a new testing dependency
+  only when the existing one demonstrably cannot express the check.

package/packages/layer2/react-components/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md). Layer 2: stack-specific
+# authoring recipes for React codebases — React-specific component craft that
+# points at the target repo's own in-repo prior art for the concrete shape rather
+# than shipping code. Covers components, props, composition, accessibility, and
+# hooks conventions; not general TypeScript craft (node-recipes covers that for
+# react+node repos). Applies only when praxis.yaml declares the `react` stack.
+name: react-components
+layer: layer2
+stack: react
+provides: [rules]

package/packages/layer2/react-components/rules.md

@@ -0,0 +1,40 @@
+---
+paths: ["**/*.tsx", "**/*.jsx"]
+---
+
+## React component authoring recipes (Layer 2)
+
+React-specific craft for component code. General TypeScript/Node craft (types,
+module shape, surgical change) lives in `node-recipes` — this file covers only
+what is React-specific. The concrete shape lives in this repo's own prior art,
+not here. Find the nearest existing component and mirror it.
+
+- **Mirror the nearest component.** Before adding a component, open the closest
+  existing one that does the same kind of thing (a sibling in the same directory
+  or feature folder). Copy its structure — file layout, how it exports, how it
+  receives and passes props, where state lives — rather than inventing a new
+  shape. The prior art is the template; matching it is verifiable, following
+  prose is not.
+- **Props typed at the boundary.** Every component declares an explicit props
+  interface or type at the top of its file. Accept the minimum props needed; no
+  catch-all `[key: string]: unknown`. Children are explicit when the component
+  uses them.
+- **Composition over configuration.** Prefer a small focused component used in
+  multiple arrangements over a large one with a boolean-flag API. When a
+  component's props grow into a switch statement, split into two components that
+  share a common primitive.
+- **Native HTML elements before a component library.** A `<button>`, `<label>`,
+  or `<ul>` is always the first option. Reach for a library component only when
+  the native element demonstrably cannot satisfy the requirement — and then use
+  whichever library the repo already imports, not a new one.
+- **Accessibility is non-negotiable.** Every interactive element is reachable by
+  keyboard and has a visible focus style. Form inputs have associated `<label>`
+  elements (via `htmlFor`/`id` or wrapping). Non-decorative images have
+  descriptive `alt` text. Custom interactive elements carry the correct ARIA
+  `role` and `aria-*` attributes. These are not optional polish; ship them with
+  the component.
+- **Follow the repo's hooks and state conventions.** Use `useState`/`useReducer`
+  at the level state is first needed, and lift only when a sibling needs it.
+  Match whatever custom-hook patterns the repo already uses; don't introduce a
+  new global-state solution for a single component's needs. Mirror how the
+  existing components here manage side effects and data fetching.

package/packages/layer2/react-testing/package.yaml

@@ -0,0 +1,10 @@
+# Package manifest (docs/wiki/packages-and-emit.md). Layer 2: a stack-specific
+# decision recipe for React codebases — how to choose the right test layer
+# (unit-render vs integration vs e2e), use React Testing Library idioms, and
+# test behaviour/roles/user-visible output rather than implementation — pointing
+# at the target repo's own test suites for the concrete shape. Applies only when
+# praxis.yaml declares the `react` stack.
+name: react-testing
+layer: layer2
+stack: react
+provides: [rules]

package/packages/layer2/react-testing/rules.md

@@ -0,0 +1,35 @@
+---
+paths: ["**/*.test.tsx", "**/*.test.jsx", "**/*.spec.tsx", "**/*.spec.jsx"]
+---
+
+## React test-layer recipe (Layer 2)
+
+Choosing *where* a test belongs matters as much as writing it. Pick the layer
+that fails for the right reason, and mirror the repo's existing tests of that
+kind for structure and setup.
+
+- **Test behaviour, not implementation.** Query by roles and user-visible text
+  (`getByRole`, `getByLabelText`, `getByText`) — not by CSS class, component
+  display name, or internal state. A test that breaks on a classname rename
+  without catching a real regression is noise; a test that catches a missing
+  label is signal.
+- **Pick the layer by what could break.**
+  - *Unit render* — a single component in isolation: does it render the right
+    output for a given set of props, show/hide the right elements, respond to
+    user events? Default here for most component logic.
+  - *Integration* — two or more components composed, or a component wired to a
+    real hook/context/store. Use when the bug would live in the seam between
+    components, not inside one.
+  - *End-to-end* — a full user journey in a real browser. Use only for the
+    critical paths that no unit or integration test can protect; reserve for the
+    rails, not for every feature.
+- **Use React Testing Library.** The repo's RTL setup (`render`, `screen`,
+  `userEvent`, `fireEvent`) covers almost everything. Mirror the nearest
+  existing test file for setup, cleanup, and how it wraps providers. Don't
+  introduce a second render helper or a separate component-testing framework.
+- **Mirror the existing suite.** Copy the nearest test file's structure —
+  runner, file naming, directory location, how it imports the component under
+  test, how it sets up providers or mocks. Consistency beats cleverness.
+- **No new framework for one test.** RTL and the repo's installed runner (e.g.
+  vitest/jest) cover almost every component test need. Reach for a new dependency
+  only when the existing tooling demonstrably cannot express the check.