Skip to content

04JUL26.md

Latest commit

 

History

History
60 lines (42 loc) · 5.86 KB

04JUL26.md

File metadata and controls

60 lines (42 loc) · 5.86 KB
Raw

HANDOFF: State of the Repo After v0.81 (July 4, 2026)

You are working in the Product-Manager-Skills repository. This document is the session handoff from the v0.81 release. Read it alongside CLAUDE.md (governance + distillation protocol) before touching files.

Where Things Stand

v0.81 shipped July 4, 2026 — committed, pushed, tagged, release assets published, CI green. The library is at 55 skills (23 component, 25 interactive, 7 workflow) plus 6 commands.

What v0.81 was (full story: docs/announcements/2026-07-04-v0-81-input-sections.md):

  1. Required ## Input section in every skill, between Purpose and Key Concepts. Convention: **Works best with:** (subject) → **Also useful:** (optional context) → the inline-input rule → **Arriving empty-handed? That works too.** (guided-flow fallback) → example invocation.
  2. The inline-input rule, verbatim in every skill: anything supplied with the invocation — text after the skill name, a pasted context dump, or an appended ARGUMENTS: line — counts as answers already given; use it and skip what it covers, don't re-ask.
  3. The $ARGUMENTS stance: this library deliberately does not use runtime template syntax. Rationale (portability, pedagogy, unnecessary) lives in CONTRIBUTING.md → "Why We Don't Use $ARGUMENTS". argument-hint frontmatter is the one sanctioned exception (Claude Code autocomplete; 53 skills have it).
  4. Recovered agent-orchestration-advisor — Phase 6 skill #34 existed only on orphaned commit a41415c for months while docs claimed it shipped. Restored and upgraded to current standards.
  5. Synced .claude-plugin/marketplace.json (47 → 55 entries) and bumped plugin manifests to 0.81.
  6. Streamlit: every skill detail page renders the skill's own Input section in a "What to bring (all optional)" expander.
  7. Post-release: added scripts/check-library-drift.py (commit 93921da) so failures #4 and #5 can never be silent again.

Conventions the Next Session Must Honor

These are load-bearing decisions, not preferences:

  • Skill anatomy is now 7 sections, in order: Purpose, Input, Key Concepts, Application, Examples, Common Pitfalls, References. Validator-enforced.
  • Input sections are invitations, not gates. Never label anything "Required." Users must finish the section knowing they can arrive with nothing and be walked through it. Dean flagged this explicitly — the first draft used "Provide:" and he pushed back.
  • No $ARGUMENTS in skill bodies. Hard validation failure (backticked mentions naming the anti-pattern are allowed). PRs "modernizing" skills with template syntax get converted, not merged.
  • Pedagogic-first still governs everything (v0.75). Stripping learning scaffolding is a defect. The Input convention is an extension of this, not a separate rule.

Enforcement Map (What Catches What)

Check Where Catches
Required sections incl. Input, $ARGUMENTS ban scripts/check-skill-metadata.py structural drift, template syntax
Input has example invocation + empty-handed language scripts/test-a-skill.sh --smoke (warns) hollow Input sections
Marketplace entries ↔ skills/*/ dirs; README/CLAUDE.md skill links resolve scripts/check-library-drift.py docs claiming more than the repo contains
All of the above on every PR and tag scripts/validate-skills.sh via .github/workflows/build-release.yml regressions reaching main

Run locally: ./scripts/test-library.sh --smoke. Three pre-existing smoke warnings (interactive-flow option counts) are known and unrelated.

Open Work Queue (Rough Priority)

  1. Theme metadata backfill — only 19 of 55 skills have theme/best_for/scenarios/estimated_time frontmatter. The other 36 land in the Streamlit "All other skills" expander. Mechanical pass; follow the tagged skills' format.
  2. Phase 6 remainder (AI PM Orchestrator): ai-product-evals (Component), ai-observability-framework (Component), ai-maintenance-planning (Component), ai-product-orchestrator (Workflow). Source material listed in CLAUDE.md.
  3. The v0.80 AI Product Builder Track brief was never executed. 15MAY26.md and research/v080-ai-product-builder-execution-brief.md planned v0.80 as an AI Product Builder Track; the actual v0.80 shipped the stakeholder suite instead. The brief's content (hard exclusions, source material, skill plans) is still valid raw material for a future release — decide with Dean whether to execute, renumber, or retire it.
  4. "Invoking skills with arguments" subsection in docs/Using PM Skills with Claude.md — the Input sections teach the pattern per-skill; the guide could teach it once, generally, with the /skill-name your context example. Small, deferred from v0.81.
  5. Streamlit follow-ons: streaming responses, related-skills panel, export conversation, search.
  6. Potential Phase 8: Pricing & Monetization Suite (7 skills, listed in CLAUDE.md).

Gotchas Learned This Session

  • Marketplace.json is hand-maintained. New skills need an entry added manually (name, source, description without the "Use when..." clause, category from the existing seven, tags). The drift check will remind you.
  • Orphaned commits happen here. Before trusting "docs say it shipped," verify the path exists on main. git log --all finds work that never merged.
  • Bulk skill edits: use a Python script via Bash, not the Edit tool — files drift between reads. Quote YAML description values containing colons.
  • README has three places that state the skill count (badge, ASCII banner, tagline) plus .claude-plugin/marketplace.json metadata.description. All must move together; the banner box is width-sensitive.
  • Release mechanics: tag v* → .github/workflows/build-release.yml validates, builds all ZIP packs, and publishes release assets automatically. Nothing manual after the tag push.