feat(plugin-creator): context/plugin creator (working name) v0.1.0

plugin-creator/.tessl-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "tessl/plugin-creator",
+  "version": "0.1.0",
+  "description": "Create a Tessl plugin: wrap your existing skills into a versioned, shareable bundle, decide what else it needs (rules, commands, MCP servers), validate, and publish.",
+  "private": false,
+  "skills": "./skills/"
+}

plugin-creator/.tesslignore

@@ -0,0 +1,3 @@
+DRAFT-NOTES.md
+TRY-THIS.md
+tessl.json

plugin-creator/DRAFT-NOTES.md

@@ -0,0 +1,46 @@
+# Draft notes (for Marc's review)
+
+Draft of the context/plugin creator plugin. Uncommitted, unpublished, untracked in git. Working name only.
+
+## Model (updated 2026-07-01, per Marc): composition plan
+
+**Problem-first, and eval is downstream.** Users are not asking to package anything. They usually already tried to solve their problem and now have a skill that is a mess, too long, or not getting enough out of Tessl. This plugin understands the problem, gathers what they have, plans the right shape, builds it, and *then* points them to eval, which stays in skill-optimizer as a separate sibling flow. We never run evals mid-creation. Sprawl/rot is skill-inventory's concern, not this plugin's.
+
+Note: in Tessl a "skill" is already a minimal single-skill plugin (`tessl skill new` / `import` create the `plugin.json`). So packaging-for-eval is cheap; this plugin's job ends at *composition created*.
+
+## The arc (and the 6 skills)
+
+understand → gather → plan → build → (then, separately) eval
+
+| Skill | Phase / role |
+|---|---|
+| `create-context` | Orchestrator. Runs the arc; hands off to skill-optimizer for eval at the end. |
+| `gather-context` | Understand the problem; take stock of artifacts (skill, plugin, code, prompt, or "go find it"); fill gaps by asking, hunting, or inferring. |
+| `plan-composition` | Decide the shape: single skill vs plugin (+ rules / MCP). Produce a short composition plan and confirm it. |
+| `build-composition` | Create it: author/restructure/wrap skills, add rules/MCP per plan. Scaffolds with `tessl skill new` / `plugin new`. |
+| `decompose-into-skills` | Split a big skill into focused, independently-verifiable skills. Invoked during build. |
+| `publish-plugin` | Optional. Kept in for now; distribute workflow may absorb it later. |
+
+`author-skill-from-intent`, `find-context-opportunities`, `wrap-skills-into-plugin`, and `add-mcp-server-to-plugin` from the previous draft were **absorbed**: gathering (incl. the PR/log hunt) folded into `gather-context`; authoring/wrapping/MCP folded into `build-composition`.
+
+## What changed this round
+
+- Reframed to the composition-plan arc; eval is a downstream sibling, never woven in.
+- Dropped the "skill → evals → plugin" ladder (it implied evaling mid-flow).
+- Unified the entry points into `gather-context` (Marc: author-from-intent and find-opportunities are aspects of the same gathering).
+- Folded MCP into `build-composition` (no standalone MCP skill).
+- Kept publishing in (Marc: distribute is undefined; pull it out later if needed).
+- Removed sprawl/rot as a design anchor.
+
+## QA status
+
+- `tessl plugin lint` — PASS. Clean install — PASS, all 6 skills materialise.
+- Quality review (`tessl review run`) — still needs `tessl login`.
+
+## Parked actions / decisions
+
+1. **Name** (not plugin-first; Sandra may weigh in) — decide once the flow is pinned.
+2. **Update skill-optimizer** so that when a user brings it a skill, it can decide to package it and call *these* skills to do so (sibling ↔ sibling).
+3. **Fate of existing creators**: `tessl-labs/tile-creator` is deprecated (no tiles; Labs = prototype). The `harness-engineering/plugin-creator` placeholder is closer to a product surface (ships with Tessl agent) so replacing it needs care.
+4. Does this plugin own publishing long-term, or defer to distribute?
+5. Is 6 skills the right cut?

plugin-creator/README.md

