🧾 BriefLoop

AI-assisted business briefings you can question later.

English | 简体中文

Website: briefloop.ai · Contact: [email protected]

15-Minute Pilot · Getting Started · Weekly Loop · Troubleshooting · Reference Workspace · Contact

Writer entry: use /briefloop in Claude Code, or briefloop in a shell.

---

✨ In one sentence

BriefLoop is an open-source workflow for recurring business briefings.

It does not try to be “a better prompt.” It keeps track of the process behind a brief:

• Which source did this number come from?
• Which claims were registered?
• Which checks passed or failed?
• Which reader preferences were approved by a human?
• What should be reused next time, and what should not?

When someone asks where a number came from, BriefLoop does not ask the model to improvise an explanation. It opens the ledger.

---

🧯 The problem

Many teams write the same kind of material every week:

• market updates
• industry briefings
• competitor tracking
• policy monitoring
• equity research notes
• investor-relations materials
• executive briefings
• project status reports

LLMs can draft these documents quickly. The hard part is not drafting. The hard part is trust.

Common problems:

1. Sources disappear. A number enters the final brief, and two weeks later nobody knows where it came from.

2. Small errors become confident conclusions. A weak source, stale data point, or misread paragraph can survive several editing passes and look authoritative.

3. Feedback evaporates. “Lead with the business impact,” “do not use generic wording,” or “verify this category against the original filing” often stays in someone’s head instead of the workflow.

4. Handoffs are painful. The real rules for writing the brief live with one experienced person, not in a visible process.

BriefLoop turns those hidden rules into a workflow that can be inspected, repeated, and improved.

---

👥 Who is this for?

BriefLoop is useful for:

• analysts, associates, management trainees, IR teams, strategy teams, and market-intelligence teams who write recurring briefings;
• teams that want AI-assisted writing to be traceable instead of merely fluent;
• researchers studying agent workflows, human-in-the-loop systems, and auditable AI processes.

It is not the right tool if you only want:

• a one-click pretty report generator;
• an autonomous agent that publishes without review;
• a system that proves every claim is true;
• a way to make an externally generated AI report “safe” after the fact.

---

🧱 What BriefLoop actually does

Think of BriefLoop as a briefing pipeline with ledgers.

Step	What happens	Why it matters
1. Prepare materials	Collect local files, source packs, or search results	The model should not start from nothing
2. Register claims	Important numbers, dates, entities, and claims are written into a Claim Ledger	Later you can ask where a claim came from
3. Draft by roles	Scout, Analyst, Editor, Auditor, and related roles work within boundaries	Writing becomes staged work, not one giant prompt
4. Run gates	Quality gates check source age, new facts, missing support, and delivery state	Deterministic checks do not rely on prompt memory
5. Deliver by human action	Final delivery is explicitly triggered by a human	The system does not publish or bypass review
6. Keep approved feedback	Only human-approved reader preferences are reused	“Do this next time” becomes visible and reversible

The design rule is simple:

Smart parts may write and propose. Authoritative parts must be checkable. Nothing takes effect without a human decision.

---

📚 The four questions it keeps answerable

Question	What BriefLoop records	Where to look
Where is this run?	Current stage, missing artifacts, blockers, next safe action	/briefloop status, workflow_state.json, agent_handoff.md
Where did each number come from?	Claim Ledger entries, source dates, source appendix, gate findings	claim_ledger.json, source_appendix.md, quality_gate_report.json
What has it learned?	Human-approved reader preferences only	improvement/ledger.jsonl, improvement_memory_snapshot.md
What guards delivery?	Stage-completion records, reader-final gate, delivery checks	finalize_report.json, state finalize-complete

It can observe and propose. Only what you approve is remembered, and it is remembered in a ledger you can open, audit, and undo.

---

📦 What you get from a run

A normal delivered brief is usually:

• output/delivery/brief.md
• output/delivery/<report-name>.docx

The workflow also keeps audit artifacts, such as:

• output/intermediate/claim_ledger.json
• output/source_appendix.md
• output/intermediate/quality_gate_report.json
• event_log.jsonl
• improvement/ledger.jsonl

Those audit files are not meant to be read by every end user. They exist so a team can answer questions, debug failures, review decisions, and hand the process to someone else.

---

