@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/generate-docs/references/GENERATION_PROCESS.md

@@ -0,0 +1,90 @@
+## Process
+
+1. **Resolve the scope** — exactly one of, in this order:
+   - an explicit argument (`NN-slug`, `fix-n`, or a path/glob) → that unit's
+     branch diff vs the default branch, or the given paths;
+   - no argument → the current branch's diff vs the default branch;
+   - on the default branch with a clean tree → the last merged unit's diff
+     (`git log --merges -1` → its diff). State the resolved scope in the
+     report.
+
+2. **Select pages with the incrementality checklist.** A guide page is
+   (re)written only if at least one holds — otherwise it is not touched:
+   - ✓ the diff changes files under the page's subject paths (page exists →
+     update it);
+   - ✓ the diff introduces a public entry point (exported API, event, command,
+     route, port) that no existing guide covers (→ create the page).
+
+   **Whole-tree regeneration is Forbidden** — an empty selection is a valid,
+   reportable outcome (`0 pages`, `Decision: PASS`).
+
+3. **Write the pages** into the adapter's guides location (see the adapter
+   table). Fixed page shape, identical on every agent:
+   - **Title** — task-oriented ("Create a domain event"), not file-oriented.
+   - **Frontmatter** — the adapter's required keys **plus the provenance
+     keys** (mandatory, exactly these names):
+
+     ```yaml
+     generated-by: agentic-workflow/generate-docs
+     source-unit: <NN-slug | fix-n>
+     updated: <ISO date>
+     ```
+
+   - **Body sections, in order**: *What this is* (1 paragraph) · *How to do
+     it* (numbered steps citing real paths — `src/...`, clickable) · *Where
+     the pieces live* (table: role → path) · *Related* (links to sibling
+     guide pages that share subject paths).
+   - **File name**: kebab-case derived from the subject module path
+     (`src/domain/events/` → `guides/domain/events.mdx`) — never a
+     model-invented name.
+   - Facts come from the diff and the code — a claim that cannot cite a path
+     does not go in the page.
+
+4. **Knowledge map** (only when the documentation map declares a `map`
+   command). The map is the navigable call/module graph that lets a reader
+   trace an error doc-to-doc to its origin. Rules — no interpretation:
+   - **Run the declared command** (a project script wrapping deterministic
+     tooling — dependency-cruiser, madge, TypeDoc, tree-sitter, an LSP dump…).
+     The model **never infers graph nodes or edges** — zero-token structural
+     truth, or no map at all.
+   - **Validate the output**: JSON with `nodes[]` (each
+     `{"id", "path"}` minimum) and `edges[]` (each `{"from", "to"}`), any
+     extra keys allowed. Invalid → write nothing, report
+     `Map: invalid output — <first mismatch>` and count it as a FAIL.
+   - Valid → write it to the adapter's map location as `graph.json`, then
+     write/refresh one wrapper page per top-level module **the scope
+     touched** (incrementality applies to wrapper pages, not to the JSON):
+     the page lists the module's nodes with source paths, direct callers,
+     direct callees, and links to guide pages sharing subject paths — the
+     stack-trace walk. Wrapper pages carry the provenance frontmatter.
+   - No `map` command declared → `Map: n/a — no map command declared` in the
+     report. Never substitute model inference.
+
+   Per-tool recipes (the mapping each tool needs to emit the shape above):
+   `dependency-cruiser --output-type json` → modules⇒nodes, dependencies⇒edges;
+   `madge --json` → adjacency object⇒edges; TypeDoc JSON → reflections⇒nodes,
+   references⇒edges; tree-sitter/LSP call hierarchy → definitions⇒nodes,
+   calls⇒edges. The project's script owns the mapping; these recipes are
+   documentation for writing that script, not something this skill executes ad
+   hoc.
+
+5. **Review export** (only with the explicit `--review` flag — never
+   automatic; findings may predate their fixes and a public site is a
+   publishing decision). Take the most recent `review-change` report available
+   in the invoking context (or the path the user names), convert its
+   fixed-format blocks verbatim into one page at the adapter's reviews
+   location (`reviews/<unit>-<ISO-date>.mdx` or `.md`), provenance frontmatter
+   included, findings tables intact — no summarizing, no re-judging (that is
+   `review-change`'s output, frozen). No report available → state it in the
+   report block and write nothing.
+
+6. **Verify.** Run the declared docs build command (e.g. `npx astro check`)
+   when the adapter declares one; otherwise check that every intra-docs link
+   in the written pages resolves. Paste the command + exit code (or the link
+   count) in the report. A red build → fix the written pages or revert them;
+   never leave the docs site broken.
+
+7. **Report** (fixed block), then the closing `→ Next:` block as the
+   ABSOLUTE last output. This skill does **not** commit — the pages ride the
+   unit's workflow (the executor or the user commits them with the unit's
+   close-out).

