Briefback
Install

Open source · MIT

Make sure your agent understands before it builds.

Briefback guides your coding agent from research to reviewable code, choosing the next step as the task unfolds. Grill is the core: it challenges assumptions and settles open decisions with you before implementation starts.

Star on GitHub
Works withClaude CodeCodexCursor
~/project · briefback
❯ "Figure out how our auth works"
  ● Subagent research: tracing session middleware & schemas
  ✓ Research saved to .briefback/auth/research/

❯ "Great, let's implement OAuth migration based on this research"        
  ● Grilling architecture before writing code:

  ? 1 · Session schema: modify table or add OAuth rows?
    ▲ Risk: Altering current table invalidates active tokens
    ✓ Recommendation: Add separate oauth_accounts table

  ? 2 · Migration rollout: single commit or phased?
    ✓ Recommendation: Expand-then-contract across 2 stages

❯ "Agreed, let's go with your recommendations"        
  ● Planning 3 implementation stages:
    ├─ Stage 1 · Token schema & database models
    ├─ Stage 2 · OAuth callback & session linking
    └─ Stage 3 · Cleanup & legacy deprecation
  ✓ Plan saved to .briefback/auth/plan.md

❯ "Let's implement stage 1"        
  ● Building stage 1: token encryption & schema
  ● Subagent review: passed clean · 0 defects
  ✓ Stage 1 reviewed · ready to commit

The loop

ResearchGrillPlanStageReviewCommit

Every phase is optional and invoked in ordinary language - zero slash commands required. Run deep research, grill edge cases, or go straight to implementation: Briefback adapts to the task while keeping changes reviewable.

  1. 1
    Research

    Learn how it works

    optional

    Ask the agent to investigate an unfamiliar area. Findings that should outlive the chat are saved under .briefback/<feature>/research/ - ready to attach in a fresh session.

  2. 2
    Grill

    Sharpen the idea

    core

    The agent surfaces assumptions, explains trade-offs, and recommends answers in conversation - until nothing important is left unclear.

  3. 3
    Plan

    Plan the stages

    Larger work is split into coherent stages: each one has a clear outcome, a practical check, and a fresh chat can pick it up. Saved to .briefback/<slug>/plan.md.

  4. 4
    Implement

    Implement one stage

    The first unchecked stage and nothing beyond it. Stay in this chat, start a fresh one, or write code directly - the plan travels with you.

  5. 5
    Review

    Subagent review

    A subagent reviews the stage with what changed and why. Defects and safe refactors are fixed in place; product and contract calls come back as decisions for you.

  6. 6
    Commit

    Your review, then commit

    Read the diff yourself, then commit the way you always do. Git and pull requests remain the center of the workflow.

  7. 7
    Handoff

    Refresh the context

    optional

    When the chat gets noisy, handoff saves what shipped, what changed, and which stage comes next. Attach it to a fresh chat and continue.

    Steps 4–6 repeat until every stage in the plan ships

  8. 8
    Document

    Archive or document

    optional

    Turn the shipped change into a durable project page for the next session - or skip it when no page is needed.

Two paths

One prompt. Two different outcomes.

A real task from production: adding project duplication. See how an unguided agent drifts into silent bugs and tangled diffs, versus how Briefback engineers clean, verified PRs.

The identical starting prompt
human input
❯ "Let's implement project duplication so users can duplicate an existing project."
Phase 01

Codebase Discovery

Before touching code: does the agent investigate existing architecture?

Without Briefback
0 research · Blind leap

Rushes straight into modifying files

Starts editing code without reading database schemas, S3 asset references, or platform host uniqueness rules.

● Unguided Agent: "Sure! Creating the duplication endpoint, copying S3 buckets, and configuring new custom domains now..."
Msrc/server/routes/projects.ts
Msrc/db/schema.prisma
Msrc/components/editor/ForkModal.tsx

Blindly edits 3 critical files simultaneously on raw assumptions.

With Briefback
System research · Constraint discovery

Uncovers hidden constraints and risks

Inspects schemas, writes structured research docs into .briefback/, and catches critical constraints before writing code.

● Subagent research: tracing schemas & storage

1. Traced storage schema: S3 assets linked via d_files claim IDs
2. Audited cascade routes: projects, workspaces, custom domains
▲ Hidden constraint: deleting original project purges shared S3 files!

✓ Research saved to .briefback/project-duplication/research/
  ├─ storage-lifecycle.md (S3 multi-claim reference map)
  └─ domain-routing.md (ingress collision risks)

Pausing code edits to clarify trade-offs with developer
Phase 02

Architectural Decisions

When forks arise: does the agent guess in secret or clarify with options?

Without Briefback
0 questions · Silent guesswork

Hallucinates assumptions that break data

Makes catastrophic architectural choices in secret without confirming with the developer:

