@harness-lab/cli 0.2.1 → 0.2.3

package/assets/workshop-bundle/workshop-blueprint/control-surfaces.md

@@ -0,0 +1,101 @@
+# Workshop Control Surfaces
+
+Harness Lab has one workshop-instance backend and multiple control surfaces with different trust levels.
+
+All control surfaces should reinforce the same operating model:
+
+- push context into the repo
+- keep the next safe step obvious
+- ask for evidence, not confidence
+- bias participants toward continuation-ready artifacts instead of hidden chat context
+
+## Participant Surface
+
+Purpose:
+- orient teams during the workshop day
+- show participant-safe phase and room context
+- keep the next action obvious on mobile and on projection
+
+Default behavior:
+- show the current phase
+- show the next hard milestone
+- show the next harness move, not only the next feature move
+- remind teams what evidence should exist by the next checkpoint
+
+Good prompts from the surface:
+- "Máš už `AGENTS.md` jako mapu repa?"
+- "Je další bezpečný krok dohledatelný pro cizí tým?"
+- "Co dnes opravdu ověřujete, ne jen předpokládáte?"
+
+Authentication:
+- public first
+- participant event code unlocks participant-private context for one workshop instance
+
+## Facilitator Dashboard
+
+Purpose:
+- fast visual control of the active workshop instance
+- safe runtime operations during the day
+
+Design rule:
+- facilitator checkpoints should ask for repo evidence
+- status collection should prefer "what changed, what verifies it, what should the next team read first?" over generic progress text
+
+Authentication:
+- facilitator identity and instance grant
+
+Scope:
+- runtime state only
+- no hidden authority to redefine the blueprint silently
+
+## Facilitator Skill
+
+Purpose:
+- AI-assisted interface to the same workshop runtime APIs
+- useful when a facilitator wants a conversational control path or guided summaries
+
+Default coaching:
+- before lunch, push teams toward `AGENTS.md`, a plan, commands, and one executable check
+- during continuation, push teams to read before editing and to write down what is missing
+- after continuation, push teams to codify repeated pain into docs, checks, or runbooks
+
+Authentication:
+- facilitator commands rely on the `harness` CLI for privileged auth bootstrap and stored local session material
+- the skill should not become a second secret store
+
+## `harness` CLI
+
+Purpose:
+- small local broker for privileged facilitator auth and session storage
+- bootstrap helper for dashboard/skill usage
+- thin operational client over the shared facilitator runtime APIs
+
+Required v1 responsibilities:
+
+- login
+- logout
+- status
+- secure local session storage
+- passing authenticated requests on behalf of facilitator tooling
+
+Explicit non-goals for v1:
+
+- participant login
+- replacing the dashboard
+- becoming a second backend
+- auto-publishing runtime edits back into the repo
+
+## Vocabulary Rule
+
+All facilitator control surfaces should use the same nouns:
+
+- blueprint
+- workshop instance
+- participant access
+- facilitator grant
+- current phase
+- continuation shift
+- archive
+- reset
+
+The blueprint is the naming authority. Runtime clients should not invent alternate labels for the same operation.

package/assets/workshop-bundle/workshop-blueprint/day-structure.md

