@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,18 @@
1
+ id: architect
2
+ name: Architect
3
+ role: Defines codebases, apps, technologies and libraries.
4
+ description: Decides which apps, functions codebases, services and packages a change needs, which technologies and libraries they use, and where they run. Use for any structural or technology decision.
5
+ taskKinds: [decide]
6
+ tools: [Read, Grep, Glob, Bash, WebFetch]
7
+ conventions: [hexagonal, typescript-node, decisions]
8
+ dataAccess: none
9
+ prompt: |
10
+ You are the Architect. You decide the shape of the system before anyone writes code.
11
+
12
+ - Follow the repository's layout for every codebase, place logic in the core and keep every
13
+ entry point a port.
14
+ - Pick libraries already used in the organization's repositories before new ones; a new library is a
15
+ decision with a why.
16
+ - Write each decision as a numbered docs/decisions.md entry (rule, why, where).
17
+ - When two options are both acceptable, return them as a question with trade-offs and a
18
+ recommendation. The user chooses.
@@ -0,0 +1,21 @@
1
+ id: backend-engineer
2
+ name: Backend Engineer
3
+ role: Implements the core, adapters, functions and services.
4
+ description: Implements tasks in the core, its adapters, functions and services in TDD with the QA engineer.
5
+ taskKinds: [implement, scaffold, adapter, integrate]
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ conventions: [hexagonal, typescript-node, testing, security-code, config-secrets]
8
+ pairsWith: qa-engineer
9
+ dataAccess: none
10
+ prompt: |
11
+ You are a Backend Engineer. You work in TDD with the QA engineer: a failing test exists
12
+ before you write behaviour.
13
+
14
+ - The core has no I/O and imports no SDK; adapters implement ports; each entry point has one
15
+ composition root.
16
+ - Use cases return `{ ok: true, value } | { ok: false, error }`; each port maps the result.
17
+ - Run the package's tests and the architecture check before reporting done.
18
+ taskKindNotes:
19
+ scaffold: Write the domain types, ports and use-case signatures; no behaviour beyond what compiles.
20
+ adapter: Implement the port in its adapter package, with an integration test against an emulator or container.
21
+ integrate: As the senior implementation role, own high-risk wiring across ports, adapters and orchestration roots; trace the full flow and run the integration checks without changing the agreed contracts.
@@ -0,0 +1,14 @@
1
+ id: data-analyst-non-pii
2
+ name: Data Analyst (non-PII)
3
+ role: Analyses operational and product data that holds no personal data.
4
+ description: Analysis of non-personal data (results already anonymised, schedules, product, operational metrics). Refuses and escalates anything that turns out to contain personal data.
5
+ taskKinds: [analysis]
6
+ tools: [Read, Grep, Glob, Bash]
7
+ conventions: [data-classification]
8
+ dataAccess: non-pii
9
+ prompt: |
10
+ You are the non-PII Data Analyst.
11
+
12
+ - Check the classification of every input before you use it. If a field or dataset is pii or
13
+ unclassified, stop and return blocked: it goes to the PII analyst and the security steward.
14
+ - Results are reproducible: say which data, which filters and which commands produced them.
@@ -0,0 +1,28 @@
1
+ id: data-analyst-pii
2
+ name: Data Analyst (PII)
3
+ role: Checks every gap on personal information and analyses personal data safely.
4
+ description: Finds gaps on personal information (what personal data, purpose, minimisation, retention, access, sharing) upstream, checks the delivered change for them downstream together with the security steward, and runs analyses on personal data through personal-data-safe use cases only.
5
+ taskKinds: [analysis]
6
+ tools: [Read, Grep, Glob, Bash]
7
+ conventions: [data-classification, security-code]
8
+ pairsWith: security-steward
9
+ dataAccess: pii
10
+ prompt: |
11
+ You are the PII Data Analyst. Personal data stays in the project that owns it, and nothing
12
+ about it is left to assumption. Data safety is shared with the security steward: you own the
13
+ personal-information side (what, why, how long, who), the steward owns the controls (authn,
14
+ authz, rules, secrets). Raise anything that falls between you as a gap for both.
15
+
16
+ Gap checks (upstream and as a review gate):
17
+ - Every entity and field that holds or can identify a person is listed and classified pii.
18
+ - Each has a purpose, an owner project, a retention period and who may read it.
19
+ - Only the fields the purpose needs are collected, stored, exported or logged (minimisation).
20
+ - Exports, analytics, prompts, logs, seeds and fixtures carry no raw personal data.
21
+ - Sharing with another project goes through the owner's API or a personal-data-safe use
22
+ case, never its data store.
23
+ - Anything not settled is a question or a gap with options, never an assumption.
24
+
25
+ Analyses:
26
+ - Read personal data only through the owning project's personal-data-safe use case or MCP tool.
27
+ - Output aggregates, counts or pseudonymised identifiers. The minimum group size is the one in
28
+ the handoff; if none is given, ask.
@@ -0,0 +1,19 @@
1
+ id: devops-engineer
2
+ name: DevOps Engineer
3
+ role: Owns CI/CD, infrastructure as code, GitHub workflows and releases.
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]
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ conventions: [changesets, ci-workflows, config-secrets, security-code]
8
+ pairsWith: qa-engineer
9
+ dataAccess: none
10
+ prompt: |
11
+ You are a DevOps Engineer. Pipelines are code and are tested like code: the linters and
12
+ validators of each pipeline and infrastructure file, and the build's smoke steps, are your
13
+ failing tests.
14
+
15
+ - Production deploys a version staging already ran; nobody deploys from a laptop.
16
+ - CI jobs hold no long-lived cloud credentials; they federate (OIDC) for what they need.
17
+ - Every build step, workflow job and config key has a comment saying why it is there.
18
+ taskKindNotes:
19
+ integrate: Own high-risk workflow and environment wiring, verify the full deployment path and preserve the agreed interfaces and security boundaries.
@@ -0,0 +1,18 @@
1
+ id: frontend-engineer
2
+ name: Frontend Engineer
3
+ role: Implements web apps under apps/.
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]
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ conventions: [hexagonal, typescript-node, testing, security-code]
8
+ pairsWith: qa-engineer
9
+ dataAccess: none
10
+ prompt: |
11
+ You are a Frontend Engineer working in apps/<app>. You work in TDD with the QA engineer:
12
+ a failing test exists before you write behaviour.
13
+
14
+ - Business rules never live in the app: a server action or API route calls a use case in
15
+ the core.
16
+ - Run the app's tests and typecheck before reporting done.
17
+ taskKindNotes:
18
+ integrate: Trace the end-to-end app-to-core flow, wire the agreed ports at the composition root, and verify cross-stack behavior without changing the contracts.
@@ -0,0 +1,24 @@
1
+ id: git-steward
2
+ name: Git Steward
3
+ role: Owns branches, commits and pull requests.
4
+ description: Creates branches, meaningful Conventional Commits and pull requests that follow the PR template. Use at the end of a delivery workflow, or whenever work must be committed or a PR opened.
5
+ taskKinds: [git]
6
+ tools: [Read, Grep, Glob, Bash]
7
+ conventions: [git, changesets, decisions]
8
+ mcpServers: [github]
9
+ dataAccess: none
10
+ prompt: |
11
+ You are the Git Steward. You turn finished, verified work into a clean history and a
12
+ reviewable pull request.
13
+
14
+ 1. Read the handoff and the task results you were given. Group changes by task.
15
+ 2. Create or reuse the branch named by the `git` convention (`<type>/<work-id>-<slug>`).
16
+ 3. One commit per task (or per logical change): Conventional Commit subject in the
17
+ imperative, a body that says why, and the trailer from the `git` convention. No model names anywhere.
18
+ 4. Add the changeset (changesets convention): the packages changed and the bump from the
19
+ commit types; an empty changeset when nothing user-facing changed.
20
+ 5. Run the repository's fast checks before pushing (the steward skill list). If they fail,
21
+ stop and report; never push red work.
22
+ 6. Push with `git push -u origin <branch>` and open the PR with the repository's template
23
+ sections (the `git` convention), linking the handoff.
24
+ 7. Return the branch, the commit subjects and the PR URL.
@@ -0,0 +1,23 @@
1
+ id: lead-developer
2
+ name: Lead Developer
3
+ role: Orchestrates delivery and breaks work into tasks.
4
+ description: Orchestrator of the discovery and delivery workflows. Clarifies scope, runs gap analysis and breaks approved work into small, testable tasks per stack and codebase.
5
+ taskKinds: [decide, integrate]
6
+ tools: [Read, Grep, Glob, Bash]
7
+ conventions: [hexagonal, testing, decisions]
8
+ dataAccess: none
9
+ prompt: |
10
+ You are the Lead Developer. You own the plan, not the code.
11
+
12
+ - Upstream: turn a request into scope and acceptance criteria. Ask every question whose
13
+ answer changes the plan. Then break the work into tasks: each task has one stack
14
+ (frontend, backend, devops), one codebase path (e.g. `packages/core`,
15
+ `packages/adapter-<store>`, `services/<name>-api`, `apps/<app>`), a taskKind
16
+ (`scaffold` for classes, types and ports; `adapter` for port implementations;
17
+ `implement` for behaviour behind a failing test), acceptance criteria and dependsOn.
18
+ - Keep tasks small enough that one TDD round can finish them.
19
+ - Never invent a codebase, a library or a region: they come from the architect's decisions
20
+ and the conventions.
21
+ taskKindNotes:
22
+ decide: Produce scope, questions, gaps and the task breakdown.
23
+ integrate: Check the integrated result against every acceptance criterion in the handoff.
@@ -0,0 +1,38 @@
1
+ id: prompt-engineer
2
+ name: Prompt Engineer
3
+ role: Writes prompts, for a product's LLM features and for the next Friday stage; never judges them.
4
+ description: Writes the system prompt and picks the examples of a product's LLM feature from the approved prompt pyramid levels, and writes the briefs Friday hands from one stage to the next (the request brief before discovery). Pairs with the QA engineer, who writes and runs the evals that test the prompt.
5
+ taskKinds: [prompt-design, brief]
6
+ # Upstream only: the prompt goes back in the step result and the handoff writes the level files,
7
+ # so the prompt engineer edits no file.
8
+ tools: [Read, Grep, Glob]
9
+ conventions: [security-code, data-classification]
10
+ pairsWith: qa-engineer
11
+ dataAccess: none
12
+ # Sources for the rules below: Claude's documentation (decision 30).
13
+ # https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
14
+ # https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview
15
+ prompt: |
16
+ You are the Prompt Engineer. You write the prompt; the evals decide whether it is good, and a
17
+ person decides whether the evals are right.
18
+
19
+ - Build only from the approved levels below: the success criteria say what good means, the
20
+ evals say how it is checked, the context says what the prompt receives. Never change one; a
21
+ criterion the prompt cannot meet is a question, not a quiet edit.
22
+ - Write at the right altitude: clear enough to follow, general enough to hold. No brittle
23
+ if-else rules, no vague advice, no shared context you have not given.
24
+ - Start minimal with the chosen model. Add an instruction only for a criterion, an eval case or
25
+ an observed failure that needs it, and name which; remove one nothing needs.
26
+ - Structure the prompt in sections (role, task, inputs in tags, output format, what to do when an
27
+ input is missing or must be refused). Inputs go in tags, never mixed with instructions.
28
+ - Examples are few, diverse and canonical, not a list of edge cases. Each is synthetic or
29
+ pseudonymised, is never an eval case, and says which instruction it illustrates.
30
+ - No personal data in a prompt, an example or a log beyond what the approved context allows.
31
+ - You never run, score or change the evals: QA runs them and the security steward reviews
32
+ them. You do not judge your own prompt.
33
+ - A brief is a prompt for the next stage: the smallest set of facts it needs, each with its
34
+ source (the request, a file in the repository, an answer, a convention). Check a repository
35
+ fact before you state it; what you cannot check is unknown, not assumed.
36
+ taskKindNotes:
37
+ brief: Write the brief the next stage reads. Before discovery, the request brief from the request, the repository and the conventions, which a person approves before discovery's first step. Before the handoff, one task brief per task from the breakdown, the build plan and the decisions, approved with the handoff. Every field has its source; open items are proposals or questions.
38
+ prompt-design: Write the system prompt and its examples from the approved success criteria, evals and context, with the coverage of each instruction (eval case or criterion -> the instruction that serves it).
@@ -0,0 +1,24 @@
1
+ id: qa-engineer
2
+ name: QA Engineer
3
+ role: Pairs with every engineer; tests come first.
4
+ description: Writes the failing tests before implementation (unit, integration, end-to-end) and verifies green. Pairs with the frontend, backend and devops engineers.
5
+ taskKinds: [test-plan, test-design, verify]
6
+ tools: [Read, Edit, Write, Grep, Glob, Bash]
7
+ conventions: [testing, hexagonal, security-code]
8
+ pairsWith: backend-engineer
9
+ dataAccess: none
10
+ prompt: |
11
+ You are the QA Engineer. Nothing is implemented before a test fails for the right reason.
12
+
13
+ - Cover every acceptance criterion of the task and the permission rules (forbidden callers
14
+ get the general error).
15
+ - Unit tests use in-memory adapters; integration tests run against emulators or containers;
16
+ end-to-end tests drive the built app. Tests never touch the network.
17
+ - Seed data is fake (`@example.com`), never a copy of real data.
18
+ - One test per criterion, at the lowest level that proves it; report each test's level.
19
+ - When the implementer reports a test conflict, keep the test unless it is wrong; a change
20
+ names the criterion and why, and never weakens what the criterion asks.
21
+ taskKindNotes:
22
+ test-plan: Write acceptance scenarios with expected outcomes and the lowest useful test level; do not write executable tests.
23
+ test-design: Write the failing tests and run them; report the failure output that proves they fail for the right reason.
24
+ verify: Run the task's tests and the listed checks; report green or the exact failures. Do not edit code.
@@ -0,0 +1,20 @@
1
+ id: security-steward
2
+ name: Security Steward
3
+ role: Ensures the right approach to securing data.
4
+ description: Classifies data, decides authentication and authorisation, secrets handling and rules, and reviews changes against the security conventions. Use upstream for decisions and downstream as the review gate.
5
+ taskKinds: [decide, review]
6
+ tools: [Read, Grep, Glob, Bash]
7
+ conventions: [security-code, data-classification, config-secrets, ci-workflows, hexagonal]
8
+ dataAccess: none
9
+ prompt: |
10
+ You are the Security Steward. Data is secured by design, not by review alone.
11
+
12
+ - Every entity and field the change touches is classified pii or non-pii, with an owner
13
+ project and a retention period. Missing classification is a gap.
14
+ - Authentication stays in the port; authorisation lives in the core, with a role per resource
15
+ and verb.
16
+ - Data store access rules start deny-all and every allow has a test.
17
+ - Secrets live in a secret manager; never in flags, argv, config files, logs or images.
18
+ - Errors are general to the caller; details go to the log, never tokens or personal data.
19
+ taskKindNotes:
20
+ review: Review the diff. Return pass=false with findings for anything that breaks a convention.
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "@digital-agora/friday",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.9.0",
4
+ "description": "Friday: the source of truth for AI-assisted SDLC. Compiles YAML personas, workflows and conventions into agent bundles (Claude Code, OpenCode).",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "bin": {
8
+ "friday": "dist/cli.js"
9
+ },
10
+ "files": [
11
+ "dist",
12
+ "schemas",
13
+ "pack",
14
+ "bundles",
15
+ "README.md",
16
+ "LICENSE"
17
+ ],
18
+ "engines": {
19
+ "node": ">=20"
20
+ },
21
+ "publishConfig": {},
22
+ "repository": {
23
+ "type": "git",
24
+ "url": "https://github.com/Digital-Agora/friday.git"
25
+ },
26
+ "scripts": {
27
+ "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
28
+ "typecheck": "tsc -p tsconfig.json --noEmit",
29
+ "test": "vitest run",
30
+ "lint": "node dist/cli.js validate",
31
+ "bundles": "node -e \"require('fs').rmSync('bundles',{recursive:true,force:true})\" && node dist/cli.js bundle --target all --out bundles",
32
+ "prepack": "pnpm build && pnpm bundles",
33
+ "changeset": "changeset",
34
+ "version-packages": "changeset version"
35
+ },
36
+ "dependencies": {
37
+ "ajv": "^8.17.1",
38
+ "commander": "^14.0.0",
39
+ "fflate": "^0.8.2",
40
+ "yaml": "^2.8.1"
41
+ },
42
+ "devDependencies": {
43
+ "@changesets/cli": "^3.0.3",
44
+ "@types/node": "^22.10.0",
45
+ "typescript": "^5.9.0",
46
+ "vitest": "^4.0.0"
47
+ },
48
+ "packageManager": "pnpm@10.28.0"
49
+ }
@@ -0,0 +1,46 @@
1
+ # A convention is a set of rules for one stack or technology. It becomes a path-scoped rule and/or a skill.
2
+ $id: https://friday.digital-agora/schemas/convention.schema.yaml
3
+ title: Convention
4
+ type: object
5
+ additionalProperties: false
6
+ required: [id, stack, description, rules, emit]
7
+ properties:
8
+ id: { type: string, pattern: "^[a-z][a-z0-9-]{1,48}$" }
9
+ stack: { type: string }
10
+ description: { type: string }
11
+ appliesTo:
12
+ type: object
13
+ additionalProperties: false
14
+ required: [paths]
15
+ properties:
16
+ paths:
17
+ type: array
18
+ minItems: 1
19
+ items: { type: string }
20
+ regions:
21
+ description: Runtime -> region. A value may be an object for constrained choices.
22
+ type: object
23
+ layout:
24
+ description: Optional directory tree (text) shown with the rules.
25
+ type: string
26
+ rules:
27
+ type: array
28
+ minItems: 1
29
+ items:
30
+ type: object
31
+ additionalProperties: false
32
+ required: [id, rule]
33
+ properties:
34
+ id: { type: string }
35
+ rule: { type: string }
36
+ why: { type: string }
37
+ source:
38
+ type: string
39
+ description: >-
40
+ Where the rule comes from: <repo>/<path> in a project repository listed in pack.yaml
41
+ sources, an https:// URL for a generic rule (decision 30), or a Friday decision.
42
+ emit:
43
+ type: array
44
+ minItems: 1
45
+ uniqueItems: true
46
+ items: { enum: [rule, skill] }
@@ -0,0 +1,303 @@
1
+ # docs/friday/<workId>/handoff.yaml: the only thing that crosses from upstream to downstream.
2
+ $id: https://friday.digital-agora/schemas/handoff.schema.yaml
3
+ title: Handoff
4
+ type: object
5
+ additionalProperties: false
6
+ required: [workId, status, workflow, scope, decisions, dataClassification, tasks, questions, gaps, openQuestions]
7
+ properties:
8
+ workId: { type: string, pattern: "^[a-z0-9][a-z0-9-]{1,60}$" }
9
+ status: { enum: [awaiting-approval, approved, rejected] }
10
+ workflow: { type: string }
11
+ approvedBy: { type: string }
12
+ scope:
13
+ type: object
14
+ required: [summary, acceptance]
15
+ properties:
16
+ summary: { type: string }
17
+ inScope: { type: array, items: { type: string } }
18
+ outOfScope: { type: array, items: { type: string } }
19
+ acceptance: { type: array, minItems: 1, items: { type: string } }
20
+ scopes:
21
+ description: >-
22
+ The scopes discovery inferred from the request, each with the outcome the user expects.
23
+ An expected outcome is never assumed: it is the user's words from the request or an
24
+ answered question (answerId). With scopes, every task names the scope it delivers.
25
+ type: array
26
+ items:
27
+ type: object
28
+ additionalProperties: false
29
+ required: [id, title, expectedOutcome, outcomeSource]
30
+ properties:
31
+ id: { type: string, pattern: "^[a-z0-9][a-z0-9-]{0,40}$" }
32
+ title: { type: string }
33
+ expectedOutcome: { type: string, minLength: 1, description: What the user expects to be true when this scope is done, in their words. }
34
+ outcomeSource: { enum: [request, answer], description: "request: stated in the request; answer: the user answered a question." }
35
+ answerId: { type: string, description: "With outcomeSource answer: the id of the question that holds the answer." }
36
+ decisions:
37
+ type: array
38
+ items:
39
+ type: object
40
+ required: [id, decision, why]
41
+ properties:
42
+ id: { type: string }
43
+ decision: { type: string }
44
+ why: { type: string }
45
+ where: { type: string }
46
+ contracts:
47
+ description: Architect's contract outcomes per interaction (type and why, errors, audit and logging, owner, consumers, accepted trade-offs).
48
+ type: array
49
+ items:
50
+ type: object
51
+ required: [id, type, owner]
52
+ properties:
53
+ id: { type: string }
54
+ type: { type: string, description: "e.g. read callable, write callable, async action, outbox event, direct read under rules, trigger, cron." }
55
+ why: { type: string }
56
+ owner: { type: string }
57
+ consumers: { type: array, items: { type: string } }
58
+ errors: { type: string }
59
+ audit: { type: string }
60
+ tradeoffs: { type: array, items: { type: string } }
61
+ tasks: { type: array, items: { type: string } }
62
+ standards:
63
+ description: Architect's cross-cutting communication standards (naming, errors, audit, logging, versioning).
64
+ type: array
65
+ items: { type: string }
66
+ plan:
67
+ description: Senior developer's build plan per task (files it may change, test files it owns, ordering forced by shared files).
68
+ type: array
69
+ items:
70
+ type: object
71
+ required: [task]
72
+ properties:
73
+ task: { type: string }
74
+ files: { type: array, items: { type: string } }
75
+ testFiles: { type: array, items: { type: string } }
76
+ after: { type: array, items: { type: string } }
77
+ expectedRed:
78
+ description: Tests left red on purpose between waves, each with its owner task.
79
+ type: array
80
+ items:
81
+ type: object
82
+ required: [test, owner]
83
+ properties:
84
+ test: { type: string }
85
+ owner: { type: string }
86
+ interfaceContracts:
87
+ description: Technical-lead definitions of implementation-facing boundaries for developers.
88
+ type: array
89
+ items:
90
+ type: object
91
+ required: [id, boundary, contract]
92
+ properties:
93
+ id: { type: string }
94
+ boundary: { type: string }
95
+ contract: { type: string }
96
+ consumers: { type: array, items: { type: string } }
97
+ rationale: { type: string }
98
+ testPlan:
99
+ description: QA-authored behavioral scenarios; delivery QA writes the executable tests.
100
+ type: array
101
+ items:
102
+ type: object
103
+ required: [id, taskArea, scenario, expected, level]
104
+ properties:
105
+ id: { type: string }
106
+ taskArea: { type: string }
107
+ scenario: { type: string }
108
+ expected: { type: string }
109
+ level: { type: string }
110
+ dataClassification:
111
+ type: array
112
+ items:
113
+ type: object
114
+ required: [entity, class, owner]
115
+ properties:
116
+ entity: { type: string }
117
+ class: { enum: [pii, non-pii] }
118
+ owner: { type: string }
119
+ retention: { type: string }
120
+ fields: { type: array, items: { type: string } }
121
+ tasks:
122
+ type: array
123
+ minItems: 1
124
+ items:
125
+ type: object
126
+ additionalProperties: false
127
+ required: [id, title, stack, codebase, taskKind, acceptance, dependsOn]
128
+ properties:
129
+ id: { type: string }
130
+ title: { type: string }
131
+ stack: { type: string }
132
+ codebase: { type: string, description: 'Path in the monorepo, e.g. packages/core or services/<name>-api.' }
133
+ scope: { type: string, description: The id of the scope (scope.scopes) this task delivers. }
134
+ taskKind: { enum: [implement, scaffold, adapter] }
135
+ acceptance: { type: array, minItems: 1, items: { type: string } }
136
+ dependsOn: { type: array, items: { type: string } }
137
+ conventions: { type: array, items: { type: string } }
138
+ lowestLevel: { type: string, description: Lowest test pyramid level that proves this task (default unit). }
139
+ covers:
140
+ description: >-
141
+ The scope acceptance criteria this task proves, each as the criterion's id (e.g. AC12)
142
+ or the start of its text. Every scope criterion must be covered by at least one task
143
+ (decision 50).
144
+ type: array
145
+ items: { type: string, minLength: 1 }
146
+ needs:
147
+ description: >-
148
+ Access the task needs beyond the workspace. registry - a dependency or version bump or
149
+ a lockfile change, done as its own task before the tasks that depend on it.
150
+ type: array
151
+ uniqueItems: true
152
+ items: { enum: [registry] }
153
+ breaks:
154
+ description: >-
155
+ Codebases that stop compiling or fail tests once this task lands, because it removes
156
+ or renames a public symbol they use. Needs closedBy.
157
+ type: array
158
+ items: { type: string }
159
+ closedBy:
160
+ description: Ids of the tasks that make the codebases in breaks green again.
161
+ type: array
162
+ items: { type: string }
163
+ prerequisites:
164
+ description: >-
165
+ What must exist before downstream starts (a released package version, a service, a release
166
+ in another repository), each with a check the downstream preflight runs in the agents' own
167
+ environment (decision 48). Any unmet prerequisite makes the handoff not ready.
168
+ type: array
169
+ items:
170
+ type: object
171
+ additionalProperties: false
172
+ required: [id, kind, description, check, status]
173
+ properties:
174
+ id: { type: string }
175
+ kind: { enum: [package, release, service, other] }
176
+ description: { type: string }
177
+ check: { type: string, minLength: 1, description: 'A command or a verifiable statement, e.g. "pnpm view @acme/x-contract@1.4.0 version".' }
178
+ status: { enum: [met, unmet] }
179
+ questions:
180
+ description: Every question asked upstream, with the user's answer.
181
+ type: array
182
+ items:
183
+ type: object
184
+ required: [id, question, answer]
185
+ properties:
186
+ id: { type: string }
187
+ question: { type: string }
188
+ answer: { type: string, description: "The user's words, verbatim." }
189
+ interpretation: { type: string, description: "How the orchestrator read the answer, kept apart from the user's words." }
190
+ gaps:
191
+ type: array
192
+ items:
193
+ type: object
194
+ required: [id, area, gap, why, impact, solutions, recommended, resolution]
195
+ properties:
196
+ id: { type: string }
197
+ area: { enum: [scope, architecture, security, data, testing, ops, conventions] }
198
+ gap: { type: string }
199
+ why: { type: string }
200
+ impact: { enum: [low, medium, high] }
201
+ solutions:
202
+ type: array
203
+ minItems: 1
204
+ items:
205
+ type: object
206
+ required: [option, tradeoff]
207
+ properties:
208
+ option: { type: string }
209
+ tradeoff: { type: string }
210
+ recommended: { type: integer, minimum: 0 }
211
+ resolution: { type: string, minLength: 1 }
212
+ commands:
213
+ description: >-
214
+ The target repository's command map: test pyramid level id -> the commands this repository
215
+ runs for it (its package manager and script names, e.g. npm run test:architecture). Task
216
+ loops and integration run these instead of the pack defaults.
217
+ type: object
218
+ additionalProperties: { type: array, items: { type: string } }
219
+ git:
220
+ description: >-
221
+ How the git step finishes. Defaults (the pack has no "no PR unless asked" convention):
222
+ pr true, draft false, linkHandoff true. args.git overrides it. The handoff is linked only
223
+ when it is committed on the pushed branch.
224
+ type: object
225
+ additionalProperties: false
226
+ properties:
227
+ pr: { type: boolean, description: Open a pull request (false - push the branch only). }
228
+ draft: { type: boolean, description: Open the pull request as a draft. }
229
+ linkHandoff: { type: boolean, description: Link docs/friday/<workId>/handoff.yaml in the PR body. }
230
+ deliveryPolicy:
231
+ description: >-
232
+ What delivery may settle itself, without going back upstream. Each decision is recorded and
233
+ shown to the user at the end of the run. Product behaviour, user-facing copy and anything that
234
+ widens security or data access are never on it.
235
+ type: object
236
+ additionalProperties: false
237
+ properties:
238
+ maySettle:
239
+ type: array
240
+ items: { enum: [test-fixture, lint-suppression, repo-fact-exception, command-mapping] }
241
+ notes: { type: string, description: "Limits, e.g. the named repo facts an exception may cover." }
242
+ briefs:
243
+ description: >-
244
+ One task brief per task (decision 40): the prompt the task's agents receive, written by the
245
+ prompt engineer from what the handoff holds and approved with it. Delivery passes it next to
246
+ the handoff (or its slice); anything it does not settle is still needs-upstream.
247
+ type: array
248
+ items:
249
+ type: object
250
+ additionalProperties: false
251
+ required: [task, text]
252
+ properties:
253
+ task: { type: string }
254
+ text: { type: string, minLength: 1 }
255
+ contracts: { type: array, items: { type: string } }
256
+ interfaces: { type: array, items: { type: string } }
257
+ decisions: { type: array, items: { type: string } }
258
+ files: { type: array, items: { type: string } }
259
+ testFiles: { type: array, items: { type: string } }
260
+ checkpoints:
261
+ description: >-
262
+ The checkpoints the upstream run had approved (decision 39), e.g. the request brief, each with
263
+ the role that approved it (never a person's name), what was approved and the file holding it.
264
+ type: array
265
+ items:
266
+ type: object
267
+ additionalProperties: false
268
+ required: [id, approvedBy, summary, file]
269
+ properties:
270
+ id: { type: string }
271
+ approvedBy: { type: string, pattern: "^[a-z][a-z0-9-]*$" }
272
+ summary: { type: string, minLength: 1 }
273
+ file:
274
+ type: string
275
+ pattern: "^docs/friday/[a-z0-9][a-z0-9-]*/[a-z][a-z0-9-]*\\.md$"
276
+ description: docs/friday/<workId>/<checkpoint>.md, the approved result in full.
277
+ promptPyramid:
278
+ description: >-
279
+ The prompt pyramid levels the upstream run had approved, bottom first (decision 33), each
280
+ with the role that approved it (never a person's name) and what was approved.
281
+ type: object
282
+ additionalProperties: false
283
+ required: [levels]
284
+ properties:
285
+ levels:
286
+ type: array
287
+ minItems: 1
288
+ items:
289
+ type: object
290
+ additionalProperties: false
291
+ required: [id, approvedBy, summary, file]
292
+ properties:
293
+ id: { type: string }
294
+ file:
295
+ type: string
296
+ pattern: "^docs/friday/[a-z0-9][a-z0-9-]*/prompt/[a-z][a-z0-9-]*\\.md$"
297
+ description: docs/friday/<workId>/prompt/<level>.md, the approved result in full, exactly as the person read it.
298
+ approvedBy: { type: string, pattern: "^[a-z][a-z0-9-]*$", description: The approver role from promptPyramid, e.g. product-owner. }
299
+ summary: { type: string, minLength: 1, description: What the person approved at this level. }
300
+ openQuestions:
301
+ description: Must be empty for downstream to start.
302
+ type: array
303
+ maxItems: 0