@aacombarro89/praxis 0.1.8 → 0.1.9

package/packages/layer1/onboarding/commands/onboard.md

@@ -1,24 +1,37 @@
 ---
-description: Author the project-owned sections of CLAUDE.md for a fresh Praxis install — build/run/test commands, layout, conventions, and always-do rules. One-shot: deletes .praxis-setup-pending when done.
+description: Author project-owned agent instructions for a fresh Praxis install—build/run/test commands, layout, conventions, and always-do rules. One-shot: deletes .praxis-setup-pending when done.
 ---
 
-Scope: $ARGUMENTS
+Scope: {{arguments}}
 
 This is the **first-run front gate** — the single entry point for a fresh Praxis
-install, symmetric to `/praxis-upkeep` (the ongoing front gate). It authors the
-**project-owned** sections of `CLAUDE.md`, then seeds the installed methodology
-packages, then hands off to `/praxis-upkeep` so the full baseline is established
+install, symmetric to `{{workflow:praxis-upkeep}}` (the ongoing front gate). It authors
+the **project-owned** agent instructions, then seeds the installed methodology
+packages, then hands off to `{{workflow:praxis-upkeep}}` so the full baseline is established
 in one pass.
 
-Praxis never calls an LLM (D12); never edits `CLAUDE.md` directly (D13). The
+Praxis never calls an LLM (D12) or authors project facts directly (D13). The
 **agent** writes the facts, guided by the steps below, asking the user for
 anything it cannot infer.
 
-1. **Bulk discovery — lean on the tool's native `/init` first.** If `CLAUDE.md`
-   does not yet exist (or is empty), suggest running the tool's built-in `/init`
-   command so the model can auto-discover repository facts (files, build config,
-   README). Incorporate any useful output into the project-owned sections below,
-   rather than restating it from scratch.
+1. **Choose the project instruction surfaces from `praxis.yaml`.** For a Codex-only
+   install, author project facts as free prose outside managed blocks in `AGENTS.md`.
+   For Claude-only, retain the existing `CLAUDE.md` flow. When both are selected,
+   maintain both native files as peers — never make either import or replace the
+   other. Put facts shared by both tools inside exactly one project-owned block in
+   each file, with identical content and these marker lines:
+
+   ```markdown
+   <!-- praxis:shared-project begin -->
+   ...shared project facts...
+   <!-- praxis:shared-project end -->
+   ```
+
+   The markers declare a parity contract, not Praxis ownership: the project owns
+   the prose and both native files remain complete if Praxis is removed. Guidance
+   outside this block may differ by target. If the active tool offers a native
+   repository initialization workflow, suggest it for bulk discovery and
+   incorporate useful output rather than re-deriving it.
 
 2. **Check detected stacks (if known).** Read `praxis.yaml` for the `stacks:`
    field. If stacks are declared, tailor the sections below to those stacks (e.g.
@@ -44,30 +57,35 @@ anything it cannot infer.
      short; a long always-do list is never read.
 
 4. **Ask the user for anything not inferable.** If a section can't be filled from
-   config files, git history, or the `/init` output, ask a targeted question
-   rather than inventing a plausible answer. Content inclusion bar: a fact only
-   enters if it's backed by the code, config, a canonical doc, or the user.
+   config files, git history, or the native initialization workflow's output, ask
+   a targeted question rather than inventing a plausible answer. Content
+   inclusion bar: a fact only enters if it's backed by the code, config, a
+   canonical doc, or the user.
 
 5. **Write only project-owned content.** Never put content inside a Praxis
-   managed block (a `<!-- praxis-start … -->` / `<!-- praxis-end … -->` region).
-   Project facts belong in the free-prose sections the author controls; Praxis
-   owns only its own managed blocks.
+   managed block (a `<!-- praxis:begin … -->` / `<!-- praxis:end … -->` region).
+   Project facts belong in the free-prose sections the author controls; the
+   unhashed `praxis:shared-project` block is also project-owned. Praxis owns only
+   its hashed managed blocks. When both native files are selected, write the four
+   rubric sections to both shared blocks in one edit and keep their content exact.
 
 6. **Run each installed companion bootstrap action** (each seeds part of the
-   methodology), then hand off to `/praxis-upkeep`:
+   methodology), then hand off to `{{workflow:praxis-upkeep}}`:
 
 <!-- praxis:bootstrap-delegations -->
 
-   After the bootstrap actions above complete, run `/praxis-upkeep` to confirm
-   the full methodology baseline is in sync. If `/praxis-upkeep` is not
+   After the bootstrap actions above complete, run `{{workflow:praxis-upkeep}}` to confirm
+   the full methodology baseline is in sync. If `{{workflow:praxis-upkeep}}` is not
    installed, skip this step.
 
 7. **Delete `.praxis-setup-pending`** to make this one-shot. Once the rubric
-   sections are authored and the user is satisfied, remove the sentinel file
-   from the repo root. This prevents the bootstrap rule (`.claude/rules/
-   praxis-onboarding.md`) from re-offering onboarding on the next session.
+   sections are authored, the bootstrap actions and upkeep pass above have run,
+   and the user is satisfied, remove the sentinel file from the repo root. This
+   prevents the bootstrap rule from re-offering onboarding on the next session —
+   deleting it any earlier would leave an interrupted session with no re-offer
+   and an unseeded baseline.
 
 8. **Report what was written / left.** Summarise which rubric sections were
    filled, which were left empty (and why — e.g. "no build step detected"), and
    any follow-up items for the user. The baseline is now established; from here
