@digital-agora/friday 0.0.0-stage → 0.10.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/LICENSE +21 -0
- package/README.md +296 -2
- package/bundles/friday-claude-0.1.0.zip +0 -0
- package/bundles/friday-opencode-0.1.0.zip +0 -0
- package/dist/adapters/adapter.js +6 -0
- package/dist/adapters/claude/guards.js +40 -0
- package/dist/adapters/claude/index.js +161 -0
- package/dist/adapters/claude/runtime.js +645 -0
- package/dist/adapters/claude/workflows.js +323 -0
- package/dist/adapters/drivers.js +300 -0
- package/dist/adapters/index.js +16 -0
- package/dist/adapters/opencode/index.js +232 -0
- package/dist/adapters/skill.js +327 -0
- package/dist/build.js +77 -0
- package/dist/cli.js +197 -0
- package/dist/frontmatter.js +16 -0
- package/dist/graph.js +218 -0
- package/dist/handoff.js +329 -0
- package/dist/install.js +137 -0
- package/dist/ir.js +177 -0
- package/dist/load.js +42 -0
- package/dist/paths.js +24 -0
- package/dist/prompts.js +230 -0
- package/dist/specialize.js +237 -0
- package/dist/step-schemas.js +444 -0
- package/dist/types.js +8 -0
- package/dist/validate.js +576 -0
- package/pack/conventions/changesets.yaml +20 -0
- package/pack/conventions/ci-workflows.yaml +16 -0
- package/pack/conventions/config-secrets.yaml +16 -0
- package/pack/conventions/data-classification.yaml +16 -0
- package/pack/conventions/decisions.yaml +13 -0
- package/pack/conventions/git.yaml +28 -0
- package/pack/conventions/hexagonal.yaml +31 -0
- package/pack/conventions/security-code.yaml +17 -0
- package/pack/conventions/testing.yaml +44 -0
- package/pack/conventions/typescript-node.yaml +16 -0
- package/pack/model-policy.yaml +80 -0
- package/pack/orchestrations/architecture-decision.yaml +52 -0
- package/pack/orchestrations/bugfix-tdd.yaml +67 -0
- package/pack/orchestrations/data-analysis.yaml +23 -0
- package/pack/orchestrations/discovery.yaml +214 -0
- package/pack/orchestrations/feature-delivery.yaml +129 -0
- package/pack/orchestrations/prompt-delivery.yaml +155 -0
- package/pack/orchestrations/prompt-discovery.yaml +201 -0
- package/pack/orchestrations/release.yaml +40 -0
- package/pack/pack.yaml +137 -0
- package/pack/personas/architect.yaml +18 -0
- package/pack/personas/backend-engineer.yaml +21 -0
- package/pack/personas/data-analyst-non-pii.yaml +14 -0
- package/pack/personas/data-analyst-pii.yaml +28 -0
- package/pack/personas/devops-engineer.yaml +19 -0
- package/pack/personas/frontend-engineer.yaml +18 -0
- package/pack/personas/git-steward.yaml +24 -0
- package/pack/personas/lead-developer.yaml +23 -0
- package/pack/personas/prompt-engineer.yaml +38 -0
- package/pack/personas/qa-engineer.yaml +24 -0
- package/pack/personas/security-steward.yaml +20 -0
- package/package.json +47 -4
- package/schemas/convention.schema.yaml +46 -0
- package/schemas/handoff.schema.yaml +303 -0
- package/schemas/model-policy.schema.yaml +33 -0
- package/schemas/orchestration.schema.yaml +224 -0
- package/schemas/pack.schema.yaml +168 -0
- package/schemas/persona.schema.yaml +41 -0
- package/schemas/specialization-patch.schema.yaml +39 -0
- package/schemas/specialization.schema.yaml +57 -0
package/dist/load.js
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { readdirSync, readFileSync, existsSync } from "node:fs";
|
|
2
|
+
import { join, relative } from "node:path";
|
|
3
|
+
import { parse } from "yaml";
|
|
4
|
+
import { resolvePackDir } from "./paths.js";
|
|
5
|
+
const FOLDERS = [
|
|
6
|
+
["persona", "personas"],
|
|
7
|
+
["convention", "conventions"],
|
|
8
|
+
["orchestration", "orchestrations"],
|
|
9
|
+
// The folder's name before orchestrations; still read so existing packs keep loading.
|
|
10
|
+
["orchestration", "workflows"],
|
|
11
|
+
];
|
|
12
|
+
function readYaml(dir, file, raw, kind) {
|
|
13
|
+
const abs = join(dir, file);
|
|
14
|
+
try {
|
|
15
|
+
raw.docs.push({ kind, file, data: parse(readFileSync(abs, "utf8")) });
|
|
16
|
+
}
|
|
17
|
+
catch (err) {
|
|
18
|
+
raw.parseErrors.push({ file, message: err.message });
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
export function loadRawPack(pack) {
|
|
22
|
+
const dir = resolvePackDir(pack);
|
|
23
|
+
const raw = { dir, docs: [], parseErrors: [], warnings: [] };
|
|
24
|
+
readYaml(dir, "pack.yaml", raw, "pack");
|
|
25
|
+
if (existsSync(join(dir, "model-policy.yaml")))
|
|
26
|
+
readYaml(dir, "model-policy.yaml", raw, "model-policy");
|
|
27
|
+
else
|
|
28
|
+
raw.parseErrors.push({ file: "model-policy.yaml", message: "missing" });
|
|
29
|
+
for (const [kind, folder] of FOLDERS) {
|
|
30
|
+
const sub = join(dir, folder);
|
|
31
|
+
if (!existsSync(sub))
|
|
32
|
+
continue;
|
|
33
|
+
if (folder === "workflows")
|
|
34
|
+
raw.warnings.push({ file: "workflows/", message: "rename the folder to orchestrations/; workflows/ is read for now" });
|
|
35
|
+
for (const name of readdirSync(sub).sort()) {
|
|
36
|
+
if (name.endsWith(".yaml") || name.endsWith(".yml")) {
|
|
37
|
+
readYaml(dir, relative(dir, join(sub, name)), raw, kind);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
return raw;
|
|
42
|
+
}
|
package/dist/paths.js
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { dirname, join, resolve } from "node:path";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
4
|
+
// The package root holds schemas/ and pack/, both when run from src/ (tests) and dist/ (published).
|
|
5
|
+
function findPackageRoot() {
|
|
6
|
+
let dir = dirname(fileURLToPath(import.meta.url));
|
|
7
|
+
for (let i = 0; i < 5; i++) {
|
|
8
|
+
if (existsSync(join(dir, "package.json")) && existsSync(join(dir, "schemas")))
|
|
9
|
+
return dir;
|
|
10
|
+
dir = dirname(dir);
|
|
11
|
+
}
|
|
12
|
+
throw new Error("friday: package root not found (no schemas/ next to package.json)");
|
|
13
|
+
}
|
|
14
|
+
export const PACKAGE_ROOT = findPackageRoot();
|
|
15
|
+
export const SCHEMAS_DIR = join(PACKAGE_ROOT, "schemas");
|
|
16
|
+
/** Friday ships one pack: its own personas, orchestrations and conventions. */
|
|
17
|
+
export const PACK_DIR = join(PACKAGE_ROOT, "pack");
|
|
18
|
+
/** The pack directory: Friday's own, or another directory (tests, pack authors). */
|
|
19
|
+
export function resolvePackDir(dir) {
|
|
20
|
+
const d = dir ? resolve(dir) : PACK_DIR;
|
|
21
|
+
if (!existsSync(join(d, "pack.yaml")))
|
|
22
|
+
throw new Error(`friday: no pack.yaml in ${d}`);
|
|
23
|
+
return d;
|
|
24
|
+
}
|
package/dist/prompts.js
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
export const CLARIFY = (topic) => [
|
|
2
|
+
`Clarify: ${topic}`,
|
|
3
|
+
"",
|
|
4
|
+
"Assumptions kill. List only questions that block a safe, testable plan, each with 2-4",
|
|
5
|
+
"options, why it matters and your recommended option. Anything you would otherwise assume",
|
|
6
|
+
"goes in `assumptions` with a blocking classification; only blockers need user confirmation.",
|
|
7
|
+
"Put what you can already",
|
|
8
|
+
"establish from the repository, the conventions and the answers in `result`.",
|
|
9
|
+
"Do not ask what the answers above already settle.",
|
|
10
|
+
"",
|
|
11
|
+
"Ask only what blocks: a question belongs here when a downstream agent could not write or",
|
|
12
|
+
"test a task without the answer. Mark non-blocking details `blocking: false`; discovery defers",
|
|
13
|
+
"them as follow-up work and continues. Where a loaded convention or an earlier answer already",
|
|
14
|
+
"decides it, that is not an assumption: put it in `result` and cite the convention. Do not ask",
|
|
15
|
+
"about edge cases beyond the acceptance criteria, wording, or nice-to-haves.",
|
|
16
|
+
"",
|
|
17
|
+
"Give every item a `topic` (short kebab-case subject; reuse the topic another step or an answer",
|
|
18
|
+
"already uses for the same subject), `blocking`, `changesBehaviour`, and, if it conflicts with a",
|
|
19
|
+
"recorded answer, `contradicts` with that answer's id.",
|
|
20
|
+
].join("\n");
|
|
21
|
+
/** Added to the brief of every step that builds a prompt pyramid level (decision 36). */
|
|
22
|
+
export const LEVEL_PROPOSALS = [
|
|
23
|
+
"This step builds what a person approves at its stop (a prompt pyramid level or a checkpoint such",
|
|
24
|
+
"as the request brief). For every decision",
|
|
25
|
+
"the request, the answers and the conventions leave open, propose: a question with 2-4 options",
|
|
26
|
+
"and your recommended one, marked `proposable: true` when the recommendation is defensible from",
|
|
27
|
+
"the request, the conventions and the approved levels below. The person sees all proposals as one",
|
|
28
|
+
"list at the level's approval and accepts or changes them; you never decide for them. Mark",
|
|
29
|
+
"`proposable: false` (asked on its own) when the decision touches personal data, security or data",
|
|
30
|
+
"access, a cost or risk only the person can own, or when no option can be recommended. Do not",
|
|
31
|
+
"ask about wording or nice-to-haves.",
|
|
32
|
+
].join("\n");
|
|
33
|
+
export const GAP_ANALYSIS = [
|
|
34
|
+
"Run a gap analysis over the request, every answer, every resolved gap and every result so far.",
|
|
35
|
+
"A gap is potentially missing information a downstream agent would have to assume: a missing decision, an",
|
|
36
|
+
"unclassified entity or field, a convention the plan breaks or does not cover, an untestable",
|
|
37
|
+
"acceptance criterion, an unknown owner, environment or region, a prerequisite (a release or",
|
|
38
|
+
"package version from another repository, a service) without a check the delivery agents can run.",
|
|
39
|
+
"For each open gap give: area, the gap, why it is a gap (cite the convention or the missing",
|
|
40
|
+
"information), impact, 1-4 solutions with their trade-offs, and the recommended solution.",
|
|
41
|
+
"Return only gaps that are still open. Return questions and assumptions too, if any.",
|
|
42
|
+
"Mark a gap blocking only when a downstream agent could not safely write or test a task without",
|
|
43
|
+
"closing it. Defer other useful details. What a loaded convention or an earlier answer already",
|
|
44
|
+
"decides is not a gap.",
|
|
45
|
+
].join("\n");
|
|
46
|
+
export const CONSOLIDATE = [
|
|
47
|
+
"You are this round's single list of open items: the user sees only what you return.",
|
|
48
|
+
"1. Merge duplicates and overlaps among the open items below into one item; list the ids it",
|
|
49
|
+
" replaces in mergedFrom and keep one of them as its id.",
|
|
50
|
+
"2. Drop what an answer, a resolved gap or a loaded convention already settles, with the reason.",
|
|
51
|
+
" Keep genuine non-blocking follow-up details with blocking: false so the workflow can",
|
|
52
|
+
" defer them instead of asking the user or blocking implementation.",
|
|
53
|
+
"3. Find contradictions: two answers, an answer and a step's result or decision, or two steps'",
|
|
54
|
+
" results that cannot both hold. For each give what conflicts, the sources (ids) in between,",
|
|
55
|
+
" why it blocks, and 2-4 options built by the inner-join principle: first the overlap, what",
|
|
56
|
+
" every source already holds or accepts; then the sweet spot as the first option, the overlap",
|
|
57
|
+
" plus the least each side must add to meet the acceptance criteria; then each side as it",
|
|
58
|
+
" stands. Recommend the sweet spot unless the overlap is empty or cannot meet an acceptance",
|
|
59
|
+
" criterion (say which in why). Do not pick one yourself: the user does.",
|
|
60
|
+
" State in premise the assumption every option rests on (decision 54), and end the options",
|
|
61
|
+
" with \"None of these: the premise is wrong\", which asks the user for their design.",
|
|
62
|
+
"4. Add the gaps you find yourself. A scope (result.scopes) whose expected outcome the user has",
|
|
63
|
+
" not stated, in the request or an answer, is a blocking question: never drop or defer it.",
|
|
64
|
+
"Every open item below must end up in your output, in a mergedFrom, or in dropped.",
|
|
65
|
+
].join("\n");
|
|
66
|
+
export const HANDOFF = (workflow) => [
|
|
67
|
+
"Every blocker is answered or resolved. Non-blocking items may be deferred. Write the handoff:",
|
|
68
|
+
"",
|
|
69
|
+
"1. `docs/friday/<workId>/handoff.yaml`, valid against Friday's handoff schema, with",
|
|
70
|
+
` workflow: ${workflow.id}, status: awaiting-approval, openQuestions: [], the scope with`,
|
|
71
|
+
" acceptance criteria, the scopes (scope.scopes: each with its expected outcome in the user's",
|
|
72
|
+
" words and where it comes from, request or the answer id; never an assumed outcome; every task",
|
|
73
|
+
" names its scope), the decisions (id, decision, why, where), the data classification",
|
|
74
|
+
" (entity, class, owner, retention), the tasks from the breakdown (with their covers, needs,",
|
|
75
|
+
" breaks and closedBy), every prerequisite (id, kind, description, check, status: met only when",
|
|
76
|
+
" its check passed where the delivery agents run, not just \"published\"), every question with",
|
|
77
|
+
" its answer (the answers above), and every gap with its resolution (the resolved gaps above,",
|
|
78
|
+
" including why, impact, solutions and the recommended index).",
|
|
79
|
+
" Include the architect's `contracts` and `standards`, the technical lead's `interfaceContracts`,",
|
|
80
|
+
" QA's `testPlan`, and the senior developer's `plan` and `expectedRed` from earlier steps.",
|
|
81
|
+
" Add `deliveryPolicy.maySettle`: the kinds of decision delivery may take itself (test-fixture",
|
|
82
|
+
" fixes, pruning stale lint suppressions, named exceptions for existing repo facts, command",
|
|
83
|
+
" mapping), from the user's answers; leave it empty if the user did not allow any.",
|
|
84
|
+
" Add `commands`: the repository's command map per test pyramid level (static, unit,",
|
|
85
|
+
" integration, e2e), detected from its packageManager field or lockfile, its package.json",
|
|
86
|
+
" scripts and its AGENTS.md / CLAUDE.md, e.g. `npm run typecheck` and `npm run test:architecture`.",
|
|
87
|
+
...(workflow.steps.some((s) => s.type === "agent" && s.output === "briefs")
|
|
88
|
+
? [
|
|
89
|
+
" Add `briefs`: the task briefs from the step that wrote them, unchanged, one per task. A task",
|
|
90
|
+
" without a brief, or a brief naming a file, contract or decision the handoff lacks, fails the check.",
|
|
91
|
+
]
|
|
92
|
+
: []),
|
|
93
|
+
...(workflow.steps.some((s) => s.type === "approval" && s.checkpoint)
|
|
94
|
+
? [
|
|
95
|
+
" Add `checkpoints`: every approved checkpoint, in order, with `id`, `approvedBy` (the role in",
|
|
96
|
+
" `approvals`, never a person's name), a one-line `summary` and `file`:",
|
|
97
|
+
" docs/friday/<workId>/<checkpoint>.md. Write each file with the checkpoint's approved result",
|
|
98
|
+
" in full, exactly as the person approved it.",
|
|
99
|
+
]
|
|
100
|
+
: []),
|
|
101
|
+
...(workflow.steps.some((s) => s.type === "approval" && s.level)
|
|
102
|
+
? [
|
|
103
|
+
" Add `promptPyramid.levels`: every approved prompt pyramid level, bottom first, with `id`,",
|
|
104
|
+
" `approvedBy` (the role in `approvals`, never a person's name), a one-line `summary` and",
|
|
105
|
+
" `file`: docs/friday/<workId>/prompt/<level>.md. Write each file with the level's approved",
|
|
106
|
+
" result in full, exactly as the person approved it; change nothing.",
|
|
107
|
+
" Add `commands.evals`: the command(s) that run the evals, as the breakdown planned them.",
|
|
108
|
+
" The handoff is delivered by `/friday-prompt-delivery`, which runs the eval run.",
|
|
109
|
+
]
|
|
110
|
+
: []),
|
|
111
|
+
"2. `docs/friday/<workId>/gap-analysis.md`: one section per gap with the gap, why, impact,",
|
|
112
|
+
" every solution with its trade-off, the recommendation and the chosen resolution, then a",
|
|
113
|
+
" summary table.",
|
|
114
|
+
"",
|
|
115
|
+
"A scope whose expected outcome the user never gave (for example when the scope was frozen)",
|
|
116
|
+
"moves to scope.outOfScope with the tasks that would deliver it; never write an outcome for it.",
|
|
117
|
+
"List every deferred non-blocking or scope-frozen item in scope.outOfScope as a",
|
|
118
|
+
"follow-up work item and in a \"Deferred\" section of gap-analysis.md. No task may depend on one.",
|
|
119
|
+
"",
|
|
120
|
+
"Do not write handoff.md: Friday renders it from handoff.yaml (`friday handoff render`), and the",
|
|
121
|
+
"user approves that render.",
|
|
122
|
+
"Do not set status: approved; only the user approves. Return the two paths and a summary.",
|
|
123
|
+
].join("\n");
|
|
124
|
+
/** Placeholder for a level's commands; replaced at run time from the repository's command map. */
|
|
125
|
+
export const commandToken = (level) => `@@commands:${level}@@`;
|
|
126
|
+
/** What a step may run, from the bottom of the pyramid up to its scope, and what it must not. */
|
|
127
|
+
export function scopeText(pyramid, scope, loop) {
|
|
128
|
+
const lines = ["Test scope for this step (bottom of the pyramid first):"];
|
|
129
|
+
for (const l of pyramid.levels) {
|
|
130
|
+
// The commands are a token the runtime replaces with the repository's command map
|
|
131
|
+
// (args.commands or handoff.commands), falling back to the pack defaults.
|
|
132
|
+
if (scope.includes(l.id))
|
|
133
|
+
lines.push(`- ${l.id}: ${l.description}. Run: ${commandToken(l.id)}`);
|
|
134
|
+
}
|
|
135
|
+
lines.push("These are this repository's commands (its package manager and script names). A round that ran", "the mapped commands for its scope and they passed is green.");
|
|
136
|
+
if (loop) {
|
|
137
|
+
const above = pyramid.levels.filter((l) => !scope.includes(l.id)).map((l) => l.id);
|
|
138
|
+
lines.push(`Never run ${above.join(" or ")} suites here (nothing containing ${pyramid.forbiddenInLoop.map((f) => `\`${f}\``).join(", ")}):`, "they are slow, and integration runs them once at the end and turns failures into follow-up tasks.", "Scope every command to the package and test files this task touches, not the whole workspace.", "Report every test command you ran, verbatim. A forbidden command makes the round fail.");
|
|
139
|
+
}
|
|
140
|
+
return lines.join("\n");
|
|
141
|
+
}
|
|
142
|
+
export const TDD_TEST = "Write the failing tests for this task first: one test per acceptance criterion and permission rule, at the lowest pyramid level that can prove it (unit with in-memory adapters where possible). Do not repeat a criterion at every level: a higher level only for what a lower one cannot prove. Report each test's level in levels. Do not decide behaviour the handoff leaves open (error types, helper signatures, option names, retry semantics): return each as a question in `questions`, with options and your recommendation, never as a note in the summary; a non-empty list stops the run and goes back upstream. Run them and report the output that proves they fail for the right reason. Do not implement. If a criterion can only be proven above the loop's scope (the task's lowestLevel), write that test but do not run it; integration will. If the acceptance is already met (for example a resumed run) and existing tests prove every criterion and pass, do not write new tests and do not return blocked: return status done with alreadyMet: true, those tests in testFiles and their passing output as proof in failureOutput.";
|
|
143
|
+
export const TDD_IMPL = "Make the failing tests for this task pass by changing the code, never the tests: do not edit, weaken, skip or delete a test, and do not change an assertion to match what the code does. Run them before reporting, within the test scope only. Only if a new test contradicts an existing test or a repository fact (so no correct code can pass both) report it in testConflict, naming the test, what it contradicts and why; do not change either and do not return blocked. It goes back to test-design, which decides.";
|
|
144
|
+
export const TDD_TEST_CONFLICT = [
|
|
145
|
+
"The implementer says one of your tests contradicts an existing test or a repository fact. Decide first; a test is not changed to let the code pass.",
|
|
146
|
+
"Check the claim against the acceptance criterion and the repository. If the test follows the criterion and the conflict is not real (the code can pass it), keep the test unchanged: return testChange { kept: true, criterion, justification } with why it stands, and the failure output as it is.",
|
|
147
|
+
"Change the test only if it is wrong: it asserts more or other than the criterion, or contradicts a repository fact the criterion does not change. Then return testChange { kept: false, criterion, justification } naming the fact or existing test and why the new test still proves the criterion; never weaken what the criterion asks, never change the existing test. Run it and report the new failure output.",
|
|
148
|
+
"If the criterion itself contradicts the repository, return blocked: it goes back upstream.",
|
|
149
|
+
].join(" ");
|
|
150
|
+
/** Opt-in (args.commitAtGreen): a task's commit is its checkpoint for a resumed run. */
|
|
151
|
+
export const COMMIT_AT_GREEN = "Checkpoint: when this task's tests pass, commit only this task's files as one commit whose body ends with the trailer `Friday-Task: <workId>/<taskId>`, following the `git` convention. Do not push.";
|
|
152
|
+
export const RESUME_FROM_COMMIT = "Resume: if a commit with the trailer `Friday-Task: <workId>/<taskId>` for this task already exists (git log --grep) and its tests pass, return alreadyMet with those tests as proof.";
|
|
153
|
+
export const TDD_VERIFY = [
|
|
154
|
+
"Run this task's tests and the static checks, within the test scope only, and report green or the exact failures. Do not edit code.",
|
|
155
|
+
"Tasks of one wave share the working tree: a test written by another task (listed under test ownership below, or",
|
|
156
|
+
"proving another task's acceptance) may be red on purpose. It does not make this task red: report it in",
|
|
157
|
+
"foreignFailures with its owner and keep it out of failures. green is about this task's own tests and checks.",
|
|
158
|
+
"Report every command you ran in evidence, verbatim, with its exit code: green counts only when each level in",
|
|
159
|
+
"scope has a command that ran and passed. Saying a suite passed without running it is not evidence.",
|
|
160
|
+
].join(" ");
|
|
161
|
+
export const INTEGRATE = [
|
|
162
|
+
"Integrate this stack's finished tasks: wire the adapters in the composition roots (wiring only).",
|
|
163
|
+
"Then run the full pyramid for this stack, bottom up, and report every suite with its result.",
|
|
164
|
+
"Run the full suites, not one task's tests: test ownership does not apply here, every failure counts.",
|
|
165
|
+
"Do not fix failures here. For each failure or gap, return a follow-up task: the stack, the",
|
|
166
|
+
"codebase, the taskKind (scaffold, adapter or implement), acceptance criteria that would make",
|
|
167
|
+
"the suite pass, dependsOn, the lowest pyramid level that can reproduce it (lowestLevel) and",
|
|
168
|
+
"the reason (the failing suite and its output). Follow-ups go through the bottom-of-pyramid task",
|
|
169
|
+
"loop and integration runs again. A gap that needs a decision the handoff does not settle is",
|
|
170
|
+
"not a follow-up: return status blocked with the question.",
|
|
171
|
+
].join("\n");
|
|
172
|
+
/** Rules every task breakdown follows; appended to the breakdown step's own prompt (decision 50). */
|
|
173
|
+
export const BREAKDOWN = [
|
|
174
|
+
"Breakdown rules:",
|
|
175
|
+
"- List every scope acceptance criterion in result.acceptance, each starting with its id (AC1, AC2, ...),",
|
|
176
|
+
" and give every task `covers`: the ids of the criteria it proves. Every criterion is covered by at",
|
|
177
|
+
" least one task; an uncovered one is an open gap that stops the breakdown.",
|
|
178
|
+
"- A dependency or version bump or a lockfile change is its own task with `needs: [registry]`; every",
|
|
179
|
+
" task that uses the new version lists it in dependsOn. Record the released version it needs as a",
|
|
180
|
+
" prerequisite with a check the delivery agents can run.",
|
|
181
|
+
"- A task that removes or renames a public symbol other codebases use lists those codebases in",
|
|
182
|
+
" `breaks` and the tasks that fix them in `closedBy`.",
|
|
183
|
+
"- A scaffold task whose tests need new test helpers states each helper's public signature (name,",
|
|
184
|
+
" parameters, option names, return shape) in its acceptance, so the test designer decides nothing.",
|
|
185
|
+
].join("\n");
|
|
186
|
+
/** Downstream, before anything that builds or tests: one install where the agents run (decision 48). */
|
|
187
|
+
export const PREFLIGHT = [
|
|
188
|
+
"Preflight: prepare the workspace once for every later step of this run. Do not edit source code,",
|
|
189
|
+
"tests, manifests or the lockfile.",
|
|
190
|
+
"1. Install: install the workspace from its lockfile with the repository's package manager, the",
|
|
191
|
+
" way every task loop will use it: offline (e.g. `pnpm install --frozen-lockfile --offline`) when",
|
|
192
|
+
" the local store holds every package, otherwise frozen-lockfile with the registry access this",
|
|
193
|
+
" environment has. Never print, pass as an argument, write or commit a token. Report the commands.",
|
|
194
|
+
"2. Prerequisites: run or verify the `check` of every prerequisite in the handoff, here.",
|
|
195
|
+
"3. Version pins: every package version the handoff's tasks or prerequisites name must be in the",
|
|
196
|
+
" lockfile and installed, or installable from this environment (a bump task will install it).",
|
|
197
|
+
"Report each prerequisite and pin with resolved true or false and the evidence. If any cannot be",
|
|
198
|
+
"resolved here, return status blocked with the reason and one question per item (for example: who",
|
|
199
|
+
"with registry access refreshes the lockfile and the store). Never change a pin to make it resolve.",
|
|
200
|
+
].join("\n");
|
|
201
|
+
/** Told to every step after a passed preflight: the workspace is ready. */
|
|
202
|
+
export const BOOTSTRAPPED = "The preflight step already installed the workspace (its commands are in the results above). Do not run an online install or change the lockfile; a missing package is a blocker: return status blocked.";
|
|
203
|
+
export const GUARD_CHECKS = [
|
|
204
|
+
"Guard tests against the current repository: for every new guard test the tasks add (architecture,",
|
|
205
|
+
"boundary, import, rules or lint gate), run it now against the repository as it is, or dry-run",
|
|
206
|
+
"the check it encodes (a grep, the existing gate with the new rule), and report each in",
|
|
207
|
+
"result.guardChecks with the command, pass, fail or not-run, and what it found. An existing",
|
|
208
|
+
"violation is a repository fact to settle here: name the task or gap that addresses it in",
|
|
209
|
+
"addressedBy. A failing check nothing addresses becomes an open gap.",
|
|
210
|
+
].join("\n");
|
|
211
|
+
export const GATE_FIX = "Fix these findings in the code, then re-run the checks. Do not change a test to make a check pass; if a finding says a test is wrong, say so in your summary with the criterion and why, and leave the test to the QA engineer:";
|
|
212
|
+
export const RETRO = [
|
|
213
|
+
"The run is over. Write `docs/friday/<workId>/retro.md` (create the folder if needed) from the run",
|
|
214
|
+
"facts below and the results of earlier steps, with sections: Stops (where and why the run",
|
|
215
|
+
"stopped), Reversed answers (answers that superseded or reframed earlier ones, and what input",
|
|
216
|
+
"would have prevented them), Red rounds and causes, Upstream returns, and Proposed Friday",
|
|
217
|
+
"improvements. Do not commit it. Keep it to generic lessons: no personal data, tokens or",
|
|
218
|
+
"repository-internal names. Return each proposed Friday improvement in `improvements`.",
|
|
219
|
+
"Add an Indicators section and return the same numbers in `indicators`, counted from the run",
|
|
220
|
+
"facts only (leave out what the run does not show): tasks, tasks green on the first verify",
|
|
221
|
+
"round, red rounds beyond the first, gate loops, upstream returns, question rounds, and files",
|
|
222
|
+
"changed outside the build plan (plan drift). Each run's numbers are compared across runs.",
|
|
223
|
+
].join("\n");
|
|
224
|
+
export const DECIDE_BLOCKER = [
|
|
225
|
+
"A delivery agent is blocked on the question below. You decide for delivery, under the handoff's",
|
|
226
|
+
"standing policy (deliveryPolicy) and its decisions; you never ask the user. Settle it (settled:",
|
|
227
|
+
"true, with the decision and why) only when the policy allows that kind of decision and the",
|
|
228
|
+
"handoff and repository facts support one answer. Product behaviour, user-facing copy and anything",
|
|
229
|
+
"that widens security or data access are never yours: return settled: false with that kind.",
|
|
230
|
+
].join("\n");
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
// Specializations (decision 41): a folder that adds to Friday's pack and overrides it. Friday's own
|
|
2
|
+
// pack holds only generic rules; a project's rules (Hybrid-Day's, or the project's own .friday/)
|
|
3
|
+
// come in a specialization, merged into the raw pack before validation, so the merged pack goes
|
|
4
|
+
// through every schema and cross-reference check. Order is the order given; the later one wins.
|
|
5
|
+
import { existsSync, readFileSync, readdirSync } from "node:fs";
|
|
6
|
+
import { createRequire } from "node:module";
|
|
7
|
+
import { dirname, join, resolve } from "node:path";
|
|
8
|
+
import { Ajv } from "ajv";
|
|
9
|
+
import { parse } from "yaml";
|
|
10
|
+
import { PACKAGE_ROOT, SCHEMAS_DIR } from "./paths.js";
|
|
11
|
+
export const SPECIALIZATION_FILE = "specialization.yaml";
|
|
12
|
+
/** The folder in a project that holds the project's own conventions, applied last on install. */
|
|
13
|
+
export const PROJECT_DIR = ".friday";
|
|
14
|
+
let validators;
|
|
15
|
+
function schemas() {
|
|
16
|
+
if (!validators) {
|
|
17
|
+
const ajv = new Ajv({ allErrors: true, strict: false });
|
|
18
|
+
const read = (f) => parse(readFileSync(join(SCHEMAS_DIR, f), "utf8"));
|
|
19
|
+
const patch = read("specialization-patch.schema.yaml");
|
|
20
|
+
ajv.addSchema(patch);
|
|
21
|
+
validators = {
|
|
22
|
+
spec: ajv.compile(read("specialization.schema.yaml")),
|
|
23
|
+
convention: ajv.getSchema(`${patch.$id}#/$defs/convention`),
|
|
24
|
+
persona: ajv.getSchema(`${patch.$id}#/$defs/persona`),
|
|
25
|
+
};
|
|
26
|
+
}
|
|
27
|
+
return validators;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* A specialization reference: a folder with specialization.yaml, or an npm package name that
|
|
31
|
+
* resolves to one (from the project folder first, then from Friday's own install).
|
|
32
|
+
*/
|
|
33
|
+
export function resolveSpecialization(ref, from = process.cwd()) {
|
|
34
|
+
const asDir = resolve(from, ref);
|
|
35
|
+
if (existsSync(join(asDir, SPECIALIZATION_FILE)))
|
|
36
|
+
return asDir;
|
|
37
|
+
if (existsSync(join(resolve(ref), SPECIALIZATION_FILE)))
|
|
38
|
+
return resolve(ref);
|
|
39
|
+
for (const base of [join(resolve(from), "package.json"), join(PACKAGE_ROOT, "package.json")]) {
|
|
40
|
+
try {
|
|
41
|
+
return dirname(createRequire(base).resolve(`${ref}/${SPECIALIZATION_FILE}`));
|
|
42
|
+
}
|
|
43
|
+
catch {
|
|
44
|
+
// not resolvable from here; try the next base
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
throw new Error(`friday: specialization ${ref} not found (no ${SPECIALIZATION_FILE} in that folder or package)`);
|
|
48
|
+
}
|
|
49
|
+
/** The project's own specialization, if the project folder has one. */
|
|
50
|
+
export function projectSpecialization(dir) {
|
|
51
|
+
const d = join(resolve(dir), PROJECT_DIR);
|
|
52
|
+
return existsSync(join(d, SPECIALIZATION_FILE)) ? d : null;
|
|
53
|
+
}
|
|
54
|
+
function readDocs(dir, folder, label, raw) {
|
|
55
|
+
const sub = join(dir, folder);
|
|
56
|
+
if (!existsSync(sub))
|
|
57
|
+
return [];
|
|
58
|
+
const out = [];
|
|
59
|
+
for (const name of readdirSync(sub).sort()) {
|
|
60
|
+
if (!name.endsWith(".yaml") && !name.endsWith(".yml"))
|
|
61
|
+
continue;
|
|
62
|
+
const file = `${label}:${folder}/${name}`;
|
|
63
|
+
try {
|
|
64
|
+
out.push({ file, data: parse(readFileSync(join(sub, name), "utf8")) });
|
|
65
|
+
}
|
|
66
|
+
catch (err) {
|
|
67
|
+
raw.parseErrors.push({ file, message: err.message });
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return out;
|
|
71
|
+
}
|
|
72
|
+
function check(v, data, file, raw) {
|
|
73
|
+
if (v(data))
|
|
74
|
+
return true;
|
|
75
|
+
for (const e of v.errors ?? [])
|
|
76
|
+
raw.parseErrors.push({ file, message: `${e.instancePath || "/"} ${e.message ?? "is invalid"}` });
|
|
77
|
+
return false;
|
|
78
|
+
}
|
|
79
|
+
const uniq = (xs) => [...new Set(xs)];
|
|
80
|
+
function mergeConvention(base, patch) {
|
|
81
|
+
const { remove, rules, ...rest } = patch;
|
|
82
|
+
const out = { ...base, ...rest };
|
|
83
|
+
const drop = new Set(remove ?? []);
|
|
84
|
+
const merged = (base.rules ?? []).filter((r) => !drop.has(r.id));
|
|
85
|
+
for (const r of rules ?? []) {
|
|
86
|
+
const i = merged.findIndex((b) => b.id === r.id);
|
|
87
|
+
if (i >= 0)
|
|
88
|
+
merged[i] = r;
|
|
89
|
+
else
|
|
90
|
+
merged.push(r);
|
|
91
|
+
}
|
|
92
|
+
out.rules = merged;
|
|
93
|
+
return out;
|
|
94
|
+
}
|
|
95
|
+
function mergePersona(base, patch, name) {
|
|
96
|
+
const out = { ...base };
|
|
97
|
+
if (patch.role)
|
|
98
|
+
out.role = patch.role;
|
|
99
|
+
if (patch.description)
|
|
100
|
+
out.description = patch.description;
|
|
101
|
+
if (patch.conventions)
|
|
102
|
+
out.conventions = uniq([...(base.conventions ?? []), ...patch.conventions]);
|
|
103
|
+
if (patch.prompt)
|
|
104
|
+
out.prompt = `${String(base.prompt).trimEnd()}\n\n## ${name}\n\n${String(patch.prompt).trimEnd()}\n`;
|
|
105
|
+
if (patch.taskKindNotes)
|
|
106
|
+
out.taskKindNotes = { ...(base.taskKindNotes ?? {}), ...patch.taskKindNotes };
|
|
107
|
+
return out;
|
|
108
|
+
}
|
|
109
|
+
function mergePack(base, spec, file, raw) {
|
|
110
|
+
const out = { ...base };
|
|
111
|
+
if (spec.description)
|
|
112
|
+
out.description = spec.description;
|
|
113
|
+
if (spec.sources)
|
|
114
|
+
out.sources = uniq([...(base.sources ?? []), ...spec.sources]);
|
|
115
|
+
const tp = spec.testPyramid;
|
|
116
|
+
if (tp) {
|
|
117
|
+
const pyramid = base.testPyramid;
|
|
118
|
+
if (!pyramid) {
|
|
119
|
+
raw.parseErrors.push({ file, message: "testPyramid: the pack has no test pyramid to specialize" });
|
|
120
|
+
}
|
|
121
|
+
else {
|
|
122
|
+
const levels = pyramid.levels.map((l) => ({ ...l }));
|
|
123
|
+
for (const l of tp.levels ?? []) {
|
|
124
|
+
const i = levels.findIndex((b) => b.id === l.id);
|
|
125
|
+
if (i < 0)
|
|
126
|
+
raw.parseErrors.push({ file, message: `testPyramid: no level ${String(l.id)} in the pack` });
|
|
127
|
+
else
|
|
128
|
+
levels[i] = { ...levels[i], ...l };
|
|
129
|
+
}
|
|
130
|
+
out.testPyramid = { ...pyramid, levels, forbiddenInLoop: uniq([...pyramid.forbiddenInLoop, ...(tp.forbiddenInLoop ?? [])]) };
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
const pii = spec.dataAccess?.piiTools;
|
|
134
|
+
if (pii) {
|
|
135
|
+
const da = base.dataAccess ?? {};
|
|
136
|
+
out.dataAccess = { ...da, piiTools: uniq([...(da.piiTools ?? []), ...pii]) };
|
|
137
|
+
}
|
|
138
|
+
return out;
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* The specializations to apply, in order: each one's `extends` (decision 53) comes before it,
|
|
142
|
+
* depth first, and a folder reached twice is applied once, at its first place. A reference that
|
|
143
|
+
* does not resolve, or a cycle, becomes a parse error of the specialization that names it.
|
|
144
|
+
*/
|
|
145
|
+
function expandExtends(dirs, raw) {
|
|
146
|
+
const out = [];
|
|
147
|
+
const done = new Set();
|
|
148
|
+
const visit = (dir, stack) => {
|
|
149
|
+
const key = resolve(dir);
|
|
150
|
+
if (done.has(key))
|
|
151
|
+
return;
|
|
152
|
+
const specFile = join(dir, SPECIALIZATION_FILE);
|
|
153
|
+
if (stack.includes(key)) {
|
|
154
|
+
raw.parseErrors.push({ file: specFile, message: `extends: cycle through ${[...stack, key].join(" -> ")}` });
|
|
155
|
+
return;
|
|
156
|
+
}
|
|
157
|
+
let spec;
|
|
158
|
+
try {
|
|
159
|
+
spec = parse(readFileSync(specFile, "utf8"));
|
|
160
|
+
}
|
|
161
|
+
catch (err) {
|
|
162
|
+
raw.parseErrors.push({ file: specFile, message: err.message });
|
|
163
|
+
return;
|
|
164
|
+
}
|
|
165
|
+
if (!check(schemas().spec, spec, specFile, raw))
|
|
166
|
+
return;
|
|
167
|
+
for (const ref of spec.extends ?? []) {
|
|
168
|
+
let base;
|
|
169
|
+
try {
|
|
170
|
+
base = resolveSpecialization(ref, dir);
|
|
171
|
+
}
|
|
172
|
+
catch (err) {
|
|
173
|
+
raw.parseErrors.push({ file: `${String(spec.id)}:${SPECIALIZATION_FILE}`, message: `extends: ${err.message}` });
|
|
174
|
+
continue;
|
|
175
|
+
}
|
|
176
|
+
visit(base, [...stack, key]);
|
|
177
|
+
}
|
|
178
|
+
if (done.has(key))
|
|
179
|
+
return;
|
|
180
|
+
done.add(key);
|
|
181
|
+
out.push({ dir, spec });
|
|
182
|
+
};
|
|
183
|
+
for (const dir of dirs)
|
|
184
|
+
visit(dir, []);
|
|
185
|
+
return out;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Merge specializations into a raw pack, in order, each after the ones it extends. Problems
|
|
189
|
+
* become parse errors of the specialization's file, so validation reports them with the rest.
|
|
190
|
+
*/
|
|
191
|
+
export function applySpecializations(raw, dirs) {
|
|
192
|
+
const applied = [];
|
|
193
|
+
for (const { dir, spec } of expandExtends(dirs, raw)) {
|
|
194
|
+
const label = spec.id;
|
|
195
|
+
const name = spec.name;
|
|
196
|
+
const file = `${label}:${SPECIALIZATION_FILE}`;
|
|
197
|
+
const packDoc = raw.docs.find((d) => d.kind === "pack");
|
|
198
|
+
if (packDoc)
|
|
199
|
+
packDoc.data = mergePack(packDoc.data, spec, file, raw);
|
|
200
|
+
const byId = (kind, id) => raw.docs.find((d) => d.kind === kind && d.data?.id === id);
|
|
201
|
+
for (const c of readDocs(dir, "conventions", label, raw)) {
|
|
202
|
+
const base = byId("convention", c.data?.id);
|
|
203
|
+
if (!base) {
|
|
204
|
+
raw.docs.push({ kind: "convention", file: c.file, data: c.data });
|
|
205
|
+
continue;
|
|
206
|
+
}
|
|
207
|
+
if (!check(schemas().convention, c.data, c.file, raw))
|
|
208
|
+
continue;
|
|
209
|
+
base.data = mergeConvention(base.data, c.data);
|
|
210
|
+
base.file = `${base.file} + ${c.file}`;
|
|
211
|
+
}
|
|
212
|
+
for (const p of readDocs(dir, "personas", label, raw)) {
|
|
213
|
+
if (!check(schemas().persona, p.data, p.file, raw))
|
|
214
|
+
continue;
|
|
215
|
+
const base = byId("persona", p.data.id);
|
|
216
|
+
if (!base) {
|
|
217
|
+
raw.parseErrors.push({ file: p.file, message: `no persona ${String(p.data.id)} in the pack: a specialization patches personas, it adds none` });
|
|
218
|
+
continue;
|
|
219
|
+
}
|
|
220
|
+
base.data = mergePersona(base.data, p.data, name);
|
|
221
|
+
base.file = `${base.file} + ${p.file}`;
|
|
222
|
+
}
|
|
223
|
+
for (const folder of ["orchestrations", "workflows"]) {
|
|
224
|
+
if (existsSync(join(dir, folder)))
|
|
225
|
+
raw.parseErrors.push({ file: `${label}:${folder}/`, message: "a specialization cannot change orchestrations" });
|
|
226
|
+
}
|
|
227
|
+
if (existsSync(join(dir, "model-policy.yaml")))
|
|
228
|
+
raw.parseErrors.push({ file: `${label}:model-policy.yaml`, message: "a specialization cannot change the model policy" });
|
|
229
|
+
// A specialization shipped as a package carries the package's version.
|
|
230
|
+
let version = spec.version;
|
|
231
|
+
if (!version && existsSync(join(dir, "package.json"))) {
|
|
232
|
+
version = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
|
|
233
|
+
}
|
|
234
|
+
applied.push({ id: label, name, ...(version ? { version } : {}) });
|
|
235
|
+
}
|
|
236
|
+
return applied;
|
|
237
|
+
}
|