productfoo 0.0.0-stage → 1.0.1

package/skills/spec-swarm-user-research/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: spec-swarm-user-research
+description: "Review an Adaptive Spec Packet, PRD-like spec, or interview-me swarm packet from a user research perspective. Use inside spec-swarm or when the user wants research questions about customer evidence, missing interviews, evidence quality, user segments, research risk, and fastest de-risking path."
+---
+
+# Spec Swarm: User Research
+
+Sharpen the spec from a user research point of view. Use the `grill-me` interaction model: ask one question at a time, give the recommended answer, and resolve the research decision before moving on.
+
+## Usage
+
+Use inside `spec-swarm` or directly on a draft spec, PRD-like spec, or `interview-me` swarm packet:
+
+```text
+Use $spec-swarm-user-research on <path-or-summary>
+```
+
+## productfoo voice for people
+
+When briefing a person, give the recommendation, its concrete reason, what is
+uncertain or disputed, and the useful next action. Follow the required output
+format; this guidance changes phrasing, not fields or workflow responsibilities.
+
+- Use concrete nouns and verbs. Keep a specialist term when it is more precise,
+  and explain it when the reader needs that meaning to decide.
+- Say what you actually inspected and what it supports. Distinguish evidence
+  from inference in ordinary sentences: “The test covers X” and “I expect Y,
+  but have not checked it.” Name the specific unknown and what would settle it.
+- Keep material dissent, source limits and required approvals in the answer,
+  with their original strength. A shorter or warmer answer must not turn an
+  unresolved risk into reassurance. Keep citations close to their claims.
+- Be candid and respectful. Dry humor can name frustrating work; aim it at the
+  situation, not the person. Describe missing evidence without guessing motives
+  or implying deception. Do not invent feelings, experience, checks or praise.
+- Ask the unresolved choice the person needs to make, with your recommendation
+  and tradeoff. Use the active workflow's question budget and consultation rules.
+- End with the concrete next step. Skip repeated process narration and stock
+  offers to continue; carry out work already authorized by the person.
+
+Structured records retain their evidence types, confidence, dissent, owners and
+machine status values. Translate those distinctions for the reader; do not erase
+them. Specialist lenses keep their craft. These rules do not change source
+permissions, expert consultation, sequencing, required questions or output schemas.
+
+## Focus
+
+- Evidence quality: what is observed, reported, inferred, or aspirational?
+- Segment fit: whose problem is this, and whose evidence is missing?
+- Research risk: what assumption would most likely invalidate the spec?
+- Fastest de-risking: what small study, interview, quote search, or usability check would help most?
+- Verbatim signal: what user language should shape the spec or UI?
+
+## Borrow From Existing Skills
+
+- Triage product ideas only against approved evidence in the supplied artifact.
+- Require attributed customer quotes; do not gather or invent them.
+- Check for crisp study framing and interview questions without running a research workflow.
+- `grill-me`: ask one question at a time with the recommended answer.
+
+## Expert Preflight Before User Questions
+
+Before asking the user, ask the other role lenses whether they can answer the candidate question from expertise or artifacts. Record a compact routing note with the candidate question, experts consulted, proposed expert answer, evidence/reason, and whether user judgment is required. When briefing the user, state the relevant expert answer, its reason, any disagreement, and the choice they need to make; keep the full routing note available with the review. Only ask the user when the answer depends on their unique judgment, risk tolerance, taste, source-boundary approval, or a choice between materially valid options.
+
+## Legible Judgment
+
+For every proposed answer, label the judgment type in the structured record as `repo-evidence`, `approved-context`, `role-expertise`, `agent-inference`, or `user-judgment`. Include evidence, confidence, and any dissent or caveat so the user can steer the agent judgment. In the human explanation, express those same distinctions in ordinary sentences with their sources; keep material uncertainty and disagreement visible.
+
+## Question Selection
+
+Ask only 2-3 questions total, one at a time. Prefer questions that expose:
+
+- weak or missing customer evidence
+- untested segment assumptions
+- a research gap that changes MVP scope
+- a claim that needs verbatim support
+- an assumption that can be de-risked quickly
+
+If the answer can be found in the spec, approved research, repo docs, quotes, or source evidence, inspect those sources instead of asking.
+
+## Output
+
+For each question, return:
+
+- `Question`: one user research question.
+- `Recommended answer`: the answer the research lens would push toward, based on the available evidence.
+- `Why it matters`: one sentence.
+- `Likely spec impact`: evidence boundary, persona, acceptance check, research task, or non-goal.
+
+Wait for the user's answer before asking the next question. Do not invent customer evidence.
+
+## Error Handling
+
+- If no spec or packet is provided, ask for one before reviewing.
+- If evidence is missing, ask what evidence should be authoritative instead of inventing it.
+- If the question requires raw private content, ask for a summary or approved evidence boundary instead.

