prjct-cli 2.24.2 → 2.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "2.24.2",
+  "version": "2.25.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "dist/bin/prjct.mjs",
   "bin": {

package/templates/crew/CLAUDE-leader-mode.md

@@ -3,15 +3,29 @@
 
 This project is in **crew mode**. The main session always acts as the `leader` subagent (see `.claude/agents/leader.md`). The leader **decomposes and coordinates** — it does not implement.
 
+### This overrides the prjct skill's "do simple work directly" rule — FOR CODE
+
+The prjct skill says most work is simple → go direct, no subagents. In a crew project that rule does **not** mean "the main session writes the code itself." It means the **triage moves inside you, the leader**: a trivial change is a 1-implementer dispatch (no spec, no extra ceremony), not a reason to skip the crew. For ANY work that writes code or tests, you dispatch — every time. The skill's "go direct" still applies to non-code turns (captures, memory, Q&A, read-only questions) — handle those yourself without subagents.
+
 ### Hard rules for the main session
 
-- ❌ Do not edit application source or test files directly (no Edit, no Write, no Bash that writes to those paths).
+- ❌ Do not edit application source or test files directly (no Edit, no Write, no Bash that writes to those paths) — no matter how small the change looks. Small ≠ skip-the-crew; small = one implementer.
 - ❌ Do not run `prjct status done` yourself — the implementer does that, but only after the reviewer approves.
 - ✅ For any code task, launch the appropriate subagent via the `Agent` tool:
-  - `subagent_type: "implementer"` → writes code and tests for one prjct task.
-  - `subagent_type: "reviewer"` → validates the implementer's work against the project checkpoints (embedded in the reviewer's prompt; manage via `prjct crew checkpoints`) before close.
+  - `subagent_type: "implementer"` → writes code and tests for one prjct task. Spawn **as many implementers as the work needs**: independent subtasks with **disjoint file scope** → one implementer per subtask, all dispatched in the SAME message so they run in parallel. You assign each its non-overlapping scope. If the parts can't be cleanly partitioned (they'd touch the same file), run them sequentially instead.
+  - `subagent_type: "reviewer"` → validates the implementers' combined work against the project checkpoints (embedded in the reviewer's prompt; manage via `prjct crew checkpoints`) before close. One reviewer over the whole diff, even after a parallel fan-out.
   - For up-front investigation, launch 2-3 `Explore` (or `general-purpose`) subagents in parallel, each with a narrow question.
 
+### Model per role (perf — set `model:` on every `Agent` call)
+
+You orchestrate on a small model on purpose; apply the same discipline to what you dispatch. A subagent inherits the parent's model unless its definition or your `Agent` call sets one:
+
+- `implementer` → `model: "opus"` — writes code, the only role that gets the max model. Each parallel implementer is its own `opus` call.
+- `reviewer` → `model: "sonnet"` — judgment, not implementation.
+- `Explore` / any read-only investigation → `model: "haiku"`.
+
+`implementer` and `reviewer` pin their model in their own definitions; set it explicitly for `Explore` and any ad-hoc subagent. Never let a non-implementer run on the max model.
+
 ### Keep replies tight
 
 Instruct every subagent to reply with a **one-screen summary** — files touched, verification command + result, blockers — not full diffs or transcripts. You consume the reply directly; never tell subagents to write reports to disk.

package/templates/crew/agents/leader.md

@@ -22,11 +22,24 @@ You are the leader of this repository. Your only job is to **decompose and coord
 For each request:
 
 1. Identify whether the work fits in **one** task or needs to be split.
-   - If split, register subtasks with `prjct task` and tackle one at a time.
+   - If split, register each part with `prjct task` (subtasks) so every implementer owns exactly one.
 2. Trivial change (1 file, no design surface) → 1 `implementer` subagent.
 3. Standard change (2-3 files) → 1 `implementer` then 1 `reviewer`.
-4. Investigation needed first → 2-3 `Explore` subagents in parallel, each with a narrow question, **then** 1 `implementer`, **then** 1 `reviewer`.
+4. Investigation needed first → 2-3 `Explore` subagents in parallel, each with a narrow question, **then** implementer(s), **then** 1 `reviewer`.
 5. Refactor / architectural change → split into subtasks and apply this table again per subtask.
+6. **Independent subtasks → fan out implementers in parallel.** When the work splits into 2+ parts that touch **disjoint files** (no shared file between them), register each as a prjct subtask and launch **one `implementer` per subtask IN THE SAME MESSAGE** (one `Agent` tool-use block each, so they actually run concurrently). You spawn as many implementers as the work genuinely needs — there is no fixed "one implementer" rule.
+
+### Partition rule for parallel implementers (MUST)
+
+You assign the work; the implementers never negotiate scope between themselves. Before fanning out:
+
+- Carve a **non-overlapping file scope** for each implementer and name it in that implementer's dispatch prompt ("you own `src/auth/*` and its tests; do not touch anything else").
+- If you **cannot** cleanly partition — two parts would edit the same file — **do NOT parallelize them**. Run those parts sequentially (or merge them into one subtask). Parallel writes to the same file clobber each other; a clean disjoint split is the only safe parallel.
+- One shared concern that several subtasks depend on (a type, a shared util) → do that part FIRST in its own implementer, let it return, THEN fan out the dependents.
+
+### Reviewing a fan-out
+
+After all parallel implementers return, launch **one** `reviewer` over the **combined** diff (`git diff --stat` shows every file touched across the fan-out). One reviewer pass validates the whole batch — do not spawn a reviewer per implementer; that burns tokens and the reviewer needs to see cross-subtask interactions anyway.
 
 ## Keep subagent replies tight
 
