+
+
+
+
+
+
+
+ 
+ Brewcode Docs
+
diff --git a/web/docs/src/components/mdx/Badge.astro b/web/docs/src/components/mdx/Badge.astro
new file mode 100644
index 0000000..0e3dd90
--- /dev/null
+++ b/web/docs/src/components/mdx/Badge.astro
@@ -0,0 +1,15 @@
+---
+interface Props {
+ variant?: 'primary' | 'secondary' | 'accent';
+ text: string;
+}
+
+const { variant = 'primary', text } = Astro.props;
+---
+
+{text}
diff --git a/web/docs/src/components/mdx/Callout.astro b/web/docs/src/components/mdx/Callout.astro
new file mode 100644
index 0000000..0ae4b52
--- /dev/null
+++ b/web/docs/src/components/mdx/Callout.astro
@@ -0,0 +1,44 @@
+---
+interface Props {
+ type?: 'note' | 'tip' | 'warning' | 'caution';
+ title?: string;
+}
+
+const { type = 'note', title } = Astro.props;
+
+const config = {
+ note: {
+ alert: 'alert-info',
+ icon: '',
+ defaultTitle: 'Note',
+ },
+ tip: {
+ alert: 'alert-success',
+ icon: '',
+ defaultTitle: 'Tip',
+ },
+ warning: {
+ alert: 'alert-warning',
+ icon: '',
+ defaultTitle: 'Warning',
+ },
+ caution: {
+ alert: 'alert-error',
+ icon: '',
+ defaultTitle: 'Caution',
+ },
+};
+
+const { alert, icon, defaultTitle } = config[type];
+const displayTitle = title || defaultTitle;
+---
+
+
+
diff --git a/web/docs/src/components/mdx/Card.astro b/web/docs/src/components/mdx/Card.astro
new file mode 100644
index 0000000..8585e57
--- /dev/null
+++ b/web/docs/src/components/mdx/Card.astro
@@ -0,0 +1,28 @@
+---
+interface Props {
+ title: string;
+ icon?: string;
+ href?: string;
+}
+
+const { title, icon, href } = Astro.props;
+const Tag = href ? 'a' : 'div';
+---
+
+
+
+{displayTitle}
+
+
+
+ {icon && {icon}}
+
+
+
+ {title}
+
+
+
+
diff --git a/web/docs/src/components/mdx/Steps.astro b/web/docs/src/components/mdx/Steps.astro
new file mode 100644
index 0000000..e57883f
--- /dev/null
+++ b/web/docs/src/components/mdx/Steps.astro
@@ -0,0 +1,5 @@
+
+
diff --git a/web/docs/src/components/mdx/TabItem.astro b/web/docs/src/components/mdx/TabItem.astro
new file mode 100644
index 0000000..b926583
--- /dev/null
+++ b/web/docs/src/components/mdx/TabItem.astro
@@ -0,0 +1,21 @@
+---
+interface Props {
+ label: string;
+}
+
+const { label } = Astro.props;
+---
+
+-
+
+
diff --git a/web/docs/src/components/mdx/Tabs.astro b/web/docs/src/components/mdx/Tabs.astro
new file mode 100644
index 0000000..8fb51ee
--- /dev/null
+++ b/web/docs/src/components/mdx/Tabs.astro
@@ -0,0 +1,52 @@
+---
+const groupId = `tabs-${Math.random().toString(36).slice(2, 8)}`;
+---
+
+
+
+
+
+
+
+
+
+
diff --git a/web/docs/src/components/mdx/index.ts b/web/docs/src/components/mdx/index.ts
new file mode 100644
index 0000000..299c7c1
--- /dev/null
+++ b/web/docs/src/components/mdx/index.ts
@@ -0,0 +1,7 @@
+export { default as Card } from './Card.astro';
+export { default as CardGrid } from './CardGrid.astro';
+export { default as Callout } from './Callout.astro';
+export { default as Tabs } from './Tabs.astro';
+export { default as TabItem } from './TabItem.astro';
+export { default as Steps } from './Steps.astro';
+export { default as Badge } from './Badge.astro';
diff --git a/web/docs/src/content.config.ts b/web/docs/src/content.config.ts
new file mode 100644
index 0000000..3f0d971
--- /dev/null
+++ b/web/docs/src/content.config.ts
@@ -0,0 +1,13 @@
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+const docs = defineCollection({
+ loader: glob({ pattern: '**/*.mdx', base: './src/content/docs' }),
+ schema: z.object({
+ title: z.string(),
+ description: z.string(),
+ order: z.number().optional(),
+ }),
+});
+
+export const collections = { docs };
diff --git a/web/docs/src/content/docs/brewcode/agents.mdx b/web/docs/src/content/docs/brewcode/agents.mdx
new file mode 100644
index 0000000..554831c
--- /dev/null
+++ b/web/docs/src/content/docs/brewcode/agents.mdx
@@ -0,0 +1,301 @@
+---
+title: "Agents"
+description: "All 13 Brewcode agents: models, triggers, tools"
+order: 12
+---
+
+import { Card, CardGrid, Callout, Tabs, TabItem, Steps, Badge } from '../../../components/mdx';
+
+# Agents
+
+Agents (brewers) are specialized roles defined in markdown files with frontmatter metadata.
+Each agent has its own model, toolset, and system prompt. Brewcode includes 13 agents,
+from developer to task coordinator.
+
+## Summary table
+
+| # | Agent | Model | Write tools | Purpose |
+|---|-------|-------|-------------|---------|
+| 1 | developer | opus | Read, Write, Edit, Bash | Feature implementation, bug fixes |
+| 2 | tester | sonnet | Read, Write, Edit, Bash | Test execution, failure analysis |
+| 3 | reviewer | opus | Read (read-only) | Code review, architecture, security |
+| 4 | architect | opus | Read (read-only) | Architecture analysis, patterns |
+| 5 | skill-creator | opus | Read, Write, Edit | Skill creation and improvement |
+| 6 | agent-creator | opus | Read, Write, Edit | Agent creation and improvement |
+| 7 | hook-creator | opus | Read, Write, Edit, Bash | Hook creation and debugging |
+| 8 | text-optimizer | sonnet | Read, Write, Edit | Text optimization for LLMs |
+| 9 | bash-expert | opus | Read, Write, Edit, Bash | Bash/sh script creation |
+| 10 | bc-coordinator | haiku | Read, Write, Edit, Bash | Phase and knowledge coordination |
+| 11 | bc-knowledge-manager | haiku | Read, Write | KNOWLEDGE.jsonl compaction |
+| 12 | bc-grepai-configurator | opus | Read, Write, Edit, Bash | grepai config.yaml generation |
+| 13 | bc-rules-organizer | sonnet | Read, Write, Edit, Bash | .claude/rules/ organization |
+
+/brewcode:start skill reads agent assignments from the phase table
+ and launches the corresponding agents via Task API.
+handoff means "re-read TASK.md", not "new session".
+/brewcode:start for finalization
+ or set the task status to finished/failed/cancelled.
+
+ Installation
+ Install dependencies: brew, coreutils, jq, optionally grepai.
+
+ Project setup
+ Analyze the project and generate adapted templates.
+
+ Specification
+ Parallel codebase research, SPEC.md creation.
+
+ Plan
+ Phase generation, quorum review, requirements tracing.
+
+ Execution
+ Launch the task with infinite context and automatic handoff.
+text-optimize, text-human, standards-review,
+ secrets-scan, skills, and agents can be used
+ independently of the core cycle -- they require no prior setup.
+
+ Template check
+
+ The skill checks for SPEC.md.template in .claude/tasks/templates/.
+ If the template is missing, you need to run /brewcode:setup first.
+ Input parsing
+
+ Determines the input type: text description, path to a requirements file, or reference
+ from .claude/TASK.md. Supports the -n (--noask) flag for autonomous mode.
+ Clarifying questions
+
+ 3-5 questions via AskUserQuestion across categories: Scope (what's in/out),
+ Constraints (libraries, compatibility), Edge cases (concurrency, null inputs).
+ Skipped in -n mode.
+ Split check
+
+ If requirements cover more than 3 independent areas or are estimated at 12+ phases -- + a split is suggested. If accepted, only the first part gets a SPEC.
+
+ Parallel research
+
+ 5-10 agents are launched in a single message (in parallel). + Each agent analyzes its area: Controllers, Services, DB/Repos, Tests, Config, Docs.
+Task(subagent_type="developer", prompt="Analyze services...")
Task(subagent_type="tester", prompt="Analyze test patterns...")
Task(subagent_type="reviewer", prompt="Analyze quality...")
Task(subagent_type="Explore", prompt="Find library docs...")
+ Consolidation into SPEC.md
+
+ Agent results are merged with deduplication. A task directory
+ .claude/tasks/{TS}_{NAME}_task/ and SPEC.md file are created from the template.
+ Specification review
+
+ Reviewer checks: completeness, consistency, feasibility, risks. + Fix loop: continues while critical/major issues exist (max 3 iterations).
+
+ WRITE report
+
+ The manager writes the agent report to artifacts/{P}-{N}{T}/{AGENT}_output.md
+ CALL bc-coordinator
+
+ The coordinator reads the report from disk, extracts 3-10 knowledge entries into KNOWLEDGE.jsonl, + and updates the Phase Status table.
+
+ PreCompact hook fires
+
+ The pre-compact.mjs hook detects the approaching limit.
+ KNOWLEDGE.jsonl compaction
+
+ Deduplication, stale entry removal, trimming to maxEntries.
+
+ Handoff entry written
+
+ A special entry in KNOWLEDGE.jsonl captures the current state: which phase was executing, + what was done, what remains.
+
+ Status update
+
+ Task status is set to handoff.
+ Claude Code compresses context
+
+ Auto-compact summarizes the context. Session ID does not change.
+
+ Continuation after compact
+
+ The /brewcode:start skill calls TaskList(),
+ reads PLAN.md, and continues from the current phase. The lock file remains valid.
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE variable can only shift the trigger threshold
+ earlier (values below 93%), but cannot increase the buffer.
+/brewcode:convention to extract reference classes and patterns
+ from the written code. Results go into .claude/convention/
+ and help future tasks follow established conventions.
+
+ Discovery
+
+ The discover.sh script finds all markdown files in the scope
+ and determines their type: skill, agent, rule, config, or doc.
+ Files without frontmatter tags are added automatically.
+
+ Queue
+
+ The index-ops.sh stale script identifies stale entries based on the configured interval
+ (INTERVAL_DAYS from config). New and stale files enter the processing queue.
+
+ Processing
+
+ For each file in the queue, a bd-auto-sync-processor agent (sonnet model) is launched.
+ Agents run in parallel (up to PARALLEL_AGENTS concurrently).
+ Each agent analyzes the code, compares it with the current document content, and applies changes.
+
+ Report
+ + Updated files receive a new date in the INDEX. Failed files remain stale for a retry. + A summary report is generated: discovered, queued, updated, unchanged, errors. +
+
+ Check
+
+ + The script determines whether pip packages and system dependencies for the target engine are installed. +
+
+ Choose
+
+ + If dependencies are missing, you are offered to install the current engine, + switch to an alternative (if available), or cancel. +
+
+ Install
+
+
+ With user consent, the check_deps.sh install script installs
+ all required packages. If installation fails, conversion is aborted.
+
+ Remove duplicates
+
+ The Explore agent cross-references all memory files against CLAUDE.md and .claude/rules/*.md.
+ It finds entries that already exist in rules or conflict with CLAUDE.md (CLAUDE.md takes priority).
+ It shows a duplicates table and asks for confirmation: "Remove all", "Review each", or "Skip".
+
+ Migrate to rules/CLAUDE.md
+
+ Remaining entries are classified by target location.
+ Global rules are moved to ~/.claude/rules/,
+ project rules to .claude/rules/,
+ architectural decisions to the project CLAUDE.md.
+ Facts and patterns useful across sessions stay in memory.
+
+ Compress
+ + Remaining entries are compressed for token savings: prose is converted to table rows, + related entries are merged, verbose descriptions are replaced with imperative one-liners, + example lists are reduced to a pattern plus one example. A preview with estimated savings is shown. +
+
+ Validate and clean up
+
+ The reviewer agent checks the final state: broken file references,
+ conflicts with CLAUDE.md, invalid markdown. Broken references are fixed automatically.
+ Orphaned memory files (not referenced from MEMORY.md) are detected and proposed for deletion.
+
+ Install the plugins
+
+ Run the commands from the section above. Restart Claude Code after installation.
+
+ Check the plugin list
+
+ In your terminal, run:
+claude plugin listYou should see brewcode and brewdoc in the list.
+ Install dependencies
+
+ Inside a Claude Code session, run:
+/brewcode:installThis skill checks for and installs brew, jq, and coreutils. Optionally installs ollama and grepai for semantic search.
+
+ Project setup
+ Open Claude Code in your project root and run:
+/brewcode:setupWhat happens: the skill analyzes your project structure, tech stack, + test frameworks, and existing agents. It generates tailored templates based on the analysis.
+Result:
+-
+
.claude/tasks/templates/PLAN.md.template-- plan template
+ .claude/tasks/templates/SPEC.md.template-- specification template
+ .claude/tasks/cfg/brewcode.config.json-- configuration
+ .claude/skills/brewcode-review/-- tailored code review skill
+
This step runs once per project.
+
+ Creating a specification
+ Describe the task in plain text or point to a requirements file:
+/brewcode:spec "Implement JWT authorization with role-based access"Or from a file:
+/brewcode:spec ./docs/requirements/auth.mdWhat happens: the plugin launches 5-10 research agents in parallel.
+ The agents analyze the codebase, find related code, dependencies, and patterns.
+ Then it asks clarifying questions (use the -n flag for autonomous mode without questions).
Result: a SPEC.md file -- a structured specification with project context.
+ Generating a plan
+ /brewcode:planWhat happens: a phased execution plan is generated from SPEC.md. + Each phase contains specific steps, expected artifacts, and completion criteria.
+Result: a PLAN.md file -- a plan with phases, ready for execution.
+ Running the task
+ /brewcode:startWhat happens: Brewcode begins executing the plan phase by phase. + Agents work on the task, recording knowledge in KNOWLEDGE.jsonl. + When context reaches ~90%, the PreCompact hook fires: + knowledge is compressed, handoff state is written, and the session continues automatically.
+Result: the task runs to completion regardless of how many compaction cycles occur.
+ All artifacts are saved in `.claude/tasks/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+