@aacombarro89/praxis 0.1.3 → 0.1.4

package/package.json

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

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

@@ -10,11 +10,34 @@ 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.
+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.
+- 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.
+
+Everything else (sections, discipline, save location) is identical to the
+single-doc flow below.
 
 ## Phase 1 — Build the filename
 
@@ -172,7 +195,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 +205,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,33 @@ 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 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.
+
+- 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.
+- 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.)
+- 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.