@troylar/flightdeck 2.0.0 → 2.1.0
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/CHANGELOG.md +35 -0
- package/README.md +488 -107
- package/bin/flightdeck.js +55 -21
- package/dist/flightdeck.html +1936 -278
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,41 +10,242 @@
|
|
|
10
10
|
[](#safe-by-design)
|
|
11
11
|
[](#install)
|
|
12
12
|
|
|
13
|
-
**[Install](#install)** · **[Tour](#a-tour)** · **[
|
|
13
|
+
**[In 60 seconds](#flightdeck-in-60-seconds)** · **[How it works](#how-it-works)** · **[Install](#install)** · **[Tour](#a-tour)** · **[Checklist format](#the-checklist-format)** · **[Process to skill](#process-to-skill-traceability)** · **[FAQ](#faq)**
|
|
14
14
|
|
|
15
15
|
</div>
|
|
16
16
|
|
|
17
17
|
<br>
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
**Flightdeck turns the processes your team keeps in its head into checklists you can run, prove and hand to your AI assistant.**
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
- **What it is:** one HTML file. No server, no sign-in, no network, no AI inside. It runs offline in Edge or Chrome.
|
|
22
|
+
- **Who it's for:** teams with work they repeat: the release, the incident, the access review, the month-end close, the check-in.
|
|
23
|
+
- **Why it's different:** your shared folder is the whole backend. Every checklist version is frozen, every run is a record, and every AI skill you build is tied to the exact steps it automates. Change a step, and Flightdeck tells you which skills are now out of date.
|
|
22
24
|
|
|
23
|
-
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/run-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/run-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/run-light.png" alt="A release in progress on the
|
|
25
|
+
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/run-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/run-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/run-light.png" alt="A release in progress on the run screen: 7/15 answered in the header, a strip saying you're recording with Pause and Hand off and the run's details, Phases with each gate's state, the checklist with Next up pinned at its top, and the selected step with what to do, the values to copy, its timing, Record the result, Done, Done differently and Blocked" width="1000"></picture></a></p>
|
|
26
|
+
|
|
27
|
+
<details>
|
|
28
|
+
<summary><b>Contents</b></summary>
|
|
29
|
+
|
|
30
|
+
- [Flightdeck in 60 seconds](#flightdeck-in-60-seconds)
|
|
31
|
+
- [How it works](#how-it-works)
|
|
32
|
+
- [Install](#install)
|
|
33
|
+
- [A tour](#a-tour)
|
|
34
|
+
- [What it does](#what-it-does)
|
|
35
|
+
- [The checklist format](#the-checklist-format)
|
|
36
|
+
- [Manage your templates in the app](#manage-your-templates-in-the-app)
|
|
37
|
+
- [Your own step types](#your-own-step-types)
|
|
38
|
+
- [Process-to-skill traceability](#process-to-skill-traceability)
|
|
39
|
+
- [Command line](#command-line)
|
|
40
|
+
- [The team folder](#the-team-folder)
|
|
41
|
+
- [Skills for your AI assistant](#skills-for-your-ai-assistant)
|
|
42
|
+
- [Safe by design](#safe-by-design)
|
|
43
|
+
- [Coming from Preflight](#coming-from-preflight)
|
|
44
|
+
- [FAQ](#faq)
|
|
45
|
+
- [More docs](#more-docs)
|
|
46
|
+
|
|
47
|
+
</details>
|
|
24
48
|
|
|
25
49
|
<br>
|
|
26
50
|
|
|
27
|
-
##
|
|
51
|
+
## Flightdeck in 60 seconds
|
|
28
52
|
|
|
29
|
-
|
|
53
|
+
**1. Write a checklist.** It's a Markdown file in your team folder. This one is complete:
|
|
30
54
|
|
|
31
|
-
|
|
55
|
+
```markdown
|
|
56
|
+
---
|
|
57
|
+
process: docs
|
|
58
|
+
title: Publish the docs
|
|
59
|
+
owner: person-casey
|
|
60
|
+
context: commit
|
|
61
|
+
---
|
|
32
62
|
|
|
33
|
-
|
|
34
|
-
-
|
|
35
|
-
|
|
36
|
-
-
|
|
37
|
-
- **Evidence kept.** Every run keeps who checked each step, what was marked N/A, and where people did it differently.
|
|
63
|
+
## Build · DO-CONFIRM {#build}
|
|
64
|
+
- [!] {run.command} Docs build with no warnings ^commit {#build-docs}
|
|
65
|
+
command: npm run docs
|
|
66
|
+
- [ ] {confirm} Screenshots match the current app {#shots}
|
|
38
67
|
|
|
39
|
-
|
|
68
|
+
## Gate: Ready to publish {#ready}
|
|
69
|
+
approves: publishing `^commit`
|
|
70
|
+
|
|
71
|
+
## Publish · READ-DO {#publish}
|
|
72
|
+
- [!] {run.command} Push the site ^commit {#push}
|
|
73
|
+
command: npm run docs:publish
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Two phases, three steps, one gate (plus the final confirmation every checklist gets). `[!]` is a must-do. `{run.command}` is the step's type, so the run shows the command with a Copy button. `^commit` ties a step to a run detail. The gate approves exactly one thing: publishing that commit.
|
|
77
|
+
|
|
78
|
+
**2. Publish it.** Flightdeck freezes it as **v1**. Runs always keep the version they started on.
|
|
79
|
+
|
|
80
|
+
**3. Run it.** Choose **Start a run** and type the commit. The Publish phase stays locked until someone passes the gate. Then step through: **Done**, **Done differently**, **Blocked** or **N/A**.
|
|
81
|
+
|
|
82
|
+
**4. Look in the folder.** Everything is a plain file:
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
docs/ ← your team folder (OneDrive, or any folder people share)
|
|
86
|
+
├── maps/drafts/docs.md ← the checklist you wrote
|
|
87
|
+
├── publications/docs/v1-k3m9p2q8/ ← v1, frozen: written once, never changed
|
|
88
|
+
│ ├── map.md ← the checklist exactly as published
|
|
89
|
+
│ ├── types.json ← every step type it uses, copied in
|
|
90
|
+
│ └── publication.json ← who published it, when, and why
|
|
91
|
+
└── runs/docs/9d96paue/ ← one run
|
|
92
|
+
├── run.json ← answers, gates, details: written only by the recorder's window
|
|
93
|
+
├── notes-<window>.jsonl ← each window's notes and corrections, in its own file
|
|
94
|
+
└── files/ ← attachments
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Here is the gate inside `run.json`, next to what the screen shows:
|
|
98
|
+
|
|
99
|
+
<table>
|
|
100
|
+
<tr><th>In <code>run.json</code></th><th>On screen</th></tr>
|
|
101
|
+
<tr><td>
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
"gates": {
|
|
105
|
+
"ready": {
|
|
106
|
+
"s": "passed",
|
|
107
|
+
"by": "person-casey",
|
|
108
|
+
"at": "2026-10-22T13:17:05.884Z",
|
|
109
|
+
"approved": { "commit": "d9d8514" }
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
</td><td>
|
|
115
|
+
|
|
116
|
+
**Gate: Ready to publish** · PASSED<br>
|
|
117
|
+
Approves publishing `d9d8514`<br>
|
|
118
|
+
Passed by Casey Nguyen at 9:17 AM for commit d9d8514
|
|
119
|
+
|
|
120
|
+
</td></tr>
|
|
121
|
+
</table>
|
|
122
|
+
|
|
123
|
+
The gate remembers the commit it approved. Change the commit mid-run, and the gate and every step tied to `^commit` come back for a re-check.
|
|
40
124
|
|
|
41
125
|
<br>
|
|
42
126
|
|
|
43
|
-
##
|
|
127
|
+
## How it works
|
|
128
|
+
|
|
129
|
+
Six ideas carry the whole design.
|
|
130
|
+
|
|
131
|
+
### 1. The team folder is the whole backend
|
|
132
|
+
|
|
133
|
+
There's no server. Each person opens the same `flightdeck.html` from a folder the team shares (OneDrive is the tested setup). The app reads and writes plain files there, and the sync tool carries them between computers.
|
|
134
|
+
|
|
135
|
+
```mermaid
|
|
136
|
+
flowchart LR
|
|
137
|
+
subgraph A["Casey's computer"]
|
|
138
|
+
a["flightdeck.html<br/>in Edge or Chrome"]
|
|
139
|
+
end
|
|
140
|
+
subgraph B["Blake's computer"]
|
|
141
|
+
b["flightdeck.html<br/>in Edge or Chrome"]
|
|
142
|
+
end
|
|
143
|
+
F[("Team folder<br/>plain files, synced")]
|
|
144
|
+
AI["Your AI assistant"]
|
|
145
|
+
a <-->|reads and writes| F
|
|
146
|
+
b <-->|reads and writes| F
|
|
147
|
+
AI -->|writes drafts, plans,<br/>skill registrations| F
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The trick that makes a synced folder safe: **every file has exactly one writer.** The recorder's window writes `run.json`. Every other window writes its own `notes-<window>.jsonl`. Publishing writes a new folder every time. Decisions are new files, written once. Two people never save over each other in ordinary use, so the sync tool never has to merge anything.
|
|
151
|
+
|
|
152
|
+
### 2. One HTML file
|
|
153
|
+
|
|
154
|
+
The app, its fonts and its built-in examples are all inside `flightdeck.html`. It makes no network requests. Copy it anywhere and open it. `flightdeck install` puts it in the team folder so everyone opens the same version.
|
|
155
|
+
|
|
156
|
+
### 3. A checklist is twenty readable lines
|
|
157
|
+
|
|
158
|
+
A checklist is Markdown that a person can read and an AI assistant can write. Phases end at gates. Steps have types, so each one asks for the right evidence: a build number, a PR link, a decision. Publishing freezes it as a numbered version, with who, when and why. To rehearse a change first, **stage** it: test runs try the staged version while every real run stays on the current default, and **Make v3 the default** publishes exactly what was rehearsed. See [The checklist format](#the-checklist-format) and [Staging and test runs](#staging-and-test-runs).
|
|
44
159
|
|
|
45
|
-
|
|
160
|
+
### 4. A run is a recording
|
|
46
161
|
|
|
47
|
-
|
|
162
|
+
One person **records** a run; everyone else follows along on their own screen and adds notes and files. Every answer keeps who and when. A re-check keeps the earlier answer as history instead of erasing it.
|
|
163
|
+
|
|
164
|
+
```mermaid
|
|
165
|
+
stateDiagram-v2
|
|
166
|
+
state "Stopped early" as Stopped
|
|
167
|
+
[*] --> Planned: Plan a run
|
|
168
|
+
[*] --> Running: Start a run
|
|
169
|
+
Planned --> Running: someone starts it
|
|
170
|
+
Running --> Paused: Pause, with a reason
|
|
171
|
+
Paused --> Running: Resume (paused time never counts)
|
|
172
|
+
Running --> Completed: End run
|
|
173
|
+
Running --> Stopped: End run
|
|
174
|
+
Running --> Cancelled: End run
|
|
175
|
+
Completed --> [*]
|
|
176
|
+
Stopped --> [*]
|
|
177
|
+
Cancelled --> [*]
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Recording can move between people. **Hand off** saves the run and names the exact revision passed on. **Pick up** continues it in another window. **Take over** is for emergencies, when the recorder's computer is gone.
|
|
181
|
+
|
|
182
|
+
### 5. Corrections flow back into the checklist
|
|
183
|
+
|
|
184
|
+
When the checklist is wrong mid-run, anyone can **Correct this step**. The correction rides along with the run as evidence, then waits on the process page until someone acts on it.
|
|
185
|
+
|
|
186
|
+
```mermaid
|
|
187
|
+
flowchart TD
|
|
188
|
+
S["A step during a run"] -->|"Correct this step<br/>(or Done differently + Fix the checklist too)"| C["Correction, saved with the run"]
|
|
189
|
+
C --> P["Process page: Corrections,<br/>grouped by step<br/>'Suggested in 3 runs'"]
|
|
190
|
+
P -->|Review and apply| D["The draft"]
|
|
191
|
+
P -->|Decline, with a reason| X["Closed, with why"]
|
|
192
|
+
D -->|Publish| V["v5 records which corrections it includes"]
|
|
193
|
+
V --> R["Runs of v5 show 'Changed in v5'<br/>with 'Why is this here?'"]
|
|
194
|
+
V --> H["Home tells whoever suggested it"]
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### 6. Skills are tied to the exact steps they automate
|
|
198
|
+
|
|
199
|
+
A skill is reusable instructions for your AI assistant. Flightdeck doesn't run skills; it keeps the link between each skill and the process version it was built from. The link is a small file:
|
|
200
|
+
|
|
201
|
+
<table>
|
|
202
|
+
<tr><th><code>skills/release-deploy.json</code></th><th>What the app shows after v2 changes the deploy step</th></tr>
|
|
203
|
+
<tr><td>
|
|
204
|
+
|
|
205
|
+
```json
|
|
206
|
+
{
|
|
207
|
+
"name": "release-deploy",
|
|
208
|
+
"version": "0.4.0",
|
|
209
|
+
"location": "~/skills/release-deploy",
|
|
210
|
+
"implements": "release@1",
|
|
211
|
+
"steps": ["merge", "jenkins"]
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
</td><td>
|
|
216
|
+
|
|
217
|
+
**NEEDS AN UPDATE**<br>
|
|
218
|
+
Built from v1. In v2, 1 of its steps changed. Give your AI assistant the update brief: it has the exact before and after.
|
|
219
|
+
|
|
220
|
+
- **Start the production deploy job**: changed
|
|
221
|
+
|
|
222
|
+
**Copy the update brief**
|
|
223
|
+
|
|
224
|
+
</td></tr>
|
|
225
|
+
</table>
|
|
226
|
+
|
|
227
|
+
```mermaid
|
|
228
|
+
flowchart LR
|
|
229
|
+
W["Write a checklist"] --> P["Publish v1<br/>(frozen)"]
|
|
230
|
+
P --> R["Run it"]
|
|
231
|
+
R --> V["Prove it:<br/>3 clean runs +<br/>owner sign-off"]
|
|
232
|
+
V --> B["Brief your<br/>AI assistant"]
|
|
233
|
+
B --> K["Skill registered<br/>against v1"]
|
|
234
|
+
R -.->|corrections| P2["Publish v2"]
|
|
235
|
+
P2 -.->|"a covered step changed"| U["Skill: needs an update<br/>+ the exact before and after"]
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
<details>
|
|
239
|
+
<summary><b>Six design choices worth knowing</b></summary>
|
|
240
|
+
|
|
241
|
+
- **A failed run read is never "nothing there."** If OneDrive hasn't finished syncing a run, or it can't be read, Flightdeck says so by name. It never treats the run as empty. A run whose latest read failed stays on screen, but it doesn't count toward a sign-off until it reads again. A sign-off that can't be read is named; if this window read it before, what it said still counts, and otherwise Flightdeck says it can't tell yet and doesn't offer Sign off. A plan, or a decision on it, that can't be read is named and holds the plan: it can't be started, declined or switched until the decision reads again (every plan, while `proposals/` itself can't be read).
|
|
242
|
+
- **Every save leaves a receipt first.** Before writing `run.json`, a window writes its version to its own `candidate-<window>-<save>.json`, and `run.json` lists the saves it includes. If two computers that can't see each other both save, the replaced save isn't on the list, so it shows up in the run as a copy to compare. It's never silently lost.
|
|
243
|
+
- **A run save checks the file it's about to replace.** Before every `run.json` save, Flightdeck compares a SHA-256 of the file's exact text with the one it read. If it changed, it writes its version beside the file as a conflict copy instead. Nothing is ever merged automatically.
|
|
244
|
+
- **An older copy can't damage what a newer copy wrote.** A run with fields an older Flightdeck doesn't understand opens read-only there, and a version that needs a newer Flightdeck says "Update Flightdeck to run it." Dropping unknown fields on save would erase someone's work, so the older copy never saves.
|
|
245
|
+
- **A gate is a record, not a live lock.** A synced folder can be a minute behind, so a gate means "passed for this commit, by Casey, at 9:52," never "safe right now." Irreversible actions always keep a person's confirmation.
|
|
246
|
+
- **The run carries its own checklist.** `run.json` holds a snapshot of the exact checklist and step types it started on, so a run reads the same years later, whatever happened to the process since.
|
|
247
|
+
|
|
248
|
+
</details>
|
|
48
249
|
|
|
49
250
|
<br>
|
|
50
251
|
|
|
@@ -56,23 +257,25 @@ npm install -g @troylar/flightdeck
|
|
|
56
257
|
flightdeck open # opens the app: start your team, join one, or look around the examples
|
|
57
258
|
```
|
|
58
259
|
|
|
59
|
-
|
|
260
|
+
The first screen offers three ways in:
|
|
261
|
+
|
|
262
|
+
| Choice | Who | What happens |
|
|
263
|
+
|---|---|---|
|
|
264
|
+
| **Start your team** | The first person | Pick an empty shared folder (Flightdeck checks it can save there), add your people and a backup owner, publish a first checklist (Code check-in, Weekly review, blank, or one your AI assistant writes), do a first run on your own, then send a teammate the way in and check that their computer answers. The folder owner and backup owner see **Getting started · N of 5** on Home until all five are done; each step ticks itself from what's in the folder. |
|
|
265
|
+
| **Join your team's folder** | Everyone else | Open the folder and choose who you are. Not on the list? Copy a request to the folder owner. Only the folder owner and backup owner change `people.json`. |
|
|
266
|
+
| **Look around the examples** | Anyone curious | A made-up team, saved in this browser only. |
|
|
267
|
+
|
|
268
|
+
**Starting a team?** Pick a new, empty folder, so nothing already there is replaced. When setup is done, put Flightdeck in that folder so everyone opens the same version:
|
|
60
269
|
|
|
61
270
|
```bash
|
|
62
271
|
flightdeck install ~/OneDrive/Team # adds flightdeck.html; keeps the AGENTS.md and skills setup wrote
|
|
63
272
|
```
|
|
64
273
|
|
|
65
|
-
**Joining a team?** Open `flightdeck.html` from your team's folder in Edge or Chrome.
|
|
66
|
-
|
|
67
|
-
The first screen offers three ways in:
|
|
68
|
-
|
|
69
|
-
- **Start your team** (the first person): pick an empty shared OneDrive folder (Flightdeck checks it can save there), add your people and a backup owner, publish a first checklist (Code check-in, Weekly review, blank, or one your AI assistant writes), do a first run on your own, then send a teammate the way in and check that their computer answers. Home shows **Getting started · N of 5** until all five are done; each step ticks itself from what's in the folder.
|
|
70
|
-
- **Join your team's folder** (everyone else): open the folder and choose who you are. Not on the list? Copy a request to the folder owner; only the folder owner and backup owner change `people.json`.
|
|
71
|
-
- **Look around the examples**: a made-up team, saved in this browser only.
|
|
72
|
-
|
|
73
274
|
Setup writes `people.json`, `AGENTS.md` and the skills itself; `flightdeck install` afterwards only adds what's missing or still a default. Run it before setup and the folder isn't empty any more, so setup asks for another one.
|
|
74
275
|
|
|
75
|
-
|
|
276
|
+
**Joining a team?** Open `flightdeck.html` from your team's folder in Edge or Chrome.
|
|
277
|
+
|
|
278
|
+
**Updating later?** Run `flightdeck install` again. It updates what's still a Flightdeck default and keeps what your team changed. [Updating Flightdeck](https://github.com/troylar/flightdeck/blob/main/docs/updating.md) walks through it, including backups and mixed versions. [When something goes wrong](https://github.com/troylar/flightdeck/blob/main/docs/recovery.md) covers conflict copies, lost folder access and restoring.
|
|
76
279
|
|
|
77
280
|
> **Prefer no npm?** `flightdeck.html` is self-contained. Copy it anywhere and open it.
|
|
78
281
|
|
|
@@ -80,38 +283,38 @@ To update later, run `flightdeck install` again: it updates what's still a Fligh
|
|
|
80
283
|
|
|
81
284
|
## A tour
|
|
82
285
|
|
|
83
|
-
|
|
286
|
+
Choose **Look around the examples**, then **Casey Nguyen** in the top right, and follow along. The top bar has four sections: **Home, Runs, Processes, Settings**. **Skills** and **Step types** open from the Processes page, from Settings and from search.
|
|
84
287
|
|
|
85
288
|
<table>
|
|
86
289
|
<tr>
|
|
87
290
|
<td width="50%" valign="top">
|
|
88
291
|
|
|
89
|
-
**Home** shows only what
|
|
292
|
+
**Home** shows only what's yours, each with one button: the run you're recording, a plan to review, a skill to update, and your open follow-ups.
|
|
90
293
|
|
|
91
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/home-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/home-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/home-light.png" alt="Home:
|
|
294
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/home-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/home-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/home-light.png" alt="Home for Casey: four things that need you, each with one button, then Your follow-ups with Done, Moved to a ticket, Moved to another run and Won't do"></picture></a>
|
|
92
295
|
|
|
93
296
|
</td>
|
|
94
297
|
<td width="50%" valign="top">
|
|
95
298
|
|
|
96
|
-
**Processes** are your templates, in your team's own hierarchy and
|
|
299
|
+
**Processes** are your templates, in your team's own hierarchy, with **Filter by tag** and each one's version and last run. **New process** starts one.
|
|
97
300
|
|
|
98
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/processes-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/processes-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/processes-light.png" alt="Processes: the team templates grouped by hierarchy, with
|
|
301
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/processes-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/processes-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/processes-light.png" alt="Processes: the team's templates grouped by hierarchy, each with its version, last run and skills, with Skills, Step types and New process at the top"></picture></a>
|
|
99
302
|
|
|
100
303
|
</td>
|
|
101
304
|
</tr>
|
|
102
305
|
<tr>
|
|
103
306
|
<td valign="top">
|
|
104
307
|
|
|
105
|
-
**A process** is one page: its checklist with skill badges, the Corrections people recorded during runs, whether it's ready for a skill, its skills
|
|
308
|
+
**A process** is one page: its checklist with skill badges, **Start a run**, **Plan a run** and **How runs go**. Its owner and backup owner also see the Corrections people recorded during runs, whether it's ready for a skill, and its skills; everyone else sees each of those as one line.
|
|
106
309
|
|
|
107
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/process-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/process-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/process-light.png" alt="The Production release process: the v2 checklist with skill badges,
|
|
310
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/process-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/process-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/process-light.png" alt="The Production release process as its owner sees it: the v2 checklist with skill badges, Checklist, Flight plan and Markdown views, Edit, Start a run and Plan a run, and the Corrections panel with two open corrections"></picture></a>
|
|
108
311
|
|
|
109
312
|
</td>
|
|
110
313
|
<td valign="top">
|
|
111
314
|
|
|
112
|
-
**Edit** in place, as an outline or as Markdown, beside a live check and preview.
|
|
315
|
+
**Edit** in place, as an outline or as Markdown, beside a live check and preview. Your AI assistant's changes show up as you edit, marked and one Undo away.
|
|
113
316
|
|
|
114
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/edit-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/edit-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/edit-light.png" alt="Editing a draft: the Markdown on the left,
|
|
317
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/edit-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/edit-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/edit-light.png" alt="Editing a draft as Markdown: the open corrections with links to their lines, the Markdown on the left, and the Checks and Preview tabs on the right"></picture></a>
|
|
115
318
|
|
|
116
319
|
</td>
|
|
117
320
|
</tr>
|
|
@@ -120,14 +323,14 @@ To update later, run `flightdeck install` again: it updates what's still a Fligh
|
|
|
120
323
|
|
|
121
324
|
**Skills**: every skill built from your processes, wherever it lives, and which ones need an update.
|
|
122
325
|
|
|
123
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skills-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-light.png" alt="Skills: two skills that need an update, then every skill in the team hierarchy with tag
|
|
326
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skills-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-light.png" alt="Skills: two skills that need an update, then every skill in the team hierarchy with a tag filter"></picture></a>
|
|
124
327
|
|
|
125
328
|
</td>
|
|
126
329
|
<td valign="top">
|
|
127
330
|
|
|
128
331
|
**A skill** says what changed under it and gives your AI assistant the exact before and after.
|
|
129
332
|
|
|
130
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skill-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-light.png" alt="The release-deploy skill: needs an update because one of its steps changed in v2, with a Copy the update brief button and where the skill lives"></picture></a>
|
|
333
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skill-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-light.png" alt="The release-deploy skill: needs an update because one of its steps changed in v2, with a Copy the update brief button, and where the skill lives and which steps it covers"></picture></a>
|
|
131
334
|
|
|
132
335
|
</td>
|
|
133
336
|
</tr>
|
|
@@ -136,14 +339,14 @@ To update later, run `flightdeck install` again: it updates what's still a Fligh
|
|
|
136
339
|
|
|
137
340
|
**Flight plan** shows a version's shape: phases from start to landing, gates as checkpoints, tracks side by side, and, from that version's runs, typical times, autopilot (steps skills cover) and turbulence.
|
|
138
341
|
|
|
139
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/flight-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/flight-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/flight-light.png" alt="The release v1 as a flight plan: Start,
|
|
342
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/flight-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/flight-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/flight-light.png" alt="The release v1 as a flight plan: Start with autopilot, phases with typical times, turbulence notes and a connecting flight to Check in code, and gates as striped checkpoints"></picture></a>
|
|
140
343
|
|
|
141
344
|
</td>
|
|
142
345
|
<td valign="top">
|
|
143
346
|
|
|
144
|
-
The **Builder** edits a draft as an outline: drag a step or press Alt+Up / Alt+Down, change it in the side form, and **Undo**. It writes the same Markdown.
|
|
347
|
+
The **Builder** edits a draft as an outline: drag a step or press Alt+Up / Alt+Down, change it in the side form (text, type, roles, fields, notes, and screenshots by paste or drop), and **Undo**. It writes the same Markdown.
|
|
145
348
|
|
|
146
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/builder-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/builder-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/builder-light.png" alt="The outline builder: phases as cards with steps as rows and a striped gate bar
|
|
349
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/builder-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/builder-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/builder-light.png" alt="The outline builder: the parts box with Phase, Gate, Step, Must-do and All parts, phases as cards with steps as rows and a striped gate bar, and the selected step's form with its text, kind, type, who does it and run details"></picture></a>
|
|
147
350
|
|
|
148
351
|
</td>
|
|
149
352
|
</tr>
|
|
@@ -159,29 +362,62 @@ The **Builder** edits a draft as an outline: drag a step or press Alt+Up / Alt+D
|
|
|
159
362
|
|
|
160
363
|
**Plan a run** for later: the details you know, who does what, and an optional time. Nothing starts until someone starts it.
|
|
161
364
|
|
|
162
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/plan-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/plan-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/plan-light.png" alt="Plan a run: run name, ticket and environment filled in, a time and a note, and
|
|
365
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/plan-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/plan-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/plan-light.png" alt="Plan a run: run name, ticket, commit and environment filled in, a time and a note, and a person for each role with the rotation's suggestion"></picture></a>
|
|
163
366
|
|
|
164
367
|
</td>
|
|
165
368
|
</tr>
|
|
166
369
|
<tr>
|
|
167
370
|
<td valign="top">
|
|
168
371
|
|
|
169
|
-
**Correct this step** during a run: it starts on the wording, with a live Before/After redline
|
|
372
|
+
**Correct this step** during a run: it starts on the wording, with a live Before/After redline. **Change something else** covers a missing step, the order, who does it, a screenshot, removing the step, or any other problem. The checklist's own text stays on screen.
|
|
170
373
|
|
|
171
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/correction-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/correction-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/correction-light.png" alt="Correct this step during a run: the checklist
|
|
374
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/correction-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/correction-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/correction-light.png" alt="Correct this step during a run: what the checklist says, the suggested wording, a Before/After redline, why, Attach for files, and Save correction"></picture></a>
|
|
172
375
|
|
|
173
376
|
</td>
|
|
174
377
|
<td valign="top">
|
|
175
378
|
|
|
176
|
-
**Corrections** on the process page, grouped by step: the same correction from several runs shows once, "Suggested in
|
|
379
|
+
**Corrections** on the process page, grouped by step: the same correction from several runs shows once, "Suggested in 2 runs". **Review and apply** puts it in the draft as one change you can undo.
|
|
177
380
|
|
|
178
|
-
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/corrections-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/corrections-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/corrections-light.png" alt="Corrections on the process page: a wording change suggested in two runs, with the runs listed, and a missing step, each with Mark as applied and Decline, then Copy correction brief"></picture></a>
|
|
381
|
+
<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/corrections-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/corrections-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/corrections-light.png" alt="Corrections on the process page: a wording change suggested in two runs, with the runs listed, and a missing step, each with Review and apply, Mark as applied and Decline, then Copy correction brief"></picture></a>
|
|
179
382
|
|
|
180
383
|
</td>
|
|
181
384
|
</tr>
|
|
182
385
|
</table>
|
|
183
386
|
|
|
184
|
-
|
|
387
|
+
<details>
|
|
388
|
+
<summary><b>More on corrections</b></summary>
|
|
389
|
+
|
|
390
|
+
- **Review and apply** compares what the run's version said, the draft now and the result side by side, then applies it to the draft in one click. If the draft already has it, **Link this correction**.
|
|
391
|
+
- You can also **Mark as applied**, **Decline** with a reason, or reopen one, and copy a correction brief for your AI assistant.
|
|
392
|
+
- The draft editor marks the steps with open corrections.
|
|
393
|
+
- Publishing records which applied corrections the version includes. A correction then says **Published in v5** once v5 both lists it and says it.
|
|
394
|
+
- Runs of v5 show **Changed in v5** on that step, with **Why is this here?**, and Home tells whoever suggested it.
|
|
395
|
+
|
|
396
|
+
</details>
|
|
397
|
+
|
|
398
|
+
### The run screen
|
|
399
|
+
|
|
400
|
+
A run fills the window, like the editor.
|
|
401
|
+
|
|
402
|
+
| Part | What it shows |
|
|
403
|
+
|---|---|
|
|
404
|
+
| **Header** | How far it is (`7/15 answered`), **Details**, **Screen share**, **Receipt** and **More** (with **Copy run key**). A test run says **Test run** beside its name. |
|
|
405
|
+
| **Recording strip** | Who's recording, with **Pause** and **Hand off** (or **Pick up**, **Record here**, **Take over**), the run's details, and what this window saved and when it last checked the folder. |
|
|
406
|
+
| **Phases** | Each phase and its gate's state, plus the day timeline and follow-ups. A phase shows its note and screenshots under its heading. |
|
|
407
|
+
| **Checklist** | Every step, with **Next up** pinned at the top. A gate shows its note above **Pass the gate**. A phase still behind its gate offers **Preview steps**, and a finished one folds to a tally with **Show steps**. Steps this run doesn't need fold into one line at the end of their phase, **1 step not needed**, each with its reason; a phase it doesn't need is one **Not needed** line, gate included. The receipt lists them under **Not needed in this run**. |
|
|
408
|
+
| **Selected step** | How to do it, the values to copy, the evidence to record, then **Done**, **Done differently**, **Blocked** and **N/A**, and the step's corrections and notes. |
|
|
409
|
+
|
|
410
|
+
<details>
|
|
411
|
+
<summary><b>Keyboard, drafts, files and tools</b></summary>
|
|
412
|
+
|
|
413
|
+
- **Keyboard.** Check the step Next up points at, and the next one is selected, ready for **Space**. The row's check, **Done**, **Space** and **Done differently** all answer that one step with the evidence typed on it.
|
|
414
|
+
- **Nothing typed is lost.** Typed evidence, Fill in values and unsent notes stay with their step (and their team folder) when you move around, and the row says **Draft**. While a step's Fill in is open or unsaved, Done says "Save or cancel Fill in first."
|
|
415
|
+
- **Done differently** asks what happened, and can fix the checklist too.
|
|
416
|
+
- **Files.** Notes and corrections take files: drop them on the note box, paste, or **Attach**. Images, PDF, text and logs, CSV, JSON, YAML and .zip, up to 10 MB each.
|
|
417
|
+
- **Reports from tools.** When a tool reported a step's work (`flightdeck report write`), the step shows the report and whether its inputs match the run. The recorder accepts or declines it.
|
|
418
|
+
- **On a phone** the checklist scrolls and a step opens as a full-screen sheet.
|
|
419
|
+
|
|
420
|
+
</details>
|
|
185
421
|
|
|
186
422
|
<br>
|
|
187
423
|
|
|
@@ -203,7 +439,7 @@ Every phase ends at a **gate**. Nothing after it opens until someone passes it,
|
|
|
203
439
|
<td width="50%" valign="top">
|
|
204
440
|
|
|
205
441
|
### One recorder, everyone watching
|
|
206
|
-
One person records; everyone else follows on their own screen and adds notes, screenshots and files (logs, PDFs, .zip) to any step. Hand recording over, or pick it up from another window. Every save first checks the file hasn't changed; if it has, yours is kept next to it as a copy you can compare and keep.
|
|
442
|
+
One person records; everyone else follows on their own screen and adds notes, screenshots and files (logs, PDFs, .zip) to any step. Hand recording over, or pick it up from another window. Every save first checks the file hasn't changed; if it has, yours is kept next to it as a copy you can compare and keep.
|
|
207
443
|
|
|
208
444
|
</td>
|
|
209
445
|
</tr>
|
|
@@ -211,7 +447,7 @@ One person records; everyone else follows on their own screen and adds notes, sc
|
|
|
211
447
|
<td valign="top">
|
|
212
448
|
|
|
213
449
|
### Steps that know their tools
|
|
214
|
-
Steps are typed: `jenkins.job`, `bitbucket.pr`, `github.pr`, `jira.issue`, `jira.sprint`, `deploy`, `verify.health`, `measure`, `run.command`, `decide`, `review` and more, plus your team's own types. Each asks for the evidence that matters (a build number, a PR link, a decision) only where the checklist says it's required.
|
|
450
|
+
Steps are typed: `jenkins.job`, `bitbucket.pr`, `github.pr`, `jira.issue`, `jira.sprint`, `deploy`, `verify.health`, `measure`, `run.command`, `decide`, `review` and more, plus your team's own types. Each asks for the evidence that matters (a build number, a PR link, a decision) only where the checklist says it's required. Evidence can be typed (a number, yes or no, a date, a choice, a link) and is checked as you type it.
|
|
215
451
|
|
|
216
452
|
</td>
|
|
217
453
|
<td valign="top">
|
|
@@ -231,7 +467,7 @@ Give a step a clock time, a deadline, or "within 2 hours of starting" and it get
|
|
|
231
467
|
<td valign="top">
|
|
232
468
|
|
|
233
469
|
### Processes inside processes
|
|
234
|
-
A step can start another process as a linked child run, passing on the details it needs. The parent step is checked only when that child completes, with the same values it was started for.
|
|
470
|
+
A step can start another process as a linked child run, passing on the details it needs, and can name the exact version to run. The parent step is checked only when that child completes, with the same values it was started for.
|
|
235
471
|
|
|
236
472
|
</td>
|
|
237
473
|
</tr>
|
|
@@ -239,13 +475,27 @@ A step can start another process as a linked child run, passing on the details i
|
|
|
239
475
|
<td valign="top">
|
|
240
476
|
|
|
241
477
|
### Values that flow
|
|
242
|
-
A step can **set** a run detail: the merge step records the release tag, and every later `^tag` in commands, messages and Jira fields uses it. Correct it later and the steps that used the old value come back for a re-check.
|
|
478
|
+
A step can **set** a run detail: the merge step records the release tag, and every later `^tag` in commands, messages and Jira fields uses it. Correct it later and the steps that used the old value come back for a re-check. Run details can be typed too, so a number or a date is checked when it's entered. With `only when`, a later step or phase applies only when a value matches, so one checklist covers both paths.
|
|
243
479
|
|
|
244
480
|
</td>
|
|
245
481
|
<td valign="top">
|
|
246
482
|
|
|
247
483
|
### Runs that teach the checklist
|
|
248
|
-
Every block, every re-check and every step **done differently**
|
|
484
|
+
Every block, every re-check and every step **done differently** is kept. Anyone in a run can **correct a step**, with files to show why. Corrections wait on the process page until someone applies or declines them. A process's **How runs go** shows typical time per phase, the steps that go off-script most, and who has never held which role yet, so the next rotation is obvious.
|
|
485
|
+
|
|
486
|
+
</td>
|
|
487
|
+
</tr>
|
|
488
|
+
<tr>
|
|
489
|
+
<td valign="top">
|
|
490
|
+
|
|
491
|
+
### Other apps work beside a run
|
|
492
|
+
Scripts and tools read checklists and runs as JSON, ask for a run, or report the work they did on a step. A person always decides: a request becomes a planned run someone starts, and a report is accepted or declined by the recorder. See [Command line](#command-line).
|
|
493
|
+
|
|
494
|
+
</td>
|
|
495
|
+
<td valign="top">
|
|
496
|
+
|
|
497
|
+
### Evidence you can hand to an auditor
|
|
498
|
+
Export one run, or every run of a process over a date range, as a zip of the original files with a readable page and SHA-256 hashes to check them by. Making a pack never changes the team folder. See [Evidence packs](https://github.com/troylar/flightdeck/blob/main/docs/evidence.md).
|
|
249
499
|
|
|
250
500
|
</td>
|
|
251
501
|
</tr>
|
|
@@ -255,9 +505,9 @@ Every block, every re-check and every step **done differently** (with what happe
|
|
|
255
505
|
|
|
256
506
|
<br>
|
|
257
507
|
|
|
258
|
-
##
|
|
508
|
+
## The checklist format
|
|
259
509
|
|
|
260
|
-
Checklists are Markdown. Your AI assistant writes them; people edit and publish them, in the builder or as Markdown.
|
|
510
|
+
Checklists are Markdown. Your AI assistant writes them; people edit and publish them, in the builder or as Markdown. Here is a fuller one:
|
|
261
511
|
|
|
262
512
|
```markdown
|
|
263
513
|
---
|
|
@@ -266,13 +516,15 @@ title: Production release
|
|
|
266
516
|
group: Engineering / Releases
|
|
267
517
|
tags: production, deploy
|
|
268
518
|
owner: person-casey
|
|
269
|
-
context: ticket, commit, environment, tag
|
|
519
|
+
context: ticket, commit, environment, tag, risk:choice(low|high)
|
|
270
520
|
roles: release-lead, qa, backend
|
|
271
521
|
---
|
|
272
522
|
|
|
273
523
|
## Before production changes · DO-CONFIRM {#prep}
|
|
274
524
|
- [!] {ci.gate} Full test gate green on the release commit ^commit {#tests}
|
|
275
525
|
require: run
|
|
526
|
+
- [!] {confirm} Change board approved the release ^ticket {#cab}
|
|
527
|
+
only when ^risk is high
|
|
276
528
|
|
|
277
529
|
## Gate: Ready to deploy · owner @release-lead {#ready}
|
|
278
530
|
approves: deploy of `^commit` to ^environment
|
|
@@ -291,48 +543,88 @@ roles: release-lead, qa, backend
|
|
|
291
543
|
| `{type}` | What kind of step, so it knows its fields and evidence |
|
|
292
544
|
| `@role` · `^detail` | Who does it · a run detail it depends on (change the detail, redo the step) |
|
|
293
545
|
| `sets: tag` | This step produces a run detail later steps use |
|
|
546
|
+
| `only when ^risk is high` | Under a step, or right under a phase heading: it applies only to runs whose details match. Otherwise it's Not needed, with the reason |
|
|
294
547
|
| `## Gate:` · `approves:` | The pause point, and exactly what passing it approves |
|
|
295
548
|
| `### Track: Name @role` | Parallel work inside a phase |
|
|
296
549
|
| `at:` · `due:` · `after:` | A clock time, a deadline, or a due time after the run starts |
|
|
297
|
-
| `{run.process}` · `carry:` | Start another process as a linked child run, passing these details |
|
|
550
|
+
| `{run.process}` · `carry:` · `version:` | Start another process as a linked child run, passing these details, on an exact version if you name one |
|
|
298
551
|
| `group:` · `tags:` | Where the process sits in your hierarchy, and how to find it |
|
|
552
|
+
| `context: rows:number, due:date` | Typed run details (number, yes-no, date, choice, link), checked as they're typed |
|
|
553
|
+
| `> note` · `` | A note or screenshot, under a step, a phase or a gate |
|
|
554
|
+
|
|
555
|
+
Publishing freezes a checklist as a numbered version, with who, when and why. Runs keep the version they started with, forever.
|
|
556
|
+
|
|
557
|
+
**Steps only some runs need.** In a run whose details don't match, an `only when` step is Not needed: it isn't counted, nobody checks it, and its reason stays one click away. A phase that isn't needed is skipped with its gate. Branching is `sets:` plus `only when`: one step sets a detail, and a later phase applies only when it matches. The process page and the flight plan show each condition as one muted line, *Only when risk is high*. **How runs go** leaves a run out of a step's numbers (corrections included) when that run didn't need the step, and **Ready for a skill?** never holds Not needed itself against a run, though something that already happened on the step still counts (for example, a step done and then sent back for re-check when a detail changed). It names conditional steps no clean run has needed yet.
|
|
299
558
|
|
|
300
|
-
|
|
559
|
+
Typed details, phase notes, phase and gate screenshots, and `version:` need Flightdeck 2.0; `only when` needs Flightdeck 2.1. Before you publish, the publish panel names what the draft uses under **Needs Flightdeck 2.0** or **Needs Flightdeck 2.1**, and teammates on an older copy see that version but can't run it. The full format is in [docs/map-format.md](https://github.com/troylar/flightdeck/blob/main/docs/map-format.md).
|
|
301
560
|
|
|
302
561
|
<br>
|
|
303
562
|
|
|
304
563
|
## Manage your templates in the app
|
|
305
564
|
|
|
306
|
-
A process is one page, with its checklist in the middle
|
|
565
|
+
A process is one page, with its checklist in the middle.
|
|
307
566
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
567
|
+
| To | Do this |
|
|
568
|
+
|---|---|
|
|
569
|
+
| **Read it** | The **Checklist** view shows it the way a run does; **Markdown** shows the source to copy. |
|
|
570
|
+
| **See its shape** | **Flight plan**: phases as waypoints, gates as checkpoints, tracks as parallel lanes, linked processes as connecting flights. From that version's runs and skills it adds typical times, autopilot (steps skills cover) and turbulence (steps that go off-script most). Each phase's steps open under it, or all at once with **Show all steps** and **Hide all steps**. Choose a phase to jump to it. |
|
|
571
|
+
| **Edit it** | **Edit** opens the draft on a page of its own, with the **Builder** or the **Markdown** beside a live check (what blocks publishing, and what's just a tip) and a preview. |
|
|
572
|
+
| **Look back** | The Versions panel shows the newest, with every version under **All versions**. An older version shows a way back to the current one and **Restore as draft**. |
|
|
573
|
+
| **Try it first** | Under **All versions**, **Stage the draft for testing**, then **Start a test run** on the staged line. Real runs stay on the current default until someone chooses **Make v3 the default**. See [Staging and test runs](#staging-and-test-runs). |
|
|
574
|
+
| **See how runs go** | **How runs go**: typical time per phase, the steps that go off-script most, and who has held each role. |
|
|
575
|
+
| **Plan ahead** | **Plan a run**, next to **Start a run**: a name, the details you know, who does what and an optional time. |
|
|
314
576
|
|
|
315
|
-
|
|
577
|
+
<details>
|
|
578
|
+
<summary><b>The editor in detail</b></summary>
|
|
316
579
|
|
|
317
|
-
|
|
580
|
+
- **Layout.** Parts, the outline, and an inspector with Selected, Checks and Preview tabs, each scrolling on its own.
|
|
581
|
+
- **Builder.** Phases are cards, steps are rows, parallel lanes sit side by side, and gates are striped bars. The parts box starts with Phase, Gate, Step and Must-do; every other part is under **All parts**. Add a part by dragging it, or by choosing a part and a place with the arrow keys. Drag a step or press Alt+Up / Alt+Down to move it. **Undo** and **Redo** step through builder changes.
|
|
582
|
+
- **The side form** edits a step's text, type, roles, run details, fields, notes and screenshots, or a lane's name and role. The builder also edits the checklist's own details.
|
|
583
|
+
- **Only when…** In a step's or a phase's form, once the checklist has run details. Write one condition a line, like `^risk is high`; one that can't be read is refused beside the box. Lines written another way are shown, and left to the Markdown view.
|
|
584
|
+
- **Same Markdown.** Both views edit the same file. The builder changes only the lines you touch, never a step ID, and keeps comments and lines it doesn't understand.
|
|
585
|
+
- **Saving and publishing.** **Save draft**, then **Done**. **Publish** appears when the draft has saved changes, and stays off while there are unsaved edits.
|
|
318
586
|
|
|
319
|
-
|
|
587
|
+
</details>
|
|
588
|
+
|
|
589
|
+
<details>
|
|
590
|
+
<summary><b>Plans, versions this copy can't use, and careful saving</b></summary>
|
|
591
|
+
|
|
592
|
+
- **Plans.** **Plan another like this** on any run or receipt copies its details and roles, never its answers. Planned runs are listed by time under **Runs** and show on Home when they're due. A plan starts on the version it was planned on until you switch to the newer one.
|
|
593
|
+
- **Versions this copy can't use** are listed with the reason: still syncing, damaged, or written by a newer Flightdeck ("update Flightdeck to run it"). They can't be started, planned or picked, and a run started on one by a newer copy opens read-only, so this copy never saves over it.
|
|
594
|
+
- **Careful saving.** A save only goes through if the draft is still exactly what you opened. If a teammate changed it meanwhile, nothing is saved: you see their version and choose to keep yours or take theirs.
|
|
595
|
+
- **Your AI assistant, live.** If your AI assistant changes a draft you have open with nothing unsaved, its change appears in the editor within seconds, marked "Changed by your AI assistant." Otherwise it waits on the process page as a proposal to Apply or Decline.
|
|
596
|
+
- **One limit.** A shared folder can't lock a file, so a change that lands in the instant between that check and the write can still be replaced. Edit a draft with one person (or one AI assistant) at a time. Saving never publishes; publishing is a separate, logged step.
|
|
597
|
+
|
|
598
|
+
</details>
|
|
320
599
|
|
|
321
600
|
**New process** on the Processes page asks for a title; the file name is made from it and shown before you create it. The group, tags, run details, roles, owner and file name are under **More options**. Start blank, from Code check-in or Weekly review (publish v1 as it is, or open it in the editor), or copy a prompt for your AI assistant.
|
|
322
601
|
|
|
602
|
+
### Staging and test runs
|
|
603
|
+
|
|
604
|
+
A stage is a safe rehearsal: the next version, tried by test runs, while every real run stays on the current default.
|
|
605
|
+
|
|
606
|
+
1. **Stage it.** With a changed draft, open **All versions** on the process page, write the change note, and choose **Stage the draft for testing**. It's written once to `staged/` and never edited.
|
|
607
|
+
2. **Try it.** **Start a test run** on the staged line opens its own start form. A test run is recorded like any run, but it's labeled **Test run** everywhere it shows (Runs, Home, Recent runs, the run header, the receipt, search and evidence) and it's never counted as a real run: **How runs go** says how many it left out, and Home's running number, last-run dates and role rotation skip it. Its follow-ups and corrections are real.
|
|
608
|
+
3. **Prove it.** Once the staged version has test runs, its line says how many are clean ("2 of 3 clean test runs"). With three, its owner (or the backup owner while the owner is away) gets **Sign off staged v3**.
|
|
609
|
+
4. **Make it the default.** **Make v3 the default** publishes exactly what was staged as the next version. If someone published meanwhile, it takes the next number and says so. **Ready for a skill?** then counts those clean test runs and that sign-off for v3, and says they're from while it was staged. Nothing from a test run counts for any other version.
|
|
610
|
+
|
|
611
|
+
**Retire** sets a stage aside and **Reopen** brings it back. Anyone can stage, make a stage the default, retire or reopen, and each is logged with their name. It all lives inside the closed **All versions**, out of the way until someone stages. Plans never start a test run, and a test run starts no linked runs, so a test run that needs a linked-run step never counts as clean (one where that step is Not needed can).
|
|
612
|
+
|
|
613
|
+
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/testrun-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/testrun-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/testrun-light.png" alt="A test run of staged v3: Test run beside its name and 'Test run · staged v3' under it, risk low among the run's details, and at the end of the first phase '1 step not needed', open to show the change request step applies only when risk is high (risk is low). The next phase, behind its gate, offers Preview steps." width="1000"></picture></a></p>
|
|
614
|
+
|
|
323
615
|
<br>
|
|
324
616
|
|
|
325
617
|
## Your own step types
|
|
326
618
|
|
|
327
|
-
Built-in types cover common tools
|
|
619
|
+
Built-in types cover common tools (General, Tools and Automation) and stay folded under **Built-in types** until you open them. Your team's types come first, in their own groups, with a tag filter. When your team has its own kind of step (a change request, a security sign-off), make it a type:
|
|
328
620
|
|
|
329
621
|
1. **Step types → New step type**, or **Copy to a team type** on any built-in.
|
|
330
622
|
2. Give it a **group** and **tags** if you like (they only organize the list), then add rows for its **fields** (what a checklist can say about the step) and its **evidence** (what's recorded when it's checked). The form checks it as you go and shows the checklist line and the file it will save.
|
|
331
|
-
3. **Save step type** writes `step-types/<id>.json`. Checklists can use `{your.type}` right away
|
|
623
|
+
3. **Save step type** writes `step-types/<id>.json`. Checklists can use `{your.type}` right away. Publishing freezes it into each version, so editing it later never changes an old one.
|
|
332
624
|
|
|
333
625
|
Or describe it to your AI assistant: `/flightdeck-new-step-type a change request the CAB approves, with the change number as evidence`.
|
|
334
626
|
|
|
335
|
-
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/types-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/types-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/types-light.png" alt="Step types: your team types, then
|
|
627
|
+
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/types-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/types-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/types-light.png" alt="Step types: your team's types first, then the built-in types opened, each with what it's for, how many checklists use it, and a button to copy it to a team type" width="1000"></picture></a></p>
|
|
336
628
|
|
|
337
629
|
<br>
|
|
338
630
|
|
|
@@ -340,14 +632,29 @@ Or describe it to your AI assistant: `/flightdeck-new-step-type a change request
|
|
|
340
632
|
|
|
341
633
|
This is what Flightdeck is for. Outside the team it's usually called **SOP-to-skill**: turning a standard operating procedure into an agent skill. Flightdeck adds the part that's usually missing: **traceability**. Each registered skill links to the exact process version and steps it follows, and runs are the evidence. Flightdeck flags process changes that affect a skill; it doesn't detect changes to the skill itself.
|
|
342
634
|
|
|
635
|
+
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skills-traced-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-traced-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-traced-light.png" alt="A process goes from v1 to v2 and one step changes. Flightdeck checks the registered skills: release-deploy and release-notes need an update, pr-opener is current. The update brief for release-deploy shows the exact before and after for your AI assistant." width="1000"></picture></a></p>
|
|
636
|
+
|
|
637
|
+
- **Built from proof.** Prove a version with three clean runs and its owner's sign-off, then brief your AI assistant to build the skill.
|
|
638
|
+
- **Traced to the step.** Each registered skill links to an exact process version and the steps it covers (or the whole process), plus where its source lives.
|
|
639
|
+
- **Changes flagged.** Publish a new version and Flightdeck shows which registered skills follow steps that changed, and which are still current.
|
|
640
|
+
- **Fixes, briefed.** One click copies an update brief: the before and after of each changed step, and the process as it is now.
|
|
641
|
+
- **Evidence kept.** Every run keeps who checked each step, what was marked N/A, and where people did it differently.
|
|
642
|
+
|
|
343
643
|
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/trace-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/trace-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/trace-light.png" alt="Five steps from process to skill: prove it with 3 clean runs, the owner signs it off, copy the brief, register the skill with its source and the steps it follows, and stay in step as new versions flag the skills they affect. Skill statuses: current, note version, needs an update, check it." width="1000"></picture></a></p>
|
|
344
644
|
|
|
345
645
|
<details>
|
|
346
646
|
<summary><b>How it works, step by step</b></summary>
|
|
347
647
|
|
|
348
|
-
**1. Prove a version.** Each process page shows its run evidence. A run counts as clean only when
|
|
648
|
+
**1. Prove a version.** Each process page shows its run evidence. A run counts as clean only when:
|
|
649
|
+
|
|
650
|
+
- it ended Completed;
|
|
651
|
+
- every covered step was done;
|
|
652
|
+
- every gate on that work (and the one before it) was passed;
|
|
653
|
+
- nothing was blocked, re-checked, marked N/A or done differently, even in answers since archived.
|
|
349
654
|
|
|
350
|
-
|
|
655
|
+
A step the run didn't need (`only when`) isn't required, and being Not needed isn't held against the run; a re-check or other deviation recorded on it earlier still is. A test run counts only for its staged version and the version made from exactly what was staged.
|
|
656
|
+
|
|
657
|
+
**2. Sign off.** With three clean runs, the process owner signs the version off. Only the owner's sign-off counts, and only for that exact published version, or for a staged version with **Sign off staged v3**, which counts for the version made from it.
|
|
351
658
|
|
|
352
659
|
**3. Brief your AI assistant.** One click copies a brief with the process in order: phases and their mode, tracks, every step with its fields, evidence and screenshots, every gate with what it approves, the run details it receives, and what people actually did differently.
|
|
353
660
|
|
|
@@ -357,7 +664,7 @@ This is what Flightdeck is for. Outside the team it's usually called **SOP-to-sk
|
|
|
357
664
|
{
|
|
358
665
|
"name": "release-deploy",
|
|
359
666
|
"version": "1.3.0",
|
|
360
|
-
"location": "https://
|
|
667
|
+
"location": "https://git.example.com/team-skills/release-deploy",
|
|
361
668
|
"implements": "release@4",
|
|
362
669
|
"steps": ["merge", "jenkins"],
|
|
363
670
|
"group": "Engineering / Releases",
|
|
@@ -365,7 +672,7 @@ This is what Flightdeck is for. Outside the team it's usually called **SOP-to-sk
|
|
|
365
672
|
}
|
|
366
673
|
```
|
|
367
674
|
|
|
368
|
-
Leave out `steps` for a skill that covers the whole process. A process can have many skills.
|
|
675
|
+
Leave out `steps` for a skill that covers the whole process. A process can have many skills. For a version made with Flightdeck 2.0, your AI assistant can register the skill with `flightdeck skill register`, which records the exact version it was built from in `skill-registrations/`.
|
|
369
676
|
|
|
370
677
|
**5. Stay in step.** When a new version is published, every skill is checked against it:
|
|
371
678
|
|
|
@@ -380,32 +687,48 @@ The same rules are in the `flightdeck-skill-brief` skill for your AI assistant,
|
|
|
380
687
|
|
|
381
688
|
</details>
|
|
382
689
|
|
|
383
|
-
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skill-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-light.png" alt="A skill that needs an update: the step that changed and the button that copies the update brief" width="1000"></picture></a></p>
|
|
384
|
-
|
|
385
690
|
<br>
|
|
386
691
|
|
|
387
692
|
## Command line
|
|
388
693
|
|
|
694
|
+
**For people:**
|
|
695
|
+
|
|
389
696
|
| Command | Does |
|
|
390
697
|
|---|---|
|
|
391
|
-
| `flightdeck open` | Opens the app on
|
|
698
|
+
| `flightdeck open` | Opens the app (it starts on the built-in examples) |
|
|
392
699
|
| `flightdeck install <folder>` | Copies `flightdeck.html` into a team folder, and adds or updates `AGENTS.md` and the skills for your AI assistant in `.flightdeck/skills`. Won't replace a newer app or an unrecognized file without `--force`. Also updates a `preflight.html` already there |
|
|
393
700
|
| `flightdeck skills <folder>` | Adds or updates only the skills, in `<folder>/.flightdeck/skills` |
|
|
394
|
-
| `flightdeck skills --to <dir>` | The same, into any other folder you name
|
|
701
|
+
| `flightdeck skills --to <dir>` | The same, into any other folder you name, such as your assistant's own skills folder or another repo. `<dir>` is created if it's missing |
|
|
395
702
|
| `flightdeck backup <folder>` | Copies the whole team folder to `~/Flightdeck backups/<folder> backup <date> <time>/`, or under `--to <dir>`. Skips links and temporary files, and refuses a destination inside the folder |
|
|
396
|
-
| `flightdeck export <folder> --run <process>/<id>` | Makes an evidence pack of one run in `~/Flightdeck evidence/` (or `--out <dir>`, never inside the team folder)
|
|
703
|
+
| `flightdeck export <folder> --run <process>/<id>` | Makes an evidence pack of one run in `~/Flightdeck evidence/` (or `--out <dir>`, never inside the team folder). Prints the pack's SHA-256 to keep somewhere separate. Reads only |
|
|
397
704
|
| `flightdeck export <folder> --process <id> --from YYYY-MM-DD --through YYYY-MM-DD` | The same for every run of a process started on those days, both included, in `--tz Area/City` (this computer's time zone unless you say) |
|
|
398
|
-
| `flightdeck processes <folder> --json` | For other apps: every process and its versions, as JSON |
|
|
399
|
-
| `flightdeck process <folder> <process> --json` | One version of a checklist (the latest usable one, or `--version N`, or `--folder v3-…`): phases, steps, gates and the evidence each step can record |
|
|
400
|
-
| `flightdeck runs <folder> --json` | Runs and planned runs, with `--process <id>` and `--status running\|planned\|ended\|all` |
|
|
401
|
-
| `flightdeck run <folder> <process>/<run id> --json` | One run in full: each step's state, who and when, what was recorded, gates and follow-ups. In the app, a run's **More** menu has **Copy run key** |
|
|
402
|
-
| `flightdeck next <folder> <process>/<run id> --json` | What's waiting in a run and on whom; `--person <id>` adds that person's own next step |
|
|
403
|
-
| `flightdeck followups <folder> --json` | Every follow-up and what became of it (`--status open` for the open ones) |
|
|
404
|
-
| `flightdeck plan request <folder> <request.json \| -> --key <key>` | For other apps: ask for a run. Writes one planned run to `proposals/`, once, for a person to review and start in the app. The same key and request again writes nothing. `--dry-run` shows what it would write; `--json` prints the result as JSON |
|
|
405
|
-
| `flightdeck report targets \| check \| write` | For other apps: report work a tool did on a step. `targets` lists running runs' steps and the evidence each records; `check` checks a report; `write` writes it once to `reports/`. A report never checks a step: the run's recorder accepts or declines it in the app |
|
|
406
705
|
| `flightdeck path` | Prints where the app file is |
|
|
407
706
|
| `flightdeck version` | Prints the version |
|
|
408
707
|
|
|
708
|
+
**For other apps** (they read the folder the way a teammate would, and never act for a person):
|
|
709
|
+
|
|
710
|
+
| Command | Does |
|
|
711
|
+
|---|---|
|
|
712
|
+
| `flightdeck processes <folder> --json` | Every process and its versions |
|
|
713
|
+
| `flightdeck process <folder> <process> --json` | One version of a checklist (the latest usable one, or `--version N`, or `--folder v3-…`, or a staged one with `--stage stage-…` and `--contract 2`): phases, steps, gates and the evidence each step can record |
|
|
714
|
+
| `flightdeck runs <folder> --json --contract 2` | Runs and planned runs, with `--process <id>` and `--status running\|planned\|ended\|all`. Test runs are left out and counted unless you add `--tests --contract 2` |
|
|
715
|
+
| `flightdeck run <folder> <process>/<run id> --json` | One run in full: each step's state, who and when, what was recorded, gates and follow-ups. In the app, a run's **More** menu has **Copy run key** |
|
|
716
|
+
| `flightdeck next <folder> <process>/<run id> --json` | What's waiting in a run and on whom; `--person <id>` adds that person's own next step |
|
|
717
|
+
| `flightdeck followups <folder> --json` | Every follow-up and what became of it, with `--process <id>` and `--status open\|all` |
|
|
718
|
+
| `flightdeck plan request <folder> <request.json \| -> --key <key>` | Ask for a run. Writes one planned run to `proposals/`, once, for a person to review and start in the app. The same key and request again writes nothing. `--dry-run` shows what it would write; `--json` prints the result as JSON |
|
|
719
|
+
| `flightdeck report targets \| check \| write` | Report work a tool did on a step. `targets` lists running runs' steps and the evidence each records; `check` checks a report; `write` writes it once to `reports/`. A report never checks a step: the run's recorder accepts or declines it in the app |
|
|
720
|
+
|
|
721
|
+
**For your AI assistant:**
|
|
722
|
+
|
|
723
|
+
| Command | Does |
|
|
724
|
+
|---|---|
|
|
725
|
+
| `flightdeck draft read <folder> <process> --json` | The draft's exact text and revision, who has it open, and this session's proposals |
|
|
726
|
+
| `flightdeck draft save <folder> <process> --expect <rev\|none> --from <file\|-> [--base <file>] --json` | Writes the draft only when nobody has it open and it's exactly what was read; otherwise writes a proposal a person applies in the app. If the text you started from is gone (someone changed the draft since you read it), it writes nothing and asks for it with `--base` |
|
|
727
|
+
| `flightdeck draft propose …` | The same arguments, `--json` included; writes a proposal instead of the draft, with the same `--base` rule |
|
|
728
|
+
| `flightdeck skill register <folder> --from <file\|->` | Registers a skill against the exact version it was built from (versions made with Flightdeck 2.0). The only writer of `skill-registrations/` |
|
|
729
|
+
|
|
730
|
+
**Options:**
|
|
731
|
+
|
|
409
732
|
| Option | Does |
|
|
410
733
|
|---|---|
|
|
411
734
|
| `--check` | With `install` or `skills`: lists what would change and changes nothing. Exit code 0: nothing to do; 2: updates to install; 3: files your team changed need merging; 1: a problem |
|
|
@@ -413,15 +736,27 @@ The same rules are in the `flightdeck-skill-brief` skill for your AI assistant,
|
|
|
413
736
|
| `--force` | Replaces a newer app, an unrecognized file, or files your team changed. Like every install, it first saves a checked copy of each file it replaces in `.flightdeck/updates/<version>/replaced/` |
|
|
414
737
|
| `--no-attachments` | With `export`: lists attachments with their sizes instead of packing them |
|
|
415
738
|
|
|
416
|
-
|
|
739
|
+
<details>
|
|
740
|
+
<summary><b>Exit codes and guarantees</b></summary>
|
|
741
|
+
|
|
742
|
+
**The JSON commands** only read, never through a link, and never change a file in the team folder. Every result says which contract it follows (`flightdeck-read/1`; `--contract 2` adds typed values, conditions and test runs) and names, file by file, anything it couldn't read. Exit code 0: complete; 4: partial (the data is still printed, with each problem listed); 1: no data; 5: no such process, version or run. People-directory email fields are omitted. See [Using Flightdeck from other apps](https://github.com/troylar/flightdeck/blob/main/docs/apps.md).
|
|
743
|
+
|
|
744
|
+
**`flightdeck plan request`** lets another app ask for a run, the way a teammate would put one on the calendar. A monthly script asks for the backup check with `--key 2026-11`; asking again with the same key and the same request changes nothing, and the same key with other details is refused. The request shows under **Runs** as a planned run, "requested by" the tool, by its own account: the name is what the file says, not proof of who wrote it. Nothing starts by itself; a person starts it, changes it or declines it. It writes only in `proposals/`, never through a link. Exit 0 when written, 4 when something it depends on couldn't be read and nothing was written, 1 when it's refused, 5 when there's no such process or version.
|
|
417
745
|
|
|
418
|
-
|
|
746
|
+
**`flightdeck report write`** lets a tool say it did a step's work, in a report the step shows beside what a person decided and whether its inputs match the run. Accepting a passing report checks the step with exactly its evidence; the receipt and Evidence name the report and its hash. See *Reporting work* in [docs/apps.md](https://github.com/troylar/flightdeck/blob/main/docs/apps.md).
|
|
419
747
|
|
|
420
|
-
|
|
748
|
+
**`export`** exits with 0 for a complete pack, 4 for a partial one (made, and it lists at the top what changed or was missing while it read), and 1 when it made no pack. It writes `<name>.zip.partial` as it goes and renames it only when it's done; Ctrl+C or a failure removes it. It uses only the code in its own installed `flightdeck.html`, never a team folder's copy, and never reads through a link. The people directory's email fields are left out; original records and attachments may contain personal information. A pack isn't signed: its hashes show whether its files still match, and comparing its SHA-256 with the one you kept shows whether it's the pack you made. See [Evidence packs](https://github.com/troylar/flightdeck/blob/main/docs/evidence.md).
|
|
421
749
|
|
|
422
|
-
|
|
750
|
+
**Install and skills** sort every `AGENTS.md` and skill file the same way:
|
|
423
751
|
|
|
424
|
-
|
|
752
|
+
- A file that's still a Flightdeck default (this version's or an earlier one) is updated.
|
|
753
|
+
- A file your team changed is left alone. If this version changed that file's default too, the new default goes to `.flightdeck/updates/<version>/`, with a `README.md` holding a prompt for your AI assistant to merge it.
|
|
754
|
+
- In `AGENTS.md` only the part between the `flightdeck:begin` and `flightdeck:end` markers is Flightdeck's. Team notes, below it, are never touched.
|
|
755
|
+
- `.flightdeck/installed.json` records which defaults the folder is based on. It can make install more careful, never less.
|
|
756
|
+
- Every file install replaces is first copied to `.flightdeck/updates/<version>/replaced/`.
|
|
757
|
+
- A file that changes while install runs is left alone, and install exits with 1. Nothing is written through a link or outside the folder (see [Updating Flightdeck](https://github.com/troylar/flightdeck/blob/main/docs/updating.md) for the limits).
|
|
758
|
+
|
|
759
|
+
</details>
|
|
425
760
|
|
|
426
761
|
<br>
|
|
427
762
|
|
|
@@ -429,6 +764,17 @@ Install and skills sort every `AGENTS.md` and skill file the same way. A file th
|
|
|
429
764
|
|
|
430
765
|
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/folder-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/folder-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/folder-light.png" alt="The team folder and who writes each part: people.json and validations by people; drafts and step types by people and your AI assistant; skills, Jira workflows and proposals by your AI assistant; publications and runs by Flightdeck." width="1000"></picture></a></p>
|
|
431
766
|
|
|
767
|
+
Every file has exactly one writer, which keeps ordinary use of a shared folder free of conflicts. When two saves do collide, the replaced one is kept for you to recover. Your AI assistant writes checklists, plans, step types, workflows and skill registrations; tools write reports; people publish, plan, run and sign off.
|
|
768
|
+
|
|
769
|
+
```mermaid
|
|
770
|
+
flowchart LR
|
|
771
|
+
P(["People, in the app"]) --> people["people.json"] & val["validations/"] & dec["corrections/ · followups/<br/>report-decisions/"]
|
|
772
|
+
P & AI(["Your AI assistant"]) --> drafts["maps/drafts/"] & types["step-types/"] & prop["proposals/"]
|
|
773
|
+
AI --> skills["skills/ · skill-registrations/"] & jira["jira/workflows.json"] & proposed["proposed/"]
|
|
774
|
+
FD(["Flightdeck, when people<br/>publish, stage and run"]) --> pubs["publications/"] & staged["staged/"] & runs["runs/"]
|
|
775
|
+
T(["Other apps"]) --> reports["reports/"] & prop
|
|
776
|
+
```
|
|
777
|
+
|
|
432
778
|
<details>
|
|
433
779
|
<summary><b>The folder, as text</b></summary>
|
|
434
780
|
|
|
@@ -436,31 +782,37 @@ Install and skills sort every `AGENTS.md` and skill file the same way. A file th
|
|
|
436
782
|
people.json who's on the team, with the folder owner and backup owner
|
|
437
783
|
maps/drafts/ checklists being written (Markdown)
|
|
438
784
|
publications/ published versions, frozen (Flightdeck writes these)
|
|
785
|
+
staged/ staged versions only test runs use, and each retire or reopen, written once
|
|
439
786
|
runs/ one folder per run: run.json, everyone's notes and corrections, attached files
|
|
440
787
|
skills/ skill registrations: each skill's source, what it implements
|
|
441
|
-
|
|
788
|
+
skill-registrations/ skills registered with flightdeck skill register (Flightdeck 2.0)
|
|
789
|
+
validations/ owners' sign-offs that a version, or a staged version, is ready for a skill
|
|
442
790
|
corrections/ decisions on corrections (applied, declined, reopened, withdrawn), each a file written once
|
|
443
791
|
followups/ what became of each follow-up (done, moved, won't do, reopened), each a file written once
|
|
444
792
|
suggestions/ decisions on suggested fixes from before 1.13 (still read)
|
|
445
793
|
step-types/ your team's own step types (create them in the app)
|
|
446
794
|
jira/workflows.json your real Jira workflows, with required fields
|
|
447
|
-
proposals/ planned runs (from the app
|
|
795
|
+
proposals/ planned runs (from the app, your AI assistant or another app), waiting for a person to start them
|
|
796
|
+
proposed/ draft changes your AI assistant proposed, waiting to be applied or declined
|
|
797
|
+
reports/ reports from tools that did a step's work (flightdeck report write)
|
|
798
|
+
report-decisions/ the recorder's accept or decline on each report
|
|
448
799
|
images/ screenshots that checklists refer to
|
|
800
|
+
history/ saved history of drafts and step types
|
|
801
|
+
presence/ which drafts a window has open, so your AI assistant knows to propose instead of save
|
|
802
|
+
connection/ connection checks between computers (Settings → Folder health)
|
|
449
803
|
AGENTS.md the rules any AI assistant follows in this folder (your own go under Team notes)
|
|
450
804
|
.flightdeck/skills/ the Flightdeck skills for your AI assistant
|
|
451
805
|
.flightdeck/installed.json which Flightdeck defaults AGENTS.md and the skills are based on
|
|
452
|
-
.flightdeck/updates/ new defaults waiting to be merged, and copies of files
|
|
806
|
+
.flightdeck/updates/ new defaults waiting to be merged, and copies of files install replaced
|
|
453
807
|
```
|
|
454
808
|
|
|
455
809
|
</details>
|
|
456
810
|
|
|
457
|
-
Every file has exactly one writer, which keeps ordinary use of a shared folder free of conflicts; when two saves do collide, the replaced one is kept for you to recover. Your AI assistant writes checklists, plans, step types, workflows and skill registrations; people publish, plan, run and sign off.
|
|
458
|
-
|
|
459
811
|
<br>
|
|
460
812
|
|
|
461
813
|
## Skills for your AI assistant
|
|
462
814
|
|
|
463
|
-
`flightdeck install` puts these in the team folder's `.flightdeck/skills/` (`flightdeck skills` does only the skills), or `flightdeck skills --to <dir>` puts them anywhere else. They're plain `SKILL.md` files (a name, a description and instructions), so any assistant that supports skills can use them
|
|
815
|
+
`flightdeck install` puts these in the team folder's `.flightdeck/skills/` (`flightdeck skills` does only the skills), or `flightdeck skills --to <dir>` puts them anywhere else. They're plain `SKILL.md` files (a name, a description and instructions), so any assistant that supports skills can use them. Install them where your assistant looks for skills, or point it at the folder. Then open the team folder with your assistant and ask for one by name:
|
|
464
816
|
|
|
465
817
|
| Skill | Does |
|
|
466
818
|
|---|---|
|
|
@@ -479,18 +831,13 @@ Every file has exactly one writer, which keeps ordinary use of a shared folder f
|
|
|
479
831
|
|
|
480
832
|
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/safe-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/safe-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/safe-light.png" alt="Safe by design: nothing leaves your machine; no server or accounts; saves that check first; built for OneDrive; a careful command; accessible." width="1000"></picture></a></p>
|
|
481
833
|
|
|
482
|
-
<details>
|
|
483
|
-
<summary><b>The details</b></summary>
|
|
484
|
-
|
|
485
834
|
- **Nothing leaves your machine.** The app makes no network requests and loads nothing from the internet; its fonts and code are inside the file.
|
|
486
835
|
- **No server to run, no accounts to manage.** Your data is files in a folder you already control.
|
|
487
|
-
- **One writer per file, and checked saves.**
|
|
488
|
-
- **Built for OneDrive.** Folders that sync a minute late are expected
|
|
489
|
-
- **The command is careful too.** No dependencies, nothing runs on install, no network. It refuses to write through links,
|
|
836
|
+
- **One writer per file, and checked saves.** Before a run is saved, this window checks a SHA-256 of its file's exact text; if it changed since this window read it, this window's version is kept beside it as a copy to compare and keep. Every run save first leaves its own receipt, so if a computer that can't see the change replaces it anyway, the replaced save shows up in the run as a copy, never silently lost. A draft save that finds a change writes nothing and reports the conflict (see [docs/onedrive.md](https://github.com/troylar/flightdeck/blob/main/docs/onedrive.md)).
|
|
837
|
+
- **Built for OneDrive.** Folders that sync a minute late are expected. A gate means "passed for this commit, by this person," never a live lock.
|
|
838
|
+
- **The command is careful too.** No dependencies, nothing runs on install, no network. It refuses to write through links, replaces an existing file only with a complete copy, and never replaces a newer version without `--force`.
|
|
490
839
|
- **Accessible.** Every control has a label, errors sit next to their field, shortcuts can be turned off, and it works with a keyboard.
|
|
491
840
|
|
|
492
|
-
</details>
|
|
493
|
-
|
|
494
841
|
<br>
|
|
495
842
|
|
|
496
843
|
## Coming from Preflight
|
|
@@ -522,6 +869,13 @@ Outside Flightdeck. Your AI assistant writes checklists and builds skills from F
|
|
|
522
869
|
|
|
523
870
|
</details>
|
|
524
871
|
|
|
872
|
+
<details>
|
|
873
|
+
<summary><b>Do I need OneDrive?</b></summary>
|
|
874
|
+
|
|
875
|
+
OneDrive is the setup Flightdeck is tested and documented for, in Edge or Chrome. The app works on any folder the browser can open; what matters is how the folder is shared and synced. [docs/onedrive.md](https://github.com/troylar/flightdeck/blob/main/docs/onedrive.md) explains what a synced folder can and can't promise.
|
|
876
|
+
|
|
877
|
+
</details>
|
|
878
|
+
|
|
525
879
|
<details>
|
|
526
880
|
<summary><b>Can a skill cover only part of a process?</b></summary>
|
|
527
881
|
|
|
@@ -539,14 +893,21 @@ Yes. Ask your AI assistant to draft a checklist from an existing skill, publish
|
|
|
539
893
|
<details>
|
|
540
894
|
<summary><b>Can people edit checklists in the app, or only the AI assistant?</b></summary>
|
|
541
895
|
|
|
542
|
-
Both. The app's editor and your AI assistant write the same draft files. The app saves only over the version you opened and shows both when they differ
|
|
896
|
+
Both. The app's editor and your AI assistant write the same draft files. The app saves only over the version you opened and shows both when they differ. Since a shared folder can't lock a file, edit a draft with one of them at a time.
|
|
543
897
|
|
|
544
898
|
</details>
|
|
545
899
|
|
|
546
900
|
<details>
|
|
547
901
|
<summary><b>The checklist was wrong during a run. What do I do?</b></summary>
|
|
548
902
|
|
|
549
|
-
Select the step and choose **Correct this step** (or press C): change its wording with a live Before/After, or choose **Change something else** for a missing step, the order, who does it, a screenshot or removing it. Attach files to show why. It never answers the step. If you already did the step another way, use **Done differently** beside Done and choose **Fix the checklist too**. Corrections wait on the process page, grouped by step, where anyone
|
|
903
|
+
Select the step and choose **Correct this step** (or press C): change its wording with a live Before/After, or choose **Change something else** for a missing step, the order, who does it, a screenshot or removing it. Attach files to show why. It never answers the step. If you already did the step another way, use **Done differently** beside Done and choose **Fix the checklist too**. Corrections wait on the process page, grouped by step, where anyone reviews and applies one to the draft, marks it applied, or declines it with a reason. Then publish as usual.
|
|
904
|
+
|
|
905
|
+
</details>
|
|
906
|
+
|
|
907
|
+
<details>
|
|
908
|
+
<summary><b>What happens if two people open the same run?</b></summary>
|
|
909
|
+
|
|
910
|
+
Both see it. Only the recorder's window writes the run; every other window rereads it every few seconds and adds notes and files in its own file. To change who records, use **Hand off** (the run names the exact revision passed on) or **Pick up**. If two computers that can't see each other both save, one save can replace the other in `run.json`, but the replaced save is never lost: its receipt stays beside the run, and the run shows a panel to compare and keep the right one.
|
|
550
911
|
|
|
551
912
|
</details>
|
|
552
913
|
|
|
@@ -566,6 +927,12 @@ Keep secrets, tokens and customer data out of checklists, notes and attachments.
|
|
|
566
927
|
|
|
567
928
|
A version or run saved by a newer copy, with checklist features this copy doesn't understand, is shown with the reason and "Update Flightdeck to run it." It can't be started here, and a run on it opens read-only, so an older copy never records over what a newer one wrote. Put the newest `flightdeck.html` in the team folder; anyone on an older copy sees that a newer one is there.
|
|
568
929
|
|
|
930
|
+
Moving from 1.x to 2.0: put Flightdeck 1.21 or later on every computer first, then 2.0, and only then start using 2.0 features. **Settings → Folder health** names older copies it saw in the last 7 days. [Updating Flightdeck](https://github.com/troylar/flightdeck/blob/main/docs/updating.md#when-computers-run-different-versions) has the details.
|
|
931
|
+
|
|
932
|
+
Moving from 2.0 to 2.1: put 2.1 in the team folder and have everyone reopen it before anyone publishes a checklist with `only when`. Flightdeck 2.0 shows such a version as "needs Flightdeck 2.1" and can't run it. Staged versions and test runs show only on 2.1, and a version made the default from a stage is an ordinary version: any copy that understands the features it uses can run it (one with `only when` needs 2.1).
|
|
933
|
+
|
|
934
|
+
**Known issue:** an older copy shows a test run by name only and never changes it, but counts it in Home's running number, and How runs go and Compare versions list its stage as one more version (marked Clash once that stage is made the default). Updating to 2.1 fixes both.
|
|
935
|
+
|
|
569
936
|
</details>
|
|
570
937
|
|
|
571
938
|
<details>
|
|
@@ -584,6 +951,20 @@ The top bar shows the version and **What's new**, the full searchable history. I
|
|
|
584
951
|
|
|
585
952
|
<br>
|
|
586
953
|
|
|
954
|
+
## More docs
|
|
955
|
+
|
|
956
|
+
| Doc | For | You'll get |
|
|
957
|
+
|---|---|---|
|
|
958
|
+
| [Checklist format](https://github.com/troylar/flightdeck/blob/main/docs/map-format.md) | Anyone writing checklists, and their AI assistant | Every mark, field and step type, and what stops a checklist from publishing |
|
|
959
|
+
| [Flightdeck and OneDrive](https://github.com/troylar/flightdeck/blob/main/docs/onedrive.md) | Whoever sets up the team folder | What keeps runs safe on a synced folder, and what it can't promise |
|
|
960
|
+
| [Updating Flightdeck](https://github.com/troylar/flightdeck/blob/main/docs/updating.md) | Whoever keeps the team's copy current | A step-by-step update, mixed versions and rolling back |
|
|
961
|
+
| [When something goes wrong](https://github.com/troylar/flightdeck/blob/main/docs/recovery.md) | Anyone who sees a warning | What each problem means and what to do, step by step |
|
|
962
|
+
| [Evidence packs](https://github.com/troylar/flightdeck/blob/main/docs/evidence.md) | Anyone who needs proof of a run | What's in a pack and how to check it |
|
|
963
|
+
| [Using Flightdeck from other apps](https://github.com/troylar/flightdeck/blob/main/docs/apps.md) | Script and tool authors | The JSON commands, run requests, reports and the draft contract |
|
|
964
|
+
| [Design](https://github.com/troylar/flightdeck/blob/main/docs/design.md) | Contributors | The full specification and its decisions |
|
|
965
|
+
|
|
966
|
+
<br>
|
|
967
|
+
|
|
587
968
|
## License
|
|
588
969
|
|
|
589
970
|
[MIT](https://unpkg.com/@troylar/flightdeck/LICENSE). The embedded Barlow Condensed fonts are licensed under the SIL Open Font License 1.1; see [`dist/FONT-LICENSE.txt`](https://unpkg.com/@troylar/flightdeck/dist/FONT-LICENSE.txt).
|