Skills Architecture: Use Cases¶

How the common jobs run from start to finish, and where they cross from one project to another.

Working habits¶

A few working habits, not hard rules:

• Work usually starts in the project that owns it, and anything public usually ends in the Wiki project. Crossing over is normal: wiki-tasting can borrow the dregs research, and a correction found during a run travels in the run's next update draft.
• Projects hand over through the repository. A new page is a draft in inbox/drafts/ that already has its ID (the draft reserves it); a change to a published page is an update draft (<page-id>-update-<date>.md); a finished document goes to inbox/raw/; a skill release is a bundle in inbox/releases/. You carry one line, never the conversation.
• The skill that hands over gives you the line to paste in the next project.
• Every skill is available in every session; the project instructions keep each one in its lane. Nothing reaches git or the live site until you commit and push.

Reading the diagrams¶

• Columns, always in this order when they take part: You, Cultures Studio, Ingredients Studio, Repository, Wiki project.
• Solid arrow from you: what you give, then the skill and mode it starts, as (skill · mode).
• Solid arrow from a project to itself: one skill calling another, (skill · mode).
• Solid arrow to the repository: what is written there.
• Dashed arrow: what comes back to you, or what a skill reads from the repository.
• Notes: what you do outside Claude.

1 · Taste and review a beer¶

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant R as Repository
  participant WP as Wiki project
  Y->>WP: tasting notes, bottle, label and glass photos<br/>(wiki-tasting · new)
  R-->>WP: isolation plan research, if the bottle has one
  WP->>R: research file in work/beer-research/
  WP->>WP: photos and page<br/>(wiki-media · photos, then wiki-publish · new draft)
  WP->>R: tasting note page
  WP-->>Y: change set and commit message
  Note over Y: review, commit, push

Research for notes already published: wiki-tasting · research. A second tasting of the same beer is a dated block on its page.

2 · From dregs to an adopted plan¶

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant CS as Cultures Studio
  participant R as Repository
  Y->>CS: bottle data, label photos, micrographs<br/>(bottle-dregs-analysis · analysis)
  R-->>CS: beer research, capability matrix
  CS->>R: plan-v1 in work/isolation-plans/
  loop until you adopt the plan
    Y->>CS: proposed changes, kit changes<br/>(bottle-dregs-analysis · critique)
    CS->>R: critique, plan-vN
    opt cell sizes wanted
      Y->>CS: micrographs<br/>(bottle-dregs-analysis · measure)
      CS->>R: measured copies beside the photos
    end
  end

3 · Start and run the plan¶

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant CS as Cultures Studio
  participant R as Repository
  participant WP as Wiki project
  Y->>CS: adopted plan-vN<br/>(isolation-run · start)
  CS->>CS: journey seed from the plan<br/>(bottle-dregs-analysis · start journey)
  CS->>CS: journey draft and its ID<br/>(wiki-capture · new-journey)
  CS->>R: journey draft in inbox/drafts/
  CS->>R: run record: state, log, registers, sample tree
  CS-->>Y: line for the Wiki project
  Y->>WP: journey draft<br/>(wiki-publish · new draft)
  WP->>R: journey page, tasting note set to started
  Note over Y: review, commit, push
  loop each bench session
    Y->>CS: bench results, photos<br/>(isolation-run · update)
    CS->>R: log, registers, sample tree, state
    opt a question or a plan change
      Y->>CS: question or change<br/>(isolation-run · consult or re-plan)
      CS->>CS: reading or new plan version<br/>(bottle-dregs-analysis · critique)
    end
  end
  Y->>CS: end of session<br/>(isolation-run · hand-over)
  CS-->>Y: pick-up prompt
  Note over Y: new chat
  Y->>CS: pick-up prompt<br/>(isolation-run · pick-up)

A bottle with no plan starts with wiki-capture · new-journey alone, in either project.

4 · Publish progress on the journey¶

Usually at a milestone (a plating round, colonies picked, a target closed), but at any time.

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant CS as Cultures Studio
  participant R as Repository
  participant WP as Wiki project
  Y->>CS: milestone reached<br/>(isolation-run · milestone)
  CS->>R: update draft in inbox/drafts/:<br/>entry, photos, sample tree, current state
  CS-->>Y: line for the Wiki project
  Y->>WP: update draft<br/>(wiki-capture · apply-update)
  WP->>WP: photos and page<br/>(wiki-media · photos, then wiki-publish · in-place update)
  WP->>R: journey updated, draft moved to inbox/attic/
  Note over Y: review, commit, push, back to the bench

