@aacombarro89/praxis 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aacombarro89/praxis",
-  "version": "0.1.3",
+  "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

@@ -10,11 +10,37 @@ You are a senior engineer writing a handoff document at the end of a working
 session. Capture ALL relevant context so a fresh session — with none of this
 conversation in memory — can read the file and immediately continue the work.
 
-The handoff is a **context cache, not just a status report.** A fresh session
-(or a resume subagent whose only briefing is this file) should be able to act
-from it without re-running the discovery you already did. Provide or reference
-the load-bearing context — files, line numbers, doc sections, prior art,
-commands — rather than making the next session rediscover it.
+The handoff is a **context cache, not just a status report.** Whoever reads it —
+with none of this conversation in memory — should be able to act from it without
+re-running the discovery you already did. Provide or reference the load-bearing
+context — files, line numbers, doc sections, prior art, commands — rather than
+making the reader rediscover it.
+
+The brief serves two readers, and the same document works for both:
+- **A fresh session** a human starts later to resume the work.
+- **A subagent** the orchestrator dispatches *now* to execute a scoped
+  workstream (see *Delegation mode* below).
+
+## Delegation mode
+
+By default this command writes one combined handoff for resuming the whole task.
+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 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.
 
 ## Phase 1 — Build the filename
 
@@ -172,7 +198,8 @@ not reopen the file.]
 
 ## Phase 6 — Confirm and hand off
 
-After writing, print exactly this to chat (with real values substituted):
+**Resume path (single combined handoff).** After writing, print exactly this to
+chat (with real values substituted):
 
 ```
 ✅ Handoff saved: <relative/path/to/file.md>
@@ -181,5 +208,23 @@ To continue, open a NEW session and send:
   Read <relative/path/to/file.md> and continue from the Immediate Next Steps section.
 ```
 
-Do not attempt to spawn or launch another session — that is not supported in
-this environment. The user starts the next session manually.
+Starting a new top-level session is a manual step — do not try to launch one;
+the user does that.
+
+**Delegation path (per-workstream briefs).** After writing the briefs, print the
+dispatch list so the orchestrator can fan the work out — one subagent per brief:
+
+```
+✅ Briefs saved:
+  - <relative/path/to/workstream-a.md>
+  - <relative/path/to/workstream-b.md>
+
+To execute, dispatch one subagent per brief:
+  Read <brief> and complete the workstream it describes; verify against its
+  success criterion before returning.
+```
+
+Spawning a subagent for each brief and verifying its result on return is the
+orchestrator's job (the main thread, which has the subagent/Task tool) — this
+command only produces the briefs. Within-session subagent delegation is
+supported; launching a separate top-level session is not.

package/packages/layer1/session-handoff/package.yaml

@@ -1,7 +1,10 @@
-# Package manifest (docs/wiki/packages-and-emit.md, D22/D24). Ships a standing reminder
+# Package manifest (docs/wiki/packages-and-emit.md, D22/D24/D37). Ships a standing reminder
 # (rules.md) plus the /praxis-handoff command (commands/handoff.md): capture full
-# session context into a chronologically-named, self-contained handoff doc so a
-# fresh agent session resumes without losing state or re-running discovery.
+# session context into a chronologically-named, self-contained handoff doc that
+# carries work across both boundaries it can cross — a session boundary (a fresh
+# agent session resumes without re-running discovery) and an agent boundary (a
+# subagent executes a scoped workstream the orchestrator delegated, D37). One
+# context-cache artifact serves both readers.
 # Layer 1 / stack- & tool-agnostic — the command adapts to whatever build/test,
 # design doc, and instruction layer the target project has; it hardcodes none of
 # Praxis's own specifics.

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

@@ -18,3 +18,45 @@ the current conversation in memory, can resume without guessing or re-deriving.
   that makes the authored instruction files stale or incomplete, say so.
 - Keep handoffs together in one directory so they sort in chronological order;
   don't scatter them into the codebase.
+
+## Delegated execution
+
+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.
+
+- 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; 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. 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.