@digital-agora/friday 0.11.0 → 0.13.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 (40) hide show
  1. package/README.md +7 -4
  2. package/bundles/friday-claude-0.13.0.zip +0 -0
  3. package/bundles/friday-opencode-0.13.0.zip +0 -0
  4. package/dist/adapters/claude/index.js +2 -1
  5. package/dist/adapters/claude/runtime.js +298 -49
  6. package/dist/adapters/claude/workflows.js +94 -36
  7. package/dist/adapters/drivers.js +44 -14
  8. package/dist/adapters/opencode/index.js +2 -1
  9. package/dist/adapters/skill.js +10 -2
  10. package/dist/cli.js +42 -7
  11. package/dist/contracts.js +200 -0
  12. package/dist/flow.js +230 -0
  13. package/dist/graph.js +11 -5
  14. package/dist/handoff.js +76 -3
  15. package/dist/ir.js +1 -0
  16. package/dist/load.js +3 -0
  17. package/dist/prompts.js +88 -5
  18. package/dist/reads.js +1 -1
  19. package/dist/slice.js +126 -0
  20. package/dist/specialize.js +10 -0
  21. package/dist/step-schemas.js +28 -3
  22. package/dist/validate.js +38 -20
  23. package/pack/model-policy.yaml +5 -0
  24. package/pack/orchestrations/architecture-decision.yaml +5 -0
  25. package/pack/orchestrations/bugfix-tdd.yaml +1 -1
  26. package/pack/orchestrations/discovery.yaml +16 -3
  27. package/pack/orchestrations/feature-delivery.yaml +11 -3
  28. package/pack/orchestrations/prompt-delivery.yaml +13 -5
  29. package/pack/orchestrations/prompt-discovery.yaml +3 -0
  30. package/pack/pack.yaml +14 -3
  31. package/pack/personas/backend-engineer.yaml +1 -1
  32. package/pack/personas/devops-engineer.yaml +1 -1
  33. package/pack/personas/frontend-engineer.yaml +1 -1
  34. package/package.json +2 -2
  35. package/schemas/decisions.schema.yaml +28 -0
  36. package/schemas/handoff.schema.yaml +66 -4
  37. package/schemas/orchestration.schema.yaml +10 -4
  38. package/schemas/pack.schema.yaml +25 -0
  39. package/bundles/friday-claude-0.1.0.zip +0 -0
  40. package/bundles/friday-opencode-0.1.0.zip +0 -0
@@ -20,6 +20,9 @@ sizing:
20
20
  large: 10
21
21
  maxAgentsPerWorkflow: 6
22
22
  maxRounds: 5
23
+ # From round 3 the driver offers the close-out rule once: only items that change behaviour or
24
+ # contradict an answer still go to the user, the rest take the recommended option (decision 59).
25
+ closeOutFromRound: 3
23
26
  deferNonBlocking: true
24
27
  maxItemsPerRound: 15
25
28
  inputs:
package/pack/pack.yaml CHANGED
@@ -4,7 +4,8 @@
4
4
  # come in a specialization (decision 41), which lists the repositories they cite in its sources.
5
5
  id: friday
6
6
  name: Friday
7
- version: 0.1.0
7
+ # The release's version: pnpm version-packages copies it from package.json (decision 67).
8
+ version: 0.13.0
8
9
  description: SDLC agents, workflows and conventions (hexagonal core, TDD pairs, a test pyramid, people approving every handoff).
9
10
  sources: []
10
11
  # A task's `stack` (set by the lead developer upstream) picks the engineer that implements it.
@@ -102,16 +103,26 @@ checkpoints:
102
103
  description: The request brief, the structured prompt discovery starts from (goal, who, today, wanted, constraints, acceptance, out of scope, facts checked, unknowns)
103
104
  approver: requester
104
105
  source: decision 39 (friday docs/decisions.md)
106
+ # The orchestration check (decision 58) computes every orchestration's worst-case agent calls from
107
+ # its loop limits and warns above warnAbove for a handoff of this size. Today's largest delivery
108
+ # (prompt-delivery) is 472 at this size.
109
+ agentCallBudget:
110
+ warnAbove: 500
111
+ # friday handoff check estimates the run's prompt tokens spent on the handoff from the real
112
+ # handoff and warns above this (decision 61). A 22-task handoff of about 120,000 tokens comes to
113
+ # about 13 million in the worst case even with task slices; at 5 million it warns.
114
+ warnPromptTokensAbove: 5000000
115
+ assume: { task: 10, stack: 3, followup: 3, item: 10 }
105
116
  # Rules the agents cannot break: checked before each tool call, not only stated in the prompt.
106
117
  # Skills and prompts advise; these hooks enforce (The AI-native SDLC playbook, Build and Test).
107
118
  guardrails:
108
119
  # Every agent kind that runs inside a TDD pair. integrate is left out: it runs the integration
109
120
  # loop, the one place the whole pyramid runs.
110
121
  loopCommands:
111
- taskKinds: [test-design, implement, scaffold, adapter, verify]
122
+ taskKinds: [test-design, implement, scaffold, adapter, verify, document]
112
123
  # QA writes the failing test; the implementer makes it pass without touching it.
113
124
  protectedTests:
114
- taskKinds: [implement]
125
+ taskKinds: [implement, document]
115
126
  patterns:
116
127
  - '(^|/)(test|tests|__tests__|e2e)/'
117
128
  - '\.(test|spec)\.[cm]?[jt]sx?$'
@@ -2,7 +2,7 @@ id: backend-engineer
2
2
  name: Backend Engineer
3
3
  role: Implements the core, adapters, functions and services.
4
4
  description: Implements tasks in the core, its adapters, functions and services in TDD with the QA engineer.
5
- taskKinds: [implement, scaffold, adapter, integrate]
5
+ taskKinds: [implement, scaffold, adapter, integrate, document]
6
6
  tools: [Read, Edit, Write, Grep, Glob, Bash]
7
7
  conventions: [hexagonal, typescript-node, testing, security-code, config-secrets]
8
8
  pairsWith: qa-engineer
@@ -2,7 +2,7 @@ id: devops-engineer
2
2
  name: DevOps Engineer
3
3
  role: Owns CI/CD, infrastructure as code, GitHub workflows and releases.
4
4
  description: Implements pipeline, infrastructure-as-code, .github/workflows, config/ and release tasks in TDD with the QA engineer (pipeline checks are the tests).
5
- taskKinds: [implement, scaffold, integrate]
5
+ taskKinds: [implement, scaffold, integrate, document]
6
6
  tools: [Read, Edit, Write, Grep, Glob, Bash]
7
7
  conventions: [changesets, ci-workflows, config-secrets, security-code]
8
8
  pairsWith: qa-engineer
@@ -2,7 +2,7 @@ id: frontend-engineer
2
2
  name: Frontend Engineer
3
3
  role: Implements web apps under apps/.
4
4
  description: Implements web app tasks under apps/<app> in TDD with the QA engineer. Server actions and API routes call the core.
5
- taskKinds: [implement, scaffold, adapter, integrate]
5
+ taskKinds: [implement, scaffold, adapter, integrate, document]
6
6
  tools: [Read, Edit, Write, Grep, Glob, Bash]
7
7
  conventions: [hexagonal, typescript-node, testing, security-code]
8
8
  pairsWith: qa-engineer
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@digital-agora/friday",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "description": "Friday: the source of truth for AI-assisted SDLC. Compiles YAML personas, workflows and conventions into agent bundles (Claude Code, OpenCode).",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,7 +31,7 @@
31
31
  "bundles": "node -e \"require('fs').rmSync('bundles',{recursive:true,force:true})\" && node dist/cli.js bundle --target all --out bundles",
32
32
  "prepack": "pnpm build && pnpm bundles",
33
33
  "changeset": "changeset",
34
- "version-packages": "changeset version"
34
+ "version-packages": "changeset version && node scripts/sync-pack-version.mjs"
35
35
  },