5 · Bank an organism¶

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant CS as Cultures Studio
  participant R as Repository
  participant WP as Wiki project
  Y->>CS: every target banked or closed<br/>(isolation-run · close)
  CS->>CS: plan and outcome<br/>(bottle-dregs-analysis · merge)
  CS->>CS: one page per banked culture<br/>(wiki-capture · new-organism)
  CS->>R: one update draft and the organism drafts in inbox/drafts/
  CS-->>Y: line for the Wiki project
  Y->>WP: update draft<br/>(wiki-capture · apply-update)
  Y->>WP: organism drafts<br/>(wiki-publish · new draft)
  WP->>R: journey, organism pages, links,<br/>bank inventory, tasting note
  Note over Y: review, commit, push

An organism with no journey (a pouch, a swap) is wiki-capture · new-organism in the Wiki project; later changes (slants, tests, a mini-beer) are wiki-capture · organism-update.

6 · Ingredient work to the wiki¶

Cross to the Wiki project when a design or an analysis page is worth showing; each later version makes the same trip.

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant IS as Ingredients Studio
  participant R as Repository
  participant WP as Wiki project
  Y->>IS: ingredient, beer or target<br/>(ingredient-studio · explore)
  IS-->>Y: overview with options
  Y->>IS: chosen task or directive<br/>(ingredient-studio · directed)
  IS->>R: design or analysis page in designs/
  Y->>IS: design or page to publish<br/>(ingredient-studio · send to the wiki)
  IS->>R: copy in inbox/raw/ (-v2 for a new version)
  IS-->>Y: file name for the Wiki project
  Y->>WP: document in inbox/raw/<br/>(wiki-intake · new page or new version)
  WP->>WP: placement, links, check<br/>(wiki-publish · new draft)
  WP->>R: page, a new version keeping its ID and URL
  Note over Y: review, commit, push

7 · Cook, dose, taste and debrief¶

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant IS as Ingredients Studio
  participant R as Repository
  participant WP as Wiki project
  Note over Y: cook, then dose
  Y->>WP: cook or dosing readings, photos<br/>(wiki-capture · prep-update)
  WP->>WP: entry and status<br/>(wiki-publish · in-place update)
  WP->>R: Prepared or Dosed entry on the preparation page
  Note over Y: taste
  Y->>IS: tasting notes for the design<br/>(fruit-maillard-prep · debrief)
  IS-->>Y: verdict per prediction, blocks to paste
  Y->>IS: pasted blocks<br/>(ingredient-studio · check)
  Y->>WP: verdicts, tasting notes<br/>(wiki-capture · prep-update)
  WP->>WP: entry and status<br/>(wiki-publish · in-place update)
  WP->>R: Debriefed entry on the preparation page
  Note over Y: review, commit, push
  opt a revised design
    Y->>IS: changes to the design<br/>(fruit-maillard-prep · design)
    Note over Y,WP: then use case 6
  end

A treatment design is debriefed the same way with ingredient-treatments · debrief.

8 · Change and release an ingredient skill¶

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant IS as Ingredients Studio
  participant R as Repository
  participant WP as Wiki project
  Y->>IS: the change to the skill<br/>(ingredient-suite · change)
  Y->>IS: checks and guide text<br/>(ingredient-suite · check, then ingredient-suite · docs)
  Y->>IS: go<br/>(ingredient-suite · release)
  IS->>R: bundle in inbox/releases/
  IS-->>Y: bundle ID
  Y->>WP: bundle ID<br/>(wiki-release-skill · Path A)
  WP->>WP: indexes, navigation, check<br/>(wiki-publish · in-place update)
  WP->>R: zips and guide pages
  WP-->>Y: change set, line for Ingredients Studio
  Note over Y: review, commit, push
  Y->>IS: bundle ID<br/>(ingredient-suite · released)
  IS->>R: register and guide tables updated
  Note over Y,WP: the tables changed, so a docs-only bundle and Path A once more

A guide fix alone: edit suite/docs/, then ingredient-suite · release with --docs-only, and Path A. The ingredient skills run from skills/, so nothing needs installing.

9 · Change and release a culture skill¶

%%{init: {"sequence": {"mirrorActors": false}}}%%
sequenceDiagram
  actor Y as You
  participant CS as Cultures Studio
  participant R as Repository
  participant WP as Wiki project
  Y->>CS: the change to the skill, edited in the session
  CS->>R: skills/ folder with CHANGELOG-vN.md
  Y->>WP: skill name and version<br/>(wiki-release-skill · Path B)
  WP->>R: scrubbed copy in skills-src/, zip
  WP->>WP: guide page and studio index<br/>(wiki-publish · in-place update)
  WP-->>Y: change set, install line
  Note over Y: review, commit, push, upload the zip in Claude settings

A guide change without a new version: wiki-release-skill · guide-only in the Wiki project.

Everything else¶

Generated pages are never edited in the Wiki project: changes go back to Ingredients Studio.