@@ -0,0 +1,129 @@
+# Harness Lab Day Structure
+
+Harness Lab is a full-day build workshop about harness engineering: engineering context, instructions, workflow, and review loops so AI-agent work survives another team, another facilitator, and another context window.
+
+The workshop should not teach these practices as optional extras layered on top of a hackathon. The practices are the operating system of the day. Every phase should make the next safe harness move more obvious than jumping straight into feature generation.
+
+## Core Promise
+
+Participants should leave with two things:
+
+- a working artifact or tracer-bullet implementation in their team repo
+- a clearer mental model of how to turn agent output into durable engineering work
+
+The workshop does not optimize for maximum feature count. It optimizes for continuation quality.
+
+## Design Rule
+
+Harness Lab teaches by forcing the useful behavior:
+
+- repo-native context beats chat memory
+- short maps beat giant instruction dumps
+- verification beats confidence
+- explicit boundaries beat hidden convention
+- cleanup is part of building, not a postponed chore
+
+## Day Arc
+
+### 1. Opening and framing
+
+Goal:
+- explain why harness engineering matters
+- make the repo the operating surface, not the slide deck
+- set expectations around tests, review, and explicit context
+
+Habit installed:
+- humans steer, agents execute
+- the engineer's job is to design context, constraints, and feedback loops
+
+What teams should hear:
+- success is not "how much code we got"
+- success is whether another team can continue without needing the authors in the room
+
+### 2. Context is King talk
+
+Goal:
+- demonstrate that better context changes output quality materially
+- show why `AGENTS.md`, plans, and explicit boundaries matter before implementation starts
+
+Habit installed:
+- `AGENTS.md` is a map, not a manual
+- if a rule matters, it should live in the repo where the next agent can find it
+
+Teaching move:
+- compare one underspecified task with one task that has goal, context, constraints, and done criteria
+- show that progressive disclosure is stronger than one giant prompt blob
+
+### 3. Build Phase 1
+
+Goal:
+- get every team into a real repo quickly
+- establish a legible operating surface before feature chasing
+- get `AGENTS.md`, a plan, one executable check, and the first reviewed output in place before lunch
+
+Expected evidence in the repo:
+- clear task framing
+- explicit working rules
+- a plan or tracked implementation path
+- at least one meaningful verification step
+- a visible next safe step for another person or agent
+
+Habit installed:
+- map before motion
+- verification is the trust boundary
+- the first deliverable is harness quality, not feature count
+
+### 4. Continuation shift
+
+Goal:
+- prove what survives when a different team takes over
+- force teams to read the repo before editing
+- expose missing context, weak runbooks, and fragile assumptions
+
+Operating rule:
+- the receiving team reads first
+- the receiving team changes only after it can explain the current state
+- the sending team is not the hidden source of truth
+
+Habit installed:
+- if it is not encoded in the repo, it does not exist
+- continuation quality is the real quality check
+
+Required first move:
+- the receiving team should first write what helped continuation, what is missing, what looks risky, and what the next safe move is
+
+### 5. Reveal and reflection
+
+Goal:
+- compare what helped continuation versus what caused friction
+- reinforce the idea that the harness is part of the product
+- collect improvements that belong back in the reusable blueprint
+
+Habit installed:
+- cleanup and codification are part of delivery
+- repeated pain should become a better template, check, or runbook
+
+## What Must Survive In The Repo
+
+- goal and constraints
+- build and test flow
+- architecture boundaries that affect safety or continuation
+- the current plan or handoff status
+- evidence of what was verified
+- the next safe step
+- the small set of rules that the team kept repeating out loud
+
+## What The Workshop Teaches Implicitly
+
+- context before generation
+- explicit interfaces before hidden backchannels
+- tests and executable checks as trust boundaries
+- documentation that changes decisions, not documentation for its own sake
+- `AGENTS.md` as a table of contents that points to deeper sources of truth
+- small, continuous garbage collection before bad patterns spread
+
+## Canonical Agenda Source
+
+The reusable agenda lives in [`agenda.json`](agenda.json).
+
+Runtime workshop instances import from that blueprint and then track live phase position, reveal state, teams, and checkpoints locally in the private runtime layer.

package/assets/workshop-bundle/workshop-blueprint/edit-boundaries.md

