@lovehlmmm/primekit 1.0.0

package/skills/handoff/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Ondrej
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/handoff/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: pk:handoff
+description: Create a portable, redacted Markdown continuation contract that a fresh coding agent can consume to resume in-progress work safely. Use when switching sessions, models, or runtimes, or when preserving decisions, verification state, and blockers.
+user-invocable: true
+when_to_use: Invoke to capture a session's continuation contract for a successor agent. For a human-facing status report derived from branches, worktrees, plans, and repository history, use primekit-watzup instead.
+category: utilities
+keywords: [handoff, session, continuation, decisions, blockers, redaction]
+license: MIT
+argument-hint: "[task focus] [--output PATH] [--include-diff] [--include-status] [--force]"
+metadata:
+  author: primekit
+  version: "2.0.0"
+  upstream: "Pinned MIT source archive: handoff@ce70edaa26247b84c2b9491a0cdb4964f65cf3a5 (rewritten for PrimeKit v2 contract)"
+---
+
+# Handoff
+
+Create one Markdown artifact that lets a fresh coding agent resume in-progress
+work with minimal rediscovery. The artifact is a **continuation contract**:
+mission, guardrails, live state, decisions, verification, blockers, and the
+exact next safe action — never a transcript dump, never invented context.
+
+This skill is a documentation/capture surface only. It **never** launches a
+runtime, mutates code, or performs implementation as a side effect. That
+composition belongs to [`pk:handover`](../primekit-handover/SKILL.md).
+
+## Boundary vs `pk:watzup`
+
+- `pk:handoff` = continuation contract for a **successor agent**. Session
+  reasoning, decisions, verification state, exact next actions.
+- `pk:watzup` = status report for a **human**, derived from branches,
+  worktrees, plans, and repository history.
+
+When in doubt: is the reader another AI agent about to continue this exact
+task? Handoff. A human wanting to know where the project stands? Watzup.
+
+## Inputs
+
+Accepted forms:
+
+```bash
+/pk:handoff
+/pk:handoff "continue the OAuth callback fix"
+/pk:handoff --output plans/handoffs/oauth-callback.md
+/pk:handoff --include-diff --include-status
+/pk:handoff --force --output plans/handoffs/oauth-callback.md
+```
+
+Flags:
+
+| Flag | Effect |
+| --- | --- |
+| _(bare)_ | Capture the current session's continuation contract with an auto-derived slug. |
+| `[task focus]` | Optional single-string focus for the successor agent. Included in the Mission section and the artifact filename slug. |
+| `--output PATH` | Explicit artifact path. Must resolve inside the workspace root; parent directory is created if it does not exist; the auto-derived slug/timestamp is not applied; `--force` is still required to overwrite an existing file at that path. |
+| `--include-diff` | Append a bounded diff summary (`git diff --stat` + first 200 lines of `git diff`, redacted, truncation explicitly marked). |
+| `--include-status` | Append a `git status --short` snapshot, redacted. |
+| `--force` | Allow overwriting an existing artifact at the target path. Refuse otherwise. |
+
+## Output Location
+
+**Write path** (single canonical destination):
+
+```text
+plans/handoffs/<slug>-<YYYYMMDD-HHmm>.md
+```
+
+- Slug is derived from the `[task focus]` string when provided, otherwise
+  from the branch name or a short summary of the goal.
+- Create `plans/handoffs/` under an existing `plans/` root when it does not
+  exist yet.
+- If the project has no `plans/` root at all, ask the user for a safe output
+  location before writing.
+- Never write outside the project workspace.
+
+**Discovery** (when reading prior handoffs to inform the current one):
+
+- Scan `plans/handoffs/*.md` first.
+- Also scan legacy `plans/reports/handoff-*.md` so muscle memory from earlier
+  PrimeKit versions keeps working.
+
+## Required Artifact Structure
+
+Every handoff document contains these nine H2 sections in this order — the
+schema is validated by `pk:handover` before dispatch. See
+[references/artifact-schema.md](references/artifact-schema.md) for the exact
+Markdown template.
+
+1. **Mission and current status** — desired outcome, what is done, what
+   remains, urgency/priority when known.
+2. **Scope and guardrails** — repository/workspace, permitted and prohibited
+   changes, user constraints, safety boundaries.
+3. **Current state** — branch, HEAD, worktree, changed/untracked files,
+   relevant paths, whether local modifications are intentional.
+4. **Decisions and rationale** — decisions made, alternatives rejected, links
+   to specs/issues/PRs/ADRs.
+5. **Work performed** — changes made, commands executed, meaningful
+   outputs/errors. Secrets redacted.
+6. **Verification** — checks run with outcome; checks not run and why;
+   known failures or flaky behavior.
+7. **Open risks and blockers** — unresolved questions, dependencies, review
+   requirements, external approvals.
+8. **Exact next actions** — ordered, executable steps; identify the first
+   safe step (marker: `**First safe step**`).
+9. **Source pointers** — paths and URLs needed to validate or continue. Do
+   not fabricate unavailable context.
+
+For any section with no trustworthy information, write literally
+`Not captured in this session` rather than inventing content or leaving the
+heading empty. Never remove a required heading.
+
+## Capture Rules
+
+**Live workspace evidence** — probe read-only, one command at a time, before
+drafting Current state:
+
+- `git rev-parse --is-inside-work-tree` (detect missing repo, fall through
+  to a repo-less handoff below)
+- `git rev-parse --show-toplevel`
+- `git rev-parse --abbrev-ref HEAD`
+- `git rev-parse HEAD`
+- `git status --short` (bounded; if the list exceeds 200 entries, include
+  the first 200 and mark `… truncated at 200 entries …`)
+- `git diff --stat` (only when `--include-diff`)
+- `git diff` (only when `--include-diff`, bounded to first 200 lines,
+  `… truncated at 200 lines …` marker appended after truncation)
+
+Distinguish observed facts (from probes) from agent/user assertions (from
+session context).
+
+**Missing git repository** — capture works without a repo: state
+`Not captured in this session` for Current state git fields, keep the section
+present, and continue.
+
+**Session context** — decisions, user constraints, commands already
+performed. Never dump raw transcripts. Never expose hidden reasoning. Capture
+only task-relevant, actionable facts.
+
+**Empty/new workspace** — do not fabricate repo history, file names, or
+commands. Report only what exists.
+
+## Redaction
+
+Every artifact and every appended `--include-diff` / `--include-status`
+block passes through redaction before write. See
+[references/redaction-patterns.md](references/redaction-patterns.md) for the
+pattern catalog.
+
+Categories always redacted:
+
+- API keys, tokens, JWTs, session cookies
+- Private keys (PEM blocks, SSH private keys)
+- `.env` values (KEY=VALUE where KEY looks credential-like)
+- Passwords, database URLs with credentials
+- Private URLs (internal/staging hosts, signed URLs with query tokens)
+- Customer/personal data captured incidentally
+
+Replacement is a stable marker like `[REDACTED:aws-key]` or `[REDACTED:jwt]`
+(counted, not raw). If the `[task focus]` string itself contains a
+credential-looking value, refuse the invocation and ask the user to rephrase.
+
+## Collision Guard
+
+- If the target path already exists and `--force` is absent, refuse with an
+  explicit message showing the existing file's mtime and suggesting either
+  `--force` or a different `--output`.
+- Overwrite only when `--force` is passed explicitly; `--force` is not
+  implied by `--output`.
+- Never rename or delete an existing artifact silently.
+
+## Return Value
+
+After successful write, print:
+
+1. The absolute artifact path.
+2. A single-line continuation instruction the user can copy into the next
+   session, of the shape:
+   `Read <path> and verify the Current state section against the repo before acting.`
+
+Do not print the artifact body inline.
+
+## Security & Boundaries
+
+- Never launch a coding runtime, subagent, or CLI as a side effect. This
+  skill only reads workspace state and writes one Markdown file.
+- Never make git commits, edits, deletions, or config changes.
+- Never write outside the project workspace or the chosen artifact path.
+- Never include raw transcripts, chain-of-thought, or hidden reasoning.
+- The task focus string is included verbatim in the Mission section; if it
+  contains credentials, refuse the invocation.
+
+## Scenarios
+
+The scenarios below define expected behavior. They double as review fixtures
+for the `--advice` post-implementation gate.
+
+### Scenario 1 — Clean git workspace, bare invocation
+
+**Given** a clean workspace on a feature branch, no `plans/handoffs/` yet.
+**When** `/pk:handoff` runs with no arguments.
+**Expect** `plans/handoffs/` created; artifact written with an
+auto-derived slug + timestamp; all nine sections present; Current state
+records branch/HEAD/"working tree clean"; Verification section states
+"Not captured in this session" for anything unverified; return prints the
+path + continuation instruction.
+
+### Scenario 2 — Dirty workspace with `--include-diff --include-status`
+
+**Given** modified files and untracked files exist.
+**When** `/pk:handoff --include-diff --include-status` runs.
+**Expect** Current state lists changed/untracked files; Work performed cites
+executed commands; a redacted diff summary appears with `… truncated at 200
+lines …` when the raw diff exceeds the limit; a `git status --short`
+snapshot appears, redacted.
+
+### Scenario 3 — Missing git repository
+
+**Given** the current directory is not inside a git repo.
+**When** `/pk:handoff` runs.
+**Expect** the artifact still writes; Current state section is present with
+`Not captured in this session` for the git-derived fields; no `git` command
+runs beyond the initial `rev-parse --is-inside-work-tree` probe.
+
+### Scenario 4 — Secret redaction fixture
+
+**Given** the session captured a command output containing (fake) values
+like `AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` and a
+line `Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJmYWtlIn0.sig-fake`
+(three base64url-shaped segments so the JWT regex actually matches).
+**When** `/pk:handoff` runs.
+**Expect** the artifact contains `[REDACTED:aws-key]` and `[REDACTED:jwt]`
+markers respectively; no raw secret value appears anywhere; the total number
+of redactions applied is mentioned in Work performed.
+
+### Scenario 5 — Explicit `--output` path
+
+**Given** the user passes `--output plans/handoffs/oauth-callback.md`.
+**When** `/pk:handoff --output plans/handoffs/oauth-callback.md` runs.
+**Expect** the artifact is written to that exact path (parent created if
+needed); the auto-derived slug/timestamp is not applied; the return prints
+the same explicit path.
+
+### Scenario 6 — Collision without `--force`
+
+**Given** `plans/handoffs/oauth-callback.md` already exists.
+**When** `/pk:handoff --output plans/handoffs/oauth-callback.md` runs
+without `--force`.
+**Expect** refusal with a message showing existing-file mtime; no write
+occurs; suggestion to pass `--force` or choose a different path. Rerunning
+with `--force` overwrites the file.
+
+## Non-goals
+
+- No runtime dispatch, prompt assembly for another agent, or preflight — use
+  [`pk:handover`](../primekit-handover/SKILL.md).
+- No human-facing project status derived from branches or history — use
+  `pk:watzup`.
+- No plan authoring or ADR minting — use `pk:plan` or the docs skills.