package/skills/init-workspace/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: init-workspace
+user-invocable: true
+version: 2.8.0
+argument-hint: <target-dir>
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Adapt the workflow scaffold to a new repository or add only missing substrate
+  blocks to an existing install. Every install, hook, and overwrite needs
+  explicit consent. Triggers: "init-workspace", "set up agentic workflow",
+  "upgrade workflow scaffold".
+---
+
+# Init Workspace
+
+Turn an empty or existing repo into one that works with the agentic workflow:
+copy the generic scaffold, then **tailor it to this project** instead of leaving
+raw placeholders.
+
+## Turn contract — verify before ending the turn
+
+```
+✓ The adapted scaffold and repository-state ledger are written (or the merge/abort decision was asked) and remaining placeholders are listed
+✓ Nothing was installed or overwritten without an explicit yes
+✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
+✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
+```
+
+About to end the turn with any box unchecked? The turn is NOT done — complete
+the missing box first (weak models drop end-of-document duties; this list is
+first on purpose).
+
+## When to use
+
+- Setting up a repo to use these skills and you want the documentation substrate
+  (`CLAUDE.md` + `docs/` map + templates) adapted to the project, not just copied.
+- Prefer this over a static `npx degit gtrabanco/agentic-workflow/template` when you
+  want the gate commands, architecture, and doc domains filled in by interview.
+
+## Step 0 — Discover the project (always first)
+
+Inspect the target dir (`[target-dir]`, default cwd) before touching anything:
+
+- Existing `CLAUDE.md` / `AGENTS.md` / `docs/` / `.github/`? If so, **do not
+  clobber** — check first whether it's an **agentic-workflow scaffold**
+  (marker: `CLAUDE.md` present *and* either `docs/features/ROADMAP.md` or a
+  `docs/workflow/` dir). If both markers are present, offer **upgrade** as the
+  default action, alongside merge / adapt-in-place / abort — see **Upgrade
+  mode** below. If `CLAUDE.md`/`docs/` exist but the markers are absent (a
+  foreign scaffold), stay in bootstrap and ask merge / adapt in place / abort
+  as before.
+- Detect the stack from manifests (`package.json`, `pyproject.toml`, `go.mod`,
+  `Cargo.toml`, `Gemfile`, …) to *propose* gate commands and naming conventions.
+- Note the git state (is it a repo, what's the default branch, and the **remote
+  URL → forge**: github.com → GitHub/`gh`, gitlab → GitLab/`glab`, else ask).
+
+
+## Progressive loading — bootstrap or upgrade, never both
+
+The reference allowlist is exactly the four linked paths below. Never invent or
+read another `references/` path. Step 0 selects exactly one route:
+
+**Hard rule for an existing Claude Code, Cursor, Copilot, or OpenCode
+scaffold:** LOAD exactly `references/UPGRADE.md`. A missing committed safety
+adapter is upgrade work, not a missing vendor primitive. Do not load bootstrap
+or portability unless the runtime platform has no named adapter at all.
+
+- Bare/foreign repository: read
+  [bootstrap discovery](references/BOOTSTRAP_DISCOVERY.md), complete its
+  interview, then read [bootstrap write](references/BOOTSTRAP_WRITE.md).
+- Existing agentic-workflow scaffold: read [upgrade](references/UPGRADE.md)
+  only. Its additive-only rule is absolute; do not replay bootstrap.
+- No named adapter exists for the detected runtime platform: add
+  [portability](references/PORTABILITY.md) only for that fallback. Claude Code,
+  Cursor, Copilot, and OpenCode are named supported adapters; a missing adapter
+  file is repaired by upgrade and does not trigger portability.
+
+All resources are one hop from this file. Existing files, hook consent,
+installation consent, and residual reporting are fixed contracts. Missing
+template/migration evidence is reported by the selected route, never filled by
+guessing. An existing OpenCode scaffold with only its safety adapter missing
+loads exactly upgrade and skips bootstrap plus portability.
+
+## Guardrails
+
+- **Never overwrite an existing `CLAUDE.md` or `docs/` without explicit consent.**
+- **Additive-only, never clobber (upgrade mode).** Upgrade mode only adds
+  blocks the project lacks and fills raw placeholders — it never rewrites or
+  deletes a block the project already tailored, even if the current template
+  changed that block too. A genuine re-tailor is a separate, explicitly
+  requested bootstrap adapt-in-place run, never something upgrade mode does
+  on its own. **The urgency label seeding is additive-only the same way:**
+  create a missing `urgent`/`fix-next` label, never touch one that already
+  exists (name, color, or description a project already customized).
+- **Never redefine the urgency label vocabulary here.** `skills/triage-issue
+  /SKILL.md` is the sole owner of the `urgent`/`fix-next` names, colors, and
+  apply rules — this skill only seeds those two labels into the repo; it never
+  invents a third label or changes what the two mean.
+- Docs-only scaffolding; no app code, no dependencies installed unprompted.
+- Architecture-agnostic: record the project's pattern, don't impose one.
+- Honest placeholders over invented specifics; flag what's left to fill.
+- Honor the project's **Workflow conventions** once present; on an existing repo,
+  don't work on its default branch and never commit/push unless asked.
+
+## Normalized Repository State
+
+Seed `docs/workflow/REPOSITORY_STATE.md` from the template. Explain that
+discovery freezes evidence before planning and only the resolver updates facts.
+
+## Architectural invariants
+
+Offer `docs/architecture/ARCHITECTURAL_INVARIANTS.md` as an optional project
+contract for long-lived architectural rules. Its entries must name a stable ID,
+repository evidence, and the authority that can change the rule. Do not infer a
+rule from the implementation or a feature SPEC. A project without this document
+remains compatible; record `n/a: no project invariants declared` in later
+workflow artifacts rather than creating one silently.
+
+
+## Portability
+
+The scaffold is vendor-neutral; only hook activation differs. When the detected
+agent has no named adapter, follow [portability](references/PORTABILITY.md) and
+keep it as an explicit residual. A supported Claude Code, Cursor, Copilot, or
+OpenCode adapter does not load this fallback.
+
+## Relationship to other skills
+
+- `npx degit gtrabanco/agentic-workflow/template` — the static copy this skill
+  adapts. Use that when you want the raw scaffold and will fill it yourself.
+- `docs/workflow/PORTABLE_PROMPT.md` — regenerates the **skills** adapted to a
+  project (behavior). This skill adapts the **substrate** (docs). Complementary.
+- After init: `discover-repository-state` → `design-feature` → `plan-feature` →
+  `execute-phase`; run `audit-docs` to confirm the scaffold is coherent.
+
+## Done when
+
+- A tailored `CLAUDE.md` + `docs/` scaffold + `.github/` templates exist in the
+  target, unused folders pruned, residual placeholders flagged, the platform's
+  companion review skills are recorded (and offered), and the `urgent`/
+  `fix-next` labels are seeded (scaffold) or additively reconciled (upgrade),
+  and every accepted safety adapter is active and fixture-tested — or explicitly
+  listed as a residual when its hook API/dependency was unavailable.
+- **The closing `→ Next:` block is printed** (plus the offer to install the skills):
+
+  ```
+  → Next: /discover-repository-state — freeze repository evidence before planning
+    · raw idea → /design-feature "<idea>" after discovery
+    · next roadmap entry → /plan-feature --next after discovery
+    · confirm the scaffold is coherent → /audit-docs
+  ```