@@ -0,0 +1,64 @@
+# Edit Boundaries
+
+This document is the quick answer to "what do I edit where?"
+
+## Edit The Public Blueprint When
+
+- you are improving the reusable workshop method
+- you are changing the canonical agenda or phase descriptions
+- you are clarifying participant or facilitator guidance that should apply to future workshops
+- you are refining the control model, API contract, or publish-back rule
+
+Typical locations:
+
+- [`workshop-blueprint/`](./)
+- [`content/`](../content/)
+- reusable docs in [`docs/`](../docs/)
+- shared dashboard code and skill docs
+
+## Edit The Private Runtime Instance When
+
+- you are changing the current phase of a live workshop
+- you are revealing or hiding continuation
+- you are registering teams or repo URLs
+- you are capturing checkpoints, monitoring, or sprint updates
+- you are attaching real event metadata such as date, venue, or facilitator notes
+
+Typical locations:
+
+- private database or private file-backed runtime store
+- facilitator dashboard mutations
+- facilitator skill commands over runtime APIs
+
+## Never Store In The Public Repo
+
+- real workshop dates, venues, or client names
+- live team registry for a real event
+- facilitator credentials or session material
+- monitoring output tied to a real workshop
+- facilitator-only intervention notes
+
+## Source Map
+
+| Topic | Public blueprint | Runtime instance | Private ops |
+|-------|------------------|------------------|-------------|
+| workshop framing | yes | no | no |
+| canonical agenda | yes | imported copy only | no |
+| current phase during a live event | no | yes | optional notes only |
+| participant challenge deck | yes | completion state only | no |
+| facilitator grants | no | yes | no |
+| room logistics and staffing notes | no | no | yes |
+| live team repo registry | no | yes | optional exports |
+| post-event reusable improvement | yes, by GitHub edit | no auto-promotion | optional prep notes |
+
+## Publishing Rule
+
+Runtime edits stay local to the instance.
+
+If a facilitator learns something reusable during a live event:
+
+1. capture the learning privately if needed
+2. decide whether it changes the reusable method
+3. make a deliberate GitHub edit to the blueprint or related docs
+
+The system must not imply that reset, archive, or runtime mutation writes back into the blueprint automatically.

package/assets/workshop-bundle/workshop-blueprint/operator-guide.md

@@ -0,0 +1,74 @@
+# Workshop Operator Guide
+
+This guide explains how a facilitator runs a workshop instance without confusing reusable blueprint design with live runtime control.
+
+## Facilitator Job
+
+The facilitator owns:
+
+- preparing a private workshop instance
+- verifying participant access and facilitator auth
+- steering the agenda through the day
+- capturing team progress and live signals
+- protecting the boundary between public blueprint and private event state
+
+The facilitator does not use the live dashboard to silently rewrite the reusable workshop method.
+
+## Before The Day
+
+1. Start from the public blueprint in [`README.md`](README.md).
+2. Create or prepare a private workshop instance by importing the blueprint.
+3. Attach instance-local metadata outside the public repo:
+   - real date
+   - venue and room
+   - participant event code configuration
+   - facilitator grants
+   - facilitator-only notes
+4. Verify participant and facilitator access paths.
+5. Verify the active instance begins from the expected blueprint version/reference.
+
+## During The Day
+
+Operate the live instance through the shared runtime control surfaces:
+
+- dashboard facilitator surface for fast visual control
+- facilitator skill for AI-assisted operations
+- `harness` CLI for privileged auth bootstrap and local secure credential/session handling
+
+Facilitation priority order:
+
+1. keep the next safe move obvious
+2. push teams to encode context in the repo instead of explaining it orally
+3. ask for executable verification before encouraging more autonomy
+4. treat continuation friction as a signal to improve the harness, not as a participant failure
+
+Typical runtime-only actions:
+
+- move the current phase
+- reveal or hide the continuation shift
+- register teams and repo URLs
+- update checkpoints and sprint notes
+- archive or reset the instance
+
+These actions affect only the active workshop instance unless a facilitator deliberately makes a repo edit afterward.
+
+## After The Day
+
+1. Archive the workshop instance.
+2. Capture runtime learnings that may improve the reusable workshop method.
+3. Decide which learnings are:
+   - runtime-only notes that stay private
+   - reusable improvements that belong back in the public blueprint
+4. Publish reusable improvements through a normal GitHub edit or pull request.
+
+## Golden Rule
+
+If a change should help the next workshop by default, it belongs in the blueprint and must be committed deliberately.
+
+If a change only helps the current live event, it belongs in the runtime instance and must not auto-promote back into the repo.
+
+## What To Keep Reinforcing
+
+- `AGENTS.md` should stay short and point outward to deeper sources of truth.
+- The repo should contain plan, commands, verification evidence, and the next safe step.
+- When a repeated issue appears across tables, turn it into a stronger template, challenge, reference card, or check.

package/assets/workshop-bundle/workshop-blueprint/teaching-spine.md

