Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/skills/effort-modeling/CONTEXT-FORMAT.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,4 @@ that prevents a common ambiguity.
```

Do not put implementation plans, alternatives, or commitments here. Journal
those in Effort Graph records.
those in Proof records.
12 changes: 6 additions & 6 deletions .agents/skills/effort-modeling/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
---
name: effort-modeling
description: Sharpen a project's vocabulary and planning through one-question-at-a-time grilling, then journal Decisions, Constraints, Findings, Issues, and Risks into the Flatbread Effort Graph. Use when a plan needs durable reasoning instead of ADRs.
description: Sharpen a project's vocabulary and planning through one-question-at-a-time grilling, then journal Decisions, Constraints, Findings, Issues, and Risks into the Flatbread Proof. Use when a plan needs durable reasoning instead of ADRs.
disable-model-invocation: true
---

# Effort modeling

Use this discipline while a plan or design is being shaped. Store planning
records in the Effort Graph. Keep project terms in a glossary such as
records in the Proof. Keep project terms in a glossary such as
`CONTEXT.md` or `docs/glossary.md`.

## Resume before asking

From the project root, use the `effort-graph` skill's bounded reads:
From the project root, use the `proof` skill's bounded reads:

1. `flatbread effort list --status active`
1. `flatbread proof list --status active`
2. For the relevant Effort, inspect open Issues and blocking Decisions.
3. Read a record or digest when a prior conclusion affects the question.

Expand All @@ -35,8 +35,8 @@ answer, and resolve prerequisite choices before dependent ones.

## Journal the right speech act

Use `flatbread effort write` for the current Effort, following
[the Effort Graph reference](../effort-graph/reference.md):
Use `flatbread proof write` for the current Effort, following
[the Proof reference](../proof/reference.md):

- **Finding** — evidence about code, users, or runtime behavior.
- **Issue** — a question, defect, gap, or blocker needing attention.
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/grill-with-efforts/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: grill-with-efforts
description: Run a relentless one-question-at-a-time planning interview that sharpens vocabulary and journals durable reasoning into the Flatbread Effort Graph. Use when a plan is fuzzy and needs an Effort Graph trail instead of ADRs.
description: Run a relentless one-question-at-a-time planning interview that sharpens vocabulary and journals durable reasoning into the Flatbread Proof. Use when a plan is fuzzy and needs an Proof trail instead of ADRs.
disable-model-invocation: true
---

Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
name: effort-graph
description: Journal reasoning (decisions, findings, issues, constraints, risks, citations, blobs) into a Flatbread Effort Graph and recall it with bounded reads. Use when starting or resuming a thread of work, recording a decision or finding, resolving an issue, checking what is blocking or still open on an effort, or when the user mentions effort graph, journaling, blocking decisions, agent memory, citation, blob, cites, longform, WriteCitation, or WriteBlob.
name: proof
description: Journal reasoning (decisions, findings, issues, constraints, risks, citations, blobs) into a Flatbread Proof and recall it with bounded reads. Use when starting or resuming a thread of work, recording a decision or finding, resolving an issue, checking what is blocking or still open on an effort, or when the user mentions effort graph, journaling, blocking decisions, agent memory, citation, blob, cites, longform, WriteCitation, or WriteBlob.
---

# Effort Graph — agent journaling and recall
# Proof — agent journaling and recall

The Effort Graph stores durable project memory as markdown records in the
The Proof stores durable project memory as markdown records in the
repository. It has eight record types: **Effort**, **Issue**, **Finding**,
**Decision**, **Constraint**, and **Risk** capture the work and reasoning;
**Citation** stores a source or reference; and **Blob** stores attached
Expand All @@ -24,7 +24,7 @@ errors print JSON to stderr and exit 1.
## First activation

Read [setup.md](./setup.md), make the reviewed config and gitignore edits, then
run `flatbread effort bootstrap` followed by `flatbread effort bootstrap --verify`. Bootstrap is report-only and never edits project files.
run `flatbread proof bootstrap` followed by `flatbread proof bootstrap --verify`. Bootstrap is report-only and never edits project files.

## Prerequisites

Expand All @@ -35,26 +35,26 @@ import {
defineConfig,
sourceFilesystem,
transformerMarkdown,
effortGraphContent,
proofContent,
} from 'flatbread';

export default defineConfig({
source: sourceFilesystem(),
transformer: transformerMarkdown(),
content: [...effortGraphContent()],
content: [...proofContent()],
});
```

