jorgex-stack 1.0.20 → 1.0.21

package/README.md

@@ -83,7 +83,7 @@ GitHub authentication: requests use `GH_TOKEN`/`GITHUB_TOKEN` from the environme
 
 ### OpenCode Goal Mode
 
-Goal Mode is an OpenCode plugin for long-running goals: multiple sessions, multiple slices, multiple worktrees, and, when needed, multiple PRs. It is not meant for short tasks. If the change fits without extended autonomy, do not use `/goal`.
+The normal work-lifecycle already supports multi-PR plans: `work/{name}/PRD.md` and `plan.md` stay alive across intermediate merges, `work/{name}/pr/{NN}` stores each checkpoint, and `work/{name}/done` is reserved for the final close. Goal Mode is separate: an OpenCode plugin for long-running goals, multiple sessions, multiple slices, multiple worktrees, and, when needed, multiple PRs. It is not meant for short tasks. If the change fits without extended autonomy, do not use `/goal`.
 
 It only exists in OpenCode. Claude Code and Codex do not receive it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI y OpenCode",
   "type": "module",
   "license": "MIT",

package/stack/agents/README.md

@@ -30,4 +30,4 @@ Una sola fuente por agente. El instalador los traduce al formato de cada runtime
 
 - Todo subagente termina con el **Result contract** (Status / Delegations / Risks) — el orchestrator lo procesa.
 - Las delegaciones usan el formato `→ [agent]: [work] — [paths] — [inputs]` (skill `agent-delegation`).
-- El flujo de trabajo lo define la skill `work-lifecycle` (PRD D9): `work/{nombre}/plan.md` es el tablero de estado; las specs de tareas (`work/{nombre}/task/{NN}`), los resultados de fase (`work/{nombre}/{fase}`) y el backlog (`work/backlog`) viven en Engram. Los subagentes reciben topic_key + título, nunca la tarea inline.
+- El flujo de trabajo lo define la skill `work-lifecycle`: `work/{nombre}/plan.md` es el tablero de estado y se mantiene entre merges intermedios; las specs de tareas (`work/{nombre}/task/{NN}`), los resultados de fase (`work/{nombre}/{fase}`), los checkpoints de PR (`work/{nombre}/pr/{NN}`) y el cierre final (`work/{nombre}/done`) viven en Engram. Los subagentes reciben topic_key + título, nunca la tarea inline.

package/stack/agents/orchestrator.md

@@ -19,7 +19,7 @@ INIT → EXPLORE → SPEC → PLAN → EXECUTE → VERIFY → SHIP → CLOSE
 
 ### Autonomy
 
-The human drives the flow UP TO the plan: the idea, the PRD review and the plan review are interactive. Once the plan is approved, EXECUTE → VERIFY → SHIP run **autonomously** — no questions, no confirmation pauses: plan approval authorizes commits, pushes to the work branch and the PR creation. Control returns to the user at CLOSE. Merging the PR is NEVER yours: it always requires an explicit user order.
+The human drives the flow UP TO the plan: the idea, the PRD review and the plan review are interactive. Once the plan is approved, EXECUTE → VERIFY → SHIP run **autonomously** — no questions, no confirmation pauses: plan approval authorizes commits, pushes to the work branch and the PR creation. Control returns to the user at CLOSE. Merging the PR is NEVER yours: it always requires an explicit user order. For multi-PR work, each merge is a checkpoint; keep `work/{name}/PRD.md` and `plan.md` alive until the roadmap is finished.
 
 ## 1. INIT
 
