@harness-lab/cli 0.2.0 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -5
- package/assets/workshop-bundle/SKILL.md +295 -0
- package/assets/workshop-bundle/bundle-manifest.json +172 -0
- package/assets/workshop-bundle/content/challenge-cards/.gitkeep +0 -0
- package/assets/workshop-bundle/content/challenge-cards/deck.md +38 -0
- package/assets/workshop-bundle/content/challenge-cards/print-spec.md +28 -0
- package/assets/workshop-bundle/content/facilitation/.gitkeep +0 -0
- package/assets/workshop-bundle/content/facilitation/codex-setup-verification.md +54 -0
- package/assets/workshop-bundle/content/facilitation/master-guide.md +131 -0
- package/assets/workshop-bundle/content/project-briefs/.gitkeep +0 -0
- package/assets/workshop-bundle/content/project-briefs/code-review-helper.md +31 -0
- package/assets/workshop-bundle/content/project-briefs/devtoolbox-cli.md +31 -0
- package/assets/workshop-bundle/content/project-briefs/doc-generator.md +31 -0
- package/assets/workshop-bundle/content/project-briefs/metrics-dashboard.md +31 -0
- package/assets/workshop-bundle/content/project-briefs/standup-bot.md +31 -0
- package/assets/workshop-bundle/content/style-examples.md +127 -0
- package/assets/workshop-bundle/content/style-guide.md +106 -0
- package/assets/workshop-bundle/content/talks/.gitkeep +0 -0
- package/assets/workshop-bundle/content/talks/codex-demo-script.md +43 -0
- package/assets/workshop-bundle/content/talks/context-is-king.md +42 -0
- package/assets/workshop-bundle/docs/harness-cli-foundation.md +112 -0
- package/assets/workshop-bundle/docs/learner-reference-gallery.md +82 -0
- package/assets/workshop-bundle/docs/learner-resource-kit.md +126 -0
- package/assets/workshop-bundle/docs/workshop-event-context-contract.md +123 -0
- package/assets/workshop-bundle/materials/participant-resource-kit.md +72 -0
- package/assets/workshop-bundle/workshop-blueprint/README.md +48 -0
- package/assets/workshop-bundle/workshop-blueprint/agenda.json +70 -0
- package/assets/workshop-bundle/workshop-blueprint/control-surfaces.md +101 -0
- package/assets/workshop-bundle/workshop-blueprint/day-structure.md +129 -0
- package/assets/workshop-bundle/workshop-blueprint/edit-boundaries.md +64 -0
- package/assets/workshop-bundle/workshop-blueprint/operator-guide.md +74 -0
- package/assets/workshop-bundle/workshop-blueprint/teaching-spine.md +134 -0
- package/assets/workshop-bundle/workshop-skill/.gitkeep +0 -0
- package/assets/workshop-bundle/workshop-skill/analyze-checklist.md +21 -0
- package/assets/workshop-bundle/workshop-skill/closing-skill.md +30 -0
- package/assets/workshop-bundle/workshop-skill/commands.md +44 -0
- package/assets/workshop-bundle/workshop-skill/facilitator.md +416 -0
- package/assets/workshop-bundle/workshop-skill/follow-up-package.md +35 -0
- package/assets/workshop-bundle/workshop-skill/install.md +58 -0
- package/assets/workshop-bundle/workshop-skill/recap.md +22 -0
- package/assets/workshop-bundle/workshop-skill/reference.md +80 -0
- package/assets/workshop-bundle/workshop-skill/setup.md +84 -0
- package/assets/workshop-bundle/workshop-skill/template-agents.md +35 -0
- package/package.json +8 -3
- package/src/client.js +3 -1
- package/src/run-cli.js +16 -9
- package/src/skill-install.js +98 -57
- package/src/workshop-bundle.js +233 -0
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# `harness` CLI Foundation
|
|
2
|
+
|
|
3
|
+
This document defines the deliberately small v1 scope for the facilitator-side `harness` CLI.
|
|
4
|
+
|
|
5
|
+
## Current Repo Status
|
|
6
|
+
|
|
7
|
+
Current implementation in this repo:
|
|
8
|
+
|
|
9
|
+
- lives in the repository `harness-cli/` package and ships publicly as `@harness-lab/cli`
|
|
10
|
+
- distributes a portable participant workshop skill bundle through `harness skill install`
|
|
11
|
+
- covers `auth login/logout/status` plus `workshop status/create-instance/update-instance/prepare/remove-instance/archive/phase set`
|
|
12
|
+
- targets the existing shared dashboard facilitator APIs
|
|
13
|
+
- is tested for browser/device auth, local-dev Basic Auth fallback, and cookie-backed Neon bootstrap fallback
|
|
14
|
+
- stores sessions in a local file under `HARNESS_CLI_HOME` or `~/.harness` by default
|
|
15
|
+
- supports macOS Keychain, Windows Credential Manager, or Linux Secret Service as explicit storage overrides
|
|
16
|
+
- exposes dashboard-side device auth routes plus a facilitator approval page at `/admin/device`
|
|
17
|
+
|
|
18
|
+
Current npm release posture:
|
|
19
|
+
|
|
20
|
+
- participant-facing npm publication is supported through an explicit release workflow
|
|
21
|
+
- routine development still happens from this repository
|
|
22
|
+
- broader live-runtime manual validation against a deployed dashboard remains part of the first-release checklist
|
|
23
|
+
|
|
24
|
+
## Why The CLI Exists
|
|
25
|
+
|
|
26
|
+
The facilitator skill and any other local tooling need a privileged auth path, but raw facilitator credentials and long-lived session state should not live inside arbitrary skill state.
|
|
27
|
+
|
|
28
|
+
The CLI creates a narrower trust boundary:
|
|
29
|
+
|
|
30
|
+
- browser or device-based facilitator login
|
|
31
|
+
- local session storage
|
|
32
|
+
- short operational commands over the same runtime APIs used by the dashboard
|
|
33
|
+
|
|
34
|
+
## V1 Scope
|
|
35
|
+
|
|
36
|
+
Required commands:
|
|
37
|
+
|
|
38
|
+
- `harness auth login`
|
|
39
|
+
- `harness auth logout`
|
|
40
|
+
- `harness auth status`
|
|
41
|
+
- `harness workshop status`
|
|
42
|
+
- `harness workshop create-instance`
|
|
43
|
+
- `harness workshop update-instance`
|
|
44
|
+
- `harness workshop archive`
|
|
45
|
+
- `harness workshop prepare`
|
|
46
|
+
- `harness workshop remove-instance`
|
|
47
|
+
- `harness workshop phase set <phase-id>`
|
|
48
|
+
|
|
49
|
+
The CLI may also expose a thin authenticated request wrapper for facilitator skills.
|
|
50
|
+
|
|
51
|
+
## V1 Non-Goals
|
|
52
|
+
|
|
53
|
+
- participant teaching logic beyond portable skill distribution and install guidance
|
|
54
|
+
- replacing dashboard UX
|
|
55
|
+
- storing reusable workshop blueprint content
|
|
56
|
+
- becoming a second API surface with different nouns
|
|
57
|
+
- automatic publish-back of runtime edits into the repo
|
|
58
|
+
|
|
59
|
+
## Auth Model
|
|
60
|
+
|
|
61
|
+
Preferred interactive path:
|
|
62
|
+
|
|
63
|
+
1. facilitator starts `harness auth login`
|
|
64
|
+
2. CLI opens browser or emits a device-code style flow
|
|
65
|
+
3. dashboard auth/backend completes facilitator identity verification
|
|
66
|
+
4. CLI stores the resulting session material in local session storage
|
|
67
|
+
|
|
68
|
+
The facilitator skill should call the CLI for privileged operations instead of storing raw auth/session material itself.
|
|
69
|
+
|
|
70
|
+
Control model:
|
|
71
|
+
|
|
72
|
+
- skill invokes CLI
|
|
73
|
+
- CLI invokes shared protected dashboard APIs
|
|
74
|
+
- APIs enforce authz, validation, idempotency, and audit logging
|
|
75
|
+
|
|
76
|
+
For the current facilitator lifecycle slice:
|
|
77
|
+
|
|
78
|
+
- `workshop status`, `create-instance`, `update-instance`, and `prepare` are brokered-session commands
|
|
79
|
+
- `workshop remove-instance` remains owner-only on the server
|
|
80
|
+
- facilitator `grant` and `revoke` remain a later step-up policy slice rather than part of this lifecycle command set
|
|
81
|
+
|
|
82
|
+
Current step-up posture:
|
|
83
|
+
|
|
84
|
+
- the existing CLI command set (`workshop status/archive/phase set`) may run on a valid brokered device session
|
|
85
|
+
- future higher-risk commands such as facilitator grant/revoke or destructive instance mutations should require a fresh browser approval window rather than silently reusing an older CLI session
|
|
86
|
+
|
|
87
|
+
## Session Storage Posture
|
|
88
|
+
|
|
89
|
+
Default storage backend:
|
|
90
|
+
|
|
91
|
+
- file-based storage under `HARNESS_CLI_HOME` or `~/.harness`
|
|
92
|
+
|
|
93
|
+
Optional storage backends:
|
|
94
|
+
|
|
95
|
+
- macOS Keychain
|
|
96
|
+
- Windows Credential Manager
|
|
97
|
+
- Linux Secret Service
|
|
98
|
+
|
|
99
|
+
The default should optimize for reliability and low-friction setup across facilitator machines. OS-native credential stores remain available through `HARNESS_SESSION_STORAGE` when a facilitator prefers them.
|
|
100
|
+
|
|
101
|
+
## Packaging Posture
|
|
102
|
+
|
|
103
|
+
V1 should optimize for cross-platform setup speed, not native-binary perfection.
|
|
104
|
+
|
|
105
|
+
Recommended posture:
|
|
106
|
+
|
|
107
|
+
- ship as a small Node-based CLI from this repository or its derived package
|
|
108
|
+
- support straightforward installation on macOS and Windows
|
|
109
|
+
- carry the portable public-safe workshop skill bundle needed for participant install
|
|
110
|
+
- keep the command surface stable enough that the facilitator skill can depend on it
|
|
111
|
+
|
|
112
|
+
If facilitator setup friction remains high, native single-file packaging can be evaluated later without changing the control model.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Learner Reference Gallery
|
|
2
|
+
|
|
3
|
+
Tohle je krátký seznam zdrojů pro účastníky po workshopu.
|
|
4
|
+
|
|
5
|
+
Pravidlo je jednoduché:
|
|
6
|
+
- nejdřív oficiální dokumentace
|
|
7
|
+
- potom několik silných veřejných repozitářů
|
|
8
|
+
- nakonec malý počet patternů přímo relevantních pro Harness Lab
|
|
9
|
+
|
|
10
|
+
Jakmile tato stránka začne připomínat „awesome list“, je moc dlouhá.
|
|
11
|
+
|
|
12
|
+
## Oficiální dokumentace
|
|
13
|
+
|
|
14
|
+
- [OpenAI Codex documentation](https://developers.openai.com/codex)
|
|
15
|
+
Použijte jako hlavní zdroj pro aktuální Codex workflows, skills, `AGENTS.md`, subagents a security guidance.
|
|
16
|
+
|
|
17
|
+
- [OpenAI Codex best practices](https://developers.openai.com/codex/learn/best-practices)
|
|
18
|
+
Nejlepší rychlý vstup pro to, jak Codex používat jako dlouhodobého spolupracovníka: kontext, `AGENTS.md`, review, verification, MCP a automatizace.
|
|
19
|
+
|
|
20
|
+
- [OpenAI Codex skills documentation](https://developers.openai.com/codex/skills)
|
|
21
|
+
Hodí se ve chvíli, kdy chcete z opakovaných promptů udělat znovupoužitelné repo-native skills.
|
|
22
|
+
|
|
23
|
+
- [OpenAI Codex plugins](https://developers.openai.com/codex/plugins)
|
|
24
|
+
Dobré pro pochopení, kdy v Codexu použít pluginy a marketplace místo samotných repo-native skills. Pro workshop je berte jako volitelný Codex akcelerátor, ne jako základní bootstrap.
|
|
25
|
+
|
|
26
|
+
- [OpenAI Codex build plugins](https://developers.openai.com/codex/plugins/build)
|
|
27
|
+
Hodí se maintainerům, když chtějí pochopit marketplace model, repo-local marketplace nebo bundling skills, app integrations a MCP serverů do jednoho Codex package.
|
|
28
|
+
|
|
29
|
+
- [OpenAI Codex workflows](https://developers.openai.com/codex/workflows)
|
|
30
|
+
Dobré pro převedení workshopových návyků do reálných projektových workflow.
|
|
31
|
+
|
|
32
|
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
|
|
33
|
+
Dobré pro pochopení, proč má být repo knowledge systémem záznamu a proč jsou plans, review a garbage collection součást engineering discipline, ne bonus navíc.
|
|
34
|
+
|
|
35
|
+
- [Next.js AI Coding Agents](https://nextjs.org/docs/app/guides/ai-agents)
|
|
36
|
+
Důležité hlavně pro Next.js projekty: ukazuje, proč mají agenti číst version-matched framework docs místo spoléhání na starší paměť modelu.
|
|
37
|
+
|
|
38
|
+
## Veřejné repozitáře
|
|
39
|
+
|
|
40
|
+
- [openai/codex](https://github.com/openai/codex)
|
|
41
|
+
Oficiální CLI repozitář a nejlepší kotva pro to, jak se samotný nástroj vyvíjí.
|
|
42
|
+
|
|
43
|
+
- [openai/skills](https://github.com/openai/skills)
|
|
44
|
+
Oficiální katalog skills a nejlepší reference pro to, jak vypadá Codex-native skill.
|
|
45
|
+
|
|
46
|
+
- [openai/codex-action](https://github.com/openai/codex-action)
|
|
47
|
+
Silný příklad úzké a bezpečné automatizace kolem Codexu v CI.
|
|
48
|
+
|
|
49
|
+
- [vercel-labs/skills](https://github.com/vercel-labs/skills)
|
|
50
|
+
Užitečné ve chvíli, kdy chcete skill packaging přenositelný napříč více coding agenty.
|
|
51
|
+
|
|
52
|
+
- [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)
|
|
53
|
+
Dobré příklady kvalitních a praktických skills, hlavně pro frontend a React práci.
|
|
54
|
+
|
|
55
|
+
## Volitelné workflow packs
|
|
56
|
+
|
|
57
|
+
- [EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin)
|
|
58
|
+
Silná volitelná volba pro lidi, kteří chtějí explicitní loop `brainstorm -> plan -> work -> review -> compound`. Repo dnes umí instalaci i pro Codex a pi, ale berte to jako akcelerátor nad workshop defaultem, ne jako nutný setup.
|
|
59
|
+
|
|
60
|
+
## Praktické patterny
|
|
61
|
+
|
|
62
|
+
- Začněte repo kontextem dřív, než začnete opakovat prompt.
|
|
63
|
+
V praxi: nejdřív přidejte `AGENTS.md`, build/test příkazy a konkrétní definici hotovo.
|
|
64
|
+
|
|
65
|
+
- Skills používejte pro opakované workflow, ne jako jednorázové chat makro.
|
|
66
|
+
Když se stejný task vrací napříč více sessions nebo repy, je to kandidát na skill.
|
|
67
|
+
|
|
68
|
+
- Pluginy a marketplace berte jako Codex-specific distribuční vrstvu, ne jako definici workshop metody.
|
|
69
|
+
Když něco učíme jako Harness Lab default, mělo by to dávat smysl i mimo Codex. Plugin má smysl tam, kde skutečně přidává Codex integrations nebo pohodlnější distribuci.
|
|
70
|
+
|
|
71
|
+
- Testy, tracer bullets a checklisty berte jako hranici důvěry.
|
|
72
|
+
Čím víc autonomie agent dostane, tím méně stačí „rychle jsem projel diff“.
|
|
73
|
+
|
|
74
|
+
- Participant-facing příklady držte menší než backstage systémy.
|
|
75
|
+
Dobrý learner artefakt je kopírovatelný a čitelný, ne vyčerpávající.
|
|
76
|
+
|
|
77
|
+
## Pravidlo čerstvosti
|
|
78
|
+
|
|
79
|
+
Tento seznam zrevidujte:
|
|
80
|
+
- před každým workshopovým během
|
|
81
|
+
- po větší změně Codex capabilities
|
|
82
|
+
- když doporučený repozitář zastará, začne být noisy nebo přestane být nejlepší ukázkou
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# Learner Resource Kit
|
|
2
|
+
|
|
3
|
+
Tato stránka definuje participant-facing resource kit pro Harness Lab.
|
|
4
|
+
|
|
5
|
+
Je to malá, kopírovatelná část repa, kterou si mají účastníci odnést, projít a znovu použít ve vlastních projektech.
|
|
6
|
+
|
|
7
|
+
## Základní pravidlo
|
|
8
|
+
|
|
9
|
+
Learner kit není celý backstage harness.
|
|
10
|
+
|
|
11
|
+
Má odpovídat na otázky:
|
|
12
|
+
- co si mám z workshopu zkopírovat do vlastního repa?
|
|
13
|
+
- co má agent udělat jako první?
|
|
14
|
+
- jak zařídit, aby práce přežila handoff?
|
|
15
|
+
- co musím ověřit, než výstupu uvěřím?
|
|
16
|
+
|
|
17
|
+
Výchozí participant pattern, který má learner kit posilovat, je:
|
|
18
|
+
- `workshop` pro orientaci
|
|
19
|
+
- `brainstorm` nebo `plan` před větším řezem
|
|
20
|
+
- `work` proti jednomu ověřitelnému cíli
|
|
21
|
+
- `review` před důvěrou
|
|
22
|
+
- `compound` a cleanup pro věci, které mají přežít session
|
|
23
|
+
|
|
24
|
+
## Jádro learner kitu
|
|
25
|
+
|
|
26
|
+
### 1. Workshop skill
|
|
27
|
+
|
|
28
|
+
Hlavní participant interface:
|
|
29
|
+
- [`SKILL.md`](../SKILL.md)
|
|
30
|
+
- [`workshop-skill/setup.md`](../workshop-skill/setup.md)
|
|
31
|
+
- [`workshop-skill/reference.md`](../workshop-skill/reference.md)
|
|
32
|
+
- [`workshop-skill/recap.md`](../workshop-skill/recap.md)
|
|
33
|
+
|
|
34
|
+
Proč sem patří:
|
|
35
|
+
- ukazuje, jak může participant-facing skill vést setup, workflow i ověřování v češtině
|
|
36
|
+
- je to reálné repo-native rozhraní, ne workshopový slide artefakt
|
|
37
|
+
|
|
38
|
+
### 2. `AGENTS.md` příklad
|
|
39
|
+
|
|
40
|
+
Výchozí starter:
|
|
41
|
+
- [`workshop-skill/template-agents.md`](../workshop-skill/template-agents.md)
|
|
42
|
+
|
|
43
|
+
Proč sem patří:
|
|
44
|
+
- je to nejmenší znovupoužitelný příklad trvalého kontextu v repu
|
|
45
|
+
- účastníci ho mohou upravit přímo pro vlastní projekt
|
|
46
|
+
|
|
47
|
+
### 3. Příklad pro verification / review
|
|
48
|
+
|
|
49
|
+
Výchozí checklist:
|
|
50
|
+
- [`workshop-skill/analyze-checklist.md`](../workshop-skill/analyze-checklist.md)
|
|
51
|
+
|
|
52
|
+
Proč sem patří:
|
|
53
|
+
- dává konkrétní standard pro otázku „dokáže odtud pokračovat další tým?“
|
|
54
|
+
- převádí kvalitu repa do checklistu, který jde opravdu projít
|
|
55
|
+
|
|
56
|
+
### 4. Challenge cards
|
|
57
|
+
|
|
58
|
+
Doporučený subset:
|
|
59
|
+
- [`content/challenge-cards/deck.md`](../content/challenge-cards/deck.md)
|
|
60
|
+
|
|
61
|
+
Použití:
|
|
62
|
+
- malé zásahy během workshopu
|
|
63
|
+
- nápověda, co zlepšit později v reálném repu
|
|
64
|
+
|
|
65
|
+
### 5. Follow-up package
|
|
66
|
+
|
|
67
|
+
Posílení po workshopu:
|
|
68
|
+
- [`workshop-skill/follow-up-package.md`](../workshop-skill/follow-up-package.md)
|
|
69
|
+
- [`materials/participant-resource-kit.md`](../materials/participant-resource-kit.md)
|
|
70
|
+
|
|
71
|
+
Proč sem patří:
|
|
72
|
+
- proměňuje workshop z jednodenní akce na opakovatelný impuls ke změně chování
|
|
73
|
+
- dává doslovný handout, který lze poslat nebo vytisknout bez dalšího vysvětlování
|
|
74
|
+
|
|
75
|
+
## Kdy který artefakt použít
|
|
76
|
+
|
|
77
|
+
### Během setupu
|
|
78
|
+
|
|
79
|
+
Použijte:
|
|
80
|
+
- [`workshop-skill/setup.md`](../workshop-skill/setup.md)
|
|
81
|
+
- [`workshop-skill/reference.md`](../workshop-skill/reference.md)
|
|
82
|
+
|
|
83
|
+
### Během Build Phase 1
|
|
84
|
+
|
|
85
|
+
Použijte:
|
|
86
|
+
- [`workshop-skill/template-agents.md`](../workshop-skill/template-agents.md)
|
|
87
|
+
- the `Context Engineering` cards in [`content/challenge-cards/deck.md`](../content/challenge-cards/deck.md)
|
|
88
|
+
|
|
89
|
+
### Během continuation shift
|
|
90
|
+
|
|
91
|
+
Použijte:
|
|
92
|
+
- [`workshop-skill/analyze-checklist.md`](../workshop-skill/analyze-checklist.md)
|
|
93
|
+
- the `Workflow` cards in [`content/challenge-cards/deck.md`](../content/challenge-cards/deck.md)
|
|
94
|
+
|
|
95
|
+
### Po workshopu
|
|
96
|
+
|
|
97
|
+
Použijte:
|
|
98
|
+
- [`workshop-skill/recap.md`](../workshop-skill/recap.md)
|
|
99
|
+
- [`workshop-skill/follow-up-package.md`](../workshop-skill/follow-up-package.md)
|
|
100
|
+
- [`materials/participant-resource-kit.md`](../materials/participant-resource-kit.md)
|
|
101
|
+
- [`learner-reference-gallery.md`](learner-reference-gallery.md)
|
|
102
|
+
|
|
103
|
+
## Co si odnést do reálného projektu
|
|
104
|
+
|
|
105
|
+
Účastníci by měli odejít s těmito konkrétními kroky:
|
|
106
|
+
|
|
107
|
+
1. Přidejte `AGENTS.md` s částmi:
|
|
108
|
+
- goal
|
|
109
|
+
- context
|
|
110
|
+
- constraints
|
|
111
|
+
- done when
|
|
112
|
+
2. Do `context` napište, co má agent číst jako první a které docs jsou source of truth.
|
|
113
|
+
3. Do `done when` napište konkrétní ověření a další safe move, když práce zůstane rozdělaná.
|
|
114
|
+
4. Přidejte build/test příkazy, které zvládne spustit další tým nebo agent bez ústního dovysvětlení.
|
|
115
|
+
5. Přidejte jeden review nebo handoff checklist.
|
|
116
|
+
6. Přesuňte jedno trvalé pravidlo z chatu do repa.
|
|
117
|
+
7. Před větší implementací použijte plan a po větší změně review nebo check.
|
|
118
|
+
8. Když už používáte externí workflow skill pack, napojte ho až nad tento základ místo toho, abyste jím nahrazovali repo-native kontext a verification.
|
|
119
|
+
|
|
120
|
+
## Co sem nepatří
|
|
121
|
+
|
|
122
|
+
Learner kit nemá obsahovat plný backstage operating detail, například:
|
|
123
|
+
- workshop-instance runbooky
|
|
124
|
+
- privátní runtime architekturu a operace
|
|
125
|
+
- facilitator-only monitoring nebo control postupy
|
|
126
|
+
- maintainer-level deployment a security postupy, pokud se zrovna neučí explicitně jako participant skill
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Workshop Event Context Contract
|
|
2
|
+
|
|
3
|
+
This document defines the day-one contract for participant event access across the dashboard and `workshop-skill/`.
|
|
4
|
+
|
|
5
|
+
## Auth States
|
|
6
|
+
|
|
7
|
+
### 1. Public mode
|
|
8
|
+
|
|
9
|
+
Available without event login:
|
|
10
|
+
- public participant dashboard surface
|
|
11
|
+
- public-safe dashboard content
|
|
12
|
+
- local/fallback `workshop-skill` behavior
|
|
13
|
+
- setup, reference, and bundled project brief content
|
|
14
|
+
|
|
15
|
+
Not available:
|
|
16
|
+
- real event-private participant data
|
|
17
|
+
- team repo registry
|
|
18
|
+
- live checkpoint state
|
|
19
|
+
|
|
20
|
+
### 2. Participant-authenticated mode
|
|
21
|
+
|
|
22
|
+
Unlocked by redeeming the shared event code into a short-lived participant session.
|
|
23
|
+
|
|
24
|
+
Available:
|
|
25
|
+
- authenticated core bundle
|
|
26
|
+
- on-demand participant team/runtime lookups
|
|
27
|
+
|
|
28
|
+
### 3. Facilitator mode
|
|
29
|
+
|
|
30
|
+
Separate auth path.
|
|
31
|
+
|
|
32
|
+
Available:
|
|
33
|
+
- admin surface
|
|
34
|
+
- write operations
|
|
35
|
+
- facilitator-only views and monitoring
|
|
36
|
+
- facilitator skill commands via the CLI-backed auth path
|
|
37
|
+
|
|
38
|
+
## Authenticated Core Bundle
|
|
39
|
+
|
|
40
|
+
Day-one shape:
|
|
41
|
+
|
|
42
|
+
- `event.title`
|
|
43
|
+
- `event.subtitle`
|
|
44
|
+
- `event.currentPhaseLabel`
|
|
45
|
+
- `event.dateRange`
|
|
46
|
+
- `event.city`
|
|
47
|
+
- `agenda`
|
|
48
|
+
- `briefs`
|
|
49
|
+
- `challenges`
|
|
50
|
+
- `keyLinks`
|
|
51
|
+
- `announcements`
|
|
52
|
+
|
|
53
|
+
Design rule:
|
|
54
|
+
- small enough to fetch immediately after login
|
|
55
|
+
- rich enough to make `/workshop` and the participant dashboard feel live
|
|
56
|
+
|
|
57
|
+
## On-Demand Participant Lookups
|
|
58
|
+
|
|
59
|
+
Fetched only when requested:
|
|
60
|
+
|
|
61
|
+
- `teams[].id`
|
|
62
|
+
- `teams[].name`
|
|
63
|
+
- `teams[].city`
|
|
64
|
+
- `teams[].repoUrl`
|
|
65
|
+
- `teams[].checkpoint`
|
|
66
|
+
|
|
67
|
+
These remain outside the core bundle because they are more privacy-sensitive and more volatile.
|
|
68
|
+
|
|
69
|
+
## API Endpoints
|
|
70
|
+
|
|
71
|
+
### Event access
|
|
72
|
+
|
|
73
|
+
- `POST /api/event-access/redeem`
|
|
74
|
+
- `POST /api/event-access/logout`
|
|
75
|
+
|
|
76
|
+
### Participant event context
|
|
77
|
+
|
|
78
|
+
- `GET /api/event-context/core`
|
|
79
|
+
- `GET /api/event-context/teams`
|
|
80
|
+
|
|
81
|
+
### Existing facilitator routes
|
|
82
|
+
|
|
83
|
+
Current admin/facilitator write routes remain under existing admin protection and must not be unlocked by participant auth.
|
|
84
|
+
|
|
85
|
+
## Skill Command Mapping
|
|
86
|
+
|
|
87
|
+
| Command | Scope | Notes |
|
|
88
|
+
|---------|-------|-------|
|
|
89
|
+
| `/workshop` | Public first, authenticated when available | Must state clearly whether it is using fallback/public-only data or live event context |
|
|
90
|
+
| `/workshop login` | Participant-auth bootstrap | Redeems the shared event code into a short-lived participant session |
|
|
91
|
+
| `/workshop logout` | Participant-auth teardown | Clears the active participant session |
|
|
92
|
+
| `/workshop setup` | Public | Always available |
|
|
93
|
+
| `/workshop brief` | Public first, authenticated when available | Public brief content stays available; event-specific assignment can be layered later |
|
|
94
|
+
| `/workshop challenges` | Public first, authenticated when available | Public deck stays available; live completion context can be layered later |
|
|
95
|
+
| `/workshop team` | Participant-authenticated | Repo URLs and live checkpoint state are not public by default |
|
|
96
|
+
| `/workshop help` | Public first, authenticated when available | Coaching stays useful in fallback mode |
|
|
97
|
+
| `/workshop reference` | Public | Always available |
|
|
98
|
+
| `/workshop analyze` | Public/local | Works against the participant repo even without live event access |
|
|
99
|
+
|
|
100
|
+
## Error States
|
|
101
|
+
|
|
102
|
+
- `invalid_code`
|
|
103
|
+
- `expired_code`
|
|
104
|
+
- `expired_session`
|
|
105
|
+
- `participant event access required`
|
|
106
|
+
- `fallback mode`
|
|
107
|
+
|
|
108
|
+
## Session Transport Rules
|
|
109
|
+
|
|
110
|
+
- dashboard participant sessions are stored in a server-issued HTTP-only cookie
|
|
111
|
+
- skill-side session persistence should stay minimal and prefer renewable short-lived tokens over long-lived bearer state
|
|
112
|
+
- the event code must not be reused as the live bearer credential after redemption
|
|
113
|
+
- facilitator skill auth/session handling should live in the `harness` CLI, not in arbitrary skill state
|
|
114
|
+
|
|
115
|
+
## Logging Expectations
|
|
116
|
+
|
|
117
|
+
The private workshop-instance layer should log at least:
|
|
118
|
+
|
|
119
|
+
- redemption attempts
|
|
120
|
+
- successful session creation
|
|
121
|
+
- session expiry or invalidation
|
|
122
|
+
- failed protected lookups
|
|
123
|
+
- event-code rotation events
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Participant Resource Kit
|
|
2
|
+
|
|
3
|
+
Krátká sada artefaktů, které si můžete odnést z Harness Lab do vlastního projektu.
|
|
4
|
+
|
|
5
|
+
## 1. Začněte `AGENTS.md`
|
|
6
|
+
|
|
7
|
+
Použijte tento základ:
|
|
8
|
+
- `goal`
|
|
9
|
+
- `context`
|
|
10
|
+
- `constraints`
|
|
11
|
+
- `done when`
|
|
12
|
+
|
|
13
|
+
Výchozí šablona:
|
|
14
|
+
- [`workshop-skill/template-agents.md`](../workshop-skill/template-agents.md)
|
|
15
|
+
|
|
16
|
+
## 2. Přidejte jeden zdroj důvěry
|
|
17
|
+
|
|
18
|
+
Vyberte si alespoň jeden:
|
|
19
|
+
- build/test příkazy
|
|
20
|
+
- RED test
|
|
21
|
+
- tracer bullet
|
|
22
|
+
- review checklist
|
|
23
|
+
|
|
24
|
+
Když agent dělá větší kus práce, nestačí „rychle jsem to projel očima“.
|
|
25
|
+
|
|
26
|
+
Checklist pro handoff:
|
|
27
|
+
- [`workshop-skill/analyze-checklist.md`](../workshop-skill/analyze-checklist.md)
|
|
28
|
+
|
|
29
|
+
## 3. Používejte malý workflow, ne chaos
|
|
30
|
+
|
|
31
|
+
Doporučený základ:
|
|
32
|
+
- `workshop` pro orientaci a další safe move
|
|
33
|
+
- `/brainstorm`, když ještě není jasný scope nebo první slice
|
|
34
|
+
- `/plan` před větší implementací
|
|
35
|
+
- `/work` nebo jiný úzký implementační loop, když už víte co stavíte
|
|
36
|
+
- test nebo jiný executable check před důležitou změnou
|
|
37
|
+
- `/review` po větším kusu práce
|
|
38
|
+
- `/compound` nebo krátká repo-native poznámka, když objev udělá další práci levnější
|
|
39
|
+
- malý cleanup průběžně: build/test příkazy, omezení a handoff poznámky přesouvejte z chatu do repa
|
|
40
|
+
|
|
41
|
+
## 4. Přesuňte jedno pravidlo z chatu do repa
|
|
42
|
+
|
|
43
|
+
Typické kandidáty:
|
|
44
|
+
- build/test příkazy
|
|
45
|
+
- bezpečnostní omezení
|
|
46
|
+
- definice hotovo
|
|
47
|
+
- pravidlo pro handoff
|
|
48
|
+
|
|
49
|
+
## 5. Pro UI práci držte bezpečný postup
|
|
50
|
+
|
|
51
|
+
Výchozí pattern:
|
|
52
|
+
- `agent exploration`
|
|
53
|
+
- `Playwright regression`
|
|
54
|
+
- `human review`
|
|
55
|
+
|
|
56
|
+
Nenechávejte model jako default ovládat váš běžný přihlášený browser bez sandboxu a kontroly.
|
|
57
|
+
|
|
58
|
+
## 6. Co si projít po workshopu
|
|
59
|
+
|
|
60
|
+
- [`workshop-skill/reference.md`](../workshop-skill/reference.md)
|
|
61
|
+
- [`workshop-skill/recap.md`](../workshop-skill/recap.md)
|
|
62
|
+
- [`docs/learner-reference-gallery.md`](../docs/learner-reference-gallery.md)
|
|
63
|
+
|
|
64
|
+
Poznámka:
|
|
65
|
+
- `workshop` skill je garantovaný workshop default
|
|
66
|
+
- další workflow skills a veřejné toolkity berte jako volitelné akcelerátory, ne povinný setup
|
|
67
|
+
|
|
68
|
+
## Výzva na příští týden
|
|
69
|
+
|
|
70
|
+
1. Přidejte `AGENTS.md` do jednoho reálného projektu.
|
|
71
|
+
2. Přesuňte jedno trvalé pravidlo z promptu do repa.
|
|
72
|
+
3. Přidejte jeden review nebo handoff checklist.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Workshop Blueprint
|
|
2
|
+
|
|
3
|
+
This folder is the canonical public definition of how Harness Lab works.
|
|
4
|
+
|
|
5
|
+
Use it for the reusable workshop method:
|
|
6
|
+
|
|
7
|
+
- what the workshop is trying to teach
|
|
8
|
+
- how the day is structured
|
|
9
|
+
- what facilitators operate
|
|
10
|
+
- what participants use
|
|
11
|
+
- what is editable in the public repo versus only in the private runtime layer
|
|
12
|
+
|
|
13
|
+
Do not use this folder for live event state. Real dates, rooms, rosters, checkpoint data, monitoring output, and facilitator-only operations belong in the private workshop-instance layer.
|
|
14
|
+
|
|
15
|
+
## Recommended Reading Order
|
|
16
|
+
|
|
17
|
+
1. [`day-structure.md`](day-structure.md)
|
|
18
|
+
2. [`teaching-spine.md`](teaching-spine.md)
|
|
19
|
+
3. [`operator-guide.md`](operator-guide.md)
|
|
20
|
+
4. [`control-surfaces.md`](control-surfaces.md)
|
|
21
|
+
5. [`edit-boundaries.md`](edit-boundaries.md)
|
|
22
|
+
6. [`agenda.json`](agenda.json)
|
|
23
|
+
|
|
24
|
+
## Blueprint Contents
|
|
25
|
+
|
|
26
|
+
### Human-readable guidance
|
|
27
|
+
|
|
28
|
+
- [`day-structure.md`](day-structure.md)
|
|
29
|
+
Explains the workshop arc, phase goals, and what should survive handoff.
|
|
30
|
+
- [`teaching-spine.md`](teaching-spine.md)
|
|
31
|
+
Defines the habits, facilitator messages, and participant defaults the workshop should install.
|
|
32
|
+
- [`operator-guide.md`](operator-guide.md)
|
|
33
|
+
Explains how a facilitator prepares, runs, and closes a workshop.
|
|
34
|
+
- [`control-surfaces.md`](control-surfaces.md)
|
|
35
|
+
Defines participant surface, facilitator dashboard, facilitator skill, and the `harness` CLI as equal clients of one runtime model.
|
|
36
|
+
- [`edit-boundaries.md`](edit-boundaries.md)
|
|
37
|
+
Explains what changes in the public repo, what changes only in runtime, and how learnings are published back deliberately.
|
|
38
|
+
|
|
39
|
+
### Structured data
|
|
40
|
+
|
|
41
|
+
- [`agenda.json`](agenda.json)
|
|
42
|
+
Canonical reusable agenda and workshop metadata for blueprint import.
|
|
43
|
+
|
|
44
|
+
## Related Runtime Documents
|
|
45
|
+
|
|
46
|
+
- [`harness-cli-foundation.md`](../docs/harness-cli-foundation.md)
|
|
47
|
+
|
|
48
|
+
The deeper runtime and maintainer docs such as blueprint import, publish-back flow, and workshop-instance runbooks remain part of the source repository and maintainer path. They are intentionally not part of the portable participant bundle.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 1,
|
|
3
|
+
"blueprintId": "harness-lab-core-day",
|
|
4
|
+
"title": "Harness Lab",
|
|
5
|
+
"subtitle": "Workshop operating system pro práci s AI agenty",
|
|
6
|
+
"principles": [
|
|
7
|
+
"Mapa před pohybem",
|
|
8
|
+
"Ověření je hranice důvěry",
|
|
9
|
+
"Pište tak, aby další tým mohl pokračovat"
|
|
10
|
+
],
|
|
11
|
+
"phases": [
|
|
12
|
+
{
|
|
13
|
+
"id": "opening",
|
|
14
|
+
"order": 1,
|
|
15
|
+
"label": "Úvod a naladění",
|
|
16
|
+
"startTime": "09:10",
|
|
17
|
+
"kind": "shared",
|
|
18
|
+
"goal": "Rámec dne: nejde o promptování, ale o repo a workflow, které přežijí handoff."
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
"id": "talk",
|
|
22
|
+
"order": 2,
|
|
23
|
+
"label": "Context is King",
|
|
24
|
+
"startTime": "09:40",
|
|
25
|
+
"kind": "shared",
|
|
26
|
+
"goal": "Krátký talk a porovnání přístupů. Krátká mapa v repu je silnější než prompt blob."
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"id": "build-1",
|
|
30
|
+
"order": 3,
|
|
31
|
+
"label": "Build Phase 1",
|
|
32
|
+
"startTime": "10:30",
|
|
33
|
+
"kind": "team",
|
|
34
|
+
"goal": "Nejdřív udělejte z repa operating surface: krátké AGENTS.md, plán, build/test flow, první ověření a první reviewed output."
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
"id": "rotation",
|
|
38
|
+
"order": 4,
|
|
39
|
+
"label": "Rotace týmů",
|
|
40
|
+
"startTime": "13:30",
|
|
41
|
+
"kind": "team",
|
|
42
|
+
"goal": "Plný přesun lidí mezi stoly. Nejdřív čtěte a napište diagnózu, až pak měňte kód."
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
"id": "reveal",
|
|
46
|
+
"order": 5,
|
|
47
|
+
"label": "Reveal a reflexe",
|
|
48
|
+
"startTime": "15:45",
|
|
49
|
+
"kind": "shared",
|
|
50
|
+
"goal": "Co pomohlo pokračovat, co chybělo, a kterou bolest teď proměníme v lepší harness."
|
|
51
|
+
}
|
|
52
|
+
],
|
|
53
|
+
"runtimeImport": {
|
|
54
|
+
"copiedIntoInstance": [
|
|
55
|
+
"title",
|
|
56
|
+
"subtitle",
|
|
57
|
+
"phases"
|
|
58
|
+
],
|
|
59
|
+
"instanceLocalOnly": [
|
|
60
|
+
"currentPhaseId",
|
|
61
|
+
"continuationRevealed",
|
|
62
|
+
"realDate",
|
|
63
|
+
"venue",
|
|
64
|
+
"room",
|
|
65
|
+
"teamRegistry",
|
|
66
|
+
"checkpoints",
|
|
67
|
+
"monitoringSnapshots"
|
|
68
|
+
]
|
|
69
|
+
}
|
|
70
|
+
}
|