@digital-agora/friday 0.0.0-stage → 0.10.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 +296 -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 +300 -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 +230 -0
- package/dist/specialize.js +237 -0
- package/dist/step-schemas.js +444 -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 +214 -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 +57 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 digital-agora
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,297 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Friday
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A Digital Agora product. Friday is the source of truth for SDLC with AI. Its personas, workflows and conventions are
|
|
4
|
+
written once, as YAML in `pack/` validated by the YAML schemas in `schemas/`, and compiled into
|
|
5
|
+
bundles that install with `npx` into Claude Code or OpenCode, globally or into any folder.
|
|
6
|
+
|
|
7
|
+
| You write (`pack/`) | Claude Code gets | OpenCode gets |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `personas/*.yaml` | `.claude/agents/<persona>--<taskKind>.md` (model from the policy) | `.opencode/agent/<persona>--<taskKind>.md` (`mode: subagent`) |
|
|
10
|
+
| `conventions/*.yaml` | `.claude/rules/<id>.md` (`paths:` frontmatter) and `.claude/skills/<id>/SKILL.md`, listed in agents' `skills:` | `.opencode/conventions/<id>.md` loaded by `instructions`, skill-only ones as skills |
|
|
11
|
+
| `orchestrations/*.yaml`, `outputs: [workflow]` (the default) | `.claude/workflows/<id>.js` (deterministic `agent()`/`parallel()` script) and the `friday-<id>` driver skill | `friday-<id>` primary orchestrator agent and `/friday-<id>` command |
|
|
12
|
+
| `orchestrations/*.yaml`, `outputs: [skill]` | `.claude/skills/friday-<id>/` (`SKILL.md`, `steps.md`, `shapes.md`): the session sizes the work and runs each step with its agent | `.opencode/skill/friday-<id>/` and a `/friday-<id>` command that loads it |
|
|
13
|
+
| `orchestrations/*.yaml`, `outputs: [workflow, skill]` | the script and the sized skill; a large run goes through the script | the skill and its command (OpenCode has no scripts) |
|
|
14
|
+
| `model-policy.yaml` | `model:` on every agent and every workflow step | full provider ids (`anthropic/claude-...`) |
|
|
15
|
+
| `pack.yaml` | a marker block in `CLAUDE.md` | a marker block in `AGENTS.md`, merged `opencode.json` |
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
Friday is MIT-licensed. It is published to GitHub Packages, and to npmjs.com once a release turns
|
|
20
|
+
that on (decision 43, "Develop" below). From npmjs.com it needs no token: leave any
|
|
21
|
+
`@digital-agora:registry` line out of `~/.npmrc`.
|
|
22
|
+
|
|
23
|
+
Internal packages (Hybrid-Day's specialization, decision 42) are on GitHub Packages only, and so
|
|
24
|
+
is every version of Friday and of the open-source specializations (Google Cloud's, decision 53). Installing from there needs a GitHub personal access token (classic)
|
|
25
|
+
with `read:packages`, from https://github.com/settings/tokens/new?scopes=read:packages, in
|
|
26
|
+
`~/.npmrc`:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
@digital-agora:registry=https://npm.pkg.github.com
|
|
30
|
+
//npm.pkg.github.com/:_authToken=<token>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Run it from the project you want to install into, not from inside a clone of friday itself:
|
|
34
|
+
there, `npx` looks for the local `friday` command and fails with `friday: command not found`.
|
|
35
|
+
|
|
36
|
+
Install into the current project, for both agents:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx -y @digital-agora/friday install
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Install for your user (`~/.claude`, `~/.config/opencode`):
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npx -y @digital-agora/friday install --global
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Only one target, into another folder, or from a downloaded bundle:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npx -y @digital-agora/friday install --target opencode --dir ../my-project
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npx -y @digital-agora/friday install --from ./friday-claude-0.1.0.zip --dir .
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`--dry-run` shows what would change. Installing again only updates files Friday wrote; a file you
|
|
59
|
+
changed is kept and reported as a conflict (exit code 3) unless you pass `--force`. `CLAUDE.md`,
|
|
60
|
+
`AGENTS.md` and `opencode.json` are merged, never replaced. `.friday/lock.json` records what was
|
|
61
|
+
written.
|
|
62
|
+
|
|
63
|
+
On demand in a cloud environment, add the install to the environment's setup script:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npx -y @digital-agora/friday install --target claude
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Specialize: bring your own conventions
|
|
70
|
+
|
|
71
|
+
Friday's pack is generic (decision 42). A project adds its own rules, or changes Friday's, with a
|
|
72
|
+
specialization: a folder with `specialization.yaml` (`id`, `name`, and optionally `sources`,
|
|
73
|
+
`description`, test pyramid commands per level, more `forbiddenInLoop` commands, `piiTools`),
|
|
74
|
+
`conventions/*.yaml` and `personas/*.yaml`. On a conflict the specialization wins (decision 41):
|
|
75
|
+
|
|
76
|
+
- a convention with a new id is added; one with one of Friday's ids is a patch, merged rule by
|
|
77
|
+
rule (same rule id: the specialization's rule replaces Friday's; a new id is appended;
|
|
78
|
+
`remove: [ruleId]` drops one of Friday's);
|
|
79
|
+
- a persona file patches one of Friday's personas: `conventions` are added, `prompt` is appended
|
|
80
|
+
under the specialization's name, `taskKindNotes` merge, `role` and `description` replace;
|
|
81
|
+
- orchestrations, personas of its own and the model policy are Friday's only.
|
|
82
|
+
|
|
83
|
+
Put it in the project's `.friday/` and `friday install` applies it last, so the project wins over
|
|
84
|
+
everything else (`--no-project-conventions` skips it):
|
|
85
|
+
|
|
86
|
+
```text
|
|
87
|
+
my-project/.friday/
|
|
88
|
+
├── specialization.yaml id: acme, name: Acme, sources: [Acme/acme-handbook]
|
|
89
|
+
└── conventions/testing.yaml id: testing, rules: [{ id: no-network, rule: ..., source: acme-handbook/testing.md }]
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Or ship it as a package and pass it with `--with` (repeatable, in order; the later one wins):
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npx -y @digital-agora/friday install --with ./path/to/specialization --with @acme/friday-acme
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
A project rule cites its repository (`<repo>/<path>`, a repository in the specialization's
|
|
99
|
+
`sources`); `friday validate --with <it>` checks the merged pack.
|
|
100
|
+
|
|
101
|
+
A specialization can build on another with `extends` in `specialization.yaml` (a folder, or a
|
|
102
|
+
package it depends on); what it extends is applied first, so it wins (decision 53):
|
|
103
|
+
|
|
104
|
+
```yaml
|
|
105
|
+
extends: ["@digital-agora/friday-google-cloud"]
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Google Cloud's specialization lives in `specializations/google-cloud/`: the rules that hold for any
|
|
109
|
+
project on Google Cloud and Firebase (Firestore rules and `private/` documents for protected fields,
|
|
110
|
+
service accounts and Workload Identity Federation, Secret Manager, Cloud Run, `demo-` emulator
|
|
111
|
+
projects), each citing Google's documentation. It is MIT-licensed and published with friday, to
|
|
112
|
+
npmjs.com too, as `@digital-agora/friday-google-cloud`:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npx -y @digital-agora/friday-google-cloud install
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Hybrid-Day's specialization lives in `specializations/hybrid-day/`, extends Google Cloud's, and is
|
|
119
|
+
published to GitHub Packages only, as `@digital-agora/friday-hybrid-day`:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npx -y @digital-agora/friday-hybrid-day install
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Use
|
|
126
|
+
|
|
127
|
+
| Stream | Claude Code | OpenCode | What happens |
|
|
128
|
+
| --- | --- | --- | --- |
|
|
129
|
+
| upstream | `/friday-discovery`, `/friday-architecture-decision`, `/friday-prompt-discovery` | same commands | Resolves only implementation blockers, defers non-blocking details, compares solution trade-offs, defines interface contracts and acceptance scenarios, then writes the handoff for your approval |
|
|
130
|
+
| downstream | `/friday-feature-delivery`, `/friday-prompt-delivery`, `/friday-bugfix-tdd`, `/friday-data-analysis` | same commands | Starts only from an approved handoff, never asks, sends anything missing back upstream |
|
|
131
|
+
| release | `/friday-release` | same command | From pending changesets: checks staging is green, runs `changeset version`, opens the `chore(release)` PR; a maintainer tags `vX.Y.Z` after the merge |
|
|
132
|
+
|
|
133
|
+
**Assumptions kill, without discovery loops for non-blockers.** Upstream steps ask only questions
|
|
134
|
+
whose answers block a safe, testable task. Explicitly non-blocking details are deferred into the
|
|
135
|
+
handoff's out-of-scope follow-ups; unresolved blockers still return to the user. Discovery compares
|
|
136
|
+
solution trade-offs, has the technical lead define implementation-facing contracts, and has QA
|
|
137
|
+
write behavioral acceptance scenarios. Delivery QA remains responsible for executable failing
|
|
138
|
+
tests. After discovery writes the handoff, Friday renders it as a readable
|
|
139
|
+
`docs/friday/<workId>/handoff.md` (`friday handoff render`), and the user reads and approves that
|
|
140
|
+
text; `friday handoff check` is the gate downstream must pass, and it refuses a `handoff.md` that is
|
|
141
|
+
missing or no longer matches the yaml.
|
|
142
|
+
|
|
143
|
+
**Discovery starts from a request brief.** Before any perspective asks a question, the prompt
|
|
144
|
+
engineer turns the request into a brief (goal, who, today, wanted, constraints, acceptance, out of
|
|
145
|
+
scope, facts checked in the repository, unknowns), every field citing its source, and the run stops
|
|
146
|
+
for the requester to approve it, with open items as one list of proposals. Every later step
|
|
147
|
+
builds on the approved brief; a change to it reopens every approval after it. The handoff records
|
|
148
|
+
who approved it (`checkpoints`), and `friday handoff check` refuses a discovery handoff without it.
|
|
149
|
+
Before the handoff, the prompt engineer also writes one **task brief** per task: the prompt that
|
|
150
|
+
task's agents receive (its acceptance, the contracts and files it may touch, the decisions that
|
|
151
|
+
apply, what it must not touch). You approve the briefs with the handoff, `handoff.md` shows each
|
|
152
|
+
under its task, and delivery gives each task's agents its brief next to the handoff.
|
|
153
|
+
|
|
154
|
+
**Discovery compiles to a skill that sizes the work** (`outputs: [skill]`). It has no workflow script: the session counts the
|
|
155
|
+
pack's sizing signals (codebases, personal data, interactions, acceptance criteria, dependencies)
|
|
156
|
+
and runs one agent at a time for a small request, a parallel group's agents at once for a medium
|
|
157
|
+
one, and each parallel group as a small workflow for a large one. The size never changes which
|
|
158
|
+
agents run or their models. Discovery infers the scopes a request covers and needs the outcome you
|
|
159
|
+
expect for each one, from the request or your answer, never assumed. Every contradiction comes with
|
|
160
|
+
what both sides already agree on and an "inner join" sweet spot: that overlap plus the least each
|
|
161
|
+
side must add.
|
|
162
|
+
|
|
163
|
+
**Data safety is shared.** The PII analyst checks every gap on personal information (what,
|
|
164
|
+
purpose, minimisation, retention, who reads it, exports, logs, seeds) upstream next to the
|
|
165
|
+
security steward, and, when the handoff holds pii, reviews the delivered diff before the security
|
|
166
|
+
steward reviews the controls.
|
|
167
|
+
|
|
168
|
+
**Changesets.** Every delivery PR carries a changeset added by the git steward (empty when
|
|
169
|
+
nothing user-facing changes); releases are prepared from them.
|
|
170
|
+
|
|
171
|
+
**The test pyramid in the development loop.** Every task runs as a QA-paired TDD loop that may
|
|
172
|
+
run only the bottom of the pyramid (`static`: typecheck and the architecture gate; `unit`: the
|
|
173
|
+
touched package's unit tests). Emulator and e2e suites are forbidden in task loops: a round that
|
|
174
|
+
runs one is not green, and the violation is reported. The **integration loop** at the end wires
|
|
175
|
+
each stack and runs the whole pyramid once (`static -> unit -> integration -> e2e`); it fixes
|
|
176
|
+
nothing, but turns every failure into a follow-up task (with the lowest level that reproduces
|
|
177
|
+
it) that goes back through the task loop, then integrates again, up to `maxRounds`. Levels,
|
|
178
|
+
commands and forbidden patterns are in `pack/pack.yaml` (`testPyramid`); `friday validate`
|
|
179
|
+
refuses a task loop that names an integration or e2e level, and an integration loop that skips
|
|
180
|
+
one.
|
|
181
|
+
|
|
182
|
+
**The prompt pyramid keeps people in the loop.** The prompt of a product's LLM feature is
|
|
183
|
+
built bottom first, `success-criteria -> evals -> context -> instructions -> examples ->
|
|
184
|
+
structure -> eval-run`, each level by its specialists and approved by a person's role (product
|
|
185
|
+
owner, data owner, domain reviewer, tech lead) before the next starts. The levels follow Claude's
|
|
186
|
+
documentation and are in `pack/pack.yaml` (`promptPyramid`); `friday validate` refuses an agent
|
|
187
|
+
as approver and a prompt author who also runs or reviews its evals. **`/friday-prompt-discovery`**
|
|
188
|
+
walks it with a person in the middle: after every level an `approval` step always stops the run,
|
|
189
|
+
even when nothing is open, and a person in the level's role approves it or asks for a change.
|
|
190
|
+
The level's agents propose a recommended value for each open decision; the stop merges the
|
|
191
|
+
level's open items, asks on their own only those touching personal data, security or a cost or
|
|
192
|
+
risk the person must own, and shows the rest as one list to approve in one go or change. A
|
|
193
|
+
change reopens that level and every level above it. The handoff records which role approved each
|
|
194
|
+
level and the file with what they approved; `friday handoff check` refuses a level that was never
|
|
195
|
+
approved or was approved by the wrong role. **`/friday-prompt-delivery`** builds the handoff the
|
|
196
|
+
way feature delivery does, then runs the top level, the eval run: QA runs the approved evals and
|
|
197
|
+
the security steward reviews them, neither of them the prompt's author. A criterion below its
|
|
198
|
+
threshold is never fixed there: the run returns `needs-upstream` naming the lowest level that
|
|
199
|
+
explains it, and prompt discovery reopens that level. The PR carries the eval report, and a person
|
|
200
|
+
in the product-owner role approves the eval run by approving the PR.
|
|
201
|
+
|
|
202
|
+
**Guardrails are enforced, not advised.** Following the
|
|
203
|
+
[AI-native SDLC playbook](https://claude.com/resources/articles/the-ai-native-sdlc-playbook), rules
|
|
204
|
+
that must always hold run as hooks before the tool call (`guardrails` in `pack/pack.yaml`): agents
|
|
205
|
+
inside task loops cannot run emulator or e2e commands, and implementers cannot edit the tests they
|
|
206
|
+
make pass, and approved prompt files (`docs/friday/<workId>/prompt/*.md` and the product's
|
|
207
|
+
`*.prompt.*`, `*.examples.*`, `*.evals.*`) are write-once for downstream agents: created once from
|
|
208
|
+
the approved level, never changed after. No agent approves its own work: `friday validate` refuses a gate that fixes its own
|
|
209
|
+
findings and a TDD pair whose implementer writes or verifies its tests. Every retro reports the
|
|
210
|
+
run's indicators (first-pass green, rework rounds, plan drift). See
|
|
211
|
+
`docs/proposals/ai-native-sdlc.md` for how Friday maps to the playbook and what comes next.
|
|
212
|
+
|
|
213
|
+
**Delivery checks before it builds.** Delivery workflows start with a preflight: QA installs the
|
|
214
|
+
workspace once and resolves every handoff `prerequisite` and version pin where the agents run, or
|
|
215
|
+
the run goes back upstream before anything is built. Tasks name the acceptance criteria they
|
|
216
|
+
prove (`covers`; an uncovered criterion stops the breakdown), registry work (`needs: [registry]`)
|
|
217
|
+
and the codebases they leave red until other tasks close the break (`breaks`, `closedBy`). Two
|
|
218
|
+
tasks with the same codebase never run at the same time, task loops run their tests by file
|
|
219
|
+
(`pnpm --filter <package> exec <test runner> <files>`), and behaviour a test designer would have to
|
|
220
|
+
decide comes back as questions, never as a note (decisions 48-52).
|
|
221
|
+
|
|
222
|
+
## Models
|
|
223
|
+
|
|
224
|
+
| Task kind | Model | Effort | Who |
|
|
225
|
+
| --- | --- | --- | --- |
|
|
226
|
+
| implement | haiku | medium | frontend/backend/devops engineers making a failing test pass |
|
|
227
|
+
| verify | haiku | low | QA running the checks |
|
|
228
|
+
| git | haiku | low | git steward |
|
|
229
|
+
| scaffold (classes, types, ports) | sonnet | high | engineers defining and implementing interfaces |
|
|
230
|
+
| adapter | sonnet | medium | engineers implementing port adapters |
|
|
231
|
+
| test-plan | sonnet | high | QA planning acceptance scenarios before breakdown |
|
|
232
|
+
| test-design | sonnet | high | QA writing failing tests |
|
|
233
|
+
| analysis | sonnet | medium | PII analyst (personal-information gap checks, PII analyses), non-PII analyst |
|
|
234
|
+
| decide | opus | high | lead developer, architect, security steward |
|
|
235
|
+
| integrate | opus | high | senior integration work: engineers wiring ports/composition roots and running the full pyramid |
|
|
236
|
+
| review | opus | high | security steward gate |
|
|
237
|
+
| prompt-design | opus | high | prompt engineer writing a product feature's system prompt and examples (prompt pyramid) |
|
|
238
|
+
| brief | sonnet | high | prompt engineer writing the request brief before discovery |
|
|
239
|
+
|
|
240
|
+
`friday validate` refuses a workflow step that uses another model without `override.reason`.
|
|
241
|
+
|
|
242
|
+
## Commands
|
|
243
|
+
|
|
244
|
+
```text
|
|
245
|
+
friday install [-t target] [-g | -d dir] [--from zip|url] [--with spec]... [--no-project-conventions] [--force] [--dry-run]
|
|
246
|
+
friday list [--with spec]... agents (with models) and workflows
|
|
247
|
+
friday validate [--with spec]... schemas + cross-references + sources + model policy + test pyramid
|
|
248
|
+
friday build [-t target] [-o dir] [--with spec]... unpacked bundles
|
|
249
|
+
friday bundle [-t target] [-o dir] [--with spec]... friday-<target>-<version>.zip
|
|
250
|
+
friday graph [orchestration] [--with spec]... steps, routes, loops and every way a run can end (Mermaid + table)
|
|
251
|
+
friday handoff render <file> write the readable handoff.md next to handoff.yaml
|
|
252
|
+
friday handoff check <file> [--pending]
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Every command takes `--json` (one document on stdout; messages on stderr). Exit codes: 0 ok,
|
|
256
|
+
1 error, 2 usage, 3 install conflicts kept.
|
|
257
|
+
|
|
258
|
+
## Develop
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
pnpm install
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
pnpm typecheck && pnpm build && pnpm lint && pnpm test
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Friday releases itself from changesets too: `pnpm changeset` in every PR (CI checks it), then
|
|
269
|
+
**Actions › Release › Run workflow** on `main` versions friday and the specializations, publishes
|
|
270
|
+
them to GitHub Packages, and pushes the `chore(release)` commit and the tags (`v<version>` for
|
|
271
|
+
friday, `friday-<id>@<version>` for a specialization, such as `friday-hybrid-day@<version>`;
|
|
272
|
+
decision 22). **dry-run** rehearses it
|
|
273
|
+
and pushes nothing.
|
|
274
|
+
|
|
275
|
+
Publishing friday and the open-source specializations to npmjs.com as well is off unless turned
|
|
276
|
+
on (decisions 43, 53):
|
|
277
|
+
|
|
278
|
+
1. The `@digital-agora` scope is an npm organization that can publish `@digital-agora/friday` and
|
|
279
|
+
`@digital-agora/friday-google-cloud`.
|
|
280
|
+
2. The organization secret `NPM_TOKEN` (an automation token, or a granular token with read and
|
|
281
|
+
write on the `@digital-agora` scope, or on both packages once they exist, and bypass 2FA) is shared with this repository: Organization ›
|
|
282
|
+
Settings › Secrets and variables › Actions › `NPM_TOKEN` › Repository access.
|
|
283
|
+
3. Turn it on for every release with the repository variable `PUBLISH_NPMJS` = `true`, or for one
|
|
284
|
+
with **npmjs** ticked in Run workflow. `NPM_ACCESS` = `restricted` keeps it private (default
|
|
285
|
+
`public`).
|
|
286
|
+
|
|
287
|
+
The npmjs.com step runs after GitHub Packages and before anything is pushed; a rerun skips what is
|
|
288
|
+
already published. Without the secret it stops with an error instead of releasing to one registry
|
|
289
|
+
only. A specialization goes to npmjs.com only when its license is not `UNLICENSED` (Google
|
|
290
|
+
Cloud's); Hybrid-Day's never does.
|
|
291
|
+
|
|
292
|
+
Layout: `schemas/` (the YAML schemas), `pack/` (Friday's personas, conventions, workflows,
|
|
293
|
+
model policy and test pyramid, all generic), `specializations/` (platform and project specializations,
|
|
294
|
+
such as Google Cloud's and Hybrid-Day's, each its own package), `src/` (loader, validator, IR,
|
|
295
|
+
`src/adapters/<target>/`, bundle, install, CLI), `test/` (vitest, including a harness that runs
|
|
296
|
+
the generated workflow scripts with mocked agents). See `CLAUDE.md` for the rules and
|
|
297
|
+
`docs/decisions.md` for why things are the way they are.
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import { homedir } from "node:os";
|
|
2
|
+
/** Placeholder replaced at install time with the config root as the target expects to see it. */
|
|
3
|
+
export const CONFIG_DIR_TOKEN = "{{FRIDAY_CONFIG_DIR}}";
|
|
4
|
+
export function defaultHome() {
|
|
5
|
+
return process.env.FRIDAY_HOME ?? homedir();
|
|
6
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/** Tools that write a file path; the protected-tests hook matches them. */
|
|
2
|
+
export const EDIT_TOOLS = "Edit|Write|MultiEdit|NotebookEdit";
|
|
3
|
+
/** Quote a string for a POSIX shell. */
|
|
4
|
+
export function shellQuote(s) {
|
|
5
|
+
return `'${s.replace(/'/g, `'\\''`)}'`;
|
|
6
|
+
}
|
|
7
|
+
/** The hook script: reads the PreToolUse input on stdin, exits 2 with a reason when a guard hits. */
|
|
8
|
+
export function guardScript(check) {
|
|
9
|
+
const cfg = JSON.stringify(check);
|
|
10
|
+
return [
|
|
11
|
+
`const c=${cfg};let s="";`,
|
|
12
|
+
`process.stdin.on("data",d=>s+=d).on("end",()=>{`,
|
|
13
|
+
`let i={};try{i=JSON.parse(s)}catch{}const t=i.tool_input||{};`,
|
|
14
|
+
`if(c.kind==="command"){const cmd=String(t.command||"");const h=c.blocked.find(b=>cmd.includes(b));`,
|
|
15
|
+
`if(h){process.stderr.write("Friday guardrail: task loops run only the bottom of the test pyramid; \\""+h+"\\" runs in the integration loop. Run the static and unit checks of what you touched instead.\\n");process.exit(2)}}`,
|
|
16
|
+
`else{const raw=String(t.file_path||t.notebook_path||"");const f=raw.split("\\\\").join("/");const h=c.patterns.find(p=>new RegExp(p).test(f));`,
|
|
17
|
+
`if(h&&c.kind==="path"){process.stderr.write("Friday guardrail: "+f+" is a test, and you make tests pass without changing them. If the test is wrong, return status blocked with the question.\\n");process.exit(2)}`,
|
|
18
|
+
`if(h&&c.kind==="write-once"&&require("fs").existsSync(require("path").resolve(i.cwd||process.cwd(),raw))){process.stderr.write("Friday guardrail: "+f+" holds an approved prompt pyramid level and already exists; a person approved it, so it is never changed here. If it is stale or wrong, return status blocked naming the level: a person replaces it.\\n");process.exit(2)}}`,
|
|
19
|
+
`});`,
|
|
20
|
+
].join("");
|
|
21
|
+
}
|
|
22
|
+
export function guardCommand(check) {
|
|
23
|
+
return `node -e ${shellQuote(guardScript(check))}`;
|
|
24
|
+
}
|
|
25
|
+
/** The `hooks` frontmatter of an agent, or undefined when no guardrail applies to it. */
|
|
26
|
+
export function agentHooks(g) {
|
|
27
|
+
const pre = [];
|
|
28
|
+
if (g.blockedCommands.length) {
|
|
29
|
+
pre.push({ matcher: "Bash", hooks: [{ type: "command", command: guardCommand({ kind: "command", blocked: g.blockedCommands }) }] });
|
|
30
|
+
}
|
|
31
|
+
// One entry for the edit tools: protected tests first, then write-once approved prompt files.
|
|
32
|
+
const edits = [];
|
|
33
|
+
if (g.protectedPaths.length)
|
|
34
|
+
edits.push({ type: "command", command: guardCommand({ kind: "path", patterns: g.protectedPaths }) });
|
|
35
|
+
if (g.writeOncePaths.length)
|
|
36
|
+
edits.push({ type: "command", command: guardCommand({ kind: "write-once", patterns: g.writeOncePaths }) });
|
|
37
|
+
if (edits.length)
|
|
38
|
+
pre.push({ matcher: EDIT_TOOLS, hooks: edits });
|
|
39
|
+
return pre.length ? { PreToolUse: pre } : undefined;
|
|
40
|
+
}
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
// Claude Code target.
|
|
2
|
+
// project: <dir>/.claude/{agents,rules,skills,workflows} + <dir>/CLAUDE.md (marker block)
|
|
3
|
+
// global: ~/.claude/{agents,rules,skills,workflows} + ~/.claude/CLAUDE.md (marker block)
|
|
4
|
+
import { join } from "node:path";
|
|
5
|
+
import { withFrontmatter } from "../../frontmatter.js";
|
|
6
|
+
import { defaultHome } from "../adapter.js";
|
|
7
|
+
import { downstreamDriver, releaseDriver, renderPlan, retroRule, upstreamDriver } from "../drivers.js";
|
|
8
|
+
import { renderSkill } from "../skill.js";
|
|
9
|
+
import { emits } from "../../types.js";
|
|
10
|
+
import { agentHooks } from "./guards.js";
|
|
11
|
+
import { compileClaudeWorkflow } from "./workflows.js";
|
|
12
|
+
export const CLAUDE_DIRS = {
|
|
13
|
+
config: ".claude",
|
|
14
|
+
agents: "agents",
|
|
15
|
+
rules: "rules",
|
|
16
|
+
skills: "skills",
|
|
17
|
+
workflows: "workflows",
|
|
18
|
+
instructions: "CLAUDE.md",
|
|
19
|
+
};
|
|
20
|
+
function agents(ir) {
|
|
21
|
+
const tierId = ir.policy.targets.claude;
|
|
22
|
+
return ir.agents.map((a) => ({
|
|
23
|
+
root: "config",
|
|
24
|
+
path: `${CLAUDE_DIRS.agents}/${a.name}.md`,
|
|
25
|
+
merge: "replace",
|
|
26
|
+
content: withFrontmatter({
|
|
27
|
+
name: a.name,
|
|
28
|
+
description: a.description,
|
|
29
|
+
model: tierId[a.tier],
|
|
30
|
+
...(a.effort ? { effort: a.effort } : {}),
|
|
31
|
+
tools: a.persona.tools?.join(", "),
|
|
32
|
+
disallowedTools: [...(a.persona.disallowedTools ?? []), ...a.deniedTools].join(", ") || undefined,
|
|
33
|
+
permissionMode: a.persona.permissionMode,
|
|
34
|
+
maxTurns: a.persona.maxTurns,
|
|
35
|
+
skills: a.skills,
|
|
36
|
+
mcpServers: a.persona.mcpServers,
|
|
37
|
+
hooks: agentHooks(a.guards),
|
|
38
|
+
}, a.body),
|
|
39
|
+
}));
|
|
40
|
+
}
|
|
41
|
+
function conventions(ir) {
|
|
42
|
+
const out = [];
|
|
43
|
+
for (const { convention: c, body } of ir.conventions) {
|
|
44
|
+
if (c.emit.includes("rule")) {
|
|
45
|
+
out.push({
|
|
46
|
+
root: "config",
|
|
47
|
+
path: `${CLAUDE_DIRS.rules}/${c.id}.md`,
|
|
48
|
+
merge: "replace",
|
|
49
|
+
content: c.appliesTo ? withFrontmatter({ paths: c.appliesTo.paths }, body) : body,
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
if (c.emit.includes("skill")) {
|
|
53
|
+
out.push({
|
|
54
|
+
root: "config",
|
|
55
|
+
path: `${CLAUDE_DIRS.skills}/${c.id}/SKILL.md`,
|
|
56
|
+
merge: "replace",
|
|
57
|
+
content: withFrontmatter({ name: c.id, description: `${c.description} (${c.stack} convention, ${ir.pack.name})` }, body),
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return out;
|
|
62
|
+
}
|
|
63
|
+
const ASK = "AskUserQuestion (up to 4 questions per call; as many calls as needed)";
|
|
64
|
+
/** How a Claude Code session runs a skill output: Agent tool, parallel calls, workflows. */
|
|
65
|
+
const SKILL_TARGET = {
|
|
66
|
+
delegate: "the Agent tool, `subagent_type` set to the agent's name (its file sets the model and effort)",
|
|
67
|
+
parallel: "one message with an Agent tool call per agent",
|
|
68
|
+
ask: ASK,
|
|
69
|
+
workflow: (w, max) => [
|
|
70
|
+
"as a small workflow: call the Workflow tool with an inline `script` that starts with a pure",
|
|
71
|
+
`literal \`export const meta = { name: "friday-${w.id}-<group>", description: "<one line>", phases: [{ title: "<group>" }] }\`,`,
|
|
72
|
+
'then `phase("<group>")` and `return await parallel([...])` with one',
|
|
73
|
+
'`() => agent(<prompt>, { label: "<step id>", agentType: "<agent>", model: "<model>", schema: <shape from shapes.md> })`',
|
|
74
|
+
`per step of the group, the prompt built as section 3 says. At most ${max} agents per workflow (split a`,
|
|
75
|
+
"bigger group); no `Date.now`, `Math.random` or argless `new Date()`. Read each result as if the",
|
|
76
|
+
"agent had returned it to you; a null result is a failed agent",
|
|
77
|
+
].join(" "),
|
|
78
|
+
script: (w) => `call the Workflow tool with \`name: "${w.id}"\` and those args`,
|
|
79
|
+
notFound: [
|
|
80
|
+
"## If an agent is not found",
|
|
81
|
+
"",
|
|
82
|
+
"Claude Code registers agents at session start. If Friday was installed during this session,",
|
|
83
|
+
"agent types like `lead-developer--decide` may be unknown. Tell the user a restart (or a new",
|
|
84
|
+
"session) loads them. Until then, if the user wants to go on: start a general-purpose agent with",
|
|
85
|
+
"the agent file's prompt (`.claude/agents/<agent>.md`) as its instructions and the model the",
|
|
86
|
+
"Agents table names. Say that you did.",
|
|
87
|
+
"",
|
|
88
|
+
].join("\n"),
|
|
89
|
+
};
|
|
90
|
+
function skillOutput(w, ir) {
|
|
91
|
+
const name = `friday-${w.id}`;
|
|
92
|
+
const files = renderSkill(w, ir, SKILL_TARGET, name);
|
|
93
|
+
const description = `${w.stream === "upstream" ? "Upstream" : "Downstream"} Friday skill: ${w.description} Sizes the work first, then runs each step with its agent.`;
|
|
94
|
+
return [
|
|
95
|
+
{ root: "config", path: `${CLAUDE_DIRS.skills}/${name}/SKILL.md`, merge: "replace", content: withFrontmatter({ name, description }, files["SKILL.md"]) },
|
|
96
|
+
{ root: "config", path: `${CLAUDE_DIRS.skills}/${name}/steps.md`, merge: "replace", content: files["steps.md"] },
|
|
97
|
+
{ root: "config", path: `${CLAUDE_DIRS.skills}/${name}/shapes.md`, merge: "replace", content: files["shapes.md"] },
|
|
98
|
+
];
|
|
99
|
+
}
|
|
100
|
+
/** outputs: workflow -> the script; skill -> the structured skill, else the script's driver skill. */
|
|
101
|
+
function orchestrations(ir) {
|
|
102
|
+
return ir.orchestrations.flatMap((w) => {
|
|
103
|
+
const script = emits(w, "workflow")
|
|
104
|
+
? [{ root: "config", path: `${CLAUDE_DIRS.workflows}/${w.id}.js`, merge: "replace", content: compileClaudeWorkflow(w, ir) }]
|
|
105
|
+
: [];
|
|
106
|
+
return [...script, ...(emits(w, "skill") ? skillOutput(w, ir) : [driverSkill(w, ir)])];
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
function driverSkill(w, ir) {
|
|
110
|
+
const ask = ASK;
|
|
111
|
+
const run = `Call the Workflow tool with \`name: "${w.id}"\` and \`args\``;
|
|
112
|
+
const driver = w.stream === "upstream" ? upstreamDriver(w, { run, ask }, ir.pack.id)
|
|
113
|
+
: w.requires?.includes("changesets") ? releaseDriver(w, { run, ask })
|
|
114
|
+
: downstreamDriver(w, { run, ask }, ir.pack.id);
|
|
115
|
+
const skill = withFrontmatter({
|
|
116
|
+
name: `friday-${w.id}`,
|
|
117
|
+
description: `${w.stream === "upstream" ? "Upstream" : "Downstream"} Friday workflow: ${w.description}`,
|
|
118
|
+
}, [
|
|
119
|
+
`# friday-${w.id} (${w.stream})`,
|
|
120
|
+
"",
|
|
121
|
+
w.description,
|
|
122
|
+
"",
|
|
123
|
+
`Orchestrator: \`${w.orchestrator}\`. The steps, the agents and their models are fixed in`,
|
|
124
|
+
`\`.claude/workflows/${w.id}.js\`:`,
|
|
125
|
+
"",
|
|
126
|
+
renderPlan(w, ir),
|
|
127
|
+
"",
|
|
128
|
+
driver,
|
|
129
|
+
retroRule(w),
|
|
130
|
+
"## If the workflow or an agent is not found",
|
|
131
|
+
"",
|
|
132
|
+
"Claude Code registers agents and workflows at session start. If Friday was installed during",
|
|
133
|
+
`this session, the Workflow tool may not know \`${w.id}\` and agent types like`,
|
|
134
|
+
"`lead-developer--decide` may be unknown. Tell the user a restart (or a new session) loads them.",
|
|
135
|
+
"Until then, if the user wants to go on: run the step plan above yourself, delegating each step to",
|
|
136
|
+
"a general-purpose subagent with the agent file's prompt (`.claude/agents/<agent>.md`) as its",
|
|
137
|
+
"instructions and the model the plan names, and the same args and JSON shapes. Say that you did.",
|
|
138
|
+
].join("\n"));
|
|
139
|
+
return { root: "config", path: `${CLAUDE_DIRS.skills}/friday-${w.id}/SKILL.md`, merge: "replace", content: skill };
|
|
140
|
+
}
|
|
141
|
+
export const claudeAdapter = {
|
|
142
|
+
id: "claude",
|
|
143
|
+
capabilities: { workflowScripts: true, askUserTool: "AskUserQuestion", pathScopedRules: true, skills: true },
|
|
144
|
+
roots(scope, dir, home = defaultHome()) {
|
|
145
|
+
if (scope === "global") {
|
|
146
|
+
const config = join(home, CLAUDE_DIRS.config);
|
|
147
|
+
return { config, base: config };
|
|
148
|
+
}
|
|
149
|
+
return { config: join(dir, CLAUDE_DIRS.config), base: dir };
|
|
150
|
+
},
|
|
151
|
+
reloadNote: "Claude Code loads agents, skills and workflows at session start: restart the session (or start a new one) to use them.",
|
|
152
|
+
emit(ir) {
|
|
153
|
+
const skillsLine = "Run work through the `friday-<workflow>` skills: they drive the workflow scripts in `.claude/workflows/`, or size the work and run the steps with the agents directly.";
|
|
154
|
+
return [
|
|
155
|
+
...agents(ir),
|
|
156
|
+
...conventions(ir),
|
|
157
|
+
...orchestrations(ir),
|
|
158
|
+
{ root: "base", path: CLAUDE_DIRS.instructions, merge: "marker", content: `${ir.instructions}\n${skillsLine}\n` },
|
|
159
|
+
];
|
|
160
|
+
},
|
|
161
|
+
};
|