fascicle 0.1.13 → 0.3.3
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/CHANGELOG.md +62 -1
- package/README.md +63 -176
- package/dist/index.d.ts +338 -69
- package/dist/index.js +1020 -454
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,12 +1,73 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.3.3 — 2026-04-29
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
- `improve` composite in `@repo/composites`: bounded online self-improvement loop with parallel proposers, structured lessons accumulator, plateau detection, and configurable wall-clock + round budgets. Online counterpart to `learn`. Example at `examples/improve.ts`.
|
|
7
|
+
- `ensemble_step` composite: Step-based sibling of `ensemble` for cases where scoring is itself a `Step`. Returns `winner_id`, `winner`, structured `winner_scored`, and the full `scored` map.
|
|
8
|
+
|
|
9
|
+
## v0.3.2 — 2026-04-29
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
- `@repo/agents` package: markdown-driven `define_agent` loader plus `reviewer`, `documenter`, and `researcher` agents. `reviewer` and `documenter` are markdown-defined; `researcher` is bespoke TypeScript that drives `loop` from core over injected `search`/`fetch` callables, with a per-round summarizer that itself uses `define_agent`.
|
|
13
|
+
- Examples wiring each new agent against an in-process stub engine, plus an end-to-end `learn_reviewer` demo that runs the reviewer over three diffs (writing JSONL via `filesystem_logger`) and feeds the directory to `learn` to derive prompt-tightening proposals.
|
|
14
|
+
|
|
15
|
+
### Internal
|
|
16
|
+
- Tightened `learn` tests in `@repo/composites` around truncation events and `flow_description` equality.
|
|
17
|
+
|
|
18
|
+
## v0.3.1 — 2026-04-29
|
|
19
|
+
|
|
20
|
+
### Internal
|
|
21
|
+
- Colocated unit tests under `__tests__/` subfolders (e.g. `packages/core/src/branch.ts` ↔ `packages/core/src/__tests__/branch.test.ts`); cross-cutting tests under `packages/<name>/test/` are unchanged.
|
|
22
|
+
|
|
23
|
+
## v0.3.0 — 2026-04-29
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- New core primitives `loop` and `compose`, plus a universal `name?` option on every composer.
|
|
28
|
+
- New `learn` composer in `@repo/composites` for offline self-improvement, with file-path and directory sources, exported from the package index.
|
|
29
|
+
- `amplify` self-improvement loop example with a demo helper providing chart, measure, and reset utilities.
|
|
30
|
+
- `learn` example with smoke test.
|
|
31
|
+
- `EffortLevel` extended with `xhigh` and `max`, and reasoning support added to the `claude_cli` adapter.
|
|
32
|
+
- `spec/plans/ideas.md` capturing possible directions to build on fascicle.
|
|
33
|
+
|
|
34
|
+
### Changed
|
|
35
|
+
|
|
36
|
+
- `adversarial`, `ensemble`, `tournament`, and `consensus` extracted from `@repo/core` into a new `@repo/composites` package.
|
|
37
|
+
|
|
38
|
+
### Fixed
|
|
39
|
+
|
|
40
|
+
- `loop` type parameter renamed from `out` to `o` so tsx can parse the source.
|
|
41
|
+
|
|
42
|
+
### Internal
|
|
43
|
+
|
|
44
|
+
- Codegraph config plus ignore rules for db/cache files.
|
|
45
|
+
- Gitignored the rgr example trajectory output (per-run telemetry).
|
|
46
|
+
- Repaired the amplify cascade under tsc 6.x and `pnpm exec`.
|
|
47
|
+
- Imported adversarial types directly in the rgr harness; drive-by lint fixes for `pnpm check:all`.
|
|
48
|
+
|
|
49
|
+
## v0.2.0 — 2026-04-26
|
|
50
|
+
|
|
51
|
+
### Added
|
|
52
|
+
|
|
53
|
+
- Phase 0 library surfaces preparing for an upcoming `fascicle-studio` web UI: a `STEP_KINDS` const string union (plus `is_step_kind` and `StepKind`), structured Zod schemas for the trajectory wire format (`span_start_event_schema`, `span_end_event_schema`, `emit_event_schema`, `custom_event_schema`, and the combined `trajectory_event_schema`) configured to allow unknown fields so additional metadata survives a parse / re-serialize round-trip, an optional third-form `step(id, fn, meta?)` overload with `StepMetadata` (display name, description, port labels) echoed on `FlowNode` by `describe.json`, and automatic `run_id` stamping on every emitted trajectory event (a caller-supplied `run_id` is preserved). All re-exported through the `fascicle` umbrella.
|
|
54
|
+
- Contract tests locking the studio-facing invariants: `describe.json` is stable per `Step` instance, every emitted event id matches a node id in the flow tree, every event carries `run_id`, and every primitive's `kind` is in `STEP_KINDS`.
|
|
55
|
+
- Studio design doc plus parallel research notes at `spec/studio.md` and `spec/research/` capturing decisions for the sibling `fascicle-studio` repo.
|
|
56
|
+
- A red/green/refactor TDD harness example at `examples/red-green-refactor/`.
|
|
57
|
+
- `docs/til.md` with extracted snippets from pre-squash history.
|
|
58
|
+
|
|
59
|
+
### Changed
|
|
60
|
+
|
|
61
|
+
- Dropped the npm scope from the published name (now `fascicle`). README streamlined.
|
|
62
|
+
- `prepublishOnly` no longer runs the Stryker mutation check; it stays available via `pnpm check:all`.
|
|
63
|
+
|
|
3
64
|
## v0.1.13 — 2026-04-25
|
|
4
65
|
|
|
5
66
|
Initial public release. Fresh git baseline — prior internal commit history is intentionally not carried forward.
|
|
6
67
|
|
|
7
68
|
The v0.1.13 surface:
|
|
8
69
|
|
|
9
|
-
- Composition layer (
|
|
70
|
+
- Composition layer (`fascicle` / internal `@repo/core`) — 16 primitives (`step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `retry`, `fallback`, `timeout`, `adversarial`, `ensemble`, `tournament`, `consensus`, `checkpoint`, `suspend`, `scope`/`stash`/`use`), `run`, `run.stream`, `describe`.
|
|
10
71
|
- AI engine layer (`@repo/engine`) — `create_engine(config)` returning a unified `generate` surface over seven Vercel AI SDK provider adapters: Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, and a `claude_cli` subprocess adapter that drives the Claude Code CLI.
|
|
11
72
|
- Adapter packages — `@repo/observability` (trajectory loggers), `@repo/stores` (checkpoint stores).
|
|
12
73
|
- Check pipeline — `pnpm check` / `pnpm check:all` orchestrate types, lint, struct (ast-grep), dead-code (fallow), tests, docs, spell, and opt-in mutation testing (Stryker).
|
package/README.md
CHANGED
|
@@ -1,224 +1,111 @@
|
|
|
1
1
|
# Fascicle
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Compose agents out of LLM calls, tool calls, and plain functions. Everything is a `Step<i, o>`. Wire steps together with 16 primitives (`sequence`, `parallel`, `branch`, `retry`, `ensemble`, `checkpoint`, …) and run them as plain values. One `generate` surface fronts seven provider adapters: Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, and a `claude_cli` subprocess that drives the Claude Code CLI.
|
|
4
4
|
|
|
5
|
-
No framework lifecycle
|
|
5
|
+
No framework lifecycle. No ambient state. No decorators. Adapters are passed in per run.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
- **Composition (`@repo/core` internal / `@robmclarty/fascicle` public)** — 16 primitives (`step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `retry`, `fallback`, `timeout`, `adversarial`, `ensemble`, `tournament`, `consensus`, `checkpoint`, `suspend`, `scope`/`stash`/`use`) plus `run`, `run.stream`, and `describe`. Every composable unit is a `Step<i, o>`; every composer returns a `Step<i, o>`. Anywhere a step fits, any composition of steps fits.
|
|
10
|
-
- **AI engine (`@repo/engine`)** — `create_engine(config)` returning a unified `generate` surface over seven AI SDK provider adapters: Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, and a `claude_cli` subprocess adapter that drives the Claude Code CLI.
|
|
11
|
-
|
|
12
|
-
`@robmclarty/fascicle` is a thin umbrella package that re-exports both layers so downstream apps can install one thing. Internally, workspace packages use the `@repo/*` prefix; the published name stays `@robmclarty/fascicle`.
|
|
13
|
-
|
|
14
|
-
## Names
|
|
15
|
-
|
|
16
|
-
- **`@robmclarty/fascicle`** — the one thing you install from npm. Bundles the composition primitives and the engine.
|
|
17
|
-
- **`@repo/core`, `@repo/engine`, `@repo/observability`, `@repo/stores`, `@repo/fascicle`** — workspace-only. Contributors see these internally; they are never published.
|
|
18
|
-
|
|
19
|
-
Only `@robmclarty/fascicle` reaches npm. Contributors work against `@repo/*` symlinks inside this pnpm workspace.
|
|
20
|
-
|
|
21
|
-
The monorepo split is an **architectural boundary enforcement mechanism**, not a distribution strategy. `@repo/core` cannot import from adapter packages; `@repo/engine` cannot reach outside its providers; `packages/config/` is the only place allowed to read `process.env`. Keeping those boundaries as separate workspace packages lets the dependency graph, fallow, and the ast-grep rules in `rules/` police them directly. Consumers still see one package.
|
|
22
|
-
|
|
23
|
-
## Layout
|
|
24
|
-
|
|
25
|
-
```text
|
|
26
|
-
├── packages/
|
|
27
|
-
│ ├── fascicle/ umbrella: re-exports core + engine
|
|
28
|
-
│ ├── core/ composition layer (16 primitives, run, describe)
|
|
29
|
-
│ ├── engine/ AI engine layer (create_engine, generate)
|
|
30
|
-
│ │ └── src/providers/ anthropic, openai, google, openrouter, ollama, lmstudio, claude_cli
|
|
31
|
-
│ ├── config/ zod-validated env loader; only package that reads process.env
|
|
32
|
-
│ ├── observability/ TrajectoryLogger adapters (noop, filesystem JSONL)
|
|
33
|
-
│ └── stores/ CheckpointStore adapters (filesystem)
|
|
34
|
-
├── examples/ runnable reference harnesses (hello, streaming, ensemble, suspend, ollama)
|
|
35
|
-
├── rules/ ast-grep structural rules
|
|
36
|
-
├── scripts/check.mjs the check orchestrator
|
|
37
|
-
├── .ridgeline/ ridgeline project constraints, taste, and build dirs
|
|
38
|
-
├── docs/ concepts, providers, configuration, cookbook, CLI, harness guide
|
|
39
|
-
├── fallow.toml vitest.config.ts stryker.config.mjs cspell.json sgconfig.yml
|
|
40
|
-
├── AGENTS.md CLAUDE.md agent contracts
|
|
41
|
-
└── package.json scripts + all devDependencies live here
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
Runtime dependencies live in the package that imports them; devDependencies live at the root. Cross-package imports go through workspace names (`@repo/core`), not relative paths.
|
|
45
|
-
|
|
46
|
-
## The check contract
|
|
47
|
-
|
|
48
|
-
`pnpm check:all` is the single source of truth for "is this done?". `pnpm check` runs the same pipeline minus the opt-in `mutation` step and is the command to use during iteration.
|
|
49
|
-
|
|
50
|
-
| Check | Tool | Catches |
|
|
51
|
-
| ---------- | -------------------------------- | ------------------------------------------------------------ |
|
|
52
|
-
| `types` | `tsc` | Type errors (ground truth) |
|
|
53
|
-
| `lint` | `oxlint` + `oxlint-tsgolint` | Syntax rules, floating promises, unsafe any, 50+ type-aware rules |
|
|
54
|
-
| `struct` | `ast-grep` | Project-specific structural rules (see `rules/`) |
|
|
55
|
-
| `dead` | `fallow` | Unused exports/files/deps, circular deps, duplication, complexity, boundary violations |
|
|
56
|
-
| `test` | `vitest` + `@vitest/coverage-v8` | Unit test failures and coverage below thresholds |
|
|
57
|
-
| `docs` | `markdownlint-cli2` | Broken markdown |
|
|
58
|
-
| `spell` | `cspell` | Misspellings in source and docs |
|
|
59
|
-
| `mutation` | `stryker` (opt-in) | Tests that pass trivially (run via `pnpm check:all` or `--include mutation`) |
|
|
60
|
-
|
|
61
|
-
Deeper passes on demand:
|
|
62
|
-
|
|
63
|
-
- `pnpm check:all` — full pipeline including Stryker mutation testing
|
|
64
|
-
- `pnpm check --include mutation` — same as `check:all` but via the flag
|
|
65
|
-
- `pnpm check:mutation` — Stryker only (bypasses the orchestrator)
|
|
66
|
-
- `pnpm check:security` — `pnpm audit --audit-level=high`
|
|
67
|
-
- `pnpm check:fix` — auto-fix oxlint and fallow issues where possible
|
|
68
|
-
|
|
69
|
-
## Quick start
|
|
7
|
+
## Install
|
|
70
8
|
|
|
71
9
|
```bash
|
|
72
|
-
pnpm
|
|
73
|
-
pnpm check
|
|
10
|
+
pnpm add fascicle zod
|
|
74
11
|
```
|
|
75
12
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
- `.check/summary.json` — aggregate result for agents
|
|
79
|
-
- `.check/lint.json`, `.check/dead.json`, `.check/struct.json`, `.check/test.json` — raw per-tool JSON
|
|
80
|
-
- `.check/coverage/` — vitest coverage report
|
|
13
|
+
Provider SDKs are optional peers — install only the ones you use. See [docs/providers.md](./docs/providers.md).
|
|
81
14
|
|
|
82
|
-
##
|
|
15
|
+
## A 60-second tour
|
|
83
16
|
|
|
84
17
|
```typescript
|
|
85
|
-
import { run, sequence, step } from '
|
|
18
|
+
import { run, sequence, step } from 'fascicle';
|
|
86
19
|
|
|
87
20
|
const flow = sequence([
|
|
88
|
-
step('
|
|
89
|
-
step('
|
|
21
|
+
step('add', (n: number) => n + 1),
|
|
22
|
+
step('double', (n: number) => n * 2),
|
|
90
23
|
]);
|
|
91
24
|
|
|
92
|
-
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
Inject adapters per run:
|
|
96
|
-
|
|
97
|
-
```typescript
|
|
98
|
-
import { filesystem_logger } from '@repo/observability';
|
|
99
|
-
import { filesystem_store } from '@repo/stores';
|
|
100
|
-
|
|
101
|
-
await run(flow, input, {
|
|
102
|
-
trajectory: filesystem_logger({ output_path: '/tmp/run.jsonl' }),
|
|
103
|
-
checkpoint_store: filesystem_store({ root_dir: '/tmp/checkpoints' }),
|
|
104
|
-
});
|
|
25
|
+
await run(flow, 1); // 4
|
|
105
26
|
```
|
|
106
27
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
## Using the engine layer
|
|
28
|
+
Add a model call:
|
|
110
29
|
|
|
111
30
|
```typescript
|
|
112
|
-
import { create_engine } from '
|
|
31
|
+
import { create_engine, model_call, run, sequence, step } from 'fascicle';
|
|
113
32
|
|
|
114
33
|
const engine = create_engine({
|
|
115
34
|
providers: { anthropic: { api_key: process.env.ANTHROPIC_API_KEY! } },
|
|
116
35
|
});
|
|
117
36
|
|
|
118
|
-
const
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
await engine.dispose();
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
Provider adapters are wired behind optional peer dependencies; install only the ones you use. See [`docs/providers.md`](./docs/providers.md) for the full provider matrix, [`docs/configuration.md`](./docs/configuration.md) for engine config, and [`docs/cli.md`](./docs/cli.md) for the `claude_cli` adapter.
|
|
127
|
-
|
|
128
|
-
## Agent use
|
|
129
|
-
|
|
130
|
-
The contract: **if `pnpm check` exits 0, the work is done. If it exits non-zero, read `.check/summary.json` for which checks failed, then the corresponding tool JSON for diagnostics.**
|
|
37
|
+
const flow = sequence([
|
|
38
|
+
step('brief', (topic: string) => `Write a 2-sentence brief on: ${topic}`),
|
|
39
|
+
model_call({ engine, model: 'sonnet', system: 'No preamble.' }),
|
|
40
|
+
step('extract', (r) => r.content),
|
|
41
|
+
]);
|
|
131
42
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
{
|
|
135
|
-
|
|
136
|
-
"ok": false,
|
|
137
|
-
"total_duration_ms": 4821,
|
|
138
|
-
"checks": [
|
|
139
|
-
{ "name": "types", "ok": true, "exit_code": 0, "duration_ms": 1200, "output_file": null },
|
|
140
|
-
{ "name": "lint", "ok": false, "exit_code": 1, "duration_ms": 340, "output_file": "lint.json" }
|
|
141
|
-
]
|
|
43
|
+
try {
|
|
44
|
+
console.log(await run(flow, 'Rust ownership'));
|
|
45
|
+
} finally {
|
|
46
|
+
await engine.dispose();
|
|
142
47
|
}
|
|
143
48
|
```
|
|
144
49
|
|
|
145
|
-
|
|
50
|
+
`model_call` is the only sanctioned bridge between composition and the engine. It threads `ctx.abort`, `ctx.trajectory`, and streaming chunks for you.
|
|
146
51
|
|
|
147
|
-
|
|
148
|
-
- `pnpm check --bail` — stop at the first failure
|
|
149
|
-
- `pnpm check --only types,lint` — run a subset during iteration
|
|
150
|
-
- `pnpm check --skip spell,docs` — skip slow or noisy checks
|
|
52
|
+
## What's in the box
|
|
151
53
|
|
|
152
|
-
|
|
54
|
+
**Composition primitives (16).** `step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `retry`, `fallback`, `timeout`, `adversarial`, `ensemble`, `tournament`, `consensus`, `checkpoint`, `suspend`, `scope`/`stash`/`use`. Plus `run`, `run.stream`, and `describe`. Every composer takes `Step<i, o>` and returns `Step<i, o>`. Anything that fits a step fits any composition of steps.
|
|
153
55
|
|
|
154
|
-
`
|
|
56
|
+
**AI engine.** `create_engine(config)` returns one `generate` surface across seven providers. Aliases (`sonnet`, `opus`, `gpt-4o`, `cli-sonnet`, …) resolve to `provider:model_id`. Reasoning effort (`'low' | 'medium' | 'high'`) is translated per provider. Cost estimation uses a pricing table with per-engine overrides.
|
|
155
57
|
|
|
156
|
-
|
|
157
|
-
pnpm --filter @repo/core test # run one package's tests
|
|
158
|
-
pnpm --filter @repo/engine add zod # add a runtime dep to one package
|
|
159
|
-
pnpm add -w -D typescript@latest # upgrade a root devDependency
|
|
160
|
-
```
|
|
58
|
+
**Adapters injected per run.**
|
|
161
59
|
|
|
162
|
-
|
|
60
|
+
```typescript
|
|
61
|
+
import { filesystem_logger } from '@repo/observability';
|
|
62
|
+
import { filesystem_store } from '@repo/stores';
|
|
163
63
|
|
|
164
|
-
|
|
165
|
-
|
|
64
|
+
await run(flow, input, {
|
|
65
|
+
trajectory: filesystem_logger({ output_path: '.trajectory.jsonl' }),
|
|
66
|
+
checkpoint_store: filesystem_store({ root_dir: '.checkpoints' }),
|
|
67
|
+
});
|
|
166
68
|
```
|
|
167
69
|
|
|
168
|
-
|
|
70
|
+
`run.stream(flow, input)` returns `{ events, result }` for incremental observation.
|
|
169
71
|
|
|
170
|
-
|
|
72
|
+
## Provider matrix
|
|
171
73
|
|
|
172
|
-
|
|
173
|
-
|
|
74
|
+
| Provider | Peer dep | Auth |
|
|
75
|
+
| ------------ | ----------------------------- | ------------------- |
|
|
76
|
+
| `anthropic` | `@ai-sdk/anthropic` | API key |
|
|
77
|
+
| `openai` | `@ai-sdk/openai` | API key |
|
|
78
|
+
| `google` | `@ai-sdk/google` | API key |
|
|
79
|
+
| `openrouter` | `@openrouter/ai-sdk-provider` | API key |
|
|
80
|
+
| `ollama` | `ai-sdk-ollama` | local `base_url` |
|
|
81
|
+
| `lmstudio` | `@ai-sdk/openai-compatible` | local `base_url` |
|
|
82
|
+
| `claude_cli` | none (spawns `claude`) | OAuth or API key |
|
|
174
83
|
|
|
175
|
-
|
|
84
|
+
Full details: [docs/providers.md](./docs/providers.md). The `claude_cli` adapter has its own guide: [docs/cli.md](./docs/cli.md).
|
|
176
85
|
|
|
177
|
-
##
|
|
86
|
+
## Where to go next
|
|
178
87
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
output_file: 'agent.json',
|
|
188
|
-
}
|
|
189
|
-
```
|
|
88
|
+
- [docs/getting-started.md](./docs/getting-started.md) — install and run your first flow
|
|
89
|
+
- [docs/concepts.md](./docs/concepts.md) — step-as-value, trajectories, cancellation
|
|
90
|
+
- [docs/configuration.md](./docs/configuration.md) — engine config, aliases, pricing, retries
|
|
91
|
+
- [docs/providers.md](./docs/providers.md) — per-provider adapter notes
|
|
92
|
+
- [docs/cli.md](./docs/cli.md) — the `claude_cli` subprocess adapter
|
|
93
|
+
- [docs/cookbook.md](./docs/cookbook.md) — retries, fan-out, judges, HITL, tool loops
|
|
94
|
+
- [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
|
|
95
|
+
- [examples/](./examples/) — runnable reference flows
|
|
190
96
|
|
|
191
|
-
|
|
97
|
+
## Contributing
|
|
192
98
|
|
|
193
|
-
|
|
99
|
+
This repo is a pnpm workspace. Internally the code is split into `@repo/core`, `@repo/engine`, `@repo/observability`, `@repo/stores`, and `@repo/fascicle` (umbrella). Only the umbrella reaches npm as `fascicle`. The split exists to enforce architectural boundaries (e.g. `@repo/core` cannot import adapters; only `@repo/config` reads `process.env`); fallow and the ast-grep rules in `rules/` police them.
|
|
194
100
|
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
101
|
+
```bash
|
|
102
|
+
pnpm install
|
|
103
|
+
pnpm check # types, lint, structural rules, dead-code, tests, docs, spell
|
|
104
|
+
pnpm check:all # adds Stryker mutation testing (slow; final gate)
|
|
199
105
|
```
|
|
200
106
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
## Philosophy
|
|
107
|
+
`pnpm check` is the single source of truth for "is this done?". Output lands in `.check/` (one JSON per check). See [AGENTS.md](./AGENTS.md) for the full contract and [CLAUDE.md](./CLAUDE.md) for Claude-specific notes.
|
|
204
108
|
|
|
205
|
-
|
|
206
|
-
2. **Structured output over stderr chatter.** Every JSON-capable tool is configured to emit JSON. Agents parse structured data, not colorized text.
|
|
207
|
-
3. **The orchestrator is dumb.** It shells out, captures exit codes, and writes files. It does not parse diagnostics.
|
|
208
|
-
4. **Tools, not frameworks.** Each tool is independently swappable. If something better than oxlint ships next year, you change one line in `CHECKS`.
|
|
209
|
-
5. **Step-as-value.** In the composition layer, every unit is a `Step<i, o>` and every composer returns one. Substitutability, introspectability, and no coupling fall out of that one invariant.
|
|
109
|
+
## License
|
|
210
110
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
- [AGENTS.md](./AGENTS.md) — universal contract for any coding agent
|
|
214
|
-
- [CLAUDE.md](./CLAUDE.md) — Claude-specific workflow notes
|
|
215
|
-
- [CHANGELOG.md](./CHANGELOG.md) — version history
|
|
216
|
-
- [docs/getting-started.md](./docs/getting-started.md) — install + first flow
|
|
217
|
-
- [docs/concepts.md](./docs/concepts.md) — step-as-value, composition, trajectories
|
|
218
|
-
- [docs/configuration.md](./docs/configuration.md) — engine config, aliases, provider setup
|
|
219
|
-
- [docs/providers.md](./docs/providers.md) — per-provider adapter notes
|
|
220
|
-
- [docs/cli.md](./docs/cli.md) — `claude_cli` subprocess adapter
|
|
221
|
-
- [docs/cookbook.md](./docs/cookbook.md) — worked patterns (retries, fan-out, judges, HITL)
|
|
222
|
-
- [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
|
|
223
|
-
- [packages/core/README.md](./packages/core/README.md) — composition layer surface
|
|
224
|
-
- [.ridgeline/](./.ridgeline/) — project constraints, taste, and ridgeline build history
|
|
111
|
+
[Apache 2.0](./LICENSE)
|