🔎 A tiny example

A delivered brief might say:

This week, the sample PV module spot price fell 1.8% week over week,
the third consecutive weekly decline.

BriefLoop expects that claim to have a registered entry:

{
  "claim_id": "CL-0012",
  "statement": "The sample PV module spot price fell 1.8% week over week.",
  "source_id": "SRC-003",
  "evidence_text": "Example source excerpt showing the week-over-week price change.",
  "metadata": {
    "published_at": "2026-06-05",
    "source_title": "Example PV price sheet"
  }
}

If a source is stale, a number is unregistered, or an editor adds a new material fact late in the process, gates should surface the issue instead of letting it silently enter the final document.

---

🚀 Quick start

macOS / Linux

git clone https://github.com/Stahl-G/briefloop.git
cd briefloop
bash scripts/setup.sh
source .venv/bin/activate
bash scripts/demo.sh

scripts/demo.sh creates an API-free reference workspace with a final brief, Claim Ledger, Quality Panel HTML, Quality Summary, source appendix, and event-log excerpt.

For the shortest walkthrough, use the 15-Minute Pilot.

Package-index installs are not the launch path yet. pipx / PyPI packaging is tracked in pipx And PyPI Packaging Prep; do not use pipx install briefloop until release notes say a real package-index artifact has been published and smoked.

When you are ready to use your own materials, create your first briefing workspace:

briefloop onboard
briefloop init ~/briefloop-workspace --from-onboarding onboarding.json
briefloop run --workspace ~/briefloop-workspace

Common setup helpers:

briefloop init --from-onboarding onboarding.json <workspace>
briefloop sources decide --config <workspace>/config.yaml

sources decide is the explicit source-discovery helper for workspaces that use the llm_decide source profile.

Windows PowerShell

Windows does not require WSL or Git Bash. PowerShell is the recommended path.

winget install Python.Python.3.12

git clone https://github.com/Stahl-G/briefloop.git
cd briefloop

.\scripts\setup.ps1
.\.venv\Scripts\Activate.ps1

briefloop version

If PowerShell blocks script execution:

powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1

---

🤖 Claude Code path

If you use Claude Code, install the writer entrypoint:

source .venv/bin/activate
briefloop claude install --repo-workdir .

Then use the five main writer commands:

/briefloop new
/briefloop run <workspace>
/briefloop status <workspace>
/briefloop feedback <workspace> [text-or-file]
/briefloop deliver <workspace>

Good next reads:

• Getting Started
• Weekly Loop
• Troubleshooting
• Claude Code quickstart

---

🧪 Three ways to try it

Start from the product entry that matches your report:

Report job	Start with	Best for
Industry or market weekly	industry-weekly	recurring market updates, competitor tracking, policy monitoring
Management monthly	management-monthly	executive reviews, monthly operating updates, management briefing packs
Document review	document-review	reviewing a set of documents with page/source traceability

briefloop new industry-weekly ./weekly-brief
briefloop new management-monthly ./monthly-review
briefloop new document-review ./document-review

document-review prepares a document evidence review workspace. It does not make legal, compliance, or disclosure judgments.

Start with the three supported entries above. Other experimental entries are documented later for users who already understand the basic loop.

Path	Best for	What to do
Look once	You want to understand the project quickly	Run the demos and read the reference runs
Run once	You want to test it on a few local files	Create a workspace, add materials, run one brief
Use weekly	You want a recurring workflow	Configure sources, sections, reader preferences, and feedback

Optional demo commands:

bash scripts/demo.sh
bash scripts/demo-deep-dive.sh

The demos use synthetic materials. They show the evidence chain and gate behavior. Real use starts with your own workspace and sources.

---

🧭 Current status

Current version: v0.11.12

Current main entrypoints:

• CLI: briefloop
• Claude command: /briefloop
• experimental WorkBuddy / CodeBuddy guide: docs/workbuddy.md

v0.11.12 releases the accumulated v0.11 product-baseline, WorkBuddy adapter, operator-runtime, and semantic-support auditor hardening line, including:

