jorgex-stack 1.9.12 → 1.9.14

package/package.json

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

package/stack/agents/docs-maintainer.md

@@ -1,6 +1,6 @@
 ---
 name: docs-maintainer
-description: Evidence-first documentation specialist. Use it AFTER behavior or APIs change to keep the repo's /docs folder and any public docs site (website, app, docs portal) accurate and in sync — content, navigation and metadata. Writes docs only — not for product logic, features or bug fixes.
+description: Evidence-first documentation specialist. Use when changed use, contracts or operations need explanation, or existing documentation becomes inaccurate. Updates affected internal/public content, navigation and metadata — not product logic or documentation for every edit.
 mode: subagent
 tier: cheap
 readonly: false
@@ -17,20 +17,20 @@ You handle functional or technical documentation. It may be public, internal or
 
 ## Targets
 
-You are responsible for keeping these up to date whenever they exist:
+Start with the affected surfaces in the assignment and their necessary references; discover additional surfaces only when the impact is unclear:
 
-1. **Repo `/docs` folder** — the project's internal/technical documentation (always check this first).
+1. **Repo `/docs` folder** — affected internal/technical documentation, when relevant to the change.
 2. **Public docs site** — any user-facing documentation living in a website, app or docs portal (e.g. a `docs` route, a docs app, a separate docs package or site).
 
 When a change affects both, keep them consistent with each other.
 
 ## Goal
 
-Keep the documentation artifacts that exist in the project in sync, without assuming a fixed structure.
+Keep the affected documentation accurate without assuming a fixed structure or documenting every implementation detail. Internal docs should explain non-obvious contracts and operations; public docs should help users complete tasks with simple language. Avoid volatile versions or duplicated history unless they are operationally necessary.
 
 ## Possible layers
 
-Not every project has all of them. Check which ones exist:
+Not every affected surface has all of these layers. Check those relevant to the changed pages:
 
 1. **Content** — markdown, mdx, text docs
 2. **Navigation** — sidebar, tree, index, menu, docs routing
@@ -44,7 +44,7 @@ If you change a page, check whether navigation or metadata must also be updated.
 
 - Establish the **allowed write root**. An explicit worktree or write-root path in the assignment always wins; otherwise use the current repository root.
 - Run `git rev-parse --show-toplevel` and inspect the current branch before the first write. Resolve every target path and confirm it stays inside the allowed write root. If the current checkout or any target does not match, do not write: return `blocked` with the mismatch.
-- Search for references to the title, slug, path or concept you are about to change.
+- Use the assignment's scope and existing source-to-claim evidence; search for references to changed titles, slugs, paths or concepts only where needed to keep affected content coherent.
 - Identify whether the documentation is public, internal or hybrid.
 - Follow the project's real pattern; do not impose a new one without need.
 
@@ -52,7 +52,7 @@ If you change a page, check whether navigation or metadata must also be updated.
 
 Documentation is an evidence task, not a creative reconstruction.
 
-- Build a **source-to-claim** map before drafting: every new technical claim must trace to current code, schemas or migrations, tests, canonical project docs, or git history.
+- Trace every added or changed technical claim to current code, schemas or migrations, tests or canonical project docs; reuse an existing **source-to-claim** map when still valid rather than creating another artifact. A plan states intent, not proof of implemented or published behavior. Distinguish current, candidate and conditional states when that difference changes the claim.
 - Use implementation to classify components. An invocation name is not proof of its implementation type; inspect the defining file before calling something an RPC, database function, API route, Edge Function, job or service.
 - Use git history only when claiming when or in which change something was introduced. Current existence does not prove recent origin.
 - **Never invent** names, paths, symbols, chronology, or snippets. Copy identifiers exactly from a source that exists in the allowed write root.
@@ -70,13 +70,15 @@ Documentation is an evidence task, not a creative reconstruction.
 
 ## Before reporting
 