@@ -0,0 +1,24 @@
+# plugin-creator (working name)
+
+> First draft, not published. Built for Marc to review. Working name only, this is not plugin-first. See `DRAFT-NOTES.md`.
+
+Turn a problem, or a messy existing skill, into well-shaped agent context. It understands what you are trying to do, takes stock of what you already have, plans the right shape (a single skill, or a plugin with rules and MCP servers), and builds it. Evaluation is a separate, downstream step, handled by `tessl/skill-optimizer`; this gets you to a well-formed composition first.
+
+## The arc
+
+understand → gather → plan the composition → build → (then, separately) eval
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `create-context` | Orchestrator. Runs the arc and points to eval at the end. |
+| `gather-context` | Understand the problem and take stock of what exists; fill gaps by asking, hunting (PRs/logs), or inferring. |
+| `plan-composition` | Decide the shape: a single skill, or a plugin with the right primitives. |
+| `build-composition` | Create it, scaffolding with the CLI, not hand-written manifests. |
+| `decompose-into-skills` | Split a big skill into focused, independently-verifiable skills. |
+| `publish-plugin` | Optional. Publish or re-publish to the registry. |
+
+## Companion
+
+For quality (review, eval scenarios, optimisation), `tessl/skill-optimizer` is the sibling flow, after a composition is built.

plugin-creator/TRY-THIS.md

@@ -0,0 +1,71 @@
+# Try this (Sandra)
+
+Thanks for kicking the tyres on this draft. It's the **context/plugin creator** (working name), a set of skills that help someone turn a problem, or a messy existing skill, into well-shaped agent context. It does **not** run evals, that stays in skill-optimizer as a separate step.
+
+What we most want from you: a read on the **workflow and UX**. Does the flow make sense? Does it meet a user where they are? Anything confusing, missing, or annoying? Tweak it freely, it's a draft and nothing here is precious.
+
+The full rationale (and the user research behind it) is in the PRD Marc shared with you.
+
+## The flow it runs
+understand → gather → plan the composition → build → (then, separately) eval
+
+Six skills: `create-context` (orchestrator), `gather-context`, `plan-composition`, `build-composition`, `decompose-into-skills`, `publish-plugin`.
+
+## Set it up (about 5 minutes)
+You've got a clone of the `product-plugins` repo on the `opt-plugin-creator-draft` branch. The plugin is at `plugin-creator/`. To try it, install it into a scratch project:
+
+```bash
+# note the absolute path to the plugin-creator folder in your clone:
+PLUGIN=<absolute-path-to-your-clone>/plugin-creator
+
+mkdir -p ~/pc-sandbox && cd ~/pc-sandbox
+cat > tessl.json <<JSON
+{ "name": "pc-sandbox", "dependencies": { "tessl/plugin-creator": { "source": "file:$PLUGIN" } } }
+JSON
+tessl install
+```
+
+Then open a Tessl or Claude Code session **in `~/pc-sandbox`** and try a scenario below.
+
+## Two scenarios to try
+
+**A - a messy existing skill (the main one).** Save this as `~/pc-sandbox/sample-messy-skill/SKILL.md`:
+
+```markdown
+---
+name: backend-helper
+description: Helps with backend stuff - APIs, database migrations, and deployment. Use this whenever you are doing backend work of any kind.
+---
+
+# Backend helper
+This skill helps with our backend. It covers a lot.
+
+## Writing API endpoints
+All endpoints go under /v{n}. Use plural nouns. Return problem+json for errors. Validate the body. Add tests. Timestamps ISO 8601 UTC. Don't break a published schema.
+
+## Database migrations
+Migrations live in db/migrations with a timestamp. Always write a reversible down. Never edit a shipped migration. Back-fill large tables in batches.
+
+## Deploying
+Deploy to staging first, run smoke tests, tag the release, announce in #releases. Never deploy Friday afternoon. Roll back with the previous tag.
+```
+
+Then tell the agent:
+> "I've got a skill at `sample-messy-skill/SKILL.md` that's a mess, it does endpoints, migrations, and deploys all in one. Help me get more out of Tessl with it."
+
+Watch whether it understands the problem, proposes a sensible plan (it should suggest splitting into focused skills and explain why), builds it, and only *then* mentions eval, without rewriting your content unasked or dragging you into evals.
+
+**B - from a brain-dump (no file needed).**
+> "I keep re-explaining our service architecture conventions to the agent. Help me capture this. Rough notes: [add three or four bullets]."
+
+Watch whether it gathers and probes for what's missing rather than dead-ending because you didn't hand it a finished skill.
+
+## Tweak it
+The skills are plain markdown at `plugin-creator/skills/*/SKILL.md`. Edit anything, re-run `tessl install` in `~/pc-sandbox`, and try again.
+
+## What we'd love back
+- Does the flow feel right, or does it get in the way?
+- Where did it confuse you or do the wrong thing?
+- Anything you'd change in how it talks to the user.
+
+Notes in whatever form is easiest. Marc picks this up Friday.