@@ -0,0 +1,134 @@
+# Workshop Teaching Spine
+
+This document defines what Harness Lab should repeatedly teach, recommend, and normalize through the day.
+
+The aim is not to add a separate rubric on top of the workshop. The aim is to make the desired operating habits the default behavior of the room, the dashboard, the workshop skill, and the facilitator prompts.
+
+## Core Thesis
+
+Participants are not here to learn "how to prompt better."
+
+They are here to learn how to build a repository and workflow that an AI coding agent and another team can actually continue. The engineer's role shifts upward:
+
+- humans steer
+- agents execute
+- the repo carries context
+- verification carries trust
+
+## Five Habits To Install
+
+### 1. Map before motion
+
+Teach:
+- start by making the repo navigable
+- use `AGENTS.md` as a short map to the important files, rules, and next steps
+
+What to say:
+- "Než začnete generovat feature, udělejte z repa místo, kde se dá orientovat."
+
+Adoption signal:
+- the team has a short `AGENTS.md`, clear entry points, and an explicit next safe step
+
+### 2. If it is not in the repo, it does not exist
+
+Teach:
+- decisions, constraints, and working rules belong in tracked artifacts
+- oral handoff, chat memory, and facilitator memory are not durable context
+
+What to say:
+- "To, co má přežít vás i context window, musí být dohledatelné v repu."
+
+Adoption signal:
+- new assumptions become docs, plan updates, runbooks, or tests instead of staying in chat
+
+### 3. Verification is the trust boundary
+
+Teach:
+- the more autonomy the agent gets, the stronger the verification loop must become
+- use the smallest useful test, tracer bullet, browser regression, or check
+
+What to say:
+- "Jakmile agent pracuje samostatněji, nestačí důvěra. Potřebujete důkaz."
+
+Adoption signal:
+- meaningful work has executable evidence attached to it
+
+### 4. Boundaries create speed
+
+Teach:
+- simple architecture rules and explicit constraints help agents move faster with less drift
+- prefer boring, legible structure over clever opacity
+
+What to say:
+- "Mantinely nejsou brzda. S agentem jsou to koleje."
+
+Adoption signal:
+- the repo names boundaries, commands, and done criteria clearly enough that a new team can act without guessing
+
+### 5. Cleanup is part of build
+
+Teach:
+- drift compounds quickly in agent-heavy workflows
+- repeated review comments should become templates, checks, or reusable guidance
+
+What to say:
+- "Když vás něco bolí podruhé, nemá to zůstat jen jako připomínka v hlavě."
+
+Adoption signal:
+- teams stop to simplify, document, or encode a recurring rule before moving on
+
+## Phase-By-Phase Teaching Moves
+
+### Opening and framing
+
+Teach:
+- the workshop is about operating systems for agent work, not prompt theatre
+- the real output is a repo that can speak for itself
+
+Facilitator line:
+- "Dnes nebudeme soutěžit v promptování. Budeme stavět pracovní systém, který přežije handoff."
+
+### Context is King talk
+
+Teach:
+- progressive disclosure beats giant prompts
+- `AGENTS.md` should be a map, not an encyclopedia
+- repository knowledge should become the system of record
+
+Demonstrate:
+- a weak task with missing constraints
+- a stronger task with goal, context, constraints, and done criteria
+- the difference between a giant blob and a layered map
+
+### Build Phase 1
+
+Teach:
+- before lunch, teams should establish the operating surface that makes later autonomy safe
+
+Push teams toward:
+- short `AGENTS.md`
+- plan or tracked implementation path
+- build/test commands
+- one executable verification loop
+- one reviewed output
+
+### Continuation shift
+
+Teach:
+- continuation is the real exam
+- the receiving team should diagnose before editing
+
+Push teams toward:
+- reading `README`, `AGENTS.md`, and the current plan first
+- writing what helped, what is missing, what is risky, and what the next safe move is
+
+### Reveal and reflection
+
+Teach:
+- repeated pain should become a better harness artifact
+- the harness is part of the product, not support material around it
+
+Push teams toward:
+- concrete examples of what saved time
+- concrete examples of what remained implicit
+- one improvement they would carry back to real work next week

package/assets/workshop-bundle/workshop-skill/analyze-checklist.md