@@ -96,11 +96,11 @@ If the work is large enough to benefit from explicit vertical slices, use the `t
 
 The `work-lifecycle` skill is the single source of this flow. Summary — every piece has exactly ONE home:
 
-- `work/{name}/` (gitignored, exists only while the work is in progress) holds the human-reviewed artifacts: `PRD.md` and `plan.md`. plan.md is the ONLY task status board — flip statuses with surgical edits; don't re-read the whole plan after every task (re-read it on resume).
+- `work/{name}/` (gitignored, exists only while the work is in progress) holds the human-reviewed artifacts: `PRD.md` and `plan.md`. They stay resident across intermediate PR merges; `plan.md` is the ONLY task status board — flip statuses with surgical edits; don't re-read the whole plan after every task (re-read it on resume).
 - The full spec of each atomic task → Engram, one `mem_save` per task under `work/{name}/task/{NN}`. When you delegate a task, pass the subagent its topic_key + title — never the task content inline; it retrieves the spec itself.
-- Phase outcomes and decisions → Engram under `work/{name}/{phase}`; tell each subagent which topic_key to use for its saves.
+- Phase outcomes, decisions and PR checkpoints → Engram under `work/{name}/{phase}` and `work/{name}/pr/{NN}`; tell each subagent which topic_key to use for its saves.
 - Pending work → the project's single `work/backlog` topic_key (one upserted list), or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder.
-- On close: `mem_save` the outcome under `work/{name}/done`, move the PRD to the project's docs only if it has lasting documentation value, then delete `work/{name}/`. History is memory + git.
+- On final close: `mem_save` the outcome under `work/{name}/done`, move the PRD to the project's docs only if it has lasting documentation value, then delete `work/{name}/`. `work/{name}/done` is only for the last PR / final outcome. History is memory + git.
 
 ## Delegation map
 
@@ -118,7 +118,7 @@ Every subagent ends with a **Result contract** (Status / Delegations / Risks). P
 
 Before the first task, create a git worktree for this work and run the ENTIRE execution inside it — implementation, tests, commits and pushes happen there, never on the user's main checkout.
 
-Canonical location is mandatory: resolve the project root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, create `worktrees/` inside that root if needed, and create the worktree at `<project-root>/worktrees/<canonical-name>` (branch = canonical name). Do not create worktrees next to the repo, in the repo root, under `work/`, or in any external temp/shared folder.
+Canonical location is mandatory: resolve the project root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, create `worktrees/` inside that root if needed, and create the worktree at `<project-root>/worktrees/<canonical-name>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints (branch = worktree name). Do not create worktrees next to the repo, in the repo root, under `work/`, or in any external temp/shared folder.
 
 Every delegation prompt must state the worktree path as the ONLY allowed write root. After each writer subagent finishes, verify the user's main checkout is still clean (`git status` there); if the subagent wrote outside the worktree, STOP, move those changes into the worktree (patch/apply) and restore the main checkout before continuing. Subagent obedience is not a safety boundary — this check is.
 
@@ -178,7 +178,7 @@ When the plan is fully applied and VERIFY passes:
 ## 8. CLOSE
 
 - STOP here and hand control back to the user: report what shipped, review findings applied vs deferred to `work/backlog`, and whether manual testing is advisable (recommend it for big or user-facing changes; small well-tested changes may not need it).
-- NEVER merge the PR yourself — merge only on an explicit user order. After the merge: persist the outcome to memory, clean up `work/{name}/` and remove the worktree (see Work state).
+- NEVER merge the PR yourself — merge only on an explicit user order. After each intermediate merge: persist the checkpoint to `work/{name}/pr/{NN}`, update `plan.md`, and keep `work/{name}/` alive. After the final merge: persist the final outcome to memory, clean up `work/{name}/` and remove the worktree (see Work state).
 - If the repo has its own skill for the closing steps (release, deploy, git, cleanup), that skill takes precedence over the default behavior.
 
 ## Task rule

package/stack/plugins/opencode/worktree.ts

@@ -5,7 +5,6 @@ interface WorktreePluginConfig {
   setupScript?: string;
   docsReminderScript?: string;
   pathContains?: string;
-  branchPrefix?: string;
   reminderLines?: string[];
 }
 
