@digital-agora/friday 0.0.0-stage → 0.9.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 +275 -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 +294 -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 +228 -0
- package/dist/specialize.js +201 -0
- package/dist/step-schemas.js +440 -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 +204 -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 +51 -0
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# Downstream. Builds an approved handoff: contract outcomes (architect), frozen interfaces (lead),
|
|
2
|
+
# a build plan (senior developer), then bottom-of-pyramid TDD pairs per task, then the
|
|
3
|
+
# integration loop (full pyramid, follow-ups for every gap), security gate, PR.
|
|
4
|
+
# Never asks the user: anything missing returns needs-upstream.
|
|
5
|
+
id: feature-delivery
|
|
6
|
+
description: Deliver an approved handoff with QA-paired TDD per task (static and unit tests only), an integration loop that runs the full pyramid and follows up every gap, pass the security and acceptance gates, then commit and open the PR.
|
|
7
|
+
stream: downstream
|
|
8
|
+
orchestrator: lead-developer
|
|
9
|
+
requires: [handoff]
|
|
10
|
+
# Every finished run ends in a retro: docs/friday/<workId>/retro.md and proposed Friday improvements.
|
|
11
|
+
retro: { persona: lead-developer, taskKind: decide }
|
|
12
|
+
steps:
|
|
13
|
+
# Install the workspace once and resolve every prerequisite and version pin where the agents
|
|
14
|
+
# run; anything that cannot be resolved goes back upstream before anything is built (decision 48).
|
|
15
|
+
- id: preflight
|
|
16
|
+
type: preflight
|
|
17
|
+
persona: qa-engineer
|
|
18
|
+
taskKind: verify
|
|
19
|
+
# Roles before code: the architect fixes the contract outcomes and the communication standards,
|
|
20
|
+
# the lead developer codes and freezes the interfaces, a senior developer plans the build, and
|
|
21
|
+
# only then do QA and a developer pair on each task. Parallel tasks then share one frozen set of
|
|
22
|
+
# contracts instead of inventing their own, and every red test has a known owner.
|
|
23
|
+
- id: contracts
|
|
24
|
+
type: agent
|
|
25
|
+
persona: architect
|
|
26
|
+
taskKind: decide
|
|
27
|
+
prompt: >-
|
|
28
|
+
Before any code, fix the contract outcomes and communication standards for this handoff. For
|
|
29
|
+
every interaction the tasks need (callable, event, trigger, cron, async action, read model,
|
|
30
|
+
rule), state: its type and why (for example a read callable, a write callable, a
|
|
31
|
+
fire-and-forget async action, an outbox event); its input and output shapes in words; its
|
|
32
|
+
error outcomes (general to the caller, details to the log); its audit and logging standard;
|
|
33
|
+
its owner context and its consumers; and the trade-offs accepted for it, each with what it
|
|
34
|
+
gives up. Reuse the repository's existing standards and the handoff's decisions; where an
|
|
35
|
+
interface already exists, name it and keep its shape. Put them in result.contracts (one
|
|
36
|
+
entry per interface, with the task ids that use it) and result.standards (the cross-cutting
|
|
37
|
+
rules: naming, error, audit, logging and versioning). Write no code. Anything the handoff does
|
|
38
|
+
not settle is a blocker: return blocked with the question.
|
|
39
|
+
- id: interfaces
|
|
40
|
+
type: agent
|
|
41
|
+
persona: lead-developer
|
|
42
|
+
taskKind: integrate
|
|
43
|
+
prompt: >-
|
|
44
|
+
Code the interfaces the contracts step defined, and only those: contracts, schemas, event
|
|
45
|
+
types, port interfaces and shared types, in the repository's contract and core packages, with
|
|
46
|
+
no behaviour. They must compile, and every contract gets a contract or schema test. Run the
|
|
47
|
+
static checks and the unit tests of the packages you touched. They must be green: an
|
|
48
|
+
interface that would make another test red is a blocker. Commit them as one commit. From now
|
|
49
|
+
on they are frozen. List every file and exported name in result.interfaces, with the task ids
|
|
50
|
+
that consume each. A task that needs a frozen interface changed returns blocked; it does not
|
|
51
|
+
change it.
|
|
52
|
+
- id: orchestration
|
|
53
|
+
type: agent
|
|
54
|
+
persona: backend-engineer
|
|
55
|
+
taskKind: integrate
|
|
56
|
+
prompt: >-
|
|
57
|
+
As the senior developer, plan the build on top of the frozen interfaces. For every task,
|
|
58
|
+
give: the files it may create or change; the test files it owns, each on a path that contains
|
|
59
|
+
its task id, so two tasks never write the same file; which tasks share a file, and how they
|
|
60
|
+
are ordered so only one touches it at a time; and the red tests each wave will leave on
|
|
61
|
+
purpose, each with its owner task. Keep the handoff's dependsOn and add only ordering that
|
|
62
|
+
shared files force. Put it in result.plan (per task: files, testFiles, after) and
|
|
63
|
+
result.expectedRed (test, owner task). Write no code. A conflict between the plan and the
|
|
64
|
+
handoff is a blocker.
|
|
65
|
+
- id: build
|
|
66
|
+
type: foreach
|
|
67
|
+
over: handoff.tasks
|
|
68
|
+
order: dependsOn
|
|
69
|
+
steps:
|
|
70
|
+
# QA and a developer pair on each task, following the orchestration plan: tests on the
|
|
71
|
+
# task's own paths, code only in the task's files, against the frozen interfaces.
|
|
72
|
+
- id: tdd
|
|
73
|
+
type: tdd-pair
|
|
74
|
+
test: { persona: qa-engineer, taskKind: test-design }
|
|
75
|
+
impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
|
|
76
|
+
verify: { persona: qa-engineer, taskKind: verify }
|
|
77
|
+
# The task loop stays at the bottom of the pyramid; integration runs the rest.
|
|
78
|
+
testScope: [static, unit]
|
|
79
|
+
maxRounds: 3
|
|
80
|
+
# Wire every stack, run the whole pyramid once, and turn each failure into a follow-up task
|
|
81
|
+
# that goes back through the bottom-of-pyramid loop. Repeats until green or maxRounds.
|
|
82
|
+
- id: integrate
|
|
83
|
+
type: integration-loop
|
|
84
|
+
integrate: { persona: "{{stack}}", taskKind: integrate }
|
|
85
|
+
testScope: [static, unit, integration, e2e]
|
|
86
|
+
maxRounds: 3
|
|
87
|
+
followup:
|
|
88
|
+
- id: followup-tdd
|
|
89
|
+
type: tdd-pair
|
|
90
|
+
test: { persona: qa-engineer, taskKind: test-design }
|
|
91
|
+
impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
|
|
92
|
+
verify: { persona: qa-engineer, taskKind: verify }
|
|
93
|
+
# The task loop stays at the bottom of the pyramid; integration runs the rest.
|
|
94
|
+
testScope: [static, unit]
|
|
95
|
+
maxRounds: 3
|
|
96
|
+
# Data safety is shared: the PII analyst checks personal information, then the security
|
|
97
|
+
# steward checks the controls. Only when the handoff holds pii.
|
|
98
|
+
- id: privacy-review
|
|
99
|
+
type: gate
|
|
100
|
+
when: pii
|
|
101
|
+
persona: data-analyst-pii
|
|
102
|
+
taskKind: analysis
|
|
103
|
+
prompt: Check the full diff for gaps on personal information against the handoff's data classification - fields beyond the purpose, missing retention, personal data in logs, exports, prompts, seeds or fixtures, reads of another project's data. pass only if none remain.
|
|
104
|
+
maxLoops: 2
|
|
105
|
+
onFail: { persona: backend-engineer, taskKind: integrate }
|
|
106
|
+
- id: security-review
|
|
107
|
+
type: gate
|
|
108
|
+
persona: security-steward
|
|
109
|
+
taskKind: review
|
|
110
|
+
prompt: Review the full diff against the security, data-classification, rules and config conventions and the handoff's decisions.
|
|
111
|
+
maxLoops: 2
|
|
112
|
+
onFail: { persona: backend-engineer, taskKind: integrate }
|
|
113
|
+
- id: acceptance
|
|
114
|
+
type: gate
|
|
115
|
+
persona: lead-developer
|
|
116
|
+
taskKind: integrate
|
|
117
|
+
prompt: >-
|
|
118
|
+
Check every acceptance criterion in the handoff scope and tasks against the result. Then
|
|
119
|
+
compare the diff with the orchestration plan: every changed file outside a task's planned
|
|
120
|
+
files is plan drift, a finding with the task and the reason the plan missed it. pass only if
|
|
121
|
+
all criteria are met and verified and no drift is left unexplained.
|
|
122
|
+
maxLoops: 1
|
|
123
|
+
onFail: { persona: backend-engineer, taskKind: integrate }
|
|
124
|
+
- id: pr
|
|
125
|
+
type: agent
|
|
126
|
+
persona: git-steward
|
|
127
|
+
taskKind: git
|
|
128
|
+
output: git
|
|
129
|
+
prompt: Commit the work per task following the `git` convention, add the changeset, push the branch and open the PR with the template sections, linking the handoff.
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Downstream. Delivers an approved prompt-discovery handoff: the build of feature-delivery (contracts,
|
|
2
|
+
# frozen interfaces, a build plan, QA-paired TDD per task, the integration loop), then the top of
|
|
3
|
+
# the prompt pyramid, the eval run (decision 34): QA runs the approved evals and the security
|
|
4
|
+
# steward reviews the results, neither of them the prompt's author. A failing criterion never gets
|
|
5
|
+
# fixed here: the run returns needs-upstream naming the lowest level that explains it, and
|
|
6
|
+
# prompt-discovery reopens that level and every level above it. A person approves the eval run by
|
|
7
|
+
# approving the PR, whose body holds the eval report: downstream never asks the user.
|
|
8
|
+
id: prompt-delivery
|
|
9
|
+
description: Deliver an approved prompt-discovery handoff with QA-paired TDD per task and the integration loop, run and review the approved evals, return every failing criterion upstream to the level that explains it, then open the PR the product owner approves.
|
|
10
|
+
stream: downstream
|
|
11
|
+
orchestrator: lead-developer
|
|
12
|
+
requires: [handoff]
|
|
13
|
+
retro: { persona: lead-developer, taskKind: decide }
|
|
14
|
+
steps:
|
|
15
|
+
# Install the workspace once and resolve every prerequisite and version pin where the agents
|
|
16
|
+
# run; anything that cannot be resolved goes back upstream before anything is built (decision 48).
|
|
17
|
+
- id: preflight
|
|
18
|
+
type: preflight
|
|
19
|
+
persona: qa-engineer
|
|
20
|
+
taskKind: verify
|
|
21
|
+
- id: contracts
|
|
22
|
+
type: agent
|
|
23
|
+
persona: architect
|
|
24
|
+
taskKind: decide
|
|
25
|
+
prompt: >-
|
|
26
|
+
Before any code, fix the contract outcomes and communication standards for this handoff: the
|
|
27
|
+
code that calls the model, the eval runner and every other interaction the tasks need. For
|
|
28
|
+
each: its type and why, its input and output shapes in words, its error outcomes (general
|
|
29
|
+
to the caller, details to the log; never the prompt, a model input or output in a log line),
|
|
30
|
+
its owner context and consumers, and the trade-offs it accepts. The approved prompt pyramid
|
|
31
|
+
levels (handoff promptPyramid.levels and their files) are fixed: the prompt, examples and
|
|
32
|
+
eval cases are used exactly as approved. Put them in result.contracts and result.standards.
|
|
33
|
+
Write no code. Anything the handoff does not settle is a blocker: return blocked with the
|
|
34
|
+
question.
|
|
35
|
+
- id: interfaces
|
|
36
|
+
type: agent
|
|
37
|
+
persona: lead-developer
|
|
38
|
+
taskKind: integrate
|
|
39
|
+
prompt: >-
|
|
40
|
+
Code the interfaces the contracts step defined, and only those, with no behaviour. They must
|
|
41
|
+
compile, and every contract gets a contract or schema test. Run the static checks and the unit
|
|
42
|
+
tests of the packages you touched; they must be green. Commit them as one commit; from now on
|
|
43
|
+
they are frozen. List every file and exported name in result.interfaces, with the task ids
|
|
44
|
+
that consume each.
|
|
45
|
+
- id: orchestration
|
|
46
|
+
type: agent
|
|
47
|
+
persona: backend-engineer
|
|
48
|
+
taskKind: integrate
|
|
49
|
+
prompt: >-
|
|
50
|
+
As the senior developer, plan the build on top of the frozen interfaces. For every task, give
|
|
51
|
+
the files it may create or change and the test files it owns (each on a path that contains its
|
|
52
|
+
task id), the ordering that keeps one writer per shared file, and the red tests each wave
|
|
53
|
+
leaves on purpose with their owner task. The files that hold the approved prompt, examples and
|
|
54
|
+
eval cases (<name>.prompt.<ext>, <name>.examples.<ext>, <name>.evals.<ext>) are write-once:
|
|
55
|
+
plan for one task to create each by copying its approved level file exactly; no task changes
|
|
56
|
+
one that exists. Put it in
|
|
57
|
+
result.plan and result.expectedRed. Write no code. A conflict with the handoff is a blocker.
|
|
58
|
+
- id: build
|
|
59
|
+
type: foreach
|
|
60
|
+
over: handoff.tasks
|
|
61
|
+
order: dependsOn
|
|
62
|
+
steps:
|
|
63
|
+
- id: tdd
|
|
64
|
+
type: tdd-pair
|
|
65
|
+
test: { persona: qa-engineer, taskKind: test-design }
|
|
66
|
+
impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
|
|
67
|
+
verify: { persona: qa-engineer, taskKind: verify }
|
|
68
|
+
testScope: [static, unit]
|
|
69
|
+
maxRounds: 3
|
|
70
|
+
- id: integrate
|
|
71
|
+
type: integration-loop
|
|
72
|
+
integrate: { persona: "{{stack}}", taskKind: integrate }
|
|
73
|
+
testScope: [static, unit, integration, e2e]
|
|
74
|
+
maxRounds: 3
|
|
75
|
+
followup:
|
|
76
|
+
- id: followup-tdd
|
|
77
|
+
type: tdd-pair
|
|
78
|
+
test: { persona: qa-engineer, taskKind: test-design }
|
|
79
|
+
impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
|
|
80
|
+
verify: { persona: qa-engineer, taskKind: verify }
|
|
81
|
+
testScope: [static, unit]
|
|
82
|
+
maxRounds: 3
|
|
83
|
+
# The top of the prompt pyramid. Neither agent wrote the prompt (decision 25).
|
|
84
|
+
- id: eval-run
|
|
85
|
+
type: agent
|
|
86
|
+
level: eval-run
|
|
87
|
+
persona: qa-engineer
|
|
88
|
+
taskKind: verify
|
|
89
|
+
prompt: >-
|
|
90
|
+
Run the approved evals with the `evals` commands of the command map (args.commands or
|
|
91
|
+
handoff.commands); no such entry is a blocker. Report, per success criterion of
|
|
92
|
+
docs/friday/<workId>/prompt/success-criteria.md, the pass rate against its threshold, and
|
|
93
|
+
every failing case with its id, input id and what the output did wrong; never copy a model
|
|
94
|
+
input or output that could hold personal data, cite the case id instead. Put it in
|
|
95
|
+
result.evalReport. Every criterion at or above its threshold -> done. Any criterion below it
|
|
96
|
+
-> status blocked: blocked.reason starts with "Level <id>:", the lowest prompt pyramid level
|
|
97
|
+
that explains the failures (success-criteria when the threshold cannot be met, evals when a
|
|
98
|
+
case or its check is wrong, context when an input is missing, instructions, examples or
|
|
99
|
+
structure otherwise), and blocked.questions has one question per failure with 2-4 options.
|
|
100
|
+
Never change the prompt, the examples or the eval cases: they were approved upstream, and
|
|
101
|
+
changing one reopens its level in prompt-discovery.
|
|
102
|
+
- id: eval-review
|
|
103
|
+
type: agent
|
|
104
|
+
level: eval-run
|
|
105
|
+
persona: security-steward
|
|
106
|
+
taskKind: review
|
|
107
|
+
prompt: >-
|
|
108
|
+
Review the eval run (result.evalReport of eval-run) and the code that calls the model against
|
|
109
|
+
the handoff's data classification and the security conventions: personal data in prompts,
|
|
110
|
+
examples, eval cases, logs or reports; model inputs or outputs in log lines; the model key
|
|
111
|
+
read from the secret store, never from a prompt, a flag or argv; refusals the success
|
|
112
|
+
criteria require. Put the findings in result.findings, each with severity, file or case id,
|
|
113
|
+
issue and the level it belongs to. No high finding -> done. A high finding in the code ->
|
|
114
|
+
status blocked naming the task; a high finding in an approved level -> status blocked with
|
|
115
|
+
blocked.reason starting "Level <id>:". Never fix anything yourself.
|
|
116
|
+
- id: privacy-review
|
|
117
|
+
type: gate
|
|
118
|
+
when: pii
|
|
119
|
+
persona: data-analyst-pii
|
|
120
|
+
taskKind: analysis
|
|
121
|
+
prompt: Check the full diff for gaps on personal information against the handoff's data classification - fields beyond the purpose, missing retention, personal data in logs, exports, prompts, examples, eval cases, seeds or fixtures, reads of another project's data. pass only if none remain.
|
|
122
|
+
maxLoops: 2
|
|
123
|
+
onFail: { persona: backend-engineer, taskKind: integrate }
|
|
124
|
+
- id: security-review
|
|
125
|
+
type: gate
|
|
126
|
+
persona: security-steward
|
|
127
|
+
taskKind: review
|
|
128
|
+
prompt: Review the full diff against the security, data-classification, rules and config conventions and the handoff's decisions. The approved prompt, examples and eval cases are not findings to fix here; a problem in one is a high finding naming its level.
|
|
129
|
+
maxLoops: 2
|
|
130
|
+
onFail: { persona: backend-engineer, taskKind: integrate }
|
|
131
|
+
- id: acceptance
|
|
132
|
+
type: gate
|
|
133
|
+
persona: lead-developer
|
|
134
|
+
taskKind: integrate
|
|
135
|
+
prompt: >-
|
|
136
|
+
Check every acceptance criterion in the handoff scope and tasks against the result, the eval
|
|
137
|
+
pass rate per success criterion among them. Check that the prompt, examples and eval cases in
|
|
138
|
+
the repository are exactly the approved level files of the handoff. Then compare the diff with
|
|
139
|
+
the orchestration plan: every changed file outside a task's planned files is plan drift, a
|
|
140
|
+
finding with the task and the reason. pass only if all criteria are met and verified, the
|
|
141
|
+
approved files are unchanged and no drift is left unexplained.
|
|
142
|
+
maxLoops: 1
|
|
143
|
+
onFail: { persona: backend-engineer, taskKind: integrate }
|
|
144
|
+
- id: pr
|
|
145
|
+
type: agent
|
|
146
|
+
persona: git-steward
|
|
147
|
+
taskKind: git
|
|
148
|
+
output: git
|
|
149
|
+
prompt: >-
|
|
150
|
+
Commit the work per task following the `git` convention, add the changeset, push the branch
|
|
151
|
+
and open the PR with the template sections, linking the handoff. The PR body holds the eval
|
|
152
|
+
report (pass rate per success criterion against its threshold, the failing case ids, never a
|
|
153
|
+
model input or output) and the approved prompt pyramid levels, each with the role that
|
|
154
|
+
approved it and its file. End it with: "Eval run: a person in the product-owner role approves
|
|
155
|
+
this level by approving this PR." Never put a person's name in the PR text.
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
# Upstream. Builds the prompt of a product's LLM feature level by level, following the prompt
|
|
2
|
+
# pyramid in pack.yaml (promptPyramid), and ends in an approved handoff (decision 33).
|
|
3
|
+
# A person sits between every level: each `approval` step always stops the run, and a person in
|
|
4
|
+
# the level's approver role approves the level or asks for a change. A change to a level reopens
|
|
5
|
+
# every level above it: they are built again and approved again. The eval run (the apex) is
|
|
6
|
+
# downstream; this orchestration covers the levels below it.
|
|
7
|
+
id: prompt-discovery
|
|
8
|
+
description: Build the prompt of a product's LLM feature bottom up (success criteria, evals, context, instructions, examples, structure), each level approved by a person in its role, break the work into tasks and write the handoff.
|
|
9
|
+
stream: upstream
|
|
10
|
+
orchestrator: lead-developer
|
|
11
|
+
# A skill, not a workflow script: only the session can stop between steps and wait for a person.
|
|
12
|
+
outputs: [skill]
|
|
13
|
+
sizing:
|
|
14
|
+
signals:
|
|
15
|
+
- a success criterion the request states or implies
|
|
16
|
+
- an input the prompt receives (a field, a document, a tool result, earlier messages)
|
|
17
|
+
- an entity or field that holds or identifies a person
|
|
18
|
+
- a codebase, function or service that calls the model
|
|
19
|
+
medium: 4
|
|
20
|
+
large: 10
|
|
21
|
+
maxAgentsPerWorkflow: 6
|
|
22
|
+
maxRounds: 5
|
|
23
|
+
deferNonBlocking: true
|
|
24
|
+
maxItemsPerRound: 15
|
|
25
|
+
inputs:
|
|
26
|
+
workId: { description: "Short id for the work, e.g. faq-answer-prompt", required: true }
|
|
27
|
+
request: { description: The request as the user stated it, required: true }
|
|
28
|
+
glossary: { description: "Optional. Domain words and what they mean here (term -> meaning), shown to every step." }
|
|
29
|
+
environmentFacts: { description: "Optional. Facts the orchestrator verified (model access, tools), shown to every step." }
|
|
30
|
+
answersFile: { description: "Optional. Path to answers.yaml; agents read the answers there and only answeredIds/resolvedIds travel inline." }
|
|
31
|
+
retro: { persona: lead-developer, taskKind: decide }
|
|
32
|
+
steps:
|
|
33
|
+
# The request brief (decision 39): the prompt engineer structures the request, citing every
|
|
34
|
+
# field's source, and the requester approves it before any perspective asks a question.
|
|
35
|
+
- id: brief
|
|
36
|
+
type: agent
|
|
37
|
+
checkpoint: brief
|
|
38
|
+
persona: prompt-engineer
|
|
39
|
+
taskKind: brief
|
|
40
|
+
prompt: >-
|
|
41
|
+
Turn the request into the request brief, the structured prompt every later step starts from.
|
|
42
|
+
Fields: goal (the outcome the user wants, in their words), who it is for and where it shows
|
|
43
|
+
up, today (the current behaviour, from the repository with the files, or unknown), wanted
|
|
44
|
+
(the behaviour after the change), constraints (the conventions and earlier decisions that
|
|
45
|
+
apply, by id), acceptance (only what the request states), out of scope (only what the request
|
|
46
|
+
or an answer excludes), facts checked (what you verified in the repository, with the file, so
|
|
47
|
+
no later step asks about it) and unknowns. Every field names its source: request,
|
|
48
|
+
repository (file), answer (id), convention (id) or proposed. Never invent one; what you would
|
|
49
|
+
have to guess is a proposal or a question. Put it in result.brief.
|
|
50
|
+
- id: approve-brief
|
|
51
|
+
type: approval
|
|
52
|
+
checkpoint: brief
|
|
53
|
+
- id: success-criteria
|
|
54
|
+
type: clarify
|
|
55
|
+
level: success-criteria
|
|
56
|
+
persona: lead-developer
|
|
57
|
+
taskKind: decide
|
|
58
|
+
topic: >-
|
|
59
|
+
Start from the approved request brief (step brief). Success criteria for the feature's prompt: what a good answer is, for whom, and how it is
|
|
60
|
+
measured (quality, latency, cost, refusals, tone, format). Take a criterion from the request
|
|
61
|
+
only where the request states it; otherwise propose a measurable threshold with 2-4 options
|
|
62
|
+
and your recommendation. Never decide what "good" means yourself: the person accepts or
|
|
63
|
+
changes every proposal at this level's approval. Put the criteria in
|
|
64
|
+
result.successCriteria, each with an id, what it measures, the threshold and where it comes
|
|
65
|
+
from (request, or the answer id).
|
|
66
|
+
- id: approve-success-criteria
|
|
67
|
+
type: approval
|
|
68
|
+
level: success-criteria
|
|
69
|
+
- id: evals
|
|
70
|
+
type: agent
|
|
71
|
+
level: evals
|
|
72
|
+
persona: qa-engineer
|
|
73
|
+
taskKind: test-plan
|
|
74
|
+
prompt: >-
|
|
75
|
+
From the approved success criteria only, write the evals: fixed cases with pass checks,
|
|
76
|
+
before any prompt exists and independent of it. Cover every criterion, typical inputs, hard
|
|
77
|
+
cases and inputs the feature must refuse. Each case has an id, the criterion ids it tests,
|
|
78
|
+
the input, the pass check (exact, rubric or a check another agent can apply) and why it
|
|
79
|
+
matters. Inputs are synthetic or pseudonymised, never real personal data. Put them in
|
|
80
|
+
result.evals. Do not write or run code. Ask only about a blocker.
|
|
81
|
+
- id: approve-evals
|
|
82
|
+
type: approval
|
|
83
|
+
level: evals
|
|
84
|
+
- id: context
|
|
85
|
+
type: parallel
|
|
86
|
+
level: context
|
|
87
|
+
steps:
|
|
88
|
+
- id: context-security
|
|
89
|
+
type: clarify
|
|
90
|
+
persona: security-steward
|
|
91
|
+
taskKind: decide
|
|
92
|
+
topic: >-
|
|
93
|
+
What the prompt receives and from where: every input, loaded up front or fetched just in
|
|
94
|
+
time with a tool, its data class (pii / non-pii, owner, retention) and who may send it to
|
|
95
|
+
the model. Nothing personal goes into a prompt, an example or a log unless a
|
|
96
|
+
personal-data-safe use case allows it. Put the inputs in result.context and the
|
|
97
|
+
classification in result.dataClassification.
|
|
98
|
+
- id: context-privacy
|
|
99
|
+
type: clarify
|
|
100
|
+
persona: data-analyst-pii
|
|
101
|
+
taskKind: analysis
|
|
102
|
+
topic: >-
|
|
103
|
+
Personal information in the prompt's inputs, examples, eval cases and logs: every field
|
|
104
|
+
that holds or identifies a person, its purpose, minimisation (aggregates or pseudonymised
|
|
105
|
+
identifiers instead) and whether model output could carry it. Report every gap; agree
|
|
106
|
+
the classification with the security step (put yours in result.dataClassification).
|
|
107
|
+
- id: approve-context
|
|
108
|
+
type: approval
|
|
109
|
+
level: context
|
|
110
|
+
- id: model
|
|
111
|
+
type: agent
|
|
112
|
+
level: instructions
|
|
113
|
+
persona: architect
|
|
114
|
+
taskKind: decide
|
|
115
|
+
prompt: >-
|
|
116
|
+
Choose the model for the feature from the approved success criteria (quality, latency,
|
|
117
|
+
cost) and the context, and say what it trades away; start with the most capable model the
|
|
118
|
+
criteria allow. A choice the criteria do not settle is a question with options. Put it in
|
|
119
|
+
result.model with the why and the decision to record.
|
|
120
|
+
- id: system-prompt
|
|
121
|
+
type: agent
|
|
122
|
+
level: instructions
|
|
123
|
+
persona: prompt-engineer
|
|
124
|
+
taskKind: prompt-design
|
|
125
|
+
prompt: >-
|
|
126
|
+
Write the system prompt from the approved levels below (success criteria, evals, context)
|
|
127
|
+
and the chosen model: the role, the task, the inputs in tagged sections, the output format
|
|
128
|
+
and what to do when an input is missing or must be refused. Keep it at the right altitude:
|
|
129
|
+
no brittle if-else rules, no vague advice. Start minimal; add an instruction only for a
|
|
130
|
+
criterion or eval case that needs it, and name which. Put it in result.systemPrompt with
|
|
131
|
+
result.coverage (eval case id -> the instruction that serves it).
|
|
132
|
+
- id: approve-instructions
|
|
133
|
+
type: approval
|
|
134
|
+
level: instructions
|
|
135
|
+
- id: examples
|
|
136
|
+
type: agent
|
|
137
|
+
level: examples
|
|
138
|
+
persona: prompt-engineer
|
|
139
|
+
taskKind: prompt-design
|
|
140
|
+
prompt: >-
|
|
141
|
+
Pick a few diverse, canonical examples for the approved system prompt, not a list of edge
|
|
142
|
+
cases. Each example is synthetic or pseudonymised, is not an eval case (never copy an eval
|
|
143
|
+
input) and says which instruction it illustrates. Put them in result.examples.
|
|
144
|
+
- id: approve-examples
|
|
145
|
+
type: approval
|
|
146
|
+
level: examples
|
|
147
|
+
- id: structure
|
|
148
|
+
type: agent
|
|
149
|
+
level: structure
|
|
150
|
+
persona: architect
|
|
151
|
+
taskKind: decide
|
|
152
|
+
prompt: >-
|
|
153
|
+
Decide the structure: one prompt, unless the approved criteria, context or evals show it
|
|
154
|
+
cannot meet them; then the simplest pattern that can (prompt chaining with gates, routing,
|
|
155
|
+
orchestrator-workers), with the reason and the cost it adds. Put it in result.structure
|
|
156
|
+
with the decision to record.
|
|
157
|
+
- id: approve-structure
|
|
158
|
+
type: approval
|
|
159
|
+
level: structure
|
|
160
|
+
- id: breakdown
|
|
161
|
+
type: agent
|
|
162
|
+
persona: lead-developer
|
|
163
|
+
taskKind: decide
|
|
164
|
+
output: tasks
|
|
165
|
+
prompt: >-
|
|
166
|
+
Break the approved prompt into tasks: where the prompt, examples and eval cases live in the
|
|
167
|
+
repository, in files named <name>.prompt.<ext>, <name>.examples.<ext> and <name>.evals.<ext>
|
|
168
|
+
(write-once downstream: a task creates each once from its approved level file), the code that calls the model and the eval runner (locally and in the PR build,
|
|
169
|
+
against the non-production environment, reading the model key from the project's secret
|
|
170
|
+
store); name the command that runs the evals, for the handoff's commands.evals. Each task: id, title, stack, codebase path, taskKind (scaffold, adapter or
|
|
171
|
+
implement), acceptance criteria (the eval pass rate per success criterion among them),
|
|
172
|
+
dependsOn, conventions. Never change an approved level; a level that cannot be built as
|
|
173
|
+
approved is a gap.
|
|
174
|
+
# Task briefs (decision 40): the prompt each task's agents receive, written from what this run
|
|
175
|
+
# settled and approved with the handoff.
|
|
176
|
+
- id: task-briefs
|
|
177
|
+
type: agent
|
|
178
|
+
persona: prompt-engineer
|
|
179
|
+
taskKind: brief
|
|
180
|
+
output: briefs
|
|
181
|
+
prompt: >-
|
|
182
|
+
For every task in the breakdown, write its task brief: the prompt its agents receive, the
|
|
183
|
+
smallest set they need. In Markdown sections: the task and its acceptance criteria and scope;
|
|
184
|
+
the contracts and interfaces it consumes, by id; the files it may change and the test files it
|
|
185
|
+
owns, from the build plan; the decisions, conventions and data class that apply to its
|
|
186
|
+
codebase; what it must not touch (frozen interfaces, approved prompt files, other tasks'
|
|
187
|
+
files); the commands of its test scope. List the ids and paths you name in the brief's
|
|
188
|
+
contracts, interfaces, decisions, files and testFiles. Add nothing the breakdown, the plan or
|
|
189
|
+
the decisions do not hold; a task you cannot brief from them is a gap. Put them in
|
|
190
|
+
result.briefs, one per task.
|
|
191
|
+
- id: gaps
|
|
192
|
+
title: gaps and contradictions
|
|
193
|
+
type: gap-analysis
|
|
194
|
+
persona: lead-developer
|
|
195
|
+
taskKind: decide
|
|
196
|
+
rerunUntil: no-open-gaps
|
|
197
|
+
consolidate: true
|
|
198
|
+
- id: handoff
|
|
199
|
+
type: handoff
|
|
200
|
+
persona: lead-developer
|
|
201
|
+
taskKind: decide
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Downstream, from pending changesets (not a handoff). Prepares a release: checks staging is
|
|
2
|
+
# green, versions with changesets and opens the release PR. Tagging vX.Y.Z after the merge
|
|
3
|
+
# deploys production.
|
|
4
|
+
id: release
|
|
5
|
+
description: Prepare a release from pending changesets - confirm staging is green, run changeset version, and open the release PR with the changelog.
|
|
6
|
+
stream: downstream
|
|
7
|
+
orchestrator: devops-engineer
|
|
8
|
+
requires: [changesets]
|
|
9
|
+
# Every finished run ends in a retro: docs/friday/<workId>/retro.md and proposed Friday improvements.
|
|
10
|
+
retro: { persona: lead-developer, taskKind: decide }
|
|
11
|
+
steps:
|
|
12
|
+
- id: checks
|
|
13
|
+
type: agent
|
|
14
|
+
persona: qa-engineer
|
|
15
|
+
taskKind: verify
|
|
16
|
+
prompt: >-
|
|
17
|
+
Confirm the commit at the tip of main passed the stg deploy, smoke steps and DAST on
|
|
18
|
+
staging, and that `pnpm changeset status` lists pending changesets. Report the evidence.
|
|
19
|
+
If staging is not green or there are no pending changesets, return status blocked with the
|
|
20
|
+
reason.
|
|
21
|
+
- id: version
|
|
22
|
+
type: agent
|
|
23
|
+
persona: devops-engineer
|
|
24
|
+
taskKind: implement
|
|
25
|
+
prompt: >-
|
|
26
|
+
On a release/<version> branch, run `pnpm changeset version` to consume the changesets,
|
|
27
|
+
bump the versions and write the changelogs. Check every changelog entry reads as a
|
|
28
|
+
user-facing change and that each breaking change (major) carries its migration steps for
|
|
29
|
+
stg and prod; if one does not, return status blocked naming the changeset. Run the static
|
|
30
|
+
checks and report the new versions.
|
|
31
|
+
- id: release-pr
|
|
32
|
+
type: agent
|
|
33
|
+
persona: git-steward
|
|
34
|
+
taskKind: git
|
|
35
|
+
output: git
|
|
36
|
+
prompt: >-
|
|
37
|
+
Commit as "chore(release): v<version>" following the `git` convention, push the release
|
|
38
|
+
branch and open the release PR with the changelog in What and why, the checks in How it
|
|
39
|
+
was tested and the migrations in Environments and compatibility. Do not tag: a maintainer
|
|
40
|
+
tags v<version> on the merge commit.
|
package/pack/pack.yaml
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Friday: the one pack of SDLC agents, workflows and conventions. Every convention is documented
|
|
2
|
+
# (document, don't invent) and names its source: for a generic rule an external https:// URL
|
|
3
|
+
# (decision 30), or a Friday decision. Friday's pack holds generic rules only; a project's rules
|
|
4
|
+
# come in a specialization (decision 41), which lists the repositories they cite in its sources.
|
|
5
|
+
id: friday
|
|
6
|
+
name: Friday
|
|
7
|
+
version: 0.1.0
|
|
8
|
+
description: SDLC agents, workflows and conventions (hexagonal core, TDD pairs, a test pyramid, people approving every handoff).
|
|
9
|
+
sources: []
|
|
10
|
+
# A task's `stack` (set by the lead developer upstream) picks the engineer that implements it.
|
|
11
|
+
stacks:
|
|
12
|
+
frontend: frontend-engineer
|
|
13
|
+
backend: backend-engineer
|
|
14
|
+
devops: devops-engineer
|
|
15
|
+
# The data class of the handoff picks the analyst ("{{analyst}}" in a step).
|
|
16
|
+
analysts:
|
|
17
|
+
pii: data-analyst-pii
|
|
18
|
+
non-pii: data-analyst-non-pii
|
|
19
|
+
targets: [claude, opencode]
|
|
20
|
+
dataAccess:
|
|
21
|
+
# Tools that can return personal data. Denied to data-analyst-non-pii.
|
|
22
|
+
# Left empty on purpose: a specialization lists the real tool names (decision 41).
|
|
23
|
+
piiTools: []
|
|
24
|
+
# The test pyramid, bottom first. Task loops (TDD pairs, gate fixes) run only loopLevels, scoped
|
|
25
|
+
# to what the task touches. Emulator and e2e suites run once, in the integration loop at the end,
|
|
26
|
+
# which turns every failure into a follow-up task for the task loop.
|
|
27
|
+
testPyramid:
|
|
28
|
+
levels:
|
|
29
|
+
- id: static
|
|
30
|
+
description: Typecheck, lint and the architecture check of the touched package
|
|
31
|
+
commands: ["pnpm --filter <package> typecheck", "pnpm --filter <package> lint"]
|
|
32
|
+
source: https://martinfowler.com/articles/practical-test-pyramid.html
|
|
33
|
+
- id: unit
|
|
34
|
+
description: Unit tests of the touched package and test files only, through the package's test runner (vitest run, jest, node --test), in-memory adapters for ports, no emulator
|
|
35
|
+
# `pnpm --filter <package> test -- <test files>` may run the whole package suite; exec scopes
|
|
36
|
+
# to the files (decision 49).
|
|
37
|
+
commands: ["pnpm --filter <package> exec <test runner> <test files>"]
|
|
38
|
+
source: https://martinfowler.com/articles/practical-test-pyramid.html
|
|
39
|
+
- id: integration
|
|
40
|
+
description: Adapters against local emulators or containers
|
|
41
|
+
commands: ["pnpm --filter <adapter> test:integration"]
|
|
42
|
+
source: https://martinfowler.com/articles/practical-test-pyramid.html
|
|
43
|
+
- id: e2e
|
|
44
|
+
description: End-to-end tests against the built apps
|
|
45
|
+
commands: ["pnpm --filter <e2e> test:e2e"]
|
|
46
|
+
source: https://martinfowler.com/articles/practical-test-pyramid.html
|
|
47
|
+
loopLevels: [static, unit]
|
|
48
|
+
forbiddenInLoop: ["test:integration", "test:e2e", "playwright"]
|
|
49
|
+
# The prompt pyramid, bottom first (decision 32): how the prompt of a product's LLM feature is
|
|
50
|
+
# built. Each level is built by its specialists from the approved levels below it and ends when a
|
|
51
|
+
# person in the approver role approves it. People own the base (what "good" means) and the apex
|
|
52
|
+
# (accepting the result); the agent that writes the prompt never runs or reviews its evals. A
|
|
53
|
+
# failing eval goes back to the lowest level that explains it. Generic, so its sources are
|
|
54
|
+
# Claude's documentation (decision 30).
|
|
55
|
+
promptPyramid:
|
|
56
|
+
levels:
|
|
57
|
+
- id: success-criteria
|
|
58
|
+
description: Measurable criteria for the feature (quality, latency, cost, refusals, tone), drafted from the request
|
|
59
|
+
specialists: [{ persona: lead-developer, taskKind: decide }]
|
|
60
|
+
approver: product-owner
|
|
61
|
+
source: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview
|
|
62
|
+
- id: evals
|
|
63
|
+
description: Fixed cases with pass checks that test the criteria, written before any prompt and independent of it
|
|
64
|
+
specialists: [{ persona: qa-engineer, taskKind: test-plan }]
|
|
65
|
+
approver: product-owner
|
|
66
|
+
source: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview
|
|
67
|
+
- id: context
|
|
68
|
+
description: What the prompt receives, up front or just in time; the data class of every input; no personal data in prompts, examples or logs
|
|
69
|
+
specialists:
|
|
70
|
+
- { persona: security-steward, taskKind: decide }
|
|
71
|
+
- { persona: data-analyst-pii, taskKind: analysis }
|
|
72
|
+
approver: data-owner
|
|
73
|
+
source: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
|
|
74
|
+
- id: instructions
|
|
75
|
+
description: The model, and a system prompt at the right altitude, in sections; minimal first, then what observed failures need
|
|
76
|
+
specialists:
|
|
77
|
+
- { persona: architect, taskKind: decide }
|
|
78
|
+
- { persona: prompt-engineer, taskKind: prompt-design }
|
|
79
|
+
approver: domain-reviewer
|
|
80
|
+
source: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
|
|
81
|
+
- id: examples
|
|
82
|
+
description: A few diverse, canonical examples, synthetic or pseudonymised, instead of a list of edge cases
|
|
83
|
+
specialists: [{ persona: prompt-engineer, taskKind: prompt-design }]
|
|
84
|
+
approver: domain-reviewer
|
|
85
|
+
source: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
|
|
86
|
+
- id: structure
|
|
87
|
+
description: One prompt if the evals pass; otherwise the simplest pattern that does (chaining with gates, routing, orchestrator-workers)
|
|
88
|
+
specialists: [{ persona: architect, taskKind: decide }]
|
|
89
|
+
approver: tech-lead
|
|
90
|
+
source: https://www.anthropic.com/engineering/building-effective-agents
|
|
91
|
+
- id: eval-run
|
|
92
|
+
description: The evals run and are reviewed by agents other than the author; the pass rate per criterion and each failure mapped to the lowest level that explains it
|
|
93
|
+
specialists:
|
|
94
|
+
- { persona: qa-engineer, taskKind: verify }
|
|
95
|
+
- { persona: security-steward, taskKind: review }
|
|
96
|
+
approver: product-owner
|
|
97
|
+
source: https://www.anthropic.com/engineering/building-effective-agents
|
|
98
|
+
# Human checkpoints outside the prompt pyramid (decision 39): what an approval step may name
|
|
99
|
+
# besides a level. The run always stops there for a person in the approver role.
|
|
100
|
+
checkpoints:
|
|
101
|
+
- id: brief
|
|
102
|
+
description: The request brief, the structured prompt discovery starts from (goal, who, today, wanted, constraints, acceptance, out of scope, facts checked, unknowns)
|
|
103
|
+
approver: requester
|
|
104
|
+
source: decision 39 (friday docs/decisions.md)
|
|
105
|
+
# Rules the agents cannot break: checked before each tool call, not only stated in the prompt.
|
|
106
|
+
# Skills and prompts advise; these hooks enforce (The AI-native SDLC playbook, Build and Test).
|
|
107
|
+
guardrails:
|
|
108
|
+
# Every agent kind that runs inside a TDD pair. integrate is left out: it runs the integration
|
|
109
|
+
# loop, the one place the whole pyramid runs.
|
|
110
|
+
loopCommands:
|
|
111
|
+
taskKinds: [test-design, implement, scaffold, adapter, verify]
|
|
112
|
+
# QA writes the failing test; the implementer makes it pass without touching it.
|
|
113
|
+
protectedTests:
|
|
114
|
+
taskKinds: [implement]
|
|
115
|
+
patterns:
|
|
116
|
+
- '(^|/)(test|tests|__tests__|e2e)/'
|
|
117
|
+
- '\.(test|spec)\.[cm]?[jt]sx?$'
|
|
118
|
+
# Approved prompt pyramid levels are write-once downstream (decision 35): the record in
|
|
119
|
+
# docs/friday/<workId>/prompt/ and the copies the product loads, named *.prompt.*, *.examples.*
|
|
120
|
+
# or *.evals.*. A task creates a copy once, from its approved level file; nobody downstream
|
|
121
|
+
# changes one after. Decisions, reviews and the prompt's author upstream are not limited.
|
|
122
|
+
approvedPrompts:
|
|
123
|
+
taskKinds: [implement, scaffold, adapter, integrate, test-design]
|
|
124
|
+
patterns:
|
|
125
|
+
- '(^|/)docs/friday/[^/]+/prompt/[^/]+\.md$'
|
|
126
|
+
- '\.(prompt|examples|evals)\.[a-z0-9]+$'
|
|
127
|
+
contract: |
|
|
128
|
+
## Friday contract (applies to every step)
|
|
129
|
+
|
|
130
|
+
- **Assumptions kill.** Never assume. Anything you would have to assume becomes a question
|
|
131
|
+
with options and a recommendation, returned in `questions`. Upstream, the user answers it.
|
|
132
|
+
Downstream, stop and return `status: blocked` with the question: it goes back upstream.
|
|
133
|
+
- Follow the conventions loaded as skills/rules. If a convention and the request disagree,
|
|
134
|
+
say so; do not pick silently.
|
|
135
|
+
- Report only what you did and verified. A failing test, a skipped step or a guess is reported
|
|
136
|
+
as such.
|
|
137
|
+
- Never put tokens, credentials or personal data in prompts, logs, commits or PR text.
|