@aacombarro89/praxis 0.1.7 → 0.1.9

package/packages/layer1/upkeep/commands/upkeep.md

@@ -4,18 +4,21 @@ argument-hint: [optional-area-to-focus]
 allowed-tools: Bash(npx @aacombarro89/praxis@latest check:*), Bash(npx @aacombarro89/praxis@latest sync:*), Bash(npx @aacombarro89/praxis check:*), Bash(npx @aacombarro89/praxis sync:*), Bash(praxis check:*), Bash(praxis sync:*)
 ---
 
-Focus: $ARGUMENTS — if empty, cover all three passes at a high level.
+Focus: {{arguments}} — if empty, cover all three passes at a high level.
 
 This is the single entry point for "is my methodology layer still current
 with reality?" It sequences three existing checks rather than re-implementing
 them — restating their logic here would duplicate content that drifts
 independently of its canonical home.
 
-1. **Deterministic drift.** Run `praxis check` if the CLI is on PATH; otherwise
+1. **Deterministic drift.** Run `praxis check` if the CLI is on PATH. Otherwise
    fall back to `npx @aacombarro89/praxis@latest check` (pin `@latest` — a bare
    `npx @aacombarro89/praxis` can silently reuse a stale cached build). If it
    reports file drift, run `praxis sync` (or `npx @aacombarro89/praxis@latest
-   sync`) to fix it. Surface managed-block conflicts or broken anchors as-is.
+   sync`) to fix it. Surface managed-block conflicts, shared-project parity
+   drift, or broken anchors as-is. `sync` fixes generated artifacts but must
+   never choose a winner between project-owned `CLAUDE.md` and `AGENTS.md`
+   blocks; route that drift to the instruction pass below.
    This step needs no LLM judgment — do it first so the semantic passes below
    build on a known-good baseline. **If the CLI is unavailable even via npx,
    skip only this step and proceed with steps 2 and 3 — do not skip the entire
@@ -27,10 +30,10 @@ independently of its canonical home.
    invalid-manifest message), the check did not fully run — report that as a
    failure, never as "0 checked, all fine".** A stale npx-cached CLI is the usual
    cause; re-run pinned to `@latest`, and note the version if it still lags.
-2. **Instruction layer.** Perform the update defined by `/praxis-instructions`,
+2. **Instruction layer.** Perform the update defined by `{{workflow:praxis-instructions}}`,
    scoped to the focus above. Follow that command's own steps; do not
    re-derive them here.
-3. **Wiki.** Perform the wiki maintenance defined by `/praxis-wiki`, scoped to
+3. **Wiki.** Perform the wiki maintenance defined by `{{workflow:praxis-wiki}}`, scoped to
    the focus above — it files newly-authored knowledge and lints existing pages,
    and no-ops when there is nothing to do. Follow that command's own steps; do
    not re-derive them here. (Full delegation, symmetric with the audit pass —

package/packages/layer1/upkeep/rules.md

@@ -1,18 +1,15 @@
 ## Upkeep
 
-The methodology layer (instruction files, the knowledge wiki, the emitted
-`.claude/` files) drifts from project reality the same way code drifts from
-docs. When work reveals that drift — a stale instruction, a wiki page that no
-longer matches the code, an unsynced emit — or when work produces new durable
-knowledge to file (a decision, a new package), run `/praxis-upkeep` rather than
-letting the gap persist, fixing it ad hoc, or invoking the sub-skills piecemeal.
-It is the single front gate: it sequences `praxis check` and fully delegates to
-`/praxis-instructions` (instruction layer) and `/praxis-wiki` (knowledge wiki). The
-command itself only sequences and reports; the sub-skills make any edits, each
-behind its own confirmation gate.
+The methodology layer (instructions, wiki, emitted agent files) drifts
+from project reality like code drifts from docs. When work reveals drift, or
+produces new durable knowledge to file, run `{{workflow:praxis-upkeep}}` — the single
+front gate sequencing `praxis check`, `{{workflow:praxis-instructions}}`, and
+`{{workflow:praxis-wiki}}` — rather than fixing it ad hoc or piecemeal.
 
-Run all three passes through the gate even when only one looks like it has work.
-The gate exists so you do not pre-decide which passes are needed — the irrelevant
-ones no-op cheaply, and skipping straight to a sub-skill because the others "look
-like no-ops" is exactly the piecemeal use this rule prevents (it is how a pass
-that did have work gets silently skipped).
+When Claude Code and Codex coexist, this gate covers both native instruction
+surfaces. Keep their project-owned shared sections synchronized while preserving
+target-specific guidance; never make one surface import or replace the other.
+
+Run all three passes through the gate even when only one looks like it has
+work — skipping straight to a sub-skill is the piecemeal use this rule
+prevents.

package/packages/layer1/wiki-memory/commands/wiki.md

@@ -10,8 +10,8 @@ You are curating a durable knowledge wiki for this project: linked markdown page
 of long-lived knowledge that a future session reads instead of re-deriving. This
 is the agent's cross-session memory **of the project** — version-controlled and
 shared with the team. It is NOT a per-session handoff (transient — that is
-`/praxis-handoff`) and NOT the authored instruction layer (`CLAUDE.md`,
-`.claude/rules` — that is `/praxis-instructions`).
+`{{workflow:praxis-handoff}}`) and NOT the authored agent instruction layer
+(that is `{{workflow:praxis-instructions}}`).
 
 The wiki has two kinds of durable knowledge:
 - **Derived summaries** compress code, config, and canonical docs. The underlying
@@ -21,7 +21,7 @@ The wiki has two kinds of durable knowledge:
   diverge, surface the drift for human judgment instead of silently overwriting
   one with the other.
 
-Focus: $ARGUMENTS — if empty, refresh and lint the whole wiki at a high level.
+Focus: {{arguments}} — if empty, refresh and lint the whole wiki at a high level.
 
 ## Phase 1 — Locate or create the wiki
 
@@ -31,8 +31,8 @@ Use the first of these that already exists; otherwise create the first one
 2. `wiki/`
 3. `.praxis/wiki/`
 
-- Existing entries: !`ls -R docs/wiki wiki .praxis/wiki 2>/dev/null || true`
-- Today (for log entries, do not guess): !`date +%Y-%m-%d`
+- Existing entries: {{shell:ls -R docs/wiki wiki .praxis/wiki 2>/dev/null || true}}
+- Today (for log entries, do not guess): {{shell:date +%Y-%m-%d}}
 
 Front the wiki with two entry-point files; create them if missing:
 - `index.md` — a catalog of every page: a link and a one-line summary each.
@@ -81,7 +81,7 @@ Health-check the wiki and fix what you can (ask before large deletions):
 - **Contradictions** — derived summaries that disagree with current code/config
   lose to the source; fix the wiki. Canonical-intent entries are different: if
   code and intent diverge, report the drift and route it to a decision/update
-  step (or `/praxis-instructions` for instruction-layer changes) instead of deciding
+  step (or `{{workflow:praxis-instructions}}` for instruction-layer changes) instead of deciding
   automatically. Two wiki entries that disagree resolve to the more recent /
   authoritative / better-supported claim, with the resolution noted.
 - **Stale claims** — derived facts the current code has invalidated: fix or

package/packages/layer1/wiki-memory/rules.md

@@ -1,52 +1,14 @@
 ## Wiki memory
 
-Knowledge outlives a single conversation. An agent that re-derives the same
-project facts every session wastes effort and drifts. Keep a durable, in-repo
-**knowledge wiki** — linked markdown pages of long-lived knowledge that a fresh
-session reads instead of rediscovering (the Karpathy "LLM wiki" pattern). Because
-it lives in the repo, it is version-controlled and shared with the whole team,
-unlike a tool's machine-local native memory.
+Knowledge outlives a single conversation. Keep a durable, in-repo knowledge
+wiki — linked markdown pages a future session reads instead of re-deriving —
+distinct from a handoff (transient) and from authored agent instructions
+(the instruction layer). At the start of a task, read the wiki's `index.md`
+and follow the links that bear on the work.
 
-- **Two entry points.** Front the wiki with an `index.md` that lists every page
-  with a one-line summary and a link, and a `log.md` that records — append-only —
-  what changed in the wiki and when. Read the index first; it is the map.
-- **Add a glossary when terms collide.** When a project reuses a common word for
-  a project-specific meaning, or coins its own vocabulary, keep a `glossary.md`
-  of short term definitions — each pointing to the canonical source that owns
-  it. The signal you already needed the page is one ambiguous term re-explained
-  in scattered prose. Define what a term *is* and, where the word misleads, what
-  it is *not*.
-- **Know which kind of entry you are editing.** Derived summaries compress code,
-  config, and canonical docs; the underlying source wins on conflict. Canonical
-  intent entries record decisions, rationale, scope, and design intent; when code
-  and intent diverge, surface the drift for human judgment instead of silently
-  overwriting one with the other.
-- **Keep decisions in one ledger when they are numbered or cited.** Use a single
-  canonical `decisions.md`, append new `D<N>` rows, never renumber, and never
-  scatter numbered decisions across topic pages.
-- An entry captures *durable* knowledge: architecture and how the parts fit, a
-  hard-won gotcha and its cause, a workflow, a decision and its why. Not transient
-  session state (that is a handoff) and not the authored instruction rules (those
-  are `CLAUDE.md`/`.claude/rules`).
-- At the start of a task, read the index and follow the links that bear on the
-  work — act on what is already known rather than re-deriving it.
-- When you learn something durable — including a useful answer or analysis you
-  derived mid-session — add or update an entry, link it from the index, and note
-  the change in the log. Prefer one topic per page, cross-linked, over a sprawling
-  document; update the canonical page rather than create a near-duplicate.
-- Add machine-checkable `praxisAnchors` frontmatter for canonical sources when a
-  page depends on them: `path`, `command`, and `section` anchors are hard-checked
-  by `praxis check`; staleness/hash tripwires remain advisory future work.
-- Keep it true. Periodically **lint** the wiki (via `/praxis-wiki`): flag and fix
-  contradictions, stale claims, orphan pages, and missing cross-references. A
-  stale wiki misleads worse than none. Link the canonical source rather than
-  restating it; restated facts drift independently of their source.
-- Never record a fact that isn't backed by the code, config, a canonical doc, or
-  the user — the wiki is curated knowledge, not speculation.
-- Do wiki work by running `/praxis-wiki`, not by hand — bootstrapping, filing new
-  knowledge, and linting all run the skill rather than hand-authoring pages and
-  hand-editing `index.md`/`log.md` around it. It keeps the index, log, and anchors
-  consistent. When the wiki pass is part of reconciling the methodology layer
-  after a change, enter through the `/praxis-upkeep` front gate (which delegates
-  here) instead of running it alone; call `/praxis-wiki` directly only for a
-  deliberate single pass, e.g. first-run bootstrap.
+When you learn something durable — an architecture fact, a gotcha, a decision,
+a workflow — file or update it, and periodically lint the wiki for
+contradictions and staleness. Do this by running `{{workflow:praxis-wiki}}`, not by hand.
+When reconciling the methodology layer after a change, enter through
+`{{workflow:praxis-upkeep}}`; call `{{workflow:praxis-wiki}}` directly only for a deliberate single
+pass (e.g. first-run bootstrap).

package/packages/layer2/node-recipes/rules.md

@@ -8,6 +8,10 @@ Stack-specific craft for TypeScript/Node 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 example and mirror it.
 
+Layer 1 rules (think before coding, simplicity first, surgical changes,
+goal-driven execution) apply unchanged — this file adds only what is
+Node-specific.
+
 - **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/command/service). Copy its structure — imports,
@@ -25,9 +29,6 @@ here. Find the nearest existing example and mirror it.
   validate external/untrusted input where it enters (a schema validator if the
   repo already uses one, e.g. zod). 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. Don't reformat or "improve" adjacent
-  code. Every changed line should trace to the task.
 - **ESM vs CJS, follow the repo.** Match the module system, import extensions
   (`.js` specifiers under `"type": "module"`), and `tsconfig` target already in
   use — don't introduce a second convention.

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

@@ -8,6 +8,10 @@ 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.
 
+Layer 1 rules (think before coding, simplicity first, surgical changes,
+goal-driven execution) apply unchanged — this file adds only what is
+Node-testing-specific.
+
 - **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

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

@@ -8,6 +8,10 @@ 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.
 
+Layer 1 rules (think before coding, simplicity first, surgical changes,
+goal-driven execution) apply unchanged — this file adds only what is
+Python-specific.
+
 - **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,
@@ -27,10 +31,6 @@ here. Find the nearest existing module and mirror it.
   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

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

@@ -8,6 +8,10 @@ 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.
 
+Layer 1 rules (think before coding, simplicity first, surgical changes,
+goal-driven execution) apply unchanged — this file adds only what is
+Python-testing-specific.
+
 - **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

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

@@ -9,6 +9,10 @@ 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.
 
+Layer 1 rules (think before coding, simplicity first, surgical changes,
+goal-driven execution) apply unchanged — this file adds only what is
+React-specific.
+
 - **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

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

@@ -8,6 +8,10 @@ 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.
 
+Layer 1 rules (think before coding, simplicity first, surgical changes,
+goal-driven execution) apply unchanged — this file adds only what is
+React-testing-specific.
+
 - **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