@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,28 @@
1
+ id: git
2
+ stack: git
3
+ description: Branch, commit and pull request conventions the git steward applies.
4
+ emit: [skill]
5
+ rules:
6
+ - id: branch
7
+ rule: "Branch <type>/<work-id>-<slug>, type one of feat, fix, chore, docs, refactor, test, ci, build, perf. Never commit straight to main."
8
+ source: https://www.conventionalcommits.org/en/v1.0.0/
9
+ - id: commit-subject
10
+ rule: "Conventional Commits: <type>(<scope>): <imperative summary>, at most 72 characters, scope is the codebase the change touches."
11
+ source: https://www.conventionalcommits.org/en/v1.0.0/
12
+ - id: commit-body
13
+ rule: The body says why, not what; it cites the decision number ("decision 7") or the handoff work id. One logical change per commit.
14
+ source: https://www.conventionalcommits.org/en/v1.0.0/
15
+ - id: trailer
16
+ rule: An agent's commit ends with a Co-Authored-By trailer. No model names in commits, code or PR text.
17
+ why: The trailer marks agent work; a model name ages badly and says nothing about the change.
18
+ - id: pr-body
19
+ rule: "The PR body follows the repository's pull request template; without one: What and why (link the handoff and decisions), How it was tested (the commands run)."
20
+ source: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository
21
+ - id: changeset
22
+ rule: Every PR carries a changeset per the changesets convention (empty when nothing user-facing changes).
23
+ source: decision 16 (friday docs/decisions.md)
24
+ - id: pr-title
25
+ rule: The PR title is the Conventional Commit subject of the change as a whole.
26
+ - id: history
27
+ rule: Never rewrite history on someone else's branch, never force-push a shared branch, never push red work.
28
+ source: https://git-scm.com/docs/git-push
@@ -0,0 +1,31 @@
1
+ id: hexagonal
2
+ stack: typescript
3
+ description: One core, many ports. Business logic and the data it owns are written once in the core; every entry point is a port onto it.
4
+ appliesTo:
5
+ paths: ["src/**", "packages/**"]
6
+ emit: [rule, skill]
7
+ rules:
8
+ - id: layers
9
+ rule: "The domain imports nothing outside the domain; ports import the domain; the application (use cases) imports domain and ports; adapters import the core and their SDK; entry points import the core and the adapters they wire."
10
+ source: https://alistair.cockburn.us/hexagonal-architecture/
11
+ - id: inward
12
+ rule: The core imports no SDK, framework, transport or adapter package; it does no I/O and reads no environment.
13
+ source: https://alistair.cockburn.us/hexagonal-architecture/
14
+ - id: composition-root
15
+ rule: Each entry point constructs its adapters once and passes them to the use cases. That is the only place a client of an external system is created.
16
+ source: https://alistair.cockburn.us/hexagonal-architecture/
17
+ - id: result
18
+ rule: "A use case returns { ok: true, value } | { ok: false, error: 'not-found' | 'forbidden' | ... }; each port maps it (HTTP status, tool result, error type)."
19
+ why: Errors the core expects are values; each port decides how its callers see them.
20
+ - id: authn-authz
21
+ rule: Authentication stays in the port, which builds a Caller (subject, roles). Authorisation lives in the core, checking roles per resource and verb.
22
+ source: https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
23
+ - id: one-owner
24
+ rule: One port per data store, owned by one project. Another project reads it through this project's API, never its store.
25
+ source: https://alistair.cockburn.us/hexagonal-architecture/
26
+ - id: same-use-cases
27
+ rule: Every entry point of a project exposes the same use cases. When one needs something new, add the use case to the core and expose it from each.
28
+ source: https://alistair.cockburn.us/hexagonal-architecture/
29
+ - id: gate
30
+ rule: An architecture check enforces the layers in CI. Prove every new rule by breaking it once.
31
+ why: A layer rule nobody checks erodes with the first shortcut.
@@ -0,0 +1,17 @@
1
+ id: security-code
2
+ stack: security
3
+ description: Security rules for code, logs and errors.
4
+ emit: [rule, skill]
5
+ rules:
6
+ - id: credentials
7
+ rule: Credentials are never flags, never printed, never in argv (curl -H @- with the token on stdin).
8
+ source: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
9
+ - id: errors
10
+ rule: Error messages stay general; a caller can't tell "no such thing" from "not yours". Details go to the log.
11
+ source: https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html
12
+ - id: logs
13
+ rule: Audit and log lines never carry tokens, tool arguments or results.
14
+ source: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
15
+ - id: personal-data
16
+ rule: Personal data stays in the project that owns it; share reads through a personal-data-safe use case.
17
+ source: https://eur-lex.europa.eu/eli/reg/2016/679/oj
@@ -0,0 +1,44 @@
1
+ id: testing
2
+ stack: testing
3
+ description: Test layers, tools and rules.
4
+ appliesTo:
5
+ paths: ["**/*.test.*", "**/*.spec.*", "e2e/**", "**/vitest.config.*", "**/playwright.config.*"]
6
+ emit: [rule, skill]
7
+ rules:
8
+ - id: layers
9
+ rule: "Unit tests cover the core and the entry points with in-memory adapters for the ports; integration tests run the adapters against local emulators or containers; e2e tests drive the built app. Each level has one command per package."
10
+ source: https://martinfowler.com/articles/practical-test-pyramid.html
11
+ - id: no-network
12
+ rule: Tests never touch the network or a real environment. Anything that shells out or fetches goes through one function the tests replace.
13
+ source: https://martinfowler.com/articles/practical-test-pyramid.html
14
+ - id: fake-seed
15
+ rule: Seed data is fake and committed (dummy names, @example.com). Never a copy of real data.
16
+ source: https://eur-lex.europa.eu/eli/reg/2016/679/oj
17
+ - id: tdd
18
+ rule: The QA engineer writes the failing test first; the implementer makes it pass without weakening it.
19
+ why: Friday pairs every engineer with QA.
20
+ - id: single-file
21
+ rule: "Run a task's tests by file through the package's test runner: `pnpm --filter <package> exec <test runner> <files>` (vitest run, jest, node --test). A package script with `-- <files>` (`pnpm --filter <package> test -- <files>`) may ignore the files and run the whole suite, so it never scopes a task loop."
22
+ why: Four agents in one delivery found on their own that the `test -- <files>` form ignored the file list.
23
+ source: decision 49 (friday docs/decisions.md)
24
+ - id: typecheck-package
25
+ rule: Typecheck one package with `pnpm --filter <package> typecheck`; task loops never typecheck the whole workspace.
26
+ source: decision 49 (friday docs/decisions.md)
27
+ - id: bootstrap
28
+ rule: A downstream run installs the workspace once, in its preflight step, from the lockfile (offline when the store allows) and resolves every prerequisite and version pin there. Later steps reuse that install and never install online; a missing package is a blocker that goes back upstream.
29
+ why: Every agent installing on its own cost time, and a pin the agents could not install was found only halfway through a run.
30
+ source: decision 48 (friday docs/decisions.md)
31
+ - id: lowest-level
32
+ rule: One test per acceptance criterion, at the lowest pyramid level that can prove it. A higher level only for what a lower one cannot prove; never the same criterion at every level. A task loop runs only its tests' levels within the loop's scope, plus the static checks.
33
+ source: https://martinfowler.com/articles/practical-test-pyramid.html
34
+ - id: test-changes
35
+ rule: A test is never changed to let the code pass. The implementer changes the code, not the test; a conflict goes to the QA engineer, who keeps the test unless it is wrong (it asserts more or other than the criterion, or contradicts a repository fact the criterion does not change) and then names the criterion and why. A change without that justification goes back upstream.
36
+ source: decision 47 (friday docs/decisions.md)
37
+ - id: pyramid-in-loops
38
+ rule: "Task loops (TDD pairs, gate fixes) run only the bottom of the pyramid: static checks and the unit tests of the package and files the task touches. Never an emulator, integration or e2e suite in a task loop."
39
+ why: Those suites are slow; running them per small task multiplies CI time. The integration loop runs them once at the end and turns each failure into a follow-up task.
40
+ - id: integration-followups
41
+ rule: Integration wires and runs the full pyramid but fixes nothing. Each failure becomes a follow-up task with the lowest level that reproduces it, which goes back through the task loop before integration runs again.
42
+ - id: evidence
43
+ rule: "A green claim names each command that ran and its exit code; an agent saying a suite passed is not evidence. A loop ends on a passing command per level in scope, on its round budget, or on a blocker sent upstream; never on \"keep trying until it works\"."
44
+ source: https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/core/loop-graph-engineering.md
@@ -0,0 +1,16 @@
1
+ id: typescript-node
2
+ stack: typescript
3
+ description: TypeScript and Node settings shared by every package.
4
+ appliesTo:
5
+ paths: ["**/*.ts", "**/*.tsx", "**/package.json", "**/tsconfig*.json"]
6
+ emit: [rule, skill]
7
+ rules:
8
+ - id: tsconfig
9
+ rule: Every package extends one shared tsconfig with strict on (and noUncheckedIndexedAccess). Do not loosen it per package.
10
+ source: https://www.typescriptlang.org/tsconfig/#strict
11
+ - id: tooling
12
+ rule: One package manager per repository with a committed lockfile; root scripts build, test, typecheck and lint every package.
13
+ source: https://pnpm.io/workspaces
14
+ - id: pins
15
+ rule: CLIs used by builds are dev dependencies pinned by the lockfile, never installed globally in a build step.
16
+ source: https://pnpm.io/workspaces
@@ -0,0 +1,80 @@
1
+ # One place decides which model runs which kind of work.
2
+ # Implementing is bound to haiku; writing classes and preparing adapters to sonnet;
3
+ # decisions, integration and product prompts to opus. `friday validate` refuses a step that breaks this
4
+ # without an `override.reason` (enforce: strict).
5
+ enforce: strict
6
+ taskKinds:
7
+ implement:
8
+ model: haiku
9
+ effort: medium
10
+ why: Make an existing failing test pass, or apply a fully specified change.
11
+ contract: Change only what the failing test or the spec needs. No new design decisions; if one is needed, return blocked with the question.
12
+ verify:
13
+ model: haiku
14
+ effort: low
15
+ why: Run the checks and report the result, nothing more.
16
+ contract: Run the listed commands and report exactly what they printed. Do not edit code.
17
+ git:
18
+ model: haiku
19
+ effort: low
20
+ why: Branches, commits and PRs are mechanical once the conventions are fixed.
21
+ contract: Follow the `git` convention exactly. Never push to main, never rewrite someone else's history, never force-push.
22
+ scaffold:
23
+ model: sonnet
24
+ effort: high
25
+ why: Write classes, types, ports and use-case skeletons.
26
+ contract: Write the structure (types, interfaces, classes, ports) the task asks for, respecting the hexagonal layers. Leave behaviour to the TDD pair.
27
+ adapter:
28
+ model: sonnet
29
+ effort: medium
30
+ why: Prepare adapters against existing ports.
31
+ contract: Implement a port with its SDK in packages/adapter-*, with its integration test against the emulators. The core does not change.
32
+ test-design:
33
+ model: sonnet
34
+ effort: high
35
+ why: QA designs and writes the failing tests first.
36
+ contract: Write tests that fail for the right reason before any implementation. Cover the acceptance criteria and the permission rules.
37
+ test-plan:
38
+ model: sonnet
39
+ effort: high
40
+ why: QA turns agreed acceptance criteria into implementation-independent test scenarios.
41
+ contract: Define scenarios and expected outcomes; do not write or run executable tests.
42
+ analysis:
43
+ model: sonnet
44
+ effort: medium
45
+ why: Data analysis on classified data.
46
+ contract: State the data class of every input. Output aggregates; never raw personal data.
47
+ decide:
48
+ model: opus
49
+ effort: high
50
+ why: Architecture, security, data classification and task breakdown decisions.
51
+ contract: Every decision has a why and a place in docs/decisions.md. Present options with trade-offs; ask when the choice is the user's.
52
+ integrate:
53
+ model: opus
54
+ effort: high
55
+ why: Wire composition roots and integrate across codebases.
56
+ contract: Wire adapters in the composition roots, run the full check list, and fix integration failures without weakening a test.
57
+ prompt-design:
58
+ model: opus
59
+ effort: high
60
+ why: Write the prompt of a product's LLM feature; the prompt carries the feature's behaviour (decisions 31, 37).
61
+ contract: Write the system prompt and pick the examples from the approved levels below them (success criteria, evals, context), at the right altitude and in sections. Examples are few, canonical and synthetic or pseudonymised, never real personal data. Never run, score or change the evals; a criterion the prompt cannot meet is a question, not a quiet edit.
62
+ brief:
63
+ model: sonnet
64
+ effort: high
65
+ why: Structure a request or a handoff into the prompt the next stage needs; it cites and structures, it does not decide (decision 39).
66
+ contract: Turn what you are given into the brief the next stage reads. Every field cites its source (request, repository with the file, answer id, convention id) or is a proposal. Never invent a field; what you would have to guess is a proposal or a question. Edit no file.
67
+ review:
68
+ model: opus
69
+ effort: high
70
+ why: Security and final review gates.
71
+ contract: Review against the conventions. Each finding has severity, file, issue and fix. pass is false if any high finding remains.
72
+ targets:
73
+ claude:
74
+ haiku: haiku
75
+ sonnet: sonnet
76
+ opus: opus
77
+ opencode:
78
+ haiku: anthropic/claude-haiku-5-5
79
+ sonnet: anthropic/claude-sonnet-5-5
80
+ opus: anthropic/claude-opus-5-5
@@ -0,0 +1,52 @@
1
+ # Upstream. A structural or technology decision, ending in a handoff whose tasks apply it.
2
+ id: architecture-decision
3
+ description: Decide codebases, technologies or libraries with the architect and security steward, close every gap and hand off the tasks that apply the decision.
4
+ stream: upstream
5
+ orchestrator: architect
6
+ inputs:
7
+ workId: { description: "Short id, e.g. adr-move-forms-api-to-run", required: true }
8
+ request: { description: The decision to make and its context, required: true }
9
+ glossary: { description: "Optional. Domain words and what they mean here (term -> meaning), shown to every step." }
10
+ environmentFacts: { description: "Optional. Facts the orchestrator verified (registry access, emulators, tools), shown to every step." }
11
+ answersFile: { description: "Optional. Path to answers.yaml; agents read the answers there and only answeredIds/resolvedIds travel inline." }
12
+ # Every finished run ends in a retro: docs/friday/<workId>/retro.md and proposed Friday improvements.
13
+ retro: { persona: architect, taskKind: decide }
14
+ steps:
15
+ - id: frame
16
+ type: clarify
17
+ persona: architect
18
+ taskKind: decide
19
+ topic: The decision to make, its constraints, the options already considered and who is affected.
20
+ - id: options
21
+ type: parallel
22
+ steps:
23
+ - id: architecture-options
24
+ type: clarify
25
+ persona: architect
26
+ taskKind: decide
27
+ topic: Options with trade-offs, the recommended one, and the docs/decisions.md entry. Put decisions in result.decisions.
28
+ - id: security-options
29
+ type: clarify
30
+ persona: security-steward
31
+ taskKind: decide
32
+ topic: Security and data consequences of each option. Put the classification in result.dataClassification.
33
+ - id: privacy-options
34
+ type: clarify
35
+ persona: data-analyst-pii
36
+ taskKind: analysis
37
+ topic: Personal-information consequences of each option (what personal data moves, where, for how long, who reads it). Report every gap.
38
+ - id: gaps
39
+ type: gap-analysis
40
+ persona: architect
41
+ taskKind: decide
42
+ rerunUntil: no-open-gaps
43
+ - id: breakdown
44
+ type: agent
45
+ persona: lead-developer
46
+ taskKind: decide
47
+ output: tasks
48
+ prompt: Break the chosen option into tasks (stack, codebase, taskKind, acceptance, dependsOn), including the docs/decisions.md entry as a devops implement task.
49
+ - id: handoff
50
+ type: handoff
51
+ persona: architect
52
+ taskKind: decide
@@ -0,0 +1,67 @@
1
+ # Downstream. A bug fix from an approved handoff: reproduce with a red test, fix, review, PR.
2
+ id: bugfix-tdd
3
+ description: Fix a bug from an approved handoff - QA reproduces it with a failing test, the engineer fixes it, security reviews, the git steward opens the PR.
4
+ stream: downstream
5
+ orchestrator: lead-developer
6
+ requires: [handoff]
7
+ # Every finished run ends in a retro: docs/friday/<workId>/retro.md and proposed Friday improvements.
8
+ retro: { persona: lead-developer, taskKind: decide }
9
+ steps:
10
+ # Install the workspace once and resolve every prerequisite and version pin where the agents
11
+ # run; anything that cannot be resolved goes back upstream before anything is built (decision 48).
12
+ - id: preflight
13
+ type: preflight
14
+ persona: qa-engineer
15
+ taskKind: verify
16
+ - id: fix
17
+ type: foreach
18
+ over: handoff.tasks
19
+ order: dependsOn
20
+ steps:
21
+ - id: tdd
22
+ type: tdd-pair
23
+ test: { persona: qa-engineer, taskKind: test-design }
24
+ impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
25
+ verify: { persona: qa-engineer, taskKind: verify }
26
+ # The task loop stays at the bottom of the pyramid; integration runs the rest.
27
+ testScope: [static, unit]
28
+ maxRounds: 3
29
+ # Wire every stack, run the whole pyramid once, and turn each failure into a follow-up task
30
+ # that goes back through the bottom-of-pyramid loop. Repeats until green or maxRounds.
31
+ - id: integrate
32
+ type: integration-loop
33
+ integrate: { persona: "{{stack}}", taskKind: integrate }
34
+ testScope: [static, unit, integration, e2e]
35
+ maxRounds: 2
36
+ followup:
37
+ - id: followup-tdd
38
+ type: tdd-pair
39
+ test: { persona: qa-engineer, taskKind: test-design }
40
+ impl: { persona: "{{stack}}", taskKind: "{{task.taskKind}}", allowedTaskKinds: [implement, scaffold, adapter] }
41
+ verify: { persona: qa-engineer, taskKind: verify }
42
+ # The task loop stays at the bottom of the pyramid; integration runs the rest.
43
+ testScope: [static, unit]
44
+ maxRounds: 3
45
+ # Data safety is shared: the PII analyst checks personal information, then the security
46
+ # steward checks the controls. Only when the handoff holds pii.
47
+ - id: privacy-review
48
+ type: gate
49
+ when: pii
50
+ persona: data-analyst-pii
51
+ taskKind: analysis
52
+ 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.
53
+ maxLoops: 2
54
+ onFail: { persona: backend-engineer, taskKind: integrate }
55
+ - id: security-review
56
+ type: gate
57
+ persona: security-steward
58
+ taskKind: review
59
+ prompt: Review the fix and its regression test against the security conventions.
60
+ maxLoops: 1
61
+ onFail: { persona: backend-engineer, taskKind: integrate }
62
+ - id: pr
63
+ type: agent
64
+ persona: git-steward
65
+ taskKind: git
66
+ output: git
67
+ prompt: "Commit as fix(<scope>): ... following the `git` convention, add a patch changeset, push and open the PR with the template sections."
@@ -0,0 +1,23 @@
1
+ # Downstream. Runs an analysis the handoff scoped and classified. The analyst is chosen by the
2
+ # handoff's data classification: any pii entity -> data-analyst-pii plus a security gate.
3
+ id: data-analysis
4
+ description: Run a scoped, classified analysis with the PII or non-PII analyst (chosen from the handoff), with a security review on the PII path.
5
+ stream: downstream
6
+ orchestrator: lead-developer
7
+ requires: [handoff]
8
+ # Every finished run ends in a retro: docs/friday/<workId>/retro.md and proposed Friday improvements.
9
+ retro: { persona: lead-developer, taskKind: decide }
10
+ steps:
11
+ - id: analyse
12
+ type: agent
13
+ persona: "{{analyst}}"
14
+ taskKind: analysis
15
+ prompt: Run the analysis described by the handoff scope and tasks. Report data sources, filters, commands and results (aggregates only for pii).
16
+ - id: pii-review
17
+ type: gate
18
+ when: pii
19
+ persona: security-steward
20
+ taskKind: review
21
+ prompt: Check the analysis output and any files written contain no personal data and respect the handoff's retention and minimum group size.
22
+ maxLoops: 1
23
+ onFail: { persona: data-analyst-pii, taskKind: analysis }
@@ -0,0 +1,204 @@
1
+ # Upstream. Turns a request into an approved handoff. The only place questions are asked.
2
+ # The driver loops: run -> ask the user every open question/assumption/gap -> re-run with the
3
+ # answers -> ... until nothing is open, then shows the gap summary and asks for approval.
4
+ # maxRounds bounds that loop: after the last round the user freezes the scope (anything still
5
+ # open is deferred to a follow-up work item) or explicitly allows more rounds.
6
+ # The gap steps consolidate: they turn every open item of the round into one list (duplicates
7
+ # merged, settled or non-blocking items dropped with a reason) and report contradictions, which
8
+ # the user resolves; the clarify agents' raw questions never reach the user directly.
9
+ id: discovery
10
+ description: Clarify a request, get architecture, security and data decisions, close every gap, break the work into tasks and write the handoff.
11
+ stream: upstream
12
+ orchestrator: lead-developer
13
+ # Compiled to a skill, not a workflow script: the session runs the steps itself, each with the
14
+ # agent it names, and measures the work first so a small request is not fanned out to every agent
15
+ # at once. outputs: [workflow, skill] would add the script and hand large runs to it.
16
+ outputs: [skill]
17
+ sizing:
18
+ signals:
19
+ - a codebase, app, functions codebase or package the request changes or adds
20
+ - an entity or field that holds or identifies a person
21
+ - an interaction added or changed (callable, event, trigger, cron, async action, read model, rule)
22
+ - an acceptance criterion the request states or implies
23
+ - an external service or another work item the change depends on
24
+ # Below 4 points one agent runs at a time; from 4 the perspectives run in parallel; from 10
25
+ # each parallel group runs as a small workflow of at most 6 agents.
26
+ medium: 4
27
+ large: 10
28
+ maxAgentsPerWorkflow: 6
29
+ maxRounds: 5
30
+ deferNonBlocking: true
31
+ # A real run returned 30-60 items a round, the same subject asked by 3-5 perspectives. Items are
32
+ # merged by topic and at most this many blocking items are shown per round.
33
+ maxItemsPerRound: 15
34
+ inputs:
35
+ workId: { description: "Short id for the work, e.g. athlete-export-csv", required: true }
36
+ request: { description: The request as the user stated it, required: true }
37
+ glossary: { description: "Optional. Domain words and what they mean here (term -> meaning), shown to every step." }
38
+ environmentFacts: { description: "Optional. Facts the orchestrator verified (registry access, emulators, tools), shown to every step." }
39
+ answersFile: { description: "Optional. Path to answers.yaml; agents read the answers there and only answeredIds/resolvedIds travel inline." }
40
+ # Every finished run ends in a retro: docs/friday/<workId>/retro.md and proposed Friday improvements.
41
+ retro: { persona: lead-developer, taskKind: decide }
42
+ steps:
43
+ # The request brief (decision 39): the prompt engineer structures the request, citing every
44
+ # field's source, and the requester approves it before any perspective asks a question.
45
+ - id: brief
46
+ type: agent
47
+ checkpoint: brief
48
+ persona: prompt-engineer
49
+ taskKind: brief
50
+ prompt: >-
51
+ Turn the request into the request brief, the structured prompt every later step starts from.
52
+ Fields: goal (the outcome the user wants, in their words), who it is for and where it shows
53
+ up, today (the current behaviour, from the repository with the files, or unknown), wanted
54
+ (the behaviour after the change), constraints (the conventions and earlier decisions that
55
+ apply, by id), acceptance (only what the request states), out of scope (only what the request
56
+ or an answer excludes), facts checked (what you verified in the repository, with the file, so
57
+ no later step asks about it) and unknowns. Every field names its source: request,
58
+ repository (file), answer (id), convention (id) or proposed. Never invent one; what you would
59
+ have to guess is a proposal or a question. Put it in result.brief.
60
+ - id: approve-brief
61
+ type: approval
62
+ checkpoint: brief
63
+ - id: scope
64
+ type: clarify
65
+ persona: lead-developer
66
+ taskKind: decide
67
+ topic: >-
68
+ Start from the approved request brief (step brief). Scope: who it is for, what changes, what is explicitly out of scope, the acceptance
69
+ criteria, which project(s) own the data and code, deadlines, environments. Infer the
70
+ scopes the request covers: one per result a user would accept or reject on its own (a
71
+ capability, a surface, a data flow), each with a short kebab-case id. Every scope needs
72
+ the outcome the user expects when it is done, in the user's words. Take it from the
73
+ request only where the request states it (outcomeSource: request); otherwise it is a
74
+ blocking question to the user with 2-4 concrete outcomes as options (outcomeSource:
75
+ answer, answerId: the question id). Never assume an outcome or derive it from the scope's
76
+ title. Put them in result.scopes as { id, title, expectedOutcome, outcomeSource, answerId };
77
+ a split you are unsure of is an assumption.
78
+ - id: perspectives
79
+ type: parallel
80
+ steps:
81
+ - id: architecture
82
+ type: clarify
83
+ persona: architect
84
+ taskKind: decide
85
+ topic: >-
86
+ Which apps, functions codebases, services and packages change or are added; libraries;
87
+ region; the hosting choice; the decisions to record. Put decisions in result.decisions.
88
+ - id: security
89
+ type: clarify
90
+ persona: security-steward
91
+ taskKind: decide
92
+ topic: >-
93
+ Data classification of every entity and field (pii / non-pii, owner, retention),
94
+ authentication per port, authorisation roles, rules, secrets. Put the classification in
95
+ result.dataClassification and decisions in result.decisions.
96
+ - id: privacy
97
+ type: clarify
98
+ persona: data-analyst-pii
99
+ taskKind: analysis
100
+ topic: >-
101
+ Personal information: every entity and field that holds or identifies a person, its
102
+ purpose, owner, retention, who may read it, minimisation, and whether exports, logs,
103
+ prompts or seeds could carry it. Report every gap; agree the classification with the
104
+ security step (put yours in result.dataClassification).
105
+ - id: solution-fit
106
+ type: agent
107
+ persona: architect
108
+ taskKind: decide
109
+ prompt: >-
110
+ Compare viable solution approaches against the request, repository conventions, and earlier
111
+ decisions. For each option, explain benefits, costs, risks, and what it trades away; recommend
112
+ the best fit and explain why. Put the comparison in result.solutionOptions and the
113
+ recommendation in result.recommendedApproach. Then fix the contract outcomes and the
114
+ communication standards of the recommended approach: for every interaction (callable, event,
115
+ trigger, cron, async action, read model, rule), its type and why (read or write callable,
116
+ fire-and-forget async action, outbox event, direct read under rules), its error outcomes, its
117
+ audit and logging standard, its owner context and consumers, and the trade-offs it accepts.
118
+ Put them in result.contracts and the cross-cutting rules (naming, errors, audit, logging,
119
+ versioning) in result.standards. A trade-off the user has not accepted is a question with
120
+ options, never a silent choice. Ask only a question that blocks a safe, testable plan; mark
121
+ non-blocking details blocking: false.
122
+ - id: interface-contracts
123
+ type: agent
124
+ persona: lead-developer
125
+ taskKind: decide
126
+ prompt: >-
127
+ Act as the technical lead. Define the implementation-facing interfaces and boundaries needed
128
+ by the recommended approach: names, responsibilities, inputs/outputs, provider/consumer
129
+ relationships, and compatibility constraints. Specify contracts, not concrete adapter or
130
+ feature implementations, following the architect's result.contracts and result.standards. Put
131
+ them in result.interfaceContracts, each with its owner context and the work ids or contexts
132
+ that consume it; an interface another work item already owns is referenced, not redefined.
133
+ Use repository conventions and architecture decisions; ask only about an unresolved blocker.
134
+ - id: test-plan
135
+ type: agent
136
+ persona: qa-engineer
137
+ taskKind: test-plan
138
+ prompt: >-
139
+ Create a concise, implementation-independent test plan from the request, decisions,
140
+ recommended approach and interface contracts. Put behavioral scenarios in result.testPlan,
141
+ each with an id, task area, scenario, expected outcome and lowest useful test level. Cover
142
+ acceptance criteria, permissions and important failure cases. Do not write or run code or
143
+ executable tests; QA writes the failing tests during delivery. Ask only about a blocker.
144
+ - id: gaps
145
+ title: gaps and contradictions
146
+ type: gap-analysis
147
+ persona: lead-developer
148
+ taskKind: decide
149
+ rerunUntil: no-open-gaps
150
+ consolidate: true
151
+ - id: breakdown
152
+ type: agent
153
+ persona: lead-developer
154
+ taskKind: decide
155
+ output: tasks
156
+ prompt: >-
157
+ Break the agreed scope into tasks using the architecture and security results. Each task:
158
+ id, title, scope (the id of the scope it delivers; every scope's expected outcome is met by
159
+ the acceptance criteria of its tasks, and a scope no task meets is a gap), stack
160
+ (frontend|backend|devops), codebase path, taskKind (scaffold for classes,
161
+ types and ports; adapter for port implementations; implement for behaviour), acceptance
162
+ criteria, dependsOn, conventions. Use the recommended approach, interface contracts and test
163
+ scenarios above. The technical lead owns the contracts; create scaffold tasks for developers
164
+ to implement those contracts before adapter and behavior tasks. Link test scenarios to the
165
+ relevant task acceptance criteria. Scaffold before adapter before implement.
166
+ - id: build-plan
167
+ type: agent
168
+ persona: backend-engineer
169
+ taskKind: integrate
170
+ prompt: >-
171
+ As the senior developer, check that the breakdown can be built in parallel without tasks
172
+ stepping on each other. For every task, give the files it may create or change and the test
173
+ files it owns (each on a path that contains its task id); name every file two tasks would
174
+ share and the ordering that keeps one writer at a time; name each dependency on another work
175
+ item's task as <workId>:<taskId>; and list the red tests each wave will leave on purpose,
176
+ each with its owner task. Put it in result.plan and result.expectedRed. A task whose files or
177
+ order cannot be made safe is a gap with options, not a silent change to the breakdown.
178
+ # Task briefs (decision 40): the prompt each task's agents receive, written from what this run
179
+ # settled and approved with the handoff.
180
+ - id: task-briefs
181
+ type: agent
182
+ persona: prompt-engineer
183
+ taskKind: brief
184
+ output: briefs
185
+ prompt: >-
186
+ For every task in the breakdown, write its task brief: the prompt its agents receive, the
187
+ smallest set they need. In Markdown sections: the task and its acceptance criteria and scope;
188
+ the contracts and interfaces it consumes, by id; the files it may change and the test files it
189
+ owns, from the build plan; the decisions, conventions and data class that apply to its
190
+ codebase; what it must not touch (frozen interfaces, approved prompt files, other tasks'
191
+ files); the commands of its test scope. List the ids and paths you name in the brief's
192
+ contracts, interfaces, decisions, files and testFiles. Add nothing the breakdown, the plan or
193
+ the decisions do not hold; a task you cannot brief from them is a gap. Put them in
194
+ result.briefs, one per task.
195
+ - id: final-gaps
196
+ type: gap-analysis
197
+ persona: security-steward
198
+ taskKind: review
199
+ rerunUntil: no-open-gaps
200
+ consolidate: true
201
+ - id: handoff
202
+ type: handoff
203
+ persona: lead-developer
204
+ taskKind: decide