@troylar/flightdeck 2.5.0 → 2.6.1
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 +26 -0
- package/README.md +198 -709
- package/bin/flightdeck.js +3 -1
- package/dist/flightdeck.html +482 -84
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,9 +8,9 @@
|
|
|
8
8
|
[](#license)
|
|
9
9
|
[](#safe-by-design)
|
|
10
10
|
[](#safe-by-design)
|
|
11
|
-
[](#
|
|
11
|
+
[](#quick-start)
|
|
12
12
|
|
|
13
|
-
**[
|
|
13
|
+
**[Quick start](#quick-start)** · **[How it works](#how-it-works)** · **[Checklist format](#the-checklist-format)** · **[Process to skill](#process-to-skill)** · **[Command line](#command-line)** · **[FAQ](#faq)**
|
|
14
14
|
|
|
15
15
|
</div>
|
|
16
16
|
|
|
@@ -18,496 +18,163 @@
|
|
|
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
|
-
- **What it is:** one HTML file. No server, no sign-in, no network, no AI inside. It runs offline in Edge or Chrome.
|
|
21
|
+
- **What it is:** one HTML file. No server, no sign-in, no network, no AI inside. It runs offline in Edge or Chrome, on a folder your team shares (OneDrive is the tested setup).
|
|
22
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:**
|
|
23
|
+
- **Why it's different:** the 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.
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
## Quick start
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
|
|
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>
|
|
48
|
-
|
|
49
|
-
<br>
|
|
27
|
+
1. `npx @troylar/flightdeck open` opens the app in your browser (needs Node 18 or later).
|
|
28
|
+
2. No Node? Save [flightdeck.html](https://unpkg.com/@troylar/flightdeck@2.6.1/dist/flightdeck.html) from the npm package as a file (right-click, **Save link as…**) and open that file in Edge or Chrome.
|
|
29
|
+
3. Choose **Look around the examples** to try it, or **Start your team** to set up your team's folder.
|
|
50
30
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
**1. Write a checklist.** It's a Markdown file in your team folder. This one is complete:
|
|
54
|
-
|
|
55
|
-
```markdown
|
|
56
|
-
---
|
|
57
|
-
process: docs
|
|
58
|
-
title: Publish the docs
|
|
59
|
-
owner: person-casey
|
|
60
|
-
context: commit
|
|
61
|
-
---
|
|
62
|
-
|
|
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}
|
|
31
|
+
<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 with Details, Screen share, Receipt and More; 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, whose text shows the run's tag (Start the production deploy job v2026.10.16), with the values to copy, Record the result, Done, Done differently and Blocked" width="1000"></picture></a></p>
|
|
67
32
|
|
|
68
|
-
##
|
|
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, and the run shows its value in the step's text (`‹commit›` until it's set). 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.
|
|
124
|
-
|
|
125
|
-
<br>
|
|
126
|
-
|
|
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).
|
|
159
|
-
|
|
160
|
-
### 4. A run is a recording
|
|
161
|
-
|
|
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
|
-
```
|
|
33
|
+
## Words this README uses
|
|
214
34
|
|
|
215
|
-
|
|
35
|
+
- A **process** is something your team does; the app lists them under **Processes**. Its **checklist** is the steps, written as Markdown and published as numbered **versions** (v1, v2, …).
|
|
36
|
+
- A **run** is one time through a checklist. One person **records** it (the **recorder**); everyone else follows along.
|
|
37
|
+
- A **window** is one open Flightdeck tab. Some file names include the window that wrote them.
|
|
38
|
+
- A **run detail** is a value a run carries, like the commit or the release tag. Steps refer to one as `^commit`.
|
|
39
|
+
- A **gate** ends a phase. Nothing after it opens until someone passes it, and it approves exactly what it says.
|
|
40
|
+
- The **Receipt** is a run's printable summary page. A **save receipt** is a file (`candidate-<window>-<save>.json`) a window writes before each run save, so a replaced save is never lost. They are different things.
|
|
216
41
|
|
|
217
|
-
|
|
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.
|
|
42
|
+
## Getting started
|
|
219
43
|
|
|
220
|
-
|
|
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>
|
|
249
|
-
|
|
250
|
-
<br>
|
|
251
|
-
|
|
252
|
-
## Install
|
|
44
|
+
**Install the command** (or use `npx @troylar/flightdeck <command>` each time):
|
|
253
45
|
|
|
254
46
|
```bash
|
|
255
47
|
npm install -g @troylar/flightdeck
|
|
256
|
-
|
|
257
|
-
flightdeck open # opens the app: start your team, join one, or look around the examples
|
|
48
|
+
flightdeck open
|
|
258
49
|
```
|
|
259
50
|
|
|
260
|
-
The first screen
|
|
51
|
+
`flightdeck open` opens the app that came with the package. The first time, it shows the welcome screen. After that it opens the team folder you chose, when the browser kept it and its permission; otherwise the top bar says **The team folder needs your OK again** with a **Reconnect** button.
|
|
261
52
|
|
|
262
53
|
| Choice | Who | What happens |
|
|
263
54
|
|---|---|---|
|
|
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.
|
|
55
|
+
| **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. Home shows **Getting started · N of 5** to the folder owner and backup owner until all five are done. |
|
|
265
56
|
| **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. |
|
|
57
|
+
| **Look around the examples** | Anyone curious | A made-up team, saved in this browser only. Choose **Casey Nguyen** in the top right to see what a checklist owner sees. |
|
|
267
58
|
|
|
268
|
-
**
|
|
59
|
+
**After setup**, put Flightdeck in the team folder so everyone opens the same version:
|
|
269
60
|
|
|
270
61
|
```bash
|
|
271
62
|
flightdeck install ~/OneDrive/Team # adds flightdeck.html; keeps the AGENTS.md and skills setup wrote
|
|
272
63
|
```
|
|
273
64
|
|
|
274
|
-
|
|
275
|
-
|
|
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.
|
|
279
|
-
|
|
280
|
-
> **Prefer no npm?** `flightdeck.html` is self-contained. Copy it anywhere and open it.
|
|
281
|
-
|
|
282
|
-
<br>
|
|
283
|
-
|
|
284
|
-
## A tour
|
|
285
|
-
|
|
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.
|
|
287
|
-
|
|
288
|
-
<table>
|
|
289
|
-
<tr>
|
|
290
|
-
<td width="50%" valign="top">
|
|
291
|
-
|
|
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.
|
|
293
|
-
|
|
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>
|
|
295
|
-
|
|
296
|
-
</td>
|
|
297
|
-
<td width="50%" valign="top">
|
|
298
|
-
|
|
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.
|
|
300
|
-
|
|
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>
|
|
302
|
-
|
|
303
|
-
</td>
|
|
304
|
-
</tr>
|
|
305
|
-
<tr>
|
|
306
|
-
<td valign="top">
|
|
65
|
+
Run it after setup, not before: setup wants an empty folder. Teammates then open `flightdeck.html` from the team folder in Edge or Chrome. Setting the folder up in OneDrive is covered in [Flightdeck and OneDrive](https://github.com/troylar/flightdeck/blob/main/docs/onedrive.md#set-up).
|
|
307
66
|
|
|
308
|
-
**
|
|
67
|
+
**Finding your way around.** The top bar has **Home**, **Runs**, **Processes** and **Settings**. **Skills** and **Step types** open from the Processes page, from Settings and from search (Ctrl+K, or Cmd+K on a Mac), which finds runs, steps, notes, corrections, follow-ups, step types and skills, and keeps its index in memory on your computer.
|
|
309
68
|
|
|
310
|
-
|
|
69
|
+
**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. **Processes** lists every process in your team's own groups, with **Filter by tag** and each one's version and last run. **New process** starts one.
|
|
311
70
|
|
|
312
|
-
|
|
313
|
-
<td valign="top">
|
|
71
|
+
<p align="center"><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: the things that need Casey, each with one button, then Your follow-ups with Done, Moved to a ticket, Moved to another run and Won't do" width="49%"></picture></a> <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 processes grouped by hierarchy, each with its version, when it last ran and its skills, with Filter by tag, and Skills, Step types and New process at the top" width="49%"></picture></a></p>
|
|
314
72
|
|
|
315
|
-
|
|
316
|
-
|
|
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>
|
|
318
|
-
|
|
319
|
-
</td>
|
|
320
|
-
</tr>
|
|
321
|
-
<tr>
|
|
322
|
-
<td valign="top">
|
|
73
|
+
## How it works
|
|
323
74
|
|
|
324
|
-
|
|
75
|
+
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/loop-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/loop-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/loop-light.png" alt="The Flightdeck loop: write a checklist, practice it, publish it as a frozen version, run it, and learn from the runs, with corrections flowing back into the next version; proven versions are handed to an AI assistant as skills" width="1000"></picture></a></p>
|
|
325
76
|
|
|
326
|
-
|
|
77
|
+
The loop is five steps: **write** a checklist, **practice** it, **publish** it, **run** it, and **learn** from the runs. Proven versions then become skills for your AI assistant ([Process to skill](#process-to-skill)).
|
|
327
78
|
|
|
328
|
-
|
|
329
|
-
<td valign="top">
|
|
79
|
+
### 1. Write a checklist
|
|
330
80
|
|
|
331
|
-
|
|
81
|
+
A checklist is a Markdown file a person can read and an AI assistant can write. This one is complete:
|
|
332
82
|
|
|
333
|
-
|
|
83
|
+
```markdown
|
|
84
|
+
---
|
|
85
|
+
process: docs
|
|
86
|
+
title: Publish the docs
|
|
87
|
+
owner: person-casey
|
|
88
|
+
context: commit
|
|
89
|
+
---
|
|
334
90
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
91
|
+
## Build · DO-CONFIRM {#build}
|
|
92
|
+
- [!] {run.command} Docs build with no warnings ^commit {#build-docs}
|
|
93
|
+
command: npm run docs
|
|
94
|
+
- [ ] {confirm} Screenshots match the current app {#shots}
|
|
339
95
|
|
|
340
|
-
|
|
96
|
+
## Gate: Ready to publish {#ready}
|
|
97
|
+
approves: publishing `^commit`
|
|
341
98
|
|
|
342
|
-
|
|
99
|
+
## Publish · READ-DO {#publish}
|
|
100
|
+
- [!] {run.command} Push the site ^commit {#push}
|
|
101
|
+
command: npm run docs:publish
|
|
102
|
+
```
|
|
343
103
|
|
|
344
|
-
|
|
345
|
-
<td valign="top">
|
|
104
|
+
Two phases, three steps and 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.
|
|
346
105
|
|
|
347
|
-
|
|
106
|
+
You don't have to write Markdown. **New process** on the Processes page asks for a title and opens the editor with the **Add a step** box ready: type a step, press Enter, type the next. The group, tags, run details, roles, owner and file name are under **More options**. You can also start from Code check-in or Weekly review, or copy a prompt for your AI assistant.
|
|
348
107
|
|
|
349
|
-
|
|
108
|
+
**Edit** on a process page opens its draft on a page of its own: the **Builder** (an outline) or the **Markdown**, beside **Checks** (what blocks publishing, and what's only a tip) and a **Preview**. Both views edit the same file; the builder changes only the lines you touch and never a step ID. Your AI assistant's changes to a draft you have open, with nothing unsaved, show up within seconds, marked and one Undo away.
|
|
350
109
|
|
|
351
|
-
|
|
352
|
-
</tr>
|
|
353
|
-
<tr>
|
|
354
|
-
<td valign="top">
|
|
110
|
+
<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 editor's Builder, with Save draft and Review & publish in the header: 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, scrolled to its Fields: each box asks a question (Which job?, Which parameters?, Which stage do you watch?) with a short why under it, then + Job page for a box it doesn't usually need, and How long does it usually take?" width="1000"></picture></a>
|
|
355
111
|
|
|
356
|
-
**
|
|
112
|
+
**The step form** asks a question for each box, with a gray example and why it matters. It shows only the boxes the step's type usually needs, and any that hold a value; the rest are one click away behind **+ add** buttons. The fields every step accepts (a link, how long it takes, a deadline, proof, a time) are under **More about this step**. A choice of five or fewer is a row of buttons. **When it's checked, they record** lists exactly what a run will ask for. In the outline, drag a step or press Alt+Up / Alt+Down to move it, and **Undo** and **Redo** step through changes.
|
|
357
113
|
|
|
358
|
-
|
|
114
|
+
**Save draft** saves your work. **Review & publish** goes back to the process page: there you can compare the draft with the last version, write what changed in one line, and choose **Publish vN**. Anything that blocks publishing disables the button; suggestions don't. A save goes through only if the draft is still what you opened; if a teammate changed it meanwhile, nothing is saved and you choose between their version and yours. A shared folder can't lock a file, so edit a draft with one person (or one AI assistant) at a time.
|
|
359
115
|
|
|
360
|
-
|
|
361
|
-
<td valign="top">
|
|
116
|
+
<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, with Practice, Save draft and Review & publish in the header: the open corrections with links to their lines, the Markdown on the left, and the Checks and Preview tabs on the right"></picture></a>
|
|
362
117
|
|
|
363
|
-
|
|
118
|
+
### 2. Practice it, and stage it
|
|
364
119
|
|
|
365
|
-
|
|
120
|
+
**Practice** in the editor runs the draft on the real run screen, marked **Practice · not recorded**: check steps, pass gates and give run details sample values, as a run would. **Edit** on a step or gate takes you to the editor with it selected; **Back to practice** returns you to the same place, with the steps you changed marked **Try it again**. **Run from here** starts partway. Practice lives in this browser tab only (a `#/practice/<process>` link reopens it); nothing is written to the team folder and it never counts as a run. Links and commands you follow still act on real systems.
|
|
366
121
|
|
|
367
|
-
|
|
368
|
-
</tr>
|
|
369
|
-
<tr>
|
|
370
|
-
<td valign="top">
|
|
122
|
+
To rehearse a change with real people before everyone uses it, **stage** it. A staged version is tried by **test runs** while every real run stays on the current default:
|
|
371
123
|
|
|
372
|
-
|
|
124
|
+
1. **Stage it.** At the end of Practice, write what changed and choose **Stage it for a test run**; or on the process page open **All versions** and choose **Stage the draft for testing**. It's written once to `staged/` and never edited.
|
|
125
|
+
2. **Try it.** **Start a test run** on the staged line. A test run is recorded like any run but is labeled **Test run** everywhere it shows, and it's never counted as a real run: How runs go, Home's running number, last-run dates and role rotation leave it out. Its follow-ups and corrections are real.
|
|
126
|
+
3. **Prove it.** The staged line counts clean test runs ("2 of 3 clean test runs"). With three, the owner, or the backup owner while the owner is away, gets **Sign off staged v3**.
|
|
127
|
+
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). Its clean test runs and sign-off then count for that version.
|
|
373
128
|
|
|
374
|
-
|
|
129
|
+
**Retire** sets a stage aside and **Reopen** brings it back; each is logged with who did it. Plans never start a test run, and a test run starts no linked runs.
|
|
375
130
|
|
|
376
|
-
|
|
377
|
-
<td valign="top">
|
|
131
|
+
<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 board step applies only when risk is high. The next phase, behind its gate, offers Preview steps." width="1000"></picture></a></p>
|
|
378
132
|
|
|
379
|
-
|
|
133
|
+
### 3. Publish it
|
|
380
134
|
|
|
381
|
-
|
|
135
|
+
Publishing freezes the checklist as a numbered version, with who, when and why, in a folder that is written once and never changed. Every run keeps the version it started on, forever, and carries its own copy of the checklist and step types, so it reads the same years later. Before you publish, the panel names anything the draft uses that older copies can't run, under **Needs Flightdeck 2.0** or **Needs Flightdeck 2.1**.
|
|
382
136
|
|
|
383
|
-
|
|
384
|
-
</tr>
|
|
385
|
-
</table>
|
|
137
|
+
A process page shows its checklist (as **Checklist**, **Flight plan** or **Markdown**), **Start a run**, **Plan a run**, **How runs go** and its versions; an older version offers **Restore as draft**. Its owner and backup owner also see open corrections, **Ready for a skill?** and its skills; everyone else sees each of those as one line.
|
|
386
138
|
|
|
387
|
-
<
|
|
388
|
-
<summary><b>More on corrections</b></summary>
|
|
139
|
+
<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, the Checklist, Flight plan and Markdown views, Edit, Start a run and Plan a run, and the Corrections panel with two open corrections" width="1000"></picture></a>
|
|
389
140
|
|
|
390
|
-
|
|
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.
|
|
141
|
+
### 4. Run it
|
|
395
142
|
|
|
396
|
-
|
|
143
|
+
**Start a run** and type the run's details. Or **Plan a run** for later, with the details you know, who does what and an optional time; nothing starts until a person starts it, and a plan starts on the version it was planned on until you switch it. **Plan another like this** on any run copies its details and roles, never its answers.
|
|
397
144
|
|
|
398
|
-
|
|
145
|
+
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/runs-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/runs-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/runs-light.png" alt="Runs: one release running, two planned releases (one by Casey Nguyen with a time, one requested by an AI assistant), the newest finished runs, and a More menu with Export evidence…" width="49%"></picture></a> <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" width="49%"></picture></a></p>
|
|
399
146
|
|
|
400
|
-
|
|
147
|
+
The run screen fills the window:
|
|
401
148
|
|
|
402
149
|
| Part | What it shows |
|
|
403
150
|
|---|---|
|
|
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** (
|
|
406
|
-
| **Phases** | Each phase and its gate's state,
|
|
407
|
-
| **Checklist** | Every step, with **Next up** pinned at the top.
|
|
408
|
-
| **Selected step** |
|
|
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**. Passing a gate moves to what Next up names: the next phase's open step, the next gate or **Finish**. 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>
|
|
421
|
-
|
|
422
|
-
<br>
|
|
423
|
-
|
|
424
|
-
## What it does
|
|
425
|
-
|
|
426
|
-
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/features-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/features-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/features-light.png" alt="Eight features: gates that approve exactly what they say; one recorder with everyone watching; typed steps for Jenkins, Bitbucket, Jira and commands; real Jira workflows with required fields; clock times, deadlines, tracks and pauses; linked runs of other processes; run details that flow to later steps; and insights from every run." width="1000"></picture></a></p>
|
|
427
|
-
|
|
428
|
-
<details>
|
|
429
|
-
<summary><b>Every feature, in detail</b></summary>
|
|
430
|
-
|
|
431
|
-
<table>
|
|
432
|
-
<tr>
|
|
433
|
-
<td width="50%" valign="top">
|
|
434
|
-
|
|
435
|
-
### Checklists with teeth
|
|
436
|
-
Every phase ends at a **gate**. Nothing after it opens until someone passes it, and a gate approves exactly what it says: `deploy of d9d8514 to production`. Must-do steps can't be skipped. Change the commit mid-run and every step tied to it comes back for a re-check.
|
|
437
|
-
|
|
438
|
-
</td>
|
|
439
|
-
<td width="50%" valign="top">
|
|
440
|
-
|
|
441
|
-
### One recorder, everyone watching
|
|
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.
|
|
443
|
-
|
|
444
|
-
</td>
|
|
445
|
-
</tr>
|
|
446
|
-
<tr>
|
|
447
|
-
<td valign="top">
|
|
448
|
-
|
|
449
|
-
### Steps that know their tools
|
|
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.
|
|
451
|
-
|
|
452
|
-
</td>
|
|
453
|
-
<td valign="top">
|
|
454
|
-
|
|
455
|
-
### Jira, the way it really is
|
|
456
|
-
Point Flightdeck at your real Jira workflow and a transition can't publish if Jira can't make it. Checking it asks for the transition's required fields, with a hint for each, and fills in the ones it can from the run.
|
|
457
|
-
|
|
458
|
-
</td>
|
|
459
|
-
</tr>
|
|
460
|
-
<tr>
|
|
461
|
-
<td valign="top">
|
|
462
|
-
|
|
463
|
-
### Time, tracks and pauses
|
|
464
|
-
Give a step a clock time, a deadline, or "within 2 hours of starting" and it gets a badge, a place on the day timeline, and a reminder. Split a phase into parallel tracks. Pause a run with a reason; paused time never counts.
|
|
465
|
-
|
|
466
|
-
</td>
|
|
467
|
-
<td valign="top">
|
|
468
|
-
|
|
469
|
-
### Processes inside processes
|
|
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.
|
|
151
|
+
| **Header** | How far it is (`7/15 answered`), **Details**, **Screen share**, **Receipt** and **More** (with **Copy run key** and **Export evidence…**). A test run says **Test run** beside its name. |
|
|
152
|
+
| **Recording strip** | Who's recording, with **Pause** and **Hand off** (which names the exact revision passed on), the run's details, and what this window saved and when it last checked the folder. Another window sees **Pick up recording** (when it was handed to you), **Record here** (when you're recording elsewhere) or **Take over recording** (for emergencies, when the recorder's computer is gone). |
|
|
153
|
+
| **Phases** | Each phase and its gate's state by name ("Confirm deploy · Passed"), the day timeline and follow-ups. |
|
|
154
|
+
| **Checklist** | Every step, with **Next up** pinned at the top. Step text shows the run's details: `Start the production deploy job v2026.10.16`, or `‹tag›` until the tag is set. A phase behind its gate offers **Preview steps**; 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. |
|
|
155
|
+
| **Selected step** | What to do (only when there's something to say), the values to copy, the evidence to record (**Fill in** only when there's something to fill in), then **Done**, **Done differently**, **Blocked** and **N/A**, and its corrections and notes. |
|
|
471
156
|
|
|
472
|
-
|
|
473
|
-
</tr>
|
|
474
|
-
<tr>
|
|
475
|
-
<td valign="top">
|
|
157
|
+
Check the step Next up points at and the next one is selected, ready for **Space**. Typed evidence and unsent notes stay with their step while you move around. Notes and corrections take files (drop, paste or **Attach**): images, PDF, text and logs, CSV, JSON, YAML and .zip, up to 10 MB each. On a phone the checklist scrolls and a step opens as a full-screen sheet.
|
|
476
158
|
|
|
477
|
-
|
|
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.
|
|
159
|
+
Every answer keeps who and when, and a re-check keeps the earlier answer as history. A gate remembers what it approved: change the commit mid-run, and the gate and every step tied to `^commit` come back for a re-check. A run can be paused with a reason (paused time never counts) and ends with **End run…** as Completed, Stopped early or Canceled.
|
|
479
160
|
|
|
480
|
-
|
|
481
|
-
<td valign="top">
|
|
161
|
+
### 5. Learn from runs
|
|
482
162
|
|
|
483
|
-
|
|
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.
|
|
163
|
+
When the checklist is wrong mid-run, anyone can **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, with files to show why. If you already did it another way, **Done differently** asks what happened and offers **Fix the checklist too**.
|
|
485
164
|
|
|
486
|
-
|
|
487
|
-
</tr>
|
|
488
|
-
<tr>
|
|
489
|
-
<td valign="top">
|
|
165
|
+
<p align="center"><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" width="49%"></picture></a> <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" width="49%"></picture></a></p>
|
|
490
166
|
|
|
491
|
-
|
|
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).
|
|
167
|
+
Corrections wait on the process page, grouped by step ("Suggested in 2 runs"). **Review and apply** shows what the run's version said, the draft now and the result side by side, and applies it to the draft as one change you can undo; you can also **Mark as applied**, **Decline** with a reason, or copy a correction brief for your AI assistant. The version that includes it records that, its runs show **Changed in v5** with **Why is this here?**, and Home tells whoever suggested it.
|
|
493
168
|
|
|
494
|
-
|
|
495
|
-
<td valign="top">
|
|
169
|
+
**How runs go** shows typical time per phase, the steps that go off-script most, and who has held each role. **Flight plan** draws a version's shape: phases as waypoints, gates as checkpoints, tracks side by side, and, from its runs, typical times, autopilot (steps skills cover) and turbulence (steps that go off-script most).
|
|
496
170
|
|
|
497
|
-
|
|
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).
|
|
171
|
+
<p align="center"><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" width="1000"></picture></a></p>
|
|
499
172
|
|
|
500
|
-
|
|
501
|
-
</tr>
|
|
502
|
-
</table>
|
|
503
|
-
|
|
504
|
-
</details>
|
|
505
|
-
|
|
506
|
-
<br>
|
|
173
|
+
<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/features-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/features-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/features-light.png" alt="Eight features: gates that approve exactly what they say; one recorder with everyone watching; typed steps for Jenkins, pull requests, Jira and commands; real Jira workflows with required fields; clock times, deadlines, tracks and pauses; linked runs of other processes; run details that flow to later steps; and insights from every run." width="1000"></picture></a></p>
|
|
507
174
|
|
|
508
175
|
## The checklist format
|
|
509
176
|
|
|
510
|
-
|
|
177
|
+
Your AI assistant writes checklists; people edit and publish them in the editor. A fuller one:
|
|
511
178
|
|
|
512
179
|
```markdown
|
|
513
180
|
---
|
|
@@ -540,10 +207,11 @@ roles: release-lead, qa, backend
|
|
|
540
207
|
| Mark | Means |
|
|
541
208
|
|---|---|
|
|
542
209
|
| `[!]` · `[ ]` · `[~]` | Must do · a step · automation planned |
|
|
543
|
-
| `
|
|
210
|
+
| `READ-DO` · `DO-CONFIRM` | How a phase is worked; the app shows "Read, then do" and "Do, then confirm" |
|
|
211
|
+
| `{type}` | The step's type, so it knows its fields and evidence ([Step types](#step-types)) |
|
|
544
212
|
| `@role` · `^detail` | Who does it · a run detail it depends on (change the detail, redo the step) |
|
|
545
213
|
| `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
|
|
214
|
+
| `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 |
|
|
547
215
|
| `## Gate:` · `approves:` | The pause point, and exactly what passing it approves |
|
|
548
216
|
| `### Track: Name @role` | Parallel work inside a phase |
|
|
549
217
|
| `at:` · `due:` · `after:` | A clock time, a deadline, or a due time after the run starts |
|
|
@@ -552,232 +220,80 @@ roles: release-lead, qa, backend
|
|
|
552
220
|
| `context: rows:number, due:date` | Typed run details (number, yes-no, date, choice, link), checked as they're typed |
|
|
553
221
|
| `> note` · `` | A note or screenshot, under a step, a phase or a gate |
|
|
554
222
|
|
|
555
|
-
|
|
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.
|
|
223
|
+
**Branching** is `sets:` plus `only when`: one step sets a detail, and a later step or phase applies only when it matches. A step a run doesn't need isn't counted and nobody checks it; a phase it doesn't need is skipped with its gate.
|
|
558
224
|
|
|
559
|
-
Typed details, phase notes, phase and gate screenshots
|
|
225
|
+
Typed details, phase notes, phase and gate screenshots and `version:` need Flightdeck 2.0; `only when` needs 2.1. Teammates on an older copy see such a version but can't run it. Every mark, field and rule, and what stops a checklist from publishing, is in [the checklist format](https://github.com/troylar/flightdeck/blob/main/docs/map-format.md).
|
|
560
226
|
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
## Manage your templates in the app
|
|
564
|
-
|
|
565
|
-
A process is one page, with its checklist in the middle.
|
|
566
|
-
|
|
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** | **Practice** in the editor runs the draft as you edit it, recording nothing. When you get through it, **Stage it for a test run** right there (or 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. |
|
|
227
|
+
## Step types
|
|
576
228
|
|
|
577
|
-
|
|
578
|
-
<summary><b>The editor in detail</b></summary>
|
|
579
|
-
|
|
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. In **Add a step**, Enter adds the step and keeps the box open for the next one; Enter on an empty box or Escape closes 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 **Review & publish**. **Publish** appears when the draft has saved changes, and stays off while there are unsaved edits.
|
|
586
|
-
|
|
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>
|
|
229
|
+
Built-in types cover common work and tools: `confirm`, `communicate`, `meeting`, `decide`, `review`, `wait`, `ui.action`, `jenkins.job`, `github.pr`, `bitbucket.pr`, `jira.issue`, `jira.sprint`, `ci.gate`, `deploy`, `verify.health`, `measure`, `run.command`, `run.script`, `run.skill` and `run.process`. Each asks for the evidence that matters (a build number, a link, a decision), and evidence can be typed (a number, yes or no, a date) and is checked as you type it.
|
|
599
230
|
|
|
600
|
-
**
|
|
231
|
+
**Pull requests are one step in the editor.** The parts box and type picker show one **Pull request**, whose first question is **Where is the pull request?** (GitHub or Bitbucket). Checklist files, reports and the JSON commands still say `github.pr` or `bitbucket.pr`. The `approve` action, the `pull:` field and the `checks` record exist only on GitHub: switching a step to Bitbucket keeps those values, flags them, and publishing refuses them until you remove them.
|
|
601
232
|
|
|
602
|
-
|
|
233
|
+
**Your team's own types** (a change request, a security sign-off) come first on the Step types page. **New step type**, or **Copy to a team type** on any built-in, opens a form for its fields (what a checklist can say about the step) and its evidence (what's recorded when it's checked). **Save step type** writes `step-types/<id>.json`, usable at once; publishing freezes it into each version. Or ask your AI assistant: `/flightdeck-new-step-type a change request the CAB approves, with the change number as evidence`.
|
|
603
234
|
|
|
604
|
-
|
|
235
|
+
<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 Copy to a team type" width="1000"></picture></a></p>
|
|
605
236
|
|
|
606
|
-
|
|
237
|
+
**Jira, the way it really is.** Describe your real Jira workflows in `jira/workflows.json`, and a transition can't publish if Jira can't make it; checking it asks for the transition's required fields. Flightdeck never calls Jira, Jenkins or any other tool.
|
|
607
238
|
|
|
608
|
-
|
|
239
|
+
## Process to skill
|
|
609
240
|
|
|
610
|
-
|
|
611
|
-
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.
|
|
612
|
-
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**.
|
|
613
|
-
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.
|
|
241
|
+
This is what Flightdeck is for. Outside the team it's usually called **SOP-to-skill**: turning a standard operating procedure into an AI agent skill. Flightdeck adds **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.
|
|
614
242
|
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
<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>
|
|
618
|
-
|
|
619
|
-
<br>
|
|
620
|
-
|
|
621
|
-
## Your own step types
|
|
622
|
-
|
|
623
|
-
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:
|
|
624
|
-
|
|
625
|
-
1. **Step types → New step type**, or **Copy to a team type** on any built-in.
|
|
626
|
-
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.
|
|
627
|
-
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.
|
|
628
|
-
|
|
629
|
-
Or describe it to your AI assistant: `/flightdeck-new-step-type a change request the CAB approves, with the change number as evidence`.
|
|
630
|
-
|
|
631
|
-
<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>
|
|
632
|
-
|
|
633
|
-
<br>
|
|
634
|
-
|
|
635
|
-
## Process-to-skill traceability
|
|
636
|
-
|
|
637
|
-
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.
|
|
638
|
-
|
|
639
|
-
<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>
|
|
640
|
-
|
|
641
|
-
- **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.
|
|
642
|
-
- **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.
|
|
643
|
-
- **Changes flagged.** Publish a new version and Flightdeck shows which registered skills follow steps that changed, and which are still current.
|
|
644
|
-
- **Fixes, briefed.** One click copies an update brief: the before and after of each changed step, and the process as it is now.
|
|
645
|
-
- **Evidence kept.** Every run keeps who checked each step, what was marked N/A, and where people did it differently.
|
|
646
|
-
|
|
647
|
-
<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>
|
|
648
|
-
|
|
649
|
-
<details>
|
|
650
|
-
<summary><b>How it works, step by step</b></summary>
|
|
243
|
+
<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 or backup 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>
|
|
651
244
|
|
|
652
|
-
**1. Prove a version.**
|
|
245
|
+
**1. Prove a version.** **Ready for a skill?** on the process page counts clean runs. A run is clean only when it ended Completed; every covered step was done; every gate on that work (and the one before it) was passed; nothing was blocked, re-checked, marked N/A or done differently, even in answers since archived; it has no unresolved conflict copies; and it kept a full record of deviations from its start (runs from before 1.9.0 can't show that). A step the run didn't need isn't held against it. A test run counts only for its staged version and the version made from exactly what was staged.
|
|
653
246
|
|
|
654
|
-
- it
|
|
655
|
-
- every covered step was done;
|
|
656
|
-
- every gate on that work (and the one before it) was passed;
|
|
657
|
-
- nothing was blocked, re-checked, marked N/A or done differently, even in answers since archived.
|
|
247
|
+
**2. Sign off.** With three clean runs, the process owner signs the version off. The backup owner's sign-off counts too, recorded as the backup's, and Flightdeck offers it only while the owner is away (marked inactive or no longer on the team). A sign-off counts only for that exact published version, or, with **Sign off staged v3**, for the staged version and the version made from it.
|
|
658
248
|
|
|
659
|
-
|
|
249
|
+
**3. Brief your AI assistant.** One click copies a brief: the process in order, with every step's fields, evidence and screenshots, every gate and what it approves, the run details it receives, what people actually did differently, and how to register the skill.
|
|
660
250
|
|
|
661
|
-
**
|
|
251
|
+
**4. Register the skill.** It can live anywhere: a repo, a shared folder, a local path. Your AI assistant registers it with the command, which checks the version exists and records it exactly, with fingerprints, in `skill-registrations/`:
|
|
662
252
|
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
253
|
+
```bash
|
|
254
|
+
flightdeck skill register ~/OneDrive/Team --from registration.json --json
|
|
255
|
+
```
|
|
666
256
|
|
|
667
257
|
```json
|
|
668
258
|
{
|
|
669
259
|
"name": "release-deploy",
|
|
670
260
|
"version": "1.3.0",
|
|
671
261
|
"location": "https://git.example.com/team-skills/release-deploy",
|
|
672
|
-
"implements": "release
|
|
673
|
-
"steps": ["merge", "jenkins"]
|
|
674
|
-
"group": "Engineering / Releases",
|
|
675
|
-
"tags": ["deploy"]
|
|
262
|
+
"implements": { "process": "release", "folder": "v4-abcd1234" },
|
|
263
|
+
"steps": ["merge", "jenkins"]
|
|
676
264
|
}
|
|
677
265
|
```
|
|
678
266
|
|
|
679
|
-
Leave out `steps` for a skill that covers the whole process.
|
|
267
|
+
`implements.folder` is the published version's folder (`publications/release/v4-abcd1234/`). Leave out `steps` for a skill that covers the whole process. Never write `skill-registrations/` by hand. The brief says which way to register: for a version that uses no Flightdeck 2.0 feature, it may give the older form, a `skills/<name>.json` file with `"implements": "release@4"` that copies older than 2.0 also read. Details are in [Registering a skill](https://github.com/troylar/flightdeck/blob/main/docs/apps.md#registering-a-skill-for-ai-assistants).
|
|
680
268
|
|
|
681
269
|
**5. Stay in step.** When a new version is published, every skill is checked against it:
|
|
682
270
|
|
|
683
271
|
| Status | Meaning | What you do |
|
|
684
272
|
|---|---|---|
|
|
685
273
|
| **current** | Built from the version in use | Nothing |
|
|
686
|
-
| **note version** | The process changed, but none of this skill's steps did |
|
|
687
|
-
| **needs update** | Its steps, their order, their gates, their step types, screenshots or run details changed | Copy the update brief: the exact before and after, for your AI assistant |
|
|
274
|
+
| **note version** | The process changed, but none of this skill's steps did | Note the new version: register it again (an older `skills/` file: move its `implements` forward) |
|
|
275
|
+
| **needs an update** | Its steps, their order, their gates, their step types, screenshots or run details changed | Copy the update brief: the exact before and after, for your AI assistant |
|
|
688
276
|
| **check it** | It can't be matched: a missing version, a clash, or an unreadable file | Fix the registration |
|
|
689
277
|
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
</details>
|
|
693
|
-
|
|
694
|
-
<br>
|
|
695
|
-
|
|
696
|
-
## Command line
|
|
697
|
-
|
|
698
|
-
**For people:**
|
|
699
|
-
|
|
700
|
-
| Command | Does |
|
|
701
|
-
|---|---|
|
|
702
|
-
| `flightdeck open` | Opens the app (it starts on the built-in examples) |
|
|
703
|
-
| `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 |
|
|
704
|
-
| `flightdeck skills <folder>` | Adds or updates only the skills, in `<folder>/.flightdeck/skills` |
|
|
705
|
-
| `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 |
|
|
706
|
-
| `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 |
|
|
707
|
-
| `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 |
|
|
708
|
-
| `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) |
|
|
709
|
-
| `flightdeck path` | Prints where the app file is |
|
|
710
|
-
| `flightdeck version` | Prints the version |
|
|
711
|
-
|
|
712
|
-
**For other apps** (they read the folder the way a teammate would, and never act for a person):
|
|
713
|
-
|
|
714
|
-
| Command | Does |
|
|
715
|
-
|---|---|
|
|
716
|
-
| `flightdeck processes <folder> --json` | Every process and its versions |
|
|
717
|
-
| `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 |
|
|
718
|
-
| `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` |
|
|
719
|
-
| `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** |
|
|
720
|
-
| `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 |
|
|
721
|
-
| `flightdeck followups <folder> --json` | Every follow-up and what became of it, with `--process <id>` and `--status open\|all` |
|
|
722
|
-
| `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 |
|
|
723
|
-
| `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 |
|
|
724
|
-
|
|
725
|
-
**For your AI assistant:**
|
|
726
|
-
|
|
727
|
-
| Command | Does |
|
|
728
|
-
|---|---|
|
|
729
|
-
| `flightdeck draft read <folder> <process> --json` | The draft's exact text and revision, who has it open, and this session's proposals |
|
|
730
|
-
| `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` |
|
|
731
|
-
| `flightdeck draft propose …` | The same arguments, `--json` included; writes a proposal instead of the draft, with the same `--base` rule |
|
|
732
|
-
| `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/` |
|
|
733
|
-
|
|
734
|
-
**Options:**
|
|
735
|
-
|
|
736
|
-
| Option | Does |
|
|
737
|
-
|---|---|
|
|
738
|
-
| `--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 |
|
|
739
|
-
| `--app-only` | With `install`: copies only `flightdeck.html` |
|
|
740
|
-
| `--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/` |
|
|
741
|
-
| `--no-attachments` | With `export`: lists attachments with their sizes instead of packing them |
|
|
742
|
-
|
|
743
|
-
<details>
|
|
744
|
-
<summary><b>Exit codes and guarantees</b></summary>
|
|
745
|
-
|
|
746
|
-
**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).
|
|
747
|
-
|
|
748
|
-
**`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.
|
|
749
|
-
|
|
750
|
-
**`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).
|
|
751
|
-
|
|
752
|
-
**`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).
|
|
753
|
-
|
|
754
|
-
**Install and skills** sort every `AGENTS.md` and skill file the same way:
|
|
755
|
-
|
|
756
|
-
- A file that's still a Flightdeck default (this version's or an earlier one) is updated.
|
|
757
|
-
- 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.
|
|
758
|
-
- In `AGENTS.md` only the part between the `flightdeck:begin` and `flightdeck:end` markers is Flightdeck's. Team notes, below it, are never touched.
|
|
759
|
-
- `.flightdeck/installed.json` records which defaults the folder is based on. It can make install more careful, never less.
|
|
760
|
-
- Every file install replaces is first copied to `.flightdeck/updates/<version>/replaced/`.
|
|
761
|
-
- 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).
|
|
278
|
+
<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>
|
|
762
279
|
|
|
763
|
-
|
|
280
|
+
**Skills** lists every skill built from your processes, wherever it lives, and which need an update. **A skill** says what changed under it and gives your AI assistant the exact before and after.
|
|
764
281
|
|
|
765
|
-
<
|
|
282
|
+
<p align="center"><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" width="49%"></picture></a> <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 update because one of its steps changed in v2, with Copy the update brief, where the skill lives and which steps it covers" width="49%"></picture></a></p>
|
|
766
283
|
|
|
767
284
|
## The team folder
|
|
768
285
|
|
|
769
|
-
<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
|
|
286
|
+
<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 in the app write people.json, sign-offs and decisions on corrections, follow-ups and reports; people and your AI assistant write drafts, step types and planned runs; your AI assistant writes skills, proposed draft changes and Jira workflows; the skill register command writes skill-registrations; other apps write reports and planned runs; Flightdeck writes publications, staged versions and runs when people publish, stage and run" width="1000"></picture></a></p>
|
|
770
287
|
|
|
771
|
-
|
|
288
|
+
There's no server. Everyone opens the same `flightdeck.html` from a folder the team shares; the app reads and writes plain files there and the sync tool carries them between computers. What keeps that safe:
|
|
772
289
|
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
```
|
|
290
|
+
- **Every file has 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, and decisions are new files, written once. In ordinary use nobody saves over anybody, so the sync tool never has to merge.
|
|
291
|
+
- **Saves check first.** Before each `run.json` save, a window compares a SHA-256 of the file with the one it read; if it changed, it writes its version beside the file as a conflict copy. It also leaves a save receipt first, so if two computers that can't see each other both save, the replaced save shows up in the run as a copy to compare, never silently lost. Nothing is merged automatically.
|
|
292
|
+
- **A failed read is never "nothing there."** A run, sign-off or plan that's still syncing or can't be read is named, and isn't counted until it reads.
|
|
293
|
+
- **An older copy never damages what a newer one wrote.** It shows the version or run with the reason, opens it read-only, and never saves over it.
|
|
294
|
+
- **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."
|
|
295
|
+
|
|
296
|
+
More in [Flightdeck and OneDrive](https://github.com/troylar/flightdeck/blob/main/docs/onedrive.md#what-keeps-runs-safe).
|
|
781
297
|
|
|
782
298
|
<details>
|
|
783
299
|
<summary><b>The folder, as text</b></summary>
|
|
@@ -787,14 +303,14 @@ people.json who's on the team, with the folder owner and backup owner
|
|
|
787
303
|
maps/drafts/ checklists being written (Markdown)
|
|
788
304
|
publications/ published versions, frozen (Flightdeck writes these)
|
|
789
305
|
staged/ staged versions only test runs use, and each retire or reopen, written once
|
|
790
|
-
runs/ one folder per run: run.json,
|
|
791
|
-
skills/ skill registrations
|
|
792
|
-
skill-registrations/ skills registered with flightdeck skill register
|
|
793
|
-
validations/
|
|
794
|
-
corrections/ decisions on corrections (applied, declined, reopened, withdrawn), each
|
|
795
|
-
followups/ what became of each follow-up (done, moved, won't do, reopened), each
|
|
306
|
+
runs/ one folder per run: run.json, each window's notes, save receipts, attached files
|
|
307
|
+
skills/ older skill registrations (implements "release@4")
|
|
308
|
+
skill-registrations/ skills registered with flightdeck skill register, one file per revision
|
|
309
|
+
validations/ sign-offs that a version, or a staged version, is ready for a skill
|
|
310
|
+
corrections/ decisions on corrections (applied, declined, reopened, withdrawn), each written once
|
|
311
|
+
followups/ what became of each follow-up (done, moved, won't do, reopened), each written once
|
|
796
312
|
suggestions/ decisions on suggested fixes from before 1.13 (still read)
|
|
797
|
-
step-types/ your team's own step types
|
|
313
|
+
step-types/ your team's own step types
|
|
798
314
|
jira/workflows.json your real Jira workflows, with required fields
|
|
799
315
|
proposals/ planned runs (from the app, your AI assistant or another app), waiting for a person to start them
|
|
800
316
|
proposed/ draft changes your AI assistant proposed, waiting to be applied or declined
|
|
@@ -805,18 +321,50 @@ history/ saved history of drafts and step types
|
|
|
805
321
|
presence/ which drafts a window has open, so your AI assistant knows to propose instead of save
|
|
806
322
|
connection/ connection checks between computers (Settings → Folder health)
|
|
807
323
|
AGENTS.md the rules any AI assistant follows in this folder (your own go under Team notes)
|
|
808
|
-
.flightdeck/
|
|
809
|
-
.flightdeck/installed.json which Flightdeck defaults AGENTS.md and the skills are based on
|
|
810
|
-
.flightdeck/updates/ new defaults waiting to be merged, and copies of files install replaced
|
|
324
|
+
.flightdeck/ the skills for your AI assistant, installed.json, and updates waiting to be merged
|
|
811
325
|
```
|
|
812
326
|
|
|
813
327
|
</details>
|
|
814
328
|
|
|
815
|
-
|
|
329
|
+
### How big a folder can get
|
|
330
|
+
|
|
331
|
+
Thousands of runs open and refresh without stalling. **Settings → Folder health** watches these sizes. None of them locks anything; each says what to do, and [The folder is getting big](https://github.com/troylar/flightdeck/blob/main/docs/recovery.md#the-folder-is-getting-big) has the steps.
|
|
332
|
+
|
|
333
|
+
| Size | What happens |
|
|
334
|
+
|---|---|
|
|
335
|
+
| More than 500 runs | A warning: the first read is getting slower |
|
|
336
|
+
| More than 2,000 runs | Marked as a stop: start a new team folder for new runs and keep this one as the record |
|
|
337
|
+
| Three refreshes in a row each over 15 seconds | A warning, measured on this computer |
|
|
338
|
+
| An attachment over 10 MB | Refused when you attach it |
|
|
339
|
+
| Attachments over 1 GB in all | A warning: every computer with the folder keeps every file |
|
|
340
|
+
| A path over 200 characters | A warning: Windows and OneDrive refuse paths that get too long |
|
|
341
|
+
| A run folder with more than 500 files | A warning for that run |
|
|
342
|
+
| More than 100 files in `step-types/` | Only the first 100 are read; the rest are named |
|
|
343
|
+
| More than 500 files in `skills/`, or 500 revision files in `skill-registrations/` | Only the first 500 are read (revision files, so fewer skills); the rest are named |
|
|
344
|
+
|
|
345
|
+
## Command line
|
|
346
|
+
|
|
347
|
+
| Command | Does |
|
|
348
|
+
|---|---|
|
|
349
|
+
| `flightdeck open` | Opens the app that came with the package: the welcome screen the first time, then the team folder you chose when the browser kept it (otherwise it offers **Reconnect**) |
|
|
350
|
+
| `flightdeck install <folder>` | Copies `flightdeck.html` into a team folder and adds or updates `AGENTS.md` and the skills in `.flightdeck/skills`. Keeps what your team changed, and won't replace a newer app or an unrecognized file without `--force`. Also updates a `preflight.html` already there |
|
|
351
|
+
| `flightdeck skills <folder>` | Adds or updates only the skills, in `<folder>/.flightdeck/skills`; `--to <dir>` puts them in any other folder, such as your assistant's skills folder |
|
|
352
|
+
| `flightdeck backup <folder>` | Copies the whole team folder to `~/Flightdeck backups/<folder> backup <date> <time>/`, or under `--to <dir>` |
|
|
353
|
+
| `flightdeck export <folder> --run <process>/<id>` | Makes an evidence pack of one run in `~/Flightdeck evidence/` (or `--out <dir>`); `--process <id> --from YYYY-MM-DD --through YYYY-MM-DD` packs every run of a process started on those days. See [Evidence packs](https://github.com/troylar/flightdeck/blob/main/docs/evidence.md) |
|
|
354
|
+
| `flightdeck path` · `flightdeck version` | Prints where the app file is · the version |
|
|
355
|
+
|
|
356
|
+
| Option | Does |
|
|
357
|
+
|---|---|
|
|
358
|
+
| `--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 |
|
|
359
|
+
| `--app-only` | With `install`: copies only `flightdeck.html` |
|
|
360
|
+
| `--force` | Replaces a newer app, an unrecognized file, or files your team changed. Every install first copies each file it replaces to `.flightdeck/updates/<version>/replaced/` |
|
|
361
|
+
| `--no-attachments` | With `export`: lists attachments with their sizes instead of packing them |
|
|
362
|
+
|
|
363
|
+
**For other apps and AI assistants**, the command also reads checklists and runs as JSON (`processes`, `process`, `runs`, `run`, `next`, `followups`), asks for a run (`flightdeck plan request`), reports the work a tool did on a step (`report`), reads and saves drafts safely (`draft read`, `draft save`, `draft propose`) and registers skills (`skill register`). A person always decides: a request becomes a planned run someone starts, and a report is accepted or declined by the recorder. Every command, its contract and its exit codes are in [Using Flightdeck from other apps](https://github.com/troylar/flightdeck/blob/main/docs/apps.md). `flightdeck --help` lists them all.
|
|
816
364
|
|
|
817
365
|
## Skills for your AI assistant
|
|
818
366
|
|
|
819
|
-
`flightdeck install` puts these in the team folder's `.flightdeck/skills
|
|
367
|
+
`flightdeck install` puts these in the team folder's `.flightdeck/skills/`, with an `AGENTS.md` that any assistant reads. They're plain `SKILL.md` files, so any assistant that supports skills can use them. Open the team folder with your assistant and ask for one by name:
|
|
820
368
|
|
|
821
369
|
| Skill | Does |
|
|
822
370
|
|---|---|
|
|
@@ -827,9 +375,9 @@ AGENTS.md the rules any AI assistant follows in this folder (your o
|
|
|
827
375
|
| `/flightdeck-plan-run` | Plans the next run, rotating roles fairly |
|
|
828
376
|
| `/flightdeck-status` | Summarizes the folder: what needs a person, what's running, what's stale |
|
|
829
377
|
| `/flightdeck-new-step-type` | Creates or changes a team step type from a description |
|
|
830
|
-
| `/flightdeck-skill-brief` | Writes the brief to create a skill from a signed-off version, or update one |
|
|
378
|
+
| `/flightdeck-skill-brief` | Writes the brief to create a skill from a signed-off version, or update one, by the same rules as the app |
|
|
831
379
|
|
|
832
|
-
|
|
380
|
+
In `AGENTS.md`, only the part between the `flightdeck:begin` and `flightdeck:end` markers is Flightdeck's; your Team notes below it are never touched. A file your team changed is left alone on update, and the new default waits in `.flightdeck/updates/<version>/` with a prompt for your assistant to merge it.
|
|
833
381
|
|
|
834
382
|
## Safe by design
|
|
835
383
|
|
|
@@ -837,126 +385,69 @@ AGENTS.md the rules any AI assistant follows in this folder (your o
|
|
|
837
385
|
|
|
838
386
|
- **Nothing leaves your machine.** The app makes no network requests and loads nothing from the internet; its fonts and code are inside the file.
|
|
839
387
|
- **No server to run, no accounts to manage.** Your data is files in a folder you already control.
|
|
840
|
-
- **
|
|
841
|
-
- **
|
|
842
|
-
- **
|
|
843
|
-
- **Accessible.** Every control has a label, errors sit next to their field, shortcuts can be turned off, and it works with a keyboard.
|
|
388
|
+
- **Saves that check first,** as described in [The team folder](#the-team-folder).
|
|
389
|
+
- **The command is careful too.** No dependencies, nothing runs on install, no network. It refuses to write through links, replaces a file only with a complete copy, and never replaces a newer version without `--force`.
|
|
390
|
+
- **Accessible.** Every control has a label, errors sit next to their field, keyboard shortcuts can be turned off, and everything works with a keyboard. Animations stop when your computer asks for less motion, and selections and focus stay visible in Windows high contrast.
|
|
844
391
|
|
|
845
|
-
|
|
392
|
+
Roles prevent ordinary mistakes, not attacks: anyone who can open the team folder can change any file in it. Keep secrets, tokens and customer data out of checklists, notes and attachments.
|
|
846
393
|
|
|
847
|
-
##
|
|
394
|
+
## Updating and when something goes wrong
|
|
848
395
|
|
|
849
|
-
|
|
396
|
+
Run `flightdeck install <folder>` again with the new version (or `npx @troylar/flightdeck@<version> install <folder>`). 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 backups, mixed versions and [rolling back](https://github.com/troylar/flightdeck/blob/main/docs/updating.md#rolling-back).
|
|
850
397
|
|
|
851
|
-
|
|
398
|
+
When the app shows a warning, **Settings → When something goes wrong** explains it in the app; the same guide is [online](https://github.com/troylar/flightdeck/blob/main/docs/recovery.md), covering conflict copies, lost folder access, OneDrive copies and restoring from a backup.
|
|
852
399
|
|
|
853
400
|
## FAQ
|
|
854
401
|
|
|
855
402
|
<details>
|
|
856
|
-
<summary><b>
|
|
857
|
-
|
|
858
|
-
Press Ctrl+K (Cmd+K on a Mac), or choose Search in the top bar. It searches runs, steps, notes, corrections, follow-ups, step types, skills and pages in the team folder, ignores accents, and takes you straight to what you choose. The search stays in memory on your computer; nothing is written to the team folder.
|
|
859
|
-
|
|
860
|
-
</details>
|
|
861
|
-
|
|
862
|
-
<details>
|
|
863
|
-
<summary><b>Does Flightdeck run anything for me?</b></summary>
|
|
864
|
-
|
|
865
|
-
No. It never calls Jenkins, Bitbucket or Jira, and never runs a command. It shows the command to copy, records what happened, and keeps the clock. Your skills do the automating.
|
|
866
|
-
|
|
867
|
-
</details>
|
|
868
|
-
|
|
869
|
-
<details>
|
|
870
|
-
<summary><b>Where does the AI live?</b></summary>
|
|
871
|
-
|
|
872
|
-
Outside Flightdeck. Your AI assistant writes checklists and builds skills from Flightdeck's briefs. Flightdeck versions the checklists and records which process version each skill follows.
|
|
873
|
-
|
|
874
|
-
</details>
|
|
875
|
-
|
|
876
|
-
<details>
|
|
877
|
-
<summary><b>Do I need OneDrive?</b></summary>
|
|
878
|
-
|
|
879
|
-
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.
|
|
880
|
-
|
|
881
|
-
</details>
|
|
882
|
-
|
|
883
|
-
<details>
|
|
884
|
-
<summary><b>Can a skill cover only part of a process?</b></summary>
|
|
885
|
-
|
|
886
|
-
Yes. List its `steps`. The brief tells it which gate to wait for before its first step, and the evidence and status consider only those steps.
|
|
887
|
-
|
|
888
|
-
</details>
|
|
889
|
-
|
|
890
|
-
<details>
|
|
891
|
-
<summary><b>Can a skill come first?</b></summary>
|
|
892
|
-
|
|
893
|
-
Yes. Ask your AI assistant to draft a checklist from an existing skill, publish it, and register the skill against that process version; then run and prove the checklist as usual. If the skill changes first, update and publish the checklist, then update the registration. Flightdeck doesn't detect skill changes. A guided skill-first workflow and skill change detection are planned.
|
|
894
|
-
|
|
895
|
-
</details>
|
|
896
|
-
|
|
897
|
-
<details>
|
|
898
|
-
<summary><b>Can people edit checklists in the app, or only the AI assistant?</b></summary>
|
|
403
|
+
<summary><b>What changed in 2.2 through 2.6.1?</b></summary>
|
|
899
404
|
|
|
900
|
-
|
|
405
|
+
- **2.2:** **Practice** runs the draft while you edit, recording nothing; Enter in **Add a step** keeps the box open for the next one; stage from the end of Practice.
|
|
406
|
+
- **2.3:** Practice opens on the real run screen. **2.3.1:** step text shows the run's details, gates show their names, plain steps are quieter, and the editor's button is **Review & publish**.
|
|
407
|
+
- **2.4:** a visual refresh with a new body typeface, and animations that stop for less motion.
|
|
408
|
+
- **2.5:** folders with thousands of runs open and refresh without stalling.
|
|
409
|
+
- **2.6:** every box in the step form asks a question with an example and a why; only the usual boxes show; one **Pull request** step.
|
|
410
|
+
- **2.6.1:** `AGENTS.md`, the skills and these docs match the app. Run `flightdeck install` on your team folder to get the updated assistant files.
|
|
901
411
|
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
<details>
|
|
905
|
-
<summary><b>The checklist was wrong during a run. What do I do?</b></summary>
|
|
906
|
-
|
|
907
|
-
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.
|
|
412
|
+
None of these adds a checklist feature that needs a newer copy to run: the publish panel still names only what needs 2.0 or 2.1. The full list is under **What's new** in the app and in [CHANGELOG.md](https://github.com/troylar/flightdeck/blob/main/CHANGELOG.md).
|
|
908
413
|
|
|
909
414
|
</details>
|
|
910
415
|
|
|
911
416
|
<details>
|
|
912
|
-
<summary><b>What
|
|
417
|
+
<summary><b>What if someone on the team has a newer or older Flightdeck?</b></summary>
|
|
913
418
|
|
|
914
|
-
|
|
419
|
+
A version or run with features a copy doesn't understand is shown there with the reason and "Update Flightdeck to run it," and opens read-only, so an older copy never records over a newer one's work. **Settings → Folder health** names older copies it saw in the last 7 days. Before anyone uses 2.0 features, every computer needs 1.21 or later; before anyone publishes `only when`, everyone needs 2.1; and 2.1.1's protection against starting a planned run twice works only once every computer has it. [When computers run different versions](https://github.com/troylar/flightdeck/blob/main/docs/updating.md#when-computers-run-different-versions) has the details.
|
|
915
420
|
|
|
916
421
|
</details>
|
|
917
422
|
|
|
918
423
|
<details>
|
|
919
|
-
<summary><b>
|
|
920
|
-
|
|
921
|
-
It's as private as the OneDrive folder it lives in, and no more. There's no server and no sign-in; nothing leaves your computers except through OneDrive.
|
|
922
|
-
|
|
923
|
-
Roles in Flightdeck prevent ordinary mistakes: only the folder owner and backup owner change the people list, and only a checklist's owner (or its backup owner, while the owner is away) signs off a version. They aren't security. Anyone who can open the team folder can change any file in it, with Flightdeck or without. Who can open it is set by how you share it in OneDrive.
|
|
424
|
+
<summary><b>Does Flightdeck run anything for me?</b></summary>
|
|
924
425
|
|
|
925
|
-
|
|
426
|
+
No. It never calls Jenkins, GitHub, Bitbucket or Jira, and never runs a command. It shows the command to copy, records what happened, and keeps the clock. Your skills do the automating, and the AI lives outside Flightdeck: your assistant writes checklists and builds skills from Flightdeck's briefs.
|
|
926
427
|
|
|
927
428
|
</details>
|
|
928
429
|
|
|
929
430
|
<details>
|
|
930
|
-
<summary><b>
|
|
931
|
-
|
|
932
|
-
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.
|
|
933
|
-
|
|
934
|
-
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.
|
|
935
|
-
|
|
936
|
-
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).
|
|
937
|
-
|
|
938
|
-
**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.
|
|
431
|
+
<summary><b>Do I need OneDrive?</b></summary>
|
|
939
432
|
|
|
940
|
-
|
|
433
|
+
OneDrive, in Edge or Chrome, is the setup Flightdeck is tested and documented for. The app works on any folder the browser can open; what matters is how the folder is shared and synced. [Flightdeck and OneDrive](https://github.com/troylar/flightdeck/blob/main/docs/onedrive.md) explains what a synced folder can and can't promise.
|
|
941
434
|
|
|
942
435
|
</details>
|
|
943
436
|
|
|
944
437
|
<details>
|
|
945
|
-
<summary><b>
|
|
438
|
+
<summary><b>Can a skill cover only part of a process, or come first?</b></summary>
|
|
946
439
|
|
|
947
|
-
|
|
440
|
+
Yes to both. List its `steps` and the brief tells it which gate to wait for, and readiness and status consider only those steps. For a skill that exists first, ask your AI assistant to draft a checklist from it, publish it and register the skill against that version, then run and prove the checklist as usual.
|
|
948
441
|
|
|
949
442
|
</details>
|
|
950
443
|
|
|
951
444
|
<details>
|
|
952
|
-
<summary><b>
|
|
445
|
+
<summary><b>I used Preflight. What happens?</b></summary>
|
|
953
446
|
|
|
954
|
-
|
|
447
|
+
Flightdeck was called Preflight before 1.9.0. Team folders, runs and published versions carry over untouched, and `flightdeck install` also updates a `preflight.html` already in the folder. A browser keeps saved examples and your name per file, so `flightdeck.html` starts those fresh.
|
|
955
448
|
|
|
956
449
|
</details>
|
|
957
450
|
|
|
958
|
-
<br>
|
|
959
|
-
|
|
960
451
|
## More docs
|
|
961
452
|
|
|
962
453
|
| Doc | For | You'll get |
|
|
@@ -966,11 +457,9 @@ The top bar shows the version and **What's new**, the full searchable history. I
|
|
|
966
457
|
| [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 |
|
|
967
458
|
| [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 |
|
|
968
459
|
| [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 |
|
|
969
|
-
| [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
|
|
460
|
+
| [Using Flightdeck from other apps](https://github.com/troylar/flightdeck/blob/main/docs/apps.md) | Script and tool authors, AI assistants | The JSON commands, run requests, reports, drafts and skill registration |
|
|
970
461
|
| [Design](https://github.com/troylar/flightdeck/blob/main/docs/design.md) | Contributors | The full specification and its decisions |
|
|
971
462
|
|
|
972
|
-
<br>
|
|
973
|
-
|
|
974
463
|
## License
|
|
975
464
|
|
|
976
465
|
[MIT](https://unpkg.com/@troylar/flightdeck/LICENSE). The embedded Barlow Condensed and Instrument Sans 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).
|