S3 Data Loss:Links fork directly to original S3 URLs without multi-claim tracking. Deleting the original project will permanently purge assets in the fork.
Host Collision:Auto-generates duplicate domain DNS configs, colliding with platform host uniqueness rules.
With Briefback
Proactive inquiry · Settled plan

Surfaces critical forks & locks contract

Translates research into targeted questions with recommended paths, then locks decisions in a plan:

● Agent: "Before I write code, I found a critical S3 storage constraint. Let's settle two architectural forks:"
? Q1 - Asset storage: share S3 claims or duplicate file bytes?
✓ (b) Share claims via d_files + patch delete trigger [Recommended]
? Q2 - Custom domains: how should routing behave on fork?
✓ (a) Duplicate project only; defer domain to manual publish [Recommended]
Developer approved recommendationsLocked into 2 stages
Phase 03

Execution & Review

When shipping: is it a massive unreviewed dump or verified stages?

Without Briefback
Monolithic dump · 0 reviews

One tangled 48-file change set

A massive, chaotic change set mixing frontend buttons, DB schemas, broken migrations, and hardcoded tokens:

48 files modified+1,840 / -620 lines
✕DB migrations, UI buttons, and runner sync tangled together
✕Hardcoded runner tokens committed directly in clone script
✕Zero subagent review or automated verification before handoff
With Briefback
Staged loop · Self-auditing

Build StageReviewCommitNext Stage

Executes in small, isolated stages. Each one is reviewed by a subagent before the next begins:

PR #1 · Storage safetymerged

Patched deletion to retain shared S3 claims. Isolated migration.

PR #2 · Duplicate APImerged

POST /duplicate endpoint with safe rollback and sanitized tokens.

Subagent review passed clean on each stage
Phase 04

Final Outcome

What actually lands in the repository?

Without Briefback
Crooked commit · Revert required

Unmergeable code, wasted engineering time

The implementation is dangerous to merge. The developer must roll back the branch and start over from scratch.

Result: Revert required · 0 PRs merged

Hidden S3 deletion bug would destroy user assets. All 48 files reverted.

With Briefback
Production-ready · Merged

Two clean PRs with zero regressions

Every edge case accounted for, shared S3 storage 100% safe, clean git history, and ready for production deployment.

Result: Ready to deploy · 2 discrete PRs

2 bite-sized PRs, 0 lost bytes, verified review loop, and 100% human control.

Without Briefback: 48 files scrambled

Zero questions asked upfront. S3 lifecycle broken, domain rules ignored, and hours spent undoing a messy commit.

With Briefback: 2 verified, bite-sized PRs

Codebase researched and architectural forks settled before line 1 of code. Safe S3 reuse, self-auditing reviews, and total human control.

The capabilities

One skill. Seven modes.

Briefback installs as one skill. Describe your task in ordinary language - the agent selects the relevant mode and delivers in reviewable stages.

Research

Explore unfamiliar code and save findings to .briefback/research/

Grill

Question assumptions and clarify architectural trade-offs in chat

Plan

Divide larger work into coherent, reviewable stages

Code review

Subagent audits the stage for defects, risks, and regressions

Handoff

Pass context seamlessly when continuing work in a fresh session

TDD

Work through one red-green test slice at a time

Document

Turn completed work into permanent project documentation

Install Briefback once into the agents you already use.

The principles

What Briefback believes

Specs ≠ shipped code

Research, plans, and handoffs are working artifacts first. Commit them, keep them local, or delete them after the PR - Briefback never prescribes their lifetime.

Ceremony is a tax

No spec tree to adopt, no commands to learn before code starts. You clarify the task and the agent carries the workflow from there.

Discipline lives in the loop

Decisions settle before implementation. Scope stays one reviewable stage, and that stage is reviewed before the next begins. Optional phases can be skipped - the order cannot.

Compare

Not an all-in-one system

Spec-driven frameworks move intent into documents and drive the agent from them. Briefback adds a small, opinionated loop to the way you already build software.

vs OpenSpec

OpenSpec manages proposals, requirements, designs, and completed changes - when specs are the center of the process. Briefback uses Grill to settle decisions and writes a plan when the work needs durable coordination.

vs Spec Kit

Spec Kit runs a full phase-based process - constitution, specs, plans, tasks. Briefback starts from an ordinary task and selects phases as needed.

vs unstructured chat

Fine for a small fix. On larger changes, chat loses decisions and grows unreviewable scope. Briefback keeps both out of history - one stage at a time.

Install

One command, then just work

Pick the agents you use, choose project or global scope, and let Briefback guide your next task.

Init installs the skill through the skills CLI, then asks whether to set up docs - it writes BRIEFBACK.md and adds a pointer to AGENTS.md. Updates are non-interactive after setup.