package/skills/handoff/references/artifact-schema.md

@@ -0,0 +1,147 @@
+# `pk:handoff` Artifact Schema
+
+The handoff artifact is a Markdown document with a fixed section order. This
+schema is validated by `pk:handover` before dispatch (by heading name,
+tolerating extra sections between required ones).
+
+## Frontmatter (optional but recommended)
+
+```yaml
+---
+handoff-version: 1
+generated: 2026-08-07T10:49:00Z
+generator: pk:handoff@2.0.0
+focus: "continue the OAuth callback fix"
+workspace: /path/to/repo
+branch: feature/oauth-callback
+head: 26f9ff8
+---
+```
+
+`handoff-version` lets `pk:handover` reject artifacts written by a future
+incompatible schema.
+
+## Required section order
+
+Every artifact contains these nine H2 sections, in this exact order and with
+these exact headings:
+
+```markdown
+# HANDOFF: <short title>
+
+## Mission and current status
+## Scope and guardrails
+## Current state
+## Decisions and rationale
+## Work performed
+## Verification
+## Open risks and blockers
+## Exact next actions
+## Source pointers
+```
+
+Additional H2 sections may appear between required ones. `pk:handover`
+tolerates extra sections; it fails closed only when a required heading is
+missing.
+
+## Section contracts
+
+- **Mission and current status** — outcome + `Done:` list + `Remaining:`
+  list + optional `Urgency:` line. When the focus string was passed, quote
+  it verbatim on the first line.
+- **Scope and guardrails** — `Workspace:`, `In scope:`, `Out of scope:`,
+  `Constraints:` (user-imposed), `Safety boundaries:` (destructive
+  operations disallowed, protected files, etc.).
+- **Current state** — `Branch:`, `HEAD:`, `Working tree:`, `Changed files:`
+  (bounded list), `Untracked files:` (bounded list), `Intentional local
+  modifications:` (`yes|no|not captured`).
+- **Decisions and rationale** — table or bulleted list of `Decision —
+  Rationale — Alternative rejected — Reference` rows.
+- **Work performed** — bulleted commands executed with observed outcome,
+  and code/config changes described at file granularity. `N redactions
+  applied.` line at the end.
+- **Verification** — table of `Check — Command — Outcome — When`. Include a
+  `Not run:` sub-list for skipped checks with a reason each.
+- **Open risks and blockers** — bulleted, each with `Type:` (blocker,
+  risk, question), `Owner:` (unknown when unknown), `Impact:` short.
+- **Exact next actions** — numbered list; the first item is prefixed
+  `**First safe step**` in bold.
+- **Source pointers** — bulleted list of paths and URLs the successor agent
+  needs. Do not fabricate URLs. Repo-relative paths preferred.
+
+For any section with no trustworthy information, write literally
+`Not captured in this session` — do not delete the heading.
+
+## Minimal example (Scenario 1 — clean workspace)
+
+```markdown
+---
+handoff-version: 1
+generated: 2026-08-07T10:49:00Z
+generator: pk:handoff@2.0.0
+focus: "start OAuth callback fix"
+workspace: /home/user/primekit
+branch: feature/oauth-callback
+head: 26f9ff8
+---
+
+# HANDOFF: start OAuth callback fix
+
+## Mission and current status
+Focus: "start OAuth callback fix".
+Done: none — new session.
+Remaining: reproduce the callback 500 in staging, then design the fix.
+Urgency: normal.
+
+## Scope and guardrails
+Workspace: /home/user/primekit
+In scope: `apps/api/auth/oauth-callback.ts` and its unit tests.
+Out of scope: session store schema, mobile deep-link handling.
+Constraints: preserve public callback URL shape.
+Safety boundaries: no destructive migrations; no changes to production secrets.
+
+## Current state
+Branch: feature/oauth-callback
+HEAD: 26f9ff8
+Working tree: clean
+Changed files: none
+Untracked files: none
+Intentional local modifications: no
+
+## Decisions and rationale
+Not captured in this session
+
+## Work performed
+No commands executed yet.
+0 redactions applied.
+
+## Verification
+Not captured in this session
+
+## Open risks and blockers
+- Type: question. Owner: unknown. Impact: whether staging reproduction is
+  possible without a real IdP credential.
+
+## Exact next actions
+1. **First safe step** — read `apps/api/auth/oauth-callback.ts` and its
+   test file.
+2. Reproduce the 500 in staging with the shared test IdP.
+3. Draft the fix in a new branch off `feature/oauth-callback`.
+
+## Source pointers
+- `apps/api/auth/oauth-callback.ts`
+- `docs/auth/oauth-callback-spec.md`
+```
+
+## Validation summary (used by `pk:handover`)
+
+An artifact passes validation when:
+
+- Every required H2 heading is present, spelled exactly as above.
+- The document begins with an H1 that starts with `HANDOFF: `.
+- No line matches the raw-secret patterns in
+  [redaction-patterns.md](redaction-patterns.md).
+- `Exact next actions` includes at least one item, and the first item is
+  bold-prefixed `**First safe step**`.
+
+Any failure is a hard blocker — `pk:handover` refuses to dispatch.

