claude - freeCodeCamp.org

How to Export a Claude Conversation as a PDF

Vikram Aruchamy — Mon, 06 Jul 2026 13:56:14 +0000

Whether you're documenting research, sharing AI-generated content with colleagues, creating reports, or keeping an offline backup, saving Claude conversations as PDFs is one of the easiest ways to preserve your work.

While Claude lets you export your account data for archival purposes, it doesn't currently include a built-in option to export an individual conversation directly as a PDF. As a result, users often rely on browser printing, document editors, Claude Artifacts, share links, or dedicated Claude to PDF tools depending on their workflow.

In this guide, you'll learn the most effective ways to convert Claude conversations into PDFs, including the advantages, limitations, and best use cases for each method.

Whether you need to save a single conversation, export a Claude Artifact, archive your entire conversation history, or preserve formatting in code- and image-heavy conversations, you'll find the approach that best fits your needs.

How to Save Claude Conversations as a PDF Using the Browser Print Option
How to Copy Claude Responses into Google Docs and Save Them as PDFs
How to Convert Claude Share Links into PDFs
How to Export Claude Artifacts as PDFs
How to Download All Claude Conversations from Settings
How to Choose the Best Export Method
Video Tutorial: How to Export a Claude Conversation as PDF
Conclusion

How to Save Claude Conversations as a PDF Using the Browser Print Option

The browser's built-in Print feature is the quickest way to convert a Claude conversation to PDF. It works in all modern browsers, requires no additional software, and is suitable for most one-time exports of conversations that are text-heavy, with limited images and interactive content.

Depending on your preferred workflow, you can rely on this native method or use a simple Claude to PDF Chrome Extension to export your conversation.

How Browsers Generate PDFs From Web Pages:

When you use your browser's Print feature, it doesn't take a screenshot of the page. Instead, the browser renders the page specifically for printing by processing its HTML and CSS.

Websites can also provide a print stylesheet — a set of CSS rules that changes how the page appears on paper or in a PDF.

A print stylesheet can hide navigation menus, buttons, sidebars, advertisements, and other interactive elements while optimizing the layout for printing. If a website doesn't define print-specific styles for certain elements, the browser prints them as they appear on the page.

This is why buttons such as Copy, Share, and other Claude interface controls may appear in the exported PDF when you use this option to export the conversation as pdf.

Now, lets see the steps to print the conversation to PDF.

Step 1: Open the Browser's Print Dialog

Open the Claude conversation you want to export.
Scroll through the conversation to ensure all responses have finished loading.
Press Ctrl + P (Windows/Linux) or ⌘ + P (macOS), or select Print from your browser's menu.

Step 2: Save the Conversation as a PDF

In the print dialog:

Set the destination to Save as PDF.
Choose the pages you want to export (optional).
Select a location to save the PDF.
Click Save.

Step 3: Adjust the Print Settings

Before saving the PDF, review the available print settings. Most browsers provide these options under More settings. The following image shows the print settings.

Let's go over a few of these:

Margins

Leave the margins set to None for most conversations. If wide code blocks or tables are clipped, switch to Minimum margins to use more of the page width.

Scale

Keep the Scale as Actual size If long lines of code extend beyond the page width, reduce the scale slightly so the content fits on the page.

Background graphics

By default, browsers don't print background colors. If you want to preserve the background styling used for code blocks and other interface elements, enable Background graphics.

Headers and footers

This option is disabled by default. If you'd like the PDF to include the page title, URL, date, and page numbers, enable Headers and footers.

Advantages:

Available in every modern browser.
Requires no additional software.
Works entirely on your device.
Suitable for quickly exporting individual conversations.

Limitations:

Long conversations may generate very large PDFs with awkward page breaks.
Long code blocks can wrap or split across pages.
Wide tables may be compressed or clipped.
Large images may be resized or moved across pages.
Interface elements such as Copy, Share, and other Claude controls may appear in the exported PDF if they are not hidden by Claude's print stylesheet.
Embedded Artifacts may not be fully captured and often need to be exported separately.

For short conversations, browser printing is usually sufficient. For conversations containing extensive code, large images, complex tables, or Artifacts, the other methods we'll discuss next generally produce better results.

How to Copy Claude Responses into Google Docs and Save Them as PDFs

If you only need to export a single Claude response, you can use Claude's built-in Copy button. Unlike browser printing, this method copies the response as Markdown, preserving headings, lists, tables, code blocks, links, and other formatting.

Click the Copy button located below the response. Claude copies it to your clipboard as Markdown, making it easy to import into applications that support the Markdown format.

Then open a Google Docs document. If this is your first time using Markdown import, go to Tools → Preferences and enable Markdown. This option is disabled by default.

Once enabled, select Edit → Paste from Markdown (or right-click and choose Paste from Markdown) to import the copied content.

Google Docs automatically converts the Markdown into a formatted document, preserving most elements such as:

Headings
Bullet and numbered lists
Tables
Code blocks
Blockquotes
Hyperlinks

Review the imported document before exporting it, especially if it contains complex tables, nested lists, or long code blocks. Minor formatting adjustments may be required depending on the content.

Once you're satisfied with the document, select File → Download → PDF Document (.pdf) to generate the PDF.

Advantages:

Produces a clean document without Claude's interface elements.
Preserves document structure better than browser printing.
Allows you to edit the content before exporting.
Uses built-in features available in Claude and Google Docs.

Limitations:

Suitable for exporting individual Claude responses, not entire conversations.
Images and interactive content may require manual adjustments.
Complex layouts may need minor formatting cleanup before exporting.

If you don't need to edit the response, you can also convert the copied Markdown directly using a Markdown to PDF converter online tools, eliminating the need to import it into Google Docs first.

Claude lets you create a public Share Link for any conversation. Once a conversation is shared, anyone with the link can view it in a web browser without signing in to your account.

Share Links are a convenient way to convert conversations into PDFs using free online tools, such as a Claude to PDF converter that accept a Claude Share Link and generate a downloadable PDF. They automate the conversion process and produce cleaner page layouts with fewer manual adjustments.

To create a Share Link:

Open the conversation you want to export.
Click the Share button from the top right.
Choose the Create public link option.
Copy the generated URL.
Enter the URL in the free tool text box, and your entire conversation will be downloaded as a PDF file.

This method is most appropriate when you want to generate a cleaner PDF from a publicly accessible conversation.

Note: Because Share Links are publicly accessible, avoid using this method for conversations containing confidential, personal, or sensitive information. Anyone with the link can view the shared conversation until the Share Link is revoked or deleted from your Claude account.

How to Export Claude Artifacts as PDFs

Claude Artifacts are standalone outputs that Claude generates alongside a conversation. Unlike regular chat messages, Artifacts open in a dedicated panel and are designed for working with larger pieces of content such as documents, code, web pages, and diagrams.

Common Artifact types include:

Documents
Markdown files
HTML pages
Source code
SVG graphics

If an Artifact supports PDF export, this is the easiest way to create a PDF. Open the Artifact and click Download as PDF option from the toolbar as shown in the following image:

Claude generates the PDF directly from the Artifact, producing a cleaner result than printing the entire conversation.

This approach is particularly useful for content that is intended to be read as a standalone document, such as reports, articles, technical documentation, or Markdown files.

Keep the following considerations in mind:

The PDF contains only the Artifact, not the surrounding conversation.
If a conversation contains multiple Artifacts, each one must be exported separately.
Interactive HTML Artifacts are exported as their rendered output, so interactive behavior isn't preserved in the PDF.
Code Artifacts retain their formatting, although very long lines may wrap depending on the page width.
Large SVG graphics may be scaled to fit the page size.

If your goal is to preserve the conversation itself, including prompts, responses, and the generated Artifact, you'll need to use one of the conversation export methods covered in this guide.

How to Download All Claude Conversations from Settings

If you want to archive your entire Claude account instead of exporting individual conversations, Claude's Export Data feature is the most comprehensive option. Rather than generating PDFs, Claude exports your account as a ZIP archive containing JSON files that preserve your complete conversation history.

To request an export:

Open Claude.
Go to Settings.
Select Export Data.
Request the export.
Download the ZIP archive when you receive the email.

The exported archive may contain:

Conversations
Projects (if applicable)
Account information
Other account data

Unlike browser printing, the conversations are stored as structured JSON rather than formatted documents.

A typical conversation file has the following structure:

Conversation
├── uuid
├── name
├── summary
├── chat_messages
│   ├── sender
│   ├── created_at
│   ├── content
│   │   ├── type
│   │   └── text
│   └── attachments

The fields at the top of the file contain metadata about the conversation, while the actual conversation is stored inside the chat_messages array. Each message records:

sender: Whether the message was written by the user or Claude.
created_at: When the message was created.
content: One or more content blocks.
type: The content type, such as text.
text: The actual conversation text.

If your goal is simply to read or archive the conversation, you can ignore most of the metadata and extract only the text field from each message.

The following Python script converts an exported conversation into a simple Markdown document by extracting only the conversation text.

import json

with open("conversation.json", "r", encoding="utf-8") as f:
    conversation = json.load(f)

print(f"# {conversation['name']}\n")

for message in conversation["chat_messages"]:
    sender = message["sender"].capitalize()

    for block in message["content"]:
        if block.get("type") == "text":
            print(f"## {sender}\n")
            print(block["text"])
            print()

The generated Markdown can then be:

Imported into Google Docs using Paste from Markdown.
Converted with a Markdown-to-PDF converter.
Archived in a Git repository or knowledge base.
Indexed by documentation tools.

This method is the best choice when you want to preserve your entire Claude history in a formatted document. It isn't intended for quickly exporting individual conversations as PDFs, but it provides the highest-fidelity archive of your data.

How to Choose the Best Export Method

Each export method serves a different purpose. The right choice depends on whether you're exporting a single response, an entire conversation, a Claude Artifact, or your complete account history.

Method	Best For	Advantages	Limitations
Browser Print	Quick one-time exports	Built into every browser, no additional tools required	Includes Claude interface elements, limited formatting control
Google Docs	Editing before exporting	Produces a clean, editable document with good formatting	Best suited for individual Claude responses
Claude Artifacts	Exporting generated documents, code, or HTML	Preserves the original artifact content	Doesn't export the entire conversation
Claude Share Links	Converting publicly shared conversations	Cleaner output than printing the Claude interface	Requires creating a public Share Link
Account Data Export	Backing up all conversations	Exports your complete conversation history for archival	Produces JSON files rather than readable PDFs

Use the following recommendations to choose the most appropriate method:

Quickly saving a single conversation: Use the Browser Print option.
Editing the content before exporting: Copy the response into Google Docs and export it as a PDF.
Saving a Claude Artifact: Export or print the Artifact directly.
Backing up your entire Claude account: Use Account Data Export from Claude Settings.
Preserving formatting for long or complex conversations: Use a dedicated Claude to PDF tool designed for exporting conversations.

Video Tutorial: How to Export a Claude Conversation as PDF

Conclusion

Although Claude doesn't currently offer a native option to export individual conversations as PDFs, it's possible to achieve the same result using browser printing, Google Docs, Claude Artifacts, Share Links, or the built-in account export feature. Each method has its own trade-offs in terms of formatting, convenience, and intended use.

If you're looking for a more streamlined workflow, especially for exporting conversations with code blocks, tables, images, and long responses, you can also use a dedicated Claude to PDF tool that automates the process and produces cleaner PDFs with minimal manual effort.

Codex vs Claude Code: Which AI Coding Assistant to Choose

Manish Shivanandhan — Thu, 02 Jul 2026 16:54:03 +0000

AI coding assistants have evolved from simple autocomplete tools into capable development agents that can write code, debug applications, refactor projects, and even execute complex workflows.

Among the newest generation of tools, OpenAI's Codex and Anthropic's Claude Code have emerged as two of the strongest options for developers.

Both platforms promise to improve productivity, reduce repetitive work, and help teams ship software faster. But they approach software development differently.

Choosing between them depends less on finding a universal winner and more on understanding which tool aligns with your workflow, team structure, and development goals.

Understanding Codex

Codex is OpenAI's dedicated coding agent designed to assist developers throughout the software development lifecycle.

Unlike earlier code generation tools that focused mainly on snippets and autocomplete, modern Codex operates more like an autonomous development partner.

It can understand large codebases, generate new features, fix bugs, review existing implementations, and work on multiple tasks simultaneously.

OpenAI has expanded Codex beyond a simple command-line experience, introducing desktop and cloud-based environments that allow developers to delegate work while continuing with other responsibilities.

According to OpenAI, Codex can read, edit, and run code while operating in its own environment to complete assigned tasks. This makes it particularly useful for teams that want an AI assistant capable of handling longer-running assignments independently.

Understanding Claude Code

Claude Code takes a different approach. Rather than emphasising autonomous execution, Anthropic has focused heavily on developer collaboration and reasoning quality.

Claude Code functions as a terminal-native assistant that integrates directly into existing workflows. Developers can interact with it conversationally while maintaining close oversight of the coding process.

The tool is particularly strong at explaining architectural decisions, reviewing unfamiliar codebases, and helping developers work through complex implementation challenges. Instead of simply generating solutions, Claude Code often provides context that helps engineers understand why a particular approach may be preferable.

This makes Claude Code attractive for developers who view AI as an intelligent collaborator rather than an independent coding agent.

Codex vs Claude Code: Direct Comparison

The Difference in Philosophy

The biggest distinction between Codex and Claude Code lies in their approaches to autonomy.

Codex is designed to execute delegated work efficiently. Developers describe objectives, and the system attempts to complete them with minimal intervention. It excels in situations where productivity and task completion are the primary objectives.

Claude Code, on the other hand, prioritises interaction. It keeps developers closely involved in the decision-making process and often produces explanations alongside implementation suggestions.

Neither philosophy is inherently better.

Teams building products under tight deadlines may benefit from Codex's autonomous capabilities. Developers working on complex systems that require thoughtful design discussions may prefer Claude Code's collaborative style.

Code Quality and Reasoning

When evaluating coding assistants, raw output quality matters.

Claude Code has earned a reputation for producing clean, maintainable code with strong architectural awareness. It often breaks larger problems into logical components and provides reasoning that helps developers understand the trade-offs involved.

Codex tends to optimise for execution and efficiency. Its outputs frequently focus on accomplishing the requested task with minimal overhead while maintaining practical production considerations.

Comparative testing has shown that Claude Code often excels in documentation tasks and feature design. Codex demonstrates strong consistency across multiple categories of development work. Research analysing thousands of pull requests found that no single agent dominated every software engineering task, reinforcing the idea that context matters when selecting a tool.

Workflow Integration

The way an AI coding assistant fits into your existing development process can significantly impact adoption and long-term value.

Claude Code is built around a terminal-first experience, allowing developers to interact with the model directly within familiar command-line environments. This makes it particularly appealing to engineers who prefer maintaining close control over implementation decisions while receiving real-time guidance and feedback.

Codex takes a different approach by emphasising automation and delegation. Developers can assign coding tasks and review the completed work later, making it well-suited for teams looking to reduce repetitive workloads and improve development velocity. This model can be especially useful in larger organisations where engineers frequently juggle multiple projects and priorities.

Ultimately, the right choice depends on how your team prefers to work. Developers seeking an interactive coding companion may gravitate toward Claude Code, while organisations focused on streamlining execution may find Codex a better fit within their existing workflows.

Deployment Options

Writing code is only part of the software development process. Once an application is complete, developers still need a reliable way to test, deploy, and maintain it in production.

Whether you use Codex or Claude Code, the deployment workflow remains largely the same. AI coding assistants can generate production-ready applications, but they don't replace the infrastructure needed to host them.

Developers still need platforms like Vercel, Hostinger and Railway that support automated deployments, scalable environments, SSL certificates, backups, monitoring, and straightforward rollback options.

For teams looking to deploy apps built with Claude, platforms like AWS and Vercel make it easier. They integrate continuous delivery pipelines while providing the reliability expected from production systems.

The same applies when you try to deploy apps built with Codex. Services such as Hostinger simplify deployments with managed Node.js hosting, Git integration, and built-in security features, allowing developers to move from AI-generated code to a live production environment with minimal configuration.

As AI coding assistants become part of everyday development workflows, selecting the right production hosting for AI coding assistants is becoming just as important as choosing the coding tool itself. The best workflow combines an intelligent development assistant with infrastructure that makes shipping software fast, reliable, and repeatable.

Productivity Considerations

One of the primary reasons organisations adopt AI coding assistants is to improve development velocity.

Codex often shines when repetitive or well-defined tasks dominate the workload. Generating boilerplate code, implementing straightforward features, writing tests, or executing multi-step workflows are scenarios where autonomy can deliver meaningful time savings.

Claude Code provides value during exploratory development. Developers can brainstorm implementation approaches, validate assumptions, and receive guidance while preserving human oversight.

The productivity gains from each tool depend heavily on how teams allocate engineering effort.

Organisations emphasising rapid delivery may prioritise Codex.

Teams prioritising knowledge sharing and architectural consistency may lean toward Claude Code.

Security and Oversight

As AI agents gain more capabilities, governance becomes increasingly important.

Claude Code's interactive design naturally encourages human review before significant actions occur. This reduces the likelihood of unintended modifications and reinforces developer accountability.

Codex introduces stronger automation capabilities, which can accelerate workflows but also require clearly defined operational safeguards. Organisations adopting autonomous coding agents should establish review processes, permission controls, and testing requirements before integrating them into production environments.

The goal is not to eliminate human involvement but to position AI appropriately within existing software development practices.

Should you Choose Codex or Claude Code?

The answer depends on how you work.

Choose Codex if your team values autonomy, wants to delegate substantial development tasks, and needs an assistant that can operate independently across multiple assignments. Organisations focused on maximising throughput may find this approach particularly compelling.

Choose Claude Code if you prefer collaborative problem-solving, appreciate detailed reasoning, and want AI assistance that remains closely integrated with human decision-making throughout the development process.

Neither assistant replaces engineering judgment. Instead, they amplify different aspects of software development.

Final Thoughts

The debate between Codex and Claude Code reflects a broader shift within software engineering. AI assistants are no longer limited to suggesting individual lines of code. They're evolving into sophisticated development partners capable of influencing planning, implementation, testing, and deployment.

Codex emphasises execution. Claude Code emphasises collaboration.

For some teams, Codex will unlock significant productivity gains by handling routine work autonomously. For others, Claude Code will enhance decision-making by serving as an intelligent coding companion.

Ultimately, the best choice is the one that complements your team's existing strengths and addresses its most significant bottlenecks.

As AI continues to reshape development practices, the organisations that succeed will not necessarily be those using the most advanced tools. They will be the ones who integrate those tools thoughtfully into well-defined engineering processes.

Hope you enjoyed this article. You can connect with me on LinkedIn.

How to Use Claude Code to Build Flutter Apps Faster — Best Practices for 2026

Jesutoni Aderibigbe — Mon, 29 Jun 2026 14:05:14 +0000

In early 2023, I was interning at a US-based company, long before agentic AI became part of everyday development.

We had tools like ChatGPT, Gemini, and Copilot, but they were mostly chat interfaces: you pasted code, got a response, and moved on.

During that time, my manager, who worked in AI/ML, told me that a day would come when developers would collaborate with AI agents and that learning how to write effective prompts would become a valuable skill.

I took that advice seriously. I spent countless nights experimenting with prompts, refining instructions, and learning how to communicate with AI systems effectively.

Today, while I still write code by hand and believe strongly in fundamentals, those early lessons have paid off. In an era where AI is embedded into the development workflow, I've been able to leverage it to significantly amplify my productivity as a software engineer.

You've probably seen all the excitement around AI coding assistants. But if you've tried using one on a real Flutter project, whether it's a fintech app, an e-commerce platform, or any application with a well-structured architecture, you've likely experienced the frustration, too.

The assistant generates a widget. You paste it in. It doesn't fit your architecture. It ignores your naming conventions. It recreates functionality that already exists somewhere else in your codebase. Before long, you've spent twenty minutes fixing code that was supposed to save you time.

The problem isn't the AI. The problem is that most developers still use AI as an advanced autocomplete tool when it can function as something much more powerful: a second engineer that understands your codebase, follows your conventions, and tackles parallel tasks while you focus on solving the hard problems.

In this article, I'll show you what has actually worked for me. We'll cover how to structure your Flutter projects so Claude Code can navigate them effectively and how to use skills, loops, and subagents to automate repetitive development tasks and dramatically increase your productivity.

Prerequisites

Before following along, you should be comfortable with the basics of Flutter development; building widgets, managing state, and running the app from the terminal. You don't need to be an expert.

On the tooling side, you'll need:

Flutter SDK (3.x or later): the framework we're building with. Install it from flutter.dev.
Claude Code: Anthropic's agentic coding tool that runs in your terminal alongside your editor. Install it with npm install -g @anthropic-ai/claude-code, then run claude in your project directory to start a session. You'll need an Anthropic account and API key.
A code editor: VS Code or Android Studio both work well. Claude Code operates in the terminal and reads/writes files directly, so it works alongside whatever editor you use.
Git: version control is assumed throughout. Claude Code integrates with Git for commits, diffs, and branch awareness.

Here's a quick overview of the Claude Code concepts we'll use throughout the article:

CLAUDE.md: a markdown file at your project root that Claude reads at the start of every session. Think of it as a briefing document: your architecture, your conventions, your commands.
Skills: reusable instruction packs stored in .claude/skills/. You define them once, and Claude invokes them automatically when the task matches, or you call them manually with /skillname.
Subagents: isolated Claude instances that handle a focused task in their own context window, then return only a summary. Great for parallel work without polluting your main session.
Hooks: shell commands or scripts that fire on lifecycle events (before a tool runs, after a turn completes, and so on). They bypass Claude's judgment entirely — useful for enforcing rules deterministically.
/loop: a built-in skill that reruns a task repeatedly until a condition you define is met.

None of these require special configuration to unlock. They’re all available once you have Claude Code installed.

1. Why Architecture Comes First
2. Setting Up Your CLAUDE.md
3. Feature-First Folder Structure — The Details
4. Writing Skills for Your Most Repeated Tasks
5. Using /loop for Self-Correcting Workflows
6. Subagents for Parallel Screen Development
7. Hooks — Enforcing Rules Deterministically
8. Putting It All Together: A Real Sprint Workflow
Key Takeaways

1. Why Architecture Comes First

Before you write a single skill or configure a single hook, your folder structure needs to make sense to an AI reading it cold.

Claude Code reads your files to understand your project. If your code is scattered across a layer-first structure (lib/models/, lib/services/, lib/widgets/), Claude has to piece together what each feature does by jumping between folders. It makes mistakes. It creates files in the wrong place. It generates code that doesn't conform to the pattern used in the rest of the app.

The fix is a feature-first structure. Each feature is a self-contained module. Everything Claude needs to understand the transfer flow, for example, lives inside lib/features/transfer/.

lib/
├── core/
│   ├── constants/
│   ├── errors/
│   ├── router/
│   └── theme/
├── features/
│   ├── auth/
│   │   ├── data/
│   │   │   ├── models/         # Freezed models
│   │   │   └── repositories/
│   │   ├── presentation/
│   │   │   ├── screens/
│   │   │   ├── widgets/
│   │   │   └── providers/      # Riverpod providers
│   │   └── auth.dart           # barrel export
│   ├── transfer/
│   │   ├── data/
│   │   ├── presentation/
│   │   └── transfer.dart
│   └── wallet/
│       ├── data/
│       ├── presentation/
│       └── wallet.dart
└── main.dart

This structure tells Claude immediately: "Everything for the transfer feature is in lib/features/transfer/"When you ask it to 'add a beneficiary validation to the transfer flow,' it knows exactly where to look and where to create new files.

It also maps cleanly to Riverpod with code generation. Each feature's providers live close to the screens that use them, which means build_runner output lands in the right place, too.

2. Setting Up Your CLAUDE.md

CLAUDE.md is arguably the most important file in your Claude Code setup. It's loaded at the beginning of every session. It remains in context throughout the conversation, helping Claude stay aligned with your project's architecture, conventions, and development practices no matter how long the session becomes.

Create it at the root of your project:

touch CLAUDE.md

Here's a template shaped for a Flutter/Riverpod project:

# My Flutter App

## Commands
- `flutter pub get` — install dependencies
- `dart run build_runner build --delete-conflicting-outputs` — generate code
- `flutter analyze` — run linter
- `flutter test` — run tests
- `flutter run` — start dev build

## Architecture
Feature-first folder structure. Each feature lives in lib/features//.
State management: Riverpod with @riverpod code generation (AsyncNotifier pattern).
HTTP: Dio with interceptors in lib/core/network/.
Navigation: GoRouter with named routes defined in lib/core/router/.
Models: Freezed + JsonSerializable. Run build_runner after any model change.

## Conventions
- All monetary amounts in the smallest unit (e.g. kobo for NGN), stored as int — never use doubles for money
- Use ref.invalidate() not ref.refresh()
- No business logic in widgets — all logic goes in notifiers or repositories
- Widget files contain only one public widget per file
- Barrel exports via feature.dart in each feature root
- Prefix private widgets with an underscore

## What NOT to do
- Do not add new packages without asking first
- Do not modify *.g.dart or *.freezed.dart files directly — regenerate with build_runner
- Do not put API calls directly in notifiers — always go through the repository layer

A few things to note about this file:

Keep it honest: If your conventions don't match what's actually in the codebase, Claude will get confused. The CLAUDE.md should reflect how the code actually works today, not aspirationally.

The "What NOT to do" section matters: AI assistants are optimistic. They'll solve the problem in front of them without thinking about side effects. Explicitly telling Claude what to avoid saves a lot of cleanup.

Don't make it too long: Every line in CLAUDE.md costs tokens on every single turn of every session. Put team-wide, always-relevant rules here. Everything else should be a skill (covered next).

3. Feature-First Folder Structure — The Details

Let's look inside a feature in more detail, using a wallet feature as an example:

lib/features/wallet/
├── data/
│   ├── models/
│   │   ├── wallet.dart             # Freezed model
│   │   ├── wallet.freezed.dart     # Generated
│   │   ├── wallet.g.dart           # Generated
│   │   └── transaction.dart
│   └── repositories/
│       ├── wallet_repository.dart  # Abstract class
│       └── wallet_repository_impl.dart
├── presentation/
│   ├── screens/
│   │   ├── wallet_screen.dart
│   │   └── transaction_history_screen.dart
│   ├── widgets/
│   │   ├── balance_card.dart
│   │   └── transaction_tile.dart
│   └── providers/
│       ├── wallet_provider.dart
│       └── wallet_provider.g.dart  # Generated
└── wallet.dart                     # Barrel export

And here's what a clean Riverpod provider looks like in this structure:

// lib/features/wallet/presentation/providers/wallet_provider.dart

import 'package:riverpod_annotation/riverpod_annotation.dart';
import '../../data/models/wallet.dart';
import '../../data/repositories/wallet_repository.dart';

part 'wallet_provider.g.dart';

@riverpod
class WalletNotifier extends _$WalletNotifier {
  @override
  Future build() async {
    return ref.watch(walletRepositoryProvider).getWallet();
  }

  Future refreshBalance() async {
    state = const AsyncValue.loading();
    state = await AsyncValue.guard(
      () => ref.read(walletRepositoryProvider).getWallet(),
    );
  }
}

When Claude Code sees this pattern repeated across multiple features, it learns to replicate it. The more consistent your structure, the better Claude's output matches what you'd write yourself.

4. Writing Skills for Your Most Repeated Tasks

Skills are reusable instruction packs that Claude Code loads when they're relevant. They live in .claude/skills//SKILL.md and can be invoked manually with /skillname or triggered automatically when Claude recognises the right context.

A simple way to think about a Skill is as a specialist on your team. Imagine working with a designer, a QA engineer, and a security expert. You don't explain their entire job every time you need their help. Each person already knows their responsibilities and follows a defined process.

Skills work the same way. Instead of repeatedly telling Claude how to generate Riverpod providers, write tests, or review security concerns, you package those instructions into a Skill and let Claude load them whenever they're needed.

Think of a Skill as a saved recipe. Instead of writing out the ingredients and cooking steps every time you want to make a meal, you keep the recipe in one place and reuse it whenever needed.

Skills do the same thing for development workflows. They allow you to save a set of instructions once and have Claude follow them consistently every time a similar task comes up.

The key thing to understand is that the description field is what triggers a skill. Claude evaluates it on every turn and decides whether the current task matches. Because of this, you should describe it using the same verbs that developers actually type in real workflows, like build, commit, release, or fix lint, instead of documentation-style language.

Creating Your First Skill

Before you write a skill, think about the tasks you perform over and over again. A good skill captures a workflow you already know by heart. If you find yourself giving Claude the same instructions every session, such as "run flutter analyze, then run build_runner, then execute the tests," that's a good candidate for a skill.

Start with one task. Keep the steps in the exact order you expect Claude to follow, and clearly define what a successful outcome looks like. Don't try to cover every possible edge case. The goal is to automate your normal workflow so Claude can handle the repetitive work consistently, while you step in only when something unexpected happens.

mkdir -p .claude/skills/flutter-release
touch .claude/skills/flutter-release/SKILL.md

---
name: flutter-release
description: |
  Use this skill when building a release APK or preparing the app for deployment.
  Triggers on: "build release", "generate apk", "prepare release", "release build".
allowed-tools: Bash Read
---

# Flutter release checklist

Run these steps in order. Do not skip any step.

1. Run `flutter pub get`
2. Run `dart run build_runner build --delete-conflicting-outputs`
3. Run `flutter analyze` — fix every error before proceeding. Do not continue with warnings treated as errors.
4. Run `flutter test` — if any test fails, fix it before continuing
5. Run `flutter build apk --release`
6. Confirm build output at `build/app/outputs/flutter-apk/app-release.apk`
7. Create a git commit: `chore: release build vX.X.X`

If any step fails, stop and report the error clearly. Do not skip ahead.

Now, whenever you type "prepare a release" or "build the apk"Claude follows this checklist without you having to remind it of the steps.

A Skill For Conventional Commits

mkdir -p .claude/skills/commit
touch .claude/skills/commit/SKILL.md

---
name: commit
description: |
  Use when committing changes or writing a commit message.
  Triggers on: "commit", "git commit", "commit changes", "write a commit message".
---

Follow Conventional Commits format:

Types: feat | fix | chore | refactor | docs | test | perf

Format: `type(scope): short imperative summary`

Rules:
- Subject line max 72 characters
- Imperative mood — "add" not "added", "fix" not "fixed"
- Scope = the feature name (auth, transfer, wallet, cards)

Examples:
- `feat(transfer): add beneficiary validation on amount input`
- `fix(wallet): correct kobo-to-naira display conversion`
- `chore(deps): upgrade riverpod to 2.6.1`

Always run `flutter analyze` before committing. Never commit with lint errors.

Dynamic Context Injection

Skills support a powerful trick: you can inject live shell output directly into the skill body using !`command` syntax. Claude receives the output as part of the skill, not as a separate step.

For example, you could embed something like !git status inside a skill, so Claude always sees the current state of your repository when applying that skill. In a Flutter workflow, you could also use something like !flutter test so the skill dynamically includes the latest test results before Claude suggests fixes or improvements.

---
name: sprint-status
description: |
  Use when asked about current status, what's left to do, or what changed.
---

## Current git status
!`git status --short`

## Uncommitted changes
!`git diff --stat HEAD`

## Recent commits
!`git log --oneline -10`

## Lint status
!`flutter analyze 2>&1 | tail -20`

Review the above and give a concise summary of: what's done, what's broken, and what needs attention before the next commit.

Type /sprint-status and Claude gets a live snapshot of your project state before responding.

5. Using /loop for Self-Correcting Workflows

/loop is a built-in Claude Code skill that reruns a task repeatedly until a condition is met. It's the difference between "fix this lint error" (one shot) and "fix all lint errors" (autonomous loop).

For example, instead of running a one-time prompt like “fix this lint error,” you would use /loop fix lint errors in this Flutter project until there are no warnings left. Claude will then repeatedly check the output, apply fixes, and recheck until the condition is satisfied.

A more realistic Flutter workflow could look like /loop run flutter analyze and fix all reported issues until analysis passes clean. In this case, Claude keeps running analyses, fixing issues, and revalidating until the project reaches a clean state.

It's worthy of note here that a/loop and a Skill solve two different problems, and it helps to think of them like this:

A Skill is knowledge.
A Loop is behavior over time.

The pattern is always the same: tell Claude what to run, what to check, and when to stop.

Fix Until Clean

/loop
Run flutter analyze.
If there are any errors or warnings, read each one carefully and fix it.
Run flutter analyze again.
Continue until flutter analyze reports zero issues.
Do not move on while there are errors remaining.

TDD Loop

/loop
Run: flutter test --name "WalletNotifier"
If the test fails, read the failure output carefully.
Make the minimal code change required to fix the failure.
Do not change the test itself.
Run the test again.
Stop when the test passes with no errors.

Build a Screen, Check it, Iterate

/loop
Look at the Figma spec notes in CLAUDE.md under "Remaining screens".
Pick the next incomplete screen.
Build the screen following the architecture pattern in lib/features/wallet/presentation/.
After building, run flutter analyze and fix any issues.
Add a comment `// DONE` at the top of the completed screen file.
Move to the next screen.
Stop after completing 3 screens.

A word of caution: /loop is powerful, but give Claude a clear stop condition. "Keep going until it's perfect" is not a stop condition. "Stop when flutter analyze and flutter test both pass with zero issues." is.

6. Subagents for Parallel Screen Development

Subagents are isolated Claude instances that run a task in their own context window and then return only a summary to the main session. This changes how you think about working with Claude Code on a multi-screen project.

A simple way to understand it is to imagine building a full Flutter app with multiple screens. Without subagents, you would design the home screen, then the profile screen, then settings, all in one long conversation. Over time, the context gets heavier, and Claude starts losing focus on earlier decisions.

With subagents, it's like giving each screen to a different engineer. One works on the home screen, another builds the profile screen, and another handles settings. Each one works independently, follows the same project rules, and reports back only when the screen is ready. You then combine their output into the main project without losing clarity or consistency.

Setting Up a Screen-Builder Subagent

Create a file at .claude/agents/screen-builder.md:

---
name: screen-builder
description: Builds a single Flutter screen following the app's feature-first Riverpod architecture
model: claude-sonnet-4-6
tools: [Read, Write, Bash, Glob]
---

You are a Flutter engineer building a screen for a fintech app.

Before building anything:
1. Read lib/features/wallet/presentation/screens/wallet_screen.dart to understand the existing screen pattern
2. Read CLAUDE.md for conventions and architecture rules
3. Read the feature's existing providers in the presentation/providers/ folder

When building the screen:
- Follow the exact same structure as the existing screens
- Use AsyncValue pattern for loading/error/data states
- No business logic in the widget — all state goes through the provider
- Every monetary amount displayed in naira but stored in kobo (divide by 100 for display)
- Use GoRouter for navigation, not Navigator.push

After building:
- Run flutter analyze on the file
- Fix any errors
- Return a summary: file path created, provider used, any decisions made

Using it

In your main session, you can now say:

Use the screen-builder subagent to build the Transaction History screen.
The screen should show a list of transactions from the WalletNotifier provider.
Each item should display: amount (formatted), description, date, and status badge.

Claude dispatches the subagent, which reads your existing code for context, builds the screen following your patterns, fixes any lint errors, and returns a clean summary, without cluttering your main thread with every intermediate step.

You can also run multiple subagents simultaneously for truly parallel work:

Dispatch three screen-builder subagents in parallel:
1. Transaction History screen (list of transactions)
2. Send Money screen (amount input + recipient selection)
3. Wallet Top-Up screen (amount input + payment method)

Each should follow the existing wallet feature patterns.
Report back when all three are complete.

7. Hooks — Enforcing Rules Deterministically

Skills and subagents influence how Claude thinks and plans, but hooks are different. Hooks are deterministic. They run automatically at specific lifecycle events, no matter what Claude decides to do. This makes them useful for enforcing hard rules in your workflow.

A simple way to understand it is to think of hooks as guards in a real engineering pipeline. For example, before any code is committed, a PreToolUse hook can run to check formatting or block unsafe changes. After a tool runs, a PostToolUse hook can validate the output. When a session ends, a Stop hook can trigger cleanup tasks or logging. Other events, like SessionStart, PreCompact help you initialize context or manage memory before Claude continues working.

In practice, hooks are how you enforce consistency. While Skills and subagents guide Claude’s behavior, hooks ensure certain actions always happen at the right moment, without relying on Claude to “remember” or “decide.”

Block Edits to Generated Files

Generated files like *.g.dart and *.freezed.dart should never be edited manually — they get overwritten by build_runner. This hook blocks Claude from writing to them:

Create .claude/hooks.json:

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit",
      "command": "bash -c 'if [[ \"\(CLAUDE_TOOL_INPUT_PATH\" == *.g.dart ]] || [[ \"\)CLAUDE_TOOL_INPUT_PATH\" == *.freezed.dart ]]; then echo \"Blocked: Do not edit generated files. Run build_runner instead.\"; exit 1; fi'"
    }
  ]
}

Run Analyze Before Every Stop

This hook runs flutter analyze before Claude considers its turn complete, catching lint errors before they accumulate:

{
  "Stop": [
    {
      "command": "bash -c 'result=\((flutter analyze 2>&1); if echo \"\)result\" | grep -q \"error •\"; then echo \"Flutter analyze found errors. Fix before stopping:\"; echo \"$result\"; exit 1; fi'"
    }
  ]
}

Now Claude can't finish a turn if there are lint errors. It gets blocked and has to fix them first.

8. Putting It All Together: A Real Sprint Workflow

Here's what a typical feature development session looks like when all of this is configured:

Morning: Check Project State

/sprint-status

Claude reads live Git status, recent commits, and current lint output, then summarises what needs attention.

Start a New Feature

I need to build the beneficiary management feature. 
Users should be able to save, view, and delete beneficiaries for the transfer flow.
Start with the data layer — Freezed model and repository interface.

Claude reads your CLAUDE.md and existing feature patterns, then builds the model and repository in the right place, following your conventions.

Generate All the Screens in Parallel

Use the screen-builder subagent to build:
1. BeneficiaryListScreen — shows saved beneficiaries with search
2. AddBeneficiaryScreen — form with account number and bank selection
3. BeneficiaryDetailScreen — shows details with delete option

Fix Everything Until it's Clean

/loop
Run flutter analyze.
Fix all errors.
Run flutter test.
Fix any test failures.
Stop when both pass with zero issues.

Commit Cleanly

Commit the beneficiary feature

The commit skill triggers, runs analyze one more time, and creates a correctly-formatted conventional commit message.

Key Takeaways

If there's one key takeaway from all of this, it's that Claude Code isn't just about prompting. It's about setup. The quality of its output is shaped far more by what you define about your project upfront than by what you type in the moment.

This is also what separates vibe coding from real AI-assisted engineering. Without structure, you end up guessing and reacting, which feels fast but breaks down quickly.

With the right setup, Claude becomes a pair programming partner that follows your conventions and handles execution while you focus on decisions that actually require engineering judgment. That shift is what lets you spend less time fixing generated code and more time solving the problems that matter.

The payoff compounds. A CLAUDE.md takes 20 minutes to write. A skill for your release flow takes 10 minutes. But both of those pay for themselves the first time Claude correctly follows your process without you having to walk it through every step.

Start small: write your CLAUDE.md this week. Add one skill for the task you repeat most — committing, releasing, or running lint. Then, when you're comfortable, try a /loop on your next test-fixing session. The rest follows naturally.

The goal isn't to let AI write all your code. It's to stop spending your limited engineering time on the parts that don't require your judgment, and to spend more of it on the parts that do.

How to Build an AI-Powered, Local-First Chrome Extension That Turns Your Browsing History into an Intent Map

Shola Jegede — Fri, 19 Jun 2026 17:14:43 +0000

Your browser remembers every page you've ever opened, but it has no idea why you opened any of them.

You might spend three days comparing laptops across a dozen tabs, get distracted, come back a week later, and your history just shows a flat list of timestamps and titles, with no sense that those visits were one thing, a decision you started and never finished.

In this tutorial, you'll build openloops, an open-source, local-first Chrome extension that fixes this by scanning your browsing history and grouping it into "intent threads" – the decisions, research, and open questions you keep coming back to – then scoring each one for how alive it still is. Optionally, it also uses Claude to label those threads in plain language, suggest a concrete next step, and power a chat assistant you can ask "what should I close this week?"

By the end, you'll have built:

A Manifest V3 Chrome extension with a service worker and a full-tab dashboard
A local pipeline that captures, cleans, segments, and clusters browsing history entirely in IndexedDB
A clustering algorithm tuned and debugged on real (messy) browsing data
An AI labeling layer using Claude, with a grounding step that uses brand data from context.dev
A chat assistant that reasons across your threads and tells you what to do next
A polished dashboard with onboarding, a design system, and a working pipeline status machine

Everything runs on-device, and the only network calls are optional and opt-in, made with your own API keys.

What You'll Build
Prerequisites
How openloops Is Structured
- The shared types
- The manifest
How to Scaffold the Extension
How to Capture Your Browsing History
How to Turn Noise into Sessions
How to Cluster Sessions into Intent Threads
How to Clean Up Self-Referential Noise
How to Label Threads with Claude
How to Ground Labels with context.dev
How to Design the Dashboard
How to Build the AI Assistant
What You've Built, and Where to Take It
Resources

What You'll Build

On first run, openloops greets you with a centered welcome screen that walks you through the three pipeline steps:

Once you've scanned your history, built sessions, and built the intent map, your browsing reorganizes into status-grouped threads: active, stalled, and dormant. Each one has a confidence score, a plain-language summary, a concrete next step, and a Resume button that reopens the exact pages you left off on. The right column holds a chat assistant grounded in your own threads:

That assistant response reasons across the user's actual threads, ranking them by how easy they are to close against how much of a real decision they still need. It also explains why, which is the most novel part of this build, and depends on the context.dev grounding step you'll add later in this tutorial.

Prerequisites

To follow along, you'll need:

Node 18+ and a Chromium-based browser (Chrome, Brave, Edge, and so on).
Comfort with TypeScript and React. You don't need to be an expert, but you should be comfortable reading hooks and async/await.
Basic familiarity with IndexedDB is helpful but not required, as you'll learn what you need as you go.

Two parts of this build are optional and require your own API key, each with a free tier:

An Anthropic API key (from platform.claude.com) for AI labeling and the chat assistant
A context.dev API key (from context.dev) for the brand-grounding step

You can build and use the entire core pipeline, capture, clustering, scoring, without either key, since both are additive layers on top of it.

How openloops Is Structured

Before writing any code, it helps to see the whole shape of the thing. Every stage of openloops reads from one IndexedDB store and writes to the next:

chrome.history (backfill) ──┐
chrome.tabs.onUpdated (live)─┴─→ raw_events
                                     │  noise filter
                                     ▼
                                  sessions
                                     │  ambient detection + clustering + scoring
                                     ▼
                               intent_threads
                                     │
                                     ▼
                              React dashboard
                                     │  optional, opt-in
                                     ├──→ brand enrichment   (context.dev)
                                     └──→ AI labeling + next step (Claude)
                                              │
                                              ▼  optional, opt-in
                                        AI assistant chat (Claude)

Each stage is a separate module under src/pipeline/, and each one is independently inspectable: you can open Chrome DevTools, look at raw_events, sessions, or intent_threads directly in the Application tab, and rebuild any single stage without touching the others.

The Shared Types

Every stage consumes and produces the same handful of TypeScript interfaces, defined once in src/types.ts:

// Shared TypeScript interfaces for the openloops pipeline.
// Each stage of the pipeline consumes and produces these types.

export interface RawEvent {
  id: string;
  url: string;
  domain: string;
  title: string;
  visitedAt: number;         // epoch ms
  source: "backfill" | "live";
}

export interface Session {
  id: string;
  events: RawEvent[];
  startedAt: number;
  endedAt: number;
  domains: string[];
  keywords: string[];
}

export interface IntentThread {
  id: string;
  title: string;
  summary?: string;
  nextStep?: string;   // one concrete action to move the thread forward
  sessions: Session[];
  type: "buying" | "research" | "planning" | "learning" | "unclassified";
  confidence: number;        // 0-1
  status: "active" | "stalled" | "dormant";
  firstSeen: number;
  lastSeen: number;
  distinctDays: number;
  signals: string[];
}

export interface Brand {
  domain: string;
  name: string;
  description: string;
  industry: string;
  logoUrl: string;
  brandColor: string;
}

Most fields on IntentThread, confidence, status, signals, and distinctDays get filled in by pure local heuristics later in this guide, when you cluster and score threads. summary and nextStep stay undefined until the optional AI labeling step, covered after that, fills them in.

This is the pattern that makes the whole project work: the core data model functions on its own, and AI makes it richer.

The Manifest

openloops is a Manifest V3 extension with three permissions and three host permissions:

{
  "manifest_version": 3,
  "name": "openloops",
  "version": "0.0.1",
  "description": "Reconstruct your browsing history into an AI-labeled map of intent threads: active decisions, stalled research, open questions. Fully local.",

  "permissions": ["history", "tabs", "storage"],
  "host_permissions": [
    "https://api.anthropic.com/*",
    "https://api.context.dev/*",
    "https://logos.context.dev/*"
  ],

  "background": {
    "service_worker": "src/background.ts",
    "type": "module"
  },

  "options_page": "src/dashboard/index.html",

  "icons": {
    "16": "icons/icon16.png",
    "32": "icons/icon32.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },

  "action": {
    "default_title": "openloops",
    "default_icon": {
      "16": "icons/icon16.png",
      "32": "icons/icon32.png"
    }
  }
}

The permissions, host permissions, and options_page entry each carry specific weight:

permissions: ["history", "tabs", "storage"] are the only permissions the core pipeline needs. history reads your browsing history for the backfill, tabs lets the service worker observe new page loads and lets "Resume" reopen tabs, and storage is where API keys and preferences live.
host_permissions are separate, and only matter if you use the optional AI features. They're what let the dashboard make fetch() calls to Anthropic and context.dev without hitting CORS errors.
options_page points at the dashboard. Setting it this way, instead of a default_popup, means clicking the toolbar icon opens the dashboard as a full browser tab rather than a tiny popup, which matters once you're looking at a multi-column layout with status-grouped cards and a chat panel.

How to Scaffold the Extension

Start with Vite and the CRXJS plugin, which compiles a Manifest V3 extension with hot module reloading:

npm create vite@latest openloops -- --template react-ts
cd openloops
npm install @crxjs/vite-plugin idb react-markdown

Your vite.config.ts wires CRXJS to your manifest.json, and from there, Vite handles compiling src/background.ts to a real .js file that Chrome can load (a raw .ts service worker path in the manifest will fail with a registration error, which we'll debug in the next section).

The dashboard's entry point is a standard React 18 root:



  
    
    
    openloops

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./app.css";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  
    
  
);

Build it, then load it as an unpacked extension:

npm run build

In Chrome, go to chrome://extensions, enable Developer mode, click Load unpacked, and select the dist/ folder. With nothing else built yet, clicking the toolbar icon should open a blank dashboard tab, and the service worker (visible from the extension card's "service worker" link) should log [openloops] Extension installed. on install.

With that foundation in place, it's time to start filling raw_events with your actual browsing history.

How to Capture Your Browsing History

Every record in openloops starts life as a RawEvent, the type you saw earlier: a URL, a domain, a title, a timestamp, and a source of either "backfill" or "live".

Two pipelines populate it:

A one-time backfill that reads your last 14 days of chrome.history on demand
Live capture, which listens for new page loads from this point forward

Both paths share a handful of small helpers and write through the same IndexedDB layer, so it's worth building those first.

A Few Shared Helpers

Create src/lib/util.ts:

export function isHttpUrl(url: string): boolean {
  return url.startsWith("http://") || url.startsWith("https://");
}

export function extractDomain(url: string): string {
  try {
    const { hostname } = new URL(url);
    return hostname.replace(/^www\./, "");
  } catch {
    return url;
  }
}

export function isLocalHost(domain: string): boolean {
  if (domain === "localhost" || domain === "127.0.0.1") return true;
  if (domain.endsWith(".local")) return true;

  const octets = domain.split(".");
  if (octets.length === 4 && octets.every((o) => /^\d{1,3}$/.test(o))) {
    const [a, b] = octets.map(Number);
    if (a === 10) return true;
    if (a === 172 && b >= 16 && b <= 31) return true;
    if (a === 192 && b === 168) return true;
  }

  return false;
}

export function hashId(url: string, visitedAt: number): string {
  const str = `\({url}|\){visitedAt}`;
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
    hash |= 0;
  }
  return (hash >>> 0).toString(36);
}

Each of these four functions solves a problem you won't notice until later in the build:

isHttpUrl is the shared scheme guard used by both live capture and the backfill, and the single gate that keeps chrome://, chrome-extension://, about:, and file:// URLs out of your data entirely. Both capture paths call it before anything else.
extractDomain strips a leading www. and returns the hostname, which is a simplification: bbc.co.uk and news.bbc.co.uk wouldn't collapse to the same domain under this logic, since true registrable-domain extraction needs the Public Suffix List. If the URL is malformed, it just returns the input unchanged rather than throwing.
isLocalHost exists for one reason: when you add brand enrichment later in this guide, you'll be sending domain names to an external API. localhost:5173 or 192.168.1.50 are meaningless to that API and would just be wasted lookups, so it's better to filter them here, once, at the source. It checks for localhost, 127.0.0.1, .local hostnames, and the standard private IPv4 ranges (10.x.x.x, 172.16.x.x–172.31.x.x, 192.168.x.x).
hashId combines the URL and timestamp into a short, deterministic string using a simple hashing algorithm (djb2), so the same (url, visitedAt) pair always produces the same ID. This makes writes idempotent: re-running the backfill produces the same IDs for the same visits, so IndexedDB's put overwrites cleanly instead of duplicating, which is what makes "Scan my history" safe to click more than once.

The Database Layer (So Far)

openloops stores everything in IndexedDB via the idb wrapper, which gives you a typed, promise-based API over the raw IndexedDB calls. Create src/db/index.ts:

import { openDB, type DBSchema, type IDBPDatabase } from "idb";
import type { RawEvent } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
}

const DB_NAME = "openloops";
const DB_VERSION = 1;

let _db: Promise> | null = null;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
      },
    });
  }
  return _db;
}

export async function clearEvents(): Promise {
  const db = await getDB();
  return db.clear("raw_events");
}

export async function putEvents(events: RawEvent[]): Promise {
  if (events.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("raw_events", "readwrite");
  await Promise.all([...events.map((e) => tx.store.put(e)), tx.done]);
}

export async function getAllEvents(): Promise {
  const db = await getDB();
  return db.getAllFromIndex("raw_events", "by_visitedAt");
}

export async function getEventCount(): Promise {
  const db = await getDB();
  return db.count("raw_events");
}

Four small functions round out this first version of the database layer: clearEvents wipes the store, which the backfill calls first so every scan starts from a clean snapshot. putEvents writes a batch using IDB's put, which overwrites rather than duplicates. getAllEvents returns everything sorted by visitedAt via the index. And getEventCount returns a simple count for the dashboard.

_db is a module-level singleton promise, so every part of the extension, the service worker and the dashboard alike, shares one connection. DB_VERSION starts at 1 here. As you add sessions, intent threads, and brand data in later parts, you'll add new stores guarded by if (!db.objectStoreNames.contains(...)) and bump this number. That guard means existing users upgrade safely without touching stores that already exist.

Capturing New Visits Live

The service worker is the always-on part of the extension. Create src/background.ts:

import { hashId, extractDomain, isHttpUrl } from "./lib/util";
import { putEvents } from "./db/index";
import type { RawEvent } from "./types";

chrome.runtime.onInstalled.addListener(() => {
  console.log("[openloops] Extension installed.");
});

chrome.action.onClicked.addListener(() => {
  chrome.runtime.openOptionsPage();
});

const DEDUP_MS = 3_000;
const recentCaptures = new Map();

chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status !== "complete" || !tab.url) return;

  const url = tab.url;

  if (!isHttpUrl(url)) return;

  const last = recentCaptures.get(tabId);
  const now = Date.now();
  if (last && last.url === url && now - last.at < DEDUP_MS) {
    console.log(`[openloops] dedup skip — tab \({tabId} \){url}`);
    return;
  }

  recentCaptures.set(tabId, { url, at: now });

  const event: RawEvent = {
    id: hashId(url, now),
    url,
    domain: extractDomain(url),
    title: tab.title ?? url,
    visitedAt: now,
    source: "live",
  };

  putEvents([event]).then(() => {
    console.log(`[openloops] captured \({event.domain} — \){event.title}`);
  }).catch((err) => {
    console.error("[openloops] putEvents failed:", err);
  });
});

chrome.action.onClicked is what makes the toolbar icon open the dashboard as a tab rather than a popup, working together with the options_page entry in your manifest.

Live capture happens inside the tabs.onUpdated listener, which Chrome fires repeatedly as a page loads, redirects, and updates its title, though you should only care about the moment changeInfo.status === "complete". From there, isHttpUrl drops anything that isn't a real web page, the dedup guard collapses the duplicate "complete" events that SPAs love to fire, and the rest becomes a RawEvent with source: "live".

That dedup guard is best-effort by design: recentCaptures is a plain in-memory Map, and Chrome can suspend the service worker between events, which wipes the Map along with it. It still collapses duplicate bursts within a single waking session, just not across service worker restarts, and that's an acceptable tradeoff since hashId already makes any duplicate that slips through harmless once it reaches IndexedDB.

The final write also looks slightly unusual: putEvents([event]).then(...).catch(...) instead of await. The listener doesn't need to block on the write finishing, and the service worker stays alive long enough to complete a single IndexedDB write even if it's about to be suspended, so firing the write and moving on is enough.

That source field carries more weight than it first appears, since it's how later code distinguishes "the user actually scanned their history" from "the extension has only been open for five minutes". This matters for onboarding when you design the dashboard later in this guide.

Build and reload the extension now (npm run build, then click the reload icon on the extension card in chrome://extensions), browse a few pages, then open the service worker's DevTools by clicking "service worker" on the extension card. You'll be able to see [openloops] captured ... log lines appear as confirmation that live capture is working.

Backfilling 14 Days of History

Live capture only sees what happens after you install the extension, so to make openloops useful immediately, you also need to backfill recent history. Create src/pipeline/backfill.ts:

import { extractDomain, hashId, isHttpUrl } from "../lib/util";
import { putEvents, clearEvents } from "../db/index";
import type { RawEvent } from "../types";

const CONCURRENCY = 50;

async function visitsForItem(
  item: chrome.history.HistoryItem,
  startTime: number
): Promise {
  if (!item.url) return [];
  if (!isHttpUrl(item.url)) return [];

  const visits = await chrome.history.getVisits({ url: item.url });

  const events: RawEvent[] = [];
  for (const visit of visits) {
    if (!visit.visitTime || visit.visitTime < startTime) continue;

    events.push({
      id: hashId(item.url, visit.visitTime),
      url: item.url,
      domain: extractDomain(item.url),
      title: item.title ?? item.url,
      visitedAt: visit.visitTime,
      source: "backfill",
    });
  }

  return events;
}

export async function backfillHistory(days = 14): Promise {
  await clearEvents();

  const startTime = Date.now() - days * 24 * 60 * 60 * 1000;

  const historyItems = await chrome.history.search({
    text: "",
    startTime,
    maxResults: 100_000,
  });

  let totalWritten = 0;

  for (let i = 0; i < historyItems.length; i += CONCURRENCY) {
    const batch = historyItems.slice(i, i + CONCURRENCY);
    const batchResults = await Promise.all(
      batch.map((item) => visitsForItem(item, startTime))
    );
    const events = batchResults.flat();
    await putEvents(events);
    totalWritten += events.length;
  }

  return totalWritten;
}

backfillHistory starts by calling clearEvents and wiping the store so each run produces a clean snapshot for the chosen window. Every real visit still exists in chrome.history, so nothing is lost by starting over. It then searches with maxResults: 100_000, since the default of 100 is far too low for anyone with more than a few days of real browsing.

Each matching HistoryItem goes through visitsForItem, which skips items that Chrome returns with no url at all, a quirk of some deleted-history entries, and skips non-web URLs using isHttpUrl, before fetching that item's full visit list.

Calling getVisits here, instead of relying on search alone, matters because chrome.history.search is tempting as a single call, but it collapses every visit to a URL down to just the most recent one. If you visited the same Stack Overflow answer three times over two days while debugging something, search gives you one row, and in the next section, where you segment events into sessions, you need all three: that's the difference between "one visit, three days ago" and "a sustained debugging session."

getVisits gives you that full timestamp list, but it returns all history for a URL regardless of date range, so visitsForItem filters by startTime itself. And because chrome.history.search can return tens of thousands of items for a heavy browser history, the backfill fans out to getVisits in batches of CONCURRENCY, set to 50, rather than firing everything at once. Chrome doesn't document a hard limit on concurrent getVisits calls, but 50 in flight at a time keeps things responsive without flooding it.

Checkpoint

You can verify live capture by browsing normally and watching raw_events fill up: open chrome://extensions, click "service worker" on the openloops card, then go to the Application tab → IndexedDB → openloops → raw_events, where each row should be a RawEvent with source: "live".

backfillHistory itself doesn't have a UI yet, but you'll wire it up to a "Scan my history" button when you build the dashboard rail in Part 13. For now, it's enough that it compiles and that raw_events is filling up from live capture. In the next part you'll start turning that raw stream into something structured: sessions.

How to Turn Noise into Sessions

A real browsing history is full of activity that has nothing to do with what you were actually trying to do. An afternoon of research might be interleaved with dozens of visits to Gmail, Slack, or YouTube, along with pages whose titles are just "New Tab" or "Dashboard" because the page hadn't finished loading when the browser recorded it.

Before any of this can be grouped into something meaningful, two things need to happen: the noise needs to be filtered out, and what remains needs to be broken into sessions, contiguous stretches of activity separated by gaps in time.

This section builds both of those steps, along with a small keyword extractor that each session uses to describe what it was about, since that description is what later powers clustering.

Filtering Out Noise

Create src/pipeline/noise.ts:

import type { RawEvent } from "../types";
import { isHttpUrl, isLocalHost } from "../lib/util";

export const BLOCKED_DOMAINS: readonly string[] = [
  "mail.google.com",
  "outlook.live.com",
  "outlook.office.com",
  "calendar.google.com",
  "slack.com",
  "app.slack.com",
  "discord.com",
  "web.whatsapp.com",
  "teams.microsoft.com",
  "messenger.com",
];

export const ADULT_DOMAINS: readonly string[] = [
  "xvideos.com",
  "pornhub.com",
  "xnxx.com",
  "xhamster.com",
  "redtube.com",
  "youporn.com",
  "spankbang.com",
];

export const JUNK_DOMAINS: readonly string[] = [
  "trk.myperfect2give.com",
  "t.buenotraffic.com",
  "bwredir.com",
  "osom.saintscommunity.net",
];

const ALL_BLOCKED = [...BLOCKED_DOMAINS, ...ADULT_DOMAINS, ...JUNK_DOMAINS];

function domainIsBlocked(domain: string): boolean {
  return ALL_BLOCKED.some(
    (blocked) => domain === blocked || domain.endsWith("." + blocked)
  );
}

export const NOISE_TITLE_PREFIXES: readonly string[] = [
  "new tab",
  "new chat",
  "untitled",
  "inbox",
  "home",
  "dashboard",
  "sign in",
  "log in",
  "loading",
];

function titleIsGeneric(title: string, domain: string): boolean {
  if (title.trim() === "") return true;
  if (title.toLowerCase() === domain.toLowerCase()) return true;

  const lower = title.toLowerCase();
  return NOISE_TITLE_PREFIXES.some((prefix) => lower.startsWith(prefix));
}

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

isNoise is the single function the rest of the pipeline calls, and it layers four checks on top of each other, each one catching a different kind of noise.

The first two checks reuse the helpers from earlier: isHttpUrl and isLocalHost drop anything that isn't a real web page or that points at a local development server, the same filters that already protect capture. Checking them again here is a deliberate belt-and-suspenders measure: if anything ever reaches raw_events without having passed through capture's checks, it still can't make it into a session.

BLOCKED_DOMAINS covers communication and productivity tools, Gmail, Slack, Discord, WhatsApp Web, and similar. Those tools that you visit constantly but that carry no research intent of their own. domainIsBlocked matches both the exact domain and any subdomain, so slack.com in the list also catches app.slack.com. ADULT_DOMAINS and JUNK_DOMAINS exist for related reasons, keeping adult content and known tracker or redirect domains out of your threads entirely.

BLOCKED_DOMAINS is a curated, static list, and later in this guide it's complemented by a second, frequency-based detector in ambient.ts. This drops any domain that shows up in nearly every session regardless of what that domain actually is.

The last check, titleIsGeneric, catches pages whose titles tell you nothing useful: an empty title, a title that's identical to the domain name, or a title that starts with a generic prefix like "New Tab", "Dashboard", "Loading...", or "Sign in". NOISE_TITLE_PREFIXES is matched against the start of the lowercased title, so "Dashboard | Vercel" gets dropped right alongside a bare "Dashboard", while a content-rich title on that same domain passes through untouched.

Extracting Keywords

Create src/pipeline/keywords.ts. This isn't NLP, just frequency counting after stopword removal. This is good enough to surface something like "typescript generics" or "react hooks" from a session of related browsing:

import { BLOCKED_DOMAINS } from "./noise";

export const STOPWORDS: ReadonlySet = new Set([
  "the", "and", "for", "with", "you", "your", "how", "what", "this", "that",
  "from", "are", "was", "not", "but", "all", "can", "has", "have", "will",
  "its", "out", "one", "get", "our", "had", "just", "about", "also", "more",
  "into", "than", "then", "when", "their", "there", "which", "would", "been",
  "his", "her", "who", "they", "she", "him", "now", "any", "way", "use",
  "using", "used", "make", "made",
  "google", "youtube", "search", "chat", "new", "home", "www", "com", "org",
  "net", "page", "site", "tab", "view", "app", "log", "sign", "login",
  "official", "free", "online", "best", "top", "open",
]);

export const PLATFORM_STOPWORDS: ReadonlySet = new Set([
  "instagram", "facebook", "youtube", "claude", "google", "linkedin",
  "twitter", "reddit", "netflix", "amazon", "gmail", "whatsapp", "tiktok",
  "messenger",
  "stories", "story", "reel", "reels", "shorts", "short", "feed", "watch",
  "video", "videos", "music", "post", "posts", "message", "messages",
  "dm", "dms", "notification", "notifications", "profile", "home", "login",
  "signin", "follow", "followers",
]);

function derivedDomainLabels(): Set {
  const labels = new Set();
  for (const domain of BLOCKED_DOMAINS) {
    const label = domain.split(".").at(-2);
    if (label) labels.add(label);
  }
  return labels;
}

const ALL_STOP_TOKENS: ReadonlySet = new Set([
  ...STOPWORDS,
  ...PLATFORM_STOPWORDS,
  ...derivedDomainLabels(),
]);

export function extractKeywords(titles: string[], max = 8): string[] {
  const freq = new Map();

  for (const title of titles) {
    const tokens = title.toLowerCase().split(/[^a-z0-9]+/);
    for (const token of tokens) {
      if (token.length < 3) continue;
      if (/^\d+$/.test(token)) continue;
      if (ALL_STOP_TOKENS.has(token)) continue;

      freq.set(token, (freq.get(token) ?? 0) + 1);
    }
  }

  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .slice(0, max)
    .map(([token]) => token);
}

extractKeywords takes the page titles from a group of events and returns the handful of words that show up most often, after stripping out everything that isn't a topic. That stripping is doing more work than the name "stopwords" suggests.

STOPWORDS covers common English function words like "the" and "with", plus generic site chrome like "search", "login", and "page". On its own, this would still let through tokens like "instagram" or "reels" from a title such as "Reels · Instagram", and those tokens would then show up as keywords for that session.

That gap is what PLATFORM_STOPWORDS closes. A title like "Reels · Instagram" or "Watch - YouTube" identifies the tool you were using, not what you were doing with it. So PLATFORM_STOPWORDS strips out platform and brand names along with social media UI chrome like "stories", "feed", "dm", and "notifications". Without this list, sessions on social platforms would extract keywords like "instagram" or "watch". Those would become thread titles that quietly pull unrelated sessions together during clustering, since every social-media session would share that one meaningless keyword.

derivedDomainLabels keeps a third source of stopwords in sync automatically: for every domain in BLOCKED_DOMAINS, it takes the label immediately before the top-level domain. So mail.google.com becomes google and web.whatsapp.com becomes whatsapp. Adding a new domain to that blocklist later also prevents its name from polluting keywords, without any extra bookkeeping.

With all three sets merged once at module load into ALL_STOP_TOKENS, extractKeywords itself is straightforward: lowercase every title, split on anything that isn't a letter or digit, drop tokens shorter than three characters or made entirely of digits, and drop anything in ALL_STOP_TOKENS. Then count what's left and return the most frequent entries.

Extending the Database For Sessions

Sessions need a place to live. Earlier in this guide, src/db/index.ts defined a schema with just raw_events at version 1. We'll add a sessions store and bump the version to 2.

First, extend the schema and the upgrade callback:

import type { RawEvent, Session } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
}

const DB_VERSION = 2;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
      },
    });
  }
  return _db;
}

Then add the helper functions sessions need, alongside the raw_events helpers you already wrote. They follow the same shape: putSessions writes a batch idempotently, clearSessions wipes the store before a rebuild, getAllSessions returns everything sorted by startedAt via the index, and getSessionCount returns a total.

export async function putSessions(sessions: Session[]): Promise {
  if (sessions.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("sessions", "readwrite");
  await Promise.all([...sessions.map((s) => tx.store.put(s)), tx.done]);
}

export async function clearSessions(): Promise {
  const db = await getDB();
  return db.clear("sessions");
}

export async function getAllSessions(): Promise {
  const db = await getDB();
  return db.getAllFromIndex("sessions", "by_startedAt");
}

export async function getSessionCount(): Promise {
  const db = await getDB();
  return db.count("sessions");
}

The if (!db.objectStoreNames.contains(...)) guard from earlier is what makes this safe: anyone who already has a version-1 database, with raw_events full of real data, gets the new sessions store added on top, without touching what's already there.

Segmenting Events into Sessions

A session is a contiguous block of browsing activity, with a new one starting whenever the gap between two consecutive events exceeds SESSION_GAP_MS. Create src/pipeline/sessions.ts:

import { getAllEvents, clearSessions, putSessions } from "../db/index";
import { isNoise } from "./noise";
import { extractKeywords } from "./keywords";
import { hashId } from "../lib/util";
import type { RawEvent, Session } from "../types";

const SESSION_GAP_MS = 30 * 60 * 1000;

function rankDomains(events: RawEvent[]): string[] {
  const freq = new Map();
  for (const e of events) {
    freq.set(e.domain, (freq.get(e.domain) ?? 0) + 1);
  }
  return [...freq.entries()]
    .sort((a, b) => b[1] - a[1])
    .map(([domain]) => domain);
}

function buildSession(events: RawEvent[]): Session {
  const startedAt = events[0].visitedAt;
  const endedAt = events[events.length - 1].visitedAt;

  return {
    id: hashId(events[0].url, startedAt),
    events,
    startedAt,
    endedAt,
    domains: rankDomains(events),
    keywords: extractKeywords(events.map((e) => e.title)),
  };
}

export async function buildSessions(): Promise<{ events: number; sessions: number }> {
  const allEvents = await getAllEvents();

  const meaningful = allEvents.filter((e) => !isNoise(e));

  if (meaningful.length === 0) {
    await clearSessions();
    return { events: 0, sessions: 0 };
  }

  const sessions: Session[] = [];
  let currentGroup: RawEvent[] = [meaningful[0]];

  for (let i = 1; i < meaningful.length; i++) {
    const gap = meaningful[i].visitedAt - meaningful[i - 1].visitedAt;

    if (gap > SESSION_GAP_MS) {
      sessions.push(buildSession(currentGroup));
      currentGroup = [meaningful[i]];
    } else {
      currentGroup.push(meaningful[i]);
    }
  }
  sessions.push(buildSession(currentGroup));

  const substantive = sessions.filter(
    (s) => !(s.events.length === 1 && s.keywords.length === 0)
  );

  await clearSessions();
  await putSessions(substantive);

  return { events: meaningful.length, sessions: substantive.length };
}

buildSessions does five things in order:

loads every raw event sorted by time,
drops anything isNoise flags,
walks the remaining list and starts a new session whenever the gap between two consecutive events exceeds SESSION_GAP_MS (pushing the final in-progress group once the loop ends since nothing else closes it off),
drops sessions that turned out to be a single event with no extractable keywords (usually stray page loads that never connected to anything else),
and persists the result.

Each session's domains and keywords come from rankDomains and extractKeywords running over just the events in that group. rankDomains counts how many events came from each domain and orders them by frequency, so the most-visited domain in a session comes first.

A worked example makes "walking the list" concrete. Take five events that survive noise filtering, A through E:

A  t= 0 min  "TypeScript generics - Stack Overflow"   stackoverflow.com
B  t= 5 min  "TypeScript Handbook"                    typescriptlang.org
C  t=10 min  "microsoft/TypeScript - GitHub"          github.com
   ↑ gap to D = 45 min  >  SESSION_GAP_MS (30 min)  → SPLIT HERE
D  t=55 min  "React hooks explained - YouTube"         youtube.com
E  t=60 min  "useEffect cleanup - Stack Overflow"     stackoverflow.com

As the loop walks from A to B to C, each gap is under the 30-minute limit, so all three stay in the same group. The jump from C to D is 45 minutes, which crosses SESSION_GAP_MS, so the loop closes off [A, B, C] as Session 1 and starts a fresh group with D. From D to E is only 5 minutes, so E joins D, and that group becomes Session 2 once the loop ends.

Session 1 ends up tagged with keywords like typescript and generics, while Session 2 is tagged with react and hooks, even though both sessions happened on the same day.

SESSION_GAP_MS is set to 30 minutes because that's the same default that Google Analytics and similar tools use, and it works well for most browsing patterns.

The tradeoff runs in both directions: a shorter gap produces more, smaller sessions, which gives clustering a more granular signal but risks fragmenting one continuous task into several pieces. A longer gap produces fewer, larger sessions, which risks merging activity that was actually unrelated.

30 minutes is a reasonable starting point, and it's the kind of constant you can come back and tune once you see how your own threads turn out.

Checkpoint

buildSessions doesn't have a UI yet either. It'll get wired up to a "Build sessions" button alongside "Scan my history" when you design the dashboard later in this guide.

For now, the goal is just for everything in this section to compile cleanly: src/pipeline/noise.ts, src/pipeline/keywords.ts, the updated src/db/index.ts, and src/pipeline/sessions.ts should all build without errors. getDB() should report version 2 the next time the extension reloads (visible in DevTools under Application → IndexedDB → openloops, where the database now lists both raw_events and sessions as object stores).

With sessions in place, the next section takes this structured-but-unconnected data and groups sessions together into the intent threads this whole project is named after.

How to Cluster Sessions into Intent Threads

Sessions group events that happened close together in time. But the things you're actually trying to do rarely fit inside one session. Comparing laptops might span three sessions over four days. A question you keep meaning to look into might surface for ten minutes every few days for two weeks.

This section groups related sessions together into intent threads, then scores each thread for how confident openloops is that it represents something real and how alive it still is.

Two files do this work. src/pipeline/ambient.ts detects domains that are part of your daily routine rather than any particular intent, so they don't create false similarity between unrelated sessions. src/pipeline/threads.ts does the actual clustering and scoring.

Detecting Ambient Domains

Some domains show up in almost every session regardless of what you're doing: youtube.com as background noise, github.com if you're a developer who commits daily, or claude.ai if you use it as a general assistant. If clustering compared sessions on these domains the same way it compares them on anything else, two completely unrelated sessions would look similar just because they both touched youtube.com, and everything would eventually merge into one enormous thread.

ambient.ts solves this with a frequency check: a domain is ambient if it shows up on a large enough fraction of your active days, regardless of topic.

Create src/pipeline/ambient.ts:

import type { Session } from "../types";

export const UBIQUITY_THRESHOLD = 0.6;
export const MIN_ACTIVE_DAYS = 3;

function toDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

export function detectAmbientDomains(sessions: Session[]): Set {
  const allEvents = sessions.flatMap((s) => s.events);

  const activeDays = new Set(allEvents.map((e) => toDay(e.visitedAt)));
  const totalActiveDays = activeDays.size;

  if (totalActiveDays < MIN_ACTIVE_DAYS) {
    return new Set();
  }

  const domainDayMap = new Map>();
  for (const event of allEvents) {
    const day = toDay(event.visitedAt);
    if (!domainDayMap.has(event.domain)) {
      domainDayMap.set(event.domain, new Set());
    }
    domainDayMap.get(event.domain)!.add(day);
  }

  const ambient = new Set();
  for (const [domain, days] of domainDayMap) {
    const ubiquity = days.size / totalActiveDays;
    if (ubiquity >= UBIQUITY_THRESHOLD) {
      ambient.add(domain);
      console.log(
        `[openloops] ambient: \({domain} (\){days.size}/\({totalActiveDays} days, ubiquity=\){ubiquity.toFixed(2)})`
      );
    }
  }

  return ambient;
}

toDay collapses a timestamp down to a calendar-day string, so two events on the same day produce the same key, regardless of the exact time.

detectAmbientDomains first counts how many distinct days had any browsing activity at all – that's totalActiveDays – then builds a map from each domain to the set of days it appeared on. A domain's ubiquity is days.size / totalActiveDays, the fraction of your active days that domain showed up on. Anything at or above UBIQUITY_THRESHOLD 0.6 gets added to the returned set.

MIN_ACTIVE_DAYS exists because with only one or two days of data, almost every domain you visited would technically appear on 100% of your active days, and the detector would mark everything as ambient. Below three active days, it returns an empty set and skips detection entirely.

This approach has a real tradeoff. It correctly identifies genuinely ambient tools, but it can also suppress a domain you happened to research intensively every single day for a week, which would also cross the 60% threshold.

UBIQUITY_THRESHOLD is the knob for that tradeoff: raising it reduces false positives at the cost of letting some real ambient noise back in.

Extending the Database for Intent Threads

Threads need their own store. Bump DB_VERSION to 3 and add intent_threads, indexed by lastSeen, so the dashboard can show the most recently active threads first:

import type { RawEvent, Session, IntentThread } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: {
    key: string;
    value: RawEvent;
    indexes: { by_visitedAt: number };
  };
  sessions: {
    key: string;
    value: Session;
    indexes: { by_startedAt: number };
  };
  intent_threads: {
    key: string;
    value: IntentThread;
    indexes: { by_lastSeen: number };
  };
}

const DB_VERSION = 3;

export function getDB(): Promise> {
  if (!_db) {
    _db = openDB(DB_NAME, DB_VERSION, {
      upgrade(db) {
        if (!db.objectStoreNames.contains("raw_events")) {
          const s = db.createObjectStore("raw_events", { keyPath: "id" });
          s.createIndex("by_visitedAt", "visitedAt");
        }
        if (!db.objectStoreNames.contains("sessions")) {
          const s = db.createObjectStore("sessions", { keyPath: "id" });
          s.createIndex("by_startedAt", "startedAt");
        }
        if (!db.objectStoreNames.contains("intent_threads")) {
          const s = db.createObjectStore("intent_threads", { keyPath: "id" });
          s.createIndex("by_lastSeen", "lastSeen");
        }
      },
    });
  }
  return _db;
}

Then add the matching helpers:

export async function putThreads(threads: IntentThread[]): Promise {
  if (threads.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("intent_threads", "readwrite");
  await Promise.all([...threads.map((t) => tx.store.put(t)), tx.done]);
}

export async function clearThreads(): Promise {
  const db = await getDB();
  return db.clear("intent_threads");
}

export async function getAllThreads(): Promise {
  const db = await getDB();
  const index = db
    .transaction("intent_threads", "readonly")
    .store.index("by_lastSeen");

  let cursor = await index.openCursor(null, "prev");
  const results: IntentThread[] = [];
  while (cursor) {
    results.push(cursor.value);
    cursor = await cursor.continue();
  }
  return results;
}

export async function getThreadCount(): Promise {
  const db = await getDB();
  return db.count("intent_threads");
}

putThreads, clearThreads, and getThreadCount follow the same pattern as the sessions helpers from earlier. getAllThreads is the odd one out: instead of getAllFromIndex, which only returns ascending order, it opens a cursor on by_lastSeen in "prev" direction and walks it manually. That gives you threads ordered with the most recently active first, the order the dashboard wants for status-grouped cards.

Clustering Sessions into Threads

With ambient domains identified, src/pipeline/threads.ts now does the real work: grouping sessions into threads, then scoring and classifying each one.

The approach is greedy agglomerative clustering. Walk through sessions in chronological order, and for each one, either merge it into the most similar existing thread or start a new thread if nothing is similar enough.

Start with the imports, the tuning constants, and the similarity calculation:

import { getAllSessions, clearThreads, putThreads } from "../db/index";
import { detectAmbientDomains } from "./ambient";
import { hashId } from "../lib/util";
import type { Session, IntentThread } from "../types";

export const SIMILARITY_THRESHOLD = 0.15;
export const DOMAIN_WEIGHT = 0.5;
export const KEYWORD_WEIGHT = 0.5;

interface ThreadBuilder {
  id: string;
  sessions: Session[];
  domainSet: Set;
  keywordSet: Set;
}

function jaccard(a: Set, b: Set): number {
  if (a.size === 0 && b.size === 0) return 0;
  let intersection = 0;
  for (const item of a) {
    if (b.has(item)) intersection++;
  }
  const union = a.size + b.size - intersection;
  return intersection / union;
}

function similarity(
  session: Session,
  thread: ThreadBuilder,
  ambient: Set
): number {
  const sessionDomains  = new Set(session.domains.filter((d) => !ambient.has(d)));
  const threadDomains   = new Set([...thread.domainSet].filter((d) => !ambient.has(d)));
  const sessionKeywords = new Set(session.keywords);

  const domainScore   = jaccard(sessionDomains, threadDomains);
  const keywordScore  = jaccard(sessionKeywords, thread.keywordSet);

  return DOMAIN_WEIGHT * domainScore + KEYWORD_WEIGHT * keywordScore;
}

ThreadBuilder is a mutable accumulator used only during clustering: a thread in progress, with its sessions plus the union of all domains and keywords seen so far. jaccard is the standard set-similarity measure, the size of the intersection divided by the size of the union, returning 0 for two empty sets rather than dividing zero by zero.

similarity compares one candidate session against one in-progress thread. Before comparing domains, it filters ambient domains out of both sides, so a shared youtube.com never contributes to the score. It then computes a domain Jaccard score and a keyword Jaccard score separately, and combines them with DOMAIN_WEIGHT and KEYWORD_WEIGHT, both 0.5, giving domain overlap and keyword overlap equal say in the final number.

Next, the clustering loop itself:

function clusterSessions(
  sessions: Session[],
  ambient: Set
): ThreadBuilder[] {
  const threads: ThreadBuilder[] = [];

  for (const session of sessions) {
    let bestThread: ThreadBuilder | null = null;
    let bestScore = 0;

    for (const thread of threads) {
      const score = similarity(session, thread, ambient);
      if (score > bestScore) {
        bestScore = score;
        bestThread = thread;
      }
    }

    if (bestThread && bestScore >= SIMILARITY_THRESHOLD) {
      bestThread.sessions.push(session);
      for (const d of session.domains)  bestThread.domainSet.add(d);
      for (const k of session.keywords) bestThread.keywordSet.add(k);
    } else {
      threads.push({
        id: hashId(session.id, session.startedAt),
        sessions: [session],
        domainSet:  new Set(session.domains),
        keywordSet: new Set(session.keywords),
      });
    }
  }

  return threads;
}

clusterSessions relies on sessions already being sorted chronologically, which getAllSessions guarantees via its index. For each session, it scores against every thread built so far and keeps the best match.

If that best score clears SIMILARITY_THRESHOLD, the session merges in and its domains and keywords get folded into the thread's accumulated sets. This means that later sessions are compared against the thread's entire accumulated history rather than only its seed session. If nothing clears the threshold, the session becomes the seed of a brand-new thread.

A worked example shows how this plays out. Suppose detectAmbientDomains returned { youtube.com }, and three sessions arrive in this order:

S1: domains=[stackoverflow.com, typescriptlang.org]
    keywords=[typescript, generics, interface, mapped]

S2: domains=[stackoverflow.com, typescriptlang.org, github.com]
    keywords=[typescript, generics, utility, types]

S3: domains=[python.org, docs.python.org]
    keywords=[python, async, await, coroutine]

S1 arrives first. With no threads yet, it seeds Thread A: domainSet = {stackoverflow.com, typescriptlang.org}, keywordSet = {typescript, generics, interface, mapped}.

S2 is scored against Thread A. Neither set contains the ambient youtube.com, so nothing gets filtered out. The domain Jaccard is |{stackoverflow.com, typescriptlang.org}| / |{stackoverflow.com, typescriptlang.org, github.com}|, or 2/3 ≈ 0.667. The keyword Jaccard is |{typescript, generics}| / |{typescript, generics, interface, mapped, utility, types}|, or 2/6 ≈ 0.333. The combined similarity is 0.5 × 0.667 + 0.5 × 0.333 = 0.5, comfortably above SIMILARITY_THRESHOLD (0.15), so S2 merges into Thread A, whose sets grow to include github.com, utility, and types.

S3 is scored against Thread A. There's no overlap at all between {python.org, docs.python.org} and Thread A's domains, or between their keyword sets, so both Jaccard scores are 0 and the combined similarity is 0. That's below the threshold, so S3 seeds a new Thread B.

The result: Thread A holds the TypeScript research across two sessions, and Thread B holds the Python session on its own.

SIMILARITY_THRESHOLD is the single most consequential constant in this file, and 0.15 is lower than you might guess for a 50/50 weighted Jaccard score. A starting value like 0.3 sounds more principled. That would mean two sessions need to share roughly a third of their combined domains and keywords before they're considered part of the same thread.

Run that against real, messy browsing history, though, and it produces far too many threads: sessions that were obviously part of the same research, but didn't share quite enough keywords to clear 0.3, end up scattered across separate threads.

Dropping the threshold to 0.15 lets sessions merge on weaker but still real signal. Two sessions sharing just one domain and one keyword out of several can already cross 0.15, and the result is fewer, more coherent threads that actually match what the browsing history looks like.

This is the kind of constant you tune empirically rather than deriving it from first principles: build your threads, look at the result, and adjust.

buildThreads, covered next, prints a table of every thread's title, type, status, confidence, and top keywords specifically so you can eyeball this. If two threads obviously belong together, lower SIMILARITY_THRESHOLD. If one thread is clearly several unrelated topics glued together, raise it.

Scoring and Classifying Threads

Clustering produces groups of sessions, but a group of sessions isn't yet an IntentThread. The rest of threads.ts turns each group into something with a type, a confidence score, a status, and a set of human-readable signals explaining why.

A few small helpers come first:

export const BUYING_WORDS: readonly string[] = [
  "vs", "versus", "alternative", "alternatives",
  "comparison", "pricing", "price", "review", "reviews", "best",
];

export const LEARNING_WORDS: readonly string[] = [
  "how to", "tutorial", "tutorials", "docs", "documentation",
  "guide", "learn", "example", "examples", "crash course", "introduction",
];

const STATUS_ACTIVE_MS  = 48 * 60 * 60 * 1000;
const STATUS_STALLED_MS = 7  * 24 * 60 * 60 * 1000;

function toTitleCase(s: string): string {
  return s.charAt(0).toUpperCase() + s.slice(1);
}

function findMatches(titles: string[], wordList: readonly string[]): string[] {
  const lower = titles.map((t) => t.toLowerCase());
  const found = new Set();

  for (const word of wordList) {
    const isPhrase = word.includes(" ");
    for (const title of lower) {
      if (isPhrase) {
        if (title.includes(word)) found.add(word);
      } else {
        const tokens = title.split(/[^a-z0-9]+/);
        if (tokens.includes(word)) found.add(word);
      }
    }
  }

  return [...found];
}

function toCalendarDay(epochMs: number): string {
  return new Date(epochMs).toDateString();
}

BUYING_WORDS and LEARNING_WORDS are small vocabularies that signal intent. findMatches checks a list of page titles against one of these vocabularies, and handles single words and phrases differently: a multi-word entry like "how to" is checked as a substring, since it's specific enough that false positives are unlikely. But a single word like "review" is checked as a whole token, split out of the title on non-alphanumeric characters.

Without that distinction, "review" would match inside "overview" too, which would misclassify any thread that happened to involve an "Overview" page. toTitleCase and toCalendarDay are small formatting helpers used by the scoring function next.

That scoring function, scoreThread, is the longest function in the project, since it's where every signal collected so far gets turned into the fields on IntentThread:

function scoreThread(builder: ThreadBuilder): IntentThread {
  const { sessions, keywordSet } = builder;

  const firstSeen  = sessions[0].startedAt;
  const lastSeen   = sessions[sessions.length - 1].endedAt;

  const allEvents  = sessions.flatMap((s) => s.events);
  const totalEvents = allEvents.length;
  const daySet     = new Set(allEvents.map((e) => toCalendarDay(e.visitedAt)));
  const distinctDays = daySet.size;

  const allTitles      = allEvents.map((e) => e.title);
  const buyingMatches  = findMatches(allTitles, BUYING_WORDS);
  const learningMatches = findMatches(allTitles, LEARNING_WORDS);

  let type: IntentThread["type"];
  if (buyingMatches.length > 0) {
    type = "buying";
  } else if (learningMatches.length > 0) {
    type = "learning";
  } else if (distinctDays > 5 && sessions.length >= 3) {
    type = "planning";
  } else if (totalEvents >= 3) {
    type = "research";
  } else {
    type = "unclassified";
  }

  const age = Date.now() - lastSeen;
  const status: IntentThread["status"] =
    age < STATUS_ACTIVE_MS  ? "active"  :
    age < STATUS_STALLED_MS ? "stalled" :
    "dormant";

  const confidence = parseFloat((
    Math.min(distinctDays / 5, 1) * 0.35 +
    Math.min(sessions.length / 5, 1) * 0.25 +
    Math.min(totalEvents / 20, 1)  * 0.20 +
    (type !== "unclassified" ? 1 : 0)  * 0.20
  ).toFixed(2));

  const signals: string[] = [];

  if (distinctDays > 1)
    signals.push(`revisited across ${distinctDays} days`);
  if (type === "buying" && buyingMatches.length > 0)
    signals.push(`comparison language: ${buyingMatches.join(", ")}`);
  if (type === "learning" && learningMatches.length > 0)
    signals.push(`learning language: ${learningMatches.join(", ")}`);
  signals.push(`\({sessions.length} session\){sessions.length !== 1 ? "s" : ""}`);
  if (totalEvents > 5)
    signals.push(`${totalEvents} total events`);
  if (type === "planning")
    signals.push("sustained activity across many days");

  const ageDays = Math.floor(age / (24 * 60 * 60 * 1000));
  if (ageDays === 0)       signals.push("last active today");
  else if (ageDays === 1)  signals.push("last active yesterday");
  else                     signals.push(`last active ${ageDays} days ago`);

  const title =
    [...keywordSet].slice(0, 3).map(toTitleCase).join(" ") || "Untitled Thread";

  return {
    id: builder.id,
    title,
    sessions,
    type,
    confidence,
    status,
    firstSeen,
    lastSeen,
    distinctDays,
    signals,
  };
}

There's a lot here, so it's worth walking through each field on IntentThread in the order it's computed.

firstSeen and lastSeen come straight from the boundary sessions, since sessions arrives in chronological order from clustering. distinctDays reuses the same calendar-day collapsing as ambient.ts. This time it counts how many different days this thread's events span, regardless of how many total active days you had overall.

Classification into type is a cascade, and the order matters. Comparison language (BUYING_WORDS) is checked first, because a thread where you're comparing two frameworks is "buying" even if it also contains tutorial pages. Comparison intent is the stronger signal.

Learning language comes next. After that, planning is reserved for threads that span more than five distinct days and have at least three sessions of sustained, recurring activity rather than a single deep dive.

research is the catch-all for anything with at least three events that didn't match anything more specific, and unclassified is what's left, usually threads with too little activity to say anything confident about.

status is purely a function of how long ago lastSeen was: under 48 hours is active, under 7 days is stalled, anything older is dormant.

confidence is a weighted sum of four signals, each normalized to a maximum of 1 before weighting, so the total can't exceed 1 either. distinctDays / 5, capped at 1, contributes up to 35%, treating five or more distinct days as fully confident on that axis. sessions.length / 5, capped at 1, contributes up to 25%. totalEvents / 20, capped at 1, contributes up to 20%. And whether type is anything other than unclassified contributes the final 20% as an all-or-nothing bonus.

A thread revisited across five-plus days, across five-plus sessions, with twenty-plus events, that also classified cleanly, scores a full 1.0. A thread that's a single session with two events and no classification scores close to 0.

signals is a plain-English audit trail for the confidence score and status: it explains why a thread looks the way it does, listing things like how many days it was revisited across, what comparison or learning language was found, the session and event counts, and how recently it was last active. The dashboard surfaces these directly.

Finally, title is a placeholder: the top three keywords from the thread's accumulated keywordSet, title-cased and joined with spaces, or "Untitled Thread" if there are none.

This is deliberately weak. Later in this guide, AI labeling replaces this heuristic title, along with summary and nextStep, with something grounded in what the thread is actually about (but the thread is fully usable without that step, too).

Putting it Together

buildThreads ties everything in this section together:

export async function buildThreads(): Promise<{ sessions: number; threads: number }> {
  const sessions = await getAllSessions();

  if (sessions.length === 0) {
    await clearThreads();
    return { sessions: 0, threads: 0 };
  }

  const ambient = detectAmbientDomains(sessions);

  const builders = clusterSessions(sessions, ambient);

  const substantive = builders.filter(
    (b) => !(b.sessions.length === 1 && b.sessions[0].events.length < 3)
  );

  const threads = substantive.map(scoreThread);

  await clearThreads();
  await putThreads(threads);

  console.table(
    threads.map((t) => ({
      title:        t.title,
      type:         t.type,
      status:       t.status,
      confidence:   t.confidence,
      distinctDays: t.distinctDays,
      sessions:     t.sessions.length,
      events:       t.sessions.reduce((n, s) => n + s.events.length, 0),
      keywords:     [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 5).join(", "),
    }))
  );

  return { sessions: sessions.length, threads: threads.length };
}

The order here matters. detectAmbientDomains runs once, over every session, before any clustering happens, since ambient detection needs the full picture of your browsing to know what counts as "every day".

clusterSessions then produces ThreadBuilders, which get filtered before scoring: a ThreadBuilder with exactly one session and fewer than three events is almost always a stray page load that didn't merge with anything, so it's dropped rather than becoming a thread with a confidence near zero.

Everything that survives gets scored by scoreThread, persisted, and printed via console.table, which is the tuning aid mentioned earlier. If you open the service worker's console after running this, every thread is laid out in a sortable table. This is the fastest way to spot a SIMILARITY_THRESHOLD that's too high or too low.

Checkpoint

Like the previous two sections, buildThreads doesn't have a UI yet. It'll get wired up to a "Build intent map" button alongside the other two when you design the dashboard later in this guide.

For now, confirm that src/pipeline/ambient.ts, the updated src/db/index.ts, and src/pipeline/threads.ts all build without errors, and that getDB() reports version 3 the next time the extension reloads. intent_threads should now be listed alongside raw_events and sessions in DevTools.

At this point, the entire core pipeline runs end to end, locally, with no API keys involved: your browsing history becomes raw events, raw events become sessions, and sessions become scored, classified intent threads.

Everything from here is optional and additive: cleaning up a source of self-referential noise this pipeline doesn't yet handle (which you probably want to look at and incorporate), then AI labeling, brand grounding, and the dashboard that ties it all together.

How to Clean Up Self-Referential Noise

Run the pipeline a few times against your own browsing and a strange kind of thread starts appearing: one made entirely of openloops itself.

The dashboard is a web page, so every time you open it to check your threads, that page load gets captured as an event. If you're also developing the extension, your localhost dev server and any private-network addresses end up in the data too.

The tool ends up watching itself use itself, and that self-reference pollutes the intent map in two distinct ways which are worth separating.

The Two Problems

The first problem is the extension's own pages. A Chrome extension's dashboard loads from a chrome-extension:// URL, and Chrome's own internal pages use chrome://. Left unfiltered, opening the openloops dashboard ten times in an afternoon produces ten events on a chrome-extension:// origin, which cluster happily into a thread about, essentially, looking at your threads.

This is circular and useless, and because you tend to open the dashboard often while the rest of your browsing is quieter, this self-thread can score deceptively high on recency and session count.

The second problem is local development infrastructure. If you're building the extension, or any local project, your history fills with localhost:5173, 127.0.0.1:8080, and maybe LAN addresses like 192.168.1.40. These are real page visits as far as Chrome is concerned, but they carry no browsing intent in the sense openloops cares about. Worse, they'd later be sent to context.dev during brand enrichment, where they can never resolve to anything and would only waste API credits.

Both problems share a root cause: the pipeline is capturing URLs that aren't really part of your browsing in the first place. The fix is to define what counts as a real, external web page once, and apply that definition everywhere a URL or domain enters the system.

One Definition, Applied Everywhere

The two helpers that do this, isHttpUrl and isLocalHost, were written back when you first built src/lib/util.ts. We deliberately introduced them early for exactly this moment.

isHttpUrl returns true only for http:// and https:// URLs, which excludes chrome-extension://, chrome://, about:, and file:// in one stroke. isLocalHost returns true for localhost, loopback and private IP ranges, and .local hostnames.

The thing that makes them effective is consistency: the same two functions guard every entry point, so the definition of "a real page" can never drift between one part of the pipeline and another. There are three such entry points.

Live capture, in src/background.ts, calls isHttpUrl before recording anything:

if (!isHttpUrl(url)) return;

The backfill, in src/pipeline/backfill.ts, applies the same guard to every history item before fetching its visits:

if (!item.url) return [];
if (!isHttpUrl(item.url)) return [];

And the noise filter, in src/pipeline/noise.ts, checks both helpers at the very top of isNoise, before any of its domain or title rules run:

export function isNoise(event: RawEvent): boolean {
  if (!isHttpUrl(event.url)) return true;
  if (isLocalHost(event.domain)) return true;
  return domainIsBlocked(event.domain) || titleIsGeneric(event.title, event.domain);
}

Capture and backfill already screen out non-web URLs, so checking isHttpUrl a third time inside isNoise looks redundant, and in normal operation it is. The third check is a guarantee: if a stray non-web event ever reaches raw_events through some path you didn't anticipate (like a future capture mechanism, imported data, or a bug), it still can't survive into a session.

Each stage defends its own input rather than trusting that an earlier stage did its job. This is what keeps a single missed case from silently propagating all the way into the intent map.

Defending the Enrichment Boundary Too

The same isLocalHost check appears once more, in the brand enrichment step you'll build next, where domains get sent to context.dev. Even though isNoise already strips local addresses before sessionization, the enrichment function filters them again before making any network call:

const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

The reasoning is the same defense-in-depth idea, applied to a boundary where the cost of a mistake is higher. A local address that somehow reached a thread's domain list shouldn't just be useless noise in the UI. It should never leave your machine as part of an API request. Putting the filter directly at the network boundary means that guarantee holds regardless of what happened upstream.

Checkpoint

After loading the updated build, openloops should stop appearing in its own intent map. To verify, open the dashboard a handful of times, browse some real pages, then rebuild the pipeline: the chrome-extension:// self-thread should be gone, and no localhost or private-IP domains should appear in any thread's domain list.

If you inspect raw_events in DevTools, you may still see live-captured events from before this fix, since the backfill clears and rewrites events but live capture appends. Running a fresh "Scan my history" wipes and repopulates raw_events cleanly under the new rules.

With the pipeline now producing a clean intent map of genuinely external browsing, it's worth making those threads more legible.

Up to now, each thread's title is just its top three keywords stitched together, and there's no summary or suggested next step at all. The next section adds the first optional, key-gated layer: AI labeling with Claude.

How to Label Threads with Claude

A thread titled "Typescript Generics Handbook" is readable, but it's a description of the keywords – not of what you were trying to do. "Learning TypeScript's advanced type system" is the kind of label a person would actually write, and the difference between those two is the gap this section closes.

Claude reads each thread's keywords, domains, and sample page titles, and returns a real title, a one-sentence summary, a classification, and a concrete next step.

This is the first part of openloops that calls an external API and requires a key. Everything about its design is shaped by one constraint: the request has to survive real data, where a person might have thirty or forty threads, each carrying a dozen page titles.

The naïve version of this is to send all the threads in one request and ask for all the labels back. And that's exactly what the first implementation did. But it failed in a way worth walking through, because the fix is the most instructive part of the whole section.

Storing Keys Locally

Before any API call, the key needs somewhere to live. openloops keeps it in chrome.storage.local, which never syncs anywhere and never leaves the device. Create src/lib/settings.ts:

export async function getApiKey(): Promise {
  const result = await chrome.storage.local.get("anthropicApiKey");
  return (result.anthropicApiKey as string) ?? null;
}

export async function setApiKey(key: string): Promise {
  await chrome.storage.local.set({ anthropicApiKey: key });
}

The same file later grows parallel getters and setters for the context.dev key and the assistant's model and effort preferences, all following this identical shape. So it's enough to understand this one pair to understand all of them.

The First Version, and How it Broke

The first labeling implementation sent every thread to Claude in a single request: serialize all forty threads into one JSON payload, ask for a JSON array of forty labels in return, parse it, write it back. It worked perfectly with five or six threads during early testing, then silently produced nothing once a real history with thirty-plus threads went through it. There was no error or thrown exception, just threads that kept their old keyword titles as if the labeling had never run.

The cause was output token truncation. A request specifies max_tokens, the ceiling on how much the model may generate in response, and forty threads' worth of titles, summaries, and next steps is a lot of output. When the response hit that ceiling mid-generation, the JSON array was cut off partway through an opening [ and thirty complete objects followed by half of the thirty-first and no closing ]. JSON.parse on that throws, the catch block logged it and returned nothing, and because labeling was designed to fail gracefully and leave existing titles intact, the failure was invisible from the UI.

Two design changes came out of this, and both are in the final code: split the work into small batches so no single response can grow large enough to truncate, and make the parsing resilient enough that one bad batch can't take down the whole run.

Batching the Requests

Create src/pipeline/label.ts, starting with the per-batch request function:

import { getAllThreads, putThreads, getAllBrands } from "../db/index";
import type { IntentThread } from "../types";

interface ThreadDescriptor {
  id: string;
  keywords: string[];
  domains: string[];
  sampleTitles: string[];
  domainContext: string[];
}

interface LabelResult {
  id: string;
  title: string;
  summary: string;
  type: string;
  nextStep: string;
}

const VALID_TYPES: ReadonlySet = new Set([
  "buying",
  "research",
  "learning",
  "planning",
  "unclassified",
]);

const BATCH_SIZE = 10;
const MAX_TOKENS_PER_BATCH = 4000;

async function callClaudeBatch(
  apiKey: string,
  systemPrompt: string,
  batch: ThreadDescriptor[],
): Promise {
  const response = await fetch("https://api.anthropic.com/v1/messages", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": apiKey,
      "anthropic-version": "2023-06-01",
      "anthropic-dangerous-direct-browser-access": "true",
    },
    body: JSON.stringify({
      model: "claude-haiku-4-5-20251001",
      max_tokens: MAX_TOKENS_PER_BATCH,
      system: systemPrompt,
      messages: [
        {
          role: "user",
          content: JSON.stringify(batch),
        },
      ],
    }),
  });

  if (!response.ok) {
    let body = "";
    try { body = (await response.text()).slice(0, 400); } catch { }
    console.error(
      `[openloops] label: API request failed\n` +
      `  → HTTP \({response.status} \){response.statusText}\n` +
      `  body: ${body || "(empty)"}`,
    );
    if (response.status === 401) {
      throw new Error("Invalid API key. Check your Anthropic API key and try again.");
    }
    throw new Error(`API request failed: \({response.status} \){response.statusText}`);
  }

  const data = await response.json();
  const raw: string = data.content[0].text;

  const cleaned = raw
    .trim()
    .replace(/^```(?:json)?\s*/, "")
    .replace(/```\s*$/, "")
    .trim();

  try {
    return JSON.parse(cleaned);
  } catch (err) {
    console.error(`[openloops] label: parse error: ${err instanceof Error ? err.message : String(err)}`);
    console.error(`[openloops] label: raw tail (last 400 chars):\n${raw.slice(-400)}`);
    return null;
  }
}

BATCH_SIZE of 10 with MAX_TOKENS_PER_BATCH of 4000 is the direct answer to the truncation problem. Ten threads' worth of labels comfortably fits inside 4000 output tokens with room to spare, so a batch can't hit the ceiling and get cut off. A history with forty threads becomes four independent requests rather than one oversized one.

The request itself uses raw fetch rather than Anthropic's TypeScript SDK, because the SDK isn't built to run in a browser or extension context.

Browser-originated calls to the Anthropic API also require the anthropic-dangerous-direct-browser-access header, which is what opts into this usage pattern. The model is Claude Haiku, the fastest and cheapest in the lineup, which is well-matched to a high-volume, structured-output task like this one where you're making several calls and want them quick.

The error handling splits into two deliberately different behaviors. An HTTP-level failure (a 401 from a bad key, a 429 from rate limiting) throws, because every subsequent batch would fail the same way and there's no point continuing. A parse failure, by contrast, returns null rather than throwing, so the caller can skip just that one batch and keep going with the rest.

The fence-stripping before JSON.parse handles a common real-world wrinkle: models sometimes wrap JSON output in a Markdown code fence (```json), even when asked for raw JSON. The two .replace calls strip a leading fence and a trailing fence if present, tolerating surrounding whitespace, so a response comes through whether or not it arrived wrapped.

When parsing still fails, the catch logs the last 400 characters of the raw response, which is precisely where you'd see the truncation signature of a cut-off array, the diagnostic that would have made the original bug obvious in minutes.

Building the Prompt and Merging Results

The public labelThreads function builds the descriptors, runs the batches, and merges what comes back:

export async function labelThreads(apiKey: string): Promise<{ labeled: number }> {
  const threads = await getAllThreads();
  if (threads.length === 0) return { labeled: 0 };

  const allBrands = await getAllBrands();
  const brandMap = new Map(allBrands.map((b) => [b.domain, b]));

  const descriptors: ThreadDescriptor[] = threads.map((t) => {
    const keywords = [...new Set(t.sessions.flatMap((s) => s.keywords))].slice(0, 8);
    const domains  = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5);
    const titles   = [...new Set(t.sessions.flatMap((s) => s.events.map((e) => e.title)))].slice(0, 20);

    const domainContext = domains
      .map((d) => {
        const brand = brandMap.get(d);
        if (!brand || !brand.name) return null;
        let line = `\({d}: \){brand.name}`;
        if (brand.description) line += ` — ${brand.description}`;
        if (brand.industry)    line += ` (${brand.industry})`;
        return line;
      })
      .filter((s): s is string => s !== null);

    return { id: t.id, keywords, domains, sampleTitles: titles, domainContext };
  });

  const systemPrompt = `You label browsing intent threads. Return ONLY a JSON array — no markdown fences, no explanation.
Each element: { "id": "", "title": "<3-6 word title>", "summary": "<1 sentence>", "type": "", "nextStep": "" }
The nextStep must be grounded in what the person was actually looking at. Be specific — name the actual decision, comparison, or action (e.g. "Decide between MacBook Pro and Dell XPS — your open question was battery life") rather than generic advice ("continue researching"). Use the sampleTitles and domainContext to ground it.
Each thread descriptor may include a "domainContext" array of company descriptions for the sites visited. When present, use these to produce sharper, more specific titles, summaries, and next steps grounded in what each company actually does.
Respond with exactly one array covering every thread in the request.`;

  const allResults: LabelResult[] = [];
  let failedBatches = 0;
  for (let i = 0; i < descriptors.length; i += BATCH_SIZE) {
    const batch = descriptors.slice(i, i + BATCH_SIZE);
    const results = await callClaudeBatch(apiKey, systemPrompt, batch);
    if (results === null) {
      failedBatches++;
      continue;
    }
    allResults.push(...results);
  }

  const byId = new Map(allResults.map((r) => [r.id, r]));

  let labeled = 0;
  const updated = threads.map((t) => {
    const label = byId.get(t.id);
    if (!label) return t;

    const type = VALID_TYPES.has(label.type as IntentThread["type"])
      ? (label.type as IntentThread["type"])
      : t.type;

    labeled++;
    return {
      ...t,
      title:    label.title    || t.title,
      summary:  label.summary  || undefined,
      nextStep: label.nextStep || undefined,
      type,
    };
  });

  await putThreads(updated);
  return { labeled };
}

Each thread is compressed into a ThreadDescriptor carrying only what Claude needs to label it: up to eight keywords, five domains, and twenty sample page titles, capped so a thread with hundreds of events doesn't bloat the payload.

The domainContext field is the hook for the brand-grounding step covered in the next section. It's empty for now since no brands have been fetched yet, which is exactly why labeling works fine on its own and gets sharper once grounding is added.

The merge step is where a failed batch costs you only its own threads. Results come back as a flat list across all successful batches, indexed by thread id into byId.

Then every thread is walked: if a label came back for it, the AI title, summary, next step, and type are merged in, with the returned type validated against VALID_TYPES and falling back to the heuristic type if the model returned something unexpected. If no label came back, because that thread's batch failed to parse, the thread is returned untouched, keeping the keyword title and heuristic classification it already had.

A single failed batch costs you ten threads' worth of polish, not the entire run, and never corrupts a thread with malformed data.

Notice that title, summary, and nextStep all guard against empty strings with || t.title and || undefined. A thread always has a usable title even if the model returned a blank one, and summary and nextStep stay undefined rather than becoming empty strings. This keeps the dashboard's "does this thread have a summary?" checks honest.

Checkpoint

Labeling needs a key and a button, both of which arrive with the dashboard later in this guide, so a full end-to-end test waits until then.

What you can verify now is that src/lib/settings.ts and src/pipeline/label.ts compile, and that the request shape is correct by calling labelThreads with a real key from a temporary test harness if you want immediate feedback. When it runs against built threads, the console will show batch progress, and your threads' titles in IndexedDB will change from keyword fragments to readable phrases, with summary and nextStep fields appearing for the first time.

The labels are already a large improvement, but they're working from keywords and bare domain names. This means a thread built around mastra.ai and langchain.com has no idea those are AI agent frameworks. It only sees two domain strings.

The next section closes that gap by resolving domains into real company descriptions before labeling. This is the grounding step that gives the AI something concrete to reason about.

How to Ground Labels with context.dev

This is the most distinctive idea in openloops, so it's worth stating plainly before any code: instead of asking the model to label a thread from keywords and bare domain names, openloops first resolves each domain into a real company description – what the company is, what industry it's in, what it actually does – and feeds those descriptions into the labeling prompt. The model labels the thread knowing that mastra.ai and langchain.com are both AI agent frameworks, rather than seeing two opaque strings it has to guess about.

A thread whose keywords are "mastra langchain sholajegede" produces, ungrounded, a title like "Mastra Langchain Sholajegede", a literal echo of the keywords. Grounded with the knowledge that those domains are competing agent frameworks, the same thread becomes "Benchmarking Mastra against LangChain", a title that names the actual intent.

The raw material for a good label was always there in the browsing. What was missing was the context to interpret it, and that context is exactly what a brand-intelligence API provides.

What the API Returns

openloops uses context.dev, which resolves a domain into a structured brand record: company name, a one-line description, industry classification, brand colors, and logo URLs. The grounding step needs the name, description, and industry, while the logo and colors get used later by the dashboard to render domain chips.

This step is entirely optional: the labeling from the previous section works without it, and grounding simply makes the output sharper when a context.dev key is present.

Like the Anthropic key, the context.dev key lives in chrome.storage.local, via the same getter/setter pattern in src/lib/settings.ts:

export async function getContextKey(): Promise {
  const result = await chrome.storage.local.get("contextDevApiKey");
  return (result.contextDevApiKey as string) ?? null;
}

export async function setContextKey(key: string): Promise {
  await chrome.storage.local.set({ contextDevApiKey: key });
}

Brand records also need a place to be cached, since resolving the same domain twice is wasteful and costs API credits. Bump DB_VERSION to 4 and add a domain_brands store keyed by domain:

import type { RawEvent, Session, IntentThread, Brand } from "../types";

interface OpenloopsDB extends DBSchema {
  raw_events: { key: string; value: RawEvent; indexes: { by_visitedAt: number } };
  sessions: { key: string; value: Session; indexes: { by_startedAt: number } };
  intent_threads: { key: string; value: IntentThread; indexes: { by_lastSeen: number } };
  domain_brands: {
    key: string;
    value: Brand;
  };
}

const DB_VERSION = 4;

Inside the upgrade callback, the new store is added with the same guard as the others, and domain_brands is keyed on domain rather than id because a domain is its own natural unique key:

if (!db.objectStoreNames.contains("domain_brands")) {
  db.createObjectStore("domain_brands", { keyPath: "domain" });
}

The matching helpers add one that's specific to caching, getCachedDomains. This returns the set of domains already resolved so the enrichment step can skip them:

export async function getBrand(domain: string): Promise {
  const db = await getDB();
  return db.get("domain_brands", domain);
}

export async function putBrands(brands: Brand[]): Promise {
  if (brands.length === 0) return;
  const db = await getDB();
  const tx = db.transaction("domain_brands", "readwrite");
  await Promise.all([...brands.map((b) => tx.store.put(b)), tx.done]);
}

export async function getAllBrands(): Promise {
  const db = await getDB();
  return db.getAll("domain_brands");
}

export async function getCachedDomains(): Promise> {
  const db = await getDB();
  const keys = await db.getAllKeys("domain_brands");
  return new Set(keys);
}

Fetching One Brand

Create src/pipeline/enrich.ts. The core is a function that resolves a single domain, and most of its length is there to make sure a slow or failing lookup can never hang or crash the whole step:

import { getCachedDomains, putBrands } from "../db/index";
import { isLocalHost } from "../lib/util";
import type { Brand } from "../types";

const API_BASE        = "https://api.context.dev/v1";
const LOGO_LINK_BASE  = "https://logos.context.dev";

const REQUEST_TIMEOUT_MS = 15_000;
const BATCH_SIZE     = 3;
const BATCH_DELAY_MS = 2_000;

interface FetchResult {
  brand: Brand | null;
  errorCode?: string;
}

async function fetchBrand(domain: string, contextKey: string): Promise {
  const url = `\({API_BASE}/brand/retrieve?domain=\){encodeURIComponent(domain)}`;
  const headers = { Authorization: `Bearer ${contextKey}` };

  async function attempt(): Promise {
    const ctrl = new AbortController();
    const tid  = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
    try {
      return await fetch(url, { headers, signal: ctrl.signal });
    } finally {
      clearTimeout(tid);
    }
  }

  try {
    let res = await attempt();

    if (res.status === 408) {
      res = await attempt();
    }

    if (!res.ok) {
      let body = "";
      try { body = (await res.text()).slice(0, 400); } catch { }
      console.error(`[openloops] enrich: HTTP \({res.status} for "\){domain}" — ${body}`);
      return { brand: null, errorCode: String(res.status) };
    }

    let data: { status?: string; brand?: Record };
    try {
      data = await res.json();
    } catch (e) {
      return { brand: null, errorCode: "parse" };
    }

    if (data.status !== "ok" || !data.brand) {
      return { brand: null, errorCode: "shape" };
    }

    const b = data.brand as {
      title?:        string;
      description?:  string;
      colors?:       { hex?: string }[];
      logos?:        { url?: string }[];
      industries?:   { eic?: { industry?: string; subindustry?: string }[] };
    };

    const logoUrl =
      b.logos?.[0]?.url ||
      `\({LOGO_LINK_BASE}?domain=\){encodeURIComponent(domain)}`;

    return {
      brand: {
        domain,
        name:        b.title                          ?? domain,
        description: b.description                    ?? "",
        industry:    b.industries?.eic?.[0]?.industry ?? "",
        logoUrl,
        brandColor:  b.colors?.[0]?.hex               ?? "",
      },
    };

  } catch (err) {
    if (err instanceof Error && err.name === "AbortError") {
      return { brand: null, errorCode: "timeout" };
    }
    return { brand: null, errorCode: "network" };
  }
}

The request authenticates with a bearer token and hits a single brand/retrieve endpoint. The attempt inner function wraps each call in an AbortController with a 15-second timeout, so a stalled connection aborts itself rather than hanging the enrichment step indefinitely.

The finally clears the timer whether the request succeeds, fails, or aborts. A 408 response from context.dev means a cold cache miss on their side, which their documentation says to retry once, so a single retry handles it before giving up.

The response is unpacked defensively at every level: a non-OK status returns a FetchResult with the HTTP code, a body that won't parse returns a "parse" error, and a response whose shape isn't what's expected returns a "shape" error.

When the brand record does come through, each field falls back to a sensible default if absent, the company name falls back to the domain itself, the description and industry to empty strings, and the logo to context.dev's keyless logo CDN if the record carries no logo URL.

Every failure path returns { brand: null, errorCode } rather than throwing, which is what lets the batch driver above it treat a single domain's failure as a skip rather than a crash.

Enriching Domains in Batches

The public enrichDomains function resolves a list of domains, skipping ones already cached and respecting the API's rate limit:

export async function enrichDomains(
  contextKey: string,
  domains: string[],
): Promise<{ enriched: number; failed: number; error?: string }> {
  const unique = [...new Set(domains)].filter((d) => !isLocalHost(d));

  let cached: Set;
  try {
    cached = await getCachedDomains();
  } catch (err) {
    return { enriched: 0, failed: 0, error: "DB error" };
  }

  const toFetch = unique.filter((d) => !cached.has(d));
  if (toFetch.length === 0) return { enriched: 0, failed: 0 };

  let enriched = 0;
  let failed   = 0;
  let firstErrorCode: string | undefined;

  for (let i = 0; i < toFetch.length; i += BATCH_SIZE) {
    const batch   = toFetch.slice(i, i + BATCH_SIZE);
    const results = await Promise.all(batch.map((d) => fetchBrand(d, contextKey)));

    const brands = results.map((r) => r.brand).filter((b): b is Brand => b !== null);

    for (const r of results) {
      if (!r.brand) {
        failed += 1;
        if (!firstErrorCode) firstErrorCode = r.errorCode;
      }
    }

    if (brands.length > 0) {
      try {
        await putBrands(brands);
        enriched += brands.length;
      } catch (err) {
        failed += brands.length;
      }
    }

    if (i + BATCH_SIZE < toFetch.length) {
      await new Promise((resolve) => setTimeout(resolve, BATCH_DELAY_MS));
    }
  }

  let error: string | undefined;
  if (firstErrorCode) {
    const map: Record = {
      "401":     "401 — invalid key",
      "403":     "403 — check key permissions",
      "429":     "429 — rate limited, try again later",
      "timeout": "request timeout (15 s)",
      "network": "unreachable — check network/CORS",
    };
    error = map[firstErrorCode] ?? firstErrorCode;
  }

  return { enriched, failed, error };
}

The function opens by stripping local addresses with isLocalHost, the enrichment-boundary guard discussed in the self-referential noise section. This means that a dev server can never be sent to context.dev even if it slipped into a thread's domain list. It then removes already-cached domains via getCachedDomains, so re-running enrichment only ever fetches domains it hasn't seen. This keeps credit usage proportional to new browsing rather than total browsing.

The remaining domains are fetched three at a time, with a two-second pause between batches. This keeps the request rate well under the API's limit without making the user wait through a long serial queue.

Failures are tallied rather than thrown: a domain that fails to resolve increments failed and records its error code, but the loop carries on. The first error code encountered gets mapped to a human-readable message at the end so the UI can show something useful, such as an invalid-key or rate-limit notice.

The whole function returns counts rather than raising, which matters because the dashboard runs enrichment immediately before labeling, and a problem fetching brands should never prevent the labeling that follows it.

How Grounding Feeds Back into Labeling

Grounding connects back to labelThreads from the previous section, which already builds a domainContext array for each thread by looking up every domain in the brand cache:

const domainContext = domains
  .map((d) => {
    const brand = brandMap.get(d);
    if (!brand || !brand.name) return null;
    let line = `\({d}: \){brand.name}`;
    if (brand.description) line += ` — ${brand.description}`;
    if (brand.industry)    line += ` (${brand.industry})`;
    return line;
  })
  .filter((s): s is string => s !== null);

Before enrichment runs, the brand cache is empty, every lookup returns nothing, domainContext is an empty array, and the prompt falls back to keywords and domain names alone.

After enrichment, the same code produces lines like mastra.ai: Mastra — TypeScript framework for building AI agents (Developer Tools), and the labeling prompt's instruction to use domainContext "to produce sharper, more specific titles, summaries, and next steps" finally has something to work with.

The two steps are decoupled by design: labeling never requires grounding, but grounding measurably improves labeling. This is why the dashboard runs them in sequence as a single "enrich, then label" action.

Checkpoint

Like the labeling step, enrichment is exercised through the dashboard, so the full path waits for the dashboard section. For now, confirm that src/pipeline/enrich.ts and the updated src/db/index.ts compile, and that getDB() reports version 4 with domain_brands present in DevTools.

Once it runs against real threads with a context.dev key, the domain_brands store fills with cached records, and your thread labels should noticeably sharpen. The clearest single demonstration will be any thread built around niche or technical domains whose names don't, on their own, reveal what they are.

Every piece of the engine now exists: capture, sessions, clustering, scoring, labeling, and grounding. What's missing is the surface that drives them and shows the results.

The next section builds the dashboard, the three-column React interface with its onboarding flow and pipeline state machine, that turns this pipeline into something a person actually uses.

How to Design the Dashboard

The dashboard is a single React component tree rendered into the full-tab page you wired up at the very start when you set options_page in the manifest.

It does three jobs: it drives the pipeline (the buttons that run scanning, session-building, thread-building, and labeling), it displays the resulting intent map (threads grouped by status), and it hosts the assistant covered in the next section.

This section focuses on the structure and the one piece of genuinely interesting logic: the state machine that decides which pipeline button is live at any moment. We'll treat the styling at a summary level here, since it's mostly conventional CSS.

The Three-Column Layout

src/dashboard/App.tsx lays out three columns inside a flex shell. The left rail holds the pipeline controls, the API-key inputs, and the status filter. The center column is the main content: either the onboarding welcome screen or the intent map of threads. The right column holds overview statistics and the assistant chat.

┌──────────────┬───────────────────────────┬──────────────────┐
│  LEFT RAIL   │       MAIN COLUMN         │  RIGHT COLUMN    │
│              │                           │                  │
│  Pipeline    │  Welcome screen           │  Overview stats  │
│   · Scan     │    — or —                 │                  │
│   · Sessions │  Intent map:              │  Assistant chat  │
│   · Threads  │   ACTIVE   threads        │   · messages     │
│              │   STALLED  threads        │   · composer     │
│  Keys        │   DORMANT  threads        │   · model/effort │
│  Filter      │                           │                  │
└──────────────┴───────────────────────────┴──────────────────┘

Each thread renders as a card showing its title, type and status pills, the AI summary, the next-step row with a Resume button, a confidence bar, and a collapsible details section with domains, keywords, and signals.

The cards are grouped into ACTIVE, STALLED, and DORMANT sections, sorted by confidence within each group. The threads most worth acting on rise to the top of the most urgent group.

The styling lives in src/dashboard/app.css and is conventional: a dark theme defined through CSS custom properties (a near-black background, a single orange accent at --accent: #ff5c33, a small scale of grays for text and borders), a monospace font for labels and metadata, and a sans-serif for content.

The design choices that matter for usability are the status-based color coding (the accent for active, a muted amber for stalled, gray for dormant) and the confidence bar's width mapping directly to the thread's confidence score.

None of the CSS is load-bearing for understanding the build, so rather than reproduce it, the rest of this section focuses on the logic the styling sits on top of.

The Pipeline State Machine

The pipeline has a strict order: you can't build sessions before scanning history, and you can't build threads before building sessions. The dashboard encodes this as a small state machine, and getting it right is what makes the interface feel guided rather than confusing. Every button is either disabled (its input doesn't exist yet), highlighted as the next action to take, or done (re-runnable, but no longer the obvious next step).

type PipelineState = "disabled" | "next" | "done";

function pipelineStates(
  hasScanned: boolean,
  eventCount: number | null,
  sessionCount: number | null,
  threadCount: number | null,
): { scan: PipelineState; sessions: PipelineState; threads: PipelineState } {
  const hasEvents   = (eventCount   ?? 0) > 0;
  const hasSessions = (sessionCount ?? 0) > 0;
  const hasThreads  = (threadCount  ?? 0) > 0;

  if (!hasScanned)  return { scan: "next", sessions: "disabled", threads: "disabled" };
  if (!hasSessions) return { scan: "done", sessions: hasEvents ? "next" : "disabled", threads: "disabled" };
  if (!hasThreads)  return { scan: "done", sessions: "done", threads: "next" };
  return { scan: "done", sessions: "done", threads: "done" };
}

The function reads the presence of data at each stage and returns the state of all three buttons. Before any scan, only Scan is live, marked next, while the other two are disabled.

Once events exist but sessions don't, Scan flips to done and Sessions becomes next. Once sessions exist but threads don't, Threads becomes next. Once all three stages have produced output, everything is done, every step re-runnable but none demanding attention. The cascade walks the pipeline in order and lights up exactly one next action at a time, which is what turns a row of three buttons into a guided sequence.

The first parameter, hasScanned, is more subtle than a simple count. It's where a piece of plumbing from the very first capture section pays off.

The check can't just be "are there any events," because live capture starts populating raw_events the moment the extension is installed. There would always be events, and the onboarding would skip straight past the Scan step before the user had ever scanned.

The fix is the source field on every RawEvent, set to "backfill" or "live" back when you built capture. hasScanned comes from a dedicated query that checks specifically for backfill events:

export async function hasBackfillEvents(): Promise {
  const db = await getDB();
  let cursor = await db.transaction("raw_events", "readonly").store.openCursor();
  while (cursor) {
    if (cursor.value.source === "backfill") return true;
    cursor = await cursor.continue();
  }
  return false;
}

This walks raw_events until it finds a single event with source === "backfill", returning early the moment it does. Live-captured events alone never satisfy it, so "Scan my history" stays lit as the first step until the user actually runs a backfill, which is the correct onboarding behavior. The seemingly minor decision to tag each event with its origin, made several sections ago, is what makes this distinction possible now.

Driving the Welcome Screen from the Same Machine

A first-time user with no threads sees a centered welcome screen instead of an empty intent map. But rather than give that screen its own separate logic, the dashboard drives it from the same pipelineStates output. Whichever step is currently next determines which single call-to-action the welcome screen shows:

let welcomeStep: 1 | 2 | 3 = 1;
let welcomeCtaLabel = "Scan my history";
let welcomeCtaClick = handleScan;
if (scanState === "next") {
  welcomeStep = 1;
  welcomeCtaLabel = scanning ? "Scanning…" : "Scan my history";
  welcomeCtaClick = handleScan;
} else if (sessionsState === "next") {
  welcomeStep = 2;
  welcomeCtaLabel = buildingSessions ? "Building…" : "Build sessions";
  welcomeCtaClick = handleBuildSessions;
} else if (threadsState === "next") {
  welcomeStep = 3;
  welcomeCtaLabel = buildingThreads ? "Building…" : "Build your intent map";
  welcomeCtaClick = handleBuildThreads;
}

The welcome screen's single button always mirrors the rail's next action, so a user can move through scan, build sessions, and build threads by clicking one prominent button three times. The moment threads exist, the welcome screen is replaced by the intent map. The rail and the welcome screen never disagree about what to do next, because both read from the same source of truth.

Wiring the Handlers

The handlers themselves are thin: each runs a pipeline stage, then refreshes the component's view of the database. The action that runs grounding and labeling together is the one worth seeing, because it puts into practice the decoupling described in the previous two sections:

async function handleEnrichAndLabel() {
  setLabelError(null);
  setEnrichError(null);

  if (contextKey.trim() && contextKeySaved) {
    setEnriching(true);
    try {
      const allDomains = [...new Set(
        threads.flatMap((t) => t.sessions.flatMap((s) => s.domains))
      )];
      const result = await enrichDomains(contextKey.trim(), allDomains);
      if (result.error) setEnrichError(`context.dev: ${result.error}`);
      if (result.enriched > 0) {
        const all = await getAllBrands();
        setBrands(new Map(all.map((b) => [b.domain, b])));
      }
    } catch (err) {
      setEnrichError(`context.dev: ${err instanceof Error ? err.message : "unknown error"}`);
    } finally {
      setEnriching(false);
    }
  }

  setLabeling(true);
  try {
    await labelThreads(apiKey.trim());
    setThreads(await getAllThreads());
  } catch (err) {
    setLabelError(err instanceof Error ? err.message : "Labeling failed.");
  } finally {
    setLabeling(false);
  }
}

Enrichment runs only if a context.dev key is present, and it's wrapped so that any failure (like a network error, a bad key, or a rate limit) sets an error message but never stops execution. Labeling then runs unconditionally afterward, outside the enrichment block, so it proceeds whether enrichment succeeded, failed, or was skipped entirely for lack of a key.

That structure is the decoupling from the grounding section made concrete: grounding improves labeling when it works, and labeling degrades gracefully to keyword-and-domain context when it doesn't.

The enrichment error surfaces in amber rather than red, because it's a warning (labeling still happened) rather than a blocking failure. This is a small UI cue that matches the actual severity of what went wrong.

The Resume Button

One interaction ties the intent map back to live browsing. Each thread card has a Resume button that reopens the pages you were on, so acting on a thread is one click rather than a hunt through history:

const RESUME_SKIP_DOMAINS = new Set([
  "google.com", "youtube.com", "bing.com", "duckduckgo.com",
  "gmail.com", "mail.google.com",
]);

function resumeThread(thread: IntentThread): void {
  const seen = new Set();
  const urls: string[] = [];

  const sorted = thread.sessions
    .flatMap((s) => s.events)
    .sort((a, b) => b.visitedAt - a.visitedAt);

  for (const ev of sorted) {
    if (RESUME_SKIP_DOMAINS.has(ev.domain)) continue;
    if (seen.has(ev.url)) continue;
    seen.add(ev.url);
    urls.push(ev.url);
    if (urls.length >= 3) break;
  }

  urls.forEach((url, i) => {
    chrome.tabs.create({ url, active: i === 0 });
  });
}

Resume sorts the thread's events newest-first, skips search engines and webmail (which are waypoints rather than destinations you'd want to return to), dedupes by URL, and opens the three most recent meaningful pages. The first is the active tab and the rest are in the background. It's a small feature, but it's the thing that makes a thread feel like a place you can return to rather than a record of where you've been.

Checkpoint

With the dashboard wired up, the entire pipeline is finally usable end to end through the interface. Reload the extension, open the dashboard, and you should see the welcome screen prompting you to scan.

Click through scan, build sessions, build your intent map, and the threads should appear, grouped by status. Add an Anthropic key, optionally a context.dev key, and click "Label & enrich" to see titles and next steps sharpen. The full loop you've built across every previous section now runs from a single screen.

What remains is the conversational layer on the right: an AI assistant that can reason across all your threads at once and answer questions like "what should I close this week?" The next section builds it.

How to Build the AI Assistant

The labeling step asks Claude to describe one thread at a time. The assistant asks something harder: to reason across all of your threads together and answer open-ended questions about them, like what to close this week, what you've stalled on longest, or how to finish a particular one.

This is a chat interface, but a constrained one – grounded entirely in your own thread data, so its answers reference real threads by name rather than offering generic productivity advice.

The whole design rests on one idea: a chat assistant is only as good as the context it's given. So most of the work here is in building the right grounding context for each message, not in the chat mechanics themselves.

Grounding the Conversation

Before any message goes to Claude, the assistant assembles a system prompt describing the user's threads. It does this in one of two modes, depending on whether the user has clicked into a specific thread.

With no thread selected, it builds a compact digest of every thread. With one selected, it gives rich detail on that thread and a brief list of the others.

function buildGroundingContext(
  threads: IntentThread[],
  brands: Map,
  selectedThread: IntentThread | null,
): string {
  if (!selectedThread) {
    const digest = threads
      .map((t) => {
        const domains = [...new Set(t.sessions.flatMap((s) => s.domains))].slice(0, 5).join(", ");
        return `- \({t.title} (\){t.status}, \({t.type}): \){t.summary ?? "no summary yet"} | next: \({t.nextStep ?? "none"} | domains: \){domains || "none"}`;
      })
      .join("\n");

    return `\({SYSTEM_INSTRUCTION}\n\nHere is a digest of all the user's open intent threads:\n\){digest || "(no threads yet)"}`;
  }

  const keywords = [...new Set(selectedThread.sessions.flatMap((s) => s.keywords))].slice(0, 10).join(", ");
  const domains = [...new Set(selectedThread.sessions.flatMap((s) => s.domains))].slice(0, 5);

  const domainLines = domains
    .map((d) => {
      const brand = brands.get(d);
      if (brand?.description) return `- \({d}: \){brand.name} — ${brand.description}`;
      return `- ${d}`;
    })
    .join("\n");

  const sampleTitles = [...new Set(selectedThread.sessions.flatMap((s) => s.events.map((e) => e.title)))]
    .slice(0, 20)
    .map((t) => `- ${t}`)
    .join("\n");

  const otherTitles = threads
    .filter((t) => t.id !== selectedThread.id)
    .map((t) => t.title)
    .join(", ");

  return `${SYSTEM_INSTRUCTION}

The user is focused on this thread:
Title: ${selectedThread.title}
Status: ${selectedThread.status}
Type: ${selectedThread.type}
Summary: ${selectedThread.summary ?? "none"}
Next step: ${selectedThread.nextStep ?? "none"}
Keywords: ${keywords || "none"}

Domains visited:
${domainLines || "(none)"}

Recent page titles:
${sampleTitles || "(none)"}

For context, the user's other open threads are: ${otherTitles || "none"}.`;
}

The two modes match the two kinds of questions people ask. A question like "what should I close this week?" is about the whole set, so the digest mode gives Claude a one-line summary of every thread. This is enough breadth to compare and prioritize across all of them.

A question like "how do I finish this one?", on the other hand, is about a single thread, so the focused mode trades breadth for depth. It hands over that thread's keywords, its domains with their brand descriptions, and up to twenty real page titles, while still naming the other threads so Claude knows what else is in play.

The focused mode is where brand grounding shows up again. The same brand records fetched during enrichment get woven into the domain list, so when the user asks about a thread, Claude sees mastra.ai: Mastra — TypeScript framework for building AI agents rather than a bare domain. This is the identical grounding principle from labeling, now applied to conversation.

The system instruction that prefixes both modes pins the assistant to its data:

const SYSTEM_INSTRUCTION =
  `You are the assistant inside "openloops", a browser extension that reconstructs ` +
  `the user's browsing history into "intent threads" — decisions, research, or ` +
  `plans they started and haven't closed. Help the user understand and act on ` +
  `these open loops. Be concrete: reference the actual threads by name and ` +
  `suggest real next actions. You are grounded only in the thread data provided ` +
  `below — if the user asks about something not present in it, say so plainly ` +
  `rather than guessing.`;

The final instruction is the important one: telling the model to admit when something isn't in its data, rather than inventing a plausible answer, is what keeps the assistant trustworthy when a user asks about a thread that doesn't exist or a detail the data doesn't contain.

Sending a Message

The send function rebuilds the grounding context fresh on every message. The assistant always reflects the current state of the threads (including any that changed since the conversation started) and posts the whole message history to Claude:

async function send(text: string) {
  const trimmed = text.trim();
  if (!trimmed || sending) return;

  if (!keySaved) {
    setError("Add your Anthropic key above to chat.");
    return;
  }

  setError(null);
  const nextMessages: Message[] = [...messages, { role: "user", content: trimmed }];
  setMessages(nextMessages);
  setInput("");
  setSending(true);

  try {
    const systemPrompt = buildGroundingContext(threads, brands, selectedThread);
    const maxTokens = EFFORT_OPTIONS.find((e) => e.id === effort)?.maxTokens ?? 1024;

    const response = await fetch("https://api.anthropic.com/v1/messages", {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-api-key": apiKey,
        "anthropic-version": "2023-06-01",
        "anthropic-dangerous-direct-browser-access": "true",
      },
      body: JSON.stringify({
        model,
        max_tokens: maxTokens,
        system: systemPrompt,
        messages: nextMessages.map((m) => ({ role: m.role, content: m.content })),
      }),
    });

    if (!response.ok) {
      if (response.status === 401) {
        throw new Error("Invalid API key. Check your Anthropic API key and try again.");
      }
      throw new Error(`API request failed: \({response.status} \){response.statusText}`);
    }

    const data: { content: AnthropicContentBlock[] } = await response.json();
    const reply = data.content
      .filter((b) => b.type === "text" && b.text)
      .map((b) => b.text)
      .join("");

    setMessages((prev) => [...prev, { role: "assistant", content: reply || "(empty response)" }]);
  } catch (err) {
    setError(err instanceof Error ? err.message : "Something went wrong.");
  } finally {
    setSending(false);
  }
}

The mechanics mirror the labeling request, the same endpoint, the same browser-access header, and the same 401-aware error handling, since both talk to the same API from the same constrained environment. The user's message gets appended to the running messages array, the full array is sent so the model has the conversation so far, and the assembled grounding context rides along as the system prompt. The reply is extracted by concatenating the text blocks from the response, with a fallback string if the model returned nothing usable.

Rebuilding buildGroundingContext on every send rather than once per conversation is a deliberate choice: if the user re-runs the pipeline or labels their threads mid-conversation, the next message reflects the updated data automatically, with no stale snapshot from when the chat began.

Model and Effort Controls

The assistant exposes two selectors: which model to use and how much depth to allow. Both are persisted to chrome.storage.local through the same settings pattern as the keys:

const MODEL_OPTIONS = [
  { id: "claude-haiku-4-5-20251001", label: "Haiku 4.5 — fastest" },
  { id: "claude-sonnet-4-6",          label: "Sonnet 4.6 — balanced" },
  { id: "claude-opus-4-8",            label: "Opus 4.8 — most capable" },
];

const EFFORT_OPTIONS = [
  { id: "low",    label: "Low",    maxTokens: 512 },
  { id: "medium", label: "Medium", maxTokens: 1024 },
  { id: "high",   label: "High",   maxTokens: 2048 },
];

The model selector spans the speed-versus-capability range: Haiku for quick answers, Opus for harder reasoning over a tangled set of threads. The effort selector maps to max_tokens, controlling how long an answer the model may produce. This is a reasonable proxy for response depth given the Messages API has no dedicated depth control. A user wanting a one-line answer picks Low, while one wanting a reasoned, prioritized plan picks High.

Rendering Replies and the Empty State

The assistant renders Claude's replies as Markdown, since the model naturally formats prioritized lists and step-by-step suggestions with headings and bullets. This would look like raw asterisks and hashes if rendered as plain text. Using react-markdown, the reply component is essentially {m.content} for assistant messages, with user messages rendered as plain text. The accompanying styles target the rendered Markdown elements to match the dashboard's type scale.

Before any conversation starts, the panel shows an empty state with a one-line explanation and a few suggested prompts as clickable chips, "What should I close this week?", "Summarize my open loops", "What have I stalled on longest?". These both demonstrate what the assistant can do and give a one-click way to start.

The suggested prompts shift slightly when a thread is focused, offering "How do I finish this one?" in place of the whole-set summary, matching the focused grounding mode.

A privacy line sits permanently below the composer, stating that chats send thread titles and summaries to Anthropic and nothing else leaves the device. This is the same honest disclosure principle applied throughout, placed where the user will see it before they type.

Checkpoint

With the assistant in place, openloops is feature-complete. Reload, build your intent map, add your Anthropic key, and try the suggested prompts. Ask what to close this week and the assistant should name specific threads and reason about which are easy wins versus which need a real decision. Click into a single thread and ask how to finish it, and the answer should narrow to that thread's specifics.

The conversation reflects your real, current threads, and nothing about it leaves your machine except the thread summaries you can see in the grounding context itself.

The build is done. The final section steps back to look at what you've made: how it compares to the one mainstream attempt at this idea, what the privacy model adds up to, and where you might take it next.

What You've Built, and Where to Take It

You've built a complete system: browsing history flows in through capture, gets cleaned and segmented into sessions, clustered and scored into intent threads, optionally labeled and grounded by AI, and surfaced through a dashboard with a conversational assistant. Every stage runs on your own machine, and the AI layers are optional additions on top of a pipeline that works without them.

If the clustering reminds you of Chrome's old Journeys feature, that's a fair connection. Grouping history by topic instead of by time is the same starting point.

openloops takes it further: every thread carries a confidence score and a status, the AI layer adds labels and a concrete next step, the assistant reasons across threads on demand, and the whole thing is open source and local-first. This means that you can read and change exactly what it does with your data.

What the Privacy Model Adds Up To

Privacy shaped the build at every step, and it's worth collecting what that amounted to in one place. The entire core pipeline, capture through scored threads, runs locally in IndexedDB with no network calls of any kind. Your browsing history – the raw events, the sessions, the threads – never leaves your machine for the parts of the system that work without a key.

The two AI layers are the only paths by which any data leaves the device, and both are opt-in, gated on you providing your own API key. When they run, what they send is deliberately minimal: brand enrichment sends only bare domain names to context.dev, never URLs or page contents, and stripped of any local addresses first. Labeling and the assistant send thread titles, summaries, keywords, and sample page titles to Anthropic, the grounding context you can read directly in the code, and nothing more. Keys themselves live in chrome.storage.local, which never syncs.

Where to Take it Next

The build leaves a few deliberate simplifications that make good exercises.

The most satisfying one builds directly on code you've already written. The domain side has ambient.ts, which drops domains that appear on most of your active days. But the keyword side has no equivalent, so a word that's ubiquitous for you (say typescript, if you're a TypeScript developer) survives in every session's keywords and can nudge unrelated threads together.

The fix is a frequency-based keyword detector that mirrors detectAmbientDomains almost line for line, counting days-per-keyword instead of days-per-domain:

export function detectAmbientKeywords(sessions: Session[]): Set {
  const allEvents = sessions.flatMap((s) => s.events);
  const activeDays = new Set(allEvents.map((e) => new Date(e.visitedAt).toDateString()));
  const totalActiveDays = activeDays.size;
  if (totalActiveDays < MIN_ACTIVE_DAYS) return new Set();

  const keywordDayMap = new Map>();
  for (const session of sessions) {
    const day = new Date(session.startedAt).toDateString();
    for (const kw of session.keywords) {
      if (!keywordDayMap.has(kw)) keywordDayMap.set(kw, new Set());
      keywordDayMap.get(kw)!.add(day);
    }
  }

  const ambient = new Set();
  for (const [kw, days] of keywordDayMap) {
    if (days.size / totalActiveDays >= UBIQUITY_THRESHOLD) ambient.add(kw);
  }
  return ambient;
}

You'd then strip these keywords inside similarity exactly as ambient domains are stripped today, filtering them out of both sessionKeywords and the thread's keywordSet before the Jaccard call.

Two smaller exercises round it out. The session gap, similarity threshold, and ambient ubiquity threshold are all hardcoded constants. Lifting them into a settings panel backed by chrome.storage.local (the same store the API keys already use) would let you tune clustering to your own browsing.

And extractDomain strips only a leading www., so news.bbc.co.uk and bbc.co.uk are treated as different domains. Swapping its hostname logic for a library that uses the Public Suffix List (the canonical list of domain suffixes like .co.uk that browsers use to know where a registrable domain actually ends) would collapse subdomains of the same site correctly.

Since the whole pipeline is local and inspectable, each of these is straightforward to try against your own real data and see the effect immediately.

Wrapping up

openloops turns the flat, chronological record your browser keeps into a map of what you were actually trying to do, and helps you close the loops you left open.

The engineering underneath – time-gap segmentation, weighted Jaccard clustering with ambient-domain correction, heuristic scoring, AI labeling grounded in real company data, and a conversational layer over the result – is the kind of layered system where each stage is simple on its own and the value comes from how they compose.

Resources

Source Code

The complete source is available on GitHub under the MIT license, so you can run it, read it, and reshape it to fit how you browse. If it helped you, consider giving it a star.

Core Documentation

Chrome Extensions: Manifest V3: the extension platform openloops is built on
chrome.history API: the search and getVisits methods the backfill relies on
chrome.tabs API: onUpdated for live capture and create for Resume
chrome.storage API: where API keys and preferences live, locally
Anthropic API reference: the Messages endpoint used for labeling and the assistant

Services used

Anthropic Console: create the API key for AI labeling and the assistant
context.dev documentation: the brand-intelligence API used for grounding
IndexedDB (MDN): the local database every pipeline stage reads and writes

Build tooling

Vite: the build tool and dev server
CRXJS Vite plugin: compiles a Manifest V3 extension with hot reloading
idb: the typed, promise-based IndexedDB wrapper
react-markdown: renders the assistant's Markdown replies

Debugging tools

Chrome extension service worker DevTools: inspect live-capture logs and the pipeline console.table output
The Application → IndexedDB panel in Chrome DevTools: browse raw_events, sessions, intent_threads, and domain_brands directly to verify each stage

How to Build a Software Factory with Claude Code: From Vibe Coding to Agentic Development

Qudrat Ullah — Fri, 22 May 2026 14:37:35 +0000

AI coding tools now offer much more than autocomplete. They can analyze your codebase, edit multiple files, execute commands, explain errors, generate tests, write documentation, and prepare pull request summaries. For small tasks, these capabilities are impressive. When you ask Claude Code, Cursor, or Copilot to explain a function, clean up a component, write a utility, or fix a clear bug, the process often feels seamless.

However, developing significant features presents different challenges.

A complete feature involves more than code. It requires product rules, architectural decisions, edge case handling, tests, security checks, review standards, and delivery constraints. As features grow, a single AI session must manage increasing complexity.

This is where the workflow begins to strain.

For example, you might ask your AI assistant to add invoice reminders to a SaaS billing application. Initially, it performs well: inspecting the invoice model, identifying the email service, recognizing the background worker, proposing a plan, and implementing changes. You approve permissions and edits, it runs tests, resolves errors, and updates the summary.

As the session progresses, complexity increases.

The AI must now track the original business rule, tenant boundaries, retry behavior, modified files, added tests, corrected constraints, and instructions on what not to change. While progress remains faster than before, the workflow becomes less organized.

You review the plan again, approve additional edits, identify missing constraints, reiterate rules, request file checks, rerun tests, and examine the diff. You begin to question whether the implementation still aligns with the original intent.

The AI is not failing due to lack of capability; it struggles because the workflow lacks sufficient structure.

A single extended conversation attempts to serve as product analyst, architect, backend engineer, frontend engineer, test engineer, reviewer, and release assistant simultaneously. While this may suffice for small tasks, it becomes unreliable when features involve complex business rules and production risks. Many developers overlook this transition.

Advancing AI-assisted development requires more than improved prompts; it involves designing a more effective system around the model.

If this scenario resonates with you, it does not reflect a lack of skill with AI. Instead, it indicates that your workflow may not be well-suited to the tool.

I am Qudrat Ullah, a tech lead based in London. I collaborate with engineering teams delivering production software and have observed how AI coding tools are transforming daily workflows. In this handbook, I will share practical insights to help you evolve your approach. By the end, you will move beyond repetitive setups and begin building your own software factory. Effective solutions start small and develop over time; avoid aiming for a comprehensive solution in a single day. Start small and continue to grow.

This handbook outlines the workflow I wish I had received when I started using AI for production code. By the end, you will be able to establish your own small software factory, a structured approach to using AI for planning, building, testing, and reviewing features while maintaining control of your codebase.

What You'll learn

How AI-assisted development actually evolved, and what the shape of that history tells you about where it is going.
Why "just ask the AI" stops working as soon as a project gets real, and what to do instead.
The five layers of an AI-assisted workflow: context, knowledge, agents, workflows, and delivery.
How to use Claude Code's building blocks (CLAUDE.md, skills, subagents, hooks) and let Claude itself generate most of them for you. (You can use any tool. The concepts are the same. I picked one tool for simplicity.)
How to build a working set of seven specialized agents and an orchestrator that chains them together.
A hands-on setup you can copy into any Next.js or Node.js project this weekend. If you understand the concepts, you can apply them to any project.
What I deliberately left out, and where to learn it next.

Who this is For

This guide is accessible to developers new to Claude Code or any AI tool, yet comprehensive enough for senior engineers or tech leads to benefit from the workflow patterns, orchestrator design, review checklist, and delivery section.

Examples reference Next.js, Node.js, and a SaaS billing application, but the concepts are tool-agnostic. Whether you use Cursor, Claude, Aider, Windsurf, Kilo, Cline, or future tools, the same principles apply.

What You'll Be Able to Build by the End

A CLAUDE.md that captures your project's facts and standards.
Seven custom subagents that do focused work in their own context: researcher, story writer, spec writer, backend builder, frontend builder, test verifier, and validator.
One orchestrator (first as a skill, then optionally as an agent) that delegates work across those seven sub agents.
One reusable skill that encodes a workflow your team runs repeatedly.
One pre-commit hook for safety.
A short PR review checklist to ensure AI-generated pull requests are reviewed against the same standards every time.

This is what a "software factory" means in practice. A factory can be scaled to your needs. It is not a large autonomous system, but rather a small set of files in your repository that enables one developer and one AI to function as a coordinated team.

Part 1: Foundations Before the Factory

Before building a factory, it is important to understand the current landscape, why existing workflows break down, and the foundational elements required. The first five sections establish this groundwork; construction begins in Section 6.

1. How AI-Assisted Development Evolved

Before building anything, it is helpful to understand the progression of AI in coding. This evolution occurred in few stages, with each stage addressing a specific problem and enabling the next.

Figure 1: Five stages of AI in coding, leading to today's software factory shift.

Manual Coding

In the early workflow, you wrote everything by hand. The editor highlighted the text but did not understand it. You looked things up in books, in docs, on Stack Overflow, then slowly shaped the application line by line. This produced strong developers because every detail had to pass through their heads, but it placed a hard cap on what one person could ship in a week.

Smart editors

Then the editors got useful. IntelliSense, language servers, ESLint, snippet engines, refactoring tools. None of these wrote code for you, but they removed friction inside the file you were already editing. This was the first stage at which developers began to expect the editor to help. It changed the baseline.

Smart Autocomplete

Tabnine and early versions of GitHub Copilot looked at nearby code and predicted what would come next. If you started writing a function calculateInvoiceTotal(items), the tool guessed you wanted to loop over items, multiply quantity by price, and return a total. The editor was no longer completing syntax. It was completing intent. But you still owned the design.

Chat AI

Then chat-based AI arrived, and the workflow split in half. You opened ChatGPT or Claude in another tab and asked for a login page or a registration API. Useful for boilerplate. Bad for anything that depended on your real folder structure, your auth flow, your database schema, or your team's decisions. The generated code looked correct in isolation, but broke when you pasted it in. It helped you draft something initially without typing.

AI in the IDE

Cursor, Claude Code, Copilot Chat, Windsurf, Aider. These closed that gap. The AI could now inspect files, suggest edits across the project, run commands, and help with multi-file work. Instead of "write me a React component," you could ask, "Look at our existing dashboard widgets and add a new metric card in the same style." Much more powerful, because the AI is no longer working from a blank page. This is also the start of vibe coding. You vibe with the AI, it makes changes, you keep going. A lot of people are doing that today and getting real leverage from it.

That power is changing how software is built, but the industry is already moving in another direction. Let's look at what breaks in the vibe coding model.

2. Why Vibe Coding Breaks Down

Vibe coding is the workflow most developers fall into in the first week they use an AI IDE. You ask for a feature. The AI writes code. Something breaks. You paste the error. The AI patches it. Something else breaks. You ask again. Round and round.

On day one, this feels fast. You can build a landing page in fifteen minutes. You can sketch a prototype in an afternoon. Real progress.

On day thirty, the loop turns painful. The same logic appears in three places. The AI has forgotten the convention you set up two weeks ago. New features step on old ones. Tests are missing or shallow. The app works today, then breaks tomorrow because one prompt removed a guard you forgot existed. You are now spending more time supervising the AI than you used to spend writing code yourself.

There are techniques that make this better. Writing better prompts. Maintaining good docs. Keeping the context tight. I covered some of those in my previous article on unblocking the AI PR review bottleneck. Those techniques help, but a single session still drifts when too many jobs land in the same conversation, and that's the challenge we are going to solve.

The Deeper Problem: One Chat, Too Many Jobs

If you watch a real engineering team for a day, you notice that different people have different responsibilities. A product person clarifies the user problem. A senior engineer thinks about architecture. A backend developer designs the API. A frontend developer builds the interface. A test engineer thinks about edge cases. A reviewer decides whether the work fits the codebase.

When you point one AI session at "build the feature," you collapse all of those roles into one conversation. The AI plans, designs, codes, tests, and reviews its own work in the same messy context. That is risky because mistakes compound. A wrong assumption in the plan becomes a wrong database model. A wrong database model becomes a wrong API. A wrong API becomes a wrong UI. By the time you notice, the mistake has spread through the whole feature.

You may start thinking the next stage of AI-assisted development is better prompts. No, it is not, It is a better system.

Use AI to automate structured work, not chaotic work. If your team has no standards, AI will generate inconsistent code faster. If your tests are weak, AI will produce fragile features faster. If your review process is vague, AI will let important risks through faster.

That single idea drives everything that follows.

3. The Five Layers of an AI-Assisted Workflow

Before we get into specifics, here is the mental model this article uses. A working AI-assisted workflow has five layers that stack. Each one only works as well as the one below it.

Figure 2: The five layers. Each one feeds the next; the whole stack is your software factory.

At the bottom is the Context Layer, which is what the AI can see in the current message. Above that sits the Knowledge Layer, which is the persistent project memory the AI inherits at the start of every session. Memory management itself is a huge topic we will cover in a future article (centralized memory, shared knowledge stores, and so on). For now, rely on Claude's session memory. The Agent Layer turns that knowledge into focused workers with their own tools and their own context windows. The Workflow Layer puts an orchestrator on top of those agents and chains them into a real pipeline with validation gates and human approval points. The Delivery Layer is how everything that comes out of the pipeline reaches production safely: pull requests, a review checklist, and CI gates.

If you invest in only one layer, the others remain weak. A team with great agents but no shared CLAUDE.md ends up with inconsistent code. A team with great context discipline but no validation gates ships fragile features fast. The whole point of the model is that you build all five, even if you start small in each one. Also, one more important tip across the teams use same AI and tools for better and consistent results.

Before you build the factory, understand the foundations first.

This article is split into two halves on purpose.

Part 1 (Sections 4 and 5) covers the foundations. Context management. CLAUDE.md. Skills. Hooks. These are not the factory. These are the things you have to understand before the factory can stand on top of them. If you skip them and jump straight to building agents, the factory looks impressive for a week and then falls over. The agents will inherit a messy context. The orchestrator will route work that lacks clear rules. The validator will have nothing to validate against.

Part 2 (Sections 6, 7, 8, and 9) is where you actually build the factory. Seven specialized agents. An orchestrator that runs the chain. A delivery layer that gets the output to production. A hands-on section that wires it all together in your own repo.

A note on Part 1. You might read Sections 4 and 5 and think, "This is still me typing prompts. This is still vibe coding with extra steps." That is fair on the surface, and I want to address it directly. The habits in Part 1 are not the factory. They are the discipline that makes the factory possible. The exploration workflow you do by hand in Section 4 is the same workflow your codebase-researcher agent will automate in Section 6. The CLAUDE.md you write in Section 5 is what every agent will read at the start of every task. Part 1 teaches you the moves. Part 2 teaches the machine to make them for you.

If you already practice good context hygiene and have a CLAUDE.md you trust, skim Part 1 and head straight to Section 6. If you do not, take the time. The factory is only as good as what it stands on.

4. The Context Layer: Explore Before You Build

Context is the AI's working memory. It is your prompt, the files you opened, the previous messages, your project rules, the documentation you injected, the terminal output, and the errors. Anything else the model can see while it is helping you.

Senior engineers carry a lot of project knowledge in their heads. They know why a decision was made, where the risky files live, which patterns the team follows, and what should not be touched. AI does not automatically know any of that. It only knows what is in its context.

Even with very large context windows, more is not better. Too much uncontrolled context makes the model worse. It mixes old decisions with new ones. It follows an outdated file pattern. It carries forward a wrong assumption that you corrected three messages ago. The goal is not to give the AI everything. The goal is to give it the right information at the right time which save computing time and cost both.

Habit 1: Explore before you build

The single biggest mistake developers make with AI in the IDE is asking for code as the first move. The AI accepts the prompt, makes guesses to fill the gaps in your description, and starts generating. That is when bad designs sneak in. Strongly recommend avoid that.

A better move is to treat the first phase as exploration, not implementation. You are not asking the AI to build anything yet. You are asking it to read the existing code and tell you what is there. During this process you will observe AI will discover things which it finalize wrong initially.

Concrete example. Imagine you run a SaaS billing platform built with Next.js (App Router) on the frontend and Node.js services on the backend. The app has customers, subscriptions, invoices, a webhook handler that updates payment status, and a Resend integration for transactional email. You want to add reminder emails for unpaid invoices.

If you tell Claude Code, "add invoice reminders," you are gambling. It might do something reasonable. It might also create a new scheduler when you already have one, send reminders to customers who already paid, ignore timezone handling, hardcode business rules into the API route, or skip audit logs entirely. None of that is the AI being bad. It is the AI guessing because you asked it to.

Here is the controlled version, step by step.

Step 1. Open Claude Code in plan mode and start with a read-only prompt. The goal is to make the AI describe the relevant parts of your codebase before any code is written.

I want to add reminder emails for invoices that have been unpaid
for more than 7 days. Before suggesting anything, please:

1. Read the invoice, payment, and email-sending code in this repo.
2. Tell me how invoices are created and where their status is stored.
3. Tell me how transactional emails are sent today.
4. Tell me whether we already have a background job system or scheduler.
5. List the files that would most likely change if we added reminders.

Do not write any code yet. I want a clear map first.

The prompt above can be written in many ways. Also can references docs folder if CLAUDE.md does not have clear mapping or you want to give more context to the AI for better results. The purpose is to show the shape: ask for understanding before action.

Step 2. Read the response carefully. This is the moment to spot wrong assumptions while they are cheap to fix. If the AI says "I will use cron," but you actually have BullMQ workers running, correct that now. Because during codebase discovery it's possible it has not discovered BullMQ code and that information is in your head.

Step 3. Once the map is right, ask for options, not code. You want a small comparison, not a solution.

Based on what you just found, suggest 3 ways we could implement
invoice reminders.

For each option, explain:

- how it would work end-to-end
- which existing parts of the system it reuses
- which new files or DB changes it needs
- the main risks (timezone, multi-tenant, retries, deduplication)
- Which option would you recommend and why

Do not edit any files yet.

Step 4. Pick one option, then ask Claude Code to write a one-page brief: goal, approach, business rules, data model changes, tests needed, edge cases, open risks. Read the brief in under a minute. If something is missing, ask for a revision before moving on.

Step 5. Open a fresh Claude Code session and paste only the brief into it. This is the move most people skip. During exploration, the AI discussed multiple options. Some were rejected. Some were partially correct. You do not want all that noise carried forward when implementation starts. A clean session means a clean context.

Step 6. Ask about the new session's implementation plan and read it slowly. Look for things like "we will store processed invoice IDs in memory." That is a red flag. Memory is lost on restart and is not shared across multiple servers, so the same reminder could be sent twice. Catching that in the plan costs five minutes. Catching it after Claude has changed ten files costs an afternoon.

Step 7. Build, then ask Claude to explain back. After the implementation, do not blindly commit. Ask the AI to walk you through the important decisions, list the tests it added, and update the docs with anything operators need to know. Trust but verify.

The shape of this workflow is:

inspect → compare options → pick approach → write brief → start clean → plan → review → build → explain back

Compare that to the vibe-coding shape: prompt → generate → run → paste error → repeat. The first one is controlled progress. The second is accidental progress, which does not scale.

This whole workflow is what you do today, by hand. In Section 7, you will see how an orchestrator can run most of it for you while you only step in at the review points.

Habit 2: Watch for Context Drift

Even with a clean start, bad information can sneak into a long session. Once a wrong assumption enters the context, the model keeps building on top of it. I call this context drift, and it is the most common reason a working session quietly produces a broken codebase. One small wrong assumption can spread across many files before you notice.

Figure 3: How a vague prompt drifts into spreading damage, and the only reliable way out.

A real example. You give Claude this prompt:

Add subscription management to our SaaS. Users should be able to create a subscription and cancel it later.

That prompt is too broad. The AI guesses ownership and creates something like:

User
└── Subscription
      ├── planName
      ├── status
      └── renewalDate

Looks fine on the surface. Then you remember your real business rule: a company account has many users, and the subscription belongs to the company, not the individual user. That difference is huge, and the AI has already designed around the wrong owner.

If you only say "no, subscriptions belong to companies," Claude tries to patch. You end up with both user.subscriptionId and company.subscriptionId floating around, defensive comments where they should not exist, and renamed code that still behaves like the old design.

Rule of thumb: If the AI makes a small typo, correct it inline. If it makes a wrong architectural assumption, throw the conversation away and start a new session with a stronger prompt. Small mistakes can be patched. Deep design mistakes should not be patched inside a polluted conversation.

The cleaner move is to discard the chat, edit your original prompt, and start over with the rule baked in:

We need subscription management for our SaaS.

Important business rules:
- Subscriptions belong to a company account, not an individual user.
- A company can have many users.
- Only company admins can change the subscription.
- Billing history is visible to admins only.
- Cancelled subscriptions remain active until the end of the billing period.

Before writing code, inspect our existing account, user, and billing models.
Then suggest an implementation plan. Do not edit files yet.

Now the AI starts from the correct mental model. The first version is a guess. The second version is a design.

Habit 3: Pin the AI to your installed versions

Models know a lot, but they do not always know the exact version of your framework, your library, or your team standard. Sometimes they answer from older training data. Sometimes they give you a generic answer that worked in a tutorial three years ago and does not fit your project today.

A better prompt forces the AI to ground itself in your real installed versions:

Before writing code, inspect this project's structure and package.json.

This project uses Next.js App Router. Use the authentication library
version that is actually installed. Look up the current docs for that
specific version. Then explain the recommended file structure before
editing anything.

Same idea for Tailwind versions, Stripe SDK versions, Prisma migrations, React 18 vs 19 differences. Anywhere there is a real version-to-pattern dependency, make the AI ground itself in your installed versions and the current docs, not its training memory. Without it, the model produces average internet code and keep fixing errors and after a while will reach to correct information. With it, the model produces code that fits your project.

A useful tool here is Context7. It is a plugin that fetches the current docs for the exact installed version of each library. You can install it in Claude Code and reference it in your prompts or knowledge files so the model always pulls current docs before writing code. I use it regularly.

5. The Knowledge Layer: CLAUDE.md, Skills, and Hooks

The Context Layer covers a single conversation. The Knowledge Layer covers everything that survives between conversations. This is where most teams' AI workflows quietly fail. They keep re-explaining the same project facts to the AI, every day, in every chat. Capturing that knowledge once, in the right place, is what turns a good AI workflow into a repeatable one.

Claude Code gives you four building blocks for this layer. Picking the right block for the right kind of knowledge is half the skill.

Figure 4: Four building blocks. Each one feeds your Claude Code session in a different way.

CLAUDE.md: The Lasting Facts

CLAUDE.md is a Markdown file at the root of your repo (or at ~/.claude/CLAUDE.md for personal-level instructions). It is loaded automatically every time you open a Claude Code session in that project, and it is where lasting facts live. If you have multiple projects in a monorepo you can have one for each project.

A working CLAUDE.md for a Next.js + Node.js SaaS billing app looks like this:

# Project Instructions

This is a SaaS billing application.

## Stack

- Next.js 14 (App Router) with TypeScript
- Node.js services for billing and email
- Prisma + PostgreSQL
- Auth.js for authentication
- Resend for transactional email
- BullMQ for background jobs

## Commands

- npm run dev - start the dev server
- npm test - run unit tests
- npm run typecheck - type-check the project
- npm run lint - lint the project
- npx prisma migrate dev - run migrations locally

## Architecture

- Business logic lives in services or domain modules.
- API routes stay thin and call into services.
- Use the existing email template system; do not add a new one.
- The BullMQ worker handles all scheduled jobs. Do not add cron.
- Tenant isolation is enforced at the service layer, not the route.

## Documentation

For deeper context, consult these before guessing:

- `docs/architecture.md` — service boundaries, request flow, tenant isolation model
- `docs/billing.md` — Stripe webhook handling, invoice lifecycle, proration rules
- `docs/email.md` — template system, Resend setup, list of available templates
- `docs/jobs.md` — BullMQ queue names, job patterns, retry/backoff policy
- `docs/db.md` — schema conventions, tenant isolation patterns, soft-delete rules
- `docs/runbooks/` — production incident runbooks
- `prisma/schema.prisma` — source of truth for the data model
- ADRs in `docs/adr/` — past architecture decisions; read before contradicting one

For Next.js, Prisma, Auth.js, BullMQ, or Resend specifics, check the official docs rather than guessing.

## Testing

- Every feature has success, validation failure, and not-found tests.
- Use test data builders, not inline setup objects.
- Do not mock the database unless existing tests do.

## Don't do

- Do not log raw payment payloads.
- Do not return database errors directly to the client.
- Do not edit migrations after they have been merged.

Keep CLAUDE.md tight. 100 to 300 lines is healthy. If a section grows into a multi-step procedure, that procedure belongs in a skill, not in CLAUDE.md. CLAUDE.md is for facts and rules. Workflows go in the next building block.

A trick for growing your CLAUDE.md naturally. Every time the AI makes a mistake that surprises you, ask yourself if a rule in CLAUDE.md would have prevented it. Add the rule. Over a few weeks, your CLAUDE.md becomes a record of every assumption the AI got wrong, and your future sessions get noticeably better.

Skills: The Workflows You Keep Retyping

A skill is a small folder with a SKILL.md file inside. Claude scans every skill's name and description on startup, but only loads the body when the skill is needed. That progressive loading is what makes it cheap to keep dozens of skills around without slowing the model down.

Use a skill when you keep pasting the same instructions into chat: a commit format, a deployment checklist, a build process, a PR review pattern. Use CLAUDE.md for facts. Use skills for procedures.

The neat trick is that you do not have to write a skill by hand. Claude will write it for you. Open Claude Code in the project, then ask:

I want to create a Claude Code skill that captures how I build a production feature on this project. The skill should cover:

1. How to read CLAUDE.md and the technical brief before writing code.

2. How to look at 2-3 existing similar features and match their
   patterns.

3. How to write unit tests alongside the production code as normal good engineering (not as a strict TDD red-green loop).

4. How to run typecheck, lint, and the test suite at the end.

5. The conventions our codebase already follows: naming, error handling, where business logic lives, how tests are structured.

Create the skill at .claude/skills/build-with-tests/SKILL.md.
Use the recommended Claude Code skill format with proper YAML
frontmatter (name, description). Make the description specific
enough that the skill triggers automatically when I ask to
build, implement, or extend a feature.

Show me the file before writing it.

Claude reads your existing code, infers the patterns, and proposes a skill file. You review it, edit anything that does not match your taste, then save. The skill is now part of the repo, and every future session can use it. You can also use Claude's skill-creator to bootstrap new skills with /skill-creator create me a new skill....

Here is the kind of file Claude will produce:

---
name: build-with-tests
description: Use this skill when implementing a feature or extending existing behaviour. Reads CLAUDE.md and the technical brief first, matches existing patterns, writes production code with unit tests alongside it, and runs the project's typecheck and test commands at the end. Triggers on: "build", "implement", "add", "extend", "ship the feature".
---

Process:

1. Read CLAUDE.md so you know the project rules and stack.
2. Read the technical brief so you stay inside its scope.
3. Look at 2-3 similar features in the codebase. Note their file layout, naming, error handling, and test structure.
4. Implement the feature in the smallest coherent steps you can.
For each step:
   - Write the production code.
   - Write a unit test that covers the new behaviour.
   - Run the test and confirm it passes.
5. When the feature is complete, run the full typecheck, lint,
   and test commands from CLAUDE.md.
6. Return a short summary: files changed, patterns reused, any
   rule you would suggest adding to CLAUDE.md.

Conventions used in this project:

- File names follow the existing folder structure.
- Tests live next to the code they cover (or in tests/ if that
  is the existing pattern).
- Use builders from test/builders/ for any entity setup.
- Cover success, validation failure, and one edge case per
  behaviour.

Rules:

- Do not refactor unrelated code.
- Do not change files outside the agreed scope.
- Do not add new dependencies without explicit instruction.
- If you cannot make the tests pass without violating a rule,
  stop and report the conflict.

With this skill saved, you no longer paste the process every time. You can just write:

Use the build-with-tests skill to implement the invoice reminder service.

The most common skill mistake. Avoid the mega-skill. A single SKILL.md trying to handle commits, PRs, branch naming, and changelog updates all at once tends to fire less reliably and confuse the model when two parts conflict. Split them. A good skill fits on one screen.

Hooks: Automatic Gates and Workflow Triggers

Some parts of an AI workflow should not depend on the model remembering them.

A prompt can say, "run the tests before finishing." CLAUDE.md can say, "do not edit secret files." A skill can say, "validate the implementation before opening a PR." But those are still instructions. The model can forget. The model can choose to skip.

A hook is different.

A hook is an automatic action that runs at a specific point in the Claude Code session lifecycle. It can run a shell command, call an HTTP endpoint, or trigger a prompt or agent-based check depending on how you configure it.

That makes hooks useful for two things:

Gates. Stop or warn when something unsafe happens.
Workflow triggers. Notify another system when something important happens.

In a software factory, agents do the work, but hooks enforce the rules around them.

Claude Code hooks can run at lifecycle events such as:

UserPromptSubmit: before Claude processes your prompt
PreToolUse: before Claude runs a tool
PostToolUse: after a tool succeeds
Stop: when Claude finishes a response
SubagentStart: when a subagent starts
SubagentStop: when a subagent finishes

A simple, useful hook is a pre-commit gate that blocks credential files from ever being committed. Save this as .claude/hooks/pre-commit.sh:

#!/usr/bin/env bash
# Block commits that would include sensitive files.

if git diff --cached --name-only \
   | grep -qE '\.(env|key|pem)$|secrets\.json|creds\.md'; then
  echo "BLOCKED: attempt to commit sensitive files"
  exit 1
fi

Wire it into your Claude Code hook configuration so it runs before commits. The configuration syntax lives in the official Claude Code hooks docs, but the shape is JSON and looks roughly like this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre-commit.sh"
          }
        ]
      }
    ]
  }
}

That is deliberately minimal. In a real project you would also use PostToolUse to run formatters after edits, and Stop to run typecheck and tests before Claude finishes a response. Once it is wired, the hook runs every time, regardless of what the model thinks.

A few other hooks that pay off quickly:

PostToolUse on Edit: run the formatter so every AI edit comes out formatted.
Stop: run typecheck and tests, refuse to stop if either fails.
SubagentStop on validator: post the validator's findings to your team Slack channel automatically.

Hooks matter because they cannot be argued with. The model can suggest, plan, and write. The lint, the type-check, and the test run on every change. That asymmetry is what keeps a software factory honest.

How the Four Blocks fit Together

A simple way to remember which block to reach for:

CLAUDE.md answers "what is true here?" Project facts and rules.
Skills answer "how is this done?" Repeatable procedures.
Subagents answer "who should do this?" Focused workers (next section).
Hooks answer "what is enforced?" Deterministic gates.

You will use all four. CLAUDE.md tells the AI the rules of your codebase. Skills give the AI repeatable playbooks. Subagents give it focused workers. Hooks make sure the rules are real and not optional.

The four blocks are the foundation. Section 6 is where we build the workers that actually do the factory's work.

Part 2: Build the Agent Factory

You now have everything Part 1 promised. You know how to keep the AI's context clean. You have a CLAUDE.md it can lean on. You understand skills and hooks. That is the ground floor.

The next four sections are the factory itself.

Section 6 builds the seven specialized agents. Section 7 puts an orchestrator on top of them so the chain runs itself. Section 8 covers how the factory's output reaches production safely. Section 9 is the hands-on walkthrough where you build the whole thing in your own repo.

By the end of Part 2, the workflow you have been doing by hand will be running on its own. You will type one prompt. The orchestrator will route the work. The agents will do their focused jobs. You will step in at three approval points where your judgement matters. That is the shift.

6. The Agent Layer: Seven Agents That Do Focused Work

Now we get to the part that makes a factory a factory.

So far we have been giving the AI better instructions and better memory. But the AI is still one worker doing every job in the same chat. That is fine for small tasks. It does not scale to real feature work.

The fix is to split the work across specialized agents. In Claude Code these are called subagents. A subagent is not just a longer chat message. It is a focused worker with its own job description, its own tool permissions, and its own context window. That last piece is the one that matters most.

When the main session delegates work to a subagent, the subagent does the heavy reading or processing in its own context. It returns only a short summary to the main thread. The verbose part (file searches, log dumps, multi-step exploration) never bloats your main conversation.

Picture it like this. Your main Claude Code session is the lead engineer. Subagents are specialists you call in for specific tasks. A researcher who maps the codebase. A story writer who turns ideas into user stories. A spec writer who turns stories into technical briefs. A backend builder who writes API routes, services, and database access. A frontend builder who writes components and pages. A test verifier who writes acceptance tests against the user story once the feature is built. A validator who compares everything against the brief.

Each one is good at one thing. None of them tries to do everything.

Why One Big AI Session is Not Enough

Imagine you ask your main session "build the invoice reminder feature." The session inspects files, designs the data model, writes API routes, builds UI, adds tests, and updates documentation. That sounds great until you realize one conversation is now carrying product thinking, architecture, database design, backend implementation, frontend implementation, testing, documentation, and self-review. The context is heavy, the model mixes responsibilities, and the same conversation that designed the feature is also reviewing it. That is a self-graded paper.

Splitting work into subagents fixes that. Each subagent has a narrow responsibility, a clean context window, and only sees what it needs. The validator does not see how the code was written. It sees what was supposed to be built and what is now on disk. That is exactly the gap a real reviewer looks for.

Let Claude Write the Agent File for You

You can write a subagent file by hand if you want (it is just Markdown with YAML frontmatter) but there is rarely a reason to. The cleaner workflow is to use the /agents slash command and let Claude itself draft the file from your description.

Here is the workflow, end to end. Open Claude Code in your project and type:

/agents

That opens the agent management view. Choose to create a new project-level agent (which lives at .claude/agents/.md and gets committed to your repo so the whole team uses it) and ask Claude to generate it for you. Claude will ask what the agent should do, what tools it should have, and what model it should run on.

The key idea is this: you describe the role you want. Claude writes the file. You review, edit, save, commit. Repeat for every agent your team needs.

Tool Access and Model Selection are Part of the Design

Before we look at the seven agents, two design choices apply to every one of them.

Tool access. A common beginner mistake is giving every agent every tool. That is risky. If an agent's job is to inspect architecture, it should not have Edit. If its job is to review code, it should not have Write. Restricting tools is how you make a subagent's behaviour match its description. The researcher cannot accidentally write code. The validator cannot accidentally fix what it found. The backend builder cannot accidentally edit frontend files. That separation is the point.

Model selection. Inspection and review do not need a top-tier model. Routing them to a smaller, faster, cheaper model (Haiku) is one of the practical reasons subagents exist. Save the top-tier model (Sonnet, or Opus when reasoning quality really matters) for the work that needs it: the spec writer, the builders, the test verifier, and the validator.

The Anatomy of a Good Agent Definition

Before we look at the seven specific agents, here is the shape every good agent definition follows. You can use this as a template to design your own agents later. Anything the agents below have, you can copy. Anything they do not have but your team needs, you can add.

Two things beginners almost always miss when they design their first agent. The first is boundaries. They tell the agent what to do but not what it must not do, and the agent ends up doing both. The second is output format. They tell the agent what to think about but not how to return the result, so each invocation produces a slightly different shape and the next agent in the chain cannot rely on it. Both of those are in the template below.

Here is the template, written as if you were briefing a new agent on day one:

Subagent name:
  

Purpose:
  One sentence on why this agent exists and what it is for.

Main responsibility:
  One sentence on the single job this agent owns.

What it should investigate / do:
  - Specific thing one
  - Specific thing two
  - Specific thing three
  (Be concrete. "Find similar features already implemented" is
   better than "understand the codebase".)

What it should NOT do:
  - The action it must never take (for example, edit files)
  - The decision it must never make (for example, invent rules)
  - The tool it must never use
  - The scope it must never widen
  (Boundaries are what make an agent's behaviour predictable.)

Tool access:
  Only the tools this agent actually needs.

Model:
  haiku for cheap inspection, sonnet for reasoning,
  opus when reasoning quality is critical.

Output format:
  1. Section one of the result (for example, "Relevant files")
  2. Section two (for example, "Existing patterns to follow")
  3. Section three (for example, "Risks or conflicts")
  (This is the contract with the next agent in the chain.
   A consistent output shape is what makes chaining reliable.)

Behaviour rules:
  - Short, specific rules the agent must follow every time
  - Limits on length, scope, or assumptions
  - When to ask a clarifying question instead of guessing

That is the shape. You hand it to Claude using the /agents slash command and ask Claude to create the agent file from the template. Claude turns it into a complete .claude/agents/.md with the right YAML frontmatter, formatted system prompt, and tool restrictions.

The seven agents below all follow this shape. Once you understand the template, you can design your own. A design-system reviewer that checks new components against your tokens. An accessibility auditor that reads new UI code and flags issues. A migration writer that turns a schema change into a Prisma migration with the right naming. A release-note drafter that reads recent merges and writes a summary. Anything your team keeps doing by hand and would like to capture once.

The Seven Agents at a Glance

Before drilling into each one, here is the whole chain on one screen.

Agent	Purpose	Main output	Tools
`codebase-researcher`	Map the relevant code before anything is built	Relevant files, existing patterns, risks	Read, Grep, Glob
`story-writer`	Turn a rough feature idea into a user story	Story, acceptance criteria, edge cases	Read
`spec-writer`	Turn the approved story into a technical brief	Data model, flow, API, UI, tests, risks	Read, Grep, Glob
`backend-builder`	Build the backend half	Services, API, jobs, migrations, unit tests	Read, Edit, Write, Bash
`frontend-builder`	Build the frontend half	Components, pages, hooks, UI tests	Read, Edit, Write, Bash
`test-verifier`	Add acceptance tests against the user story	Acceptance tests and coverage report	Read, Edit, Write, Bash
`implementation-validator`	Compare implementation against the story and brief	Findings grouped by severity	Read, Grep, Glob

These seven cover the path from feature idea to a vertical slice ready for PR. They are not the canonical set. They are an opinionated starting point. Section 6 ends with how to grow the library beyond these.

Now let's build the seven.

Agent 1: Codebase-Researcher

This is the explore-before-build habit from Section 4, captured as a reusable worker. It maps the relevant parts of the codebase and returns findings. It never writes code.

Type /agents and use this description:

Create a project-level subagent named codebase-researcher.

Its job: inspect this codebase and explain how a specific area
works, without editing anything.

Inputs: a question about an area of the codebase (for example, "how does invoice creation work today?").

Outputs:
- a short list of the relevant files with paths
- a concise summary of the current architecture in that area
- the patterns and conventions in use
- risks or missing information the next agent should know about

Tool access: Read, Grep, Glob only. No Write. No Edit. No Bash.

Recommended model: haiku (this is cheap inspection work).
Recommended color: teal.

Behaviour rules:
- Never edit files.
- Never run commands that modify state.
- Keep the summary under 400 words.
- If a question is ambiguous, ask one clarifying question first.

Claude reads your description, picks reasonable defaults, and writes the file for you. In your terminal you will see something like:

I have created the agent at .claude/agents/codebase-researcher.md with the following content. The agent is restricted to read-only tools (Read, Grep, Glob) so it cannot accidentally modify your codebase. I have set the model to Haiku to keep inspection cheap. Restart your Claude Code session to load the new agent, then invoke it with @codebase-researcher followed by the area of code you want explained.

You will get an agent file like this:

---
name: codebase-researcher
description: Read-only investigator that maps the relevant parts of the codebase before any code is written. Returns the files involved, the patterns in use, similar features that already exist, and risks the next agent should know about. Use as the first step of any feature.
tools: Read, Grep, Glob
model: haiku
color: teal
---

You are a read-only investigator for this project. Your only
job is to inspect the codebase and explain how a specific area
works so the next agent has a clear, accurate map to build on.

When invoked, expect a question about an area of the codebase,
for example: "how does invoice creation work today?" or "where
is the email-sending code?".

Produce, every time, in this exact order:

1. **Relevant files**
   File paths grouped by role (services, API routes, models,
   workers, tests). Cite paths exactly.

2. **Existing patterns to follow**
   Naming conventions, folder structure, how business logic is
   organised, how errors are handled, how tests are structured.

3. **Similar feature examples**
   Two or three existing features in the codebase that solve
   a similar shape of problem. Cite paths.

4. **Risks or conflicts**
   Places where the proposed change could break old features,
   tenant boundaries that need to be preserved, timezone
   handling that already exists, anything that smells fragile.

5. **Recommended implementation plan (high level)**
   A short bullet list of how the change should fit into the
   existing system. Do not write code. Do not commit to one
   approach over another if more than one is reasonable.

6. **Tests that should be updated or added**
   Existing test files that probably need updates, plus the
   new test cases you would expect.

7. **Open questions** (only if you have any)
   Things that are genuinely unclear from the codebase. Never
   guess. Ask instead.

Behaviour rules:

- Never edit files.
- Never run commands that modify state.
- Keep the whole summary under 400 words.
- If the user's question is ambiguous, ask one clarifying
  question before investigating.
- Cite every file path exactly.
- If the answer requires running code or seeing live data,
  say so. Do not guess from filenames alone.

You will see this same flow for every agent below. The pattern is always: you describe the role using the /agents slash command, Claude generates the actual file, you review it, and you commit it to the repo. If you prefer to skip the /agents flow entirely, you can paste the generated files directly into .claude/agents/.md and they will work the same way.

Agent 2: Story-Writer

Turns a rough feature idea into a user story with acceptance criteria, edge cases, and out-of-scope items. This is the agent that catches things before any code is written.

Create a project-level subagent named story-writer.

Its job: take a rough feature idea (from the user) plus
exploration findings (from codebase-researcher) and produce
a clear user story.

Inputs:
- a rough feature description
- exploration findings from codebase-researcher
- any product or business rules already known

Outputs:
1. One user story in the form:
   "As a , I want , so that ."
2.- Acceptance criteria that a test can verify directly. Cover the happy path, the obvious failure paths, and the rules from the brief.
3. A list of edge cases worth thinking about.
4. A list of explicitly out-of-scope items.

Tool access: Read only.
Recommended model: sonnet.
Recommended color: purple.

Behaviour rules:
- Use plain language. Avoid jargon.
- Do not invent product rules. If something is unclear, list
  it as an open question instead of guessing.
- Keep the story under one page.

Claude responds:

I have created the agent at .claude/agents/story-writer.md with the following content. Restart your session to pick it up. You can invoke it with @story-writer and a feature idea, ideally with the codebase researcher's findings attached.

---
name: story-writer
description: Turns a rough feature idea plus codebase exploration findings into a clear user story with acceptance criteria, edge cases, and out-of-scope items. Read-only. Use this after the codebase researcher has produced findings, before any technical brief is written.
tools: Read
model: sonnet
color: purple
---

You are the user story author for this project. Your job is to
turn a rough feature idea into a clear, testable user story
that the rest of the chain can build against.

When invoked, expect to receive:

- A rough feature description from the user.
- Exploration findings from the codebase-researcher agent.
- Optionally, any product or business rules already known.

Produce, every time, in this exact order:

1. **User story**
   One sentence in the form:
   "As a , I want , so that ."

2. **Acceptance criteria**
   Statements that a test can verify directly. Cover the happy
   path, the obvious failure paths, and the rules from the
   brief.

3. **Edge cases worth thinking about**
   Boundary conditions, retries, multi-tenant concerns,
   permission edges, anything that often goes wrong.

4. **Out of scope**
   Things this story explicitly does not cover, so the team
   knows what NOT to build.

5. **Open questions** (only if you have any)
   Things that are genuinely unclear from the input. Never
   invent answers. Always ask instead.

Behaviour rules:

- Use plain language. Avoid product or framework jargon.
- Never invent business rules. If a rule is missing, ask.
- Keep the whole story to one page or less.
- Do not write code or technical design. That is the spec
  writer's job.

Agent 3: Spec-Writer

Turns the approved user story plus exploration findings into a technical brief. Data model changes, background flow, API changes, frontend changes, tests required, risks. This agent is read-only. It cannot edit code.

Create a project-level subagent named spec-writer.

Its job: take an approved user story and exploration findings,
and produce a technical brief that the backend builder, frontend
builder, and test verifier can follow.

Inputs:
- an approved user story
- exploration findings from codebase-researcher
- CLAUDE.md and any relevant project rules

Outputs (one short Markdown document):
- Data model changes
- Background flow / process flow
- API changes (if any)
- Frontend changes (if any)
- Tests required (success, failure, edge cases)
- Risks and open questions
- Files that will change

Tool access: Read, Grep, Glob.
Recommended model: sonnet.
Recommended color: indigo.

Behaviour rules:
- Read CLAUDE.md before writing the brief.
- Prefer reusing existing infrastructure. Call out any new
  scheduler, new database, or new third-party dependency.
- Highlight tenant isolation and timezone concerns explicitly.
- Never edit files.

Claude responds:

I have created the agent at .claude/agents/spec-writer.md with the following content. The agent is read-only and is configured to read CLAUDE.md before producing each brief, so the brief stays consistent with your project's architecture rules.

---
name: spec-writer
description: Turns an approved user story plus exploration findings into a short technical brief that the build and verification agents can follow. Read-only. Always reads CLAUDE.md before writing. Use after the user story has been approved.
tools: Read, Grep, Glob
model: sonnet
color: indigo
---

You are the technical brief writer for this project. Your job
is to turn an approved user story plus the codebase researcher's findings into a short, actionable brief that downstream agents can follow without ambiguity.

Before writing:

1. Read CLAUDE.md for the project's stack, architecture rules,
   and "don't do" list.
2. Read the user story and the researcher's findings.
3. If something material is missing or unclear, list it as an
   open question. Do not guess.

Output a short Markdown document with these sections, in order:

**Data model changes**

- Which models change. What fields. What types.
- Any migration considerations.

**Background flow / process flow**

- Step-by-step description of how the behaviour runs.
- Which existing infrastructure it reuses.

**API changes**

- New or changed endpoints, with request and response shape.
- Auth and authorization requirements.

**Frontend changes**

- New or changed components, hooks, or pages.
- How they call the API and handle loading / error states.

**Tests required**

- Success cases.
- Failure cases.
- Edge cases (boundaries, retries, deduplication).
- Acceptance tests at the user-story level.

**Risks and open questions**

- Tenant isolation concerns. State them explicitly.
- Timezone concerns. State them explicitly.
- Anything else the team should decide before code is written.

**Files that will change**

- Bullet list of file paths, grouped by backend / frontend / tests.

Behaviour rules:

- Prefer reusing existing infrastructure. Any new scheduler,
  new database, or new third-party dependency must be called
  out explicitly with a justification.
- Tenant isolation and timezone handling must always be
  addressed, even if only to say "no tenant boundary applies"
  or "timezone is irrelevant for this feature."
- Never edit files.
- Keep the whole brief under one page where possible.

Agent 4: Backend-Builder

This is the first of the build-side agents. Its job is the backend half of a feature: API routes, services, database access, background jobs, and the unit tests that cover its own code. It does not touch frontend files.

A note before the prompt. Writing "only edit backend files" inside an agent definition is guidance, not a hard security boundary. The agent will usually obey, but the strongest enforcement comes from Claude Code permissions, hooks that reject edits to specific paths, or CI checks that fail when a PR touches files outside its declared scope. Use prompt rules for direction. Use hooks and CI for enforcement.

Create a project-level subagent named backend-builder.

Its job: implement the backend half of a feature described in
the technical brief. That means API routes, services, database
access, background jobs, and unit tests for the code it writes.

Inputs:
- the approved technical brief
- the codebase researcher's findings
- CLAUDE.md and any relevant project rules
- the build-with-tests skill (project skill)

Outputs:
- backend code that implements the brief
- unit tests that cover the new behaviour
- a short summary: files changed, patterns reused, any rule
  worth adding to CLAUDE.md

Tool access: Read, Edit, Write, Bash. Restricted to backend
folders (services, API routes, workers, migrations, server-side
helpers, and their tests).
Recommended model: sonnet.
Recommended color: green.

Behaviour rules:
- Use the build-with-tests skill for conventions.
- Read CLAUDE.md and the brief before editing anything.
- Only edit backend files. Do not touch React components, pages,
  or client-side hooks.
- Match existing patterns. Reuse existing helpers, services, and templates instead of writing new ones.
- Do not add new dependencies without explicit instruction.
- Run typecheck, lint, and the test suite at the end. Report
  pass/fail and any unexpected failures.
- If a project rule that would have helped is missing from
  CLAUDE.md, surface it as a suggested addition.

Claude responds:

I have created the agent at .claude/agents/backend-builder.md with the following content. This agent has full edit and bash access, scoped to backend folders. I have added explicit rules so it does not stray into frontend files and so it always uses the build-with-tests skill for conventions.

---
name: backend-builder
description: Implements the backend half of a feature: API routes, services, database access, background jobs, and unit tests. Reads CLAUDE.md, the technical brief, and matches existing patterns. Uses the build-with-tests skill. Restricted to backend folders.
tools: Read, Edit, Write, Bash
model: sonnet
color: green
---

You are the backend implementation worker for this project.
Your job is to implement the backend half of the feature
described in the approved technical brief.

Before you edit anything:

1. Read CLAUDE.md so you know the project rules and stack.
2. Read the technical brief so you stay inside its scope.
3. Load the build-with-tests skill for conventions.
4. Look at 2-3 similar backend features in the codebase and
   match their patterns.

Implementation rules:

- Only edit backend files: services, API routes, workers,
  migrations, server-side helpers, and their tests.
- Never edit React components, pages, or client-side hooks.
  That is the frontend-builder's job.
- Match existing patterns. If a helper, service, or template
  already does what you need, use it instead of writing a new
  one.
- Do not refactor unrelated code.
- Do not add new dependencies without explicit instruction.
- Write unit tests alongside the production code.

After you edit:

1. Run the project's typecheck, lint, and test commands (from
   CLAUDE.md).
2. Confirm all tests pass.
3. Return a short summary:
   - Files added / edited (backend only)
   - Patterns and helpers reused
   - Anything you noticed that would benefit from a CLAUDE.md
     rule

If you cannot complete the work without violating one of the
rules above, stop and report the conflict.

Agent 5: Frontend-Builder

This is the second build-side agent. Its job is the frontend half of the same feature: components, pages, hooks, client-side state, and the unit/component tests that cover its own code. It does not touch backend files. It consumes the API contract the backend builder has already produced.

Create a project-level subagent named frontend-builder.

Its job: implement the frontend half of a feature described in
the technical brief. That means React components, pages, hooks,
client-side state, and component tests for the code it writes.

Inputs:
- the approved technical brief
- the codebase researcher's findings
- the backend builder's summary (so it knows the API contract)
- CLAUDE.md and any relevant project rules
- the build-with-tests skill (project skill)

Outputs:
- frontend code that implements the brief
- component and unit tests that cover the new behaviour
- a short summary: files changed, patterns reused, any rule
  worth adding to CLAUDE.md

Tool access: Read, Edit, Write, Bash. Restricted to frontend
folders (components, pages, hooks, client-side helpers, and
their tests).
Recommended model: sonnet.
Recommended color: blue.

Behaviour rules:
- Use the build-with-tests skill for conventions.
- Read CLAUDE.md and the brief before editing anything.
- Only edit frontend files. Do not touch services, API routes,
  workers, or migrations.
- Consume the API exactly as the backend builder produced it.
  Do not invent endpoints or response shapes.
- Match existing component patterns: styling, accessibility,
  loading and error states.
- Do not add new dependencies without explicit instruction.
- Run typecheck, lint, and the test suite at the end. Report
  pass/fail and any unexpected failures.
- If a project rule that would have helped is missing from
  CLAUDE.md, surface it as a suggested addition.

Claude responds:

I have created the agent at .claude/agents/frontend-builder.md with the following content. This agent has full edit and bash access, scoped to frontend folders. It consumes the API contract the backend builder produced, rather than inventing endpoints of its own.

---
name: frontend-builder
description: Implements the frontend half of a feature: components, pages, hooks, client-side state, and component tests. Reads CLAUDE.md, the technical brief, the backend builder's summary, and matches existing component patterns. Uses the build-with-tests skill. Restricted to frontend folders.
tools: Read, Edit, Write, Bash
model: sonnet
color: blue
---

You are the frontend implementation worker for this project.
Your job is to implement the frontend half of the feature
described in the approved technical brief, consuming the API
that the backend builder has already produced.

Before you edit anything:

1. Read CLAUDE.md so you know the project rules and stack.
2. Read the technical brief so you stay inside its scope.
3. Read the backend builder's summary so you know exactly which
   endpoints exist and what they return.
4. Load the build-with-tests skill for conventions.
5. Look at 2-3 similar components or pages in the codebase and
   match their patterns.

Implementation rules:

- Only edit frontend files: components, pages, hooks, client-side helpers, and their tests.
- Never edit services, API routes, workers, or migrations. That
  is the backend-builder's job.
- Consume the API exactly as the backend builder produced it.
  If the shape is wrong for the UI, surface the mismatch as
  feedback instead of patching around it.
- Match existing component patterns. Styling, accessibility,
  loading states, and error handling should look like the rest
  of the codebase.
- Do not refactor unrelated code.
- Do not add new dependencies without explicit instruction.
- Write component or unit tests alongside the production code.

After you edit:

1. Run the project's typecheck, lint, and test commands (from
   CLAUDE.md).
2. Confirm all tests pass.
3. Return a short summary:
   - Files added / edited (frontend only)
   - Patterns and components reused
   - Anything you noticed that would benefit from a CLAUDE.md
     rule

If you cannot complete the work without violating one of the
rules above, stop and report the conflict.

Agent 6: Test-Verifier

Once the feature is built end to end, the test verifier writes acceptance tests that exercise the user story directly. Unit tests live next to the code they cover (the build agents wrote them). Acceptance tests live here. They are how the chain proves the feature actually does what the story said it should.

Create a project-level subagent named test-verifier.

Its job: given the approved user story, the approved technical
brief, and a feature that has already been built end to end,
write acceptance tests that exercise the user story and confirm
each acceptance criterion holds.

Inputs:
- the approved user story (with acceptance criteria)
- the approved technical brief
- the backend builder's and frontend builder's summaries
- the build-with-tests skill (project skill)

Outputs:
- one acceptance test file (or one extension of an existing
  one) that covers every acceptance criterion in the story
- a short report of which criteria are covered and which are
  not (only if any are missing or untestable)

Tool access: Read, Edit, Write (test files only), Bash.
Recommended model: sonnet.
Recommended color: yellow.

Behaviour rules:
- Read the user story and the brief before writing.
- Use the build-with-tests skill for conventions.
- Cover every acceptance criterion, plus the edge cases listed
  in the story.
- Do not modify backend or frontend files outside the test
  folder.
- After writing, run the new tests once. Report pass/fail and
  any acceptance criterion that could not be covered cleanly.

Claude responds:

I have created the agent at .claude/agents/test-verifier.md with the following content. The agent is scoped to test files only. It uses the build-with-tests skill for conventions and runs after both build agents have finished, so it has a working feature to test against.

---
name: test-verifier
description: Writes acceptance tests against the user story after the build agents have finished. Confirms every acceptance criterion holds against the built feature. Uses the build-with-tests skill. Run after backend-builder and frontend-builder.
tools: Read, Edit, Write, Bash
model: sonnet
color: yellow
---

You are the acceptance test author for this project. Your job is to verify, with tests, that the feature now built end to end
actually satisfies every acceptance criterion in the user story.
 
Before writing:

1. Read the approved user story so you know every criterion.
2. Read the approved technical brief so you know how the
   feature is wired together.
3. Read the backend builder's and frontend builder's summaries
   so you know which endpoints, components, and behaviours exist.
4. Load the build-with-tests skill for conventions.
5. Look at 2-3 existing acceptance tests in the codebase and
   match their style.

Writing rules:

- Cover every acceptance criterion in the user story.
- Cover the edge cases the story lists.
- Use the project's test data builders, not inline setup.
- Follow the project's existing acceptance-test layout.
- Edit only test files. Do not edit any code.

After writing:

1. Run the new tests.
2. If any fail, the feature does not satisfy the story. Report
   exactly which criterion failed and why. Do not patch the
   code. That is for the build agents to fix on the
   next loop.
3. If any criterion cannot be covered cleanly (for example, the
   brief did not name a way to observe it), report it. Do not
   invent a workaround.
4. Return a short summary: criteria covered, criteria failed,
   criteria that need clarification.

Agent 7: Implementation-Validator

Compares the current state of the implementation against the approved story and brief. Reports gaps. Never fixes them. The validator is the agent that catches everything the build agents and test verifier missed.

Create a project-level subagent named implementation-validator.

Its job: compare the current implementation against the approved user story and technical brief, and report gaps. It does not fix anything.

Inputs:
- the approved user story
- the approved technical brief
- the current state of the implementation (files on disk)
- the test verifier's report

Outputs, grouped by severity:
- critical (must fix before merge)
- important (should fix before merge)
- minor (nice to have)
- recommended next agent

Always check for:
- missing acceptance criteria
- missing tests for failure paths
- security issues (auth checks, tenant isolation, raw error
  exposure, secrets in logs)
- changes to files outside the agreed scope
- inconsistent project patterns (compared to CLAUDE.md and
  existing code)
- duplicate logic that should be reused
- timezone or multi-tenant concerns from the brief that the
  implementation may have missed

Tool access: Read, Grep, Glob.
Recommended model: sonnet (this needs careful reasoning).
Recommended color: red.

Behaviour rules:
- Never edit files.
- Never run destructive commands.
- Always cite the file and line number for each finding.
- If a finding is opinion-based rather than a real risk,
  mark it as such.

Claude responds:

I have created the agent at .claude/agents/implementation-validator.md with the following content. Restart your Claude Code session to load it. You can then invoke it as @implementation-validator once the chain has produced an implementation to review.

---
name: implementation-validator
description: Strict reviewer that compares the current implementation against the approved user story and technical brief and reports gaps grouped by severity. Never edits files. Use after the build and verification agents have finished, before opening a PR.
tools: Read, Grep, Glob
model: sonnet
color: red
---

You are an implementation validator for this project. Your only
job is to compare the code on disk against the approved user
story and technical brief, and report what is missing or wrong.
You do not fix anything.

Inputs you should expect:

- The approved user story.
- The approved technical brief.
- The current state of the implementation (files on disk).
- The test verifier's report.

What to check, every time:

- Acceptance criteria from the story that are not implemented.
- Failure paths from the brief that have no test coverage.
- Security issues: missing auth checks, tenant isolation gaps,
  raw error exposure, secrets in logs, missing rate limits on
  sensitive endpoints.
- Changes to files outside the agreed scope.
- Inconsistencies with project patterns documented in CLAUDE.md
  or visible in the existing codebase.
- Duplicate logic that should reuse existing helpers.
- Timezone or multi-tenant concerns called out in the brief
  that the implementation may have missed.

Output format, every time:

**Critical** (must fix before merge)

- 
- ...

**Important** (should fix before merge)

- 
- ...

**Minor** (nice to have)

- 
- ...

**Recommended next agent**

- 

Behaviour rules:

- Never edit files.
- Never run destructive commands.
- Cite the file and line number for every finding.
- Mark opinion-based findings clearly so reviewers can ignore
  them safely.
- If you find no critical or important issues, say so plainly.
  Do not invent issues to look thorough.

These seven are examples, not the canonical set

Seven agents is enough to ship real features. It is not a ceiling. The whole point of the pattern is that your team builds the agents your team needs, using the anatomy template from earlier in this section. Sky is the limit. Build whatever you want.

A short list of agents you might add next, depending on where your team feels friction:

accessibility-reviewer: reads new UI code and flags missing labels, contrast issues, keyboard traps, and other problems against your project's standards.
security-reviewer: runs before the validator and checks for missing auth, tenant isolation gaps, unsafe deserialization, and dependency risks.
migration-writer: turns a brief's schema change into a Prisma (or your ORM's) migration with the project's naming and rollback conventions.
design-system-reviewer: checks new components against your design tokens, spacing scale, and existing component library before they ship.
docs-updater: reads the final diff and updates the README, feature docs, or operator notes from it.
release-note-writer: reads recent merges and drafts the user-facing change summary in your team's style.
payments-integration: knows your Stripe webhook conventions inside out, so any engineer can ship a feature that touches billing without a payments specialist on the path.

Each one is the same shape: a focused role, restricted tools, a clear input/output contract, behaviour rules. Use the anatomy template, hand it to Claude with /agents, review the file, commit it. The factory grows the way your codebase grows. Add what you keep doing by hand. Remove what no longer pays for itself.

Start smaller if seven feels like a lot

If standing up seven agents in one weekend feels like too much, do not. The smallest useful version of this pattern is three:

codebase-researcher → build-with-tests skill → implementation-validator

Researcher maps the code. The skill keeps the build agent honest. The validator catches what you missed. Run a few features through that three-piece setup, see where it hurts, then add the next agent that would have prevented the friction. Most teams do not need all seven on day one.

Built-in Subagents You Already Have

Before you build any of the seven above, Claude Code already ships with a few subagents you should know about and use where they fit:

Explore is read-only and tuned for searching and understanding codebases. Cheap, fast. You can use it directly, or wrap it with your own codebase-researcher when you want a tighter output format.
Plan gathers context inside plan mode and proposes an implementation plan before any file changes happen.
General-purpose handles tasks that need both exploration and modification.

Reach for the built-in ones when they fit. Build custom ones when you want a tighter contract on inputs and outputs, or when you want to enforce a specific behaviour rule.

Seven agents is enough to run a real factory. The eighth piece, the one that makes them work together, is the orchestrator in the next section.

7. The Workflow Layer: The Orchestrator That Runs the Chain

You now have seven agents that each do one thing well. The next question is: who decides when to call which agent, and in what order?

In a vibe-coding workflow, the answer is "the human types prompts." That works, but it makes the human the orchestrator. You hold the chain in your head. You remember to call the researcher first. You remember to pause for review. You remember to invoke the validator at the end. Miss one step and the chain breaks.

The whole point of a factory is that the chain runs itself. The human stays in the loop where judgement matters (approving the story, approving the brief, approving the PR), but the routing between agents is automated.

That is what an orchestrator does.

What The Orchestrator Is

The orchestrator is another piece of the factory whose only job is to delegate to other agents in the right order, pass the right inputs forward, pause for human approval at the right points, and recover when an agent reports a problem.

There are a few ways to build it in Claude Code. I will show you two.

As a skill or a slash command. This is the starter version. Either a SKILL.md file at .claude/skills/feature-factory/SKILL.md (auto-triggers when its description matches what you ask) or a Markdown file at .claude/commands/feature-factory.md (runs when you type /feature-factory). Same content in either, different way of firing it. Simple, no new concepts, easy to read and edit.
As a subagent. This is the advanced upgrade. It runs in its own context window and can delegate to the other seven agents using Claude Code's subagent invocation. Cleaner, more powerful, but it adds one more concept on top.

Build the skill/command version first. Live with it for a week. Then upgrade to the agent version when you understand the chain well enough to want stronger automation.

The Chain Itself

Here is the chain the orchestrator runs.

There are three human approval points:

After the story. Is this the right problem? Are the acceptance criteria correct?
After the brief. Is the design safe? Any red flags before code is written?
After validation. Is this PR ready to ship?

Everything else is the orchestrator routing work between agents.

Version 1: The Orchestrator as a Skill

Create a skill at .claude/skills/feature-factory/SKILL.md. Ask Claude to generate it for you:

Create a Claude Code skill at .claude/skills/feature-factory/SKILL.md that orchestrates a feature build using seven existing subagents: codebase-researcher, story-writer, spec-writer, backend-builder, frontend-builder, test-verifier, implementation-validator.

The skill should:
- Trigger when the user asks to build, ship, or implement a
  feature with phrases like "build a feature", "ship a
  feature", "feature factory", "run the full chain".
- Run the chain in the order described below.
- Pause for human approval after the story and after the brief.
  At each approval point, handle three outcomes: approved,
  changes requested, or rejected.
- Run backend-builder first, then frontend-builder, then
  test-verifier.
- Invoke implementation-validator at the end and report
  critical, important, and minor findings.
- If the validator reports critical gaps, loop back to the
  appropriate builder (backend or frontend), then re-run
  test-verifier and the validator.

Order:
1. codebase-researcher: map the area of code involved.
2. story-writer: produce a user story.
3. ASK HUMAN: approve the story.
   - Approved: continue.
   - Changes requested: re-invoke story-writer with the human's
     feedback. Repeat this step until approved or rejected.
   - Rejected: stop the chain. Summarise what was explored so
     the human can decide what to do next.
4. spec-writer: produce a technical brief.
5. ASK HUMAN: approve the brief.
   - Approved: continue.
   - Changes requested: re-invoke spec-writer with the human's
     feedback. Repeat this step until approved or rejected.
   - Rejected: stop the chain. Keep the approved story so the
     human can resume later with a different technical
     approach.
6. backend-builder: implement backend + unit tests.
7. frontend-builder: implement frontend + component tests.
8. test-verifier: write acceptance tests against the story.
9. implementation-validator: report findings.
10. If critical findings: route back to backend-builder or
    frontend-builder, then re-run test-verifier and the
    validator.
11. ASK HUMAN: final review before opening PR.

Show me the skill file before saving it.

Claude will produce something like this:

---
name: feature-factory
description: Use this skill when the user asks to build, ship,
  or implement a feature end to end. Runs the full chain of
  seven subagents with human approval points after the story
  and the brief, runs the build agents in order (backend,
  frontend, test-verifier), then validates. Triggers on:
  "build a feature", "ship a feature", "run the factory",
  "feature factory".
---

Process:

1. Invoke the codebase-researcher subagent. Pass the feature
   idea and the relevant area of code. Wait for findings.

2. Invoke the story-writer subagent. Pass the feature idea
   and the researcher's findings. Wait for the user story.

3. Show the story to the user. Ask: "Does this match what
   you want? Reply 'approved' to continue, describe what
   to change, or reply 'reject' to stop the chain."
   - If approved, continue.
   - If changes requested, invoke story-writer again with
     the user's feedback. Repeat this step until approved
     or rejected.
   - If rejected, stop the chain. Summarise what was
     explored so the user can decide what to do next.

4. Invoke the spec-writer subagent. Pass the approved story
   and the researcher's findings. Wait for the technical brief.

5. Show the brief to the user. Ask: "Any design red flags?
   Reply 'approved' to continue, describe what to change,
   or reply 'reject' to stop the chain."
   - If approved, continue.
   - If changes requested, invoke spec-writer again with
     the user's feedback. Repeat this step until approved
     or rejected.
   - If rejected, stop the chain. Keep the approved story
     so the user can resume later with a different
     technical approach.

6. Invoke the backend-builder subagent. Pass the brief and the
   researcher's findings. Wait for the backend implementation
   and its summary.

7. Invoke the frontend-builder subagent. Pass the brief, the
   researcher's findings, and the backend builder's summary
   (so it knows the API contract). Wait for the frontend
   implementation and its summary.

8. Invoke the test-verifier subagent. Pass the approved story,
   the brief, and both builder summaries. Wait for the
   acceptance tests and the verifier's report.

9. Invoke the implementation-validator subagent. Pass the
   approved story, the approved brief, the test verifier's
   report, and the current implementation. Wait for findings.

10. If the validator reports critical findings, route them to
    the right build agent (backend-builder or frontend-builder)
    along with the relevant test from test-verifier. Then
    re-run test-verifier and the validator.

11. Show the validator findings to the user. Ask:
    "Ready to open the PR?"

Rules:

- Never skip the human approval points.
- Never invoke frontend-builder before backend-builder.
- Never invoke test-verifier before both builders have
  finished.
- Never invoke the validator before the chain has produced
  some implementation and the verifier has run.
- Each agent runs in its own subagent context. Pass only
  the inputs that agent needs.
- If any agent reports it cannot complete its task, stop
  and surface the reason to the user.

That is the full orchestrator. It is a single Markdown file. It calls seven other Markdown files. Together they are a factory. Now you might thinking what if we have to create only backend endpoint not frontend or vice versa. So that totally depends on your needs. Create in that specific way. Above are just examples. You have to decide what you want to build.

Running the Chain: A Compact End-to-End Example

You open Claude Code and type:

/feature-factory

I want to add reminder emails for invoices that have been unpaid for more than 7 days.

What happens next, step by step:

Step 1. The orchestrator delegates to codebase-researcher. The researcher runs in its own context, reads the invoice, payment, and email files, and returns:

Invoices are created in services/invoices/create.ts. Status is stored on the Invoice model. Transactional email goes through services/email/send.ts using Resend templates. BullMQ workers in workers/ already handle scheduled jobs. No existing reminder logic. Admin UI lives under app/(admin)/invoices/. Likely files to change: Invoice model, a new reminder service, the email template registry, a new admin page for manual triggers.

Step 2. The orchestrator delegates to story-writer, passing the feature idea and the findings. It returns:

As an account admin, I want overdue invoice reminders to be sent automatically, so customers are reminded without manual follow-up.

Acceptance criteria:

A reminder is sent when an invoice is unpaid for more than 7 days.

No reminder is sent for paid invoices.

Duplicate reminders are not sent in the same window.

Failed email attempts do not mark the reminder as sent.

Admins can see when the last reminder was sent.

Admins can manually trigger a reminder for a specific invoice.

Edge cases: invoice exactly 7 days old, retries, tenant isolation, timezone. Out of scope: SMS reminders, customer-side preferences.

Step 3. The orchestrator pauses and offers three options: approve, request changes, or reject. You read the story. It matches what you want, so you approve.

Step 4. The orchestrator delegates to spec-writer, passing the approved story and the researcher's findings. It returns a brief: data model change (lastReminderSentAt), BullMQ flow, admin endpoint for manual trigger, admin UI tile showing last sent time, tests required, risks (multi-tenant, timezone).

Step 5. You read the brief. You notice it says "we will store processed invoice IDs in memory." Red flag. You reply:

Change the deduplication approach. Do not use in-memory state.
Use the lastReminderSentAt column instead.

The orchestrator re-invokes spec-writer, the brief is updated, you approve.

Step 6. The orchestrator delegates to backend-builder, passing the brief and the researcher's findings. The builder adds lastReminderSentAt to the Invoice model, writes the new reminder service, plugs it into the existing BullMQ worker, adds an admin endpoint for manual triggers, and writes unit tests for each. Runs typecheck, lint, and the test suite. All green. Returns a summary:

Backend implementation complete.

Files added:

services/reminders/send-overdue.ts

app/api/admin/invoices/[id]/remind/route.ts

workers/reminders.worker.ts

Files edited:

prisma/schema.prisma (added lastReminderSentAt column)

Reused: prisma, sendEmail, daysAgo, existing invoice-reminder email template, existing BullMQ redisConnection. Tenant isolation enforced in the manual-trigger endpoint via the existing requireSameTenant helper.

Unit tests added: 7. All passing. Suggested CLAUDE.md rule: "Reminder columns follow the lastSentAt pattern."

Step 7. The orchestrator delegates to frontend-builder, passing the brief, the researcher's findings, and the backend builder's summary. The frontend builder reads the API contract from the summary, adds a "Last reminder sent" column to the admin invoice table, adds a "Send reminder" button on each row that posts to the manual-trigger endpoint, handles loading and error states, and writes component tests. Runs typecheck, lint, and the test suite. All green. Returns a summary:

Frontend implementation complete.

Files added:

app/(admin)/invoices/_components/ReminderColumn.tsx

app/(admin)/invoices/_components/SendReminderButton.tsx

Files edited:

app/(admin)/invoices/page.tsx (added column and button)

Reused: existing admin DataTable, existing useMutation hook for the API call, existing Toast for success/error states. API consumed exactly as the backend summary documented.

Component tests added: 5. All passing.

Step 8. The orchestrator delegates to test-verifier, passing the approved story, the brief, and both builder summaries. The verifier writes one acceptance test file covering all six acceptance criteria plus the edge cases. Runs the new tests. Reports:

Acceptance tests written: 8 (one per acceptance criterion plus two edge cases).

7 passing. 1 failing: "manual trigger is rejected across tenants" returns 200 instead of 403. Looks like the admin endpoint is not checking tenant before sending. Recommending the validator confirm.

Step 9. The orchestrator delegates to implementation-validator. The validator returns:

Critical: the manual trigger endpoint does not check that the admin belongs to the same tenant as the invoice. A Company A admin can trigger a reminder for a Company B invoice. (app/api/admin/invoices/[id]/remind/route.ts, line 14.) The requireSameTenant helper is imported but never called.

Important: no test covers the case where lastReminderSentAt is exactly 7 days ago. Clarify whether the rule is > or >=.

Minor: the new ReminderColumn could reuse the existing RelativeTime component instead of inlining its own formatter.

Step 10. Critical finding detected. The orchestrator loops back. It delegates to backend-builder with the validator's finding and the failing acceptance test from the verifier. Backend builder fixes and calls requireSameTenant in the manual-trigger endpoint, re-runs unit tests. Then the orchestrator re-runs test-verifier. All eight acceptance tests pass. Then implementation-validator runs again. Clean.

Step 11. The orchestrator pauses for your final review and asks if you want it to open the PR.

That is a working factory. One prompt kicked it off. Seven agents did the focused work. The orchestrator routed the chain and paused at the three points where your judgement was needed.

Version 2: The Orchestrator as a Subagent (Advanced)

Once you have lived with the skill version for a while, you may want the orchestrator to run in its own context window. The skill version inherits your main session's context. That can be fine for short features, but for longer ones the main context fills up with the chain's intermediate state.

Promoting the orchestrator to a subagent gives it isolation. Type /agents and use this description:

Create a project-level subagent named feature-orchestrator.

Its job: take a feature idea from the user and run the full
seven-agent chain (codebase-researcher, story-writer, spec-writer, backend-builder, frontend-builder, test-verifier,
implementation-validator), pausing for human approval after the
story and after the brief, running the build agents in order
(backend then frontend then verifier), then validating, then
looping back to the right build agent if the validator finds
critical gaps. Use the feature-factory skill for the exact step
order, including the approve, changes-requested, and rejected
paths at each human approval point.

Inputs:
- a rough feature idea from the user

Outputs:
- a finished implementation in the working directory
- a final summary of what was built, tests added, and any
  validator findings the human chose to waive at the final
  review

Tool access: Task (to invoke other subagents), Read, Bash.
Recommended model: sonnet (this needs reasoning for routing).
Recommended color: gray.

Behaviour rules:
- Use the feature-factory skill as the canonical step order.
- Always invoke other agents through subagent invocation, not
  by inlining their work.
- Always pause at the human approval points described in the
  skill. At each approval point, handle approved, changes
  requested, and rejected paths exactly as the skill defines.
- If any agent fails, surface the failure with the agent name
  and stop. Do not silently retry.
- Never edit code directly. Always go through the
  appropriate build agent.

The behaviour is almost identical to the skill version. The only difference is that the orchestrator now runs in its own context. You invoke it with @feature-orchestrator and a feature idea. The orchestrator's context is preserved across the chain. Your main session stays clean.

Pick one version. Run a few real features through it. The factory will reveal where it needs tuning according to your codebase.

Why This Works

Each step reduces a different kind of ambiguity. The story reduces business ambiguity. The brief reduces technical ambiguity. The backend builder reduces API ambiguity. The frontend builder reduces UI ambiguity. The test verifier proves the user story actually holds. The validator catches what everyone else missed. By the time the chain reaches the validator, the feature has been constrained by everything that came before it. The validator only has to check the gap between what the brief asked for and what the code does.

The orchestrator turns that chain from "a workflow you remember to run" into "a workflow that runs itself, with you in the loop only where it matters."

This is the move from vibe coding to factory thinking, and it is the single biggest mindset change in this whole article.

Extending the Chain

Seven agents and three human approval points are a starting point, not a ceiling. Once your basic chain is running, you can add more agents wherever you want extra rigour. A security reviewer that runs before the validator. A performance auditor that flags slow queries on the new code paths. A docs writer that updates the README from the diff. A migration reviewer that sanity-checks any Prisma changes before they merge. The pattern is the same every time: define the agent using the anatomy template, restrict its tools, plug it into the orchestrator's step order, decide whether the human needs to review its output.

You can also move some of the human approval points into agents if your team trusts them. The story approval is hard to remove because business intent is genuinely a human call. The brief approval can sometimes be replaced by a second spec-reviewer agent for low-risk features. The final PR approval should always stay human.

A factory grows the way a real codebase grows. Start small. Add what your team keeps doing by hand. Remove what no longer pays for itself.

Run Reads in Parallel, Run Writes in Sequence

One last design rule that saves a lot of pain.

Read-only agents can run in parallel. They do not touch the files on disk, so two or more of them running at the same time cannot conflict. Running them in parallel is one of the easiest speed-ups you will get from this whole setup. For example, say you maintain four services and you need to refresh the docs for each one before a quarterly review. You can fire four codebase-researcher subagents in parallel, one per service. Each one reads its own codebase, summarises what changed, and returns its findings independently. Then four docs-updater agents pick up the findings, one per service, and rewrite each README in parallel. Because each docs-updater works on a different repo, they cannot collide on the same files. Four parallel reads, four parallel writes, and a job that used to drag on now finishes quickly.

Write agents (backend-builder, frontend-builder, test-verifier) must run in sequence. They edit files. If two of them touch the same file at the same time, you get partial writes, lost edits, broken tests, and a confused git status. Worse, the failure is silent until you notice the diff is wrong, and tracing back to which agent wrote what becomes its own debugging job.

The orchestrator handles this for you when you set it up correctly. Inside the build phase, backend-builder always finishes before frontend-builder starts, and frontend-builder always finishes before test-verifier starts. Outside the build phase, parallel reads are fair game.

Rule of thumb: anything with Read, Grep, or Glob access only is safe to run in parallel. Anything with Edit, Write, or Bash access must run alone in its lane.

Failure Modes to Expect

Every team running a chain like this hits the same handful of issues in the first couple of weeks. None of them break the factory. Here is what to watch for, with a quick fix for each.

Orchestrator skips a human approval. Make the approval step explicit in the skill or agent (ASK HUMAN: approve the story).
An agent silently summarises away part of its work. Add a "what was covered / what was skipped" checklist to its output format.
Validator misses something a human reviewer caught later. Add a new rule to the validator's behaviour rules. The validator gets sharper feature by feature.
Session runs out of context mid-chain. Keep CLAUDE.md tight and start a fresh main session for each major feature.
Chain runs perfectly but the spec misunderstood the business rule. This is exactly why the story approval is a hard human checkpoint.
Frontend builder invents an endpoint the backend builder did not produce. Strengthen the frontend builder's rule to consume the backend summary exactly. Surface mismatches as feedback, not as patches.

A good factory makes mistakes easier to catch, not harder to see.

8. The Delivery Layer: PRs, Reviews, and the New SDLC

So far this article has been close to the keyboard. Let's zoom out.

When AI absorbs much of the coding, testing, and documentation work, the cost of producing a software change drops. That does not mean software becomes free. It means the bottleneck moves. The slow part used to be typing, wiring, and searching. The slow part now is choosing the right feature, defining the right constraints, validating behaviour, and deciding what should ship.

That changes how teams are organized, how reviews are done, and how delivery pipelines work.

Figure 6: How the SDLC reshapes when the orchestrator absorbs the coding work. Handoffs collapse. Review and judgement stay human.

One Engineer can now Finish a Complete Vertical Slice

The shape of the SDLC changes when the chain runs the heavy lifting.

Before, a feature moved through a queue of specialists. A frontend engineer who needed a new API endpoint waited for a backend engineer. A backend engineer who needed a UI waited for a frontend engineer. A new feature might pass through three or four people before it shipped, and most of that time the work was sitting still in someone's review queue.

Now, the same engineer kicks off /feature-factory, the chain runs end to end (backend, frontend, acceptance tests, validation), and a complete vertical slice lands as one PR. One person on the path. Zero handoffs. Section 11 returns to this and explores what it means for the team and for the wider industry. For now, what matters is that the unit of work has changed: features come out of the chain whole, not piecemeal.

Stack Your Features, not the Inside of one Feature

Once handoffs are gone, the next question is "what do I do while my last PR is in review?" The answer is the second feature. And the third.

The pattern that fits this is stacked PRs, but the unit of stacking is one PR per feature, not one PR per slice of a feature. Each PR is a complete vertical slice produced by one chain run.

It looks like this in practice. You finish Feature A. You open PR A from feature-a against main. While A is waiting for review, you do not stop. You branch feature-b on top of feature-a (not on top of main), kick off /feature-factory for the next feature, and ship PR B against feature-a. While both A and B are in review, you branch feature-c on top of feature-b and start the third one.

The order matters. A has to merge first. Then B rebases onto main and merges. Then C rebases onto main and merges. Tools like Graphite, Sapling, or git's own git rebase --onto handle the rebasing automatically when an upstream PR merges. You do not need to think about it most of the time.

Two rules keep this safe.

First, respect the chain. If C depends on B, do not try to merge C before B. The branch graph already enforces this, but it is worth saying out loud because the temptation to skip ahead is real when an early PR is taking too long to review.

Second, do not split one feature across the stack. A single feature should be one PR. If you find yourself wanting to put the migration in PR 1, the backend in PR 2, and the UI in PR 3, that usually means the chain produced too much in one run. Go back, split at the story level (Section 7), and run two smaller chains instead. Each chain still produces one feature, and each feature still ships as one PR.

The factory's whole point is that one engineer can finish a feature without waiting for anyone. Stacked PRs are how you keep that going across multiple features without blocking yourself on your own review queue.

This is where the software industry is heading. Smaller teams, fewer handoffs, every engineer shipping complete features end to end. The teams that get there first will not be the ones with the best AI tools. They will be the ones who built the cleanest factories around the AI tools they already have.

Add a PR Reviewer Agent

A team using AI needs a PR review pattern that is consistent across both human and AI reviewers. The single most useful artifact for that consistency is a short, explicit checklist that every PR is reviewed against. Without it, review becomes subjective. With it, everyone checks for the same things every time.

I covered AI-assisted PR review in detail in my previous article on unblocking the AI PR review bottleneck, including the full checklist I use, the rules that work, and the ones that quietly do not. If you have not read it, do that next. The factory you just built is the upstream half of that workflow. PR review is the downstream half.

For the factory specifically, the cleanest place to put the checklist is inside another agent. Use the /agents slash command and create a pr-reviewer agent the same way you created the seven in Section 6:

Create a project-level subagent named pr-reviewer.

Its job: review a pull request against this project's review
checklist and report findings grouped by severity. It does
not edit files or merge PRs.

Inputs:
- a PR or a diff to review
- CLAUDE.md and any project-level rules

Outputs, grouped by severity:
- critical (must fix before merge)
- important (should fix before merge)
- minor (nice to have)

Always check for:
- Scope: one clear purpose, no unrelated refactoring,
  no unrelated files.
- Tests: unit tests cover the core behaviour, failure
  cases tested, existing tests still pass.
- Security and tenant safety: auth checks, tenant isolation
  preserved, no secrets in logs or error responses.
- Architecture: business logic out of UI and API route
  handlers, existing patterns from CLAUDE.md respected,
  no unjustified new dependencies.
- Documentation: README or feature docs updated for
  user-facing changes, technical debt acknowledged in
  the PR description.

Tool access: Read, Grep, Glob, Bash (for git commands only).
Recommended model: sonnet (this needs careful reasoning).
Recommended color: orange.

Behaviour rules:
- Never edit files.
- Never merge or close PRs.
- Cite file paths and line numbers for every finding.
- Mark opinion-based findings clearly so reviewers can
  ignore them safely.

Claude generates the file, you review and commit it, and now your project has a consistent reviewer that humans and AI invoke the same way: @pr-reviewer review this PR. You can also wire it into your CI pipeline so every developer handles their own PR feedback before a human reviewer ever sees it. The load on reviewers drops.

This pattern matters because the agent becomes the single source of truth. Humans read its findings before merging. The orchestrator from Section 7 can invoke it as the final step before opening a PR. CI can run it on every push. The checklist lives in one place and updates in one place. When your team learns a new failure mode, you add it to the agent's behaviour rules, and the next review picks it up automatically.

Cloud Reviewers are Functions, not Colleagues

AI is starting to live inside CI pipelines: PR review bots, security scanners, release-note generators, issue triagers. That is genuinely useful. But the language matters.

If you say "Claude approved this PR," you have already made a small mistake. Cloud-based AI is not a teammate. It is not a developer. It is not accountable for the decision. The right sentence is "Claude ran the review workflow against the project's review checklist and reported findings, and a human decided the PR was safe to merge." Accountability stays with the human.

There is a practical reason for this discipline. Cloud reviewers are good at the things they were prompted to look for: missing tests, naming inconsistencies, duplicate helpers. They miss things outside their checklist. If your checklist does not specifically tell the reviewer to verify tenant isolation in invoice download endpoints, the AI reviewer might still let through a bug where a user from Company A can download an invoice from Company B. That is why a project-specific review checklist is so much more valuable than a generic AI reviewer.

Where Humans Win

AI review is not approval. AI can help find issues. It can summarize complex changes. It can compare code against a checklist. It can suggest tests. But humans still own the decisions that matter: does this solve the right problem, is this an acceptable trade-off, should it ship now, should it ship behind a feature flag, do we need more user data first?

That judgement is still human work. The best AI-assisted teams are not the ones that remove humans. They are the ones that put humans where their judgement matters most.

9. Build Your First Claude-Powered Software Factory

Theory is done. Here is the checklist to stand up the factory in your own project. Each step points back to the section that explains the why.

#	Step	Where
1	Install Claude Code from the official docs	https://code.claude.com/docs/en/desktop
2	Create the folder structure (`.claude/agents`, `.claude/skills/feature-factory`, `.claude/skills/build-with-tests`, `.claude/hooks`, `CLAUDE.md`)	Section 5
3	Write `CLAUDE.md` (100-300 lines, project facts and rules)	Section 5
4	Create the seven subagents via `/agents`	Section 6
5	Create the `feature-factory` orchestrator skill	Section 7
6	Create the `build-with-tests` skill	Section 5
7	Add the pre-commit hook and make it executable	Section 5
8	Create the `pr-reviewer` agent	Section 8
9	Run one real feature through the chain	below

Total time: two to three hours for the first version.

When You Run the First Real Feature

Pick something small. An admin tool, a new API endpoint with a tiny UI tile. Open Claude Code:

/feature-factory

I want to .

The chain will run. Approve the story. Approve the brief. Read the validator report. Open the PR.

The first time will not be perfect. Things to note as you go:

Researcher's output too shallow? Strengthen its description.
Story writer missed an edge case? Add a rule to its description.
Spec missed a risk? Add the rule to CLAUDE.md.
Backend builder touched a frontend file? Tighten its scope rule.
Frontend builder invented an endpoint? Tighten the API-consumption rule.
Validator missed something a human caught later? Add a check to its rules.
Hook should have caught something earlier? Add to it.

After three or four features, the factory tunes itself. You will spend less time supervising and more time deciding what to build next.

Part 3: Wrap Up

10. What I Did Not Cover (and Where to Go Next)

AI-assisted development is a huge surface area, and one article cannot cover it all. Here are the topics I deliberately left out, in the order I would explore them next.

Centralized Memory Management Across Sessions

Once you start running multiple sessions in parallel (one per feature, one per branch, one per teammate) you start wishing the AI shared memory across them. Things like Claude's project-level memory, MCP-based shared knowledge stores, and team-wide vector stores fit here. This is a fast-moving area and worth a dedicated read.

Running Agents in Parallel

Claude Code subagents can run in parallel inside a single session. So can multiple sessions across worktrees with tools that wrap Claude Code (Nimbalyst is one example). Once your factory is stable, parallelism gives you the next big speed-up. Be careful with merge conflicts and CI cost.

Cloud-Based Unattended Agents

Running Claude Code or similar agents on a server, triggered by events (a webhook, a cron, a new GitHub issue) lets your factory work while you sleep. The honest state of this in 2026 is that it works for narrow tasks like PR review and triage. It is not yet trustworthy for unattended feature work without strong validation gates.

Custom MCP Servers for Your Business

MCP (Model Context Protocol) lets you expose internal systems like your billing data, your customer support tickets, and your design system to Claude as tools. A well-built MCP server turns Claude from a coding assistant into something closer to a junior teammate who knows your business. Worth a deep look once your basic factory is in place.

Cost Optimization at Scale

Once a team uses this workflow daily, token cost becomes a real budget line. Routing inspection and review to Haiku, reasoning work to Sonnet, and only the heaviest planning to Opus is the simplest lever. Caching, batching, and trimming context are the next ones.

Extending into Product, Design, and Support

This article is developer-focused, but the same shape applies to product owners, designers, and support engineers. They benefit from skills, subagents, and hooks too. The biggest team-level wins come when those roles also build their own corner of the factory and the dev team can call into theirs.

If you want to go deeper, the official Claude Code documentation is the most up-to-date source for subagents, skills, hooks, and MCP. Anthropic also publishes a free introduction-to-subagents course that pairs well with this article.

11. Closing Thoughts

This article opened with a single idea: use AI to automate structured work, not chaotic work. The eleven sections in between are what that looks like in practice.

So before you automate anything, define the system. Write the rules in CLAUDE.md. Generate the skills your team keeps retyping. Create the agents that do focused work. Wire up the orchestrator. Add the gates. And keep humans in the loop where judgement matters, not where typing matters.

A software factory is not a giant autonomous machine that builds your product overnight. It is a small set of files in your repository that turn one developer plus one AI into a controlled team. The agents are the asset. The factory is how you put them to work.

The New Way of Working

Section 8 introduced the idea that one engineer can ship a full vertical slice. Step back from the keyboard for a moment and look at what that means for the team, not just for one developer.

Software has always moved through handoffs. A product owner writes a story, a lead developer turns it into a specification, a backend engineer builds the API, a frontend engineer builds the UI, a payments specialist handles the integration. By the time the feature ships, four or five people have touched it, each waiting for the previous one to finish. Every handoff was time the work spent sitting still.

Figure 7: The old shape. Every arrow is a handoff. Every handoff is a wait.

The factory dissolves most of those handoffs because the expertise is no longer trapped inside the people. It is shared, in the form of agents.

A frontend engineer who has never written a Stripe webhook can still ship a feature that needs one, because the team's payments specialist has already built and tuned a payments-integration agent. A backend engineer who has never built a Recharts dashboard can ship a feature that needs one, because the frontend lead has built a dashboard-component-builder agent. The QA engineer's regression-suite-writer agent is available to everyone. The DevOps engineer's ci-pipeline-updater agent is available to everyone. The security engineer's auth-checker agent runs as part of every chain.

The result is that one engineer can finish a complete vertical slice on their own.

Figure 8: The new shape. Every engineer pulls from the same agent library. Specialists still exist, but their expertise lives in the agents they maintain, not in their availability for handoffs.

Look at what changed. The specialists are still there. The frontend lead still owns the design system. The payments specialist still owns the Stripe integration. The DevOps engineer still owns the CI pipeline. They still bring the taste and judgement that nobody else on the team has. What changed is that their expertise is now portable. It rides inside agents that anyone on the team can invoke.

This shift compounds in three ways:

Cycle time drops. A feature that used to wait for three engineers' time now waits for none. The chain runs end to end for one engineer. The PR opens the same day instead of the same week.

Specialists do their best work. Before, a senior payments engineer spent half their week unblocking other engineers' Stripe integrations. Now they spend that week improving the payments-integration agent itself. The leverage is much higher. One improvement to the agent benefits every feature the team ships from that point on.

Team scaling looks different. Before, hiring a tenth engineer added a tenth set of handoffs. Now, hiring a tenth engineer adds a tenth full-stack contributor who immediately benefits from every agent the existing nine have built. Onboarding speed increases. Coordination cost drops.

This is the broader shift the article is pointing at. The factory is not just a productivity trick for one developer. It is how an engineering team starts to look more like a community of full-stack contributors who share their expertise as code, and less like a relay race where every baton pass costs a day.

The teams that figure this out first will not be the ones with the largest headcount or the biggest AI budget. They will be the ones whose agent libraries reflect their team's collective taste, kept current, kept small, kept tight. The agents are the asset. The factory is how you put them to work.

A Short Note

The shape of this workflow will keep evolving as the tools evolve, and every team has its own way of working. What I have shared here is the smallest version that has actually held up under deadline pressure on real production work. It is not the final word. It is a starting point you can adapt to your team, your stack, and your taste.

If you build a version of this in your own team, I would love to hear what worked and what did not. The fastest way to improve a workflow is to read about other people's failure modes. Good luck building your factory.

Resources

Claude Code

Claude Code overview: code.claude.com/docs/en/overview
Subagents: code.claude.com/docs/en/sub-agents
Skills: docs.anthropic.com/en/docs/claude-code/slash-commands
Memory and CLAUDE.md: docs.anthropic.com/en/docs/claude-code/memory
Hooks reference: code.claude.com/docs/en/hooks
Hooks guide: code.claude.com/docs/en/hooks-guide

Other AI IDEs (the same patterns apply)

Cursor: cursor.com
Aider: aider.chat
Cline: cline.bot

Tools mentioned in the article

MCP documentation: modelcontextprotocol.io
Context7 (current docs plugin): context7.com
Nimbalyst (visual workspace for parallel Claude Code sessions): nimbalyst.com
Graphite (stacked PRs): graphite.dev
Sapling (stacked PRs): sapling-scm.com

How to Build an Autonomous OSINT Agent in Python Using Claude's Tool Use API

Tommaso Bertocchi — Fri, 15 May 2026 00:19:42 +0000

When I started studying OSINT, I always felt I was just putting random values into software without deeply understanding what I was doing. After months in the field, I realized I wasn't really investigating — I was just executing steps that follow a predictable pattern. That's exactly what an AI agent is good at. So I built one.

In this tutorial you'll learn how to set up OpenOSINT, an open-source Python OSINT framework with an AI agent at its core. You'll learn how Claude's native tool use API works, how to run autonomous investigations from the terminal using the interactive AI REPL, how to use the direct CLI for scripting, and how to expose all the tools to Claude Code or Claude Desktop via an MCP server.

What Is OSINT and Why Manual Workflows Break Down
What You'll Build
Prerequisites
How Claude's Tool Use API Works
How to Install OpenOSINT
How to Use the Interactive AI REPL
How to Run Individual Tools from the CLI
How to Set Up the MCP Server
How the Agent Loop Works Under the Hood
Project Architecture
Conclusion

What Is OSINT and Why Manual Workflows Break Down

Open Source Intelligence (OSINT) is the practice of collecting and analyzing information from publicly available sources. Security researchers use it during penetration tests. Journalists use it to verify identities and trace connections. Threat analysts use it to profile infrastructure.

A typical OSINT workflow looks like this:

You have a target email address
You run holehe to find which platforms that email is registered on
You notice a username in the output
You manually copy that username and run sherlock to search 300+ platforms
You switch to a browser to check HaveIBeenPwned
You open another tab for a WHOIS lookup
You take notes and repeat

Every tool is a silo. Every pivot is manual. The investigation logic — what to run next, what to chain, what the findings mean — lives entirely in your head.

When you close the terminal, it's gone.

This tutorial walks you through OpenOSINT, an open-source Python framework that replaces that fragmented workflow with an AI agent that chains tools autonomously, executes them against real binaries, and saves a structured Markdown report.

More importantly, you'll learn the core design principle that makes it trustworthy for security research: hallucination in tool results is structurally impossible.

What You'll Build

By the end of this tutorial, you'll have a working OSINT agent that you can use in three ways:

Interactive AI REPL — type a target in natural language and the agent decides what to run
Direct CLI — run individual tools without AI, useful for scripting
MCP Server — expose all tools to Claude Code or Claude Desktop

Here's what a real session looks like:

$ openosint
openosint ❯ investigate target@example.com

  → generate_dorks('target@example.com')
  → search_email('target@example.com')
  ✓ Found: Spotify, WordPress, Gravatar, Office365

  → search_breach('target@example.com')
  ✓ Found in 2 breaches: LinkedIn (2016), Adobe (2013)

  → search_username('target_handle')
  ✓ Found on: GitHub, Reddit, HackerNews, Twitter

  ╭──────────────── Report ────────────────╮
  │ ## Online Presence                     │
  │ Spotify · WordPress · Gravatar         │
  │                                        │
  │ ## Data Breaches                       │
  │ LinkedIn (2016) · Adobe (2013)         │
  ╰────────────────────────────────────────╯

  ✓ Report saved → reports/2026-05-11_report.md

The agent went from email → linked accounts → username pivot → cross-platform search with no human orchestration at any step.

Prerequisites

To follow this tutorial, you'll need:

Python 3.10 or later installed on your machine
Basic familiarity with the command line
An Anthropic API key — only required for the AI REPL, not for the CLI or MCP server
Git installed

You don't need prior experience with OSINT tools or the Anthropic SDK.

How Claude's Tool Use API Works

Before you dive into installation, it's worth understanding the mechanism that makes this framework trustworthy for security research.

Most AI applications that wrap external tools work by generating text that describes what a tool would return. That's a problem when accuracy matters — the model can hallucinate plausible-looking usernames, fake subdomains, or data breaches that never happened.

Claude's tool use API works differently. When the model decides it needs to call a tool, it does not generate the output. It stops and emits a structured tool_use block containing the tool name and the arguments it wants to pass.

Your code then runs the actual binary — holehe, sherlock, or whatever else — and sends the real output back as a tool_result. The model reads that real output and decides its next step.

Here's the flow:

User prompt
    ↓
Model decides to call search_email()
    ↓
Hard stop — model emits tool_use block
    ↓
Your code runs holehe against the real target
    ↓
Real output sent back as tool_result
    ↓
Model reads actual results, decides next step
    ↓
Repeat until investigation is complete

The model never generates tool output. It only ever reads it. If sherlock finds 12 profiles, those 12 URLs go back into the context verbatim. The model cannot add a 13th that doesn't exist.

This is not a prompting trick or a system prompt instruction. It is how the API is architected. Keep this in mind as you read through the agent loop code later in this tutorial.

How to Install OpenOSINT

Start by cloning the repository and installing the package:

git clone https://github.com/OpenOSINT/OpenOSINT.git
cd OpenOSINT
pip install -e .

Alternatively, if you just want to use the tool without modifying the source, install it directly from PyPI:

pip install openosint

Next, set your Anthropic API key. This is only required for the interactive AI REPL — the direct CLI and MCP server work without it:

export ANTHROPIC_API_KEY=sk-ant-...

How to Install the External Tool Dependencies

OpenOSINT wraps several standalone OSINT tools. Install the ones you plan to use:

pip install holehe            # email account enumeration
pip install sherlock-project  # username search across 300+ platforms
pip install sublist3r         # subdomain enumeration

For phone intelligence, phoneinfoga is a standalone binary. Download the release for your platform from its GitHub releases page and place it somewhere in your PATH.

How to Configure Optional API Keys

Two tools work at higher rate limits with optional API keys:

export HIBP_API_KEY=your_key    # required for breach checks via HaveIBeenPwned v3
export IPINFO_TOKEN=your_token  # optional — raises ipinfo.io rate limits

If a binary is missing or an API key is not configured, that specific tool returns a descriptive error string. All other tools continue to work normally.

How to Use the Interactive AI REPL

Run openosint with no arguments to start the AI-powered REPL. You can also use openosint shell — it's equivalent:

$ openosint
# or
$ openosint shell

If you prefer to pass the API key inline rather than via environment variable, use the --api-key flag:

$ openosint --api-key sk-ant-...

You'll get a prompt where you can type targets or questions in natural language:

openosint ❯ investigate target@example.com
openosint ❯ find all accounts for johndoe99
openosint ❯ what subdomains does example.com have?
openosint ❯ check if +14155552671 is a mobile number

The agent decides which tools to run based on your input. You don't need to specify which tools to use or in what order. If you type an email address, the agent will run email enumeration. If it finds a linked username, it may pivot and search that username across platforms.

Reports are saved automatically to the reports/ directory after every investigation that produces structured findings.

Here are the commands available inside the REPL:

Command	Description
`clear`	Reset the conversation memory
`save`	Manually save the last report
`tools`	Show available tools and their status
`config`	Show current configuration
`help`	List all commands
`exit` or Ctrl-D	Quit

How to Run Individual Tools from the CLI

If you want to run a single tool without the AI layer — for scripting, automation, or quick lookups — use the direct CLI:

# Email account enumeration (default timeout: 120s)
openosint email target@example.com

# With a custom timeout in seconds
openosint email target@example.com -t 60

# Username search across 300+ platforms (default timeout: 180s)
openosint username johndoe99

# Enable verbose output for debugging
openosint -v email target@example.com

The direct CLI doesn't require an Anthropic API key. It runs the underlying binary and prints the output to the terminal.

This mode is useful when you need predictable, scriptable behavior — for example, piping output into another tool or running automated checks.

How to Set Up the MCP Server

OpenOSINT also ships as a Model Context Protocol (MCP) server. This exposes all 9 tools to any MCP-compatible AI client.

How to Register with Claude Code

claude mcp add openosint python /absolute/path/to/OpenOSINT/openosint/mcp_server.py

Verify the registration worked:

claude mcp list

Once registered, you can drive investigations from the Claude Code prompt:

> Investigate target@example.com. If you find a linked username,
  trace it across other platforms and compile a full report.

How to Configure Claude Desktop

Add the following to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openosint": {
      "command": "python",
      "args": ["/absolute/path/to/OpenOSINT/openosint/mcp_server.py"]
    }
  }
}

Restart Claude Desktop after saving the file. The tools will appear in Claude's tool list.

The MCP server uses stdio transport and does not need a persistent background process. Claude Code or Claude Desktop starts it on demand.

How the Agent Loop Works Under the Hood

Here is a simplified version of the agent loop from openosint/agent.py:

import anthropic
import asyncio

client = anthropic.Anthropic()

async def run_investigation(user_prompt: str) -> str:
    messages = [{"role": "user", "content": user_prompt}]

    while True:
        response = client.messages.create(
            model="claude-...",   # model configured via --api-key / env var
            max_tokens=4096,
            tools=TOOL_SCHEMAS,   # JSON schemas for all 9 tools
            messages=messages
        )

        # Agent is done — extract and return the final report
        if response.stop_reason == "end_turn":
            return extract_text(response)

        # Agent needs a tool — run the real binary
        if response.stop_reason == "tool_use":
            tool_results = []

            for block in response.content:
                if block.type == "tool_use":
                    # Runs holehe, sherlock, etc. as real subprocesses
                    real_output = await execute_tool(block.name, block.input)

                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": real_output  # real output, never generated
                    })

            # Append assistant turn and real tool results to conversation
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})

There are a few important things to understand in this code.

The loop runs until stop_reason == "end_turn": The agent decides when it has gathered enough information to write the final report. It may call one tool or ten, depending on what it finds.
execute_tool() runs real subprocesses: It's a thin async wrapper around Python's asyncio.create_subprocess_exec() with a configurable timeout. There's no simulation and no mocked data at any point.
Conversation history is maintained across the entire loop: Each tool result goes back into messages, so the model always has full context of what it found when deciding what to run next.
Tool schemas are defined as JSON: Each tool has a name, description, and parameter schema. The model uses these to know what tools exist and what arguments they accept. Here's a simplified example for search_email:

{
    "name": "search_email",
    "description": (
        "Enumerates online services and social accounts "
        "associated with an email address using holehe."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "email": {
                "type": "string",
                "description": "Target email address"
            }
        },
        "required": ["email"]
    }
}

The same pattern applies to all 9 tools. The model reads these schemas at the start of every request and uses them to decide what's available and how to call it.

Project Architecture

The codebase is organized in five layers. The hard rule across the codebase is that no layer imports from a layer above it:

openosint/tools/        Core tools
                        Async wrappers around external binaries and APIs.
                        Stateless. No AI. No CLI. Pure functions.

openosint/agent.py      AI agent
                        Anthropic tool use loop.
                        Per-session conversation history.
                        Imports from tools/. Nothing imports from agent.py.

openosint/repl.py       Interactive REPL (prompt_toolkit + Rich)
openosint/mcp_server.py MCP server (stdio transport)
openosint/cli.py        CLI entry point

This separation makes each layer independently testable. The core tools are pure async functions that take a string and return a string — you can unit test them without touching the agent or the CLI.

It also means the AI layer is entirely optional. If you don't have an Anthropic API key, you use the CLI and bypass the agent. The MCP server also operates independently of the agent.

The 9 Available Tools

Tool	Backend	What it returns
`search_email`	holehe	Social accounts linked to an email
`search_username`	sherlock	Accounts across 300+ platforms
`search_breach`	HaveIBeenPwned v3	Breach names, dates, leaked data types
`search_whois`	python-whois	Registrant, registrar, creation/expiry
`search_ip`	ipinfo.io	Geolocation, ASN, hostname, org
`search_domain`	sublist3r	Subdomain enumeration
`generate_dorks`	built-in	12 targeted Google dork URLs, no network calls
`search_paste`	psbdmp.ws	Pastebin dump mentions
`search_phone`	phoneinfoga	Carrier, country, line type

Conclusion

In this tutorial, you learned how to set up and use OpenOSINT — a Python OSINT framework built on Claude's tool use API.

The key takeaway is the design principle: by using native tool use, the agent never generates tool output. It only reads real output from real binaries. This makes it suitable for security research where accuracy matters and hallucination isn't an acceptable failure mode.

To recap the three interfaces:

Run openosint for the interactive AI REPL — best for full investigations with automatic chaining
Run openosint email or openosint username for direct CLI access — best for scripting and automation
Register the MCP server in Claude Code or Claude Desktop to run investigations inside your existing AI environment

The full source code is available on GitHub under the MIT license. Contributions and issues are welcome.

Legal note: OpenOSINT is for authorized security research, penetration testing, and investigative journalism only. Users are solely responsible for compliance with applicable law, including GDPR, CCPA, and the CFAA. See the DISCLAIMER.md for the full notice.

How to Measure Your AI Citation Rate Across ChatGPT, Perplexity, and Claude

Chudi Nnorukam — Wed, 29 Apr 2026 17:02:15 +0000

Most sites think they're getting AI citations because their brand shows up in ChatGPT answers, but they're not. Visibility and citation are different numbers, and the gap between them is where the leak lives.

This started with chudi.dev getting brand mentions in ChatGPT answers while referral traffic from those answers stayed flat. Something was working and something wasn't, but the dashboards I had couldn't tell me which. So I built a way to look at the two signals separately and ran it across 7 sites.

The gap ran from 25 to 95 points. Ahrefs (DR 88 in Ahrefs Site Explorer at audit time) hit 100% visibility and 5% citation. A site with DR under 10 hit 15% citation by structuring its content as direct answers. Authority didn't predict citations in this 7-site sample. Structure did.

To make that concrete on the smallest site in the benchmark: chudi.dev was undiscovered three months ago (Domain Rating not yet assigned). Today it ranks at DR 25 with 671 verified Microsoft Copilot citations across the last 90 days, pulled from Bing Webmaster Tools' AI Performance tab. The structure work compounded faster than the authority work could. That climb is what this guide teaches you to repeat.

In this article, you'll measure both numbers in 30 minutes a month, using 20 queries across ChatGPT, Perplexity, and Claude. Then you'll read the gap to know which fix to run next. You need a site you publish to, a simple tracking table, and half an hour.

Quick note on the structure: This article opens with a counter-claim ("they're not"), not a definition. That's deliberate. AI engines preferentially surface posts that take a named position over posts that explain a concept.

The opening 100 words you just read are an example of the structural pattern this article teaches. Watch for one more callout like this one as you read.

Here's What We'll Cover:

What Counts as an AI Citation?
Prerequisites
Step 1: Pick Your 20 Seed Queries
Step 2: Run the Queries Across Three Engines
Step 3: Record Two Metrics Per Query
Step 4: Interpret the Gap
Step 5: Pick One Fix Based on Where You Leak
When to Re-measure
Automation at Scale
FAQ
What You Accomplished

What Counts as an "AI Citation"?

Two things are easy to confuse, and the distinction is the whole game.

Visibility is when an AI engine mentions your brand or your content topic in its answer, with or without a link. You appear in the conversation.

Citation is when that same engine links to a URL on your domain as a source. You appear in the sources panel.

Visibility is a brand problem. Citation is a structure problem. You can't fix one by working on the other, which is why measuring both separately is the load-bearing step.

Prerequisites

Before you start, make sure you have:

A live website with at least a handful of indexed posts you'd want AI engines to cite. Brand-new sites with no Google presence will return rows of zeros and teach you nothing.
Access to Google Search Console (free) or Ahrefs (free or paid tier) for query data. Bing Webmaster Tools also works if you publish there.
A spreadsheet, Notion table, or markdown file to record results. The tracking table at the end of Step 3 shows the exact shape.
Free-tier accounts for ChatGPT, Perplexity, and Claude. All three include web search on their free plans.
About 30 minutes for the first run. Re-measurements take 15 minutes once you have your seed query list locked in.

You don't need any paid tools, developer skills, or analytics integrations to run this.

Step 1: Pick Your 20 Seed Queries

Pull Queries from Your Top-Indexed Pages

Open Search Console or Ahrefs and export the queries you already rank on. This gives you a shortlist of topics your site has at least some authority on. Discard anything below position 20. AI engines rarely cite sources that Google can't surface either.

In Google Search Console, the path is Performance > Search results > Queries tab. Sort by Impressions descending, set the date range to the last 90 days, and export the table.

In Bing Webmaster Tools, the path is Search Performance > Keywords, with a similar export. Ahrefs Webmaster Tools (free) covers verified properties similarly under Site Explorer > Organic keywords.

Here is the top of my own export (chudi.dev, Google Search Console, last 90 days, sorted by impressions):

Query	Impressions	Position
unpdf	107	3.7
ai code verification	90	34.6
recommended pdf compression library node.js serverless vercel	84	13.3
how can i optimize my content to appear in perplexity and claude responses?	49	30.9
bug bounty automation framework	45	17.2
ai code validation	37	75.2
citation readiness	27	66.6
pdfjs-dist optionaldependencies canvas	26	11.2
aeo keywords	24	59.2
aeo seo	24	62.3

That is the raw material. The next step is shaping it into a balanced 20.

Mix Brand, Topic, and Long-tail Queries

Aim for this split:

4 branded queries that name your site or brand directly
10 topic queries that sit in your core content area without naming you
6 long-tail queries that describe a specific problem your content solves

The mix matters. Branded queries test whether engines associate your name with your topic. Topic queries test whether engines pull from your content unprompted. Long-tail queries test whether your specific angle beats the generic one.

Here is how I shaped my 20 from the chudi.dev export.

Branded (3, fewer than the recommended 4 because my branded volume is thin):

chudi ai
chude ai (a real typo of my name that picked up impressions)
claude code guide (adjacent: readers find my Claude Code content searching for this)

If your branded volume is stronger, push to 4 or 5. If yours is even thinner than mine, accept it and use the saved slots for topic queries. The bucket targets are guidance, not a contract.

Topic (12, bumped up to absorb the missing branded slot):

aeo keywords
aeo seo
aeo content
citation readiness
ai citation audit service
how do i allow chatgpt, claude, and perplexity to crawl my site?
optimize for perplexity ai responses
bug bounty automation
claude code token optimization
how to reduce token usage in claude ai
unpdf
recommended pdf compression library node.js serverless vercel

I picked these because each one has impressions in my GSC export AND maps to content I have actually published. Skip queries where your site can't plausibly answer.

Long-tail (5, specific-problem queries with sharper angles than the generic top result):

how can i optimize my content to appear in perplexity and claude responses?
what is the minimum viable seo optimization?
does site authority matter in ai citation rankings?
claude stuck on compacting conversation
claude losing context

A few picks I deliberately rejected:

wordpress schema plugin review: high impressions but my content doesn't actually answer it. A row of zeros teaches nothing.
intext:"seo" site:dev: an operator-syntax query, probably an SEO researcher poking around. Not real informational intent.
reply with the single word ok: a literal prompt-injection probe that landed in my GSC. Filter these from your seed list (and consider a WAF rule to flag them in your access logs).
chudi nnorukam adhd: branded but a personal post outside the AI-visibility cluster I'm trying to measure.

The 20th slot stayed empty. Running 19 strong queries beats padding to 20 with weak picks.

Step 2: Run the Queries Across Three Engines

Run each query through three engines. Do it in one session so cached state doesn't bleed between runs.

ChatGPT with Search Enabled

Open chatgpt.com and start a new chat. Click the + icon below the input box, then select Look something up. The placeholder text changes from "Ask anything" to "Search the web", which confirms search mode is active. Paste your query and send.

If you have custom GPTs or saved presets that override default behavior, use Temporary Chat instead (toggle in the top-right of the chat window). Temporary Chat ignores presets and gives you a clean search-mode response.

ChatGPT shows sources in two places: small source-card pills inline at the end of paragraphs grounded in web results, and a Sources button at the bottom of the response that opens a panel listing every URL the model referenced.

Perplexity

Open perplexity.ai, paste the query, and send. Perplexity always shows sources as numbered cards below the answer (and as inline pills next to each cited claim).

This is the easiest engine to score because the citation panel is unambiguous.

Claude with Web Search

Open claude.ai and start a new chat. Make sure web search is enabled. (Claude Pro includes it by default. On the free tier, look for the Search option in the input area's tool menu.) Paste the query and send.

Claude weaves citations as inline source-name pills next to each grounded claim. These small grey badges link to the cited URL. Scan the prose for your domain, or click any pill to confirm the source.

Step 3: Record Two Metrics Per Query

For each query, fill two columns in your tracking table: one for visibility, one for citation.

Visibility: Does the Engine Mention Your Brand Name?

If the engine says your brand name or links to your domain anywhere in the answer, mark visibility as 1. Otherwise 0.

Citation: Does the Engine Link to a URL on Your Domain?

If the engine's sources panel or inline citations contain a URL on your domain, mark citation as 1. Otherwise 0. A URL on your domain counts even if it isn't the exact page you wanted cited.

Your tracking table looks like this:

| Query                          | Engine     | Visibility | Citation |
|--------------------------------|------------|------------|----------|
| how to add schema to a blog    | ChatGPT    | 1          | 0        |
| how to add schema to a blog    | Perplexity | 1          | 1        |
| how to add schema to a blog    | Claude     | 0          | 0        |

At the end you have 60 rows (20 queries across 3 engines). Sum each column, divide by 60, and multiply by 100. Those are your visibility rate and your citation rate.

Structure callout #2: I'm using a markdown table here on purpose. AI engines extract data from tables more reliably than from prose-with-numbers because the engine can parse cell structure directly. If you write a guide and want it cited as the canonical source for a number, put the number in a table.

Step 4: Interpret the Gap

Subtract citation rate from visibility rate. The gap tells you where the leak is.

A small gap (under 10 points) means engines are both mentioning you and linking to you. You're well structured, and the next move is to grow overall visibility.

A large gap (25 points or more) means engines know your brand but aren't linking to your URLs. That's almost always a structure problem: canonical tags, schema, or answer-first format.

Across the 7-site benchmark I ran at chudi.dev, the gap ranged from 25 points on the best-structured site up to 95 points on the worst. Ahrefs scored 100% on visibility and only 5% on citation. That 95 point gap told me structure was the bottleneck, not reputation.

The full benchmark data lives here. The sample is small, so treat the gap range as directional rather than statistical.

Step 5: Pick One Fix Based on Where You Leak

Low Visibility: Brand Mention is the Fix

If your visibility rate is below 20%, engines don't associate your brand with your topic strongly enough. The fix is distribution, not structure.

Get your name into Reddit threads, YouTube comments, guest posts, and podcasts. AI engines pull heavily from community discussions, and Perplexity in particular sources a big chunk of its citations from Reddit.

High Visibility, Low Citation: Canonical and Schema is the Fix

If your visibility is high (40% or more) but your citation rate is low (under 15%), you have a structure problem. Common causes:

Canonical URLs point to cross-posts instead of your original post
BlogPosting or HowTo schema is missing or malformed
Key answers are buried below scrollable prose instead of surfaced in the first paragraph

Pick the most common issue across your top-cited queries and fix one thing at a time. One fix per measurement cycle tells you which lever moved the needle. If you fix three things at once, you learn which three worked together but not which one carried the weight.

For the setup that gets your site cite-able in the first place, see this guide on optimizing for Perplexity and ChatGPT.

When to Re-measure

Run the full 60-query sweep monthly. More often is noise. Less often misses algorithm changes that move your rates in either direction.

Re-measure sooner when:

You shipped a structural fix (schema, canonical, answer-first rewrite). Re-measure in 14 days to catch the delta.
You published a major new piece of content. Re-measure in 30 days to see whether it lifted your topical authority.
An AI engine shipped a documented update to its ranking system. Re-measure in 14 days to catch any regression.

Automation at Scale

Sixty manual checks a month is tolerable for one site. For teams running measurements across a portfolio, it breaks fast. citability.dev applies the same methodology across engines.

FAQ

How is AI citation rate different from referral traffic?

Citation rate measures whether AI engines link to you. Referral traffic measures whether users click those links.

You can have a high citation rate with low referral traffic if AI summaries answer the user's question without needing a click. Track both. They answer different questions about your content.

Should I measure across more than 3 engines?

You'll get diminishing returns past 3. ChatGPT, Perplexity, and Claude cover most user behavior on conversational queries. Add Google AI Overviews if SEO traffic is core to your business. Add Gemini if your audience is Google Workspace-heavy. Beyond 5 engines, the per-engine work outweighs the diagnostic value.

What if my visibility rate is 100% but my citation rate is also 100%?

That's an outlier and usually a query-selection problem. Branded queries that name your site or product inflate both metrics because the engine has to mention you to answer.

Re-run with topic queries only and compare. The rates that matter for diagnosis come from queries where you aren't naming yourself.

What You Accomplished

You now have a reproducible way to measure whether AI engines are citing your site, a diagnostic for reading the visibility-to-citation gap, and a one-fix-at-a-time cadence for improving it.

Run the sweep this week, pick your biggest gap, and fix one structural issue. Come back in 30 days and measure again. The numbers will tell you whether you moved.

How to Keep Human Experts Visible in Your AI-Assisted Codebase

Daniel Nwaneri — Mon, 13 Apr 2026 16:24:52 +0000

Six months ago, Stack Overflow processed 108,563 questions in a single month. By December 2025, that number had fallen to 3,862. A 78% collapse in two years.

The explanation everyone reaches for is that AI replaced it. That's partly true. But it misses the structural problem underneath: every time a developer asks Claude or ChatGPT to write code, the knowledge that shaped the answer disappears.

The GitHub discussion where someone spent two hours documenting why cursor-based pagination beats offset for live-updating datasets. The Stack Overflow answer from 2019 where one engineer, after a week of debugging, documented exactly why that approach fails under concurrent writes.

The AI consumed all of it. The humans who produced it got nothing — no citation in the codebase, no signal that their work mattered.

Over time, those people stopped contributing. Stack Overflow isn't dying because it's bad. It's dying because AI extracted its value and the feedback loop that kept humans contributing broke down.

This tutorial builds a tool that puts that loop back together. proof-of-contribution is a Claude Code skill that links every AI-generated artifact back to the human knowledge that inspired it — and surfaces exactly where the AI made choices with no human source at all.

I'll show you how to install proof-of-contribution, how to record your first provenance entry, how to use the spec-writer integration that makes Knowledge Gaps deterministic, and how to run poc.py verify — a static analyser that detects gaps without a single API call.

What You Will Build
Prerequisites
Quickstart in 5 Minutes
How the Tool Works
How to Install proof-of-contribution
How to Scaffold Your Project
How to Record Your First Provenance Entry
How to Use import-spec to Seed Knowledge Gaps
How to Trace Human Attribution
How to Verify with Static Analysis
How to Enable PR Enforcement
Where to Go Next

What You Will Build

proof-of-contribution is a Claude Code skill with a local CLI. Together they give you:

Provenance Blocks: Claude appends a structured attribution block to every generated artifact, listing the human sources that inspired it and flagging what it synthesized without any traceable source.
Knowledge Gaps: the parts of AI-generated code that have no human citation, surfaced before they become production incidents
poc.py trace: a CLI command that shows the full human attribution chain for any file in thirty seconds
poc.py import-spec: bridges proof-of-contribution with spec-writer, seeding knowledge gaps from your spec's assumptions list before the agent builds anything
poc.py verify: a static analyser that cross-checks your file's structure against seeded claims using Python's AST. Zero API calls. Exit code 0 means clean, exit code 1 means gaps found — wires directly into CI
A GitHub Action: optional PR enforcement that fails PRs missing attribution, for teams that want a standard

The complete source is at github.com/dannwaneri/proof-of-contribution.

Prerequisites

This is a beginner-to-intermediate tutorial. You should be comfortable with:

Command line basics: navigating directories, running scripts
Git: basic commits and PRs
Python 3.8 or higher: the CLI is pure Python with no dependencies

You will need:

Python installed: check with python --version or python3 --version
Git installed: check with git --version
Claude Code (or any agent that supports the Agent Skills standard — Cursor and Gemini CLI also work)

There's no database to install. No API keys. No paid services. The default storage is SQLite, which Python includes out of the box.

Quickstart in 5 Minutes

If you want to try the tool before reading the full tutorial, here are the five commands that take you from zero to your first gap detection:

Mac and Linux:

# 1. Install
mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/proof-of-contribution.git \
  ~/.claude/skills/proof-of-contribution

# 2. Scaffold your project (run in your repo root)
python ~/.claude/skills/proof-of-contribution/assets/scripts/poc_init.py

# 3. Record attribution for an AI-generated file
python poc.py add src/utils/parser.py

# 4. Detect gaps via static analysis
python poc.py verify src/utils/parser.py

# 5. See the full provenance chain
python poc.py trace src/utils/parser.py

Windows PowerShell:

# 1. Install
New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
git clone https://github.com/dannwaneri/proof-of-contribution.git `
  "$HOME\.claude\skills\proof-of-contribution"

# 2. Scaffold your project
python "$HOME\.claude\skills\proof-of-contribution\assets\scripts\poc_init.py"

# 3. Record attribution
python poc.py add src\utils\parser.py

# 4. Detect gaps
python poc.py verify src\utils\parser.py

# 5. See the full provenance chain
python poc.py trace src\utils\parser.py

That's the whole tool. The sections below walk through each step in detail with real terminal output at every stage.

How the Tool Works

Before you install anything, you need a clear mental model of what proof-of-contribution actually does — because the most important part isn't obvious.

The Archaeology Problem

Here's a scenario that happens on every team using AI-assisted development.

A developer joins. They go through six months of AI-generated codebase. They hit a bug in the pagination logic — cursor-based, unusual implementation, nobody remembers why it was built that way. The original developer has left.

Old answer: two days of archaeology. git blame points to a commit message that says "fix pagination." The commit before that says "implement pagination." Dead end.

With poc.py trace src/utils/paginator.py, that same developer sees this in thirty seconds:

Provenance trace: src/utils/paginator.py
────────────────────────────────────────────────────────────
  [HIGH]  @tannerlinsley on github
          Cursor pagination discussion
          https://github.com/TanStack/query/discussions/123
          Insight: cursor beats offset for live-updating datasets

Knowledge gaps (AI-synthesized, no human source):
  • Error retry strategy — no human source cited
  • Concurrent write handling — AI chose this arbitrarily

They now know where the pattern came from and — critically — which parts have no traceable human source. The concurrent write handling is where the bug lives. The AI made a choice nobody reviewed.

That's what this tool does. Not enforcement first. Archaeology first.

How Knowledge Gaps Are Detected

The obvious assumption is that Claude introspects and reports what it doesn't know. That assumption is wrong. LLMs hallucinate confidently. An AI that could reliably detect its own knowledge gaps wouldn't produce them.

The detection mechanism is a comparison, not introspection.

When you use spec-writer before building, it generates a spec with an explicit ## Assumptions to review section — every decision the AI is making that you didn't specify, each one impact-rated. That list is the contract.

When you run poc.py import-spec spec.md --artifact src/utils/paginator.py, those assumptions get seeded into the database as unresolved knowledge gaps. After the agent builds, poc.py trace shows which assumptions made it into code with no human source ever cited.

The AI isn't grading its own exam. The spec is the answer key.

poc.py verify takes this further. After the agent builds, it parses the file's actual structure using Python's built-in ast module — extracting every function definition, conditional branch, and return path. It cross-checks each one against the seeded claims. Any structural unit with no resolved claim surfaces as a deterministic Knowledge Gap, regardless of how confident the model was when it wrote the code.

How to Install proof-of-contribution

Mac and Linux

mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/proof-of-contribution.git \
  ~/.claude/skills/proof-of-contribution

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
git clone https://github.com/dannwaneri/proof-of-contribution.git `
  "$HOME\.claude\skills\proof-of-contribution"

That's the entire installation. No package to install, no configuration file to edit. The skill is a markdown file the agent reads. The CLI is a Python script that runs locally.

Verify the Install:

ls ~/.claude/skills/proof-of-contribution/

You should see SKILL.md, poc.py, assets/, and references/. If the directory is empty, the clone failed — check your internet connection and try again.

How to Scaffold Your Project

The scaffold script creates the database, config, CLI, and GitHub integration in your project root. Run it once per project.

Mac and Linux

cd /path/to/your/project
python ~/.claude/skills/proof-of-contribution/assets/scripts/poc_init.py

Windows PowerShell

cd C:\path\to\your\project
python "$HOME\.claude\skills\proof-of-contribution\assets\scripts\poc_init.py"

You should see output like this:

🔗 Proof of Contribution — init

  →  Project root: /path/to/your/project
  ✔  Created .poc/config.json
  ✔  Created .poc/.gitignore  (db excluded from git, config tracked)
  ✔  Created .poc/provenance.db  (SQLite — no extra infra needed)
  ✔  Created .github/PULL_REQUEST_TEMPLATE.md
  ✔  Created .github/workflows/poc-check.yml
  ✔  Created poc.py  (local CLI — includes import-spec command)
  ✔  Created .gitignore

✔ Proof of Contribution initialised for 'your-project'

This creates four things in your project:

your-project/
├── .poc/
│   ├── config.json      ← project settings (commit this)
│   ├── provenance.db    ← SQLite database (local only, gitignored)
│   └── .gitignore
├── .github/
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── workflows/
│       └── poc-check.yml
└── poc.py               ← your local CLI

.poc/ — the tool's local data directory. config.json stores project settings and is committed to git. provenance.db is the SQLite database where attribution records and knowledge gaps are stored — local only, gitignored.
poc.py — your local CLI, copied into the project root. Run python poc.py trace, python poc.py verify, and every other command directly without a global install.
.github/PULL_REQUEST_TEMPLATE.md — a PR template with the ## 🤖 AI Provenance section pre-filled. Developers fill it in when submitting PRs that contain AI-generated code.
.github/workflows/poc-check.yml — the optional GitHub Action for PR enforcement. Installed but dormant until you push the workflow file and enable it in your repo settings.

Windows note: if the scaffold fails with a UnicodeEncodeError, the emoji in the PR template is hitting a Windows encoding limit. Open assets/scripts/poc_init.py in a text editor and find every line ending with .write_text(...). Change each one to .write_text(..., encoding="utf-8"). Save and re-run.

Verify the Scaffold Worked

python poc.py report

Expected output:

Proof of Contribution Report
────────────────────────────────────────
  Artifacts tracked    : 0
  With provenance      : 0  (0%)
  Unresolved gaps      : 0
  Resolved claims      : 0
  Human experts        : 0

Empty database, clean state. You're ready.

How to Record Your First Provenance Entry

Before we dive in here, I just want to clear something up. Earlier, I described poc.py verify as detecting Knowledge Gaps automatically — and it does. But the static analyser can only tell you that a function has no human citation. It can't tell you which human source inspired it. That knowledge lives in your head, not in the code.

poc.py add is where you supply that context. After the agent builds a file, you record the human sources you actually drew on: the GitHub discussion you read before prompting, the Stack Overflow answer that shaped the approach. Those records become the attribution chain poc.py trace surfaces — and what closes the gaps poc.py verify flags.

verify finds the gaps. add fills them.

poc.py add records attribution for a file interactively. You can run it on any AI-generated file in your project.

python poc.py add src/utils/parser.py

You'll see a prompt:

Recording provenance for: src/utils/parser.py
(Press Ctrl+C to cancel)

  Human source URL (or Enter to finish):

Enter the URL of the human-authored source that inspired the code. This could be a GitHub discussion, a Stack Overflow answer, a documentation page, a blog post, or an RFC.

  Human source URL (or Enter to finish): https://github.com/TanStack/query/discussions/123
  Author handle: tannerlinsley
  Platform (github/stackoverflow/docs/other): github
  Source title: Cursor pagination discussion
  What specific insight came from this? cursor beats offset for live-updating datasets
  Confidence HIGH/MEDIUM/LOW [MEDIUM]: HIGH
  ✔ Recorded.

Add as many sources as apply. Press Enter on a blank URL when you're done.

  Human source URL (or Enter to finish): 
✔ Provenance saved. Run: python poc.py trace src/utils/parser.py

Check What You Recorded

python poc.py trace src/utils/parser.py

Provenance trace: src/utils/parser.py
────────────────────────────────────────────────────────────
  [HIGH]  @tannerlinsley on github
          Cursor pagination discussion
          https://github.com/TanStack/query/discussions/123
          Insight: cursor beats offset for live-updating datasets

No knowledge gaps — because you recorded a source. If the file had parts with no human source, they would appear below as gaps.

See All Experts in Your Graph

Every poc.py add call stores not just the URL but the author — their handle, platform, and the specific insight they contributed. Run it across enough files, and those authors accumulate into a knowledge graph: a local record of which human experts your codebase drew from, which files their knowledge shaped, and how many artifacts trace back to their work.

poc.py experts surfaces the top contributors. On a new project, it'll be one or two entries. On a mature codebase, it becomes a map of whose knowledge is load-bearing — the people you'd want to consult if that part of the code ever needed to change.

python poc.py experts

Top Human Experts in Knowledge Graph
──────────────────────────────────────────────────────
  @tannerlinsley            github          1 artifact(s)

How to Use import-spec to Seed Knowledge Gaps

This is the most important command in the tool. It connects proof-of-contribution with spec-writer and makes Knowledge Gaps deterministic.

When you use spec-writer before building a feature, it generates an ## Assumptions to review section — every implicit decision is impact-rated HIGH, MEDIUM, or LOW. The import-spec command reads that section and seeds those assumptions into the database as unresolved gaps before the agent writes a line of code.

After the agent builds, any assumption that made it into the implementation without a cited human source surfaces automatically in poc.py trace. You don't need to know which parts of the code are uncertain. The spec already told you.

Step 1 — Create a Test Spec

If you don't have a spec-writer output yet, create one manually to see how the import works.

Mac and Linux:

cat > test-spec.md << 'EOF'
## Assumptions to review

1. SQLite is sufficient for single-developer use — Impact: HIGH
   Correct this if: you need team-shared provenance

2. Filepath is the artifact identifier — Impact: MEDIUM
   Correct this if: you use content hashing instead

3. REST pattern for any future API — Impact: LOW
   Correct this if: you prefer GraphQL
EOF

Windows PowerShell:

python -c "
content = '''## Assumptions to review

1. SQLite is sufficient for single-developer use - Impact: HIGH
   Correct this if: you need team-shared provenance

2. Filepath is the artifact identifier - Impact: MEDIUM
   Correct this if: you use content hashing instead

3. REST pattern for any future API - Impact: LOW
   Correct this if: you prefer GraphQL'''
open('test-spec.md', 'w', encoding='utf-8').write(content)
print('test-spec.md created')
"

Windows note: don't use PowerShell's echo to create spec files. PowerShell saves files as UTF-16, which causes a UnicodeDecodeError when import-spec reads them. The python -c approach above writes UTF-8 correctly.

Step 2 — Import the Assumptions

python poc.py import-spec test-spec.md --artifact src/utils/parser.py

Spec assumptions imported — 3 Knowledge Gap(s) seeded
───────────────────────────────────────────────────────
  1. [HIGH] SQLite is sufficient for single-developer use
       Correct if: you need team-shared provenance
  2. [MEDIUM] Filepath is the artifact identifier
       Correct if: you use content hashing instead
  3. [LOW] REST pattern for any future API
       Correct if: you prefer GraphQL

  →  Bound to: src/utils/parser.py
  After the agent builds, run:
  python poc.py trace src/utils/parser.py
  python poc.py add src/utils/parser.py

Step 3 — Trace the Gaps

python poc.py trace src/utils/parser.py

Knowledge gaps (AI-synthesized, no human source):
  • REST pattern for any future API [Correct if: you prefer GraphQL]
  • SQLite is sufficient for single-developer use [Correct if: you need team-shared provenance]
  • Filepath is the artifact identifier [Correct if: you use content hashing instead]

  Resolve gaps: python poc.py add src/utils/parser.py

Three gaps, colour-coded by urgency. The HIGH-impact assumption — SQLite for single-developer use — appears in red. The LOW-impact one appears in green. When you run poc.py add and record a human source with an insight that overlaps the gap text, the gap auto-closes.

Preview Without Writing

python poc.py import-spec test-spec.md --dry-run

This parses the spec and prints what would be seeded without touching the database. This is useful before committing to an import.

Check the Overall Health

python poc.py report

Proof of Contribution Report
────────────────────────────────────────
  Artifacts tracked    : 1
  With provenance      : 0  (0%)
  Unresolved gaps      : 3
  Resolved claims      : 0
  Human experts        : 1
  ⚠ Less than 50% of artifacts have provenance records.
  ⚠ 3 unresolved Knowledge Gap(s).
    Run `poc.py trace ` to locate them.

How to Trace Human Attribution

poc.py trace is the command you'll use most. It shows the full human attribution chain for any file and lists any knowledge gaps — parts of the code with no traceable human source.

python poc.py trace src/utils/parser.py

A file with both attribution and gaps looks like this:

Provenance trace: src/utils/parser.py
────────────────────────────────────────────────────────────
  [HIGH]  @juliandeangelis on github
          Spec Driven Development methodology
          https://github.com/dannwaneri/spec-writer
          Insight: separate functional from technical spec

  [MEDIUM] @tannerlinsley on github
           Cursor pagination discussion
           https://github.com/TanStack/query/discussions/123
           Insight: cursor beats offset for live-updating datasets

Knowledge gaps (AI-synthesized, no human source):
  • Error retry strategy — no human source cited
  • CSV column ordering — AI chose this arbitrarily

  Resolve gaps: python poc.py add src/utils/parser.py

The human attribution section shows every cited source, colour-coded by confidence. The knowledge gaps section shows every assumption that shipped without a human citation — either seeded from a spec via import-spec, or flagged by Claude in the Provenance Block.

Resolving Gaps

Run poc.py add on any file with open gaps:

python poc.py add src/utils/parser.py

When you enter an insight that shares words with an open gap claim, the gap auto-closes. Run poc.py trace again to confirm it's resolved.

How to Verify with Static Analysis

poc.py verify is the command that closes the epistemic trust gap completely. It detects Knowledge Gaps by analysing the file's actual code structure — not by asking the AI what it doesn't know.

Run it after the agent builds, once you've seeded gaps with import-spec:

python poc.py verify src/utils/parser.py

Expected output:

Verify: src/utils/parser.py
────────────────────────────────────────────────────────────
  Structural units detected : 11
  Seeded claims             : 3
  Covered by cited source   : 2
  Deterministic gaps        : 1

Deterministic Knowledge Gaps (no human source):
  • function: handle_concurrent_writes (lines 47–61)
      Seeded assumption: concurrent write handling — AI chose this arbitrarily

  Resolve: python poc.py add src/utils/parser.py

The gap shown is not something Claude admitted. It's something the analyser found by comparing the file's function list against your seeded claims. The function handle_concurrent_writes exists in the code but has no resolved human citation in the database. That's the gap.

What the Exit Codes Mean

python poc.py verify src/utils/parser.py
echo $?   # Mac/Linux

python poc.py verify src/utils/parser.py
echo $LASTEXITCODE   # Windows PowerShell

Exit code 0 — no gaps, all detected units have cited sources
Exit code 1 — gaps found, resolve with poc.py add
Exit code 2 — file not found or unsupported language

Exit code 1 integrates directly into CI pipelines. Add poc.py verify to your GitHub Action or pre-commit hook and gaps block the build before they reach production.

Run it Without a Seeded Spec

If you haven't run import-spec first, verify still works — it falls back to structural analysis and surfaces every uncited function and branch as a gap:

python poc.py verify src/utils/parser.py

⚠ No spec imported — showing all uncited structural units.
  Run: python poc.py import-spec spec.md --artifact src/utils/parser.py
  for deterministic gap detection.

Deterministic Knowledge Gaps (no human source):
  • function: parse_query (lines 1–7)
  • branch: if not text (lines 2–3)
  • function: fetch_results (lines 9–12)
  ...

It's less precise than the spec-writer path — every structural unit shows rather than only the ones tied to named assumptions — but it's useful as a baseline on any file, new or old.

The `--strict` Flag

python poc.py verify src/utils/parser.py --strict

Strict mode flags every uncited structural unit as a gap even when claims are seeded. You can use it when you want zero tolerance: any function or branch without a resolved human source fails the check.

How to Enable PR Enforcement

Once poc.py trace has saved you real hours — not before — enable the GitHub Action. The distinction matters. Turning it on day one frames the tool as overhead. Turning it on after the team already finds value frames it as a standard.

git add .github/ .poc/config.json poc.py
git commit -m "chore: add proof-of-contribution"
git push

After that, every PR is checked for an ## 🤖 AI Provenance section. The scaffold already created the PR template with that section included. Developers fill it in naturally once they're already running poc.py trace locally — the template just asks them to record what they already know.

Developers who write fully human code opt out by adding 100% human-written anywhere in the PR body. The action skips the check automatically.

What the Action Checks

The action reads the PR description and looks for:

The ## 🤖 AI Provenance heading
At least one populated row in the attribution table

If the section is missing or the table is empty, the action fails and posts a comment explaining what to add. The comment includes a link to poc.py trace so the developer knows exactly where to look.

Where to Go Next

Use it with spec-writer on a Real Feature

The real value of import-spec is on actual features, not test specs. If you use spec-writer, the workflow is:

/spec-writer "your feature description"

Save the output to spec.md. Then:

python poc.py import-spec spec.md --artifact src/path/to/output.py

Build the feature with your agent. Then run poc.py trace to see which assumptions made it into code with no human source. Resolve the HIGH-impact gaps first — those are the ones that will cause production incidents.

Activate the Claude Code Skill

The SKILL.md file makes Claude automatically append a Provenance Block to every generated artifact when the skill is active. The block lists human sources Claude drew from and flags what it synthesized without any traceable source.

To activate it in Claude Code, the skill is already installed at ~/.claude/skills/proof-of-contribution/. Claude Code loads it automatically when you are in a project that has .poc/config.json.

A generated Provenance Block looks like this:

## PROOF OF CONTRIBUTION
Generated artifact: fetch_github_discussions()
Confidence: MEDIUM

## HUMAN SOURCES THAT INSPIRED THIS

[1] GitHub GraphQL API Documentation Team
    Source type: Official Docs
    URL: docs.github.com/en/graphql
    Contribution: cursor-based pagination pattern

[2] GitHub Community (multiple contributors)
    Source type: GitHub Discussions
    URL: github.com/community/community
    Contribution: "ghost" fallback for deleted accounts
                  surfaced in bug reports

## KNOWLEDGE GAPS (AI synthesized, no human cited)
- Error handling / retry logic
- Rate limit strategy

## RECOMMENDED HUMAN EXPERTS TO CONSULT
- github.com/octokit community for pagination

The Knowledge Gaps section is the part no other tool produces. It's where AI admits what it synthesized without a traceable human source — before that gap becomes a production incident.

Upgrade When You Outgrow SQLite

The default database is SQLite — local only, no infra required. When you need team sharing or graph queries, the references/ directory in the repo has migration guides:

Need	File
Team sharing a provenance DB	`references/relational-schema.md`
Graph traversal queries	`references/neo4j-implementation.md`
Semantic web / interoperability	`references/jsonld-schema.md`

Manual Tracking vs. proof-of-contribution

	Manual tracking	proof-of-contribution
Finding who wrote the code	Search Slack, ask the team, dig through commits	`poc.py trace` — thirty seconds
Knowing which parts the AI guessed	You don't, until it breaks in production	Knowledge Gaps section — surfaced before the code ships
Detecting gaps after the build	Code review, if someone notices	`poc.py verify` — static analysis, zero API calls
Enforcing attribution on PRs	Honor system	GitHub Action fails the PR if attribution is missing
Connecting to your spec	Copy-paste assumptions into comments manually	`poc.py import-spec` seeds them as tracked claims automatically
Infrastructure required	None (usually a spreadsheet or nothing)	None — SQLite, pure Python, no paid services

The tool doesn't replace code review. It gives code review the context it needs to catch the right things.

The archaeology scenario — two days tracing a bug through dead-end commit messages — takes thirty seconds with poc.py trace. The code still has gaps, and it always will. But now you know where they are.

Built by Daniel Nwaneri. The spec-writer skill that feeds import-spec is at github.com/dannwaneri/spec-writer. The full proof-of-contribution repo is at github.com/dannwaneri/proof-of-contribution.

How to Build Your Own Claude Code Skill

Daniel Nwaneri — Fri, 27 Mar 2026 20:47:26 +0000

Every developer eventually has a workflow they repeat. A way they write commit messages. A checklist they run before opening a pull request. A structure they follow when reviewing code. They do it manually, explain it to their agents in every session, and watch the agent interpret it differently each time.

Agent skills fix this. A skill is a markdown file that loads into Claude Code's context automatically when you need it. You write the workflow once. The agent follows it every time. And because skills follow an open standard, the same file works in Claude Code, GitHub Copilot, Cursor, and Gemini CLI.

This tutorial shows you how to build a skill from scratch. You will build a commit-message-writer — a skill that reads your staged changes and generates a structured commit message following the Conventional Commits standard. By the end, you will have a working skill installed and ready to use, and you will understand the structure well enough to build any skill you need.

What an Agent Skill Is
How to Choose What to Build
How to Structure Your Skill
How to Write the Description
How to Write the Instructions
How to Build the commit-message-writer Skill
How to Install and Test Your Skill
How to Improve Your Skill Over Time
Where to Go Next

What an Agent Skill Is

A skill is a folder containing a SKILL.md file. That file has two parts: a YAML frontmatter block at the top, and a markdown body below it.

my-skill/
└── SKILL.md

The frontmatter tells the agent what the skill is called and when to use it. The body tells the agent what to do when it loads the skill. Here is the minimal structure:

---
name: my-skill
description: What this skill does and when to use it.
---
 
# My Skill
 
Instructions for the agent go here.

When you invoke a skill — either explicitly with /skill-name or by describing what you want — the agent reads the SKILL.md body and follows the instructions inside it. The frontmatter never reaches the agent's instructions. It's metadata the skill system uses to decide whether to load the skill at all.

How the Agent Decides to Load a Skill

This is the most important thing to understand before you write your first skill: the agent decides whether to load your skill based entirely on the description field.

Skills appear in Claude Code's context as a list of names and descriptions. When you make a request, the agent scans that list and loads any skill whose description matches what you're asking for. If the description is vague, the skill won't load when you need it. If the description is too narrow, it won't load for variations of the same request.

The instructions in the body only matter after the skill loads. Getting the description right is what determines whether the skill loads at all.

What Skills Are Not

Skills are instruction files. They cannot run code on their own — but they can instruct the agent to run code using its existing tools. They are not plugins, extensions, or packages. They have no runtime. They are markdown files the agent reads, like a recipe a chef follows.

How to Choose What to Build

The best skills share three properties.

They encode a repeatable workflow. If you do something differently every time, a skill won't help. If you follow the same steps every session — even if you explain them differently each time — that's a skill candidate.
They have a clear trigger. You should be able to finish the sentence "I need this skill when I want to...". If you can't finish that sentence in one clause, the workflow isn't scoped enough for a skill.
They produce a consistent output format. Skills that output in a fixed structure — a commit message, a code review, a spec — are easier to build and test than skills that produce open-ended prose.

Good candidates: commit messages, pull request descriptions, code reviews, changelog entries. Bad candidates: "help me think through this", "make this better" — too open-ended to encode in a skill.

For this tutorial, commit message generation is the right scope. The trigger is obvious (you want to commit), the workflow is defined (read staged changes, apply Conventional Commits format), and the output is structured (a commit message with a specific shape).

How to Structure Your Skill

Every skill starts as a single folder with a single file:

commit-message-writer/
└── SKILL.md

As skills grow, they can include additional files the agent loads as needed:

commit-message-writer/
├── SKILL.md          ← always loaded when skill triggers
└── references/
    └── examples.md   ← loaded only when the agent needs examples

The SKILL.md body should stay under 500 lines. If your instructions are growing beyond that, move supporting detail into a references/ subfolder and tell the agent when to read those files. This keeps the skill lean — the agent only loads what it needs.

For this tutorial, a single SKILL.md is enough.

How to Write the Description

The description field is the trigger condition. It determines when your skill loads and when it doesn't. Most skills fail not because the instructions are wrong, but because the description doesn't match how people actually ask for help.

Here is a weak description:

description: Generates commit messages.

This will undertrigger. "Generate a commit message" will load it. "Write a commit for my changes" probably won't. "Summarize my staged diff" definitely won't — even though all three are asking for the same thing.

Here is a stronger description:

description: Generates structured commit messages following the Conventional Commits standard. Use when you want to commit your changes and need a well-formatted message. Triggers on "write a commit message", "commit my changes", "summarize my staged diff", "what should my commit say", or any request to describe or document code changes for version control.

The pattern is: what the skill does + when to use it + specific trigger phrases. The trigger phrases cover the different ways a developer might ask for the same thing.

Two rules for descriptions:

Be specific about the output. "Generates commit messages" is vague. "Generates structured commit messages following the Conventional Commits standard" tells the agent and the user exactly what they'll get.

Be slightly pushy. The agent has a natural tendency to undertrigger skills — to handle requests itself rather than loading a skill. A description that explicitly lists trigger phrases counteracts this. You are not being redundant. You are training the trigger.

How to Write the Instructions

The body of SKILL.md is where you define what the agent does when the skill loads. Good instructions follow two principles.

Generate first, clarify second. The agent should produce output immediately rather than asking clarifying questions. If it needs to make assumptions, it should make them and flag them — not ask. Asking questions before producing output adds friction and loses the benefit of having a skill at all.

Define the output format explicitly. Don't say "write a good commit message." Say exactly what the structure is, what fields are required, what the character limits are. The more specific the output format, the more consistent the results.

Here is what weak instructions look like:

# Commit Message Writer
 
Look at the staged changes and write a commit message that describes what changed.

That will produce different results every time — different formats, different lengths, different conventions. It's not a skill. It's a prompt.

Here is what strong instructions look like:

# Commit Message Writer
 
Read the staged diff using `git diff --staged`. Generate a commit message
following the Conventional Commits standard.
 
Output format:
type(scope): short description under 72 characters
 
Body (if changes are non-trivial):
- What changed and why, not how
- One bullet per logical change
 
Footer (if applicable):
BREAKING CHANGE: description
Closes #issue-number

The agent knows exactly what to produce. The output will be consistent across sessions, across projects, and across agents that support the standard.

How to Build the `commit-message-writer` Skill

Now build it. Create the skill directory:

mkdir -p ~/.claude/skills/commit-message-writer

On Windows PowerShell:

Note: PowerShell uses backtick (`) for line continuation, not backslash.

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\commit-message-writer"

Create the SKILL.md file inside that directory. Here is the complete content:

---
name: commit-message-writer
description: Generates structured commit messages following the Conventional Commits
  standard. Use when you want to commit your changes and need a well-formatted message.
  Triggers on "write a commit message", "commit my changes", "summarize my staged
  diff", "what should my commit say", or any request to describe or document staged
  changes for version control.
---
 
# commit-message-writer
 
You generate structured commit messages from staged git changes.
 
## How to invoke
 
Run `git diff --staged` to read the staged changes. If nothing is staged, tell the
user and suggest they run `git add` first.
 
Generate first. Do not ask clarifying questions before producing the commit message.
If you need to make assumptions about scope or type, make them and note them after
the output.
 
## Output format
 
~~~
type(scope): short description
 
[body — optional, include if changes are non-trivial]
 
[footer — optional]
~~~
 
**Type** — choose one:
- `feat` — a new feature
- `fix` — a bug fix
- `docs` — documentation changes only
- `refactor` — code change that neither fixes a bug nor adds a feature
- `test` — adding or updating tests
- `chore` — build process, tooling, or dependency updates
 
**Scope** — the module, file, or area affected. Use the directory name or component
name. Omit if the change spans the entire codebase.
 
**Short description** — imperative mood, under 72 characters, no period at the end.
"Add user authentication" not "Added user authentication" or "Adds user authentication."
 
**Body** — what changed and why, not how. One bullet per logical change. Skip if the
short description is self-explanatory.
 
**Footer** — include `BREAKING CHANGE:` if the commit breaks backward compatibility.
Include `Closes #N` if it resolves a GitHub issue.
 
## Quality rules
 
- Never use "updated", "changed", or "modified" in the short description — be specific
- Never write "various improvements" or "misc fixes" — name what improved
- If more than three files changed across unrelated concerns, flag it:
  "These changes may be better split into separate commits: [list concerns]"
- The short description must be under 72 characters — count before outputting
 
## Example output
 
Input: staged changes adding a rate limiter to an API endpoint
 
~~~
feat(api): add rate limiting to /query endpoint
 
- Limits requests to 100 per minute per IP using Cloudflare's rate limit binding
- Returns 429 with Retry-After header when limit is exceeded
- Adds rate limit configuration to wrangler.toml
 
Closes #47
~~~

Save that file. The skill is built.

How to Install and Test Your Skill

Verify the File Exists

cat ~/.claude/skills/commit-message-writer/SKILL.md

You should see the full SKILL.md content. If you get an error, check the directory path.

Test the Skill

Open Claude Code in any git repository that has staged changes. Type:

/commit-message-writer

The agent will read your staged diff and produce a commit message following the format you defined.

You can also trigger it naturally:

write a commit message for my staged changes

what should my commit say

summarize my diff for git

All three should load the skill and produce a structured commit message. If the skill doesn't trigger on natural language requests, the description needs more trigger phrases — see the improvement section below.

Test Edge Cases

Test these cases before relying on the skill in production:

# Stage nothing, then ask for a commit message
git add -p  # stage nothing
# In Claude Code: "write a commit message"
# Expected: skill tells you nothing is staged and suggests git add

# Stage changes across unrelated files
git add src/api.ts src/styles.css README.md
# In Claude Code: "write a commit message"  
# Expected: skill flags that commits may be better split

How to Improve Your Skill Over Time

The first version of any skill is a draft. You improve it by observing where it produces inconsistent or wrong output, then updating the instructions.

When the Skill Undertriggers

If you type "summarize my changes for git" and the skill doesn't load, add that phrase to the description's trigger list:

description: ... Triggers on "write a commit message", "commit my changes",
  "summarize my staged diff", "summarize my changes for git", ...

The description is your primary lever for fixing triggering problems.

When the Output Format Drifts

If the agent starts producing commit messages that don't match your format — wrong type, missing scope, body in the wrong style — the instructions need to be more explicit. Add a concrete example that shows the failure and the correct output:

## Common mistakes to avoid
 
Wrong: "Updated the authentication flow"
Right: "refactor(auth): simplify token validation logic"
 
Wrong: "Fixed bugs"
Right: "fix(api): handle null response from upstream service"

Concrete counterexamples are more effective than abstract rules.

When the Scope Grows

If you find yourself wanting the skill to handle related tasks — reviewing commit messages, generating changelogs, writing PR descriptions — resist the urge to add everything to one skill. Build separate skills. Each skill should do one thing well. The Agent Skills standard is designed for composition, not for monolithic instructions.

Where to Go Next

The commit-message-writer covers the core pattern. The same structure works for any repeatable workflow.

Pull request descriptions follow the same shape — read the diff, apply a structure, produce consistent output. The trigger phrases are different ("write a PR description", "summarize my branch for review") and the output format adds sections for motivation and testing, but the SKILL.md structure is identical.

Code review checklists work well as skills when your team has a standard review process. The trigger is "review this code" or "check this PR", and the instructions encode whatever your team actually checks — security concerns, test coverage, naming conventions.

The commit-message-writer is the simplest skill architecture — instructions only. As your skills grow more specialized, two other patterns become useful.

The first adds a references/ directory: the voice-humanizer skill loads a CORPUS.md file containing the author's published writing, which the agent reads when it needs to check output against a specific style. The second adds quality rules and structured output formats that make results stricter and more consistent — that's the pattern spec-writer uses to surface assumptions inline. Each is the same SKILL.md structure at a different level of complexity.

Start with instructions only. Add references when the agent needs external context. Add output format rules when consistency matters more than flexibility.

The Agent Skills standard is supported in Claude Code, GitHub Copilot in VS Code, Cursor, and Gemini CLI. A skill you build once installs across all of them. The install path differs by agent:

Agent	Skills directory
Claude Code	`~/.claude/skills/`
GitHub Copilot	`~/.copilot/skills/` or `.github/skills/`
Cursor	`~/.cursor/skills/`
Gemini CLI	`~/.gemini/skills/`

The SKILL.md format is the same across all of them.

The commit-message-writer you just built is a working skill. The next one will take less time. By the third, you will start seeing workflows you repeat and immediately think: that should be a skill.

That's the point.

How to Apply GAN Architecture to Multi-Agent Code Generation

Christopher Galliart — Wed, 25 Mar 2026 16:49:56 +0000

Ask an AI coding agent to build a feature and it will probably do a decent job. Ask it to review its own work and it will tell you everything looks great.

This is the fundamental problem with single-pass AI code generation: the same context that created the code is the one evaluating it. There's no adversarial pressure. No second opinion. No fresh eyes.

What if you could structure the work so that separate agents generate and critique each other in iterative loops, the way a generator and discriminator improve each other in a GAN? The code that reaches you has already survived an argument between agents who disagreed about whether it was good enough.

This article walks through why that pattern works, how to build it, and when it is (and is not) worth the extra tokens. The concrete example is an open source project called Claude Forge, but the ideas are framework-agnostic. Anything that supports subagent spawning with fresh context windows can implement this pattern.

The Single-Pass Problem
What the Ecosystem Is Solving
The GAN Pattern Applied to Code
Why Rhetorical Questions Outperform Direct Instructions
Feedback as Filesystem
The Zero-Context Engineer
Phase-0: Immutable Conventions
Convergence Design: Knowing When to Stop
Ground Truth Documents and the Pipeline
What the Adversarial Loop Actually Catches
Honest Trade-offs
When to Use This (And When Not To)
Getting Started

Prerequisites

Familiarity with Claude Code or a similar AI coding agent
A working installation of Claude Code (for the hands-on sections)
Basic understanding of how LLM context windows work
Git installed and configured

No machine learning background is required. The GAN concepts are explained from first principles where they appear.

The Single-Pass Problem

The AI generates code in one pass. If it hallucinates a file path, misunderstands the architecture, or writes tests that don't actually test anything, you catch it during review. Or worse, you don't.

This isn't a hypothetical. Anyone who has used AI coding agents at scale has seen placeholder tests like expect(true).toBe(true), phantom dependencies where Phase 2 assumes a model that Phase 1 never creates, and instructions so ambiguous that two valid interpretations exist. These aren't rare edge cases. They're the predictable failure mode of single-pass generation.

The problem compounds with task complexity. A simple utility function generates fine in one pass. An auth middleware with token refresh, error handling, rate limiting, and logging across multiple files? The agent starts cutting corners, because the entire generation happened inside one context window that is simultaneously tracking the plan, the code, the tests, and the growing weight of its own prior reasoning.

What the Ecosystem Is Solving

There is a growing ecosystem of frameworks tackling different aspects of this problem. They each bring real contributions worth understanding.

Superpowers focuses on development methodology. It uses subagent-driven development, TDD enforcement, and multi-stage review. The framework generates a design spec, then an implementation plan, then dispatches subagents to execute. Review subagents check the output, and if they find issues, the implementer revises and gets re-reviewed until approved.

Get Shit Done (GSD) focuses on context engineering. Its key insight is fighting context window degradation through fresh 200k subagent contexts, parallel wave execution, and XML-structured plans. A JavaScript CLI handles the deterministic work (tracking progress, dependency ordering, context budgets) so the LLM never wastes tokens on bookkeeping it would do unreliably anyway.

Both frameworks share a crucial design decision: fresh context windows. When an agent has been reasoning for 100k tokens, its attention degrades. By spawning subagents with clean 200k contexts, these frameworks sidestep the "context rot" problem that plagues long-running agent sessions.

Where these frameworks diverge is in how they handle quality assurance. GSD relies on mechanical verification: lint, test, type-check, and auto-fix retries if the checks fail. There is no agent reading another agent's code to assess whether it matches the spec's intent. The "review" is whether npm run test passes.

Superpowers does have agent-to-agent review with iterative loops. But the review is enforced by in-context instructions, which means the agent can (and frequently does) rationalize skipping the review step to save tokens.

This is a known issue in the project. When review enforcement lives inside the same prompt that the model is also using to make efficiency decisions, the model sometimes decides that review is not worth the cost.

The adversarial GAN pattern addresses this differently. Instead of asking an agent to review its own work or trusting in-context instructions to enforce review, it structures the pipeline so that review is architecturally mandatory. The reviewer is a separate agent that cannot be skipped, because the orchestrator will not advance the pipeline without the reviewer's signal. The reviewer cannot modify source code, only feedback.md. The generator cannot approve its own output. Role separation is enforced by the system, not suggested by the prompt.

The GAN Pattern Applied to Code

In machine learning, GANs pit two networks against each other: a generator creates content, a discriminator evaluates it, and the feedback loop between them drives both to improve. The generator gets better at producing realistic output. The discriminator gets better at finding flaws. The adversarial tension is what produces quality.

Applied to software development, this creates two stacked feedback loops:

Each role runs as a separate agent with its own fresh context window. The Plan Reviewer has never seen the Planner's reasoning process. It only sees the output. The Code Reviewer has never seen the Implementer's struggles. It only sees the code.

This separation fundamentally changes what the reviewer can catch. When a reviewer shares context with the generator, it inherits the generator's blind spots. When a reviewer starts fresh, it reads the plan the way an actual engineer would: with no assumptions about what the author "meant" versus what they wrote.

The adversarial Plan Reviewer doesn't just verify structure. It actively tries to break the plan:

Deadlock search: Is there a task ordering that would deadlock the implementer? (Task 3 needs the output of Task 5.)
False positive verification: Could any verification checklist pass even with a wrong implementation?
Ambiguity search: Are there instructions that could be interpreted two valid ways?
Missing context: Could the implementer get stuck because a task assumes knowledge not provided?

This is where the GAN analogy is most literal. The discriminator isn't checking if the plan looks good. It's trying to find failure modes.

Why Rhetorical Questions Outperform Direct Instructions

When a reviewer finds an issue, there are two ways to communicate it.

Direct instruction:

Fix line 45: the error handler returns 500 instead of 401 for invalid tokens.

Rhetorical question:

Consider: The test test_invalid_token_rejection expects a 401 status code.
Are you returning the correct HTTP status in your error handling?

Think about: In src/auth/middleware.js:45, what happens when the token is
invalid? Is the error properly caught?

Reflect: Look at how other middleware handles auth errors. Are you following
the same pattern?

The direct instruction produces a mechanical edit. The agent changes line 45 and moves on. The rhetorical question produces a deeper investigation. The agent re-examines the surrounding code, considers the pattern used elsewhere, and is more likely to find the root cause rather than just patching the symptom.

This maps to how the underlying models work. When given an explicit instruction, the model follows it literally. When guided to reason about a problem, it activates a broader search through its understanding of the codebase. The fix addresses related issues that a mechanical edit would miss.

Reviewer prompts structured around "Consider," "Think about," and "Reflect" prefixes consistently produce better fixes than "Fix" or "Change" directives. The implementer agent receives these as feedback in feedback.md and addresses them in the next iteration of the GAN loop.

Feedback as Filesystem

Most agent orchestration systems rely on some form of message passing: API calls, databases, queue systems, in-memory state. These all work, but they introduce infrastructure dependencies and make the agent conversation opaque after the fact.

An alternative: use the filesystem as the message bus and git as the orchestration layer.

All agent communication flows through feedback.md, a structured markdown file with two sections:

## Active Feedback (OPEN)

### FB-001: Auth middleware missing rate limiting
- **Status:** OPEN
- **Source:** Plan Reviewer
- **Phase:** 1
- **Detail:** The plan specifies JWT validation but does not address rate
  limiting for failed auth attempts. Consider: what happens if an attacker
  brute-forces tokens?

## Resolved Feedback

### FB-000: Missing error codes in API spec
- **Status:** RESOLVED
- **Resolution:** Added error code table to Phase-0 conventions

This design has several properties that matter in practice:

Full audit trail: Every piece of feedback, every resolution, every signal is committed to git alongside the code it produced. When you want to understand why the auth middleware was designed a certain way, the conversation that shaped it is right there in the commit history.

State recovery: If a pipeline gets interrupted (token limits, network issues, you need to step away), resuming is trivial. The orchestrator re-reads feedback.md and git log, determines what stage the pipeline reached, and picks up where it left off. No cloud infrastructure, no database, no queue. Just files.

Transparency: You can read the agent conversation in your editor. You can see exactly what the reviewer flagged, exactly how the implementer responded, and whether the resolution actually addressed the concern.

Agents communicate through structured signals routed by the orchestrator:

PLAN_COMPLETE / REVISION_REQUIRED / PLAN_APPROVED (plan GAN loop)
IMPLEMENTATION_COMPLETE / CHANGES_REQUESTED / PHASE_APPROVED (code GAN loop)
GO / NO-GO (final gate)
VERIFIED / UNVERIFIED (post-remediation verification)

Each signal marks a state transition. The orchestrator reads the signal, determines the next agent to invoke, and passes it the relevant context. The orchestrator itself is a Claude Code session, but the agents it spawns are fresh subagents with clean context windows.

The Zero-Context Engineer

One of the most effective constraints in the system is the "zero-context engineer" framing. The Planner writes every plan as if it will be executed by an engineer who:

Is skilled but has zero context on the codebase
Is unfamiliar with the toolset and problem domain
Will follow instructions precisely
Will not infer missing details. If it's not in the plan, it won't happen.

This constraint forces explicit instructions. No "add the usual auth middleware." Instead: which library, which pattern, which error codes, which files to create, which existing files to modify, and how to verify the result.

The Plan Reviewer then simulates this zero-context experience: "If I knew nothing about this codebase, could I follow these instructions and produce a working result?"

This framing catches a class of failures that are invisible to someone with context. The author of the plan knows what they meant. The zero-context reviewer only knows what is written. The gap between intention and specification is where bugs live.

Phase-0: Immutable Conventions

Every pipeline run starts with a Phase-0 document that defines immutable rules: tech stack, testing strategy, deployment approach, shared patterns, commit format. Every subsequent phase inherits from Phase-0. Every reviewer checks against it.

This solves a common multi-agent problem: drift. Without a shared source of truth, Agent A might decide to use Jest while Agent B sets up Vitest. Agent C might use a different error handling pattern than Agent D. Phase-0 prevents this by establishing conventions before any code is written.

The conventions aren't suggestions. They're constraints that every agent in the pipeline must respect, and every reviewer must verify against.

Convergence Design: Knowing When to Stop

An adversarial loop without exit conditions is just two agents arguing forever. The convergence design has three mechanisms:

Iteration caps: Each GAN loop (plan review, code review) runs a maximum of 3 iterations. If the planner and reviewer cannot converge in 3 rounds, the issue requires human judgment, not more machine cycles.

Signal protocol: The structured signals (PLAN_APPROVED, GO, NO-GO) are explicit state transitions, not suggestions. When the final reviewer issues NO-GO, the pipeline rolls back the phase. There is no "let's try one more time." The rollback is automatic.

Token budget: Each phase targets roughly 50k tokens with a 75k hard ceiling. This prevents any single phase from consuming the entire context budget and ensures the orchestrator retains enough headroom to manage the pipeline.

These caps exist because adversarial loops have a cost curve. The first iteration catches major issues. The second iteration catches subtle issues. The third iteration catches edge cases. A fourth iteration almost never catches anything the previous three missed, but it costs just as many tokens. Three iterations hit the sweet spot between thoroughness and efficiency.

Ground Truth Documents and the Pipeline

The adversarial pipeline doesn't start from a vague prompt. Every workflow begins with an intake skill that produces a structured ground truth document. The pipeline then runs from that document, not from the original user request.

Brainstorm: Turning Ideas into Specs

The /brainstorm skill is the feature creation workflow. Given a feature idea, it first explores the codebase to understand the existing architecture, tech stack, and patterns. Then it asks 5-15 clarifying questions designed to front-load high-impact decisions:

The codebase uses DynamoDB for storage. For this feature's data, should we:

A) Add tables to the existing DynamoDB setup
B) Use a different storage approach (e.g., S3 for documents)
C) Both - DynamoDB for metadata, S3 for content

These aren't generic questions. They're grounded in what the skill found during codebase exploration. The skill identifies the real decision points for this specific project and surfaces them before any planning or code generation begins.

The output is brainstorm.md, a structured design spec. Not a conversation transcript, but a distilled set of decisions that the Planner agent can consume cold. This document becomes the single source of truth for the entire pipeline run.

Repository Evaluation, Health, and Documentation Audits

The same ground-truth-document pattern applies to the audit workflows:

/repo-eval spawns three evaluator agents in parallel (the Pragmatist, the Oncall Engineer, the Team Lead), each scoring the codebase from a different lens across 12 pillars. The output is eval.md.
/repo-health runs a technical debt auditor across four vectors (architectural, structural, operational, hygiene). The output is health-audit.md.
/doc-health runs six detection phases comparing documentation against actual code. The output is doc-audit.md.
/audit runs any combination of the above. It asks scoping questions once, then spawns up to 5 agents in parallel (3 evaluators + health auditor + doc auditor). All intake documents land in one directory.

Each of these intake skills produces a read-only assessment. The agents doing the evaluation never modify the codebase. They only write their findings into the intake document.

The Pipeline Runs from Ground Truth

The /pipeline skill reads whatever intake documents exist and runs the adversarial GAN loop from them. For a feature, it reads brainstorm.md. For an audit, it reads whichever combination of eval.md, health-audit.md, and doc-audit.md are present.

When multiple intake documents exist (from a combined audit), the Planner reads all findings together and consolidates overlapping concerns into a single unified plan. Phases are tagged by implementer type and ordered:

[HYGIENIST] phases first, subtractive cleanup (deleting dead code, simplifying over-abstractions)
[IMPLEMENTER] phases next, structural fixes on clean code
[FORTIFIER] phases next, locking in the clean state (linting, CI checks, git hooks)
[DOC-ENGINEER] phases last, documentation reflecting final code

The ordering matters. You don't want the implementer building on top of dead code that the hygienist would have removed. You don't want the doc-engineer documenting an API that the fortifier is about to add validation to.

This separation between intake and pipeline is deliberate. The intake skills are exploratory and interactive. They ask questions, explore the codebase, and produce a document. The pipeline is autonomous. It reads the document and runs through the adversarial loops with minimal human intervention, stopping only at explicit decision points.

What the Adversarial Loop Actually Catches

In practice, the adversarial loops catch issues that single-pass generation consistently misses.

Plan Review catches:

Hallucinated file paths (the Planner says "modify" a file that doesn't exist)
Phantom dependencies (Phase 2 assumes a model that Phase 1 never creates)
Test strategies that require live cloud resources instead of mocks
Ambiguous instructions that a zero-context engineer could misinterpret
Deadlocks in task ordering (Task 3 needs the output of Task 5)

Code Review catches:

Placeholder tests (expect(true).toBe(true))
Deviations from Phase-0 architecture conventions
Missing error path coverage (only happy paths tested)
Hardcoded secrets and input validation gaps

Verification catches:

Remediation targets that weren't actually addressed
Regressions introduced during fixes
Partial fixes where the symptom changed but the root cause remains

An earlier design re-ran the full evaluator or auditor agents after remediation, 3-5 agents re-scanning the entire codebase. This was token-expensive and redundant since the per-phase reviewers had already verified each fix. The current design uses a single verification agent with a targeted scope: read the original intake document findings and check each specific file:line location. One agent, targeted scope, a fraction of the tokens. Evaluator and auditor agents run exactly once (during intake) and never again.

Honest Trade-offs

This pipeline is not free. There are some trade-offs you'll want to consider and be aware of:

Token Cost

Multiple agents reviewing each other's work uses significantly more tokens than a single-pass approach. The adversarial loops can triple the total token usage for a feature. On a subscription plan, this means hitting session limits faster. On API billing, this means real money.

Time

A feature that takes one agent 10 minutes might take the pipeline 30-45 minutes with review loops. Multi-agent frameworks in general are slower than single-pass. The adversarial loops add time on top of the orchestration overhead that any multi-agent system carries.

Orchestrator Context Pressure

The orchestrator accumulates agent result summaries across phases. Long pipelines with many phases may hit context compression, which degrades the orchestrator's ability to route effectively.

Not Fire-and-Forget

Despite the automation, complex features benefit from human checkpoints. The pipeline stops and asks for judgment at key moments. If you skip those checkpoints, you may end up with technically correct code that misses the actual requirement.

Diminishing Returns on Simple Tasks

For a quick script, a utility function, or a prototype, the adversarial overhead is pure waste. Single-pass generation is faster, cheaper, and sufficient.

The trade-off is worth it for features where correctness matters more than speed: anything touching auth, payments, data integrity, or infrastructure. When the cost of a bug in production exceeds the cost of the extra tokens to prevent it, the math works. For everything else, single-pass is fine.

When to Use This (And When Not To)

Use adversarial multi-agent patterns when:

The feature touches authentication, authorization, or session management
The code handles payments or financial transactions
Data integrity is critical (migrations, schema changes, ETL pipelines)
Infrastructure changes could affect production (IaC, CI/CD modifications)
The codebase is unfamiliar to the agents (large legacy systems)

Use single-pass generation when:

Prototyping or exploring an idea
Writing utility scripts or one-off tools
Making small, well-scoped changes to familiar code
Speed matters more than thoroughness
You will review the output carefully yourself anyway

Getting Started

Claude Forge is built entirely from Claude Code custom skills. No external tooling, no CI integration required. Install by copying the skills directory into your project:

git clone https://github.com/hatmanstack/claude-forge.git
cp -r claude-forge/.claude/skills/ /path/to/your-project/.claude/skills/

Then in your project:

# Feature development
/brainstorm I want to add webhook support for payment events
/pipeline 2026-03-12-payment-webhooks

# Full audit (health + eval + docs), one command
/audit all
/pipeline 2026-03-16-audit-remediation

# Individual audits
/repo-eval
/repo-health
/doc-health

The pipeline handles the orchestration. You'll see progress reports between stages, and it will stop and ask when something needs human judgment.

Wrapping Up

The adversarial pattern (separate generator and discriminator with isolated context windows, structured feedback as the communication channel, iteration caps for convergence) can be implemented in any agent system that supports subagent spawning with fresh contexts. The specific implementation uses Claude Code skills, but the pattern is the contribution, not the tooling.

Sometimes the best code comes from the argument, not the agreement.

How to Stop Letting AI Agents Guess Your Requirements

Daniel Nwaneri — Tue, 24 Mar 2026 00:35:37 +0000

I spent 64% of my weekly Claude budget before Wednesday building a tool designed to reduce Claude usage. That's the kind of irony that deserves its own specification.

The tool is spec-writer: a Claude Code skill that takes a vague feature request and generates a structured spec, technical plan, and task breakdown before a single line of code gets written.

The problem it solves is one most developers hit within their first week of using AI coding agents seriously: the agent writes confidently in the wrong direction and you pay for it twice, once in tokens, once in rewrites.

This tutorial shows you how to install spec-writer, how to invoke it on a real feature, and how to read the output so you can catch the assumptions that would have wasted your time.

The Problem with Prompting Agents Directly
What Spec-Driven Development Is
How spec-writer Works
How to Install spec-writer
How to Write Your First Spec
How to Read the Output
How to Hand the Spec to Your Agent
Where to Go Next

The Problem with Prompting Agents Directly

Here is what happens when you skip the spec.

You have a feature in your head: "Add a way for users to export their data." You open Claude Code and describe it. The agent produces code. It looks right. You run it. It's mostly right – except it exports everything including soft-deleted records, it doesn't paginate, it times out on large accounts, and it has no authentication check on the export endpoint.

None of those things were in your prompt. The agent guessed, and it guessed plausibly – which is worse than guessing obviously wrong. You didn't notice until testing.

This is the fundamental problem with prompting agents directly on anything non-trivial: your prompt carries your conscious requirements, but every feature has a shadow of requirements you didn't think to state. And the agent fills that shadow with assumptions.

Most of the time, those assumptions are reasonable. Some of the time, they're wrong in ways that take hours to unravel.

The failure mode isn't hallucination. It's the agent being exactly as helpful as the prompt allowed, which wasn't helpful enough.

Spec-Driven Development addresses this directly. The methodology – documented extensively by practitioners like Julián Deangelis – argues that a written spec isn't documentation overhead. It's the mechanism that forces you to make decisions before the agent does.

What Spec-Driven Development Is

Spec-Driven Development is the practice of writing a structured specification before you write code or prompt an agent. The spec defines what the feature must do, what assumptions are being made, and what tasks the implementation breaks into.

The key insight is what a spec is for. A spec is not trying to replace code. It's trying to surface the decisions that would otherwise be invisible. The agent will make those decisions either way: with a spec, you make them first. Without a spec, you discover them during testing.

The strongest counterargument to SDD comes from Gabriella Gonzalez: a sufficiently detailed spec is just code. She's right that some specs devolve into pseudocode so specific they might as well be implementations.

But that's a spec written at the wrong level of abstraction. The goal is to name the decisions, not to pre-implement them. "Only authenticated users can trigger this export" is a decision. "Call verifyJWT(token) and return 401 if it fails" is implementation. The spec needs the first. The agent handles the second.

SDD has three levels:

Spec-First: write a spec before every feature and hand it to the agent as context. This is the entry point and the workflow this tutorial focuses on.
Spec-Anchored: the spec lives in the repository and evolves alongside the code. When requirements change, you update the spec and re-prompt the agent to realign.
Spec-as-Source: the spec is the primary artifact. Code is generated from it and considered disposable. This is the most ambitious level and the direction many teams are moving toward.

spec-writer gets you to Spec-First immediately, with no ceremony.

How spec-writer Works

spec-writer is a Claude Code skill – a markdown file that loads into the agent's context and changes how it responds when invoked.

The skill follows one rule: generate first, flag assumptions inline. Instead of asking you clarifying questions before producing output, it generates the full spec immediately and marks every decision it made without your explicit input using [ASSUMPTION: ...] tags. Then you correct what's wrong.

This is faster than Q&A because it makes the decisions visible in a form you can react to rather than anticipate.

The output has three sections in fixed order:

SPEC: the what. One-line purpose, user stories, requirements, edge cases, and acceptance criteria in Given/When/Then format.
PLAN: the how. Stack and architecture decisions, data model changes, API contracts, testing strategy, and security constraints.
TASKS: the breakdown. Ordered, self-contained tasks each completable in a single agent session, each with its own acceptance criteria.

After the three sections, the skill produces an Assumptions summary: every [ASSUMPTION: ...] from the output, ranked by impact. This is the part you review before handing anything to the agent.

The skill is compatible with GitHub Spec Kit and OpenSpec. If you use either framework, save the spec output to your .specify/ or openspec/changes/ directory and continue from there.

How to Install spec-writer

spec-writer uses the Agent Skills standard, which means the same SKILL.md file works across Claude Code, Cursor, GitHub Copilot, Gemini CLI, and any other agent that supports the standard. You install it once and it works everywhere.

Installation

Create the skills directory if it doesn't exist and clone the repo:

mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/spec-writer.git ~/.claude/skills/spec-writer

On Windows PowerShell:

(Note: PowerShell uses backtick (`) for line continuation, not backslash.)

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
git clone https://github.com/dannwaneri/spec-writer.git "$HOME\.claude\skills\spec-writer"

That's the entire installation. No package to install, no configuration file to edit, no API key. The skill is a markdown file. The agent reads it.

Verification

Open Claude Code and type:

/spec-writer test

If the skill is installed correctly, the agent will read the SKILL.md and produce a spec structure – even for "test" as input. You'll see the three sections and the Assumptions summary. If nothing happens, confirm that the ~/.claude/skills/spec-writer/SKILL.md file exists.

How to Write Your First Spec

The invocation pattern is:

/spec-writer [your feature description]

The description can be as rough as you'd write in a Slack message. The skill's job is to structure it. You don't need to be precise. Being precise is what the spec is for.

A Real Example

Here is a real invocation from the Foundation project, a federated knowledge base built on Cloudflare Workers:

/spec-writer Add CLI capture for Claude Code sessions stored in ~/.claude/projects/

That's twelve words. No mention of the tech stack, no data model details, no authentication requirements, no error handling spec. All of that comes out in the spec.

Here is the abbreviated output:

SPEC

One-line purpose: Developers can capture Claude Code session logs from their local filesystem into Foundation before they are deleted after 30 days.

Users and use cases:

As a developer using Claude Code daily, I want my coding sessions captured automatically so that architectural decisions and debugging patterns don't disappear after 30 days.
As a Foundation user, I want CLI sessions and browser extension captures in the same knowledge base so that I have one place to query across all my AI interactions.

Acceptance criteria:

Given a developer with Claude Code sessions in ~/.claude/projects/
When they run the Foundation CLI capture command
Then a list of uncaptured sessions is displayed, sorted by most recent first
 
Given a session already in Foundation
When the developer runs capture again
Then that session does not appear in the review list
 
Given a malformed .jsonl file
When the capture command processes it
Then an error is logged for that file and processing continues on remaining sessions

PLAN

Stack and architecture:

CLI capture runs locally — it needs to read the local filesystem, which
Cloudflare Workers cannot do. [ASSUMPTION: CLI capture is a local Node.js
or Bun script that calls the Foundation API to insert sessions, rather
than a Worker itself]

API contracts:

POST /api/sessions/import – accepts parsed session JSON, returns session ID
Returns 409 if session already exists
Triggers evaluator pipeline after successful insert

TASKS

## Task 1: .jsonl parser
 
**What to build:** A parser that reads a Claude Code .jsonl session file
and outputs Foundation's internal message format.
**Files likely affected:** cli/src/parsers/claudeCode.js (create)
**Acceptance criteria:**
1. Parses a valid .jsonl file into the correct message format
2. Handles malformed lines without crashing — logs and skips
3. Returns empty array for empty file
**Dependencies:** none

Assumptions to review:

1. CLI capture is a local script calling the Foundation API, not a Worker
   Impact: HIGH
   Correct this if: you want a purely serverless approach
 
2. Manual curation before capture, not automatic bulk import
   Impact: HIGH
   Correct this if: you want automatic background capture
 
3. Session ID from .jsonl filename is the deduplication key
   Impact: MEDIUM
   Correct this if: session IDs are stored differently in your schema
 
4. No sensitive data scrubbing in v1
   Impact: MEDIUM
   Correct this if: your sessions contain credentials or keys

Twelve words in, four decisions surfaced immediately – three of which had real architectural implications.

The third assumption ("Session ID from .jsonl filename is the deduplication key") is the one that would have caused the most subtle bug. The agent would have implemented deduplication based on the filename and it would have worked until a session was renamed. The spec caught it before a line of code was written.

How to Read the Output

The output is designed to be scanned for [ASSUMPTION: ...] tags first, read for the tasks second.

Reading the Assumptions

Every [ASSUMPTION: ...] tag marks a place where the agent filled in something you didn't specify. Your job is to go through the Assumptions summary and decide for each one:

Correct: the assumption is right, leave it
Override: the assumption is wrong, restate it and re-run the spec
Defer: the assumption doesn't matter for this iteration, mark it and move on

The impact rating tells you which assumptions to fix before you start coding. HIGH-impact assumptions affect architecture or data model. If they're wrong, fixing them requires rework. LOW-impact assumptions affect behavior details that are easy to change later.

Reading the Acceptance Criteria

The acceptance criteria in Given/When/Then format are the most useful part of the spec for catching scope errors. Read each one and ask: is this actually what I want?

Criteria are binary by design. "Returns 401 when unauthenticated" is a criterion. "Works correctly" is not. If you find yourself reading a criterion and thinking "well, it depends", then that's a signal that the criterion is hiding an assumption. Restate it.

Reading the Tasks

The tasks are ordered and self-contained. Each task produces a verifiable change. Before you hand any task to an agent, check two things:

Does the task have all the context it needs? If a task says "follow the existing auth pattern" and you haven't pointed the agent at your auth code, it will guess.
Does the acceptance criteria match what you'd actually test? If the criteria are vague, tighten them before the agent sees the task.

How to Hand the Spec to Your Agent

The spec is context, not a prompt. When you start an agent session for a task, include the relevant spec sections alongside the task description.

For Task 1 from the example above, your agent session might open like this:

Context:
- This is a federated knowledge base built on Cloudflare Workers, D1, and Vectorize
- Sessions are stored in ~/.claude/projects/ as .jsonl files
- The API runs at https://.workers.dev
 
Spec:
[paste the SPEC and PLAN sections]
 
Task:
[paste Task 1]

The context block is just an example. Replace it with your own project's tech stack, file locations, and API URL. The point is to give the agent the same context a new team member would need on day one.

The agent now has requirements, architecture context, and a single scoped task with binary acceptance criteria. It cannot guess the deduplication key incorrectly because the spec already resolved that assumption. It cannot skip error handling because the acceptance criteria explicitly require it.

This is the workflow the spec is designed for. The spec doesn't replace the agent. Rather, it removes the decisions from the agent's hands and puts them in yours, before the work starts.

Saving the Spec for Later

If you want to move toward Spec-Anchored development – where the spec lives in the repository – save the output to a specs/ directory in your project:

# Create specs directory
mkdir -p specs
 
# Save your spec
# Paste the output into specs/cli-capture.md

When requirements change, update the spec and re-prompt the agent to realign the implementation. The spec becomes the source of truth, not the code comments.

Where to Go Next

Try it on your next feature before you write a line of code. The assumptions it flags will tell you something about your feature you hadn't consciously decided yet – and correcting the HIGH-impact ones before you hand anything to an agent is the whole point. Skipping that step is the same as prompting directly.

If your project is growing, move toward Spec-Anchored. Save specs in your repository under specs/. When a new contributor joins or an agent starts a session cold, the specs give them the decisions that got made without requiring them to reverse-engineer the code.

The strongest ongoing challenge to this workflow is Gabriella Gonzalez's argument that detailed specs become code. If your specs are getting implementation-specific, you've crossed a line. Pull back to decisions – "only authenticated users can trigger this" – and leave implementation to the agent. The spec's job is to name what the agent would have guessed wrong, not to write the feature in prose.

The Agent Skills standard now works across Claude Code, GitHub Copilot, Cursor, and Gemini CLI. The spec-writer repo is at github.com/dannwaneri/spec-writer.

The irony of spending 64% of a Claude budget building a token-efficiency tool is real. But the spec surfaced four decisions on a twelve-word prompt. The fourth one – the deduplication key assumption – would have produced a bug that worked perfectly until a session got renamed.

That's not a hallucination. That's the agent being exactly as helpful as the prompt allowed.

The spec is how you raise the ceiling on what "helpful" means.

claude - freeCodeCamp.org

How to Export a Claude Conversation as a PDF

Table of Contents

How to Save Claude Conversations as a PDF Using the Browser Print Option

How Browsers Generate PDFs From Web Pages:

Step 1: Open the Browser's Print Dialog

Step 2: Save the Conversation as a PDF

Step 3: Adjust the Print Settings

Margins

Scale

Background graphics

Headers and footers

How to Copy Claude Responses into Google Docs and Save Them as PDFs

How to Convert Claude Share Links into PDFs

How to Export Claude Artifacts as PDFs

How to Download All Claude Conversations from Settings

How to Choose the Best Export Method

Video Tutorial: How to Export a Claude Conversation as PDF

Conclusion

Codex vs Claude Code: Which AI Coding Assistant to Choose

What We'll Cover Here:

Understanding Codex

Understanding Claude Code

Codex vs Claude Code: Direct Comparison

The Difference in Philosophy

Code Quality and Reasoning

Workflow Integration

Deployment Options

Productivity Considerations

Security and Oversight

Should you Choose Codex or Claude Code?

Final Thoughts

How to Use Claude Code to Build Flutter Apps Faster — Best Practices for 2026

Prerequisites

Table of Contents

1. Why Architecture Comes First

2. Setting Up Your CLAUDE.md

3. Feature-First Folder Structure — The Details

4. Writing Skills for Your Most Repeated Tasks

Creating Your First Skill

A Skill For Conventional Commits

Dynamic Context Injection

5. Using /loop for Self-Correcting Workflows

Fix Until Clean

TDD Loop

Build a Screen, Check it, Iterate

6. Subagents for Parallel Screen Development

Setting Up a Screen-Builder Subagent

Using it

7. Hooks — Enforcing Rules Deterministically

Block Edits to Generated Files

Run Analyze Before Every Stop

8. Putting It All Together: A Real Sprint Workflow

Morning: Check Project State

Start a New Feature

Generate All the Screens in Parallel

Fix Everything Until it's Clean

Commit Cleanly

Key Takeaways

How to Build an AI-Powered, Local-First Chrome Extension That Turns Your Browsing History into an Intent Map

Table of Contents

What You'll Build

Prerequisites

How openloops Is Structured

The Shared Types

The Manifest

How to Scaffold the Extension

How to Capture Your Browsing History

A Few Shared Helpers

The Database Layer (So Far)

Capturing New Visits Live

Backfilling 14 Days of History

Checkpoint

How to Turn Noise into Sessions

Filtering Out Noise

Extracting Keywords

Extending the Database For Sessions

Segmenting Events into Sessions

Checkpoint

How to Cluster Sessions into Intent Threads