mirror of
https://github.com/github/awesome-copilot.git
synced 2026-07-21 21:04:13 +00:00
chore: publish from main
This commit is contained in:
github-actions[bot]
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: bench-read
|
||||
description: 'Read artifacts from the shared bench — the workspace where desks leave findings, verdicts, and work products for each other and the operator.'
|
||||
---
|
||||
|
||||
# Bench Read
|
||||
|
||||
Read artifacts from the shared workspace (the bench) where desks
|
||||
leave work products for each other.
|
||||
|
||||
## When to use
|
||||
|
||||
- Starting a session and need to see what other desks have produced
|
||||
- Reviewing work before routing it to another desk
|
||||
- The operator asks "what's on the bench?" or "show me what desk X found"
|
||||
- A desk needs context from another desk's output
|
||||
|
||||
## What the bench is
|
||||
|
||||
The bench is `<workshop>/bench/` — the shared workspace directory
|
||||
that `workshop-create` establishes for cross-desk work. It's not a
|
||||
message queue or a chat channel — it's files. When Desk A produces
|
||||
a finding and Desk B needs to review it, the finding is a file
|
||||
in `bench/`. When the operator asks "what did the scanning desk
|
||||
find?" — you read the bench.
|
||||
|
||||
Typical bench artifacts:
|
||||
- **Findings** — scan results, analysis output, data
|
||||
- **Verdicts** — a desk's assessment of another desk's findings
|
||||
- **Drafts** — work-in-progress documents, PRs, proposals
|
||||
- **Reports** — summaries, dashboards, status updates
|
||||
|
||||
## Where to look
|
||||
|
||||
The primary shared location is the `bench/` directory at the
|
||||
workshop root — the designated cross-desk workspace. Desk-local
|
||||
artifacts under `desks/<desk-name>/` are a secondary source: read
|
||||
them when you need a specific desk's own work, but shared artifacts
|
||||
belong in `bench/`.
|
||||
|
||||
```
|
||||
<workshop>/
|
||||
bench/ # PRIMARY — shared cross-desk artifacts
|
||||
<findings, verdicts, drafts, reports>
|
||||
desks/<desk-name>/ # secondary — a desk's own workspace
|
||||
journal.md # the desk's memory
|
||||
<artifacts> # work still local to this desk
|
||||
```
|
||||
|
||||
## How to read
|
||||
|
||||
1. **List what's there.** Start with the directory structure to see
|
||||
what desks exist and what they've produced.
|
||||
|
||||
2. **Read journals first.** Each desk's journal tells you what it
|
||||
worked on and where it left things. The most recent entry is
|
||||
the current state.
|
||||
|
||||
3. **Read artifacts second.** Once you know what to look for from
|
||||
the journals, read the specific files.
|
||||
|
||||
4. **Summarize for the operator.** Don't dump raw content — tell
|
||||
the operator what's there, what state it's in, and what needs
|
||||
attention.
|
||||
|
||||
## Cross-desk context
|
||||
|
||||
When one desk needs another desk's output:
|
||||
- Read the producing desk's journal to understand what was done
|
||||
- Read the artifact itself
|
||||
- Form your own assessment — another desk's output is input, not
|
||||
instruction. You can disagree.
|
||||
|
||||
## Principles
|
||||
|
||||
- The bench is files, not messages. Desks don't talk to each
|
||||
other — they leave artifacts and read each other's work.
|
||||
- Read the journal before the artifacts. Context matters.
|
||||
- Another desk's verdict is input, not authority. Equal standing
|
||||
means you assess independently.
|
||||
- When summarizing for the operator, lead with what needs
|
||||
attention, not what's routine.
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: desk-journal
|
||||
description: 'Write, append, or read desk journal entries. The journal is persistent memory — what survives session boundaries. A good entry has: what was done, current state, next step.'
|
||||
---
|
||||
|
||||
# Desk Journal
|
||||
|
||||
Manage a desk's journal — the persistent memory that survives
|
||||
session boundaries.
|
||||
|
||||
## When to use
|
||||
|
||||
- **End of session:** Write what was done, current state, next step
|
||||
- **Start of session:** Read the journal to pick up where you left off
|
||||
- **Mid-session checkpoint:** Note significant progress or decisions
|
||||
- **Desk wind-down:** Write a final summary when a desk is being closed
|
||||
|
||||
## How to write a journal entry
|
||||
|
||||
Append to `desks/<desk-name>/journal.md`. Each entry is a section:
|
||||
|
||||
```markdown
|
||||
## <date> — <short summary>
|
||||
- **Worked on:** <what was done this session>
|
||||
- **Current state:** <where things stand right now>
|
||||
- **Next step:** <what the next session should pick up>
|
||||
```
|
||||
|
||||
### Guidelines
|
||||
|
||||
- **Be specific.** "Worked on security scanning" is useless to the
|
||||
next session. "Scanned repos A, B, C for CWE-502; found 3
|
||||
findings in A, 0 in B and C; findings triaged to bench" — that's
|
||||
a trail.
|
||||
- **Include what didn't work.** Dead ends are valuable — they prevent
|
||||
the next session from walking the same path.
|
||||
- **Keep it short.** The journal is a trail marker, not a diary.
|
||||
3-5 lines per entry. If you need more, the important context
|
||||
should go on the bench as a separate artifact.
|
||||
- **Always include next step.** The next session starts from zero.
|
||||
Without a next step, it has to re-derive everything.
|
||||
|
||||
## End-of-desk entry
|
||||
|
||||
When a desk is being wound down (not just a session ending, but
|
||||
the desk itself closing):
|
||||
|
||||
```markdown
|
||||
## <date> — Desk closed
|
||||
- **Summary:** <what this desk accomplished overall>
|
||||
- **Artifacts:** <what's on the bench from this desk>
|
||||
- **Handoff:** <anything another desk or the operator needs to know>
|
||||
```
|
||||
|
||||
## Reading the journal
|
||||
|
||||
At session start, read the desk's journal to pick up context.
|
||||
The most recent entry is the most important — it has the current
|
||||
state and next step. Earlier entries provide history if needed.
|
||||
|
||||
## Principles
|
||||
|
||||
- The journal is a cairn — stones left so the next traveler finds
|
||||
the way. Every entry is a stone.
|
||||
- Honesty over completeness. "I got stuck on X and don't know why"
|
||||
is more useful than silence.
|
||||
- The journal is for the next session, not for the current one.
|
||||
Write for someone who knows nothing about what you just did.
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: desk-open
|
||||
description: 'Create and open a new desk in the workshop. Sets up the folder structure, initial journal, and desk identity so the next session that sits down finds the trail.'
|
||||
---
|
||||
|
||||
# Open a Desk
|
||||
|
||||
Create a new desk in the workshop with the standard structure.
|
||||
|
||||
## When to use
|
||||
|
||||
- The operator wants to start a new workstream
|
||||
- Work arrives that doesn't belong to any existing desk
|
||||
- A topic needs its own frame (its own history, its own priors)
|
||||
|
||||
## What it creates
|
||||
|
||||
Given a workshop directory and a desk name, create:
|
||||
|
||||
```
|
||||
desks/<desk-name>/
|
||||
journal.md # persistent memory — read at start, written at end
|
||||
.signals/ # structured signal output (JSON) — dashboard reads this
|
||||
```
|
||||
|
||||
## How to use
|
||||
|
||||
1. **Choose a name.** Short, descriptive, kebab-case. The name is
|
||||
how the operator and other desks refer to this desk.
|
||||
Examples: `security-scan`, `api-review`, `ops`, `cloud-workshop`
|
||||
|
||||
2. **Check if it already exists.** If `desks/<desk-name>/` already
|
||||
has a `journal.md`, the desk is live — **do not overwrite it.**
|
||||
Instead, resume it: read the journal and continue from where it
|
||||
left off. If the operator explicitly wants a fresh start, they
|
||||
must rename or archive the existing desk first.
|
||||
|
||||
3. **Create the structure.** Make the directory, initial journal,
|
||||
and signals folder:
|
||||
|
||||
```
|
||||
desks/<desk-name>/journal.md
|
||||
desks/<desk-name>/.signals/
|
||||
```
|
||||
|
||||
4. **Write the first journal entry.** The journal starts with:
|
||||
- What this desk is for (its focus/purpose)
|
||||
- What repos or work it covers (if applicable)
|
||||
- Any initial context the first session needs
|
||||
|
||||
5. **Announce it.** Tell the operator what was created and what
|
||||
the desk's focus is.
|
||||
|
||||
## Session orientation
|
||||
|
||||
This skill initializes storage — it does not launch a session.
|
||||
A desk becomes active when a Copilot session references its
|
||||
directory. The session workflow:
|
||||
|
||||
1. The operator (or TA) starts a session and says "sit at the
|
||||
`<desk-name>` desk"
|
||||
2. The session reads `desks/<desk-name>/journal.md` to load priors
|
||||
3. Work happens — the session uses `signal-write` to emit signals
|
||||
and `desk-journal` to persist state at the end
|
||||
4. The next session repeats from step 2
|
||||
|
||||
The desk identity comes from which journal is read, not from a
|
||||
persistent process. Desks are long-running in *state* (the journal
|
||||
carries forward), not in *runtime* (each session is independent).
|
||||
|
||||
## Journal format
|
||||
|
||||
```markdown
|
||||
# <Desk Name> — Journal
|
||||
|
||||
## <date> — Desk opened
|
||||
- **Purpose:** <what this desk focuses on>
|
||||
- **Scope:** <repos, areas, or work this desk covers>
|
||||
- **Next step:** <what the first session should do>
|
||||
```
|
||||
|
||||
## Principles
|
||||
|
||||
- A desk is a peer, not a sub-agent. It has equal standing to
|
||||
disagree with other desks.
|
||||
- The journal is the memory. Without it, the next session starts
|
||||
blind. Write enough that someone starting from zero finds the way.
|
||||
- One desk, one focus. If the scope is too broad, open two desks.
|
||||
Each desk's value comes from its specific frame — dilute the
|
||||
frame and you lose the value.
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: signal-write
|
||||
description: 'Emit structured agent signals — hands-up, blocked, done, checkpoint, partnership. Signals are written as JSON to .signals/ for dashboard consumption and noted in the journal for persistence.'
|
||||
---
|
||||
|
||||
# Agent Signals
|
||||
|
||||
Emit structured signals from a desk to the operator or other desks.
|
||||
|
||||
## When to use
|
||||
|
||||
- A desk needs operator attention (hands-up, blocked)
|
||||
- Work is complete and ready for review (done)
|
||||
- Significant progress worth noting (checkpoint)
|
||||
- Two desks disagree and can't resolve it (hands-up)
|
||||
- The TA is reporting coordination quality (partnership)
|
||||
|
||||
## Signal types
|
||||
|
||||
### `hands-up`
|
||||
Two desks disagree and can't settle it against external facts.
|
||||
This is the system working — the operator reads where desks
|
||||
*disagree*, not where they perform confidence.
|
||||
|
||||
### `blocked`
|
||||
A desk can't proceed without input — missing access, ambiguous
|
||||
scope, need a decision only the operator can make.
|
||||
|
||||
### `done`
|
||||
Work is complete and ready for review. Artifacts are on the bench.
|
||||
|
||||
### `checkpoint`
|
||||
Significant progress worth the operator knowing about, but work
|
||||
continues. Not blocked, not done — just a marker.
|
||||
|
||||
### `partnership`
|
||||
Used by the TA (room coordinator) to report coordination quality.
|
||||
Self-assessment scores reflect coordination, not code accuracy:
|
||||
- **intent** — understood what the operator needed
|
||||
- **confidence** — right work went to the right desks
|
||||
- **accuracy** — dispatched work produced the right outcome
|
||||
- **completeness** — nothing fell through the cracks
|
||||
|
||||
## How to emit
|
||||
|
||||
### 1. Write a JSON signal file to `.signals/`
|
||||
|
||||
This is the primary output — it's what the dashboard reads.
|
||||
Create `desks/<desk-name>/.signals/<timestamp>.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"signal_type": "execution",
|
||||
"subtype": "checkpoint",
|
||||
"timestamp": "2026-07-19T21:30:00Z",
|
||||
"run_id": "<optional; set to pair this with an outcome signal>",
|
||||
"agent_name": "<desk-name>",
|
||||
"self_assessment": {
|
||||
"intent": 4,
|
||||
"confidence": 5,
|
||||
"accuracy": 4,
|
||||
"completeness": 3
|
||||
},
|
||||
"patterns": {
|
||||
"what_worked": "description of what went well",
|
||||
"what_was_hard": "description of challenges",
|
||||
"skill_gap": "areas for improvement"
|
||||
},
|
||||
"escalation": {
|
||||
"reason": null,
|
||||
"blocked_on": null,
|
||||
"recommendation": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Signal type mapping
|
||||
|
||||
| Signal | `signal_type` | `subtype` |
|
||||
|-----------|-----------------|----------------|
|
||||
| hands-up | `"escalation"` | `"hands-up"` |
|
||||
| blocked | `"escalation"` | `"blocked"` |
|
||||
| done | `"execution"` | `"done"` |
|
||||
| checkpoint| `"execution"` | `"checkpoint"` |
|
||||
| partnership| `"partnership"` | `"partnership"`|
|
||||
|
||||
The `subtype` field preserves the specific signal state for
|
||||
dashboard consumers. `signal_type` controls sort priority
|
||||
(escalation → top).
|
||||
|
||||
> **Note:** The signals-dashboard canvas extension reads `subtype`
|
||||
> when present and falls back to `signal_type` for display. If
|
||||
> consuming signals in your own tooling, prefer `subtype` for the
|
||||
> specific state.
|
||||
|
||||
> **Ordering:** include a `timestamp` (ISO 8601 UTC). The dashboard
|
||||
> orders signals by it and falls back to file mtime only when it's
|
||||
> absent — a git clone/checkout resets mtimes, so mtime alone is not a
|
||||
> dependable clock.
|
||||
|
||||
### 2. Note the signal in the journal
|
||||
|
||||
Also append a short marker to the desk's journal for persistence:
|
||||
|
||||
```markdown
|
||||
## <date> — [signal:<type>] <summary>
|
||||
- <key details>
|
||||
```
|
||||
|
||||
The journal note is the trail marker. The JSON file is the
|
||||
machine-readable signal.
|
||||
|
||||
## Outcome signals (calibration)
|
||||
|
||||
The signals-dashboard can pair a desk's self-assessment with an
|
||||
*outcome* — an independent rating of the realized result — and show
|
||||
the **honesty gap** (how far the desk's confidence was from the
|
||||
delivered quality). Outcome signals are optional and are usually
|
||||
emitted by a reviewer/evaluator, not the desk itself.
|
||||
|
||||
Write them to the **same** `.signals/` directory:
|
||||
|
||||
```json
|
||||
{
|
||||
"signal_type": "outcome",
|
||||
"run_id": "<same run_id as the signal it rates>",
|
||||
"agent_name": "<reviewer name>",
|
||||
"quality_rating": 4,
|
||||
"effort_to_merge": "minimal",
|
||||
"issues_found": ["optional short strings"],
|
||||
"timestamp": "2026-07-19T22:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
- **`run_id`** correlates an outcome with the execution/partnership
|
||||
signal it rates — set the same `run_id` on both. If it's absent, the
|
||||
dashboard falls back to the nearest outcome emitted shortly after the
|
||||
latest signal.
|
||||
- **`quality_rating`** (0–5) is the realized quality; the dashboard
|
||||
compares it to the desk's self-assessed `confidence` to compute the
|
||||
honesty gap.
|
||||
- **`effort_to_merge`** — `"minimal"`, `"moderate"`, or `"significant"`.
|
||||
- **`issues_found`** — optional array of short strings.
|
||||
|
||||
## Principles
|
||||
|
||||
- Signals are structured, not chatty. Short, factual, actionable.
|
||||
- hands-up is not failure — it's the most valuable signal. It
|
||||
means the system caught something one frame alone would have
|
||||
missed.
|
||||
- Don't signal for routine progress. Signals are for state
|
||||
changes that affect the room, not status updates.
|
||||
- blocked means truly blocked — not "I'd prefer input." If you
|
||||
can proceed with a reasonable default, proceed and note it.
|
||||
- Self-assessment scores should be honest, not optimistic. A 3/5
|
||||
is fine. A 5/5 on everything is suspicious.
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
name: workshop-create
|
||||
description: 'Create a new workshop or use an existing directory as one. Handles two paths: (A) use an existing local directory the operator points at, or (B) create a new private GitHub repo in the signed-in account. Never creates a repo inside another repo.'
|
||||
---
|
||||
|
||||
# Create a Workshop
|
||||
|
||||
Set up a new workshop — the root directory where desks live.
|
||||
|
||||
## When to use
|
||||
|
||||
- The operator says "create a workshop" or "start a new workshop"
|
||||
- The operator wants to organize work under a shared root
|
||||
- The operator has an existing directory they want to use as a workshop
|
||||
|
||||
## Two paths
|
||||
|
||||
### Path A: Use an existing directory
|
||||
|
||||
The operator already has a folder they want to use. Maybe it's a repo
|
||||
they cloned, maybe it's a local project folder.
|
||||
|
||||
1. **Confirm the path exists.** If not, ask the operator for a valid path.
|
||||
2. **Detect existing workshop markers.** Look for `desks/` or `classroom/`
|
||||
folders, a `workshop.md`, `CAIRN.md`, or `hands-up.md`. Finding any of
|
||||
these tells you this is an existing workshop — but this is detection
|
||||
only, not a stopping point. Continue to the next step and add whatever
|
||||
is missing; never overwrite what is already there.
|
||||
3. **Scaffold the workshop structure** (only what's missing):
|
||||
```
|
||||
<path>/
|
||||
desks/ # where desks live
|
||||
bench/ # shared workspace
|
||||
CAIRN.md # operating disposition
|
||||
README.md # workshop map
|
||||
```
|
||||
4. **Do NOT run `git init`.** The directory may already be a git repo, or
|
||||
the operator may not want one yet. Leave git state alone.
|
||||
5. **Do NOT create a GitHub repo.** This path is local-only.
|
||||
|
||||
### Path B: Create a new private GitHub repo
|
||||
|
||||
The operator wants a fresh workshop backed by a GitHub repo.
|
||||
|
||||
1. **Get the workshop name.** Short, no spaces, kebab-case preferred.
|
||||
2. **Pick and validate a clone parent.** `gh repo create --clone` clones
|
||||
into the **current working directory**, so choose an explicit parent
|
||||
directory first (ask the operator, or use their configured workshops
|
||||
directory) and confirm it is **not** already inside a git repo:
|
||||
```bash
|
||||
git -C <parent-dir> rev-parse --is-inside-work-tree
|
||||
```
|
||||
If that prints `true`, pick a different parent — otherwise the new
|
||||
repo nests inside the existing one. Create the parent if needed.
|
||||
3. **Create and clone the repo from that parent:**
|
||||
```bash
|
||||
cd <parent-dir>
|
||||
gh repo create <owner>/<name> --private --clone
|
||||
```
|
||||
Use the operator's signed-in GitHub account as `<owner>`.
|
||||
4. **Scaffold the workshop structure** inside the cloned repo. Git does
|
||||
not track empty directories, so add a placeholder in each otherwise
|
||||
empty folder or the scaffold will not survive the next clone:
|
||||
```
|
||||
<name>/
|
||||
desks/.gitkeep
|
||||
bench/.gitkeep
|
||||
CAIRN.md
|
||||
README.md
|
||||
```
|
||||
5. **Commit and push** the scaffold, including the `.gitkeep` placeholders.
|
||||
|
||||
### Critical: Never nest repos
|
||||
|
||||
**Never run `git init` inside a directory that is already inside a git
|
||||
repository.** Before initializing, check:
|
||||
|
||||
```bash
|
||||
git -C <parent-dir> rev-parse --is-inside-work-tree
|
||||
```
|
||||
|
||||
If that returns `true`, the parent is already a git repo. Do NOT create
|
||||
another repo inside it. Either:
|
||||
- Use Path A (just scaffold, no git)
|
||||
- Or clone to a different location that isn't inside a repo
|
||||
|
||||
## CAIRN.md content
|
||||
|
||||
The operating disposition every desk reads:
|
||||
|
||||
```markdown
|
||||
# cairn
|
||||
|
||||
the trail markers that say: someone was here, and they were honest.
|
||||
|
||||
## how a desk stands
|
||||
|
||||
- **stop is a valid finish.** don't force a result when the evidence
|
||||
says stop. "this doesn't work" is a finding, not a failure.
|
||||
- **"done" means it holds.** if you'd bet your desk on it, ship it.
|
||||
if not, say what's uncertain and why.
|
||||
- **hold scope.** touch only what the task needs. if you find something
|
||||
outside scope, note it and move on — don't chase it.
|
||||
- **never go silent, never bluff.** partial + honest > complete + wrong.
|
||||
if you're stuck, say so. if you're unsure, say that too.
|
||||
- **equal standing.** you can say "that's the wrong question." you can
|
||||
disagree with another desk. you answer to evidence, not hierarchy.
|
||||
|
||||
## the bench
|
||||
|
||||
the shared workspace. leave your work where others can find it.
|
||||
label it. if it supersedes earlier work, say so.
|
||||
|
||||
## hands-up
|
||||
|
||||
when two desks disagree and can't settle it against external facts,
|
||||
that's a hands-up. it goes to the operator. this is the system
|
||||
working, not failing.
|
||||
```
|
||||
|
||||
## After creation
|
||||
|
||||
Tell the operator:
|
||||
- Where the workshop lives (full path)
|
||||
- That they can now open desks in it with `desk-open`
|
||||
- That Cairn will show signals once desks start emitting them
|
||||
|
||||
## Principles
|
||||
|
||||
- A workshop is a place, not a product. Keep it simple.
|
||||
- The operator decides where things go. Don't assume.
|
||||
- If an existing directory already has work in it, preserve everything.
|
||||
Only add what's missing.
|
||||
Reference in New Issue
Block a user