@@ -290,7 +289,6 @@ export const WorktreePlugin: Plugin = async ({ $, client, directory }) => {
   let config: WorktreePluginConfig = {
     setupScript: "scripts/setup-worktree.ps1",
     pathContains: "worktrees/",
-    branchPrefix: "feature/",
     reminderLines: [],
   };
 
@@ -356,7 +354,7 @@ export const WorktreePlugin: Plugin = async ({ $, client, directory }) => {
         const worktreeName = getWorktreeName(parsedWorktreePath);
         if (!worktreeName) return;
 
-        const branchName = `${config.branchPrefix || "feature/"}${worktreeName}`;
+        const branchName = worktreeName;
 
         // .quiet() suppresses stderr to prevent noisy TUI logs from git calls
         const gitRoot = await $`git rev-parse --show-toplevel`.quiet().text();
@@ -372,7 +370,7 @@ export const WorktreePlugin: Plugin = async ({ $, client, directory }) => {
           appendToolOutput(output, [
             `Worktree path is not canonical: ${absoluteWorktreePath}`,
             `Use the project-local path instead: ${expectedWorktreePath}`,
-            "Canonical rule: <project-root>/worktrees/<canonical-name>.",
+            "Canonical rule: <project-root>/worktrees/<canonical-name> or <project-root>/worktrees/<canonical-name>-prNN.",
           ]);
           return;
         }

package/stack/skills/to-prd/SKILL.md

@@ -53,6 +53,16 @@ Do NOT include specific file paths or code snippets. They may end up being outda
 
 Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
 
+## Delivery / PR Roadmap
+
+This section captures the intended PR split only. Live status, checkpoints, and task progress belong in `plan.md`.
+
+1. PR 01 — [scope / outcome]
+2. PR 02 — [scope / outcome]
+3. PR 03 — [scope / outcome]
+
+Keep this static: describe the planned delivery slices, not the current state.
+
 ## Testing Decisions
 
 A list of testing decisions that were made. Include:

package/stack/skills/work-lifecycle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: work-lifecycle
-description: Single source for how a piece of work is tracked and advances — PRD and plan as files in work/{name}/ while in progress; task specs, phase outcomes and history in Engram memory. Use when starting, tracking, resuming or closing a piece of work, or when deciding where a PRD, plan, task or backlog item should live.
+description: Single source for how a piece of work is tracked and advances — PRD and plan as files in work/{name}/ while in progress; task specs, phase outcomes, PR checkpoints and history in Engram memory. Use when starting, tracking, resuming or closing a piece of work, or when deciding where a PRD, plan, task or backlog item should live.
 ---
 
 # Work Lifecycle
@@ -9,7 +9,7 @@ One rule kills duplication: **every piece of information has exactly ONE home**.
 
 ## Identity
 
-Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `checkout-refactor`), shared with the branch if applicable. The name stays the same across its whole life — it is the key to everything else.
+Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `checkout-refactor`), shared with the single-PR branch/worktree name and the base name for multi-PR checkpoints. The name stays the same across its whole life — it is the key to everything else.
 
 ## Where everything lives
 
@@ -18,8 +18,9 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 | PRD | `work/{name}/PRD.md` | Written once, reviewed by the human |
 | Plan (goal, approach, task board) | `work/{name}/plan.md` | The status board: humans glance at it; statuses flip with surgical edits |
 | Full spec of each atomic task | Engram `work/{name}/task/{NN}` | Only subagents consume it; visible from any worktree |
+| PR checkpoint outcome | Engram `work/{name}/pr/{NN}` | Intermediate PR merge record |
 | Phase outcomes, decisions, findings | Engram `work/{name}/{phase}` | History — must survive the folder and compactions |
-| Final outcome | Engram `work/{name}/done` | Permanent record of what shipped |
+| Final outcome | Engram `work/{name}/done` | Permanent record of what shipped after the last PR |
 | Pending / backlog items | Engram `work/backlog` — ONE key per project | All pending ideas in a single upserted list |
 
 `work/` is **scaffolding, not product**: add it to the project's `.gitignore`. It contains ONLY work in progress — an empty `work/` means nothing is half-done. No `1-TODOs/`, no `3-finalized/`, no phase subfolders.
@@ -28,16 +29,17 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 
 1. Pick the canonical name and create `work/{name}/`. If the item came from the backlog, remove it from `work/backlog` in the same step.
 2. Produce the PRD with the `to-prd` skill → `work/{name}/PRD.md`. The human reviews it there.
-3. Write `work/{name}/plan.md` (structure in `references/plan-template.md`): goal, chosen approach, success criteria, and the task table — number, title, one-line description, status, wave, deps.
+3. Write `work/{name}/plan.md` (structure in `references/plan-template.md`): goal, chosen approach, success criteria, PR roadmap, and the task table — number, PR, title, one-line description, status, wave, deps.
 4. Save the full spec of each atomic task to memory: one `mem_save` per task with topic_key `work/{name}/task/{NN}` (content structure in `references/plan-template.md`).
 
 ## Executing
 
 - Execution happens inside a git worktree created for the work; the user's main checkout stays untouched until merge.
