@digital-agora/friday 0.0.0-stage → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +275 -2
- package/bundles/friday-claude-0.1.0.zip +0 -0
- package/bundles/friday-opencode-0.1.0.zip +0 -0
- package/dist/adapters/adapter.js +6 -0
- package/dist/adapters/claude/guards.js +40 -0
- package/dist/adapters/claude/index.js +161 -0
- package/dist/adapters/claude/runtime.js +645 -0
- package/dist/adapters/claude/workflows.js +323 -0
- package/dist/adapters/drivers.js +294 -0
- package/dist/adapters/index.js +16 -0
- package/dist/adapters/opencode/index.js +232 -0
- package/dist/adapters/skill.js +327 -0
- package/dist/build.js +77 -0
- package/dist/cli.js +197 -0
- package/dist/frontmatter.js +16 -0
- package/dist/graph.js +218 -0
- package/dist/handoff.js +329 -0
- package/dist/install.js +137 -0
- package/dist/ir.js +177 -0
- package/dist/load.js +42 -0
- package/dist/paths.js +24 -0
- package/dist/prompts.js +228 -0
- package/dist/specialize.js +201 -0
- package/dist/step-schemas.js +440 -0
- package/dist/types.js +8 -0
- package/dist/validate.js +576 -0
- package/pack/conventions/changesets.yaml +20 -0
- package/pack/conventions/ci-workflows.yaml +16 -0
- package/pack/conventions/config-secrets.yaml +16 -0
- package/pack/conventions/data-classification.yaml +16 -0
- package/pack/conventions/decisions.yaml +13 -0
- package/pack/conventions/git.yaml +28 -0
- package/pack/conventions/hexagonal.yaml +31 -0
- package/pack/conventions/security-code.yaml +17 -0
- package/pack/conventions/testing.yaml +44 -0
- package/pack/conventions/typescript-node.yaml +16 -0
- package/pack/model-policy.yaml +80 -0
- package/pack/orchestrations/architecture-decision.yaml +52 -0
- package/pack/orchestrations/bugfix-tdd.yaml +67 -0
- package/pack/orchestrations/data-analysis.yaml +23 -0
- package/pack/orchestrations/discovery.yaml +204 -0
- package/pack/orchestrations/feature-delivery.yaml +129 -0
- package/pack/orchestrations/prompt-delivery.yaml +155 -0
- package/pack/orchestrations/prompt-discovery.yaml +201 -0
- package/pack/orchestrations/release.yaml +40 -0
- package/pack/pack.yaml +137 -0
- package/pack/personas/architect.yaml +18 -0
- package/pack/personas/backend-engineer.yaml +21 -0
- package/pack/personas/data-analyst-non-pii.yaml +14 -0
- package/pack/personas/data-analyst-pii.yaml +28 -0
- package/pack/personas/devops-engineer.yaml +19 -0
- package/pack/personas/frontend-engineer.yaml +18 -0
- package/pack/personas/git-steward.yaml +24 -0
- package/pack/personas/lead-developer.yaml +23 -0
- package/pack/personas/prompt-engineer.yaml +38 -0
- package/pack/personas/qa-engineer.yaml +24 -0
- package/pack/personas/security-steward.yaml +20 -0
- package/package.json +47 -4
- package/schemas/convention.schema.yaml +46 -0
- package/schemas/handoff.schema.yaml +303 -0
- package/schemas/model-policy.schema.yaml +33 -0
- package/schemas/orchestration.schema.yaml +224 -0
- package/schemas/pack.schema.yaml +168 -0
- package/schemas/persona.schema.yaml +41 -0
- package/schemas/specialization-patch.schema.yaml +39 -0
- package/schemas/specialization.schema.yaml +51 -0
|
@@ -0,0 +1,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
|