Records live under `<root>/{efforts,issues,findings,decisions,constraints,risks,citations,blobs}/`.
The write journal is `<root>/.journal/`; read digests cache under
`.flatbread/effort-graph/read-cache/` (both gitignored).
`.flatbread/proof/read-cache/` (both gitignored).

## Writing (journaling)

One command for all 15 mutations — pass the payload as a single JSON argument:

```bash
flatbread effort write '{"type":"WriteDecision","effort":"<eff-id>","title":"...","body":"...","derives_from":["<id>"]}'
flatbread proof write '{"type":"WriteDecision","effort":"<eff-id>","title":"...","body":"...","derives_from":["<id>"]}'
```

Response: `{"generation":"<token>","artifacts":[{"id","path","operation"}],"touched":[...]}`.
Expand All @@ -79,7 +79,7 @@ Critical semantics:
`cites: ["<cit-id>"]` when creating an Issue, Finding, Decision,
Constraint, or Risk. Both the Citation in `cites` and the Blob in
`Citation.blob` must belong to the same Effort as the record that links to
them. Bounded digests omit Blob bodies; use `effort get <blob-id>` to read
them. Bounded digests omit Blob bodies; use `proof get <blob-id>` to read
one.
- When superseding, open the new record's body with a short rollup of what
changed and why — reads render ancestors only as one-line checkpoints.
Expand All @@ -97,63 +97,63 @@ Read on it, or grep it), `served_generation`, page info, and ≤10 executable
`hints`. Digests cap at 25 records / one-hop expansion / 50 edges / 64 KiB.

Browse digests (`list`, `records`, `relations`, `blocking-decisions`) excerpt
each body at 600 chars / 12 lines (`[…truncated]`). **`effort get` digests
each body at 600 chars / 12 lines (`[…truncated]`). **`proof get` digests
always include the full record body** (still subject to the 64 KiB digest
byte cap). Zoom in with `get`, then Read/grep that digest — do not open
`.flatbread-efforts/**/*.md` for normal full-body recall.
`.flatbread-proof/**/*.md` for normal full-body recall.

```bash
# What's gating this effort? (proposed Decisions deriving from open blocker Issues)
flatbread effort blocking-decisions <effortId>
flatbread proof blocking-decisions <effortId>

# Resume: discover active Efforts first
flatbread effort list --status active
flatbread proof list --status active

# Scoped listing with filters (AND across flags, OR within comma lists).
# --status filters Issues and --state filters Decisions, so combining them in
# one call ANDs across kinds and matches nothing — query each kind separately.
flatbread effort records <effortId> --kinds issue --status open --since 2026-07-01T00:00:00Z --limit 10
flatbread effort records <effortId> --kinds decision --state proposed --limit 10
flatbread proof records <effortId> --kinds issue --status open --since 2026-07-01T00:00:00Z --limit 10
flatbread proof records <effortId> --kinds decision --state proposed --limit 10

# One-hop neighbors of a record
flatbread effort relations <effortId> <fromId> --relations derives_from,superseded_by
flatbread proof relations <effortId> <fromId> --relations derives_from,superseded_by

# Single record with full body; --resolve head follows supersession to the tip
flatbread effort get <id> [--resolve head]
flatbread proof get <id> [--resolve head]
```

Flags shared by reads: `--strict-min-generation <token>` (with optional
`--timeout-ms <ms>`, default 3000) and, on `list`/`records`/`relations`, `--limit`
(≤25) and `--cursor` (opaque `next_cursor` from a prior page; only valid for
the same query at the same generation).