package/skills/spec-swarm-user-research/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Spec Swarm: User Research"
+  short_description: "Ask research questions that sharpen a spec."
+  default_prompt: "Use $spec-swarm-user-research to ask the 2-3 user research questions this spec needs."

package/skills/strategy-check/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: strategy-check
+description: "Use when the the user says \"check strategy alignment\", \"strategy drift\", \"coverage map\", or invokes /strategy-check."
+---
+
+# Skill: Strategy Check
+
+Check whether PRDs align with the active product strategy. Surfaces misalignment, stale strategy references, and coverage gaps across strategic objectives.
+
+Two modes:
+- **Single PRD**: `/strategy-check <feature-slug>` — scores one PRD against the active strategy
+- **Portfolio coverage**: `/strategy-check --coverage` — maps all PRDs against strategic objectives
+
+This skill is **advisory only** — it surfaces signal but does not block PRD status transitions.
+
+## Usage
+
+```
+/strategy-check <feature-slug>
+/strategy-check --coverage
+```
+
+## Examples
+
+- `/strategy-check agentic-workflows` — Check alignment of the agentic workflows PRD
+- `/strategy-check --coverage` — See which strategic objectives have strong/weak PRD coverage
+
+## Instructions
+
+When this skill is invoked:
+
+### Step 1: Load the Active Strategy
+
+1. Glob `docs/strategy/*.md`
+2. Read the YAML frontmatter of each file. Find the file with `active: true`.
+3. **Error handling:**
+   - If **no file** has `active: true`: report "No active strategy found — create or activate a strategy file in `docs/strategy/`" and exit.
+   - If **multiple files** have `active: true`: warn the user listing the conflicting filenames. Use the file with the most recent `date` field. Suggest the PM fix the duplicate.
+   - If the active strategy file is **missing the `objectives` field**: report "Active strategy file `{filename}` is missing the `objectives` field in frontmatter" and exit.
+4. Extract the `objectives` array (each has `id`, `name`, `priority`) and the `deprioritized` array from frontmatter.
+5. Read the full prose body for richer context when judging alignment.
+6. Also read all inactive strategy files (`active: false`) to identify retired themes and objectives.
+
+### Step 2: Route by Mode
+
+- If a `<feature-slug>` was provided → go to **Step 3: Single PRD Alignment Check**
+- If `--coverage` was provided → go to **Step 4: Portfolio Coverage Map**
+
+### Step 3: Single PRD Alignment Check
+
+1. Read `docs/prds/<feature-slug>.md`. If it doesn't exist, report "No PRD found at `docs/prds/<feature-slug>.md` — check the filename or run `ls docs/prds/`" and exit.
+2. Parse the PRD's frontmatter and full content.
+3. **Alignment scoring:** For each objective in the active strategy, use your judgment to assess how strongly this PRD supports it:
+   - **High** — The PRD directly advances this objective; it's a primary focus
+   - **Medium** — The PRD partially supports this objective or enables it indirectly
+   - **Low** — Tangential connection only
+   - **None** — No meaningful connection
+4. **Stale reference detection:** Check if the PRD's content references themes, objectives, or terminology from older (inactive) strategy versions that are no longer in the active strategy. Examples: referencing "Unity" when the active strategy is "Marketing Harness", or citing objectives that have been retired.
+5. **Consistency check:** Read the PRD's freeform strategy alignment field (the text under "How does this project fit into <your-company>'s broader strategy?"). Compare what the PM wrote against the actual active objectives. Flag if the stated alignment is inconsistent with or contradicts your assessment.
+6. **Context note:** If the PRD was last modified before the active strategy's `date`, note this: "This PRD predates the current strategy (active since {date}). Alignment may need re-evaluation."
+7. Output the report (see **Step 5: Output Format — Single PRD**).
+
+### Step 4: Portfolio Coverage Map
+
+1. Glob `docs/prds/*.md`. Exclude `_manifest.md` and `TEMPLATE.md`.
+2. **Process PRDs one at a time** — read each PRD individually, assess alignment to each objective (high/medium/low/none), then move to the next. This avoids context window pressure.
+   - If a PRD has malformed frontmatter or cannot be read, **skip it with a warning** and continue to the next PRD. Do not abort the entire run.
+3. For each objective, count how many PRDs score "high" or "medium" alignment.
+4. **Coverage ratings:**
+   - **Strong**: 3+ PRDs with high/medium alignment
+   - **Good**: 2 PRDs with high/medium alignment
+   - **Light**: 1 PRD with high/medium alignment
+   - **Gap**: 0 PRDs with high/medium alignment
+5. **Unmapped PRDs:** List any PRDs where no objective scores above "low" alignment.
+6. **Stale references:** Flag PRDs that reference themes from inactive strategy versions.
+7. Output the report (see **Step 6: Output Format — Coverage Map**).
+
+### Step 5: Output Format — Single PRD
+
+```
+Strategy Alignment Check: {feature name}
+Active Strategy: {strategy title} ({strategy date})
+══════════════════════════════════════════════════════
+
+┌─────────────────────────────────────────────────┐
+│  QUICK READ                                     │
+├─────────────────────────────────────────────────┤
+│  Primary alignment: {strongest objective match} │
+│  Overall signal: {Strong / Moderate / Weak / None} │
+│  {1-2 key observations}                        │
+└─────────────────────────────────────────────────┘
+
+Alignment by Objective:
+─────────────────────────────────────────────────────
+  OBJ-1: {name}                              {High/Med/Low/None}
+    {Brief rationale}
+
+  OBJ-2: {name}                              {High/Med/Low/None}
+    {Brief rationale}
+
+  [... for each objective]
+─────────────────────────────────────────────────────
+
+Stale Strategy References:
+  {List any references to retired themes/objectives, or "None found"}
+
+Strategy Field Consistency:
+  PM wrote: "{text from PRD strategy field}"
+  Assessment: {Consistent / Inconsistent — with explanation}
+
+Suggestions:
+  - {Actionable suggestion, e.g., "Consider connecting this to OBJ-3 (Land new business agentically) — the migration tooling aspect is a strong fit"}
+  - {Actionable suggestion, e.g., "This references 'Unity' theme which was retired in the Apr 2026 strategy"}
+```
+
+### Step 6: Output Format — Coverage Map
+
+```
+Strategy Coverage Map
+Active Strategy: {strategy title} ({strategy date})
+══════════════════════════════════════════════════════
+
+┌─────────────────────────────────────────────────┐
+│  QUICK READ                                     │
+├─────────────────────────────────────────────────┤
+│  {X} objectives covered, {Y} gaps              │
+│  {Z} PRDs unmapped to any objective             │
+│  {Key insight about portfolio balance}          │
+└─────────────────────────────────────────────────┘
+
+Coverage by Objective:
+─────────────────────────────────────────────────────
+  OBJ-1 (P1): {name}
+    Coverage: {Strong/Good/Light/Gap}  ({N} PRDs)
+    PRDs: {list of PRD names with alignment level}
+
+  OBJ-2 (P2): {name}
+    Coverage: {Strong/Good/Light/Gap}  ({N} PRDs)
+    PRDs: {list of PRD names with alignment level}
+
+  [... for each objective]
+─────────────────────────────────────────────────────
+
+Unmapped PRDs (no objective above "low"):
+  - {prd-name.md} — {brief description of what it covers}
+
+Stale Strategy References:
+  - {prd-name.md} references "{retired theme}" from {old strategy date}
+
+Skipped PRDs:
+  - {prd-name.md} — {reason, e.g., "malformed frontmatter"}
+
+Summary:
+  Total PRDs scanned: {N}
+  Objectives with strong coverage: {N}
+  Objectives with gaps: {N}
+  PRDs with stale strategy refs: {N}
+```
+
+## Notes
+
+- This skill uses LLM judgment to assess alignment — the same approach as `/cpo-lens`. It reads both the strategy frontmatter objectives and the PRD prose to reason about connections. It does not use keyword matching or embedding similarity.
+- PRDs do **not** need to contain explicit objective IDs. The skill infers alignment from prose content. However, if a PRD's strategy field references objective IDs (e.g., "Supports OBJ-3"), the skill will use those as additional signal.
+- When a new strategy version becomes active, existing PRDs are not retroactively flagged as "drifted." They appear as-is in the next alignment check — PRDs written for a previous strategy may appear as "unmapped" in the coverage map, which is expected and useful signal.
+- The coverage map processes PRDs one at a time to avoid context window pressure. Expect 2-3 minutes for a full portfolio scan.
+
+## Error Handling
+
+- If required files, tools, connectors, credentials, or source artifacts are unavailable, state the blocker clearly and continue only with safe local evidence.
+- If the user request requires missing product judgment or source-boundary approval, ask one focused question before proceeding.

