import from local vendored copy (2026-05-06)

.github/workflows/ci.yml

@@ -0,0 +1,5 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  validate:
+    uses: Molecule-AI/molecule-ci/.github/workflows/validate-plugin.yml@main

.gitignore

@@ -0,0 +1,21 @@
+# Credentials — never commit. Use .env.example as the template.
+.env
+.env.local
+.env.*.local
+.env.*
+!.env.example
+!.env.sample
+
+# Private keys + certs
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+
+# Secret directories
+.secrets/
+
+# Workspace auth tokens
+.auth-token
+.auth_token

.molecule-ci/scripts/requirements.txt

@@ -0,0 +1 @@
+pyyaml>=6.0

.molecule-ci/scripts/validate-plugin.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Validate a Molecule AI plugin repo."""
+import os, sys, yaml
+
+errors = []
+
+if not os.path.isfile("plugin.yaml"):
+    print("::error::plugin.yaml not found at repo root")
+    sys.exit(1)
+
+with open("plugin.yaml") as f:
+    plugin = yaml.safe_load(f)
+
+for field in ["name", "version", "description"]:
+    if not plugin.get(field):
+        errors.append(f"Missing required field: {field}")
+
+v = str(plugin.get("version", ""))
+if v and not all(c in "0123456789." for c in v):
+    errors.append(f"Invalid version format: {v}")
+
+runtimes = plugin.get("runtimes")
+if runtimes is not None and not isinstance(runtimes, list):
+    errors.append(f"runtimes must be a list, got {type(runtimes).__name__}")
+
+content_paths = ["SKILL.md", "hooks", "skills", "rules"]
+found = [p for p in content_paths if os.path.exists(p)]
+if not found:
+    errors.append("Plugin must contain at least one of: SKILL.md, hooks/, skills/, rules/")
+
+if os.path.isfile("SKILL.md"):
+    with open("SKILL.md") as f:
+        first_line = f.readline().strip()
+    if first_line and not first_line.startswith("#"):
+        print("::warning::SKILL.md should start with a markdown heading (e.g., # Plugin Name)")
+
+if errors:
+    for e in errors:
+        print(f"::error::{e}")
+    sys.exit(1)
+
+print(f"✓ plugin.yaml valid: {plugin['name']} v{plugin['version']}")
+if found:
+    print(f"  Content: {', '.join(found)}")
+if runtimes:
+    print(f"  Runtimes: {', '.join(runtimes)}")

CLAUDE.md

@@ -0,0 +1,93 @@
+# molecule-workflow-retro — Weekly Retrospective Generator
+
+`molecule-workflow-retro` provides the `/retro` slash command — a weekly
+retrospective generator. It reads from `molecule-cron-learnings` JSONL files
+and synthesises a structured retro: what went well, what didn't, and action items.
+
+**Version:** 1.0.0
+**Runtime:** `claude_code`
+
+---
+
+## Repository Layout
+
+```
+molecule-workflow-retro/
+├── plugin.yaml              — Plugin manifest
+├── skills/
+│   └── cron-retro/
+│       └── SKILL.md         — Retro synthesis skill
+└── commands/
+    └── retro.md            — /retro slash command
+```
+
+---
+
+## What It Does
+
+### The /retro Command
+
+Run `/retro` in any Claude Code session to generate a weekly retrospective.
+It reads learnings from `~/.claude/projects/<project>/cron-learnings.jsonl`
+and produces:
+
+- **What went well**: Patterns across positive learnings
+- **What didn't**: Patterns across negative learnings
+- **Action items**: Concrete next steps for the next week
+
+### Prerequisites
+
+Install `molecule-cron-learnings` first — the retro reads learnings that must
+be written by the cron-learnings plugin each tick.
+
+---
+
+## Development
+
+### Prerequisites
+
+- Python 3.11+
+- `gh` CLI authenticated
+- Write access to `Molecule-AI/molecule-ai-plugin-molecule-workflow-retro`
+
+### Setup
+
+```bash
+git clone https://github.com/Molecule-AI/molecule-ai-plugin-molecule-workflow-retro.git
+cd molecule-ai-plugin-molecule-workflow-retro
+
+python3 -c "import yaml; yaml.safe_load(open('plugin.yaml'))"
+```
+
+### Pre-Commit Checklist
+
+```bash
+python3 -c "import yaml; yaml.safe_load(open('plugin.yaml'))"
+
+python3 -c "
+import re, sys
+with open('plugin.yaml') as f:
+    content = f.read()
+patterns = [r'sk.ant', r'ghp.', r'AKIA[A-Z0-9]']
+if any(re.search(p, content) for p in patterns):
+    print('FAIL: possible credentials found')
+    sys.exit(1)
+print('No credentials: OK')
+"
+```
+
+---
+
+## Release Process
+
+1. Review changes: `git log origin/main..HEAD --oneline`
+2. Bump `version` in `plugin.yaml` (semver)
+3. Commit: `chore: bump version to X.Y.Z`
+4. Tag and push: `git tag vX.Y.Z && git push origin main --tags`
+5. Create GitHub Release with changelog
+
+---
+
+## Known Issues
+
+See `known-issues.md` at the repo root.

README.md

@@ -0,0 +1,19 @@
+# molecule-workflow-retro
+
+Molecule AI plugin. Install via the Molecule AI platform plugin system.
+
+## Usage
+
+### In org template (org.yaml)
+```yaml
+plugins:
+  - molecule-workflow-retro
+```
+
+### From URL (community install)
+```
+github://Molecule-AI/molecule-ai-plugin-molecule-workflow-retro
+```
+
+## License
+Business Source License 1.1 — © Molecule AI.

adapters/claude_code.py

@@ -0,0 +1,2 @@
+"""Claude Code adaptor — uses the generic rule+skill+hooks installer."""
+from plugins_registry.builtins import AgentskillsAdaptor as Adaptor  # noqa: F401

commands/retro.md

@@ -0,0 +1,41 @@
+---
+name: retro
+description: Generate a weekly retrospective digest — PRs merged, gate failures, code-review severity trend, time-to-merge, issues picked up. Posts as a GitHub issue.
+---
+
+# /retro
+
+Weekly retrospective on cron + agent activity. Default cadence: Sundays
+23:00 local. Manual invocation on demand.
+
+## Steps
+
+1. Compute over the prior 7 days:
+   - Merged PR count (total + by category)
+   - Issues closed (with PR-link for each)
+   - Time-to-merge: median, p90, max — exclude docs PRs
+   - Gate failure breakdown (which gates, how often)
+   - Code-review findings: total 🔴/🟡/🔵, trend vs prior week
+   - Mechanical fixes pushed (count)
+   - Skips by reason: design-judgment / CI-down / scope-too-open / noteworthy-CEO-needed
+   - Code volume: net LOC added/removed
+   - Test count delta (Go + Python + Vitest + Jest)
+   - New runtime / library / tool added or removed
+
+2. Format per the `cron-retro` skill template.
+
+3. Post as a new GitHub issue titled
+   `Cron retro: <start> → <end> (week N)` with labels `meta`, `retro`.
+
+4. If trends are bad (gate failure rate up, 🔴 findings appearing,
+   time-to-merge >50% increase), flag prominently in the body and
+   @-mention the workspace owner.
+
+5. Skip new-issue creation if the prior 7 days had < 3 merged PRs;
+   post a one-liner in the latest weekly retro issue's comments instead.
+
+## Standing rules
+- careful-mode applies — don't mass-close stale issues, don't delete
+  prior retros
+- The retro is observational, not actionable — propose 2-3 follow-ups
+  for the user but never auto-create them

known-issues.md

@@ -0,0 +1,54 @@
+# Known Issues — molecule-workflow-retro
+
+---
+
+## Active Issues
+
+*(None currently open. This section is updated when issues are filed.)*
+
+---
+
+## Recently Resolved
+
+*(No recently resolved issues.)*
+
+---
+
+## How to Update This File
+
+When a new issue is identified:
+1. Add it under **Active Issues** using the template below
+2. Include: symptom, cause (if known), workaround
+3. When fixed, move to **Recently Resolved** and note the fix version
+
+### Issue Template
+
+```markdown
+## [TICKET-NUMBER] <Short Title>
+
+**Severity:** P0 / P1 / P2 / P3
+**Status:** Workaround / Fix in progress / Fix available
+**Affected versions:** All / vX.Y.Z+
+
+**Symptoms:**
+**Cause:**
+**Workaround:**
+**Fix (if available):**
+```
+
+---
+
+## Severity Definitions
+
+| Level | Description |
+|---|---|
+| P0 | Retro produces no output despite learnings existing |
+| P1 | Retro reads wrong workspace's learnings |
+| P2 | Action items missing or miscategorised |
+| P3 | Cosmetic or documentation issue |
+
+---
+
+## Reporting
+
+Use the Molecule-AI/internal issue tracker. Tag with `plugin-molecule-workflow-retro`.

plugin.yaml

@@ -0,0 +1,14 @@
+name: molecule-workflow-retro
+version: 1.0.0
+description: Provides /retro slash command — weekly retrospective generator. Recommends installing molecule-skill-cron-learnings first.
+author: Molecule AI
+tags: [molecule, guardrails]
+
+runtimes:
+  - claude_code
+
+skills:
+  - cron-retro
+
+commands:
+  - retro

runbooks/local-dev-setup.md

@@ -0,0 +1,69 @@
+# Local Development Setup
+
+This runbook covers setting up a local development environment for
+`molecule-workflow-retro`.
+
+---
+
+## Prerequisites
+
+- Python 3.11+
+- `gh` CLI authenticated
+- Write access to `Molecule-AI/molecule-ai-plugin-molecule-workflow-retro`
+
+---
+
+## Clone & Bootstrap
+
+```bash
+git clone https://github.com/Molecule-AI/molecule-ai-plugin-molecule-workflow-retro.git
+cd molecule-ai-plugin-molecule-workflow-retro
+```
+
+---
+
+## Validating Plugin Structure
+
+```bash
+python3 -c "import yaml; yaml.safe_load(open('plugin.yaml'))"
+echo "plugin.yaml OK"
+```
+
+---
+
+## Testing the Retro Skill
+
+The harness wrapper is provided by the Molecule AI platform at runtime.
+To test:
+
+1. Install `molecule-cron-learnings` first (prerequisite)
+2. Install `molecule-workflow-retro` in a test workspace
+3. Add mock learnings to `~/.claude/projects/<project>/cron-learnings.jsonl`:
+   ```jsonl
+   {"tick": "2026-04-21T00:00Z", "role": "sdk-lead", "learnings": ["CI timeout was 2min — too short for integration tests"]}
+   {"tick": "2026-04-21T01:00Z", "role": "sdk-lead", "learnings": ["PR template now has Testing section"]}
+   ```
+4. Run `/retro` and verify output has three sections (went well, didn't, actions)
+
+---
+
+## Troubleshooting
+
+### Retro has no learnings to synthesise
+
+- Verify `molecule-cron-learnings` is installed and writing to the JSONL file
+- Check the path `~/.claude/projects/<project>/cron-learnings.jsonl` exists
+- If the project directory is wrong, check the workspace config
+
+### Empty action items
+
+- The retro needs at least one "what didn't" learning to generate action items
+- Add more learnings or check the learnings parser
+
+---
+
+## Related
+
+- `molecule-cron-learnings` — prerequisite; writes learnings each tick
+- `skills/cron-retro/SKILL.md` — retro synthesis skill
+- `commands/retro.md` — /retro slash command

skills/cron-retro/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: cron-retro
+description: Weekly retrospective digest of cron activity — PRs merged, gates failed, issues picked, code-review findings by severity, time-to-merge, regression trend. Posts to a dedicated GitHub issue. Inspired by gstack's /retro.
+---
+
+# cron-retro
+
+The cron runs hourly and ships a lot. Without a periodic summary, drift happens silently — Gate 4 starts failing more often, code-review noise climbs, time-to-merge balloons, and nobody notices for weeks.
+
+## When to run
+
+- Every Sunday at 23:00 local (`0 23 * * 0` cron expression)
+- On-demand by the CEO
+
+## What to compute (over the prior 7 days)
+
+From `gh pr list --state merged --search "merged:>=YYYY-MM-DD"` and our local `cron-learnings.jsonl`:
+
+1. **Merged PR count** — total + by category (auth/security, refactor, feat, fix, docs, infra)
+2. **Issues closed** — count, with PR-link for each
+3. **Time-to-merge distribution** — median, p90, max. Excluding docs PRs (they merge instantly).
+4. **Gate failure breakdown** — which gates failed how often. Patterns?
+5. **Code-review findings** — total 🔴 / 🟡 / 🔵 across all PRs. Trend vs prior week.
+6. **Mechanical fixes pushed** — how often did the cron fix a gate failure on-branch?
+7. **Skips by reason** — categorize: design-judgment, CI-down, scope-too-open, noteworthy-CEO-needed
+8. **Code volume** — net LOC added/removed (Garry Tan publishes these in his retros — keep us honest)
+9. **Test count delta** — Go + Python + Vitest + Jest from start to end of week
+10. **New runtime / library / tool added or removed** — anything strategic
+
+## Format
+
+Post a new GitHub issue titled `Cron retro: 2026-04-14 → 2026-04-21 (week N)` with body:
+
+```markdown
+# Week summary
+- Merged: X PRs (Y closed issues)
+- Median TTM: 3h12m (excluding docs)
+- Code-review findings: 0 🔴 / 4 🟡 / 18 🔵 (vs last week: 0 / 6 / 24)
+- Mechanical fixes pushed: 5
+- Skips: 2 design-judgment, 1 CI-down
+
+# Trend signals
+- ↑ Frontend test coverage (+12 vitest, +1 file)
+- ↓ Time-to-merge for auth PRs (down from 8h median to 3h — likely
+   because Gate-4 doc-sync subagent now catches missing .env entries)
+- ⚠ Gate 7 (Playwright) failed 3 times this week vs 0 last week —
+   probably the canvas dev-server stale-chunk issue. Action item.
+
+# Code volume
+- 12,847 lines added, 8,213 removed across 23 commits
+
+# Notes
+- Closed #6, #13, #17, #23 — 4 issues from the launch backlog
+- 2 issues remain in the SaaS-launch Tier 1 list (multi-tenancy, Fly Machines)
+- New skills added this week: cross-vendor-review, careful-mode, cron-learnings, cron-retro
+
+# Action items for next week
+- [ ] Investigate Gate 7 flakes (likely fix: persistent canvas dev daemon)
+- [ ] Pick up issue #19 (workspace restart context)
+- [ ] PR #58 needs CEO review (configurable tier limits — behavior change)
+```
+
+## Why this exists
+
+What gets measured improves. gstack publishes weekly retros and credits them with knowing where to invest. We have no analog. This is the smallest viable analog: one issue per week, generated automatically, costs nothing to ignore, valuable when the metrics start drifting.
+
+## Implementation note
+
+This skill should be invoked from a separate cron job (not the hourly triage cron). Suggested cron expression: `7 23 * * 0` — Sunday 23:07 local.