plugin-creator/evals/scenario-0/criteria.json

@@ -0,0 +1,56 @@
+{
+  "context": "Tests whether the agent correctly applies Tessl plugin conventions when scaffolding a single-skill plugin: verb-form skill naming, valid plugin.json manifest fields, skill description quality (what + when), progressive disclosure via references/, and choosing the smallest appropriate shape.",
+  "type": "weighted_checklist",
+  "checklist": [
+    {
+      "name": "Verb-form skill name",
+      "description": "The skill folder name is a verb or verb phrase (e.g. 'review-pr', 'audit-pull-request') — NOT a noun or noun phrase (e.g. 'prs', 'pr-review-skill', 'code-review-tool')",
+      "max_score": 15
+    },
+    {
+      "name": "plugin.json name format",
+      "description": "plugin.json contains a 'name' field in the format '<workspace>/<plugin-name>' (two slash-separated segments, no extra slashes)",
+      "max_score": 12
+    },
+    {
+      "name": "plugin.json semver version",
+      "description": "plugin.json contains a 'version' field that is a valid semver string (e.g. '1.0.0', '0.1.0')",
+      "max_score": 8
+    },
+    {
+      "name": "plugin.json description present",
+      "description": "plugin.json contains a non-empty 'description' field",
+      "max_score": 8
+    },
+    {
+      "name": "SKILL.md description covers what",
+      "description": "The SKILL.md frontmatter 'description' field states what the skill does (i.e. describes the PR review workflow or its output)",
+      "max_score": 10
+    },
+    {
+      "name": "SKILL.md description covers when",
+      "description": "The SKILL.md frontmatter 'description' field also states when to use the skill (e.g. 'when reviewing a pull request', 'use when...', or a trigger condition)",
+      "max_score": 10
+    },
+    {
+      "name": "References directory used",
+      "description": "A 'references/' subdirectory exists inside the skill folder containing at least one file",
+      "max_score": 12
+    },
+    {
+      "name": "SKILL.md links to references",
+      "description": "SKILL.md contains at least one markdown link pointing into the references/ directory (e.g. '[see checklist](references/checklist.md)')",
+      "max_score": 10
+    },
+    {
+      "name": "Single-skill shape chosen",
+      "description": "The agent produced a single skill (not a multi-skill plugin with multiple skill folders) — the problem is simple and self-contained",
+      "max_score": 10
+    },
+    {
+      "name": "plan.md justifies shape choice",
+      "description": "plan.md explains why a single skill was chosen (or if a plugin with multiple skills was chosen, gives a clear rationale beyond 'completeness')",
+      "max_score": 5
+    }
+  ]
+}

plugin-creator/evals/scenario-0/scenario.json

@@ -0,0 +1 @@
+{ "description": "Tessl plugin scaffolding conventions" }

plugin-creator/evals/scenario-0/task.md