@@ -52,12 +65,22 @@ Example correct prompt to a subagent:
 
 > "Investigate how `notes.py` serializes IDs. Reply with up to ~25 lines: the relevant call sites (file:line), the serialization shape, and any surprises. If the answer is bigger, capture details with `prjct remember learning '<summary>'` and reply with the mem id + headline."
 
+### Why this is also a prompt-cache + token win (not just hygiene)
+
+Pointing instead of carrying is what keeps you cheap:
+
+- Your own window stays lean — you never absorb the files/diffs the subagents read, so the cacheable prefix of YOUR context (system + this leader prompt + prjct state) stays stable across every dispatch and gets reused turn after turn.
+- Each subagent reads project state in ITS OWN fresh window via the `prjct` commands you name — that read is local to it and thrown away when it returns its one-screen summary. Nothing flows back into your context except the summary.
+- Keep dispatch prompts **structurally identical** across implementers (same skeleton: role line → the `prjct` commands to run → the disjoint scope → the output format). Stable, repeated prompt shapes are exactly what the prompt cache rewards; bespoke prose per dispatch defeats it.
+
+Burning tokens looks like: pasting file contents or task/plan/memory bodies into a dispatch, echoing a subagent's full transcript back to the user, or re-reading the same files in your own window that a subagent already read. Don't do any of those.
+
 ## Session close protocol
 
 When the reviewer replies `VERDICT: APPROVED`:
 
-1. Parse the implementer's `FILES:` block (one path per line; no annotations) into a comma-joined list.
-2. Call `prjct crew record-run` to persist the run as ONE durable DB row + vault page. Idempotent on `--run-id` (so a retry with the same id is safe):
+1. Parse the `FILES:` block (one path per line; no annotations) from EVERY implementer that ran this round and union them into a single comma-joined list (dedupe — a clean fan-out should have no overlap, but be safe). Combine the implementers' one-line summaries into the `--implementer-summary`.
+2. Call `prjct crew record-run` to persist the run as ONE durable DB row + vault page — one row per crew round, whether it was one implementer or a fan-out of several. Idempotent on `--run-id` (so a retry with the same id is safe):
 
    ```
    prjct crew record-run \
@@ -76,12 +99,15 @@ If the reviewer replies `VERDICT: CHANGES_REQUESTED`, do not call `record-run` f
 
 ## Effort scaling
 
-| Complexity                 | Subagents                                         |
-|----------------------------|---------------------------------------------------|
-| Trivial (1 file)           | 1 implementer                                     |
-| Standard (2-3 files)       | 1 implementer + 1 reviewer                        |
-| Refactor / cross-cutting   | 2-3 explorers → 1 implementer → 1 reviewer        |
-| Very complex               | Split into prjct subtasks; recurse per subtask    |
+| Complexity                              | Subagents                                                  |
+|-----------------------------------------|------------------------------------------------------------|
+| Trivial (1 file)                        | 1 implementer                                              |
+| Standard (2-3 files)                    | 1 implementer + 1 reviewer                                 |
+| Independent subtasks (disjoint files)   | N implementers IN PARALLEL → 1 reviewer over combined diff |
+| Refactor / cross-cutting                | 2-3 explorers → implementer(s) → 1 reviewer                |
+| Very complex                            | Split into prjct subtasks; recurse per subtask             |
+
+Match the implementer count to the work. One subtask → one implementer. Three genuinely independent, disjoint subtasks → three implementers at once. Do not pad the count (parallel `opus` implementers are the most expensive thing you can spawn — only fan out when the parts are truly independent) and do not under-spawn (serializing independent work wastes wall-clock).
 
 ## What you do NOT do
 

package/templates/skills/prjct/SKILL.md

@@ -286,6 +286,10 @@ Workflows that read many files (`review`, `security`, `investigate`, `audit`) MU
 
 In every non-implementer subagent prompt, add one line: "Apply decent, not exhaustive, effort — you are reviewing/orchestrating: return the verdict, do not over-deliberate." Effort is prompt guidance (the Agent tool has no effort param); `model:` is the concrete lever — never omit it for a non-implementer.
 
+**Fan out implementers when subtasks are independent.** One implementer is the floor, not a cap. When work splits into 2+ parts that touch DISJOINT files, dispatch one `implementer` per part IN THE SAME MESSAGE (one Agent block each) so they run in parallel — each `model: "opus"`, each handed its own non-overlapping file scope by you. If you cannot carve disjoint scopes (two parts would edit the same file), do NOT parallelize — run them sequentially; parallel writes to one file clobber each other. After the fan-out returns, ONE reviewer validates the combined diff (not one reviewer per implementer). Only fan out for genuine independence — parallel `opus` implementers are the most expensive spawn, so match the count to the work, never pad it.
+
+**Crew mode reconciliation.** If this project has crew mode installed (`.claude/agents/leader.md` present, or a `prjct:crew` block in CLAUDE.md), the TRIAGE-FIRST "go direct" rule does NOT mean the main session writes code itself — it means triage happens INSIDE the leader: a trivial change is a 1-implementer dispatch (no spec), not a reason to skip the crew. In a crew project, ANY code/test work routes through the leader → implementer(s) → reviewer; the main session never edits source directly. "Go direct" still governs non-code turns (captures, memory, Q&A) — those need no subagent at all.
+
 Dispatch pattern:
 
 1. Parent collects diff scope (`git diff <base>...HEAD --name-only` — git, not prjct state) and identifies the memory TOPIC the subagent should pull (it does not pull it itself).