@manhquy/flow-skill 0.3.1 → 0.4.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 +15 -0
- package/README.md +110 -91
- package/README_VN.md +98 -83
- package/package.json +1 -1
- package/skills/flow/SKILL.md +3 -3
- package/skills/flow/_templates/00-inspect.md +18 -0
- package/skills/flow/harness/GAP-MATRIX-0.1.17.md +50 -31
- package/skills/flow/harness/README.md +15 -9
- package/skills/flow/harness/pins/harness-cli-v0.1.17.sha256sums +6 -3
- package/skills/flow/references/command-dispatch.md +1 -1
- package/skills/flow/references/gate-rules.md +21 -0
- package/skills/flow/references/native-rituals.md +45 -8
- package/skills-manifest.json +1 -1
- package/src/help.mjs +13 -15
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,21 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
|
|
4
4
|
|
|
5
|
+
## [0.4.1] — 2026-08-11 — README + CLI help install UX
|
|
6
|
+
|
|
7
|
+
Docs-only installer release (same skill **v0.27.0**). Professional install section, full
|
|
8
|
+
standard-command recipes, `@latest`-only help EXAMPLES, dual-version accuracy.
|
|
9
|
+
|
|
10
|
+
## [0.4.0] — 2026-08-11 — ships skill v0.27.0 (harness authority continuity)
|
|
11
|
+
|
|
12
|
+
Skill-content release. Ships skill product **v0.27.0**: flow-owned durable authority,
|
|
13
|
+
SUPERSEDED GAP matrix, R-IMPROVE-HARNESS ritual, brownfield Evidence ledger + material-authority
|
|
14
|
+
stop (see root `CHANGELOG.md` `## 0.27.0`). Publishes to dist-tag **`latest`**.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
- Bundled skill tree re-synced from monorepo `skills/flow/` (48 test suites green at ship).
|
|
18
|
+
- Install: **`npx @manhquy/flow-skill@latest`**.
|
|
19
|
+
|
|
5
20
|
## [0.3.1] — 2026-08-11 — help USAGE shows @latest
|
|
6
21
|
|
|
7
22
|
### Fixed
|
package/README.md
CHANGED
|
@@ -1,148 +1,167 @@
|
|
|
1
1
|
# @manhquy/flow-skill
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Install the **flow** skill into coding agents with one command.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
|
|
8
|
+
| **Current GA** | **0.4.1** — ships skill product **v0.27.0** |
|
|
9
|
+
| **Platforms** | macOS · Linux · Windows (same Node path) |
|
|
10
|
+
| **Requirement** | Node.js **≥ 22.14** |
|
|
11
|
+
| **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
|
|
9
12
|
|
|
10
|
-
|
|
13
|
+
flow is a gated build harness (`/flow`): idea → honest gates → real done-evidence. This package only **installs** that skill into agent skill homes.
|
|
11
14
|
|
|
12
|
-
|
|
13
|
-
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Standard install
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# Recommended — always pin the dist-tag so npx does not reuse a stale cache entry
|
|
14
21
|
npx @manhquy/flow-skill@latest
|
|
15
22
|
```
|
|
16
23
|
|
|
17
|
-
|
|
24
|
+
| Step | Detail |
|
|
25
|
+
|------|--------|
|
|
26
|
+
| 1 | Fetches **`latest`** from the npm registry |
|
|
27
|
+
| 2 | Interactive multi-select of detected agents (Claude is always offered) |
|
|
28
|
+
| 3 | Copies `skills/flow` into each selected destination |
|
|
29
|
+
| 4 | Prints what to type after reload (`/flow`, `$flow`, …) |
|
|
18
30
|
|
|
19
|
-
|
|
20
|
-
> re-run a stale cached copy; `@latest` forces npx to fetch the newest GA release. See
|
|
21
|
-
> [SECURITY.md](./SECURITY.md).
|
|
22
|
-
>
|
|
23
|
-
> **`npm i` alone is not enough.** `npm install @manhquy/flow-skill` only adds the installer
|
|
24
|
-
> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill@latest` or
|
|
25
|
-
> `npx flow-skill` after install) to copy the skill into agent homes.
|
|
26
|
-
>
|
|
27
|
-
> **Two version axes:** package `version` in this folder is the **installer** (e.g. `0.3.0`).
|
|
28
|
-
> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.26.0`).
|
|
29
|
-
> `--help` and the JSONL `plan` event expose both (`version` + `skillVersion`).
|
|
31
|
+
**After install:** restart or reload the agent, then invoke flow (see [After install](#after-install)).
|
|
30
32
|
|
|
31
|
-
|
|
33
|
+
### Confirm versions
|
|
32
34
|
|
|
35
|
+
```bash
|
|
36
|
+
npx @manhquy/flow-skill@latest --help
|
|
37
|
+
# expect: flow-skill v0.4.x (ships skill v0.27.x)
|
|
33
38
|
```
|
|
34
|
-
|
|
39
|
+
|
|
40
|
+
### Common commands
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# Non-interactive (Claude + detected agents)
|
|
35
44
|
npx @manhquy/flow-skill@latest --yes
|
|
36
45
|
|
|
37
|
-
#
|
|
46
|
+
# One or more targets
|
|
47
|
+
npx @manhquy/flow-skill@latest --yes --target claude
|
|
38
48
|
npx @manhquy/flow-skill@latest --yes -t claude -t codex
|
|
39
|
-
npx @manhquy/flow-skill@latest --yes -t claude,codex
|
|
49
|
+
npx @manhquy/flow-skill@latest --yes -t claude,codex
|
|
40
50
|
|
|
41
|
-
#
|
|
51
|
+
# Every supported target
|
|
42
52
|
npx @manhquy/flow-skill@latest --yes --all
|
|
43
53
|
|
|
44
|
-
#
|
|
54
|
+
# Claude skill inside a project repo (commit-friendly)
|
|
45
55
|
npx @manhquy/flow-skill@latest --yes --project --dir .
|
|
46
56
|
|
|
47
|
-
#
|
|
57
|
+
# Plan only (no disk writes) + JSONL for CI
|
|
48
58
|
npx @manhquy/flow-skill@latest --yes --all --dry-run --json
|
|
49
59
|
```
|
|
50
60
|
|
|
51
|
-
|
|
61
|
+
### Options
|
|
52
62
|
|
|
53
|
-
|
|
|
54
|
-
|
|
55
|
-
| `
|
|
56
|
-
|
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
|
|
|
63
|
+
| Flag | Meaning |
|
|
64
|
+
|------|---------|
|
|
65
|
+
| `-y`, `--yes` | Skip prompts; install default selection (detected + Claude) |
|
|
66
|
+
| `-t`, `--target <name>` | Target (repeatable or comma-separated) |
|
|
67
|
+
| `--all` | All targets, even if not detected |
|
|
68
|
+
| `--project` | Project scope — Claude only → `<dir>/.claude/skills/flow` |
|
|
69
|
+
| `--dir <path>` | Project directory (implies `--project`; default: cwd) |
|
|
70
|
+
| `--json` | JSONL events (`plan`, `install:*`, `summary`) |
|
|
71
|
+
| `--dry-run` | Print plan; do not write |
|
|
72
|
+
| `-h`, `--help` | Help |
|
|
60
73
|
|
|
61
|
-
|
|
74
|
+
### Targets
|
|
62
75
|
|
|
63
|
-
|
|
76
|
+
| Name | Destination | Detection |
|
|
77
|
+
|------|-------------|-----------|
|
|
78
|
+
| `claude` | `~/.claude/skills/flow` | `~/.claude` (always offered) |
|
|
79
|
+
| `codex` | `~/.codex/skills/flow` | `~/.codex/skills` |
|
|
80
|
+
| `agents` | `~/.agents/skills/flow` | `~/.agents/skills` |
|
|
81
|
+
| `antigravity` | `~/.gemini/antigravity-cli/skills/flow` **and** `~/.gemini/config/skills/flow` | either path |
|
|
82
|
+
| `cursor` | `~/.cursor/skills/flow` | `~/.cursor/skills` |
|
|
64
83
|
|
|
65
|
-
|
|
66
|
-
line tells you exactly what to do for whichever targets you installed:
|
|
84
|
+
`--project` supports **only** `claude`. Other targets with `--project` exit `2`.
|
|
67
85
|
|
|
68
|
-
|
|
69
|
-
- Codex CLI: type `$flow` (restart Codex once to load a new skill).
|
|
70
|
-
- Antigravity: restart/reload the IDE (or restart `agy`) to load the new skill, then type `/flow`.
|
|
71
|
-
- Agents home (`~/.agents/skills/`): restart/reload your tool if it does not auto-detect new skills.
|
|
72
|
-
- Cursor: **install verified, live runner execution not yet independently confirmed** — Cursor
|
|
73
|
-
has no headless CLI probe available for automated verification (unlike Antigravity's `agy -p`
|
|
74
|
-
or Codex's `codex exec`); restart/reload Cursor after install and check the Agent panel for
|
|
75
|
-
the `flow` skill.
|
|
76
|
-
- Diagnostics: run `/flow doctor` from your agent.
|
|
86
|
+
### Rules
|
|
77
87
|
|
|
78
|
-
|
|
88
|
+
| Do | Don’t |
|
|
89
|
+
|----|--------|
|
|
90
|
+
| `npx @manhquy/flow-skill@latest` | Bare `npx @manhquy/flow-skill` (stale npx cache) |
|
|
91
|
+
| **Run** the CLI to copy the skill | `npm i` alone (package only; no skill files in agent homes) |
|
|
92
|
+
| Pin installer `@0.4.1` if needed | Pin npm `@0.27.0` (skill version ≠ package version) |
|
|
93
|
+
| Prefer `@latest` | `@rc` (retired / behind) |
|
|
79
94
|
|
|
80
|
-
|
|
95
|
+
**Two version axes:** `package.json` version = installer; `SKILL.md` metadata = skill product. Both appear in `--help` and in the `plan` JSONL event (`version` + `skillVersion`).
|
|
81
96
|
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## After install
|
|
100
|
+
|
|
101
|
+
| Agent | Next step |
|
|
102
|
+
|-------|-----------|
|
|
103
|
+
| Claude Code | Type `/flow` |
|
|
104
|
+
| Codex CLI | Restart Codex once → `$flow` |
|
|
105
|
+
| Antigravity | Restart IDE / `agy` → `/flow` |
|
|
106
|
+
| Agents home | Reload the tool if it does not auto-pick new skills |
|
|
107
|
+
| Cursor | Reload Cursor; confirm `flow` in the agent skills panel |
|
|
108
|
+
| Any | `/flow doctor` (or run `runner/flow.sh doctor`) |
|
|
109
|
+
|
|
110
|
+
### Verify on disk (Claude global)
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1
|
|
114
|
+
bash ~/.claude/skills/flow/runner/flow.sh doctor
|
|
82
115
|
```
|
|
83
|
-
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Uninstall
|
|
120
|
+
|
|
121
|
+
```bash
|
|
84
122
|
rm -rf ~/.claude/skills/flow
|
|
85
123
|
rm -rf ~/.codex/skills/flow
|
|
86
124
|
rm -rf ~/.agents/skills/flow
|
|
125
|
+
rm -rf ~/.cursor/skills/flow
|
|
87
126
|
rm -rf ~/.gemini/antigravity-cli/skills/flow
|
|
88
127
|
rm -rf ~/.gemini/config/skills/flow
|
|
89
|
-
|
|
90
|
-
# Project scope (only Claude)
|
|
128
|
+
# project scope:
|
|
91
129
|
rm -rf <project>/.claude/skills/flow
|
|
92
130
|
```
|
|
93
131
|
|
|
132
|
+
---
|
|
133
|
+
|
|
94
134
|
## Troubleshooting
|
|
95
135
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
136
|
+
| Symptom | Fix |
|
|
137
|
+
|---------|-----|
|
|
138
|
+
| Agent has no `/flow` after `npm i` | Run `npx @manhquy/flow-skill@latest` (install must **execute**) |
|
|
139
|
+
| Old skill after reinstall | Always use `@latest`; avoid bare package name |
|
|
140
|
+
| `No matching version found` for `@0.27.0` | That is the **skill** version. Use `@latest` or `@0.4.x` |
|
|
141
|
+
| Node too old | Install Node ≥ 22.14 (`nvm install 22`, etc.) |
|
|
142
|
+
| Windows `EBUSY` / `EPERM` | Close the agent holding files under the skill dir; re-run |
|
|
143
|
+
| Stale install lock | Delete `<parent>/.flow-skill.installing.lock` if reclaim fails |
|
|
101
144
|
|
|
102
|
-
|
|
145
|
+
---
|
|
103
146
|
|
|
104
|
-
`--json`
|
|
147
|
+
## JSONL (`--json`)
|
|
105
148
|
|
|
106
149
|
```jsonl
|
|
107
|
-
{"event":"plan","version":"0.
|
|
150
|
+
{"event":"plan","version":"0.4.1","skillVersion":"0.27.0","dryRun":false,"scope":"global","targets":["claude"]}
|
|
108
151
|
{"event":"install:start","target":"claude","dests":["~/.claude/skills/flow"]}
|
|
109
152
|
{"event":"install:done","target":"claude","dests":["~/.claude/skills/flow"],"result":"success","error":null,"warnings":[]}
|
|
110
|
-
{"event":"summary","success":true,"total":
|
|
153
|
+
{"event":"summary","success":true,"total":1,"attempted":1,"installed":1,"failed":0,"skipped":0,"aborted":false}
|
|
111
154
|
```
|
|
112
155
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
### Event contract
|
|
116
|
-
|
|
117
|
-
| Event | Required fields | Notes |
|
|
118
|
-
|---|---|---|
|
|
119
|
-
| `plan` | `version` (string), `dryRun` (bool), `scope` (`global`\|`project`), `targets` (string[]), optional `skillVersion` (string\|null) | Always the first event. `version` = npm package; `skillVersion` = bundled `SKILL.md` product version. |
|
|
120
|
-
| `install:start` | `target` (string), `dests` (string[]) | One per selected target. |
|
|
121
|
-
| `install:done` | `target`, `dests`, `result` (`success`\|`failed`), `error` (string\|null), `warnings` (string[]) | Fired after each target. `error` is `null` on success. |
|
|
122
|
-
| `summary` | `success` (bool), `total`, `attempted`, `installed`, `failed`, `skipped`, `aborted` (bool) | Always the last event. Counts sum: `attempted = installed + failed`; `skipped = total - attempted`. |
|
|
123
|
-
| `error` | `message` (string), `exitCode` (int) | Emitted only when the process crashes before completing a normal flow (e.g. missing bundled skill). Then exits with `exitCode`. |
|
|
124
|
-
|
|
125
|
-
Exit codes: `0` success · `1` at least one target failed · `2` invalid usage (bad target name, `--project` with a non-Claude target, missing bundled skill) · `130` `SIGINT` (Ctrl+C).
|
|
156
|
+
Exit codes: `0` success · `1` target failure · `2` bad usage · `130` SIGINT.
|
|
126
157
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
## Requirements
|
|
130
|
-
|
|
131
|
-
- Node.js **>= 22.14.0** — Node 20 reached end-of-life in April 2026, and the publish workflow requires npm >=11.5.1 (bundled with Node 22.14+) for OIDC Trusted Publisher support
|
|
132
|
-
|
|
133
|
-
## Provenance
|
|
134
|
-
|
|
135
|
-
Every version published from the CI workflow carries an [npm provenance](https://docs.npmjs.com/generating-provenance-statements) attestation (SLSA Build Level 2). Verify with:
|
|
136
|
-
|
|
137
|
-
```
|
|
138
|
-
npm view @manhquy/flow-skill@<version> dist.attestations.provenance
|
|
139
|
-
```
|
|
158
|
+
Contract is additive: new optional fields may appear; existing fields are stable.
|
|
140
159
|
|
|
141
|
-
|
|
160
|
+
---
|
|
142
161
|
|
|
143
|
-
##
|
|
162
|
+
## Provenance & security
|
|
144
163
|
|
|
145
|
-
|
|
164
|
+
Published builds from CI include [npm provenance](https://docs.npmjs.com/generating-provenance-statements). Threat model and reporting: [SECURITY.md](./SECURITY.md).
|
|
146
165
|
|
|
147
166
|
## License
|
|
148
167
|
|
package/README_VN.md
CHANGED
|
@@ -1,128 +1,143 @@
|
|
|
1
1
|
# @manhquy/flow-skill
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Cài skill **flow** vào coding agent bằng một lệnh.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Package** | [`@manhquy/flow-skill`](https://www.npmjs.com/package/@manhquy/flow-skill) (installer CLI) |
|
|
8
|
+
| **GA hiện tại** | **0.4.1** — ships skill product **v0.27.0** |
|
|
9
|
+
| **Nền tảng** | macOS · Linux · Windows (cùng code path Node) |
|
|
10
|
+
| **Yêu cầu** | Node.js **≥ 22.14** |
|
|
11
|
+
| **Source** | [github.com/manhquydev/flow-skill](https://github.com/manhquydev/flow-skill) |
|
|
9
12
|
|
|
10
|
-
|
|
13
|
+
flow là harness build có cổng (`/flow`). Package này chỉ **cài** skill đó vào skill home của agent.
|
|
11
14
|
|
|
12
|
-
|
|
13
|
-
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Lệnh chuẩn
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# Khuyến nghị — luôn gắn @latest để npx không dùng cache cũ
|
|
14
21
|
npx @manhquy/flow-skill@latest
|
|
15
22
|
```
|
|
16
23
|
|
|
17
|
-
|
|
24
|
+
| Bước | Chi tiết |
|
|
25
|
+
|------|----------|
|
|
26
|
+
| 1 | Tải dist-tag **`latest`** từ npm |
|
|
27
|
+
| 2 | Multi-select agent (Claude luôn được đề xuất) |
|
|
28
|
+
| 3 | Copy `skills/flow` vào từng đích |
|
|
29
|
+
| 4 | In hướng dẫn gọi sau reload (`/flow`, `$flow`, …) |
|
|
18
30
|
|
|
19
|
-
|
|
20
|
-
> bản cache cũ; `@latest` ép lấy GA mới nhất. Kênh `rc` đã retire — không dùng `@rc`.
|
|
21
|
-
>
|
|
22
|
-
> **`npm i` alone chưa đủ** — phải **chạy** CLI. Hai trục version: package npm vs skill product
|
|
23
|
-
> (`ships skill v…` / `skillVersion` trong JSONL). Xem [SECURITY.md](./SECURITY.md).
|
|
31
|
+
**Sau cài:** restart/reload agent (xem [Sau khi cài](#sau-khi-cài)).
|
|
24
32
|
|
|
25
|
-
|
|
33
|
+
### Xác nhận version
|
|
26
34
|
|
|
35
|
+
```bash
|
|
36
|
+
npx @manhquy/flow-skill@latest --help
|
|
37
|
+
# expect: flow-skill v0.4.x (ships skill v0.27.x)
|
|
27
38
|
```
|
|
28
|
-
|
|
39
|
+
|
|
40
|
+
### Lệnh hay dùng
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# Không prompt (Claude + agent đã detect)
|
|
29
44
|
npx @manhquy/flow-skill@latest --yes
|
|
30
45
|
|
|
31
46
|
# Target rõ ràng
|
|
47
|
+
npx @manhquy/flow-skill@latest --yes --target claude
|
|
32
48
|
npx @manhquy/flow-skill@latest --yes -t claude -t codex
|
|
33
|
-
npx @manhquy/flow-skill@latest --yes -t claude,codex
|
|
49
|
+
npx @manhquy/flow-skill@latest --yes -t claude,codex
|
|
34
50
|
|
|
35
|
-
#
|
|
51
|
+
# Cả 5 target
|
|
36
52
|
npx @manhquy/flow-skill@latest --yes --all
|
|
37
53
|
|
|
38
|
-
#
|
|
54
|
+
# Skill trong repo (chỉ Claude)
|
|
39
55
|
npx @manhquy/flow-skill@latest --yes --project --dir .
|
|
40
56
|
|
|
41
|
-
# JSONL
|
|
57
|
+
# Chỉ xem kế hoạch + JSONL (CI)
|
|
42
58
|
npx @manhquy/flow-skill@latest --yes --all --dry-run --json
|
|
43
59
|
```
|
|
44
60
|
|
|
45
|
-
|
|
61
|
+
### Tùy chọn
|
|
46
62
|
|
|
47
|
-
|
|
|
48
|
-
|
|
49
|
-
|
|
|
50
|
-
|
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
53
|
-
|
|
|
63
|
+
| Flag | Ý nghĩa |
|
|
64
|
+
|------|---------|
|
|
65
|
+
| `-y`, `--yes` | Bỏ prompt; cài selection mặc định |
|
|
66
|
+
| `-t`, `--target <name>` | Target (lặp hoặc comma) |
|
|
67
|
+
| `--all` | Mọi target, kể cả chưa detect |
|
|
68
|
+
| `--project` | Scope project — chỉ Claude → `<dir>/.claude/skills/flow` |
|
|
69
|
+
| `--dir <path>` | Thư mục project (kéo theo `--project`) |
|
|
70
|
+
| `--json` | JSONL events |
|
|
71
|
+
| `--dry-run` | Không ghi đĩa |
|
|
72
|
+
| `-h`, `--help` | Help |
|
|
54
73
|
|
|
55
|
-
|
|
74
|
+
### Targets
|
|
56
75
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
76
|
+
| Tên | Đích | Detection |
|
|
77
|
+
|-----|------|-----------|
|
|
78
|
+
| `claude` | `~/.claude/skills/flow` | `~/.claude` |
|
|
79
|
+
| `codex` | `~/.codex/skills/flow` | `~/.codex/skills` |
|
|
80
|
+
| `agents` | `~/.agents/skills/flow` | `~/.agents/skills` |
|
|
81
|
+
| `antigravity` | 2 path dưới `~/.gemini/…` | CLI hoặc IDE skills |
|
|
82
|
+
| `cursor` | `~/.cursor/skills/flow` | `~/.cursor/skills` |
|
|
61
83
|
|
|
62
|
-
|
|
63
|
-
- Codex CLI: gõ `$flow` (restart Codex 1 lần để load skill mới).
|
|
64
|
-
- Antigravity: restart/reload IDE (hoặc restart `agy`) để load skill mới, rồi gõ `/flow`.
|
|
65
|
-
- Agents home: restart/reload tool nếu nó không tự nhận skill mới.
|
|
66
|
-
- Cursor: **đã xác nhận cài đúng chỗ, chưa xác nhận runner chạy độc lập** — Cursor không có
|
|
67
|
-
CLI headless để tự động kiểm (khác `agy -p` của Antigravity hay `codex exec` của Codex);
|
|
68
|
-
restart/reload Cursor sau khi cài rồi kiểm tra panel Agent xem có skill `flow` không.
|
|
69
|
-
- Chẩn đoán: chạy `/flow doctor` từ agent.
|
|
84
|
+
`--project` **chỉ** hỗ trợ `claude` (exit `2` nếu kết hợp target khác).
|
|
70
85
|
|
|
71
|
-
|
|
86
|
+
### Quy tắc
|
|
72
87
|
|
|
73
|
-
|
|
88
|
+
| Nên | Không |
|
|
89
|
+
|-----|--------|
|
|
90
|
+
| `npx @manhquy/flow-skill@latest` | Bare package name (cache npx) |
|
|
91
|
+
| **Chạy** CLI | Chỉ `npm i` |
|
|
92
|
+
| Pin `@0.4.0` nếu cần | Pin `@0.27.0` trên npm (version skill) |
|
|
93
|
+
| `@latest` | `@rc` |
|
|
74
94
|
|
|
75
|
-
|
|
76
|
-
# Global installs
|
|
77
|
-
rm -rf ~/.claude/skills/flow
|
|
78
|
-
rm -rf ~/.codex/skills/flow
|
|
79
|
-
rm -rf ~/.agents/skills/flow
|
|
80
|
-
rm -rf ~/.gemini/antigravity-cli/skills/flow
|
|
81
|
-
rm -rf ~/.gemini/config/skills/flow
|
|
82
|
-
|
|
83
|
-
# Project scope (chỉ Claude)
|
|
84
|
-
rm -rf <project>/.claude/skills/flow
|
|
85
|
-
```
|
|
95
|
+
**Hai trục version:** package = installer; skill = `SKILL.md`. Cả hai hiện trong `--help` và event `plan` (`version` + `skillVersion`).
|
|
86
96
|
|
|
87
|
-
|
|
97
|
+
---
|
|
88
98
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
- `plan` — event đầu tiên; chứa `version`, `dryRun`, `scope`, `targets`.
|
|
92
|
-
- `install:start` / `install:done` — một cặp mỗi target; `install:done.result` = `success` hoặc `failed`.
|
|
93
|
-
- `summary` — event cuối cùng; `success`, `total`, `attempted`, `installed`, `failed`, `skipped`, `aborted`.
|
|
94
|
-
- Exit codes: `0` OK · `1` ≥1 target fail · `2` sai flag/target · `130` Ctrl+C.
|
|
95
|
-
|
|
96
|
-
Hợp đồng additive trong `0.1.x` — field mới có thể thêm, field cũ không rename/xóa.
|
|
97
|
-
|
|
98
|
-
## Troubleshooting
|
|
99
|
+
## Sau khi cài
|
|
99
100
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
101
|
+
| Agent | Bước tiếp |
|
|
102
|
+
|-------|-----------|
|
|
103
|
+
| Claude Code | Gõ `/flow` |
|
|
104
|
+
| Codex | Restart Codex → `$flow` |
|
|
105
|
+
| Antigravity | Restart IDE/`agy` → `/flow` |
|
|
106
|
+
| Agents / Cursor | Reload tool; kiểm panel skill |
|
|
107
|
+
| Bất kỳ | `/flow doctor` |
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
grep -E '^\s*version:' ~/.claude/skills/flow/SKILL.md | head -1
|
|
111
|
+
bash ~/.claude/skills/flow/runner/flow.sh doctor
|
|
112
|
+
```
|
|
104
113
|
|
|
105
|
-
|
|
114
|
+
---
|
|
106
115
|
|
|
107
|
-
|
|
116
|
+
## Gỡ cài
|
|
108
117
|
|
|
109
|
-
|
|
118
|
+
```bash
|
|
119
|
+
rm -rf ~/.claude/skills/flow ~/.codex/skills/flow ~/.agents/skills/flow
|
|
120
|
+
rm -rf ~/.cursor/skills/flow
|
|
121
|
+
rm -rf ~/.gemini/antigravity-cli/skills/flow ~/.gemini/config/skills/flow
|
|
122
|
+
rm -rf <project>/.claude/skills/flow
|
|
123
|
+
```
|
|
110
124
|
|
|
111
|
-
|
|
125
|
+
---
|
|
112
126
|
|
|
113
|
-
|
|
114
|
-
npm view @manhquy/flow-skill@<version> dist.attestations.provenance
|
|
115
|
-
```
|
|
127
|
+
## Xử lý sự cố
|
|
116
128
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
129
|
+
| Hiện tượng | Cách xử lý |
|
|
130
|
+
|------------|------------|
|
|
131
|
+
| Có package nhưng không có `/flow` | Chạy `npx @manhquy/flow-skill@latest` |
|
|
132
|
+
| Skill cũ sau khi “cài lại” | Luôn `@latest` |
|
|
133
|
+
| `No matching version` với `@0.27.0` | Dùng `@latest` / `@0.4.x` (version skill ≠ package) |
|
|
134
|
+
| Node quá cũ | Nâng Node ≥ 22.14 |
|
|
135
|
+
| Windows EBUSY | Đóng agent đang giữ file skill; chạy lại |
|
|
121
136
|
|
|
122
|
-
|
|
137
|
+
---
|
|
123
138
|
|
|
124
|
-
|
|
139
|
+
## JSONL · provenance · license
|
|
125
140
|
|
|
126
|
-
|
|
141
|
+
Xem bản [English README](./README.md) cho bảng event JSONL, provenance, và [SECURITY.md](./SECURITY.md).
|
|
127
142
|
|
|
128
143
|
MIT © 2026 manhquy
|
package/package.json
CHANGED
package/skills/flow/SKILL.md
CHANGED
|
@@ -8,8 +8,8 @@ keywords: [flow, buildflow, gate, build, ship, scope, prd, contract, card, deplo
|
|
|
8
8
|
license: MIT
|
|
9
9
|
metadata:
|
|
10
10
|
author: flow-skill
|
|
11
|
-
version: "0.
|
|
12
|
-
attribution: "Methodology from ai20k-build-phase/buildflow (Tony, arealisticdreamer.com);
|
|
11
|
+
version: "0.27.0"
|
|
12
|
+
attribution: "Methodology from ai20k-build-phase/buildflow (Tony, arealisticdreamer.com); durable-layer ancestry and improve-ritual spirit from repository-harness (protocol v1 EOL — flow-owned fork); agent patterns from claudekit-engineer, BMAD-METHOD. v0.22 concierge from BMAD bmad-help; forge-idea from bmad-forge-idea (MIT, BMad Code LLC)."
|
|
13
13
|
---
|
|
14
14
|
|
|
15
15
|
# /flow — buildflow gated build harness
|
|
@@ -235,7 +235,7 @@ Hard stops (iteration/token/time caps) and ground-truth gates (`flow.sh` exit, r
|
|
|
235
235
|
- `references/gate-eval.md` — `/flow eval` behavioral proof for the semantic layer: what it
|
|
236
236
|
measures (a fresh-judge lower bound, NOT the work-mode self-challenge), cost, thresholds,
|
|
237
237
|
and the honest authorship-bias limitation. Read before running or relaying a scorecard.
|
|
238
|
-
- `harness/` — durable layer (`flow.sh harness ...`): intake/story/**complete**/trace/decision/backlog.
|
|
238
|
+
- `harness/` — **flow-owned** durable layer (`flow.sh harness ...`): intake/story/**complete**/trace/decision/backlog. Live authority = this Python CLI + `flow.sh` + gate-rules (not external `harness-cli`). Historical gap: `harness/GAP-MATRIX-0.1.17.md` (SUPERSEDED). Never `story update --status implemented` — use `story complete --proof-source …`. Improve skill/harness guidance: ritual **R-IMPROVE-HARNESS** in `references/native-rituals.md` (explicit-only; fresh-agent rerun before keep).
|
|
239
239
|
- `playbooks/` — paid-for stack knowledge: read before building a card on that stack, harvest the lesson after.
|
|
240
240
|
- `_templates/` — the 7 artifacts the runner copies into `flow/` and `cards/`. Never edit during a run.
|
|
241
241
|
|
|
@@ -12,6 +12,7 @@ then check the gate. `/flow assess` seeds the auto-scan and validates this gate.
|
|
|
12
12
|
- [ ] I listed the top risks / tech-debt / known issues
|
|
13
13
|
- [ ] I noted the test + quality baseline (what is covered vs not)
|
|
14
14
|
- [ ] A human reviewed this assessment (brownfield assessment is operator-gated)
|
|
15
|
+
- [ ] Every material claim in this assessment is tagged in the Evidence ledger (no Unknown/Decision-required silently treated as product law)
|
|
15
16
|
- [ ] No FILL placeholders remain in this file
|
|
16
17
|
|
|
17
18
|
## Detected (auto-scan)
|
|
@@ -38,5 +39,22 @@ is most likely to hide. [FILL: note which ranked surfaces you inspected + what y
|
|
|
38
39
|
## Test + quality baseline
|
|
39
40
|
[FILL: what is tested vs not; how to run the suite; coverage if known]
|
|
40
41
|
|
|
42
|
+
## Evidence ledger (claims)
|
|
43
|
+
|
|
44
|
+
Tag every material claim from Functionality / Risks / Verdict. Do **not** write product
|
|
45
|
+
policy as fact unless **Authoritative**. Tags:
|
|
46
|
+
|
|
47
|
+
| Tag | Meaning |
|
|
48
|
+
|-----|---------|
|
|
49
|
+
| **Authoritative** | Instruction, accepted decision, product contract, documented procedure |
|
|
50
|
+
| **Observed** | Code/config/tests show current behavior |
|
|
51
|
+
| **Derived** | Direct operational consequence of observed implementation |
|
|
52
|
+
| **Decision required** | Normative/product choice with no authority yet |
|
|
53
|
+
| **Unknown** | Repo does not establish the answer |
|
|
54
|
+
|
|
55
|
+
| Claim | Tag | Source (path or "none") |
|
|
56
|
+
|-------|-----|-------------------------|
|
|
57
|
+
| [FILL: one material claim] | Observed \| Authoritative \| Derived \| Decision required \| Unknown | path:line or none |
|
|
58
|
+
|
|
41
59
|
## Verdict
|
|
42
60
|
[FILL: is the codebase healthy enough to build on? what must be fixed first?]
|
|
@@ -1,42 +1,61 @@
|
|
|
1
|
-
#
|
|
1
|
+
# SUPERSEDED (2026-08) — historical comparison only
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
> **Live policy:** durable layer is **flow-owned**. **No further schema sync** from
|
|
4
|
+
> repository-harness / `harness-cli`. Last published protocol-v1 archive:
|
|
5
|
+
> **`harness-cli-v0.1.22`** (EOL; no features). Do not treat 0.1.14/0.1.17 as live trust pins.
|
|
6
|
+
>
|
|
7
|
+
> **Live authority:** `flow_harness.py` + `flow.sh` + `gate-rules.md` (see `harness/README.md`).
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Gap matrix (archive): flow durable layer vs repository-harness CLI 0.1.17
|
|
12
|
+
|
|
13
|
+
**Historical authority note:** compared against `harness-cli-v0.1.17` during v0.24 trust-align.
|
|
14
|
+
Pins below are **archive labels**, not install targets.
|
|
15
|
+
|
|
16
|
+
| Archive label | Tag | Historical use |
|
|
17
|
+
|---------------|-----|----------------|
|
|
18
|
+
| Protocol floor (archive) | `harness-cli-v0.1.14` | protocol v1 discovery floor at trust-align time |
|
|
19
|
+
| Trust-align snapshot | `harness-cli-v0.1.17` | US-101 spirit inspiration |
|
|
20
|
+
| Do not use | `harness-cli-v0.1.16` | tag without published assets |
|
|
21
|
+
| Last published archive | `harness-cli-v0.1.22` | EOL max (repository-harness ADR 0027) |
|
|
22
|
+
|
|
23
|
+
Flow does not claim US-101 parity or an isomorphic control plane.
|
|
24
|
+
|
|
25
|
+
**Supersession:** upstream work-graph / protocol-v1 is not a sync target (recorded 2026-07-26 graph band + 2026-08 EOL).
|
|
8
26
|
|
|
9
27
|
## Schema
|
|
10
28
|
|
|
11
|
-
| Ver | Flow | Harness 0.1.17 | Notes |
|
|
12
|
-
|
|
13
|
-
| 001–004 | present (shared) | present |
|
|
14
|
-
| 005 | present | present |
|
|
15
|
-
| 006–008 | **absent** (reserved gap) | changesets / deps / hierarchy | Not adopted
|
|
16
|
-
| 009–012 | **usage/accessed** (flow-
|
|
17
|
-
| 013 | absent | changeset content sha |
|
|
18
|
-
| 014+ | **graph-executor** (flow-owned
|
|
19
|
-
|
|
20
|
-
## Commands / invariants
|
|
21
|
-
|
|
22
|
-
| Surface | Flow status |
|
|
23
|
-
|
|
24
|
-
| `story update --status implemented` | rejected
|
|
25
|
-
| `story complete` | flow-native
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
| `query contract --json` | not on Python CLI | protocol v1 discovery | Optional external binary smoke only |
|
|
31
|
-
|
|
32
|
-
## Pins (consumer)
|
|
29
|
+
| Ver | Flow | Harness 0.1.17 (archive) | Notes |
|
|
30
|
+
|-----|------|--------------------------|-------|
|
|
31
|
+
| 001–004 | present (shared ancestry) | present | Frozen; no further sync |
|
|
32
|
+
| 005 | present | present | tool registry ancestry |
|
|
33
|
+
| 006–008 | **absent** (reserved gap) | changesets / deps / hierarchy | Not adopted |
|
|
34
|
+
| 009–012 | **usage/accessed** (flow-owned) | different upstream meaning | Semantic collision avoided |
|
|
35
|
+
| 013 | absent | changeset content sha | Reserved/absent |
|
|
36
|
+
| 014+ | **graph-executor** (flow-owned) | absent | Flow-owned since 2026-07-26 |
|
|
37
|
+
|
|
38
|
+
## Commands / invariants (still live in flow Python)
|
|
39
|
+
|
|
40
|
+
| Surface | Flow status | Trust note |
|
|
41
|
+
|---------|-------------|------------|
|
|
42
|
+
| `story update --status implemented` | rejected | Use `story complete` |
|
|
43
|
+
| `story complete` | flow-native `proof_source` | Never forge `last_verified_result=pass` from markdown alone |
|
|
44
|
+
| Rust forward | refused on flow-lineage DB | exit 2 when usage mirror / schema≥9 |
|
|
45
|
+
| Changesets 006–013 | not adopted | graph band 014+ is flow-owned |
|
|
46
|
+
|
|
47
|
+
## Historical pins (do not install as product dependency)
|
|
33
48
|
|
|
34
49
|
```
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
50
|
+
# archive labels only — not live authority
|
|
51
|
+
HARNESS_PROTOCOL_V1_TAG_ARCHIVE = harness-cli-v0.1.14
|
|
52
|
+
HARNESS_CLI_TRUST_ALIGN_SNAPSHOT = harness-cli-v0.1.17
|
|
53
|
+
HARNESS_CLI_LAST_PUBLISHED_ARCHIVE = harness-cli-v0.1.22
|
|
54
|
+
DO_NOT_USE = harness-cli-v0.1.16
|
|
38
55
|
```
|
|
39
56
|
|
|
40
57
|
## Rust refuse-forward
|
|
41
58
|
|
|
42
|
-
Any DB with `usage_event` or `MAX(schema_version) >= 9` is **flow-lineage**. Python entrypoint
|
|
59
|
+
Any DB with `usage_event` or `MAX(schema_version) >= 9` is **flow-lineage**. Python entrypoint
|
|
60
|
+
must refuse forwarding to external `harness-cli` (exit 2). `graph` verbs are NEVER forwarded.
|
|
61
|
+
**Supersession:** upstream work-graph / protocol-v1 is not a sync target.
|
|
@@ -1,20 +1,26 @@
|
|
|
1
1
|
# flow-harness — durable layer
|
|
2
2
|
|
|
3
3
|
The durable memory of `/flow`: intake classification, story packets with proof status,
|
|
4
|
-
auto-scored execution traces, decision records, and the growth-rule backlog.
|
|
5
|
-
`repository-harness` (shared base schema + flow-only usage extensions). State lives at
|
|
4
|
+
auto-scored execution traces, decision records, and the growth-rule backlog. State lives at
|
|
6
5
|
`<project>/.flow/harness.db` and survives across sessions — this is the "external memory"
|
|
7
6
|
that fights context rot.
|
|
8
7
|
|
|
9
|
-
##
|
|
8
|
+
## Live authority (flow-owned)
|
|
10
9
|
|
|
11
|
-
|
|
|
12
|
-
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
| **
|
|
10
|
+
| Layer | Authority |
|
|
11
|
+
|-------|-----------|
|
|
12
|
+
| **Mechanical gates** | `runner/flow.sh` exit codes |
|
|
13
|
+
| **Semantic gates** | `references/gate-rules.md` + `law/` |
|
|
14
|
+
| **Durable memory** | **this Python CLI** (`flow_harness.py`) + `.flow/harness.db` — **flow-owned** |
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
Schema bands **001–005** are frozen shared ancestry with pre-EOL `repository-harness`;
|
|
17
|
+
**009–012** and **014+** are flow-owned forever. **No further upstream schema sync**
|
|
18
|
+
(repository-harness protocol v1 / `harness-cli` is EOL — ADR 0027; last published archive
|
|
19
|
+
`harness-cli-v0.1.22`). Historical gap inventory:
|
|
20
|
+
[`GAP-MATRIX-0.1.17.md`](./GAP-MATRIX-0.1.17.md) (SUPERSEDED comparison only).
|
|
21
|
+
|
|
22
|
+
**Self-improving this skill:** explicit-only ritual **`R-IMPROVE-HARNESS`** in
|
|
23
|
+
`references/native-rituals.md` (fresh-agent rerun before claiming a keep).
|
|
18
24
|
|
|
19
25
|
## Backends
|
|
20
26
|
|
|
@@ -1,6 +1,9 @@
|
|
|
1
|
-
#
|
|
2
|
-
#
|
|
3
|
-
#
|
|
1
|
+
# HISTORICAL ARCHIVE ONLY — not live product trust.
|
|
2
|
+
# Digests from GitHub Release harness-cli-v0.1.17 (v0.24 trust-align snapshot).
|
|
3
|
+
# Protocol v1 / harness-cli is EOL (repository-harness ADR 0027; last published archive 0.1.22).
|
|
4
|
+
# Do not install as a flow dependency; flow durable layer is flow-owned Python.
|
|
5
|
+
# TAG harness-cli-v0.1.17 (archive)
|
|
6
|
+
# PROTOCOL_FLOOR harness-cli-v0.1.14 (archive)
|
|
4
7
|
# DO_NOT_USE harness-cli-v0.1.16
|
|
5
8
|
5d13f0a024d9d69701534a879581c9433bc0069e04d052e5aacd93b91b3b7a43 harness-cli-linux-x64
|
|
6
9
|
128c42c251fb31b58582342c09c68be6ed3329340fb1d8f179c88590a4539c97 harness-cli-linux-arm64
|
|
@@ -9,7 +9,7 @@ install dir; run from the project root so `flow/` and `cards/` resolve.
|
|
|
9
9
|
| `/flow` | `bash <skill>/runner/flow.sh status` | Runner now prints its own `NEXT ->` line (same helper as `resume`) plus stage dwell and, past 10 cards, a compact done/in-flight/todo summary. Relay it; nothing to author. |
|
|
10
10
|
| `/flow resume` | `bash <skill>/runner/flow.sh resume` | Read-only, no lock. Relay all four sections verbatim (last session, in-flight + dwell, gate state, NEXT ->). Run this FIRST when entering a project mid-cycle with no prior context this session. Never expand on or guess at raw args it didn't print — it deliberately shows command names only. |
|
|
11
11
|
| `/flow next` | `bash <skill>/runner/flow.sh next` | If FAIL: relay the exact violations + line numbers; offer help, don't author/tick in teach mode. If PASS: run the stage's challenge in `gate-rules.md`; flag hollow content, let operator decide. |
|
|
12
|
-
| `/flow assess` | `bash <skill>/runner/flow.sh assess` | Brownfield only: fill `flow/00-inspect.md` from EVIDENCE (read the code) — functionality/UI/UX vs product, risks, test baseline. Reuse `scout`/`researcher`. Gate is operator-reviewed; then proceed to `/flow next`. |
|
|
12
|
+
| `/flow assess` | `bash <skill>/runner/flow.sh assess` | Brownfield only: fill `flow/00-inspect.md` from EVIDENCE (read the code) — functionality/UI/UX vs product, risks, test baseline, **Evidence ledger** claim tags. After mechanical PASS, apply gate-rules **Brownfield assess** challenge (no Observed→product-law promotion). Reuse `scout`/`researcher`. Gate is operator-reviewed; then proceed to `/flow next`. |
|
|
13
13
|
| `/flow card` | `bash <skill>/runner/flow.sh card` | Confirm the new card id; remind: fill Scope (one thing) / Allowed files / Verify / Done-evidence per `law/CLAUDE.md`. |
|
|
14
14
|
| `/flow card start C-NNN` | `bash <skill>/runner/flow.sh card start C-NNN` | Optional: mark the card in flight (operator-visible in-progress, shown in `/flow status`). Portable `cards/.inflight` registry; does NOT touch the gated `status:` field. Coexists with hand-edit. |
|
|
15
15
|
| `/flow card done C-NNN` | `bash <skill>/runner/flow.sh card done C-NNN` | Optional convenience: CLI-owned flip to `done`, gated by the SAME done-rules as `check` (reverts on fail — never a hollow done). Then still apply the semantic card review (diff-vs-scope, contract shapes, real evidence) as with `check`. |
|
|
@@ -19,6 +19,20 @@ artifact, never silently block a sound one.
|
|
|
19
19
|
> the bad shape, not less, and a hedging "unless it matters" clause turns a crisp recipe noisy. Pick
|
|
20
20
|
> the form deliberately; don't reflexively reach for another "do NOT".
|
|
21
21
|
|
|
22
|
+
## Brownfield assess (flow/00-inspect.md)
|
|
23
|
+
|
|
24
|
+
Separate from Stage 00 Idea. After `flow.sh assess` mechanical PASS (no `[FILL]`, boxes
|
|
25
|
+
checked), apply this semantic challenge before planning:
|
|
26
|
+
|
|
27
|
+
- Are material claims in the **Evidence ledger** tagged
|
|
28
|
+
(Authoritative / Observed / Derived / Decision required / Unknown)?
|
|
29
|
+
- Is any **Observed** or **Derived** claim silently promoted to must-build product law
|
|
30
|
+
without operator authority?
|
|
31
|
+
- Are **Decision required** / **Unknown** items listed for the operator — not invented into
|
|
32
|
+
Scope/PRD?
|
|
33
|
+
- If the ledger is empty or only `[FILL]` rows remain while the gate boxes are checked,
|
|
34
|
+
the assessment is hollow — report mechanically-passed-but-qualitatively-weak.
|
|
35
|
+
|
|
22
36
|
## Stage 00 — Idea
|
|
23
37
|
Mechanical: pitch present, one real person named, no FILL.
|
|
24
38
|
**Challenge:** Is the pitch really 3 sentences (who / pain / what)? Is the named person a
|
|
@@ -52,6 +66,9 @@ Mechanical: 7 boxes checked, no FILL.
|
|
|
52
66
|
Mechanical: every feature has Impact (H/M/L) + Grade (A/B/C), no L-above-A in v1, cut list,
|
|
53
67
|
GO/KILL, no FILL.
|
|
54
68
|
**Challenge — watch for GRADE LAUNDERING:**
|
|
69
|
+
- **Material-authority stop:** if materially different externally observable product choices
|
|
70
|
+
remain open (quota, identity key, tenancy model, response contract, enforcement owner, …),
|
|
71
|
+
**stop** — list the choice and consequences. Configurable defaults are not authority.
|
|
55
72
|
- Is any expensive feature quietly graded B when it's really C? (realtime, payments from
|
|
56
73
|
scratch, custom auth, autonomous agentic pipeline, heavy concurrency = C). Call C a C.
|
|
57
74
|
- For every C in scope, is it justified as one of: (1) C IS the product -> it goes FIRST;
|
|
@@ -66,6 +83,8 @@ GO/KILL, no FILL.
|
|
|
66
83
|
## Stage 03 — PRD
|
|
67
84
|
Mechanical: filled from stage 02, numeric success metric, pain&gain table, no FILL.
|
|
68
85
|
**Challenge:**
|
|
86
|
+
- **Material-authority stop:** if the PRD invents policy (who can access what, retention,
|
|
87
|
+
billing rules) with no prior operator/ADR authority, stop and list Decision-required items.
|
|
69
88
|
- Is the success metric a real NUMBER ("first response < 2h"), not "save time" / "better UX"?
|
|
70
89
|
- The pain&gain table is the spine: does *every pain* cite evidence (a stage-01 quote or
|
|
71
90
|
named observation) AND name the v1 feature that kills it? Does *every v1 feature* kill at
|
|
@@ -91,6 +110,8 @@ access/effects column filled, no FILL.
|
|
|
91
110
|
**The "interface" is the project type's seam** (`/flow project-type`): web=endpoint,
|
|
92
111
|
cli=command+flags+output/exit, library=public function+args+return, skill=command/file.
|
|
93
112
|
**Challenge — this is where producer/consumer drift is born (every type):**
|
|
113
|
+
- **Material-authority stop:** access/effects (public/token/admin, writes) that encode product
|
|
114
|
+
policy without operator authority → stop; do not invent tenancy/auth from convenience.
|
|
94
115
|
- Does every PRD feature map to at least one interface, and vice versa?
|
|
95
116
|
- Does every interface have BOTH input and output shapes, with field/flag names that will not
|
|
96
117
|
drift (the #1 AI-build failure: backend ships `player_email`, UI assumed `email`, both green;
|
|
@@ -1,13 +1,15 @@
|
|
|
1
|
-
# Native gate rituals — standalone baseline (v0.22)
|
|
1
|
+
# Native gate rituals — standalone baseline (v0.22+)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
installed.
|
|
3
|
+
Six clean-room playbooks that make flow self-sufficient without any external skill kit
|
|
4
|
+
installed. Rituals 1–5 cover product gates; **R-IMPROVE-HARNESS** covers skill/harness
|
|
5
|
+
maintenance. Each was written fresh from public/generic patterns (persona-panel review,
|
|
5
6
|
generic edge-case taxonomy, STRIDE — public Microsoft SDL methodology, git-log
|
|
6
|
-
retrospection, iterate-to-numeric-target loops
|
|
7
|
-
claudekit-engineer (proprietary, All Rights Reserved)
|
|
8
|
-
ck skill is installed, it is offered as a **richer
|
|
9
|
-
see the seam files (`gate-rules.md`,
|
|
10
|
-
|
|
7
|
+
retrospection, iterate-to-numeric-target loops, evidence-backed harness improvement) —
|
|
8
|
+
none of this text is copied from claudekit-engineer (proprietary, All Rights Reserved)
|
|
9
|
+
or any other kit. Where a matching ck skill is installed, it is offered as a **richer
|
|
10
|
+
alternative**, never a requirement — see the seam files (`gate-rules.md`,
|
|
11
|
+
`adversarial-review.md`, `law/RETRO.md`) for the native-first wiring, and
|
|
12
|
+
`claudekit-skills.md` for the optional-enrichment annex.
|
|
11
13
|
|
|
12
14
|
Every ritual below follows the same rule as the ck skills it stands in for: it
|
|
13
15
|
**informs** the gate; the gate (the `flow.sh` exit code + the semantic challenge) still
|
|
@@ -131,3 +133,38 @@ Steps:
|
|
|
131
133
|
Informs, never judges: this is execution machinery, not a gate — the card's Build/Verify
|
|
132
134
|
gate (`flow.sh check`) still judges the final diff, exactly as it does for any other
|
|
133
135
|
card.
|
|
136
|
+
|
|
137
|
+
## 6. Improve-flow-harness ritual (R-IMPROVE-HARNESS)
|
|
138
|
+
|
|
139
|
+
Purpose: improve one bounded future-agent behavior in **this skill** (guidance, templates,
|
|
140
|
+
gate wording, playbooks, diagnostics) without turning every difficult task into permanent
|
|
141
|
+
process. Port of the *spirit* of repository-harness `$improve-harness` — not a binary
|
|
142
|
+
dependency. **Stable id: `R-IMPROVE-HARNESS`.** (Deferred strategist counsel is
|
|
143
|
+
`R-STRATEGIST` — do not conflate.)
|
|
144
|
+
|
|
145
|
+
When: the operator/maintainer **explicitly** asks to improve the harness/skill after
|
|
146
|
+
observed reusable agent friction. Never auto-fire from `next`/`check`/`auto`. Inspection
|
|
147
|
+
or "report friction" alone does **not** authorize skill edits.
|
|
148
|
+
|
|
149
|
+
Steps:
|
|
150
|
+
1. **Authority** — confirm explicit improve request; record repo root/revision.
|
|
151
|
+
2. **Baseline** — representative job, concrete failure, evidence, human intervention,
|
|
152
|
+
known limitations. No observed baseline → stop with an experiment *proposal* only.
|
|
153
|
+
3. **Earliest gap owner** — context | capability | domain | authority | proof | environment.
|
|
154
|
+
4. **One intervention hypothesis** before editing:
|
|
155
|
+
```
|
|
156
|
+
If <smallest change> at <owner>, then a fresh agent will <observable>
|
|
157
|
+
on <job>, because <mechanism>.
|
|
158
|
+
Evidence that would weaken this: …
|
|
159
|
+
```
|
|
160
|
+
5. Apply **only** that authorized change (prefer skill docs/templates/playbooks over
|
|
161
|
+
new frameworks). Run focused tests for the changed boundary.
|
|
162
|
+
6. **Fresh rerun** — new agent session, equivalent start state. Record whether the
|
|
163
|
+
intervention was available, retrieved/invoked, and relevant. If no fresh rerun:
|
|
164
|
+
decision stays **pending fresh rerun** — **never claim keep**.
|
|
165
|
+
7. **Decision:** keep | revise | remove | pending fresh rerun.
|
|
166
|
+
8. On **keep**, prefer a durable note: `flow.sh harness backlog close …` or
|
|
167
|
+
`decision add` with `fresh_agent_rerun=yes` + session id.
|
|
168
|
+
|
|
169
|
+
Informs, never judges: this ritual maintains the skill; it never passes a product gate
|
|
170
|
+
and never auto-runs on the build path.
|
package/skills-manifest.json
CHANGED
package/src/help.mjs
CHANGED
|
@@ -2,8 +2,6 @@ import { CLI_NAME, PKG_VERSION, SKILL_VERSION, TARGETS } from './constants.mjs';
|
|
|
2
2
|
|
|
3
3
|
export function renderHelp() {
|
|
4
4
|
const targetRows = TARGETS.map((t) => ` ${t.name.padEnd(12)} ${t.label}`).join('\n');
|
|
5
|
-
// v0.23 H5 (red-team): derive the count from TARGETS.length so a future target addition can
|
|
6
|
-
// never again leave a stale hardcoded number in the help text.
|
|
7
5
|
const targetCount = TARGETS.length;
|
|
8
6
|
const skillBit = SKILL_VERSION ? ` (ships skill v${SKILL_VERSION})` : '';
|
|
9
7
|
return `${CLI_NAME} v${PKG_VERSION}${skillBit}
|
|
@@ -12,7 +10,9 @@ Install the flow skill into your coding agent(s).
|
|
|
12
10
|
|
|
13
11
|
USAGE
|
|
14
12
|
npx @manhquy/flow-skill@latest
|
|
15
|
-
|
|
13
|
+
|
|
14
|
+
Always use @latest so npx fetches the newest release.
|
|
15
|
+
Bare "npx @manhquy/flow-skill" may reuse a stale cache.
|
|
16
16
|
|
|
17
17
|
OPTIONS
|
|
18
18
|
-y, --yes Skip prompts; install to default selection (detected + Claude)
|
|
@@ -28,20 +28,18 @@ TARGETS
|
|
|
28
28
|
${targetRows}
|
|
29
29
|
|
|
30
30
|
Notes:
|
|
31
|
-
- Antigravity
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
- --project scope supports only "claude" (agent-contract limitation).
|
|
36
|
-
- Non-detected targets can still be forced via --target or --all.
|
|
31
|
+
- Antigravity writes 2 destinations (CLI + IDE skill homes).
|
|
32
|
+
- --project supports only "claude".
|
|
33
|
+
- "npm i" alone does not install the skill — you must run this CLI.
|
|
34
|
+
- Installer version (this package) ≠ skill product version (SKILL.md).
|
|
37
35
|
|
|
38
36
|
EXAMPLES
|
|
39
|
-
npx @manhquy/flow-skill
|
|
40
|
-
npx @manhquy/flow-skill --yes
|
|
41
|
-
npx @manhquy/flow-skill --yes --all
|
|
42
|
-
npx @manhquy/flow-skill --yes -t claude -t codex
|
|
43
|
-
npx @manhquy/flow-skill --project --dir .
|
|
44
|
-
npx @manhquy/flow-skill --yes --all --dry-run --json
|
|
37
|
+
npx @manhquy/flow-skill@latest
|
|
38
|
+
npx @manhquy/flow-skill@latest --yes
|
|
39
|
+
npx @manhquy/flow-skill@latest --yes --all
|
|
40
|
+
npx @manhquy/flow-skill@latest --yes -t claude -t codex
|
|
41
|
+
npx @manhquy/flow-skill@latest --yes --project --dir .
|
|
42
|
+
npx @manhquy/flow-skill@latest --yes --all --dry-run --json
|
|
45
43
|
|
|
46
44
|
MORE
|
|
47
45
|
Docs: https://github.com/manhquydev/flow-skill#readme
|