@@ -0,0 +1,21 @@
+# Workshop Analyze Checklist
+
+Když agent dělá `/workshop analyze`, měl by projít:
+
+- existenci a kvalitu `AGENTS.md`
+- jestli je `AGENTS.md` mapa nebo přerostlý dump
+- jestli `AGENTS.md` říká, co číst jako první
+- jestli `AGENTS.md` odkazuje na skutečné source-of-truth docs
+- přítomnost build/test příkazů
+- jestli repo rozlišuje hotové vs. rozpracované části
+- jestli je v repu plan nebo runbook pro další tým
+- jestli je dohledatelné, co bylo skutečně ověřeno
+- kolik pravidel žije jen v promptu a ne v repu
+- jak snadné by bylo pokračovat po rotaci bez ústního handoffu
+- jestli je zřejmý další bezpečný krok
+
+## Výstup
+
+1. Co pomohlo pokračovat
+2. Co chybělo
+3. Co přidat před dalším handoffem

package/assets/workshop-bundle/workshop-skill/closing-skill.md

@@ -0,0 +1,30 @@
+# Workshop Closing
+
+## Úkol
+
+Na konci dne vytvoř krátké shrnutí workshopu, které je:
+
+- konkrétní
+- systémové, ne osobní
+- lehce meta: ukazuje, že agent umí shrnout práci agentů i lidí dohromady
+
+## Vstupy
+
+- sprint checkpoint feed z dashboardu
+- monitoring summary nebo manuální scan
+- W³ sticky notes nebo přepsané commitments
+- případně poznámky z intermezz
+
+## Výstup
+
+1. Co pomohlo týmům pokračovat po handoffu
+2. Co opakovaně chybělo
+3. Jaké 2-3 principy si má místnost odnést do příštího týdne
+4. Jedna závěrečná věta, která propojí workshop s reálnou prací v týmu
+
+## Styl
+
+- česky
+- věcně
+- bez oslavného tónu
+- zjištění opírej o konkrétní signály z dne

package/assets/workshop-bundle/workshop-skill/commands.md

@@ -0,0 +1,44 @@
+# Workshop Commands
+
+## Jak skill používat
+
+- V Codexu používejte `$workshop ...`
+- V pi načtěte `/skill:workshop` a potom si řekněte o konkrétní akci přirozeně nebo přes název příkazu
+- Skill má být nainstalovaný přímo ve vašem pracovním repu přes `harness skill install`. Nemusíte kvůli tomu klonovat Harness Lab repo.
+- Když si nejste jistí, začněte `workshop commands` nebo `workshop reference`
+
+## Nejkratší pracovní postup
+
+1. `workshop reference`
+2. `workshop brief`
+3. `workshop template`
+4. `workshop help`
+5. `workshop resources`
+
+## Co který příkaz dělá
+
+- `workshop` - kde v workshopu právě jste a co je další bezpečný krok
+- `workshop setup` - jak se co nejrychleji rozběhnout v Codexu nebo pi
+- `workshop brief` - zadání týmu a první ukotvení scope
+- `workshop challenges` - challenge cards pro další posun
+- `workshop team` - tým, repo a checkpoint
+- `workshop reference` - krátká karta pracovních výchozích bodů pro dnešek
+- `workshop help` - coaching podle fáze dne nebo podle problému, na kterém jste zaseknutí
+- `workshop template` - starter `AGENTS.md`
+- `workshop analyze` - rychlý handoff check repa
+- `workshop resources` - účastnický kit, learner kit a další navazující materiály
+- `workshop follow-up` - co si odnést a co udělat 48 hodin až 1 týden po workshopu
+- `workshop gallery` - ověřené externí docs a veřejné repozitáře pro další učení
+- `workshop recap` - krátké uzavření nebo připomínka po workshopu
+
+## Kdy co použít
+
+- Když nevíte, kde začít: `workshop reference`
+- Když je zadání rozmazané: `workshop brief`, potom `brainstorm` nebo `plan`
+- Když repu chybí kontext: `workshop template`
+- Když si nejste jistí workflow: `workshop commands`
+- Když chcete materiály i po workshopu: `workshop resources`, `workshop follow-up`, `workshop gallery`
+
+## Důležitá poznámka
+
+`workshop` skill je garantovaný výchozí nástroj workshopu. Další workflow skills a veřejné toolkity jsou doporučené rozšíření, ne podmínka účasti.