• ReportSpec, ReportPack, ReportTemplate, and PolicyProfile contracts
• workspace skeletons and deterministic PolicyProfile resolution
• delivery / audit bundle manifests and clean bundle archives
• supported industry-weekly, management-monthly, and document-review product entrypoints
• bounded evidence_extract source/scope registration, source locks, logical page inventory seeds, and text-span seed registries
• experimental SourceHub Lite setup for local files, RSS feeds, and runtime web-search handoff tasks
• durable source evidence pack materialization and source taxonomy normalization
• internal release-mode approval records
• Quality Panel JSON / Markdown / HTML projections and audit-bundle integration
• reader-quality warning/projection surfaces for template conformance, materiality selection, support-calibrated wording, citation profiles, coverage/omission, and scoped final-abstract diagnostics
• trajectory-regulation decision narrowing for repeated retry/repair/blocker loops
• experimental source-clone WorkBuddy Skill packaging and first-use routing
• experimental source-clone CodeBuddy project Skill and role-agent handoff through --runtime codebuddy
• operator runtime for host-agnostic compact operation, with manual kept as a legacy alias
• proposal-only Semantic Support Auditor surfaces and human adjudication records that do not create support truth, gates, delivery approval, or release authority
• public-safe reference, synthetic regression, minimal comparative evaluation, launch smoke, and release checklist guardrails

These features are meant to make report types, source evidence, default policies, delivery bundles, and operator quality visibility more product-like.

These features are still contracts, metadata, defaults, setup paths, approval records, deterministic warnings, and projection controls. They do not parse PDFs automatically, execute hidden web search or crawling, judge industry compliance, detect investment advice, verify internet rumors, claim IR/disclosure readiness, prove semantic truth, publish reports, or authorize public release.

---

🚧 What it is not

BriefLoop currently does not:

• publish reports automatically;
• bypass human review;
• prove that a source semantically supports every sub-claim;
• replace legal, compliance, investment, or disclosure judgment;
• claim that generated content is ready for IR, SEC, or regulatory disclosure;
• turn unapproved feedback into long-term memory;
• promise one-click perfect reports.

The current core claim is deliberately narrow:

Traceability, not semantic proof yet. BriefLoop aims to make a briefing process traceable, reviewable, and accountable. Semantic proof and automatic judgment are future work, not current guarantees.

---

💡 Why this exists

Coding agents improved quickly because software work has infrastructure: tests, CI, git history, code review, and rollbacks.

Business briefings usually do not. A junior analyst is corrected verbally, and the correction disappears. A stale number enters a weekly report, and nobody can tell which step allowed it. A team learns what “good” looks like, but the learning stays informal.

BriefLoop brings software-engineering discipline into recurring briefing work: auditability, structured feedback, human gates, execution traces, and tests.

The goal is not to remove human judgment. The goal is to let humans spend more time judging, questioning, and advising, and less time re-checking the same preventable mistakes.

---

📖 Glossary

Term	Plain meaning
Claim Ledger	A record of important claims, numbers, sources, and dates
Source Pack	The set of materials available to a run
Quality Gate	A check that must pass before a stage or delivery can proceed
Reader Preference	Human-approved guidance such as “lead with business impact”
Improvement Ledger	The record of approved feedback
Orchestrator / 司乐师	The runtime role that coordinates stages and boundaries
Delivery Bundle	The Markdown / Word files meant for readers
Audit Artifacts	Intermediate records used for review, debugging, and accountability

---

🗂️ Useful docs

First-user path:

• Getting Started
• Weekly Loop
• Troubleshooting
• Golden reference workspace

Architecture reference and contributor docs:

• Function Map
• Golden Path
• Architecture Status
• Naming and compatibility
• Roadmap
• Red lines and anti-patterns
• Product OS reader-quality reference package
• Minimal comparative evaluation packet
• Synthetic regression pack
• Public solar integration run
• Organoid-industry failure study (中文)

---

🤝 Collaboration

This project needs real scenarios more than it needs more concepts.

You are welcome to participate if you:

• write recurring market, strategy, policy, IR, or executive briefings;
• want to pilot BriefLoop on a real workflow;
• research agent evaluation, human-in-the-loop systems, or auditable AI workflows;
• want to contribute through issues, docs, tests, or example scenarios.

Start with a good first issue. Please read red lines and anti-patterns before contributing.

For human contact, see briefloop.ai or docs/contact.md. Use [email protected] for private security reports.

---

📄 License

MIT