package/skills/strategy-check/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Strategy Check"
+  short_description: "Run the Strategy Check workflow."
+  default_prompt: "Use $strategy-check for the relevant workflow."

package/skills/study-digest/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: study-digest
+description: "Use when approved sanitized study evidence needs a traceable synthesis, theme map, hypothesis update, or decision handoff."
+---
+
+# Study Digest
+
+## Usage
+
+Synthesize a study from approved sanitized evidence. Never ingest, quote, or
+commit raw transcripts, recordings, private messages, or participant PII.
+
+1. Anchor the digest to the research brief's decision, questions, and hypotheses.
+2. Accept only approved sanitized discovery evidence, validated research papers,
+   or explicitly approved packet evidence. Source access alone is not approval.
+3. Cluster independent evidence into themes; separate observed behavior, stated
+   preference, interpretation, dissent, and unknowns.
+4. Use a verbatim quote only when the exact approved sanitized evidence contains
+   it. Never invent or reconstruct a quote from a summary or raw-content memory.
+5. Update each hypothesis as supported, refuted, mixed, or open. Present
+   implications and decisions for a person; do not auto-create requirements.
+
+### Source ledger
+
+- **Sources used** — approved evidence reference, study/session scope, and trust label.
+- **Sources omitted** — every optional session or evidence lane not used and why.
+- **Trust status** — approved quote, sanitized observation, validated research, or inference.
+- **Limits** — sample coverage, dissent, and decisions not established by evidence.
+
+Every optional omission appears in the human summary and digest artifact. Return
+in chat by default; write only to an explicitly requested local destination.
+
+## Error Handling
+
+- If the study has no approved sanitized evidence, or a required approval or
+  brief is missing, return `status: blocked`, name what did not run, provide the
+  exact `next action`, and set `exit: nonzero`.
+- If an optional source is unavailable, continue only when the remaining
+  evidence supports an honest synthesis and list the omission.
+- If only raw material is offered, route it through the proof-gated discovery
+  flow; do not open or summarize the raw content here.

