flo-ai 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,11 +2,21 @@
2
2
 
3
3
  flo will handle the entire workflow for developing agentic software.
4
4
 
5
- It's early: flo does nothing yet beyond printing its help and its version.
5
+ It's early: flo ships one skill, `peer-review`, which has your coding assistant get a fresh agent to review its work before handing it to you.
6
6
 
7
- ## Run it
7
+ ## Install the skills
8
8
 
9
- You need Node 22 or later. Run flo with npx, no install needed:
9
+ You need Node 22 or later. In your project's root, run:
10
+
11
+ ```bash
12
+ npx flo-ai init
13
+ ```
14
+
15
+ It copies flo's skills into `.agents/skills/`, where Codex and OpenCode find them. If your project has a `.claude/skills/` folder, it also links each skill there for Claude Code. It never creates `.claude/skills/` itself.
16
+
17
+ Run it again to update the skills to the latest flo. It replaces flo's skills with fresh copies, so don't edit them: put project-specific instructions in your own `AGENTS.md` or `CLAUDE.md` instead. Other skills in those folders are left alone.
18
+
19
+ ## Other commands
10
20
 
11
21
  ```bash
12
22
  npx flo-ai --version
package/bin/flo.js CHANGED
@@ -1,5 +1,17 @@
1
1
  #!/usr/bin/env node
2
- import { readFileSync } from 'node:fs';
2
+ import {
3
+ cpSync,
4
+ lstatSync,
5
+ mkdirSync,
6
+ readdirSync,
7
+ readFileSync,
8
+ rmSync,
9
+ statSync,
10
+ symlinkSync,
11
+ unlinkSync,
12
+ } from 'node:fs';
13
+ import { join } from 'node:path';
14
+ import { fileURLToPath } from 'node:url';
3
15
 
4
16
  const { version } = JSON.parse(
5
17
  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
@@ -7,21 +19,103 @@ const { version } = JSON.parse(
7
19
 
8
20
  const usage = `flo: the entire workflow for developing agentic software.
9
21
 
10
- It has no commands yet.
22
+ Usage: flo <command>
23
+ flo [option]
11
24
 
12
- Usage: flo [option]
25
+ Commands:
26
+ init Install flo's skills into the current project
13
27
 
14
28
  Options:
15
29
  --help Show this help
16
30
  --version Print flo's version
17
31
  `;
18
32
 
33
+ // Copies every skill the package ships into .agents/skills/, and links each
34
+ // one from .claude/skills/ when that directory exists. Returns the exit code.
35
+ function init() {
36
+ const source = fileURLToPath(new URL('../skills/', import.meta.url));
37
+ const names = readdirSync(source, { withFileTypes: true })
38
+ .filter((entry) => entry.isDirectory())
39
+ .map((entry) => entry.name)
40
+ .sort();
41
+ let code = 0;
42
+
43
+ mkdirSync(join('.agents', 'skills'), { recursive: true });
44
+ for (const name of names) {
45
+ const dest = join('.agents', 'skills', name);
46
+ rmSync(dest, { recursive: true, force: true });
47
+ cpSync(join(source, name), dest, { recursive: true });
48
+ process.stdout.write(`Copied .agents/skills/${name}\n`);
49
+ }
50
+
51
+ if (!isDirectory(join('.claude', 'skills'))) return code;
52
+
53
+ for (const name of names) {
54
+ const link = join('.claude', 'skills', name);
55
+ const shown = `.claude/skills/${name}`;
56
+ const target = `../../.agents/skills/${name}`;
57
+ const existing = lstatOrNull(link);
58
+ // .claude/skills and .agents/skills are one folder through a symlink, so
59
+ // the copy is already visible here.
60
+ if (existing && !existing.isSymbolicLink() && sameFolder(link, join('.agents', 'skills', name))) {
61
+ continue;
62
+ }
63
+ if (existing && !existing.isSymbolicLink()) {
64
+ process.stderr.write(
65
+ `Left ${shown} as it is: it isn't a symlink, so flo won't replace it. Remove it and rerun flo init to link the skill.\n`,
66
+ );
67
+ code = 1;
68
+ continue;
69
+ }
70
+ try {
71
+ if (existing) unlinkSync(link);
72
+ symlinkSync(target, link);
73
+ process.stdout.write(`Linked ${shown} -> ${target}\n`);
74
+ } catch (error) {
75
+ process.stderr.write(`Couldn't link ${shown}: ${error.message}\n`);
76
+ code = 1;
77
+ }
78
+ }
79
+ return code;
80
+ }
81
+
82
+ function isDirectory(path) {
83
+ try {
84
+ return statSync(path).isDirectory();
85
+ } catch {
86
+ return false;
87
+ }
88
+ }
89
+
90
+ // Compares the folders themselves, not their paths, so different spellings of
91
+ // one folder (such as case on a case-insensitive filesystem) still match.
92
+ function sameFolder(a, b) {
93
+ const [x, y] = [statSync(a), statSync(b)];
94
+ return x.dev === y.dev && x.ino === y.ino;
95
+ }
96
+
97
+ function lstatOrNull(path) {
98
+ try {
99
+ return lstatSync(path);
100
+ } catch (error) {
101
+ if (error.code === 'ENOENT') return null;
102
+ throw error;
103
+ }
104
+ }
105
+
19
106
  const args = process.argv.slice(2);