-- Worktree path is fixed: first resolve the project root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, then create/use `<project-root>/worktrees/<canonical-name>` (branch = canonical name). Never place worktrees in the repo root, next to the repo, under `work/`, or outside the project.
+- Worktree path is fixed: first resolve the project root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, then create/use `<project-root>/worktrees/<canonical-name>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints, with the branch matching the worktree name. Never place worktrees in the repo root, next to the repo, under `work/`, or outside the project.
 - Delegation handoff: the subagent receives its **topic_key + task title**, never the task content inline. It retrieves the spec itself (`mem_search` → `mem_get_observation`).
 - The subagent saves its phase outcome under the topic_key the orchestrator gave it (`work/{name}/{phase}`) BEFORE its final report.
-- Task status lives ONLY in the plan.md table: flip it (⬜ → ✅) with a surgical edit when the task closes. Do not mirror statuses into memory, and do not re-read the whole plan after every task — it is already in context; re-read it on resume.
+- Task status lives ONLY in the task table: flip it (⬜ → ✅) with a surgical edit when the task closes. PR status/evidence lives ONLY in the PR roadmap table. Do not mirror task progress into memory, and do not re-read the whole plan after every task — it is already in context; re-read it on resume.
+- For multi-PR work, resume from the first PR/task not done in the roadmap/table. For single-PR work, the canonical name worktree/branch is enough and the roadmap collapses to one checkpoint.
 
 ## HTML review view (on demand)
 
@@ -61,13 +63,28 @@ If the project manages work through an issue tracker, issues (`to-issues`) take
 
 ## Closing
 
-When the work is finalized (e.g. PR created and merged into its target branch):
+There are two close levels:
+
+### PR checkpoint
+
+When an intermediate PR is merged:
+
+1. `mem_save` under `work/{name}/pr/{NN}`: what merged, what remains, and any blockers.
+2. Update the PR roadmap and task statuses in `work/{name}/plan.md`.
+3. Delete that PR's worktree if appropriate.
+4. Keep `work/{name}/` alive for the remaining PRs.
+
+### Final work close
+
+When all PRs are merged, cancelled, or deferred:
 
 1. `mem_save` under `work/{name}/done`: outcome, what shipped, anything left pending.
 2. If the PRD has lasting documentation value, move it to where the project keeps docs (e.g. `docs/`); otherwise its key decisions already live in `done`.
-3. **Delete `work/{name}/`** and remove the work's worktree. Nothing to archive — git has the code, memory has the story.
+3. **Delete `work/{name}/`** and remove the remaining worktree(s). Nothing to archive — git has the code, memory has the story.
 4. `mem_session_summary` covers the session as usual.
 
+For single-PR work, the PR checkpoint and final work close happen together: one merge, one `work/{name}/done`, then cleanup.
+
 ## Rules
 
 - One piece of work = one canonical name, stable across its whole life.

package/stack/skills/work-lifecycle/references/plan-template.md

@@ -1,6 +1,6 @@
 # Plan & Task Templates
 
-Templates for the two artifacts of a piece of work: `plan.md` (file — the status board) and the atomic tasks (Engram observations). `[name]` is the canonical kebab-case name shared by `work/[name]/`, the branch and every topic_key.
+Templates for the two artifacts of a piece of work: `plan.md` (file — the status board) and the atomic tasks (Engram observations). `[name]` is the canonical kebab-case name shared by `work/[name]/` and every topic_key. PR branches/worktrees derive from it: `[name]` for single-PR work, `[name]-prNN` for multi-PR checkpoints.
 
 ---
 
@@ -36,6 +36,19 @@ The full spec of each task is NOT a file: it lives in Engram, one observation pe
 
 [Why it wasn't chosen]
 
+## PR Roadmap
+
+> This is the live PR-level board: scope, PR status, and merge evidence live here.
+> Task-level status stays in the task table below.
+> Full checkpoint history lives in Engram under `work/[name]/pr/[NN]`.
+
+| PR | Scope | Branch | Worktree | Base | Status | Merge evidence |
+|----|-------|--------|----------|------|--------|----------------|
+| 01 | [scope] | [branch] | [worktree] | [base] | ⬜ | [evidence] |
+| 02 | [scope] | [branch] | [worktree] | [base] | ⬜ | [evidence] |
+
+> Intermediate PRs do not delete `work/[name]/`; only the final close does.
+
 ## Success criteria
 
 - [ ] [Verifiable behavior 1]
@@ -45,14 +58,16 @@ The full spec of each task is NOT a file: it lives in Engram, one observation pe
 ## Tasks
 
 > Full spec of task NN → Engram topic_key `work/[name]/task/NN`.
-> Status lives ONLY in this table — update it with a surgical edit per task.
-
-| # | Task | One-liner | Status | Wave | Deps |
-|---|------|-----------|--------|------|------|
-| 01 | [descriptive name] | [one-line description] | ⬜ | 1 | — |
-| 02 | [descriptive name] | [one-line description] | ⬜ | 1 | — |
-| 03 | [descriptive name] | [one-line description] | ⬜ | 2 | 01 |
-| 04 | [descriptive name] | [one-line description] | ⬜ | 2 | 01, 02 |
+> Task status lives ONLY in this table — update it with a surgical edit per task.
+> PR status/evidence lives in the PR Roadmap above.
+> Map each task to the PR that carries it; intermediate PRs keep `work/[name]/` alive.
+
+| # | PR | Task | One-liner | Status | Wave | Deps |
+|---|----|------|-----------|--------|------|------|
+| 01 | 01 | [descriptive name] | [one-line description] | ⬜ | 1 | — |
+| 02 | 01 | [descriptive name] | [one-line description] | ⬜ | 1 | — |
+| 03 | 02 | [descriptive name] | [one-line description] | ⬜ | 2 | 01 |
+| 04 | 02 | [descriptive name] | [one-line description] | ⬜ | 2 | 01, 02 |
 
 **Statuses**: ⬜ Pending → 🔴 RED → 🟢 GREEN → 🔍 Review → ✅ Done
 ```