@@ -0,0 +1,25 @@
+# Build a PR Review Skill for the Engineering Team
+
+## Problem Description
+
+Your engineering team has started using Tessl to share reusable agent workflows, and the team lead wants to add a pull-request review workflow to the shared plugin registry. Right now, developers rely on ad hoc checklists or personal notes when reviewing PRs — there is no consistent process, and newer team members miss common issues around correctness, style, and security.
+
+The team lead has asked you to create a Tessl skill that an agent can follow when reviewing a pull request. The skill should cover the full review process: checking for logic bugs, evaluating code style consistency, flagging potential security concerns, and summarising findings. It should be written so that another developer or an AI agent can pick it up and use it without hand-holding.
+
+The team lead wants this shipped as the smallest reasonable Tessl artifact — not a large multi-skill bundle unless that is genuinely needed. The skill (and any supporting files) should be placed on disk in a directory structure ready for use with Tessl tooling.
+
+## Output Specification
+
+Produce the following on disk:
+
+- A Tessl plugin directory (e.g. `.tessl-plugin/` or a named folder) containing:
+  - A `plugin.json` manifest
+  - A skill folder containing a `SKILL.md` entry point
+  - Any supporting reference files your skill links to
+- A `plan.md` file at the top level of your working directory that explains:
+  - The shape you chose (single skill vs multi-skill plugin) and why
+  - How you named the skill and why
+  - What you put in `SKILL.md` versus any `references/` files, and why
+  - Any design decisions about the description field
+
+Do not include the actual CLI output or session logs — just the final files and the `plan.md` explaining your decisions.

plugin-creator/evals/scenario-1/criteria.json

@@ -0,0 +1,56 @@
+{
+  "context": "Tests whether the agent correctly decomposes a monolithic skill into focused, independently-triggerable sub-skills following the decompose-into-skills guidance. The agent must lead with the value of decomposition, use verb-form skill names, surface shared material in references/, and avoid running evals or hinting at them.",
+  "type": "weighted_checklist",
+  "checklist": [
+    {
+      "name": "Benefit-led rationale",
+      "description": "decomposition-rationale.md leads with the benefit of the split (reliability, independent verifiability, or ease of maintenance) — not with mechanics or tidying framing",
+      "max_score": 12
+    },
+    {
+      "name": "Independent verifiability mentioned",
+      "description": "decomposition-rationale.md mentions that each skill can now be evaluated or verified independently (e.g., references skill-optimizer or independent evaluation)",
+      "max_score": 10
+    },
+    {
+      "name": "No eval-running",
+      "description": "decomposition-rationale.md does NOT announce plans to run evals now or as an immediate next step — evaluation is deferred or pointed at a separate tool",
+      "max_score": 8
+    },
+    {
+      "name": "Verb-form skill names",
+      "description": "All skill sub-folder names use verb form (e.g., migrate-schema, backup-database, monitor-health, manage-access) — none use noun-only names like 'migrations' or 'backups'",
+      "max_score": 10
+    },
+    {
+      "name": "One responsibility per skill",
+      "description": "Each resulting SKILL.md covers exactly one distinct responsibility area; no two skills have substantially overlapping trigger conditions",
+      "max_score": 12
+    },
+    {
+      "name": "Shared material in references/",
+      "description": "Shared reference content (e.g., environment variable requirements, safety rules) is placed in a references/ directory rather than duplicated across multiple skill files",
+      "max_score": 10
+    },
+    {
+      "name": "Orchestrator or explicit delegation",
+      "description": "Either an orchestrator skill exists that delegates to sub-skills, OR the plugin.json / rationale document makes delegation relationships explicit",
+      "max_score": 10
+    },
+    {
+      "name": "Cross-skill dependencies explicit",
+      "description": "If any skill depends on another (e.g., backup-database is a prerequisite for migrate-schema), that dependency is called out explicitly in the skill content or rationale — skills are not expected to be used in isolation when they cannot be",
+      "max_score": 8
+    },
+    {
+      "name": "plugin.json present",
+      "description": "A plugin.json manifest exists at the top of the plugin directory with at minimum name, version, and description fields",
+      "max_score": 8
+    },
+    {
+      "name": "Decomposition structure shown",
+      "description": "decomposition-rationale.md includes a proposed structure listing each skill name and its trigger or responsibility — not just prose explanation",
+      "max_score": 12
+    }
+  ]
+}