@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.
Files changed (67) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +275 -2
  3. package/bundles/friday-claude-0.1.0.zip +0 -0
  4. package/bundles/friday-opencode-0.1.0.zip +0 -0
  5. package/dist/adapters/adapter.js +6 -0
  6. package/dist/adapters/claude/guards.js +40 -0
  7. package/dist/adapters/claude/index.js +161 -0
  8. package/dist/adapters/claude/runtime.js +645 -0
  9. package/dist/adapters/claude/workflows.js +323 -0
  10. package/dist/adapters/drivers.js +294 -0
  11. package/dist/adapters/index.js +16 -0
  12. package/dist/adapters/opencode/index.js +232 -0
  13. package/dist/adapters/skill.js +327 -0
  14. package/dist/build.js +77 -0
  15. package/dist/cli.js +197 -0
  16. package/dist/frontmatter.js +16 -0
  17. package/dist/graph.js +218 -0
  18. package/dist/handoff.js +329 -0
  19. package/dist/install.js +137 -0
  20. package/dist/ir.js +177 -0
  21. package/dist/load.js +42 -0
  22. package/dist/paths.js +24 -0
  23. package/dist/prompts.js +228 -0
  24. package/dist/specialize.js +201 -0
  25. package/dist/step-schemas.js +440 -0
  26. package/dist/types.js +8 -0
  27. package/dist/validate.js +576 -0
  28. package/pack/conventions/changesets.yaml +20 -0
  29. package/pack/conventions/ci-workflows.yaml +16 -0
  30. package/pack/conventions/config-secrets.yaml +16 -0
  31. package/pack/conventions/data-classification.yaml +16 -0
  32. package/pack/conventions/decisions.yaml +13 -0
  33. package/pack/conventions/git.yaml +28 -0
  34. package/pack/conventions/hexagonal.yaml +31 -0
  35. package/pack/conventions/security-code.yaml +17 -0
  36. package/pack/conventions/testing.yaml +44 -0
  37. package/pack/conventions/typescript-node.yaml +16 -0
  38. package/pack/model-policy.yaml +80 -0
  39. package/pack/orchestrations/architecture-decision.yaml +52 -0
  40. package/pack/orchestrations/bugfix-tdd.yaml +67 -0
  41. package/pack/orchestrations/data-analysis.yaml +23 -0
  42. package/pack/orchestrations/discovery.yaml +204 -0
  43. package/pack/orchestrations/feature-delivery.yaml +129 -0
  44. package/pack/orchestrations/prompt-delivery.yaml +155 -0
  45. package/pack/orchestrations/prompt-discovery.yaml +201 -0
  46. package/pack/orchestrations/release.yaml +40 -0
  47. package/pack/pack.yaml +137 -0
  48. package/pack/personas/architect.yaml +18 -0
  49. package/pack/personas/backend-engineer.yaml +21 -0
  50. package/pack/personas/data-analyst-non-pii.yaml +14 -0
  51. package/pack/personas/data-analyst-pii.yaml +28 -0
  52. package/pack/personas/devops-engineer.yaml +19 -0
  53. package/pack/personas/frontend-engineer.yaml +18 -0
  54. package/pack/personas/git-steward.yaml +24 -0
  55. package/pack/personas/lead-developer.yaml +23 -0
  56. package/pack/personas/prompt-engineer.yaml +38 -0
  57. package/pack/personas/qa-engineer.yaml +24 -0
  58. package/pack/personas/security-steward.yaml +20 -0
  59. package/package.json +47 -4
  60. package/schemas/convention.schema.yaml +46 -0
  61. package/schemas/handoff.schema.yaml +303 -0
  62. package/schemas/model-policy.schema.yaml +33 -0
  63. package/schemas/orchestration.schema.yaml +224 -0
  64. package/schemas/pack.schema.yaml +168 -0
  65. package/schemas/persona.schema.yaml +41 -0
  66. package/schemas/specialization-patch.schema.yaml +39 -0
  67. 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.