package/skills/synthetic-customer/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: synthetic-customer
+description: "Use to draft a synthetic customer persona, generate testable hypotheses, or rehearse/lint an interview guide before talking to real people. Trigger on \"synthetic customer\", \"synthetic user\", \"draft a persona\", \"generate hypotheses\", \"rehearse my interview questions\", \"pressure-test this concept\", or when a discovery study needs a straw-man persona and hypothesis set to react to. This is a rehearsal and hypothesis layer, never an evidence layer: all output is agent-inference and must be validated with real customers before it informs a decision."
+---
+## Usage
+
+Use this skill when its frontmatter description matches the user request. Follow the workflow and constraints below.
+
+# Synthetic Customer
+
+Role-play a grounded customer persona to do the cheap, pre-research work: draft a persona, generate testable hypotheses, and rehearse or lint an interview guide — so the real interview is sharper. This skill produces a straw-man to react to and a hypothesis backlog to validate. It never produces findings.
+
+The product goal is legible judgment: show what is believed, how confident, on what grounding, and what a real customer still has to confirm. A synthetic customer is `agent-inference` — useful, labeled, and never smuggled into a spec or a report as if a real person decided it.
+
+## What this skill is for (and not for)
+
+Legitimate jobs (all pre-research or augmentation):
+
+- **Draft hypotheses.** From a target persona + a "what I want to prove/disprove", enumerate 3-6 candidate hypotheses, each with a belief, a starting confidence, and how a real interview would confirm or kill it.
+- **Rehearse / lint an interview guide.** Run the guide against the persona; flag dead questions, leading questions, ambiguous items, and missing branches before real-participant time is spent.
+- **Pressure-test a concept.** Surface likely objections, confusions, and reasons-not-to — as "what could be wrong", not "what users think".
+- **Draft a straw-man workflow or journey.** A first pass to correct against real evidence, faster than a blank page.
+- **Cover an edge persona for rehearsal** when the real segment is hard to recruit — to sharpen the real session, not replace it.
+
+Never for: reporting synthetic output as user findings; feature prioritization; persona development as source of truth; predicting behavior, conversion, adoption, or willingness-to-pay; market sizing; sampling minority/niche segments as if representative; or any decision-grade number.
+
+## Hard Rules (encode the failure modes)
+
+The research on LLM synthetic respondents is specific about how they mislead. Encode these as behavior:
+
+- **Label everything `agent-inference`.** Every persona, hypothesis, and drafted question carries the label. Disclose synthetic provenance on every artifact.
+- **Never present synthetic output as evidence or a validated finding.** If a whole run is synthetic-only, say so plainly and cap confidence.
+- **Force refusal.** When the persona would not plausibly know something, say "a real [persona] wouldn't reliably know this" instead of inventing a confident answer. Grounded, refusal-capable personas are far less misleading than fluent ones.
+- **Counter sycophancy.** Do not reveal the "right" answer or the product's goal to the persona. Actively ask for objections and reasons-not-to. Instruct the persona to stay in character, not to please the researcher.
+- **Preserve variance; never collapse to the mean.** Synthetic output is systematically too agreeable and too low-variance. When generating multiple personas, spread them across a calibrated distribution and report the spread and dissent, not a consensus.
+- **Ground in real artifacts, not adjectives.** Condition the persona on whatever real material exists (interview transcripts, tickets, segment data, analytics); the more real grounding, the less it is a stereotype machine. State the grounding level honestly.
+- **No magnitudes.** Do not emit numbers that imply measurement (WTP, % who would, conversion). Synthetic magnitudes are often wrong-signed.
+
+## Posture — adapt to the user's interview competence
+
+Detect or ask how grounded the user already is in customer interviews, and adjust:
+
+- **Skilled interviewer:** run fast. A tight guide-lint and a hypothesis list; skip the coaching.
+- **Novice or unsure:** coach. Explain each flagged leading question and each missing past-episode anchor, teach the quality bar (past behavior over speculation, one question at a time, don't lead), and show the fixed version.
+
+## Workflow
+
+1. **Frame.** Restate the target persona and what the user wants to prove or disprove. Note the grounding available (real artifacts vs none) and set confidence accordingly.
+2. **Persona.** Draft a persona card grounded in the available material: role, context, goals, constraints, current tools/workarounds, and what this persona plausibly would and would not know. Label `agent-inference`.
+3. **Hypotheses.** Produce 3-6 hypotheses, each as: `belief` (one sentence), `starting confidence` (low/medium/high, honest — synthetic-only defaults low), and `how a real interview confirms or kills it`.
+4. **Questions.** Draft a hypothesis-testing question set that obeys the quality bar: anchor on a specific past episode ("tell me about the last time…"), behavior over opinion, open over closed, one idea per question, never leading. Map each question to the hypothesis it tests.
+5. **Lint.** Run the leading-question / quality-bar lint over the set: flag hypotheticals ("would you…"), opinion-as-fact, double-barreled items, and any question that telegraphs the hypothesis. For a novice, explain and fix; for a skilled user, just flag.
+6. **Handoff.** Present the persona + labeled hypotheses + question set for the user to approve or edit. Nothing here is evidence — it is input for a real interview. Route an approved completed call through `customer-discovery`; its proof-gated in-memory flow commits only sanitized evidence, never the raw transcript.
+
+## Output
+
+- `Persona`: card, grounding level, `agent-inference` label.
+- `Hypotheses`: each with belief, starting confidence, and how a real interview would confirm/kill it.
+- `Questions`: hypothesis-testing set, each mapped to a hypothesis, past-episode-anchored and non-leading.
+- `Lint findings`: leading/hypothetical/opinion-as-fact/telegraphing flags, with fixes for a novice.
+- `Caveat line`: the explicit reminder that all of this is synthetic and must be validated with real customers before it informs a decision.
+
+## Error Handling
+
+- If no target persona or research goal is provided, ask one focused question before drafting; do not invent the study.
+- If no real grounding material is available, say so, mark the run synthetic-only, cap confidence at `low`, and recommend the fastest way to get one real interview.
+- If asked to produce findings, metrics, prioritization, or willingness-to-pay from synthetic output, refuse and explain that synthetic customers are a rehearsal/hypothesis layer, not evidence; offer the hypothesis + guide instead.
+- If required source artifacts are unavailable, state the blocker and continue only with safe local evidence, labeled.

package/skills/update-cli-spec/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: update-cli-spec
+description: "Use after adding, removing, renaming, or changing foo CLI commands, flags, runtime skill installation behavior, packet validation behavior, or command output; use when the user says update the CLI spec, sync the CLI docs, record the CLI change in the Adaptive Spec Packet, or make CLI behavior durable in spec/task/event artifacts."
+---
+
+# Update CLI Spec
+
+Keep executable CLI behavior, user-facing command docs, and the Adaptive Spec Packet contract aligned in one change.
+
+## Usage
+
+Use this workflow whenever a CLI change affects how a user or agent should invoke `foo`, understand its output, install runtime skills, validate packets, or reconcile work.
+
+1. Identify the behavior change.
+   - Read the changed CLI files, tests, and command output.
+   - Determine whether the change is a new command, flag, validation rule, output contract, install behavior, or error path.
+   - Do not update spec artifacts from intent alone; verify the actual behavior or add tests that define it.
+
+2. Update executable coverage first when behavior changed.
+   - Add or update focused CLI tests for the new contract.
+   - Cover safety behavior for install, delete, overwrite, path, or runtime-environment changes.
+   - Prefer temp directories and explicit roots in tests so validation does not mutate the user's real runtime environment.
+
+3. Update tracked command documentation.
+   - Update `README.md` for clone/setup or top-level command workflows.
+   - Update other tracked docs only when they are committed artifacts.
+   - Treat `docs/` as local scratch unless the repo has explicitly changed that rule; do not rely on ignored docs as the only durable documentation.
+
+4. Update `specs/adaptive-spec-packet-v0/spec.md` when the CLI contract changed.
+   - Add or revise a requirement for durable behavior.
+   - Add or revise a decision when the change chooses a product or workflow direction.
+   - Add risk and validation bullets when the behavior has safety, portability, or trust implications.
+   - Add evidence links to the implementation, tests, and tracked docs.
+
+5. Update `specs/adaptive-spec-packet-v0/tasks.yaml`.
+   - Add a new task for new accepted CLI behavior.
+   - Mark it `done` only when tests and docs are complete.
+   - Include touched files, done checks, proof paths, completion metadata, and the corresponding event ID.
+   - Use UTC timestamps in task completion metadata.
+
+6. Append to `specs/adaptive-spec-packet-v0/events.jsonl`.
+   - Append exactly one JSON object per event; do not rewrite existing ledger lines.
+   - Use the next `evt_asp_###` ID.
+   - Include actor identity, skills or prompt modules when known, adapter/runtime when known, and a concise reason.
+   - Keep raw private notes, transcripts, prompts, and tool payloads out of the event.
+
+7. Validate before reporting completion.
+   - Run the CLI tests that cover the changed behavior.
+   - Run `bin/foo asp validate specs/adaptive-spec-packet-v0`.
+   - Run the root README skill checks if skill files or registry entries changed.
+   - Run the root README spec placement and duplicate `Spec ID` check when spec files changed.
+   - Manually smoke-test important commands when the change concerns install paths, symlinks, destructive operations, or outside-repo invocation.
+
+## Output
+
+Report:
+
+- The behavior that changed.
+- The spec/docs/task/event artifacts updated.
+- The exact validation commands and results.
+- Any user-facing caveats, especially ignored docs, skipped destructive checks, or runtime roots not touched.
+
+## Error Handling
+
+- If behavior cannot be verified, stop and say what evidence is missing; do not update packet truth from guesses.
+- If a command touches a user runtime, use a temp root or dry-run equivalent first. Ask for explicit approval before mutating a real runtime root when the user did not request it.
+- If `docs/` is ignored, mirror any durable user-facing documentation in a tracked artifact such as `README.md` or the packet spec.
+- If event IDs or task IDs conflict, inspect existing packet files and choose the next unused ID rather than editing historical IDs.
+- If validation fails, fix the source behavior or the spec artifact and rerun validation before claiming the CLI spec is updated.

package/skills/update-cli-spec/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Update CLI Spec"
+  short_description: "Keep CLI behavior and spec artifacts aligned"
+  default_prompt: "Use $update-cli-spec after changing CLI commands or runtime workflow behavior."

package/skills/voc-researcher/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: voc-researcher
+description: "Use when approved customer evidence needs voice-of-customer synthesis, pain analysis, workaround mapping, or evidence-backed product triage."
+---
+
+# Voice Of Customer Researcher
+
+## Usage
+
+Produce a traceable VoC brief from approved evidence, not a connector inventory
+or a model's idea of what customers probably think.
+
+1. Confirm the product question, segment, time window, and decision the evidence
+   may inform.
+2. Inventory source classes before reading: approved sanitized discovery
+   evidence, validated research, packet evidence, product analytics, and support
+   signals. Connector access is not source approval.
+3. Record each class as `used`, `omitted`, `blocked`, or `not applicable`.
+   Approved derived evidence is allowed; raw transcripts, private messages, PII,
+   and unapproved connector content are not.
+4. Synthesize pains, jobs, triggers, workarounds, frequency evidence, segment
+   differences, dissent, and gaps. Do not manufacture counts or quotes.
+5. Recommend only when at least one approved evidence lane supports the claim and
+   the coverage limits are visible. Zero approved evidence means no recommendation.
+
+### Source ledger
+
+- **Sources used** — source class, scope, approval, date, and stable reference.
+- **Sources omitted** — every optional source class not used and why.
+- **Trust status** — approved sanitized evidence, validated research, metric, or inference.
+- **Limits** — coverage, representativeness, missing lanes, and human judgment.
+
+Every optional omission appears in both the human summary and the VoC artifact.
+Write locally only when the user supplies a destination; never update a tracker
+or send the brief.
+
+## Error Handling
+
+- With zero approved evidence, return `status: blocked`, `did_not_run: VoC
+  recommendation`, `missing: approved evidence`, the exact `next action`, and
+  `exit: nonzero`. Do not recommend “park” or any other product decision.
+- If a required source approval, receipt, or access grant is missing, name it and
+  stop; never silently fall back to another lane.
+- If only optional sources are unavailable, proceed only with adequate remaining
+  evidence and list all omissions in the summary and artifact.

package/skills/voc-researcher/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "VoC Researcher"
+  short_description: "Synthesize approved customer evidence without false recommendations."
+  default_prompt: "Use $voc-researcher for the relevant workflow."

package/skills-lock.json

@@ -0,0 +1,35 @@
+{
+  "version": 1,
+  "skills": {
+    "design-taste-frontend": {
+      "source": "leonxlnx/taste-skill",
+      "sourceType": "github",
+      "skillPath": "skills/taste-skill/SKILL.md",
+      "computedHash": "6d838b246d0e35d0b53f4f23f98ba7a1dd561937e64f7d0c7553b0928e376c3e"
+    },
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "skillPath": "skills/find-skills/SKILL.md",
+      "computedHash": "9e1c8b3103f92fa8092568a44fe64858de7c5c9dc65ce4bea8f168080e889cfd"
+    },
+    "frontend-design": {
+      "source": "anthropics/skills",
+      "sourceType": "github",
+      "skillPath": "skills/frontend-design/SKILL.md",
+      "computedHash": "4eabc66183767153e404b39d1b839b1c37f2d82d86f0a0d7e880a579d8d62336"
+    },
+    "impeccable": {
+      "source": "pbakaus/impeccable",
+      "sourceType": "github",
+      "skillPath": ".agents/skills/impeccable/SKILL.md",
+      "computedHash": "f2a6bed082dd9bf7bf8b9244e6ac6eb80fc24ed8446425effe213655662dcab9"
+    },
+    "wireframe-spec": {
+      "source": "owl-listener/designer-skills",
+      "sourceType": "github",
+      "skillPath": "prototyping-testing/skills/wireframe-spec/SKILL.md",
+      "computedHash": "790a9e40f32453f4e2de4aac5ad8883a0aecb70b765b2201aa9370a37850bd37"
+    }
+  }
+}