package/skills/init-workspace/references/BOOTSTRAP_DISCOVERY.md

@@ -0,0 +1,70 @@
+## Process
+
+1. **Preflight.** Confirm the target dir and the discovery findings. If scaffold
+   files already exist, get an explicit decision before overwriting.
+2. **Fetch the template.** `npx degit gtrabanco/agentic-workflow/template <dir>`
+   (into the target if empty, else a temp dir to merge from). **`degit` can't read
+   a private repo — it fails, or in `--mode=git` silently leaves an empty dir; for
+   a private source, `git clone` via SSH and copy the `template/` subtree instead.**
+3. **Interview to adapt** — small batched rounds, each with a recommended default
+   drawn from Step 0; skip whatever discovery already answers:
+   - **Project** — name + one-line purpose.
+   - **Gate** — dev / build / test commands and the verification gate (proposed
+     from the detected stack; confirm).
+   - **Forge** — issue/PR tracker + CLI (proposed from the remote URL; confirm)
+     → recorded in the Workflow conventions **Forge** line.
+   - **Git workflow** — how parallel work is handled: **branches** (default —
+     one active unit at a time, sequential, plain `git switch -c`) or
+     **worktrees** (parallel units in separate checkouts; only if the user's
+     agent/tooling manages them). Recorded in the Workflow conventions
+     **Git workflow** line; every skill that creates branches honors it.
+   - **Agent safety hooks** — detect where the agent actually runs and which
+     repository adapters apply: Claude Code, Cursor, Copilot, OpenCode, or none.
+     Recommend the shared command guard for every detected platform; explain
+     that shell adapters require `jq`, OpenCode uses the bundled Bun plugin,
+     and hooks are defense-in-depth behind forge rulesets. Ask one explicit
+     yes/no per adapter before activating it. Remote/VPS execution is not a
+     reason to skip: commit the repository adapter so the remote clone loads it.
+   - **Docs language.**
+   - **Architecture** — pattern, layers/modules, and dependency-direction rules
+     (stay architecture-agnostic; record the user's choice in `ARCHITECTURE.md`).
+   - **Doc domains** — which of `providers/ brand/ domain/ business/
+     infrastructure/ legal/ frontend/` apply. **Delete the folders that don't**
+     (e.g. `frontend/` for a non-UI project).
+   - **Capability inventory** (`docs/CAPABILITIES.md` — the substrate
+     `design-feature`'s Integration closure walks). Seed it from discovery,
+     not raw placeholders: on an existing codebase, propose the roles and the
+     `yes|no|partial` state of each template subsystem row (auth, ACL,
+     navigation, notifications, search, audit, settings, jobs, storage, i18n,
+     flags, billing, public API) from what the code actually shows; on an
+     empty repo, walk the same fixed rows with the user (`no` is a valid,
+     load-bearing answer). Delete rows that can never apply to this product;
+     confirm the result in one round — never leave the file as the raw
+     template.
+   - **Performance tooling** — detect what the stack offers, one slot at a
+     time (fixed checklist, first match per slot; record `none` explicitly
+     when nothing fits — never leave the slot undiscussed):
+     - *Static complexity lint*: Biome present → enable its `complexity`
+       group (incl. `noExcessiveCognitiveComplexity`); ESLint present →
+       suggest `eslint-plugin-sonarjs` + `eslint-plugin-unicorn`; neither →
+       ask for the stack's equivalent or record `none`.
+     - *Benchmark harness*: Vitest → `vitest bench`; Bun runtime → `mitata`;
+       Node → `tinybench`/`mitata`; other stacks → ask for the project's
+       benchmark command or record `none`.
+     - *Profiler*: Node → `node --cpu-prof` (zero-dependency default) or `0x`
+       via the project's package runner; Bun → `bun --inspect` CPU profiling;
+       other → ask or record `none`.
+     (The named tools are the TS/JS **adapter examples**; the contract is the
+     generic block below.) Offer installation — **the user confirms each
+     dependency; never install silently** — and register the outcome in the
+     template's `Performance commands` block next to the verification gate,
+     so `review-perf` can measure instead of guess.
+   - **Docs site** — does the project have (or want) a developer docs website
+     the `generate-docs` skill can write into? If yes, fill the template's
+     `Docs site` block in `CLAUDE.md` (format: starlight/docusaurus/markdown,
+     content dir, build command, optional knowledge-map command — proposed
+     from discovery: an `astro.config.*` + `@astrojs/starlight` dependency
+     means Starlight). If no, leave the block commented out — `generate-docs`
+     then reports NOT-CONFIGURED instead of guessing. Never scaffold the
+     website itself.
+   - **Naming conventions** and **MCP servers**, if any.

package/skills/init-workspace/references/BOOTSTRAP_WRITE.md

@@ -0,0 +1,58 @@
+## Write and verify the bootstrap
+
+4. **Write the adapted scaffold.** Fill the `CLAUDE.md` placeholders (commands,
+   the documentation map rows, architecture); keep `AGENTS.md`, the
+   `features/_TEMPLATE` + `ROADMAP`, the `fix/_TEMPLATE` + `README`, and the
+   `.github/` templates; keep `.agentic-workflow/hooks/` and activate only the
+   adapters explicitly accepted in the interview; prune unused doc folders and
+   map rows. Leave honest placeholders where the user hasn't decided — never
+   invent values.
+5. **Seed Normalized Repository State.** Copy
+   `template/docs/workflow/REPOSITORY_STATE.md` to
+   `docs/workflow/REPOSITORY_STATE.md` when it is absent. If the target already
+   has one, leave it unchanged and report that discovery should refresh it.
+   Explain that discovery freezes evidence before planning and only
+   `resolve-repository-state` updates frozen facts.
+6. **Offer architectural invariants.** Keep
+   `docs/architecture/ARCHITECTURAL_INVARIANTS.md` from the template only when
+   the project has long-lived architectural constraints. Explain that it is
+   optional: an absent document means no project invariants are declared, not
+   that the scaffold failed. If retained, add its documentation-map row and
+   name the project's explicit architectural-decision authority.
+7. **Install accepted agent safety hooks.** Keep the canonical policy and
+   fullauto wrapper at `.agentic-workflow/hooks/`. For each accepted platform,
+   activate only its repository config/example as documented in the hook pack.
+   Run `bash .agentic-workflow/hooks/tests/test-command-guard.sh`; missing `jq`,
+   an unknown payload, or an existing customized hook file becomes a residual,
+   never a silent overwrite. Direct merges remain blocked; do not create a
+   `.automerge` exception.
+8. **Offer the workflow skills.** Propose installing them:
+   `npx skills add gtrabanco/agentic-workflow` (note the SSH/local-path variant if
+   the source is private). Don't install without a yes.
+9. **State that reviews are self-contained; offer optional extras.** The
+   workflow ships its **own internal review pack** (`review-code`,
+   `review-security`, `review-verify`, `review-debt`, `review-design`,
+   `review-a11y`, `review-brand`, `review-perf`, `review-seo`) — it installs
+   with the skills and covers every review axis, so **no external review skill
+   is required on any agent**. If the user wants platform-specific extras (a
+   framework skill, a stack-specific security skill), record them in `CLAUDE.md`
+   under a short "Optional review extras" note so `review-change` and
+   `product-audit` run them **in addition** — never as a dependency. Don't
+   install anything without a yes.
+10. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
+   two capability-gated GitHub labels `triage-issue` owns and applies
+   (`skills/triage-issue/SKILL.md` is the sole owner of the name/color
+   vocabulary — this step only seeds it, never redefines it):
+   `gh label create urgent --color B60205 --description "Evaluate for
+   interrupt-now — reaches the pause-vs-finish judge"` and
+   `gh label create fix-next --color D93F0B --description "Head of the fix
+   queue — never interrupts the in-flight unit"`. Create-if-missing: an
+   "already exists" error from `gh label create` is treated as success, not a
+   failure. Requires the forge remote/auth Step 0 already detected — if the
+   forge is unavailable or the user declines forge setup, skip this step and
+   list the two labels as a residual for the user to create manually later
+   (never fail the whole scaffold on it).
+11. **Report.** List what was created, which placeholders still need human input,
+   the companion skills recorded/installed, the urgency labels seeded (or
+   skipped, with reason), and the next step: `discover-repository-state` →
+   `design-feature` → `plan-feature` → `execute-phase`.

package/skills/init-workspace/references/PORTABILITY.md

@@ -0,0 +1,16 @@
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **No slash-command menu** — where this skill says `/<skill>`, open that
+  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
+  literally, in a fresh conversation: hand-offs assume a clean context.
+- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+  the interview and adaptation are judgment work — run them on your
+  **strongest** model.
+- **No Claude Code hooks** — choose the Cursor, Copilot, or OpenCode adapter
+  when available. If the agent exposes no pre-tool hook, report the safety hook
+  as unavailable and keep forge rulesets as the hard boundary; `log-session`
+  remains the manual logging alternative.

package/skills/init-workspace/references/UPGRADE.md

@@ -0,0 +1,83 @@
+## Upgrade mode
+
+Entered when Step 0 finds an existing **agentic-workflow scaffold** (not a
+bare or foreign repo). Bootstrap mode (the Process section above) never
+engages here — upgrade mode reuses the same discovery + interview machinery,
+scoped to **only the blocks the current template has that this project
+lacks**. Seven ordered steps:
+
+1. **Locate the current template.** Fetch the current `template/` the same
+   way bootstrap does — `npx degit gtrabanco/agentic-workflow/template <temp-dir>`
+   (always into a temp dir here, never into the target); the SSH/local-path
+   variant applies verbatim for a private source.
+2. **Diff the substrate.** Compare the project's `CLAUDE.md` (and the `docs/`
+   blocks its documentation map references) against the fetched template.
+   Produce the list of blocks/conventions the template carries that this
+   project's substrate lacks, or still holds as a raw, unfilled placeholder —
+   e.g. a `Docs site` block, a `Performance commands` block, a `Git workflow`
+   line, the five-state roadmap `Status legend`, the capability inventory
+   (`docs/CAPABILITIES.md` + its documentation-map row), the optional
+   architectural-invariants document
+   (`docs/architecture/ARCHITECTURAL_INVARIANTS.md` + its documentation-map
+   row), the portable command-guard pack and detected platform adapter, or the Normalized
+   Repository State ledger (`docs/workflow/REPOSITORY_STATE.md`). This is the
+   diff-against-current-template contract; it is the only source of *what's
+   new*. (A missing `docs/CAPABILITIES.md` is proposed with the same
+   discovery-seeded defaults bootstrap's interview uses — never as the raw
+   template. A missing repository-state ledger is proposed from the template
+   without overwriting any existing ledger.)
+3. **Read `docs/workflow/MIGRATION.md`.** For each missing block, pull its
+   dated migration note so the proposal explains *why* the block exists and
+   *what* it migrates. If `MIGRATION.md` is absent, proceed on the template
+   diff alone and say so in the report — never block on a missing note.
+4. **Propose only the missing blocks — one short, batched interview round.**
+   Each item is the block, a discovery-based default (the same detection
+   bootstrap mode already runs — e.g. `astro.config.*` + Starlight ⇒ `Docs
+   site` default, Biome ⇒ the complexity-lint slot, the remote URL ⇒ forge),
+   and the `MIGRATION.md` rationale when available. The user accepts, edits,
+   or skips each block. **Never re-ask what the project already answered** —
+   a block that's already filled is skipped, not re-interviewed.
+5. **Write additively.** Insert accepted blocks, including a missing
+   `docs/workflow/REPOSITORY_STATE.md`; fill raw, still-placeholder
+   blocks with the confirmed values. **Never rewrite a block the project has
+   already tailored, and never delete anything** — a tailored block the
+   template also changed is left untouched and listed as a residual, not
+   silently updated. For hooks, add the canonical pack when absent and activate
+   a platform adapter only after an explicit yes; never replace an existing
+   platform hook config. Leave honest placeholders where the user skipped.
+6. **Seed missing urgency labels, additively (feature 15).** Independent of
+   the `CLAUDE.md`/`docs/` block diff above (this is forge-repo state, not a
+   doc block): check whether the target repo already has the `urgent` and
+   `fix-next` labels (`gh label list`); create whichever is missing with the
+   same `gh label create` calls bootstrap mode uses (see Process step 9) —
+   never touch a label that already exists (additive-only, same never-clobber
+   rule as the doc blocks; a pre-existing `urgent`/`fix-next` label the
+   project recolored or redescribed is left exactly as-is).
+7. **Report + hand off.** Summarize blocks added, filled, and skipped
+   (residuals), the urgency labels seeded (or already present), then print the
+   recommendation to run `product-audit` next to see which newly-available
+   *capabilities* apply to the code (upgrade mode migrates the substrate only,
+   never the code).
+
+**Failure edges — handle each explicitly, never silently:**
+
+- **No drift.** The diff (step 2) finds nothing missing or placeholder-only →
+  skip the interview entirely and report **"substrate current, nothing to
+  migrate"**. Never fabricate a block to propose just to have something to
+  show.
+- **`MIGRATION.md` absent.** An older install may predate this file → proceed
+  on the template diff alone (step 3 already covers this) and say so plainly
+  in the proposal and the final report: rationale was unavailable, the block
+  list is still complete.
+- **A block the project already tailored.** If the current template also
+  changed a block the project customized, **do not merge, diff-patch, or
+  overwrite it** — leave it exactly as the project has it and list it as a
+  residual in the report (step 5's never-clobber invariant). The user decides
+  separately, via an explicit bootstrap adapt-in-place run, whether to
+  re-tailor it.
+- **Bootstrap stays unchanged on a bare or foreign repo.** If Step 0's
+  scaffold markers (`CLAUDE.md` + `docs/features/ROADMAP.md` or
+  `docs/workflow/`) are absent — no repo, an empty repo, or a `CLAUDE.md`
+  that isn't this workflow's — upgrade mode never engages; the existing
+  bootstrap Process (merge/adapt/abort) runs exactly as before this mode was
+  added.

package/skills/log-session/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: log-session
+user-invocable: true
+version: 2.0.0
+argument-hint: "[note to prepend to the entry]"
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Append a structured entry to the project's session log (`docs/LOGS.md`):
+  what was done this session, files touched, decisions taken, and the next
+  step — so the next session (or another person) can pick up the thread
+  without re-reading git history. Run it before `/clear`, before closing
+  Claude Code, or at any natural stopping point. On Claude Code and want hand-tuned per-skill model/effort tiers? Install the `#claude` branch instead (`npx skills add gtrabanco/agentic-workflow#claude`) — see the README. This branch is model-agnostic: the skill inherits whatever model and effort your agent session is already using.
+  Triggers: "log this
+  session", "log-session", "write a session log", "journal what we did",
+  "record this session before I clear", "save the session summary".
+---
+
+# Log Session
+
+Capture the *why* and the *what-next* of a working session — the context that
+git history alone never records. A commit says what changed; a session log says
+what you were trying to do, what you decided, and where to resume.
+
+Deliberately cheap (`sonnet`/`medium`): this is structured summarization, not
+judgment. It must never reach for an expensive model.
+
+## Turn contract — verify before ending the turn
+
+```
+✓ The entry was APPENDED to docs/LOGS.md (file edited, not just drafted) with accurate git facts
+✓ No past entry was edited
+✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
+✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
+```
+
+About to end the turn with any box unchecked? The turn is NOT done — complete
+the missing box first (weak models drop end-of-document duties; this list is
+first on purpose).
+
+## When to use
+
+- **Before `/clear`** (or your agent's context-reset equivalent) — you're about
+  to wipe context; capture it first.
+- **Before closing your agent** for the day.
+- **At a natural stopping point** — a feature paused mid-way, a thread you want
+  to be able to resume cold.
+- **After a long session** with several decisions worth remembering.
+
+This is the *manual, rich* counterpart to the lightweight auto-logging hooks
+the `template/` ships (see `template/.claude/`). The hooks capture the
+mechanical facts for free on every exit; this skill writes the thoughtful
+entry when you want one.
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, locate
+the session log. Default path: `docs/LOGS.md`. If the documentation map names a
+different location, use that. If no log file exists yet, create it from the
+shape in `template/docs/LOGS.md` (a short header + the entry format below) and
+say so.
+
+If a session-start marker exists (`.claude/.session-*.start`, written by the
+template's SessionStart hook), read it to bound the session precisely — it holds
+the HEAD sha and start time at session open.
+
+## Process
+
+1. **Establish the session boundary.**
+   - If a marker is present, the session spans `marker_sha..HEAD` plus any
+     uncommitted work.
+   - Otherwise, use your own conversation context as the source of truth for
+     what happened this session, and corroborate with `git log` of the recent
+     commits and `git status` / `git diff --stat` for uncommitted changes.
+
+2. **Gather the mechanical facts** (cheaply, with git):
+   - branch (`git branch --show-current`),
+   - commits this session (`git log --oneline <since>..HEAD`),
+   - files touched (`git diff --stat <since>..HEAD` + uncommitted).
+
+3. **Write the narrative** — the part only you can add:
+   - **Summary:** 1–3 sentences on what this session set out to do and what
+     actually got done.
+   - **Decisions:** the non-obvious choices made and *why* (the rationale that
+     would otherwise be lost). Link related docs/issues.
+   - **Next:** the concrete next step(s) — the command to run, the unfinished
+     thread, the open question. Write it so a cold reader knows exactly where to
+     resume.
+
+4. **Append the entry** to `docs/LOGS.md`, newest at the bottom (append-only,
+   chronological). Use this format so the auto-hook entries and these stay
+   compatible:
+
+   ```markdown
+   ## <ISO-8601 timestamp> — <branch> — manual
+   - **Commits:** <n> (`<short-sha>…<short-sha>`)
+   - **Files:** <comma-separated paths, or a count if many>
+   - **Summary:** <what this session did>
+   - **Decisions:** <key choices + why; omit the line if none>
+   - **Next:** <the concrete next step>
+   ```
+
+   If the user passed a note as an argument, prepend it to the Summary.
+
+5. **Commit policy.** `docs/LOGS.md` is documentation — keep it coherent, but do
+   **not** open a PR just for a log entry. If you're mid-feature on a branch,
+   the entry rides along with the next commit. If the working tree is otherwise
+   clean and the user wants it persisted, ask before committing a standalone
+   `docs(log): session <date>` commit. Never push without the project's push
+   convention.
+
+## Guardrails
+
+- **Never use an expensive model for this.** It's summarization; `sonnet` is the
+  ceiling, and the hooks do the free mechanical version.
+- **Don't invent facts.** Decisions and next steps come from the actual session
+  (your context + git), not plausible-sounding filler. If a section has nothing
+  real, omit its line rather than padding.
+- **Append, never rewrite.** Past entries are a historical record — don't edit
+  or "tidy" them. Same reasoning as not rewriting a delivered feature's planning
+  artifacts.
+- **One file, append-only.** Don't fan session logs across files.
+
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **No Claude Code hooks** — the template's auto-logging hooks (SessionStart
+  marker, SessionEnd entry) don't run on other agents, so there is no marker
+  file and no free mechanical entry: this skill is the **only** journal writer.
+  Run it before ending every session, and bound the session with git alone
+  (Process step 1's no-marker path).
+- **No `/clear`** — read it as your agent's context-reset / new-conversation
+  equivalent, in the triggers and in the closing block alike.
+- **No per-skill `model:`/`effort:`** — the intent stands: use a **cheap**
+  model for this. It's summarization, never judgment.
+
+## Relationship to other skills
+
+- Complements the `template/`'s **SessionEnd hook** (free, mechanical, automatic
+  on `/clear` and exit) and the **opt-in SessionStart restore hook** (re-injects
+  the last entry to resume context). This skill is the rich, manual entry.
+- Pairs with `execute-phase`'s per-feature `progress.md`: that tracks progress
+  *within* a feature; the session log is *cross-cutting* — whatever you touched
+  this session, across features/fixes.
+- Not part of the PR gate — it's a working-memory aid, not a merge artifact.
+
+## Done when
+
+- A new entry is appended to `docs/LOGS.md` with at least Summary and Next.
+- The mechanical facts (branch, commits, files) are accurate to git.
+- **The closing `→ Next:` block is printed:**
+
+  ```
+  → Next: /clear (or your agent's context reset) is now safe — the session is captured
+    · resume later → the command named in the entry's **Next** line
+  ```