Four-tool walkthrough¶

Ask one question across Google Workspace, Jira, GitHub and Gcloud: “Can the New website launch, what remains, and why did we choose one page?” This walkthrough collects each tool's evidence into one brain, records the answer in the project, then shows BF flagging that answer when Jira changes.

The four records are fictional fixtures: no provider account, credential, network access or model is needed. URLs under example.test are illustrative. Complete Getting started first, including its collection exercise: this walkthrough combines sensors, field mappings and identities.

Get the example¶

You need Linux or macOS, BF, Git and python3. Copy the example from the release matching your installation into a disposable folder:

context_demo=$(mktemp -d)
git clone --quiet --depth 1 --branch "v$(bf --version)" https://github.com/fmind/brain-framework.git "$context_demo/source"
cp -R "$context_demo/source/examples/context-hub" "$context_demo/brain"
cd "$context_demo/brain"

The brain holds a minimal project note, bf.yaml and a small sensor, sensors/demo.py, that prints fixtures/TOOL.json as if each tool had returned it. Review both before running anything. From a source checkout, copy examples/context-hub instead and run each bf command as uv run --project CHECKOUT bf, where CHECKOUT is the checkout's path.

Collect four tools¶

bf collect workspace
bf collect jira
bf collect github
bf collect gcloud
bf read project:new-website

Each collection reports "records":1. project:new-website is the project note's alias, so the read opens the note. Its backlinks group the four records under the shared project relation, each with its fields side by side:

{
  "relation": "project",
  "total": 4,
  "items": [
    { "ref": "gcloud:deployment", "fields": { "kind": "deployment", "status": "healthy" } },
    { "ref": "github:implementation", "fields": { "kind": "pull-request", "status": "merged" } },
    { "ref": "jira:review", "fields": { "kind": "issue", "status": "In review" } },
    { "ref": "workspace:brief", "fields": { "kind": "brief", "status": "approved" } }
  ]
}

The previews already answer most of the question. Read the blocking record and check the brain:

bf read jira:review
bf validate
bf eval

The Jira review says launch is blocked until the keyboard navigation check passes. Validation reports "valid":true, and the example's retrieval cases report "score":"10/10". The evidence supports a precise answer: the implementation is merged and its preview is healthy, but accessibility review still blocks launch. A healthy deployment alone cannot establish launch readiness. These reads reuse the saved records: no sensor runs again.

How the four tools share one project¶

Each tool names its project and state differently. bf.yaml maps them into the same shared fields:

For example, the Jira part of the configuration:

# https://fmind.github.io/brain-framework/docs/schema/
fields:
  project:
    description: Project explicitly identified by the source.
    type: identity
    cardinality: one
    relation: true
sensors:
  jira:
    command: [sensors/demo.py, jira, "{{end}}"]
    mode: snapshot
    fields:
      project: { path: /attributes/workstream }
      kind: { value: issue }
      status: { path: /attributes/status }

At collection, BF validates each mapped value, stores it under the record's fields and turns project into a relation to project:new-website. The mapping runs automatically; its meaning is configured by you. BF never guesses that similar names identify the same project. See field mappings.

Record the conclusion¶

Write what the reads establish into the owning project, dated today:

cat > projects/new-website.md <<EOF
---
type: project
status: draft
updated: $(date +%F)
aliases: [project:new-website]
summary: Launch a product website that explains the product before signup.
---

# New website

## Decision

Start with a single product page: visitors need a clear explanation before signing up. Evidence: [Workspace brief](workspace:brief).

## Launch review

Hold public launch. The [implementation](github:implementation) is merged and the [preview](gcloud:deployment) is healthy, but the [launch review](jira:review) still blocks launch on the keyboard navigation check.

## Next actions

- [ ] Run the keyboard navigation check.
EOF
bf read

The home page lists the project under projects, with its new next task; changed names other notes changed this week. It is not flagged for review: no linked evidence is newer than the edit.

Follow a change¶

In the fictional tracker, the keyboard navigation check passes and the review moves to Done. Swap in the tracker's next fixture and collect Jira again. Like a good record, the fixture keeps the issue's event time and records the change in attributes.updated; its value now makes the demo sensor date the change at collection, as a tracker reports a transition that just happened:

cp fixtures/jira-done.json fixtures/jira.json
bf collect jira
bf read
bf read jira:review

Collection reports "updated":1. The home page now flags the project: the Jira review linked to it changed upstream after its last edit, and newer names the record to read:

{
  "ref": "projects/new-website.md",
  "review": true,
  "review_reasons": ["newer_evidence"],
  "new_links": 1,
  "newer": ["jira:review"],
  "next": "Run the keyboard navigation check."
}

The Jira record's fields now hold "status":"Done". The saved conclusion is out of date: update the Launch review and Next actions, and the flag clears with the edit. This is the loop BF supports: gather, connect, act, learn, and notice when evidence moves on.

Give a terminal agent the same context¶

Print the demo path with echo "$context_demo/brain". In a fresh terminal-agent session, replace ABSOLUTE_DEMO_PATH in this prompt:

Work in ABSOLUTE_DEMO_PATH and use the bf CLI. Read project:new-website, then the Workspace, Jira, GitHub and Gcloud records supporting it. Can the website launch, what remains, and why did we choose one page? Cite each supporting ref and separate recorded facts from inference. Report incomplete or outdated evidence. Do not collect, fetch source URLs or change files.

No skill or MCP setup is needed for this first task. Check the tool history: the agent should read the records and cite the Jira review before answering. A plausible answer without those reads does not verify access. Install the skills to make the procedure available in every session. A cloud agent's provider may receive what the agent reads.

Remove the disposable copy when you are done:

cd
rm -rf -- "$context_demo"

Use it on your work¶

Choose one recurring question whose answer spans tools. Keep the decision in its project note and collect only the evidence the question needs:

A sensor is a script printing JSON records; provider tools own authentication. Your script owns scope, complete pagination, output bounds, failures and identity normalization. Test it with fake provider output before collecting, as the sensor guide describes. The team pilot checks whether the loop helps people in practice.