20
107
 
21
108
  if (args.length === 0 || (args.length === 1 && args[0] === '--help')) {
22
109
  process.stdout.write(usage);
23
110
  } else if (args.length === 1 && args[0] === '--version') {
24
111
  process.stdout.write(`${version}\n`);
112
+ } else if (args.length === 1 && args[0] === 'init') {
113
+ try {
114
+ process.exitCode = init();
115
+ } catch (error) {
116
+ process.stderr.write(`flo init failed: ${error.message}\n`);
117
+ process.exitCode = 1;
118
+ }
25
119
  } else {
26
120
  process.stderr.write(`Unknown argument: ${args.join(' ')}\n\n${usage}`);
27
121
  process.exitCode = 1;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "flo-ai",
3
- "version": "0.1.0",
4
- "description": "The entire workflow for developing agentic software. Early: it does nothing yet beyond --version.",
3
+ "version": "0.2.0",
4
+ "description": "The entire workflow for developing agentic software. Early: it installs one skill, peer-review.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {
@@ -9,6 +9,7 @@
9
9
  },
10
10
  "files": [
11
11
  "bin/",
12
+ "skills/",
12
13
  "README.md"
13
14
  ],
14
15
  "engines": {
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: peer-review
3
+ description: Have a fresh agent review an implementation, apply what it finds, then hand the work to the user. Use once you've finished implementing something, before you hand it to the user.
4
+ ---
5
+
6
+ # Peer review
7
+
8
+ flo manages this file. `flo init` replaces it, so edits here are lost. To change how this project reviews or hands off work, say so in the project's own instructions, which this skill follows.
9
+
10
+ Before the user sees your work, an agent that didn't write it should try to find what's wrong with it. Then you fix what holds up and hand the work over.
11
+
12
+ ## 1. Get a review
13
+
14
+ Start a reviewer: a subagent with a fresh context, on a model at least as capable as Claude Opus 5.5 or GPT Sol 6.1. Those are examples of the bar, not the only choices, and your own model is fine. What matters is the fresh context.
15
+
16
+ Give it what the work was meant to do in its original form: the user's request, and the issue, design and specs themselves if they exist, not your summary of them. Point it to the changes and to how the project checks its work. Leave out your reasoning and your case for why the work is right, so it judges what you built rather than what you meant.
17
+
18
+ Its job is to find out whether the work is right. Have it judge whether the work:
19
+
20
+ - does what it was meant to, and simply;
21
+ - holds up when things fail, and breaks nothing that worked;
22
+ - has tests that would fail without it.
23
+
24
+ It changes nothing. Every finding must be shown, not suspected: it runs the project's checks, reproduces each problem, and reports where it is and how to show it, along with any check it couldn't run. Where it disagrees with something the user decided, it asks instead of proposing a fix.
25
+
26
+ If you can't start a reviewer that meets the bar, never skip the review silently. Open the handoff by saying the work wasn't reviewed, or which weaker model reviewed it.
27
+
28
+ ## 2. Apply what holds up
29
+
30
+ Treat each finding as a claim to check, not an order. Fix what holds up. Decline only what you can show is wrong, and mention it in a few words in the handoff. If a finding would change something the user decided, leave it and ask the user.
31
+
32
+ If your fixes changed more than wording, start a fresh reviewer with the same material and the earlier findings. It verifies each one, then reviews what changed since, without reopening what was settled. Stop when a review finds nothing new, or after three rounds, and hand off whatever is still open.
33
+
34
+ ## 3. Hand off
35
+
36
+ If the project says how to hand off work, do that. Otherwise, end with a report as short as it can be while still telling the user what was done, what was and wasn't verified, and what needs their decision. The review gets a line: what it caught, and anything you declined.
37
+
38
+ The review goes in the handoff only, never into the project's files.