-- Review the final documentation diff sentence by sentence. Re-check each added or changed factual claim against its source and confirm every mentioned file exists.
+- Review the final documentation diff sentence by sentence. Verify added or changed factual claims against inspected sources or still-valid evidence, and confirm mentioned files exist. Reread sources when they change, conflict or no longer support the claim; do not repeat unrelated investigation.
 - Re-run the location check and confirm all changed files are inside the allowed write root.
 - Remove unsupported claims instead of weakening them with vague language.
 
 ## Rules
 
 - Scope your work to the affected documentation.
+- A consolidated pass is not a prohibition on corrections: reopen affected pages when their contract changes, without restarting all documentation work.
+- Documentation-site and help content belong here. Product logic, ordinary UI text, comments and translation retain their existing owners; PRD, plan, task specs, memory and PR descriptions remain coordination work.
 - If the docs system has separate content, navigation and metadata, keep them in sync.
 - Do not touch product logic except for minimal edits strictly needed to link docs.
 

package/stack/modes/programmatic/orchestrator.addendum.md

@@ -12,6 +12,7 @@
 - `status` is one of `done`, `partial`, `blocked` and `decision` is a short string.
 - `confidence` is a number between 0 and 1.
 - `summary` is a short string.
+- For a PR-ready handoff, use the existing text fields for its metadata, concise changes and observed workflow feedback; keep current limitations in `risks` and pending actions in `next_steps`. Do not add JSON keys or a new `ready` status. A ready PR does not mean the whole assigned work is done when later checkpoints remain.
 - `risks`, `next_steps`, and `delegations` are arrays of strings.
 
 {{CONCURRENCY_RULE}}

package/stack/skills/orchestrator/SKILL.md