36
36
  "dependencies": {
37
37
  "ajv": "^8.17.1",
@@ -0,0 +1,28 @@
1
+ # A project's documented decisions, keyed by topic (decision 64): decisions.yaml at the root of a
2
+ # pack, a specialization or a project's .friday/. Upstream, an open item whose topic a decision
3
+ # names is settled by it instead of asked; one that contradicts it stays a contradiction.
4
+ $id: https://friday.digital-agora/schemas/decisions.schema.yaml
5
+ title: Documented decisions
6
+ type: object
7
+ additionalProperties: false
8
+ required: [decisions]
9
+ properties:
10
+ decisions:
11
+ type: array
12
+ items:
13
+ type: object
14
+ additionalProperties: false
15
+ required: [id, topics, decision, source]
16
+ properties:
17
+ id: { type: string, pattern: "^[A-Za-z][A-Za-z0-9._-]{0,60}$", description: "e.g. ADR-007; a specialization's entry with the same id replaces the pack's." }
18
+ topics:
19
+ description: The kebab-case subjects it settles; an open item with one of these topics is settled by it. One topic belongs to one decision.
20
+ type: array
21
+ minItems: 1
22
+ uniqueItems: true
23
+ items: { type: string, pattern: "^[a-z0-9][a-z0-9-]{0,60}$" }
24
+ decision: { type: string, minLength: 1, description: The rule, as complete as the code follows it. }
25
+ why: { type: string }
26
+ source:
27
+ type: string
28
+ description: Where it is documented, "document, don't invent" (decision 30) - <repo>/<path> of a repository in sources, an https:// page, or a Friday decision.
@@ -43,6 +43,7 @@ properties:
43
43
  decision: { type: string }
44
44
  why: { type: string }
45
45
  where: { type: string }
46
+ source: { type: string, description: "For a documented decision the work relies on (decision 64): where it is documented." }
46
47
  contracts:
47
48
  description: Architect's contract outcomes per interaction (type and why, errors, audit and logging, owner, consumers, accepted trade-offs).
48
49
  type: array
@@ -84,7 +85,11 @@ properties:
84
85
  test: { type: string }
85
86
  owner: { type: string }
86
87
  interfaceContracts:
87
- description: Technical-lead definitions of implementation-facing boundaries for developers.
88
+ description: >-
89
+ Technical-lead definitions of implementation-facing boundaries for developers. DSL first,
90
+ code after (decision 65): a contract the work adds (new) or changes (changed) is written in
91
+ the DSL below, with its data in shapes, or points at an OpenAPI or AsyncAPI document (spec);
92
+ an existing one is only referenced (owner). Delivery codes the interfaces from it.
88
93
  type: array
89
94
  items:
90
95
  type: object
@@ -92,9 +97,45 @@ properties:
92
97
  properties:
93
98
  id: { type: string }
94
99
  boundary: { type: string }
95
- contract: { type: string }
100
+ contract: { type: string, description: The contract in one or two sentences. }
96
101
  consumers: { type: array, items: { type: string } }
97
102
  rationale: { type: string }
103
+ change: { enum: [new, changed, existing], description: "new and changed need the DSL (kind and its body); existing is a reference: owner says where it lives." }
104
+ kind: { enum: [port, callable, event, type, http, async], description: "port and callable: operations; event: payload; type: shape; http and async: spec." }
105
+ owner: { type: string, description: "The codebase (path) that owns it." }
106
+ operations:
107
+ type: array
108
+ items:
109
+ type: object
110
+ additionalProperties: false
111
+ required: [name, errors]
112
+ properties:
113
+ name: { type: string }
114
+ input: { type: string, description: "A shape name or a primitive (string, integer, number, boolean, date, datetime)." }
115
+ output: { type: string, description: "A shape name or a primitive; leave out when it returns nothing." }
116
+ errors: { type: array, items: { type: string }, description: "Every error it can return, by name; [] when it returns none." }
117
+ realizes:
118
+ type: array
119
+ items: { type: string }
120
+ description: "The inner-layer contracts this one implements or exposes, by id (an adapter implements a port, a callable or http endpoint exposes a use-case port): each is another codebase's contract, with no cycle."
121
+ payload: { type: string, description: "kind event: the shape it carries." }
122
+ shape: { type: string, description: "kind type: the shape it is." }
123
+ spec:
124
+ type: object
125
+ additionalProperties: false
126
+ required: [file, format]
127
+ description: "kind http or async: the OpenAPI or AsyncAPI document that is the contract, by its path in the repository."
128
+ properties:
129
+ file: { type: string }
130
+ format: { enum: [openapi, asyncapi] }
131
+ ref: { type: string, description: "The part of it that is this contract, e.g. a path or a channel." }
132
+ shapes:
133
+ description: >-
134
+ The data shapes the interface contracts name (decision 65), language-neutral: a typed codebase
135
+ codes them as types, an untyped one as the validators it uses. friday contracts schema writes
136
+ them as JSON Schema.
137
+ type: object
138
+ additionalProperties: { $ref: "#/$defs/shape" }
98
139
  testPlan:
99
140
  description: QA-authored behavioral scenarios; delivery QA writes the executable tests.
100
141
  type: array
@@ -131,7 +172,9 @@ properties:
131
172
  stack: { type: string }
132
173
  codebase: { type: string, description: 'Path in the monorepo, e.g. packages/core or services/<name>-api.' }
133
174
  scope: { type: string, description: The id of the scope (scope.scopes) this task delivers. }
134
- taskKind: { enum: [implement, scaffold, adapter] }
175
+ taskKind:
176
+ description: "document: a task that only writes documents (an ADR, a guide); it skips test design and verify runs only the static level (decision 62)."
177
+ enum: [implement, scaffold, adapter, document]
135
178
  acceptance: { type: array, minItems: 1, items: { type: string } }
136
179
  dependsOn: { type: array, items: { type: string } }
137
180
  conventions: { type: array, items: { type: string } }
@@ -236,8 +279,13 @@ properties:
236
279
  additionalProperties: false
237
280
  properties:
238
281
  maySettle:
282
+ description: >-
283
+ The kinds the delivery decider may settle; a kind not listed is never applied. answer-detail
284
+ is the technical detail an answer already given implies (the exact formula, merge rule or
285
+ edge case of the chosen option) when the handoff and the repository support one reading.
286
+ other is any further kind the user allowed, limited by notes.
239
287
  type: array
240
- items: { enum: [test-fixture, lint-suppression, repo-fact-exception, command-mapping] }
288
+ items: { enum: [test-fixture, lint-suppression, repo-fact-exception, command-mapping, answer-detail, other] }
241
289
  notes: { type: string, description: "Limits, e.g. the named repo facts an exception may cover." }
242
290
  briefs:
243
291
  description: >-
@@ -301,3 +349,17 @@ properties:
301
349
  description: Must be empty for downstream to start.
302
350
  type: array
303
351
  maxItems: 0
352
+ $defs:
353
+ shape:
354
+ type: object
355
+ additionalProperties: false
356
+ required: [type]
357
+ properties:
358
+ type: { enum: [string, integer, number, boolean, date, datetime, object, array, enum, ref] }
359
+ description: { type: string }
360
+ fields: { type: object, additionalProperties: { $ref: "#/$defs/shape" }, description: "type object: its fields." }
361
+ required: { type: array, items: { type: string }, description: "type object: the fields that are always present." }
362
+ items: { $ref: "#/$defs/shape", description: "type array: its items." }
363
+ values: { type: array, items: { type: string }, minItems: 1, description: "type enum: its values." }
364
+ ref: { type: string, description: "type ref: the shape it is." }
365
+ nullable: { type: boolean }
@@ -63,8 +63,8 @@ properties:
63
63
  required: { type: boolean }
64
64
  maxRounds:
65
65
  description: >-
66
- Upstream only: how many question rounds the driver runs before it stops and asks the user
67
- to freeze the scope or explicitly allow more rounds. Without it the loop is unbounded.
66
+ Upstream only, and required there (decision 58): how many question rounds the driver runs
67
+ before it stops and asks the user to freeze the scope or explicitly allow more rounds.
68
68
  type: integer
69
69
  minimum: 1
70
70
  maximum: 10
@@ -96,6 +96,9 @@ properties:
96
96
  type: array
97
97
  minItems: 1
98
98
  items: { $ref: "#/$defs/step" }
99
+ # Every loop has a finite limit (decision 58): an upstream workflow's question rounds too.
100
+ if: { properties: { stream: { const: upstream } }, required: [stream] }
101
+ then: { required: [maxRounds] }
99
102
 
100
103
  $defs:
101
104
  common:
@@ -154,8 +157,11 @@ $defs:
154
157
  required: [persona, taskKind, prompt]
155
158
  properties:
156
159
  output:
157
- description: The shape the agent returns; briefs is one task brief per task (decision 40).
158
- enum: [result, tasks, briefs, review, git]
160
+ description: >-
161
+ The shape the agent returns; briefs is one task brief per task (decision 40);
162
+ interfaces is a result whose interfaceContracts and shapes are the DSL, checked
163
+ before the run goes on (decision 65).
164
+ enum: [result, tasks, briefs, review, git, interfaces]
159
165
  - if: { properties: { type: { const: clarify } } }
160
166
  then: { required: [persona, taskKind, topic] }
161
167
  - if: { properties: { type: { const: gap-analysis } } }
@@ -122,6 +122,31 @@ properties:
122
122
  type: string
123
123
  pattern: "^[a-z][a-z0-9-]*$"
124
124
  source: { type: string }
125
+ agentCallBudget:
126
+ description: >-
127
+ The orchestration check's budget (decision 58): every orchestration's worst-case agent calls
128
+ are computed from its nested loop limits; the validator warns, and never fails, when the
129
+ count for a handoff of the assumed size is above warnAbove.
130
+ type: object
131
+ additionalProperties: false
132
+ required: [warnAbove, assume]
133
+ properties:
134
+ warnAbove: { type: integer, minimum: 1, description: Worst-case agent calls above which validation warns. }
135
+ warnPromptTokensAbove:
136
+ type: integer
137
+ minimum: 1
138
+ description: >-
139
+ Worst-case prompt tokens of handoff above which friday handoff check warns (decision 61),
140
+ estimated from the real handoff before the run.
141
+ assume:
142
+ description: The size the worst case is evaluated at; a unit left out counts 1.
143
+ type: object
144
+ additionalProperties: false
145
+ properties:
146
+ task: { type: integer, minimum: 1, description: Tasks in the handoff. }
147
+ stack: { type: integer, minimum: 1, description: Stacks the tasks use (one integration run each per round). }
148
+ followup: { type: integer, minimum: 0, description: Follow-up tasks one integration round proposes. }
149
+ item: { type: integer, minimum: 1, description: Items of an earlier step's list (<stepId>.tasks). }
125
150
  guardrails:
126
151
  description: >-
127
152
  Pack rules the generated agents cannot break. A skill or a prompt makes a rule likely to be
Binary file
Binary file