Team plugin synthesis

Team Plugin Synthesis

Turn the workflow profile into a plugin draft. Synthesis reads .team-builder/profile/workflow-profile.md and the current contents of plugin/skills/, and records exactly one decision per affected skill in .team-builder/decisions/ledger.jsonl.

Preconditions

The workflow profile must exist and pass validation:

python3 scripts/validate-profile.py .team-builder/profile/workflow-profile.md

If the profile is missing or fails validation, refuse to run synthesis and direct the manager to team-plugin-intake first. Synthesis never invents a profile, and it never runs against a profile that hasn't passed the gate.

Procedure

Read the workflow profile in full, then list every skill under plugin/skills/. For each skill, record exactly one decision using this table:

Decision	When	Authority
keep	Trigger, procedure, and output already fit the team	Autonomous, no evidence required
extend	Method is right; add team context, tools, references, or a neighboring skill	Autonomous, evidence required
edit	Sequencing, gates, or outputs must materially change	Applied autonomously, surfaced as a diff in the change summary
delete	Irrelevant, redundant, or conflicting with approved team process	Proposed only; write approved_by: null and ask the manager explicitly
add	An evidenced repeated capability the core does not cover	Autonomous, evidence required

Ledger record shape

Each decision is one JSON line appended to .team-builder/decisions/ledger.jsonl, with exactly these seven keys — scripts/validate-ledger.py rejects a record with any key missing or any key extra. Copy this shape:

{"id":"dec-0001","decision":"extend","target":"skills/test-driven-development","rationale":"Team requires a coverage gate before review","supports":["ev-0007"],"approved_by":null,"decided_at":"2026-07-27T09:00:00Z"}
{"id":"dec-0002","decision":"delete","target":"skills/using-git-worktrees","rationale":"Team works on a single shared branch and never uses worktrees","supports":["ev-0011"],"approved_by":null,"decided_at":"2026-07-27T09:05:00Z"}

• id is unique across the file.
• decision is one of keep, extend, edit, delete, add.
• target is the path of the affected skill, e.g. skills/<name>.
• rationale must be non-empty.
• supports is a list of evidence ids from .team-builder/evidence/catalog.jsonl, and must be non-empty for every decision except keep.
• approved_by stays null on a proposed deletion. Only team-plugin-publish fills it in, with the manager's name, after asking about that deletion by name.
• decided_at is an ISO-8601 UTC timestamp.

Then generate the draft: apply extensions and edits in place under plugin/skills/; write new team skills as complete working skills, never stubs; normalize any imported team skill's structure while preserving its behavior.

REQUIRED SUB-SKILL: Use superpowers:writing-skills for every skill you write or change here — both when authoring a new team skill and when editing or extending an existing core one. It ships inside the very plugin this skill is editing, and it carries the discipline this one does not repeat: baseline testing before and after, the rationalization table, the red-flags list, file organization, and the frontmatter rules. Invoke it by name; never reference it as an @ path, which force-loads the file and burns context for no benefit.

Whatever you generate here, the team then lives inside. A defect in the authoring discipline is not one bad skill — it is every skill this product ever generates.

Deleting a skill means removing its directory from plugin/skills/ and writing its delete record. Publish compares the tree against the last published skill set and refuses a release where a skill vanished without an approved record — a removal with no record is not a shortcut, it is a blocked publish.

Generated skill contract

This is what a generated skill must additionally state for this team. It sits on top of superpowers:writing-skills, which governs how the skill is written and tested; it never replaces it.

Every added or imported skill states:

• a precise trigger description — see the rule below,
• purpose and non-goals,
• required inputs,
• an ordered procedure,
• expected outputs,
• completion criteria,
• fallback behavior when a dependency is unavailable, and
• provenance for team-specific policy.

What "a precise trigger description" means

The description: frontmatter field states triggering conditions only, in third person, starting with Use when. It must NEVER summarize the skill's process, workflow, or steps.

This is not a style preference. An agent reads descriptions to decide which skill to load, and a description that summarizes a workflow gets followed in place of the skill body — the agent takes the two-line shortcut and never reads the procedure it was supposed to run. The routing gate in team-plugin-validate also depends on descriptions naming symptoms and situations, not summaries.

# BAD - summarizes the workflow, so agents follow this instead of the skill
description: Use when deploying - run migrations, tag the release, then notify #ops

# BAD - process detail masquerading as a trigger
description: Use for incident review - gather timeline, find contributing causes, write the doc

# GOOD - triggering conditions only
description: Use when a production deploy is being prepared or a release is about to be tagged

# GOOD - symptoms and situation, no workflow
description: Use when an incident has been mitigated and the team needs its review before the next release

Everything else about how the skill is written — structure, testing, concrete-over-abstract wording — comes from superpowers:writing-skills.

Questions

Ask the manager only about:

• a direct contradiction between authoritative sources,
• a change that materially weakens or reorders the core workflow, or
• a proposed deletion.

Everything else is decided autonomously and recorded in the ledger.

Closing

Write .team-builder/reports/change-summary.md with four sections — added skills, edited core skills with diffs, proposed deletions awaiting approval, and gaps the profile could not fill. Then run:

python3 scripts/validate-ledger.py .team-builder/decisions/ledger.jsonl

Red flags

Impulse	Correction
Write a skill stub to fill a gap	Generate a working skill or record the gap. Never ship a stub.
Author or edit a skill straight from this contract	This contract is the team-specific layer. Use superpowers:writing-skills for the craft itself.
Write a description that explains what the skill does	Descriptions state when to use it. A summarized workflow is the workflow agents will follow.
Delete a core skill because it looks unused	Deletion requires explicit manager approval, recorded in approved_by.
Invent a convention the profile does not support	Every non-keep decision needs a supporting evidence id.
Rewrite an imported team skill's behavior while normalizing it	Normalize structure only; semantic changes need approval.
Skip the ledger for a small edit	Every affected skill gets exactly one decision record.
Put team-specific instructions in a plugin-root CLAUDE.md	Claude Code does not load it from installed plugins. Use skills or hooks.