@aacombarro89/praxis 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aacombarro89/praxis",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "A CLI that installs an AI methodology layer into a codebase.",
   "type": "module",
   "bin": {

package/packages/layer1/instruction-upkeep/rules.md

@@ -21,4 +21,6 @@ and complete:
   anchors; staleness signals are future advisory work.
 - Make instruction-layer changes through `/praxis-instructions`, not ad-hoc edits — run
   it when unsure whether the instruction files still match the project, or whether
-  they cover the sections above.
+  they cover the sections above. When this is part of reconciling the methodology
+  layer after a change, enter through the `/praxis-upkeep` front gate (which
+  delegates here) instead of running this pass alone.

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

@@ -24,17 +24,20 @@ The brief serves two readers, and the same document works for both:
 ## Delegation mode
 
 By default this command writes one combined handoff for resuming the whole task.
-When the work splits into several **independent workstreams** that you intend to
-delegate to subagents, switch to delegation mode: produce **one scoped brief per
-workstream** instead of a single combined doc.
-
-- Run Phases 1–5 once per workstream. Scope each brief to that workstream only —
-  its files, its prior art, its commands, its success criterion — so a subagent
-  can execute it without the others' context.
+Switch to delegation mode — **one scoped brief per workstream** instead of a
+single combined doc — when you intend to delegate execution, for either reason
+(they don't require parallelism):
+- the work splits into **independent workstreams** to run concurrently, or
+- a **context-heavy or sequential** stream is worth running in an execution
+  agent's *own* context (and on a lighter tier) to keep the orchestrator's clean.
+
+- Write one brief per workstream — including a single sequential stream worth
+  isolating. Run Phases 1–5 per brief, scoped to that workstream only (its files,
+  prior art, commands, success criterion), so an execution agent runs it cold.
 - Name each file for its workstream: `YYYY-MM-DD_HHMM_HANDOFF_<workstream>.md`, so
   the set sorts together and each is identifiable.
-- Keep workstreams genuinely independent; if two need constant coordination, they
-  are one brief, not two.
+- Keep workstreams at the right grain: independent ones don't coordinate
+  mid-flight; a sequential stream is one brief the agent works start to finish.
 
 Everything else (sections, discipline, save location) is identical to the
 single-doc flow below.

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

@@ -21,30 +21,42 @@ the current conversation in memory, can resume without guessing or re-deriving.
 
 ## Delegated execution
 
-A handoff brief is not only for the *next* session — it is also the briefing a
-*subagent* needs to execute scoped work *now*. When a task decomposes into
-independent, well-bounded workstreams, the default approach is to orchestrate:
-plan the split, brief each workstream, delegate execution, then verify and
-integrate — rather than doing every workstream inline.
+A handoff brief is not only for the *next* session — it is also the briefing an
+execution agent needs to do scoped work *now*. The reason to delegate is to keep
+in the orchestrator's context only what it needs — the *result*, not the
+execution detail — and to match each piece of work to the cheapest tier that can
+do it. Delegate when that holds; do the work inline when it doesn't.
 
-- Split by independence, not by size. A workstream worth delegating is one that
-  can be specified up front and executed without coordination mid-flight. If two
-  parts must talk to each other constantly, they are one workstream.
+- Delegate when you need the result, not the detail. Two triggers, often
+  combined — **neither requires parallelism**:
+  - *Independent workstreams* — parts specifiable up front and runnable without
+    coordination mid-flight (concurrently, where the tool allows). If two parts
+    must talk constantly, they are one workstream.
+  - *Context or budget isolation* — a context-heavy or mechanical run (a wide
+    refactor, a multi-step migration, a long grind) worth executing in an
+    execution agent's *own* context window, on a lighter/faster tier, so the
+    orchestrator's context stays clean. This holds for a *single sequential*
+    stream: size and cost justify delegating on their own.
+- Name the split at plan time. When a plan's steps form independent or
+  context-heavy workstreams, surface the delegation split *as part of the plan* —
+  what each execution agent runs and how its result returns — rather than only
+  deciding to delegate mid-execution.
 - Brief each workstream as a self-contained context cache — the same discipline
   as a handoff. An execution agent starts cold: give it the load-bearing files
   (`path:line`), the prior art to mirror, the exact build/test commands, and a
   crisp success/verify criterion. A vague brief gets vague work back.
 - Keep the tiers to their jobs. The orchestrator plans, decomposes, verifies, and
-  integrates; the execution agents do bounded, fully-specified work. Match the
-  effort to the tier — execution agents can be lighter/faster than the
-  orchestrator. (Stated by role, not by model name, so it survives model
-  releases.)
+  integrates; execution agents do bounded, fully-specified work and return the
+  result, not the intermediate detail. Match the tier to the work — execution
+  agents can be lighter/faster than the orchestrator. (Stated by role, not by
+  model name, so it survives model releases.)
 - Verify on return; trust nothing unread. Each returned workstream is checked
   against its stated success criterion (build, tests, a read of the diff) before
   it is integrated — the orchestrator owns correctness of the whole.
-- Produce the briefs with `/praxis-handoff` (run it per workstream), not by hand —
-  so each is self-contained and consistent. The orchestrator then dispatches a
-  subagent per brief where the tool supports subagents.
-- Use judgment on whether to delegate at all. Orchestration pays off for
-  multi-workstream work; for a small single-thread change it is overhead — just
-  do it inline.
+- Produce the briefs with `/praxis-handoff` (run it per workstream), not by hand,
+  so each is self-contained. Dispatch a subagent per brief where the tool
+  supports subagents; where it does not, run the briefs inline in sequence or
+  hand them to a fresh session — same brief, different venue.
+- Use judgment on whether to delegate at all. It pays off for multi-workstream or
+  context-heavy work; for a small single-thread change the briefing cost exceeds
+  the savings — just do it inline.

package/packages/layer1/upkeep/rules.md

@@ -10,3 +10,9 @@ 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.
+
+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).

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

@@ -46,4 +46,7 @@ unlike a tool's machine-local native memory.
 - 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.
+  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.