`effort list` is bounded Effort discovery. It defaults to `active`; valid
`proof list` is bounded Effort discovery. It defaults to `active`; valid
statuses are exactly `active`, `paused`, `completed`, and `abandoned`.
Comma-separated statuses are ORed. Results use the shared `created_at`, then
`id` ordering. After discovery, use bounded effort-scoped reads.

**Consistency:** reads are eventual by default. Immediately after a write,
pass the returned generation as `--strict-min-generation` — you get either
fresh data or an `EFFORT_GRAPH_GENERATION_WAIT_TIMEOUT` error (exit 1),
fresh data or a `PROOF_GENERATION_WAIT_TIMEOUT` error (exit 1),
never silently stale results. Do not build polling loops; the wait is
server-side.

## Recommended session workflow

1. **Resume / status briefing (bounded fast-path):** `effort list --status active`
1. **Resume / status briefing (bounded fast-path):** `proof list --status active`
and trust the returned digest. For each active Effort, run
`effort records <effortId> --kinds issue,decision` and read each record's
status/state from that one digest. Run `effort blocking-decisions <effortId>`
`proof records <effortId> --kinds issue,decision` and read each record's
status/state from that one digest. Run `proof blocking-decisions <effortId>`
only for an Effort whose digest shows an open `blocker` Issue — skip it
otherwise. Do not open raw `.flatbread-efforts/**/*.md` for briefing;
otherwise. Do not open raw `.flatbread-proof/**/*.md` for briefing;
browse digests are authoritative for status/state. Budget ≈ (1 + number
of active Efforts) digest reads. A 12-run experiment across three model
families showed this roughly halves recall tool calls with no loss of
answer quality (Decision
`dec-adopt-a-bounded-status-briefing-fast-path-for-ef--kcw0rw39g3b2ym2h`).
2. **When a browse digest shows `[…truncated]` and you need the body:** run
`flatbread effort get <id>`, then Read/grep that digest (`artifact_path`)
for the full body. Reserve opening `.flatbread-efforts/**/*.md` for rare
`flatbread proof get <id>`, then Read/grep that digest (`artifact_path`)
for the full body. Reserve opening `.flatbread-proof/**/*.md` for rare
cases (e.g. digest byte-cap miss on an oversized record), not normal
zoom-in.
3. **During work:** when outside material supports a record, save large
Expand All @@ -165,5 +165,5 @@ server-side.
they respond to.
4. **On commitment:** `AcceptDecision` (mind `rejectSiblings`), `ResolveIssue`
with `resolvedBy` citing the closing Decision/Findings.
5. Maintenance: `flatbread effort cache prune` deletes digests older than
5. Maintenance: `flatbread proof cache prune` deletes digests older than
24h / over the 100 MiB ceiling.
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Effort Graph glossary
# Proof glossary

The Effort Graph is persistent, queryable memory for long-horizon software
The Proof is persistent, queryable memory for long-horizon software
work. It builds on Flatbread's content vocabulary: each primitive is a
Collection, its instances are Records, and cross-primitive references are
Relations in frontmatter.
Expand Down Expand Up @@ -63,7 +63,7 @@ have a proposed/accepted lifecycle. They are ordinary Flatbread content:
filesystem-backed today, with other sources such as S3 or a CDN possible
later. Records do not cite Blobs directly. Instead, they cite a Citation,
which may optionally point to a Blob. Bounded digests omit Blob bodies by
default; use `effort get <blob-id>` to read the content.
default; use `proof get <blob-id>` to read the content.

## Edges

Expand All @@ -74,8 +74,8 @@ writer-materialized reverse projections.

`cites` links an Issue, Finding, Decision, Constraint, or Risk to a Citation.
It accepts Citation ids only, never Blob ids. A Citation may optionally point
to a Blob. Both links must stay within the same Effort. `flatbread effort relations` follows `cites` links, but does not follow Blob attachments; use
`flatbread effort get <blob-id>` to read an attachment.
to a Blob. Both links must stay within the same Effort. `flatbread proof relations` follows `cites` links, but does not follow Blob attachments; use
`flatbread proof get <blob-id>` to read an attachment.

New edge vocabulary needs a dogfooded query the existing vocabulary cannot
express.
Expand Down
Loading
Loading