babok_analyst — Claude Code plugin: what it does, how to install
babok_analyst guides business analysis across 9 BABOK v3 stages with mandatory human sign-off at every gate.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install babok_analyst@awesome-codex-pluginsWhat babok_analyst does
The plugin enforces a BABOK v3 analysis workflow structured from Stage 0 (project charter) to Stage 8 (business case and ROI). It bundles multi-stage prompts, a Node.js CLI utility with document parsers for PDF, DOCX, XLSX, and CSV, and a dedicated MCP server offering 19 tools and 9 resources.
Work progress relies on short rationales backed by cited evidence. The system keeps markdown project documentation, tracks decisions in persistent journals, and handles tailored profiles for consulting or software modernisation hooked into GitHub or GitLab.
Automated script execution in the software development profile remains blocked until explicitly granted via an authorization step.
What it helps with
- draft a project charter and structure solution scope
- map current state processes into Mermaid diagrams
- audit requirements against SMART heuristics and consistency rules
- prepare risk matrices alongside business case ROI calculations
Example prompts for the agent
- Initialize Stage 0 project charter for our new internal tool
- Validate requirements consistency across all completed stages
- Build an evidence-backed baseline for the connected repository
How to install babok_analyst
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install babok_analyst@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about babok_analyst
How to install babok_analyst in Claude Code?
Run both setup commands in order: /plugin marketplace add hashgraph-online/awesome-codex-plugins and then /plugin install babok_analyst@awesome-codex-plugins.
What does babok_analyst do?
It structures the analysis lifecycle into a 9-stage sequence compliant with BABOK v3, producing Markdown deliverables under human supervision.
Does the plugin run repository code automatically?
No, code execution within repository baselines is strictly gated behind the explicit command babok sd exec authorize.
Source text
BABOK_ANALYST · MIT
# BABOK Analyst - AI-Powered Business Analysis Agent
[](https://github.com/GSkuza/BABOK_ANALYST/releases)
[](https://github.com/GSkuza/BABOK_ANALYST/actions/workflows/lint-prompts.yml)
An AI agent for professional business analysis compliant with **BABOK v3** (International Institute of Business Analysis) standard. Guides the analyst through a structured **9-stage** flow - from Stage 0 project charter to Stage 8 business case and ROI.
**Current version:** 2.4.0 | **Plugin install:** Claude Code, Codex, Copilot CLI
## What is BABOK Analyst?
BABOK Analyst is a set of system prompts for AI models (Claude, ChatGPT, other LLMs) that transforms them into business analysis experts. The agent:
- Conducts a structured analysis process in **9 stages** (Stage 0 charter gate + Stages 1-8)
- Uses **Short Rationale + Evidence** methodology (concise conclusions with cited evidence)
- Requires **human approval** at each stage (human-in-the-loop)
- Generates complete **project documentation** in Markdown format
- Manages **project lifecycle** with unique Project IDs, save/load, and persistent journal logs
- Specializes in IT projects for **mid-market** companies (€10-100M revenue, 50-500 employees)
- Also ships a **consulting** profile (no IT delivery) and a **software-development** profile for modernising an *existing* product — connects to real GitHub/GitLab repositories, builds an autonomous evidence-backed baseline (`babok sd baseline build`), and gates any code execution behind an explicit, separate authorisation (`babok sd exec authorize`)
## Repository Structure
```
BABOK_ANALYST/
|
|-- BABOK_AGENT/ # Agent files
| |-- BABOK_Agent_System_Prompt.md # Main system prompt (modular, references stage files)
| |-- BABOK_Agent_Quick_Start_Guide.md # Quick start guide
| |-- BABOK_Project_Structure_Template.md # Generic project folder structure template
| |-- stages/ # Individual stage instruction files
| | |-- BABOK_agent_stage_0.md # Stage 0: Project Charter
| | |-- BABOK_agent_stage_1.md # Stage 1: Project Initialization
| | |-- BABOK_agent_stage_2.md # Stage 2: Current State Analysis
| | |-- BABOK_agent_stage_3.md # Stage 3: Problem Domain Analysis
| | |-- BABOK_agent_stage_4.md # Stage 4: Solution Requirements
| | |-- BABOK_agent_stage_5.md # Stage 5: Future State Design
| | |-- BABOK_agent_stage_6.md # Stage 6: Gap Analysis & Roadmap
| | |-- BABOK_agent_stage_7.md # Stage 7: Risk Assessment
| | |-- BABOK_agent_stage_8.md # Stage 8: Business Case & ROI
| |-- agents/ # Multi-agent orchestration layer (NEW v2.1.0)
| | |-- orchestrator_config.json # Pipeline: model routing, handoff, retry rules
| | |-- stage1_config.json … stage8_config.json # Per-stage model & prompt config
| | |-- quality_audit_agent.md # Automated post-stage quality review agent
| | |-- quality_scoring_rubric.json # Scoring rubric (completeness/SMART/consistency)
| | |-- context_schema_v2.json # Extended context schema v2
| |-- LLM_BABOK_AGENT/ # Standalone prompt for LLM chat
| | |-- BABOK_Agent_LLM_Prompt.md # Self-contained prompt (all stages inline)
|
|-- cli/ # Node.js CLI tool
| |-- bin/babok.js # CLI entry point
| |-- src/commands/ # Command implementations
| | |-- ingest.js # babok ingest <file> (NEW v2.1.0)
| |-- src/quality/ # Quality scoring engine (NEW v2.1.0)
| | |-- scorer.js # scoreStage() / scoreAll()
| | |-- checks/completeness.js # Section completeness checker
| | |-- checks/smart.js # SMART criteria heuristics
| | |-- checks/consistency.js # Cross-stage consistency checks
| |-- src/validation/ # Validation engine (NEW v2.1.0)
| | |-- cross-stage-validator.js # validateProject() — 6 built-in rules
| |-- src/reasoning/ # AI reasoning engine (NEW v2.1.0)
| | |-- process-mapper.js # generateProcessDiagram() — Mermaid output
| | |-- prompts/ # LLM prompt templates
| |-- src/lib/document-parser.js # PDF/DOCX/XLSX/CSV/TXT/MD parser (NEW v2.1.0)
| |-- src/lock.js # File-locking for team collaboration
| |-- src/llm.js # Multi-provider LLM integration, model discovery & keystore
| |-- src/model-routing.js # Profile/stage model routing, temperature, effort, failover
| |-- src/journal.js # Project journal management
| |-- src/project.js # Project ID generation
| |-- src/display.js # Terminal output formatting
| |-- package.json # npm package configuration
| |-- README.md # CLI Quick Start Guide
|
|-- babok-mcp/ # MCP Server (v2.2.x)
| |-- bin/babok-mcp.js # Entry point (npx babok-mcp)
| |-- src/server.js # MCP server — 19 tools + 9 resources
| |-- src/lib/project.js # Project ID & path resolution
| |-- src/lib/journal.js # Journal CRUD + stage transitions
| |-- src/test/smoke.js # 10-assertion smoke test suite
| |-- setup.bat # One-click MCP installer (Windows)
| |-- package.json # npm package (babok-mcp)
| |-- README.md # Setup guide for Claude/Cursor/VS Code
| |-- babok-mcp-user-manual.md # Full user manual (EN)
|
|-- web/ # Web UI — Next.js 15 App Router
| |-- app/ # App Router pages & API routes
| | |-- page.tsx # Dashboard — server-rendered project overview
| | |-- projects/ # Project detail, stage review, export page
| | |-- api/ # REST API routes (projects, stages, export)
| |-- components/ # Reusable React components + UI primitives
| |-- lib/project-store.ts # Shared server-side project/stage readers
| |-- lib/babok-client.ts # Typed API client helpers
| |-- next.config.js
| |-- package.json
|
|-- docs/ # Architecture & reference docs (NEW v2.1.0)
| |-- L2_L3_ARCHITECTURE.md # L2/L3 agent layer design with sequence diagrams
| |-- MCP_TOOLS_SPECIFICATION.md # Full MCP tools API reference
| |-- MIGRATION_GUIDE_L1_to_L2.md # CLI → MCP migration guide
| |-- workflows.md # End-to-end workflow diagrams
| |-- agent-portability.md # Plugin marketplace adapter matrix (NEW v2.1.0)
|
|-- templates/ # BABOK deliverable templates (NEW v2.1.0)
| |-- BRD_Template.md # Business Requirements Document
| |-- Risk_Register_Template.md # Risk Register with probability/impact matrix
| |-- Stakeholder_Analysis_Template.md # Stakeholder Analysis + RACI matrix
| |-- User_Story_Template.md # User Story with Given/When/Then criteria
| |-- project_context.example.json # Reference context file for babok run
|
|-- knowledge/ # BABOK knowledge base (NEW v2.1.0)
| |-- benchmarks/ # Industry benchmark data
| |-- industries/ # Industry-specific reference data
| |-- regulations/ # Regulatory requirements by jurisdiction
| |-- anti_patterns/ # Known BA anti-patterns
| |-- technology/ # Technology reference data
| |-- schema/
| |-- README.md
|
|-- tests/ # Automated test suite (NEW v2.1.0)
| |-- unit/ # Unit tests (project, journal, scoring, validation)
| |-- integration/ # Integration tests (CLI workflow)
| |-- plugin-manifest.test.cjs # Plugin marketplace smoke tests (NEW v2.1.0)
| |-- hooks.test.cjs # Lifecycle hook tests (NEW v2.1.0)
| |-- uninstall.test.cjs # Uninstall script tests (NEW v2.1.0)
| |-- fixtures/ # Sample deliverable files for testing
| |-- helpers/ # mock-llm.js, temp-project.js
|
|-- evaluation/ # Gold standard evaluation suite (NEW v2.1.0)
|
|-- .claude-plugin/ # Claude Code marketplace manifests (NEW v2.1.0)
|-- .codex-plugin/ # Codex plugin manifest
|-- .github/plugin/ # Copilot CLI plugin manifest
|-- .mcp.json # Portable MCP wiring (${CLAUDE_PLUGIN_ROOT})
|-- hooks/ # Lifecycle hooks (Claude/Codex/Copilot)
|-- skills/ # Bundled agent skills
|-- commands/ # Slash commands: *.md (Claude), *.toml (Copilot/Codex)
|-- agents/ # Subagent definitions (orchestrator + stages 0–8)
|-- AGENTS.md # Always-on rules for generic agents
|-- scripts/ # check-versions.cjs, uninstall.cjs
|
|-- setup.bat # One-click installer (Windows)
|-- setup.sh # One-click installer (Linux/macOS)
|-- generate_manual.py # DOCX/PDF manual generator (NEW v2.1.0)
|-- babok-mcp-podrecznik uzytkownika.md # Full MCP user manual (PL)
|-- babok-mcp-user-manual.md # Full MCP user manual (EN)
|-- BABOK_AGENT_SYSTEM_PROMPT.md # Consolidated root-level system prompt (NEW v2.1.0)
|
|-- .github/
| |-- copilot-instructions.md # Configuration for GitHub Copilot / VS Code (1,600 lines)
| |-- prompts/ # Stage-specific Copilot Chat prompt files (NEW v2.1.0)
| |-- workflows/
| | |-- lint-prompts.yml # CI: validates stage files on every push
|
|-- .gitignore # Excludes local analysis files
|-- README.md # This file
```
## Stages
| Stage | Name | What You Get |
|------|-------|----------------|
| **Stage 0** ⭐ | Project Charter | Business trigger, sponsor sign-off, scope boundary, Go/No-Go gate |
| **Stage 1** | Project Initialization & Stakeholder Mapping | Project scope, stakeholder register, success criteria |
| **Stage 2** | Current State Analysis (AS-IS) | Process maps, cost baseline, system analysis |
| **Stage 3** | Problem Domain Analysis | Problem categorization, root cause analysis, prioritization |
| **Stage 4** | Solution Requirements Definition | Functional/non-functional requirements, user stories, MoSCoW |
| **Stage 5** | Future State Design (TO-BE) | Target architecture, TO-BE processes |
| **Stage 6** | Gap Analysis & Implementation Roadmap | Gap analysis, implementation roadmap |
| **Stage 7** | Risk Assessment & Mitigation Strategy | Risk register, mitigation plans |
| **Stage 8** | Business Case & ROI Model | Financial model, ROI, NPV, payback period |
### Pipeline profiles
The table above is the default **`babok`** profile. A project can instead run the **`consulting`** profile (`babok new --profile consulting`, `/babok-new-consulting`, or `babok_new_project { profile: "consulting" }`) — a leaner, non-IT advisory pipeline with project IDs prefixed `BC-`:
| Stage | Name | What You Get |
|------|-------|----------------|
| **Stage 0** ⭐ | Engagement Charter & Mandate | Sponsor & mandate, scope with explicit no-IT exclusion, fee & budget ceiling, Go/No-Go |
| **Stage 1** | Stakeholder & Governance Mapping | Power/interest grid, steering committee, RACI, success KPIs, communication plan |
| **Stage 2** | Current State Diagnostic & Root Cause Analysis | Operating model canvas, KPI baseline, findings, 5-Whys/Fishbone root causes, value at stake |
| **Stage 3** | Strategic Options & Recommendation | Options (OPT-NN), weighted evaluation matrix, recommendation, risks of inaction |
| **Stage 4** | Target Operating Model & Change Roadmap | Target model by dimension, org-design changes, phased roadmap, ADKAR/Kotter change plan |
| **Stage 5** | Risk, Governance & Change Readiness | Risk register with owners, readiness per stakeholder group, escalation cadence |
| **Stage 6** | Business Case & Value Realization Plan | CBA, ROI/NPV/payback, benefits tracker, budget alignment, value governance |
Profiles are plain data under `profiles/<id>/` (see `profiles/profile.schema.json`); the same CLI, MCP server, hooks and web UI serve every profile.
A third **`software-development`** profile (`babok new --profile software-development`, `/babok-new-software-development`, or `babok_new_project { profile: "software-development" }`) plans modernisation or new-feature work against an **existing** product and its connected repositories — project IDs prefixed `SD-`:
| Stage | Name | What You Get |
|------|-------|----------------|
| **Stage 0** ⭐ | Change Charter | Business trigger, product & repository scope, ownership & authorisation boundaries, budget ceiling, exclusions |
| **Stage 1** | Product & Repository Baseline | Autonomous, evidence-cited Business/Technology/Architecture/SDLC baseline pinned to a commit — no technical interview |
| **Stage 2** | Change Impact & Gap Analysis | Current vs. desired behaviour, affected components/contracts, migration & regression risks |
| **Stage 3** | Options & Architecture Decisions | Autonomous option generation & evaluation, recommendation, draft ADRs, compatibility approach, self-critique pass |
| **Stage 4** | Implementation & Verification Plan | Backlog (FR-NNN), RTM, roadmap, cost vs. budget ceiling, and a distinct **execution-authorisation** record |
| **Stage 5** | Release & Operational Readiness | Actual verification evidence, migration/rollback, monitoring, risk register with owners |
| **Stage 6** | Outcome & Context Reconciliation | Real deployment/KPI evidence and the proposed update to the product's Stage 1 baseline |
This profile never self-approves a generated stage — `orchestrator.autoApproveGeneratedStages: false` means every stage, including the autonomous ones and `babok run --orchestrate`, still waits for a human `babok approve`. Approving Stage 4 freezes the plan; it does not authorise running the analysed repository's own code/tests or publishing a pull/merge request — that is requested and recorded separately in the deliverable's Execution Authorisation Status.
---
## Web UI Highlights
The bundled Next.js UI provides a lightweight review layer over the shared project files in `projects/<project_id>/`.
- **Dashboard**: server-rendered project cards with progress bars and approval counts
- **Project view**: stage list, overall progress, and ZIP export
- **Stage view**: AI-guided interview that starts from the earlier stages' deliverables (it never re-asks what they already establish, and it carries later-stage details forward instead of eliciting them), generated deliverable drafts, Mermaid diagrams, quality score badge, approve/reject controls, and an **Open revision to edit** action that reopens an approved stage (Two-Key Journal `revision_open`) so the interview/regeneration flow can complete or fix an incomplete deliverable without leaving the browser
- **AI settings**: configure encrypted provider API keys, list the models each key can access, and route models per profile and per stage (temperature, reasoning effort, fallback chains across every configured key)
- **Export endpoint**: project ZIP download via `web/app/api/projects/[id]/export/route.ts`, with Windows-compatible archive creation
Run locally:
```bash
cd web
npm install
npm run build
npm run start
```
Open `http://localhost:3000`.
---
## Modular Architecture (v2.0)
The agent system uses a **modular architecture** where each analysis stage has its own detailed instruction file:
```
BABOK_AGENT/
|-- BABOK_Agent_System_Prompt.md # Core prompt (references stage files)
|-- stages/
| |-- BABOK_agent_stage_0.md # Stage 0: Project Charter gate
| |-- BABOK_agent_stage_1.md # Detailed Stage 1 instructions
| |-- BABOK_agent_stage_2.md # Detailed Stage 2 instructions
| |-- ... # Stages 3-7
| |-- BABOK_agent_stage_8.md # Detailed Stage 8 instructions
|-- LLM_BABOK_AGENT/
| |-- BABOK_Agent_LLM_Prompt.md # All-in-one prompt for LLM chat windows
```
**Two usage variants:**
| Variant | File | Use When |
|---------|------|----------|
| **Modular** | `BABOK_Agent_System_Prompt.md` + `stages/*.md` | VS Code, Claude Code, IDE-based workflows (agent can load stage files as needed) |
| **Standalone** | `LLM_BABOK_AGENT/BABOK_Agent_LLM_Prompt.md` | Direct paste into LLM chat (Claude.ai, ChatGPT, etc.) — all stages inline, self-contained |
Each stage file contains: step-by-step process, questions for human, deliverable template, quality checklist, and CLI command references.
---
## How to Get Started
### Plugin Marketplace Install (recommended) — v2.2+
Install the full BABOK Analyst stack (skills, agents, hooks, MCP, slash commands) in Claude Code, Codex, or Copilot CLI.
**Claude Code (3 steps):**
```
/plugin marketplace add GSkuza/BABOK_ANALYST
/plugin install babok_analyst@babok_analyst
/reload-plugins
```
Then open `/hooks` and authorize lifecycle hooks. Start a **new session**.
**Update to latest release:**
```
/plugin marketplace update babok_analyst
/plugin install babok_analyst@babok_analyst
/reload-plugins
```
**Codex** (run in **PowerShell / cmd**, not inside the Codex chat — the in-app sandbox cannot write to `~/.codex`):
```
codex plugin marketplace add GSkuza/BABOK_ANALYST
codex plugin add babok_analyst@babok_analyst
```
Then open `/plugins` to confirm **babok_analyst@babok_analyst** is listed, and authorize hooks in `/hooks`.
**Update:**
```
codex plugin marketplace upgrade babok_analyst
codex plugin add babok_analyst@babok_analyst
```
**GitHub Copilot CLI:**
```
copilot plugin marketplace add GSkuza/BABOK_ANALYST
copilot plugin install babok_analyst@babok_analyst
```
#### What the plugin includes
| Component | Location | Purpose |
|-----------|----------|---------|
| Marketplace manifest | `.claude-plugin/` (Claude), `.agents/plugins/` (Codex) | Plugin registry per host |
| MCP wiring | `.mcp.json` | 19 tools + 9 stage resources (`${CLAUDE_PLUGIN_ROOT}`) |
| Lifecycle hooks | `hooks/` | Session activation + `babok-mcp` dependency install |
| Skills | `skills/babok-analyst/`, `skills/eu-pl-law-tracker/` | BABOK operating rules + EU/PL legal tracking workflow |
| Agents | `agents/` | Orchestrator + per-stage subagents (12) |
| Commands | `commands/babok-*.md` | `/babok-new`, `/babok-new PL`, `/babok-new ENG`, `/babok-new-pl`, `/babok-new-eng`, `/babok-status`, `/babok-help` |
| Always-on rules | `AGENTS.md` | Generic agents / Gemini CLI fallback |
Projects are stored in **`projects/<project_id>/`** under your workspace (not `BABOK_Analysis/`).
**Uninstall external state:** `node scripts/uninstall.cjs`
See [`docs/agent-portability.md`](docs/agent-portability.md) for the full adapter matrix.
#### Troubleshooting
| Error | Fix |
|-------|-----|
| `marketplace "babok_analyst" not found` | Run `/plugin marketplace add GSkuza/BABOK_ANALYST` **before** install |
| `agents: Invalid input` | Update to **v2.2.0+** (`/plugin marketplace update babok_analyst`) — fixed manifest |
| MCP tools missing | `/reload-plugins`, ensure Node.js ≥18; hook runs `npm install` in `babok-mcp/` |
| Codex: MCP `babok` handshake failed | Update to **v2.2.4+** — uses `hooks/babok-mcp-launcher.cjs` with `cwd: "."` (Codex does not expand `${CLAUDE_PLUGIN_ROOT}`) |
| Stale plugin cache | `/plugin marketplace update babok_analyst` then reinstall |
| Codex: empty plugin list / sandbox write error | Run `codex plugin marketplace add` in a **normal terminal** (v2.2.4+); update marketplace if on older tag |
**Local checkout (no GitHub fetch):**
```
/plugin marketplace add C:/AI_WORKSPACE/CURSOR_PROJECTS/CURSOR_PROJECTS_BIZ/BABOK_ANALYST/BABOK_ANALYST
/plugin install babok_analyst@babok_analyst
/reload-plugins
```
---
### Quick Start (non-technical users)
**Windows:**
```bat
setup.bat
```
**Linux / macOS:**
```bash
chmod +x setup.sh && ./setup.sh
```
The setup script automatically:
- checks for Node.js (with download link if missing)
- runs `npm install`
- optionally adds `babok` to PATH
- launches the **interactive setup wizard** (`babok setup`) for API key entry and language selection — no JSON editing required
---
### Method 1: Claude.ai (Projects)
1. **Clone or download the repository** (see section below)
2. Go to [claude.ai](https://claude.ai) and create a new **Project**
3. In project settings, click **"Project Instructions"** (Custom Instructions)
4. Copy the **entire** content of `BABOK_AGENT/LLM_BABOK_AGENT/BABOK_Agent_LLM_Prompt.md` file and paste it into the Project Instructions field
5. Start a new conversation in the project and type:
```
BEGIN NEW PROJECT
```
### Method 2: VS Code with Claude Code (CLI)
1. Clone the repository:
```bash
git clone https://github.com/GSkuza/BABOK_ANALYST.git
cd BABOK_ANALYST
```
2. Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (requires Node.js 18+):
```bash
npm install -g @anthropic-ai/claude-code
```
3. Launch Claude Code in the project directory:
```bash
claude
```
4. Claude will automatically load the configuration from `.github/copilot-instructions.md`
5. Type:
```
BEGIN NEW PROJECT
```
### Method 3: VS Code with GitHub Copilot Chat
1. Clone the repository and open in VS Code:
```bash
git clone https://github.com/GSkuza/BABOK_ANALYST.git
code BABOK_ANALYST
```
2. Make sure you have the **GitHub Copilot Chat** extension installed
3. Copilot will automatically load instructions from `.github/copilot-instructions.md`
4. Open Copilot Chat (Ctrl+Shift+I) and type:
```
BEGIN NEW PROJECT
```
### Method 4: ChatGPT or other LLM
1. Download the content of `BABOK_AGENT/LLM_BABOK_AGENT/BABOK_Agent_LLM_Prompt.md` file
2. In ChatGPT: Settings -> "Custom Instructions" or "System Prompt"
3. Paste the file content as system instructions
4. Start a new conversation and type:
```
BEGIN NEW PROJECT
```
### Method 5: API (Anthropic, OpenAI, others)
Use the content of `BABOK_Agent_LLM_Prompt.md` as the `system` parameter in the API call:
```python
import anthropic
client = anthropic.Anthropic()
with open("BABOK_AGENT/LLM_BABOK_AGENT/BABOK_Agent_LLM_Prompt.md") as f:
system_prompt = f.read()
message = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=8192,
system=system_prompt,
messages=[{"role": "user", "content": "BEGIN NEW PROJECT"}]
)
```
---
## BABOK CLI Tool
The repository includes a **cross-platform CLI tool** for managing project lifecycle directly from the terminal. The CLI handles project creation, state tracking via journal files, stage management, and **interactive AI chat** with multiple LLM providers — independently of any specific AI platform.
### Installation
Requires **Node.js 18+**.
**Option A — one-click installer (recommended for non-technical users):**
```bat
# Windows
setup.bat
# Linux / macOS
chmod +x setup.sh && ./setup.sh
```
**Option B — manual:**
```bash
git clone https://github.com/GSkuza/BABOK_ANALYST.git
cd BABOK_ANALYST/cli
npm install
npm link # Makes 'babok' command available globally
```
After manual install, run the setup wizard for first-time configuration:
```bash
babok setup
```
### CLI Commands
| Command | Description |
|---------|-------------|
| `babok setup` | **First-time setup wizard** — API keys, language, optional first project |
| `babok new [--name "Name"]` | Create a new project with unique ID and timestamp |
| `babok list` | List all projects with current status |
| `babok status [id]` | Show detailed project status (all stages) |
| `babok load <id>` | Load project context (generates text to paste into AI chat) |
| `babok save <id>` | Save current project state snapshot |
| `babok rename <id> [new-name]` | Rename a project |
| `babok delete <id>` | Permanently delete a project with confirmation |
| `babok approve <id> <stage>` | Mark a stage as approved, advance to next (stages 0–8) |
| `babok reject <id> <stage> -r "reason"` | Reject a stage with reason |
| `babok diff <id> [--stage N]` | Show stage history and deliverable preview |
| `babok diff <id1> <id2> [--stage N]` | Line diff between two projects' deliverables |
| `babok export <id>` | Export project deliverables to output directory |
| `babok chat <id>` | **Interactive AI chat** for current stage |
| `babok run [--context file.json]` | **Automated 8-stage pipeline** (interactive or `--auto`) |
| `babok run --diagram` | Run pipeline with auto-generated Mermaid process diagrams (NEW v2.1.0) |
| `babok ingest <file>` | **Ingest a document** (PDF/DOCX/XLSX/CSV/TXT/MD) into the project (NEW v2.1.0) |
| `babok score <id> <stage\|all>` | **Quality score** for a stage or all stages (NEW v2.1.0) |
| `babok validate <id>` | **Cross-stage consistency validation** — 6 built-in rules (NEW v2.1.0) |
| `babok sd product create --name "..." --repo host:owner:name[:role]` | **Software-development profile**: create a durable product with its repositories |
| `babok sd baseline build <productId>` | Autonomously build an evidence-backed Stage 1 baseline from the product's repositories (read-only; GitHub/GitLab) |
| `babok sd exec authorize <initiativeId> --scope run_tests --commands node --dirs <dir> --by "Name"` | Record the **explicit, separate** authorisation required before running an analysed repository's own commands |
| `babok sd exec run <initiativeId> <command> [args...] --cwd <dir>` | Run one authorised, whitelisted command and report its real exit code |
| `babok make docx <id>` | Generate DOCX document(s) from stage files |
| `babok make pdf <id>` | Generate PDF document(s) from stage files |
| `babok make all <id>` | Generate DOCX + PDF in one run |
| `babok llm list` | List all available AI models |
| `babok llm change` | Interactively switch AI provider/model |
| `babok routing show\|resolve\|set\|unset\|failover\|reset` | **Advanced model routing** per profile and stage (model, temperature, effort, fallbacks) — see [Advanced model routing](#advanced-model-routing) |
| `babok run --no-routing` / `babok chat <id> --no-routing` | Ignore `.babok_model_routing.json` and use the single selected provider |
| `babok lang [EN\|PL]` | Set or show interface language |
### Stage diff
Inspect and compare deliverables directly from the terminal:
```bash
# Show stage history + deliverable preview for a single project
babok diff K7M3
babok diff K7M3 --stage 3
# Line-by-line diff between two project versions (e.g. rejected vs reworked)
babok diff K7M3 R9TN
babok diff K7M3 R9TN --stage 4 --context 5
```
The two-project diff uses LCS to produce colored `+` / `-` output — no external tools needed.
---
### Document export (DOCX/PDF)
In addition to raw Markdown exports, the CLI can generate **CEO-ready DOCX and PDF** documents directly from stage files:
```bash
# DOCX only
babok make docx <project_id>
babok make docx <project_id> --stage 1 # only Stage 1
# PDF only
babok make pdf <project_id>
# DOCX + PDF in one run
babok make all <project_id>
```
- Works on `STAGE_XX_*.md` files generated by the agent
- Applies professional corporate styling (tables, headings, headers/footers)
- Default output directory: `<project_dir>/exports` (configurable via `--output`)
### Quick Example
```bash
# First-time setup
babok setup
# Create a new project
babok new --name "ERP Integration"
# Output: Project ID: BABOK-20260208-K7M3
# Check all projects
babok list
# Approve Stage 1 after completing it in AI chat
babok approve K7M3 1
# View detailed status
babok status K7M3
# Load context for AI chat (copy & paste the output)
babok load K7M3
# Start interactive AI chat for current stage
babok chat K7M3
# Rename a project
babok rename K7M3 "ERP Integration v2"
# Delete a project (prompts confirmation)
babok delete K7M3
# Export deliverables when done
babok export K7M3
```
Partial IDs work — `babok status K7M3` matches `BABOK-20260208-K7M3`.
For the full CLI guide, see: [`cli/README.md`](cli/README.md)
---
## Document Ingestion (`babok ingest`) — NEW in v2.1.0
The `babok ingest` command allows you to feed existing documents into a project so the AI agent can use them as context during analysis. Supported formats: **PDF, DOCX, XLSX, CSV, TXT, MD**.
```bash
# Ingest a supplier contract into a project
babok ingest path/to/contract.pdf --project K7M3
# Ingest an Excel data export
babok ingest data_export.xlsx --project K7M3
```
- Documents are parsed and classified by the LLM automatically
- Ingested files are listed in `babok status` output
- Source: `cli/src/commands/ingest.js` + `cli/src/lib/document-parser.js`
---
## Quality Scoring & Cross-Stage Validation — NEW in v2.1.0
### `babok score` — Stage Quality Scorer
Scores a deliverable (or all stages) against a rubric with three dimensions:
| Dimension | Weight | What It Checks |
|-----------|--------|----------------|
| **Completeness** | 40% | All required sections present |
| **SMART quality** | 30% | Numeric targets, dates, currencies, ROI present...
© Grzegorz Skuza · MIT · hashgraph-online/awesome-codex-plugins