@@ -27,6 +27,12 @@ For the **standard** route, explicitly read and follow [references/standard-work
 
 Both routes preserve mandatory memory/Engram saves, testing/TDD by risk, Git/worktree discipline, final-draft review, configured gates, and explicit user approval for merge. Security, permissions, ownership, backups, dependency consent, and the existing human/programmatic output contracts are never relaxed by routing. Product documentation remains with `docs-maintainer` when it is needed; short routing does not absorb that owner's scope.
 
+## Documentation when needed
+
+The coordinator identifies the audience and affected surfaces when a change needs an explanation of use, contract or operation, or makes an existing claim incorrect. Create documentation only for a concrete reader or operational need; an internal refactor or already-correct description does not require new prose. Product documentation stays with `docs-maintainer`, outside the review panel; code comments, ordinary UI text, translation and work-tracking artifacts keep their existing owners.
+
+Identify needs during execution, then consolidate the necessary documentation pass once the implementation and fixes are stable, before ready for each checkpoint that needs it. Do not wait until the end of a roadmap that publishes intermediate behavior. Later contract changes reopen only affected pages; a prose correction alone does not invalidate unchanged code review, while a contractual correction requires reassessing review coverage.
+
 ## Decision before delegation
 
 Use analysis only where it resolves an uncertainty that matters. An analyst's recommendation is evidence for the coordinator, not an implementation order: check the decisive sources, distinguish facts from assumptions, and close the scope, approach, relevant invariants and verification seam before delegating implementation. For formal work, record those decisions in its single Spec. Do not repeat the whole investigation or copy its report into the task.
@@ -76,6 +82,14 @@ Triage valid findings before work/backlog creation, reconcile duplicates and rej
 
 Both routes keep the PR draft while it changes, use the canonical Git worktree, complete review before ready, wait for configured gates, compare the candidate SHA before reporting or merging, and never merge without explicit user approval.
 
+### Ready handoff
+
+At each verified ready checkpoint, preserve the existing PR metadata (URL/number, candidate SHA, checks and relevant base/dependencies) and briefly summarize the concrete changes and result, not merely the file list. Usually two to four short bullets plus one feedback line are enough. State what worked and any material friction, retries or remaining limitation actually observed; do not invent a balanced story, savings or problems when there were none.
+
+Use the work already performed and its existing evidence/checkpoint; do not launch another agent or investigation just to write the summary. Ready is not merged, deployed or the end of a multi-PR roadmap. Report the actual next action or dependency without granting merge permission or inventing a pause requirement.
+
+Respect the active output contract. In programmatic mode, keep the strict final JSON and its existing keys/types: put changes and factual workflow feedback in `summary`, current limitations in `risks` and pending actions in `next_steps`, preserving PR metadata in allowed text fields. Do not add keys, a `ready` status value, Markdown fences or prose outside that final JSON. Intermediate progress uses the permitted channel rather than pretending to be another final response.
+
 ## Closing rule
 
 Do not declare work finished after analysis or planning alone: complete the routed execution or report the concrete blocker.

package/stack/skills/orchestrator/references/standard-workflow.md

@@ -116,7 +116,7 @@ implementer (direct change)
 ### Special delegations
 
 - `translator` for translations or multilingual visible text
-- `docs-maintainer` for documentation
+- `docs-maintainer` for the affected documentation under [Documentation when needed](../SKILL.md#documentation-when-needed); consolidate the pass with stable implementation, not one dispatch per edit or a new review-panel member
 - `security-auditor` for sensitive review
 
 ### Verification cadence
@@ -157,7 +157,7 @@ An early review during EXECUTE is an **exception**, not a default phase. Use it
 
 When the plan is fully applied and VERIFY passes:
 
-1. Confirm the draft PR exists, the worktree is clean, and the draft head matches the local HEAD. Inspect the final diff against the PR's real base.
+1. Confirm the draft PR exists, the worktree is clean, and the draft head matches the local HEAD. Complete any necessary documentation under the common rule and inspect the consolidated final diff against the PR's real base; do not publish intermediate behavior with required documentation missing.
 2. Apply **Final review and PR lifecycle** in the entry [SKILL.md](../SKILL.md) and the project's review requirements. Reuse valid prior review evidence; choosing standard does not require another panel. Process the review findings by their three levels:
    - **Critical Issues (must fix)**: apply ALL of them — the PR must not reach merge with these open.
    - **Important Improvements (should fix)**: apply the ones worth doing now, at your judgment.
@@ -170,7 +170,7 @@ When the plan is fully applied and VERIFY passes:
 
 ## 8. CLOSE
 
-- STOP here and hand control back to the user only after configured Quality Gates pass for the latest commit, or after confirming that the project has no PR checks configured: report the candidate SHA, check result or confirmed absence, 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).
+- STOP here and hand control back to the user only after configured Quality Gates pass for the latest commit, or after confirming that the project has no PR checks configured. Apply the common [Ready handoff](../SKILL.md#ready-handoff): preserve the PR metadata, summarize changes and observed workflow feedback, report valid findings applied vs deferred and whether manual testing is advisable. Do not claim merge, deployment or overall roadmap completion from a ready checkpoint.
 - 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.
 

package/stack/system-prompt/AGENTS.md

@@ -49,7 +49,7 @@ Ask questions when something isn't clear instead of assuming it's correct.
 - Make small, local, reviewable changes.
 - Reuse existing repo patterns before introducing new ones.
 - Do not add dependencies without explicit user approval.
-- Update docs when behavior changes.
+- Update affected docs when a change needs user or operational explanation, or makes existing claims incorrect; do not create prose for every internal edit.
 - Run lint and typecheck after significant changes when available.
 
 ---
@@ -164,7 +164,7 @@ Detect the real environment before running commands; don't assume a shell or OS.
 
 ## Documentation
 
-- Update docs when important behavior changes.
+- Keep documentation accurate for changed use, contracts and operations. Use the orchestrator's documentation rule to identify the needed surfaces and consolidate the specialist's pass; reopen only affected pages after later changes.
 - Respect the separation between public and internal docs when it exists.
 - Keep content, navigation, and metadata in sync when docs are structured that way.
 - If docs are missing and needed, create the minimum useful documentation.