-   `/praxis-upkeep` keeps the methodology layer current.
+   `{{workflow:praxis-upkeep}}` keeps the methodology layer current.

package/packages/layer1/onboarding/rules.md

@@ -1,10 +1,10 @@
 ## First-run onboarding
 
 At the start of work, check for the `.praxis-setup-pending` sentinel file in
-the repo root: present means a fresh Praxis install whose project-owned
-`CLAUDE.md` sections aren't authored yet.
+the repo root: present means a fresh Praxis install whose project-owned agent
+instruction sections aren't authored yet.
 
-- **Present:** offer to run `/praxis-onboard`; it deletes the sentinel on
+- **Present:** offer to run `{{workflow:praxis-onboard}}`; it deletes the sentinel on
   completion, making this check one-shot. Never nag when absent.
-- **Absent:** do nothing here — `/praxis-upkeep` (ongoing front gate, D29/D31)
+- **Absent:** do nothing here — `{{workflow:praxis-upkeep}}` (ongoing front gate, D29/D31)
   handles currency after initial setup.

package/packages/layer1/safe-permissions/permissions.yaml

@@ -1,7 +1,7 @@
 # Neutral permission policy — the enforcement side of the rails
 # (docs/wiki/emitters.md, D18/D19). Tool-agnostic INTENT expressed as capabilities; per-tool emitters
-# translate to concrete rule strings (Claude Code today; tools without a
-# permission model emit nothing). Edit your own settings to tune — Praxis owns
+# translate to target-native Claude Code and Codex controls; tools without a
+# permission model emit nothing. Edit your own settings to tune — Praxis owns
 # only the rules it emits and never clobbers rules you add.
 #
 # Posture: allow common local dev (smooth); prompt before anything that leaves the

package/packages/layer1/session-handoff/commands/handoff.md

@@ -46,10 +46,10 @@ single-doc flow below.
 
 Read the clock so the name sorts chronologically (do not guess the time):
 
-- Timestamp: !`date +%Y-%m-%d_%H%M`
+- Timestamp: {{shell:date +%Y-%m-%d_%H%M}}
 
 Build the filename `YYYY-MM-DD_HHMM_HANDOFF_<topic>.md`:
-- `<topic>` is a short kebab-case slug for the work. Use `$ARGUMENTS` if
+- `<topic>` is a short kebab-case slug for the work. Use {{arguments}} if
   provided; otherwise derive it from the task.
 - Date-and-time first means a plain alphabetical listing is chronological.
 
@@ -73,9 +73,9 @@ references* section below. Don't re-derive them; you already paid for them.
 If in a git repo, capture current branch, staged/unstaged changes, and recent
 commits from this session:
 
-- Branch: !`git branch --show-current 2>/dev/null`
-- Status: !`git status --short 2>/dev/null`
-- Recent commits: !`git log --oneline -10 2>/dev/null`
+- Branch: {{shell:git branch --show-current 2>/dev/null}}
+- Status: {{shell:git status --short 2>/dev/null}}
+- Recent commits: {{shell:git log --oneline -10 2>/dev/null}}
 
 Capture verification state too: identify the project's own build/test/lint
 commands (from its config / docs / CI) and record their current result — what

package/packages/layer1/session-handoff/rules.md

@@ -2,7 +2,7 @@
 
 Work outlives a single session: at a natural boundary in a verified state —
 never mid-edit — capture context before it's lost. Write handoffs by running
-`/praxis-handoff`, not by hand; it's the next session's only briefing.
+`{{workflow:praxis-handoff}}`, not by hand; it's the next session's only briefing.
 
 ## Delegated execution
 
@@ -11,5 +11,5 @@ neither requiring parallelism: **independent workstreams** (specifiable up
 front, no mid-flight coordination) and **context/budget isolation** (a
 context-heavy or mechanical run worth its own context and a lighter tier —
 holds even for one sequential stream). Name the split at plan time. Produce
-each brief with `/praxis-handoff`, not by hand, and verify a returned
+each brief with `{{workflow:praxis-handoff}}`, not by hand, and verify a returned
 workstream against its success criterion before integrating it.

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,10 +1,14 @@
 ## Upkeep
 
-The methodology layer (instructions, wiki, emitted `.claude/` files) drifts
+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 `/praxis-upkeep` — the single
-front gate sequencing `praxis check`, `/praxis-instructions`, and
-`/praxis-wiki` — rather than fixing it ad hoc or piecemeal.
+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.
+
+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

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

@@ -2,13 +2,13 @@
 
 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 `CLAUDE.md`/`.claude/rules`
-(authored instructions). At the start of a task, read the wiki's `index.md`
+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.
 
 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 `/praxis-wiki`, not by hand.
+contradictions and staleness. Do this by running `{{workflow:praxis-wiki}}`, not by hand.
 When reconciling the methodology layer after a change, enter through
-`/praxis-upkeep`; call `/praxis-wiki` directly only for a deliberate single
+`{{workflow:praxis-upkeep}}`; call `{{workflow:praxis-wiki}}` directly only for a deliberate single
 pass (e.g. first-run bootstrap).