package/stack/system-prompt/AGENTS.md

@@ -90,11 +90,12 @@ docs/
 
 Every piece of information about a piece of work has exactly ONE home — never two. The `work-lifecycle` skill is the single source of this flow.
 
-- In-progress work lives in `work/{name}/` (gitignored): `PRD.md` + `plan.md`. plan.md is the ONLY task status board — update statuses with surgical edits. An empty `work/` means nothing is half-done.
-- Execution worktrees always live inside the current project's root under `worktrees/{name}`. Resolve the root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, then create/use `<project-root>/worktrees/<canonical-name>`; never create worktrees next to the repo, in the repo root, under `work/`, or in external temp/shared folders.
-- Full task specs, phase outcomes and history live in Engram: `work/{name}/task/{NN}`, `work/{name}/{phase}`, `work/{name}/done`. Subagents receive a topic_key + title, never the task content inline.
+- In-progress work lives in `work/{name}/` (gitignored): `PRD.md` + `plan.md`. They stay there across intermediate PR merges; `plan.md` is the ONLY task status board — update statuses with surgical edits. An empty `work/` means nothing is half-done.
+- Execution worktrees and their branches always use the same name. Resolve the root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, then create/use `<project-root>/worktrees/<canonical-name>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints; never create worktrees next to the repo, in the repo root, under `work/`, or in external temp/shared folders.
+- Full task specs, phase outcomes, PR checkpoints and history live in Engram: `work/{name}/task/{NN}`, `work/{name}/{phase}`, `work/{name}/pr/{NN}`, `work/{name}/done`. Subagents receive a topic_key + title, never the task content inline.
 - Pending work: the project's single `work/backlog` topic_key (one upserted list — never one key per idea), or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder.
-- On close: save the outcome under `work/{name}/done`, move the PRD to the project's docs only if it has lasting value, then delete `work/{name}/`. History is memory + git — no archive folders.
+- On intermediate PR merge: save the checkpoint under `work/{name}/pr/{NN}` and keep `work/{name}/` alive for the remaining PRs.
+- On final close: save the outcome under `work/{name}/done`, move the PRD to the project's docs only if it has lasting value, then delete `work/{name}/`. `work/{name}/done` is the final outcome only. History is memory + git — no archive folders.
 
 ---
 

package/stack/system-prompt/engram-protocol.md

@@ -40,7 +40,7 @@ Use the `engram` subagent for non-trivial memory reads — it filters and return
 
 ## Work state
 
-Work tracking follows the `work-lifecycle` skill: `work/{name}/plan.md` (file) is the only status board; memory holds the task specs (`work/{name}/task/{NN}`), phase outcomes (`work/{name}/{phase}`), the final `work/{name}/done`, and the project backlog under the single key `work/backlog`. Subagents retrieve their task by the topic_key the orchestrator passes them and save their phase outcome under the topic_key they were given BEFORE their final report.
+Work tracking follows the `work-lifecycle` skill: `work/{name}/plan.md` (file) is the only status board; memory holds the task specs (`work/{name}/task/{NN}`), phase outcomes (`work/{name}/{phase}`), PR checkpoints (`work/{name}/pr/{NN}`), and the final outcome in `work/{name}/done` only after the last PR; the project backlog stays under the single key `work/backlog`. Subagents retrieve their task by the topic_key the orchestrator passes them and save their phase outcome under the topic_key they were given BEFORE their final report.
 
 ## Before ending a session