@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
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,276 @@
1
- # Temporary Holding Version
1
+ # Friday
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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. 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
+ Hybrid-Day's specialization lives in `specializations/hybrid-day/` and is published to GitHub
102
+ Packages only, as `@digital-agora/friday-hybrid-day`:
103
+
104
+ ```bash
105
+ npx -y @digital-agora/friday-hybrid-day install
106
+ ```
107
+
108
+ ## Use
109
+
110
+ | Stream | Claude Code | OpenCode | What happens |
111
+ | --- | --- | --- | --- |
112
+ | 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 |
113
+ | 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 |
114
+ | 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 |
115
+
116
+ **Assumptions kill, without discovery loops for non-blockers.** Upstream steps ask only questions
117
+ whose answers block a safe, testable task. Explicitly non-blocking details are deferred into the
118
+ handoff's out-of-scope follow-ups; unresolved blockers still return to the user. Discovery compares
119
+ solution trade-offs, has the technical lead define implementation-facing contracts, and has QA
120
+ write behavioral acceptance scenarios. Delivery QA remains responsible for executable failing
121
+ tests. After discovery writes the handoff, Friday renders it as a readable
122
+ `docs/friday/<workId>/handoff.md` (`friday handoff render`), and the user reads and approves that
123
+ text; `friday handoff check` is the gate downstream must pass, and it refuses a `handoff.md` that is
124
+ missing or no longer matches the yaml.
125
+
126
+ **Discovery starts from a request brief.** Before any perspective asks a question, the prompt
127
+ engineer turns the request into a brief (goal, who, today, wanted, constraints, acceptance, out of
128
+ scope, facts checked in the repository, unknowns), every field citing its source, and the run stops
129
+ for the requester to approve it, with open items as one list of proposals. Every later step
130
+ builds on the approved brief; a change to it reopens every approval after it. The handoff records
131
+ who approved it (`checkpoints`), and `friday handoff check` refuses a discovery handoff without it.
132
+ Before the handoff, the prompt engineer also writes one **task brief** per task: the prompt that
133
+ task's agents receive (its acceptance, the contracts and files it may touch, the decisions that
134
+ apply, what it must not touch). You approve the briefs with the handoff, `handoff.md` shows each
135
+ under its task, and delivery gives each task's agents its brief next to the handoff.
136
+
137
+ **Discovery compiles to a skill that sizes the work** (`outputs: [skill]`). It has no workflow script: the session counts the
138
+ pack's sizing signals (codebases, personal data, interactions, acceptance criteria, dependencies)
139
+ and runs one agent at a time for a small request, a parallel group's agents at once for a medium
140
+ one, and each parallel group as a small workflow for a large one. The size never changes which
141
+ agents run or their models. Discovery infers the scopes a request covers and needs the outcome you
142
+ expect for each one, from the request or your answer, never assumed. Every contradiction comes with
143
+ what both sides already agree on and an "inner join" sweet spot: that overlap plus the least each
144
+ side must add.
145
+
146
+ **Data safety is shared.** The PII analyst checks every gap on personal information (what,
147
+ purpose, minimisation, retention, who reads it, exports, logs, seeds) upstream next to the
148
+ security steward, and, when the handoff holds pii, reviews the delivered diff before the security
149
+ steward reviews the controls.
150
+
151
+ **Changesets.** Every delivery PR carries a changeset added by the git steward (empty when
152
+ nothing user-facing changes); releases are prepared from them.
153
+
154
+ **The test pyramid in the development loop.** Every task runs as a QA-paired TDD loop that may
155
+ run only the bottom of the pyramid (`static`: typecheck and the architecture gate; `unit`: the
156
+ touched package's unit tests). Emulator and e2e suites are forbidden in task loops: a round that
157
+ runs one is not green, and the violation is reported. The **integration loop** at the end wires
158
+ each stack and runs the whole pyramid once (`static -> unit -> integration -> e2e`); it fixes
159
+ nothing, but turns every failure into a follow-up task (with the lowest level that reproduces
160
+ it) that goes back through the task loop, then integrates again, up to `maxRounds`. Levels,
161
+ commands and forbidden patterns are in `pack/pack.yaml` (`testPyramid`); `friday validate`
162
+ refuses a task loop that names an integration or e2e level, and an integration loop that skips
163
+ one.
164
+
165
+ **The prompt pyramid keeps people in the loop.** The prompt of a product's LLM feature is
166
+ built bottom first, `success-criteria -> evals -> context -> instructions -> examples ->
167
+ structure -> eval-run`, each level by its specialists and approved by a person's role (product
168
+ owner, data owner, domain reviewer, tech lead) before the next starts. The levels follow Claude's
169
+ documentation and are in `pack/pack.yaml` (`promptPyramid`); `friday validate` refuses an agent
170
+ as approver and a prompt author who also runs or reviews its evals. **`/friday-prompt-discovery`**
171
+ walks it with a person in the middle: after every level an `approval` step always stops the run,
172
+ even when nothing is open, and a person in the level's role approves it or asks for a change.
173
+ The level's agents propose a recommended value for each open decision; the stop merges the
174
+ level's open items, asks on their own only those touching personal data, security or a cost or
175
+ risk the person must own, and shows the rest as one list to approve in one go or change. A
176
+ change reopens that level and every level above it. The handoff records which role approved each
177
+ level and the file with what they approved; `friday handoff check` refuses a level that was never
178
+ approved or was approved by the wrong role. **`/friday-prompt-delivery`** builds the handoff the
179
+ way feature delivery does, then runs the top level, the eval run: QA runs the approved evals and
180
+ the security steward reviews them, neither of them the prompt's author. A criterion below its
181
+ threshold is never fixed there: the run returns `needs-upstream` naming the lowest level that
182
+ explains it, and prompt discovery reopens that level. The PR carries the eval report, and a person
183
+ in the product-owner role approves the eval run by approving the PR.
184
+
185
+ **Guardrails are enforced, not advised.** Following the
186
+ [AI-native SDLC playbook](https://claude.com/resources/articles/the-ai-native-sdlc-playbook), rules
187
+ that must always hold run as hooks before the tool call (`guardrails` in `pack/pack.yaml`): agents
188
+ inside task loops cannot run emulator or e2e commands, and implementers cannot edit the tests they
189
+ make pass, and approved prompt files (`docs/friday/<workId>/prompt/*.md` and the product's
190
+ `*.prompt.*`, `*.examples.*`, `*.evals.*`) are write-once for downstream agents: created once from
191
+ the approved level, never changed after. No agent approves its own work: `friday validate` refuses a gate that fixes its own
192
+ findings and a TDD pair whose implementer writes or verifies its tests. Every retro reports the
193
+ run's indicators (first-pass green, rework rounds, plan drift). See
194
+ `docs/proposals/ai-native-sdlc.md` for how Friday maps to the playbook and what comes next.
195
+
196
+ **Delivery checks before it builds.** Delivery workflows start with a preflight: QA installs the
197
+ workspace once and resolves every handoff `prerequisite` and version pin where the agents run, or
198
+ the run goes back upstream before anything is built. Tasks name the acceptance criteria they
199
+ prove (`covers`; an uncovered criterion stops the breakdown), registry work (`needs: [registry]`)
200
+ and the codebases they leave red until other tasks close the break (`breaks`, `closedBy`). Two
201
+ tasks with the same codebase never run at the same time, task loops run their tests by file
202
+ (`pnpm --filter <package> exec <test runner> <files>`), and behaviour a test designer would have to
203
+ decide comes back as questions, never as a note (decisions 48-52).
204
+
205
+ ## Models
206
+
207
+ | Task kind | Model | Effort | Who |
208
+ | --- | --- | --- | --- |
209
+ | implement | haiku | medium | frontend/backend/devops engineers making a failing test pass |
210
+ | verify | haiku | low | QA running the checks |
211
+ | git | haiku | low | git steward |
212
+ | scaffold (classes, types, ports) | sonnet | high | engineers defining and implementing interfaces |
213
+ | adapter | sonnet | medium | engineers implementing port adapters |
214
+ | test-plan | sonnet | high | QA planning acceptance scenarios before breakdown |
215
+ | test-design | sonnet | high | QA writing failing tests |
216
+ | analysis | sonnet | medium | PII analyst (personal-information gap checks, PII analyses), non-PII analyst |
217
+ | decide | opus | high | lead developer, architect, security steward |
218
+ | integrate | opus | high | senior integration work: engineers wiring ports/composition roots and running the full pyramid |
219
+ | review | opus | high | security steward gate |
220
+ | prompt-design | opus | high | prompt engineer writing a product feature's system prompt and examples (prompt pyramid) |
221
+ | brief | sonnet | high | prompt engineer writing the request brief before discovery |
222
+
223
+ `friday validate` refuses a workflow step that uses another model without `override.reason`.
224
+
225
+ ## Commands
226
+
227
+ ```text
228
+ friday install [-t target] [-g | -d dir] [--from zip|url] [--with spec]... [--no-project-conventions] [--force] [--dry-run]
229
+ friday list [--with spec]... agents (with models) and workflows
230
+ friday validate [--with spec]... schemas + cross-references + sources + model policy + test pyramid
231
+ friday build [-t target] [-o dir] [--with spec]... unpacked bundles
232
+ friday bundle [-t target] [-o dir] [--with spec]... friday-<target>-<version>.zip
233
+ friday graph [orchestration] [--with spec]... steps, routes, loops and every way a run can end (Mermaid + table)
234
+ friday handoff render <file> write the readable handoff.md next to handoff.yaml
235
+ friday handoff check <file> [--pending]
236
+ ```
237
+
238
+ Every command takes `--json` (one document on stdout; messages on stderr). Exit codes: 0 ok,
239
+ 1 error, 2 usage, 3 install conflicts kept.
240
+
241
+ ## Develop
242
+
243
+ ```bash
244
+ pnpm install
245
+ ```
246
+
247
+ ```bash
248
+ pnpm typecheck && pnpm build && pnpm lint && pnpm test
249
+ ```
250
+
251
+ Friday releases itself from changesets too: `pnpm changeset` in every PR (CI checks it), then
252
+ **Actions › Release › Run workflow** on `main` versions friday and the specializations, publishes
253
+ them to GitHub Packages, and pushes the `chore(release)` commit and the tags (`v<version>` for
254
+ friday, `friday-hybrid-day@<version>` for Hybrid-Day's; decision 22). **dry-run** rehearses it
255
+ and pushes nothing.
256
+
257
+ Publishing friday to npmjs.com as well is off unless turned on (decision 43):
258
+
259
+ 1. The `@digital-agora` scope is an npm organization that can publish `@digital-agora/friday`.
260
+ 2. The organization secret `NPM_TOKEN` (an automation token, or a granular token with read and
261
+ write on `@digital-agora/friday` and bypass 2FA) is shared with this repository: Organization ›
262
+ Settings › Secrets and variables › Actions › `NPM_TOKEN` › Repository access.
263
+ 3. Turn it on for every release with the repository variable `PUBLISH_NPMJS` = `true`, or for one
264
+ with **npmjs** ticked in Run workflow. `NPM_ACCESS` = `restricted` keeps it private (default
265
+ `public`).
266
+
267
+ The npmjs.com step runs after GitHub Packages and before anything is pushed; a rerun skips what is
268
+ already published. Without the secret it stops with an error instead of releasing to one registry
269
+ only. Specializations never go to npmjs.com.
270
+
271
+ Layout: `schemas/` (the YAML schemas), `pack/` (Friday's personas, conventions, workflows,
272
+ model policy and test pyramid, all generic), `specializations/` (project specializations, such
273
+ as Hybrid-Day's, each its own package), `src/` (loader, validator, IR,
274
+ `src/adapters/<target>/`, bundle, install, CLI), `test/` (vitest, including a harness that runs
275
+ the generated workflow scripts with mocked agents). See `CLAUDE.md` for the rules and
276
+ `docs/decisions.md` for why things are the way they are.
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
+ };