package/skills/handoff/references/redaction-patterns.md

@@ -0,0 +1,80 @@
+# `pk:handoff` Redaction Patterns
+
+Every artifact and every appended `--include-diff` / `--include-status`
+block passes through redaction before write. Redaction is a hard gate:
+never post-hoc, never optional.
+
+## Categories
+
+Match at least these categories. Replace each hit with a stable, non-raw
+marker of the form `[REDACTED:<category>]`. Do not include any part of the
+original value, its length, or its hash.
+
+| Category | Pattern class | Marker |
+|---|---|---|
+| AWS access key ID | `AKIA[0-9A-Z]{16}` | `[REDACTED:aws-key-id]` |
+| AWS secret access key | `[A-Za-z0-9/+=]{40}` in `AWS_SECRET_*=…` context | `[REDACTED:aws-key]` |
+| Generic API key | `(?i)(api[_-]?key|apikey|access[_-]?token|secret)\s*[:=]\s*\S+` | `[REDACTED:api-key]` |
+| Bearer token | `(?i)authorization:\s*bearer\s+\S+` | `[REDACTED:bearer]` |
+| JWT | `eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+` | `[REDACTED:jwt]` |
+| SSH/PEM private key block | `-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z ]*PRIVATE KEY-----` | `[REDACTED:private-key-block]` |
+| `.env` credential-like line | `^[A-Z][A-Z0-9_]*(?:PASSWORD|SECRET|TOKEN|KEY|CREDENTIAL|PASSWD|API|AUTH|SESSION)[A-Z0-9_]*=.+$` | `[REDACTED:env-value]` |
+| Database URL with credentials | `(?i)(postgres|postgresql|mysql|mongodb|redis)://[^:@\s]+:[^@\s]+@\S+` | `[REDACTED:db-url]` |
+| Private URL with signed token | URL with `?token=`, `?sig=`, `?signature=`, `X-Amz-Signature`, `Goog-Signature`, `sv=…&sig=…` (SAS) query params | `[REDACTED:signed-url]` |
+| Internal/staging host | Hosts matching `*.internal`, `*.corp`, `*.staging.<org>`, RFC1918 IPs in URL context, or private CIDR ranges | `[REDACTED:internal-host]` |
+| GitHub PAT / OAuth token | `gh[pousr]_[A-Za-z0-9]{36,}`, `github_pat_[A-Za-z0-9_]{22,}` | `[REDACTED:github-token]` |
+| Slack token | `xox[abpr]-[A-Za-z0-9-]+` | `[REDACTED:slack-token]` |
+| Basic-auth in URL | `https?://[^:/\s]+:[^@\s]+@\S+` | `[REDACTED:basic-auth-url]` |
+| Personal/customer data captured incidentally | full-name/email/phone/address matches from workspace probes that were not the user's own repo-committed data | `[REDACTED:pii]` |
+
+Add categories as they appear in real capture; do not remove categories.
+
+## Rules
+
+1. Redact before write. Do not print raw values to logs, console, or
+   telemetry as a debugging step.
+2. Never store or emit the hash, length, or first/last N characters of a
+   redacted value. `[REDACTED:<category>]` is stable and opaque.
+3. Multiple hits collapse to per-category markers; the artifact's
+   Work performed section reports the **count** (`N redactions applied.`),
+   never the values.
+4. If the `[task focus]` string itself matches any category, refuse the
+   invocation. Do not sanitize it silently; the user has to see the
+   refusal.
+5. Diff and status blocks (`--include-diff`, `--include-status`) run
+   through the same redaction pass. Diffs are the most likely leak vector.
+6. When the same value would be redacted in more than one category, apply
+   the most specific marker (JWT before generic API key, private-key-block
+   before generic secret).
+
+## "Not captured in this session"
+
+When a required section has no trustworthy content — no probe result, no
+in-session decision, no verification evidence — write literally:
+
+```markdown
+Not captured in this session
+```
+
+Do **not** substitute:
+
+- an empty section body,
+- a placeholder like `TBD` or `TODO`,
+- fabricated content ("appears clean", "presumably all tests passed"),
+- inferences from unrelated files.
+
+The successor agent uses `Not captured in this session` as a signal to
+gather that evidence itself before acting, and `pk:handover` treats an
+empty required section as a validation failure.
+
+## Verification recipe (for the `--advice` reviewer)
+
+The Scenario 4 fixture in [`../SKILL.md`](../SKILL.md) supplies the
+canonical redaction test:
+
+- Input contains one `AWS_SECRET_ACCESS_KEY=…` line and one
+  `Authorization: Bearer eyJ…` line (both fake).
+- Expected artifact contains `[REDACTED:aws-key]` and `[REDACTED:jwt]`.
+- Expected artifact contains no substring of either raw value.
+- Expected Work performed section ends with `2 redactions applied.` (or a
+  higher count if the same raw values also appeared elsewhere).