KB Workflow Engine

A governed documentation operations system for internal knowledge-base workflows. Built on the DOE framework: Directives, Orchestration, and Execution.

---

Setup

Prerequisites

• Python 3.9+ (for future scripting and integrations)
• Git

Installation

git clone <repo-url>
cd "KB Workflow Engine"

Environment configuration

cp .env.example .env

Open .env and fill in your credentials. See Environment Variables below for what each value controls. Never commit .env — it is gitignored.

Optional: Python virtual environment

python -m venv venv
source venv/bin/activate   # macOS/Linux
# venv\Scripts\activate    # Windows

---

Environment Variables

Variable	Purpose
SYSTEM_ENV	Runtime environment (development / production)
LOG_LEVEL	Logging verbosity (DEBUG, INFO, WARNING, ERROR)
GOOGLE_API_KEY	Google Drive and Docs API access
GMAIL_CLIENT_ID / GMAIL_CLIENT_SECRET	Gmail OAuth credentials
LINKEDIN_CLIENT_ID / LINKEDIN_CLIENT_SECRET	LinkedIn OAuth credentials
GITHUB_TOKEN	GitHub API access
SUPABASE_URL / SUPABASE_KEY	Supabase database (future)
JIRA_BASE_URL / JIRA_API_TOKEN	Jira integration (future)

---

Usage

This system operates through structured AI-assisted workflows. All workflows require human approval before any file is modified or published.

To start a workflow:

1. Open this project in Claude Code
2. State your request
3. The system routes to the appropriate workflow and proposes actions for your approval

All new knowledge assets begin with Workflow 00. Submit any new document, notes, or source material through the intake workflow before any retrieval, generation, or improvement workflow is initiated. The intake workflow validates the material, analyzes KB relevance, surfaces gaps, and proposes a specific documentation action — all before touching the KB.

Workflow lifecycle:

Knowledge Intake (00) → Retrieval (01) → Generation (02) → Improvement (03)

Request	Workflow
Submit a new document, notes, or source material	Knowledge Intake — /orchestration/workflow_00_knowledge_intake.md
Search, lookup, research, gap analysis	Knowledge Retrieval — /orchestration/workflow_01_knowledge_retrieval.md
Create a new KB article	Article Generation — /orchestration/workflow_02_article_generation.md
Improve or review an existing article	KB Improvement — /orchestration/workflow_03_kb_improvement.md

---

Runtime Loading Model

The DOE framework operates in a defined loading order. Each layer depends on the one above it.

1. Directives load first. Governance rules, standards, and tone requirements are loaded before any workflow begins. They define what the system is and is not permitted to do.
2. Orchestration determines coordination. The orchestration file for the active workflow is loaded next. It specifies the trigger conditions, the execution tasks to invoke, and the approval checkpoints that govern the workflow.
3. Execution modules perform concrete tasks. Execution files are invoked by orchestration — never directly. Each module performs a single, bounded operational task (e.g., validate source material, draft an email, write a log entry).
4. Workflows execute one stage at a time. The system does not run stages in batch. Each stage completes, outputs are reviewed, and the workflow advances explicitly.
5. Approval is required before irreversible actions. The system pauses at defined checkpoints. No file is created or modified, no email is sent, and no KB action is taken without explicit operator authorization.

---

DOE Framework

The system is organized into three operational layers.

/directives

Governance rules and documentation standards. These files define what the system must and must not do. Loaded at the start of each workflow.

File	Purpose
governance.md	Approval model, human-in-the-loop rules, source integrity, error handling
email_notification_rules.md	Outbound notification types, draft-first rule, and approval requirement for all emails
kb_style_guide.md	Article structure, formatting, and heading conventions
metadata_rules.md	Required and optional metadata fields, tagging guidelines
taxonomy_rules.md	Content type and topic domain classification
tone_rules.md	Voice, language rules, tone by content type

---

/orchestration

Workflow routing files. These files define how to coordinate a workflow — triggers, inputs, which execution tasks to invoke, approval checkpoints, and routing logic.

File	Purpose
workflow_00_knowledge_intake.md	Entry workflow for all new knowledge assets — validate, classify, analyze, propose actions
workflow_01_knowledge_retrieval.md	Route and coordinate KB search and research requests
workflow_02_article_generation.md	Route and coordinate new article drafting
workflow_03_kb_improvement.md	Route and coordinate article review and improvement

---

/execution

Concrete operational task files. These files define how to perform a specific task — step-by-step procedures invoked by orchestration workflows.

Execution modules are narrow, reusable, and single-purpose. Each file performs one bounded task and should not be invoked directly — orchestration files determine when and in what order they run.

File	Purpose
validate_source_material.md	Assess usability and completeness of submitted source material
classify_content_type.md	Assign content type and topic domain using taxonomy
analyze_kb_relevance.md	Determine how incoming material relates to existing KB content
identify_kb_impact.md	Map which existing articles are affected and how
identify_missing_information.md	Surface gaps in source material that would affect documentation quality
propose_documentation_actions.md	Compile intake analysis into a ranked, approvable action plan
draft_email_notification.md	Compose a governed email draft for operator review
log_workflow_event.md	Write a structured log entry for a workflow event
search_kb.md	Conduct a structured KB search
generate_article.md	Draft a new KB article from source material
improve_article.md	Review and improve an existing KB article
assign_metadata.md	Propose metadata and taxonomy for an article

---

/memory

Runtime support files. Track operational state across sessions.

File	Purpose
memory.md	Stable preferences, conventions, long-term context
decisions.md	Architectural and governance decisions
current_state.md	Active work, pending approvals, unfinished workflows

---

/logs

Operational audit trail. One log file per significant workflow execution, named by date (YYYY-MM-DD_description.md).

---

/templates

Reusable blank content structures.

File	Purpose
kb_article_template.md	Blank KB article ready to fill in

---

System Entrypoint

See CLAUDE.md for system purpose, DOE architecture overview, workflow routing guide, and approval requirements.

---

Governance

All workflows require human approval before any file is modified, created, or published. See /directives/governance.md.