intake-ai-cli 0.1.0__tar.gz

intake_ai_cli-0.1.0/.gitignore

@@ -0,0 +1,96 @@
+# build output
+dist/
+
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+.venv/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Config files con datos sensibles
+config.yaml
+*.local.yaml
+.env
+.env.local
+
+# Logs
+logs/
+*.log
+*.jsonl
+
+tmp/
+CLAUDE.md
+.coverage
+
+__pycache__/

intake_ai_cli-0.1.0/.intake.yaml.example

@@ -0,0 +1,55 @@
+# intake configuration
+# Copy this file to .intake.yaml and customize as needed.
+# All values shown below are the defaults — only override what you need.
+#
+# Configuration priority (highest wins):
+#   CLI flags > .intake.yaml > preset > hardcoded defaults
+
+# LLM settings for requirement analysis
+llm:
+  model: claude-sonnet-4           # Any model supported by LiteLLM
+  api_key_env: ANTHROPIC_API_KEY     # Environment variable holding the API key
+  max_cost_per_spec: 0.50           # Budget limit per spec generation (USD)
+  temperature: 0.2                   # Lower = more deterministic
+  max_retries: 3                     # Retry count on LLM failures
+  timeout: 120                       # Timeout per LLM call (seconds)
+
+# Project metadata
+project:
+  name: ""                           # Auto-detected from description if empty
+  stack: []                          # Auto-detected from project files if empty
+  language: en                       # Language for generated spec content
+  conventions: {}                    # Custom conventions: { "testing": "pytest", ... }
+
+# Spec generation settings
+spec:
+  output_dir: ./specs                # Where to write generated specs
+  requirements_format: ears          # ears | user-stories | bdd | free
+  design_depth: moderate             # minimal | moderate | detailed
+  task_granularity: medium           # coarse | medium | fine
+  include_sources: true              # Include source traceability in spec
+  version_specs: true                # Create versioned spec directories
+  generate_lock: true                # Generate spec.lock.yaml for reproducibility
+  risk_assessment: true              # Include risk matrix in analysis
+
+# Verification settings
+verification:
+  auto_generate_tests: true          # Generate acceptance checks from requirements
+  test_output_dir: ./tests/generated # Where to write generated tests
+  checks: []                         # Additional custom checks
+  timeout_per_check: 120             # Timeout per acceptance check (seconds)
+
+# Export settings
+export:
+  default_format: generic            # architect | generic (claude-code, cursor, kiro: planned)
+  architect_include_guardrails: true # Include guardrails in architect pipeline
+  architect_pipeline_template: standard
+  claude_code_generate_claude_md: true
+
+# Security settings
+security:
+  redact_patterns: []                # Regex patterns to redact from spec output
+  redact_files:                      # File patterns to never include
+    - "*.env"
+    - "*.pem"
+    - "*.key"

intake_ai_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-02
+
+### Added
+
+#### Phase 1 — Ingest (8 parsers + registry)
+
+- **Project scaffolding**: `pyproject.toml` with hatchling build system, `src/intake/` package layout with 10 subpackages.
+- **CLI framework**: Click-based CLI with 8 commands (`init`, `add`, `verify`, `export`, `show`, `list`, `diff`, `doctor`).
+- **`intake doctor` command**: Full environment health check — validates Python version (3.12+), LLM API keys, optional dependencies (pdfplumber, python-docx, bs4, markdownify, litellm, jinja2), and `.intake.yaml` config validity. Outputs a Rich table with PASS/FAIL status and fix hints.
+- **Configuration system**: Pydantic v2 models for all config (`LLMConfig`, `ProjectConfig`, `SpecConfig`, `VerificationConfig`, `ExportConfig`, `SecurityConfig`). Layered merge: defaults → preset → `.intake.yaml` → CLI flags.
+- **Configuration presets**: `--preset minimal|standard|enterprise` for quick setup. Minimal is cheap/fast for prototyping, standard is balanced, enterprise is detailed with full traceability.
+- **8 input parsers** — all producing normalized `ParsedContent`:
+  - `MarkdownParser` — `.md` files with YAML front matter support and heading-based section extraction.
+  - `PlaintextParser` — `.txt` files, stdin (`-`), Slack thread dumps. Paragraph-level sections.
+  - `YamlInputParser` — `.yaml`/`.yml`/`.json` structured requirements. Section extraction from top-level keys.
+  - `PdfParser` — `.pdf` files via pdfplumber. Text + table extraction (tables converted to Markdown).
+  - `DocxParser` — `.docx` files via python-docx. Text, tables, heading-based sections, document metadata (author, title, date).
+  - `JiraParser` — Jira JSON exports (both `{"issues":[...]}` API format and `[{"key":...}]` list format). Extracts issues with summary, description, comments (last 5), labels, priority, status, and inter-issue links.
+  - `ConfluenceParser` — Confluence HTML exports via BeautifulSoup4 + markdownify. Detects Confluence markers, extracts main content, converts to clean Markdown.
+  - `ImageParser` — `.png`/`.jpg`/`.jpeg`/`.webp`/`.gif` via injectable LLM vision callable. Ships with a stub; real vision analysis enabled when LLM adapter is configured.
+- **Parser registry**: `ParserRegistry` with automatic format detection by file extension and content inspection. JSON subtype detection (Jira vs generic), HTML subtype detection (Confluence vs generic). Factory function `create_default_registry()` registers all 8 parsers.
+- **Utilities**:
+  - `file_detect.py` — Extension-based format detection with `EXTENSION_MAP`.
+  - `project_detect.py` — Auto-detects project tech stack from 20+ marker files (pyproject.toml, package.json, Dockerfile, etc.) and content patterns (fastapi, django, react, etc.).
+  - `cost.py` — `CostTracker` for LLM cost accumulation with per-phase breakdown.
+  - `logging.py` — structlog configuration with console/JSON rendering.
+
+#### Phase 2 — Analyze (LLM orchestration)
+
+- **LLM Adapter** (`llm/adapter.py`): LiteLLM wrapper with async completion, retry with exponential backoff, cost tracking per call, budget enforcement (`CostLimitError`), JSON response parsing with markdown fence stripping, API key validation. Custom exceptions: `LLMError`, `CostLimitError`, `APIKeyMissingError`.
+- **Analysis pipeline** (`analyze/`):
+  - `analyzer.py` — Orchestrator: coordinates extraction → deduplication → conflict validation → risk assessment → design phases. Supports multi-source analysis with automatic text combining.
+  - `prompts.py` — Three system prompts: `EXTRACTION_PROMPT` (requirements, conflicts, questions), `RISK_ASSESSMENT_PROMPT` (risk analysis per requirement), `DESIGN_PROMPT` (architecture, tasks, acceptance checks).
+  - `extraction.py` — Parses LLM JSON output into typed `AnalysisResult` with requirements, conflicts, and open questions.
+  - `dedup.py` — Jaccard word similarity deduplication across sources (threshold: 0.75).
+  - `conflicts.py` — Validates extracted conflicts, filters incomplete entries.
+  - `questions.py` — Validates extracted open questions, filters incomplete entries.
+  - `risks.py` — Parses LLM risk assessment into typed `RiskItem` list.
+  - `design.py` — Parses LLM design output into `DesignResult` with components, file actions, tasks, and acceptance checks.
+  - `models.py` — 10 dataclasses: `Requirement`, `Conflict`, `OpenQuestion`, `RiskItem`, `TechDecision`, `TaskItem`, `FileAction`, `AcceptanceCheck`, `DesignResult`, `AnalysisResult`.
+
+#### Phase 3 — Generate (spec files + lock)
+
+- **Generation module** (`generate/`):
+  - `spec_builder.py` — Orchestrates rendering of 6 spec files via Jinja2 templates + optional `spec.lock.yaml`.
+  - `lock.py` — `SpecLock` dataclass with SHA-256 source/spec hashing, staleness detection, YAML serialization. `create_lock()` factory function.
+- **6 Jinja2 templates** (`templates/`): `requirements.md.j2`, `design.md.j2`, `tasks.md.j2`, `acceptance.yaml.j2`, `context.md.j2`, `sources.md.j2`.
+
+#### Phase 4 — Verify (acceptance check engine)
+
+- **Verification engine** (`verify/engine.py`): Runs acceptance.yaml checks against a project directory. Four check types: `command` (shell exit code), `files_exist` (path checks), `pattern_present` (regex in files), `pattern_absent` (forbidden patterns). Tag-based filtering, fail-fast mode, configurable timeout per check. `VerifyError` exception with reason + suggestion.
+- **Report formatters** (`verify/reporter.py`):
+  - `TerminalReporter` — Rich table with colors, pass/fail status, duration, details.
+  - `JsonReporter` — Machine-readable JSON output.
+  - `JunitReporter` — JUnit XML for CI integration (GitHub Actions, Jenkins, etc.).
+  - `Reporter` Protocol with `@runtime_checkable` for extensibility.
+
+#### Phase 5 — Export (agent-ready output)
+
+- **Exporter framework** (`export/`):
+  - `base.py` — `Exporter` Protocol with `@runtime_checkable` for structural subtyping.
+  - `registry.py` — `ExporterRegistry` with format-based dispatch. Factory function `create_default_registry()` registers both built-in exporters.
+- **Architect exporter** (`export/architect.py`): Generates `pipeline.yaml` with one step per task, checkpoint flags, project context injection, final verification step with required command checks. Copies all spec files to `output/spec/`.
+- **Generic exporter** (`export/generic.py`): Generates `SPEC.md` (consolidated Markdown with all spec sections), `verify.sh` (executable bash script with `check()` helper, `set -euo pipefail`, exit code reporting). Copies all spec files to `output/spec/`.
+
+#### Spec differ
+
+- **Diff module** (`diff/differ.py`): Compares two spec versions by extracting sections from Markdown headings (FR/NFR IDs, task numbers) and acceptance check IDs. Reports added, removed, and modified items per section. `SpecDiff` dataclass with `added`, `removed`, `modified`, `has_changes` properties. `DiffError` exception.
+
+#### CLI — Full pipeline wiring
+
+- **`intake init`**: End-to-end pipeline: ingest → analyze → generate → (optional) export. Auto-detects tech stack, slugifies description for directory name, `--dry-run` support.
+- **`intake add`**: Incremental source addition to existing spec. Parses new sources, re-analyzes, regenerates spec files.
+- **`intake verify`**: Loads `acceptance.yaml`, runs checks via `VerificationEngine`, displays report in chosen format (terminal/json/junit), exits with semantic code (0/1/2).
+- **`intake export`**: Exports spec to chosen format via `ExporterRegistry`.
+- **`intake show`**: Displays spec summary from `spec.lock.yaml` (model, cost, counts) and file listing.
+- **`intake list`**: Scans specs directory for valid spec subdirectories, shows table with metadata from lock files.
+- **`intake diff`**: Compares two spec directories, shows Rich table with added/removed/modified items.
+
+#### Test suite
+
+- **313 tests**, **83% overall coverage**. 7 realistic fixture files (Markdown, plaintext, YAML, Jira JSON x2, Confluence HTML, PNG image).
+
+#### Documentation and examples
+
+- **`.intake.yaml.example`**: Fully documented configuration example with all options and defaults.
+- **4 example projects** in `examples/`: `from-markdown`, `from-jira`, `from-scratch`, `multi-source` — each with README and realistic source files.
+
+#### Error hardening
+
+- **`EmptySourceError`** and **`FileTooLargeError`** exceptions for better error messages on edge cases.
+- **`validate_file_readable()`** and **`read_text_safe()`** utilities — centralized file validation with UTF-8 → latin-1 encoding fallback, size limits (50MB), and empty file detection.
+- All 8 parsers updated to use hardened file validation utilities.
+- 16 new hardening tests covering empty files, encoding fallback, size limits, and directory rejection.
+
+#### Doctor --fix
+
+- **`intake doctor --fix`** command: auto-installs missing Python packages and creates default `.intake.yaml` configuration.
+- `FixResult` dataclass for structured fix result reporting.
+- `_find_pip()` detects `pip3.12`, `pip3`, or `pip` for package installation.
+- `IMPORT_TO_PIP` mapping for correct PyPI package names (e.g., `bs4` → `beautifulsoup4`, `docx` → `python-docx`).
+
+#### Code quality
+
+- **0 ruff errors**: Fixed 88 lint issues (TC001/TC003, F401, I001, SIM103, RUF022, E501, SIM117, RUF043).
+- **0 mypy --strict errors**: Fixed 26 type errors across 12 files. Proper isinstance narrowing, type-safe dict extraction, correct bool return types.
+
+### Fixed
+
+- **structlog test isolation**: Replaced `StringIO` sink with persistent `_NullWriter` class and yield-based autouse fixture. Fixed `cache_logger_on_first_use=True` in `setup_logging()` that caused "I/O operation on closed file" errors when CLI tests ran before module tests.
+- **`_get_list` type safety**: Split into `_get_list` (for dict lists) and `_get_str_list` (for string lists) to fix mypy --strict without breaking acceptance criteria extraction.
+- **bs4 `find()` kwargs**: Changed `**selector` to `attrs=selector` in Confluence parser for correct BeautifulSoup4 type narrowing.
+

intake_ai_cli-0.1.0/PKG-INFO

@@ -0,0 +1,365 @@
+Metadata-Version: 2.4
+Name: intake-ai-cli
+Version: 0.1.0
+Summary: From requirements in any format to verified implementation
+Author: intake contributors
+License: MIT
+Keywords: ai,automation,cli,requirements,spec-driven
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: litellm>=1.40
+Requires-Dist: markdownify>=0.13
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-docx>=1.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: structlog>=24.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-beautifulsoup4>=4.12; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# intake
+
+> From requirements in any format to verified implementation.
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**intake** is an open-source CLI tool that acts as a universal bridge between real-world requirements and AI coding agents. It accepts requirements from multiple sources and formats — Jira exports, Confluence pages, PDFs, Markdown, YAML, images, DOCX, free text — and transforms them into a normalized, verifiable spec that any AI agent can consume.
+
+It's not an IDE. It's not an agent. It doesn't generate code. intake is **preparation infrastructure**: the missing step between "we have some requirements somewhere" and "an agent implements with automatic verification."
+
+```
+intake = Chaotic requirements (N sources, N formats) → Executable spec → Any AI agent
+```
+
+---
+
+## How It Works
+
+```
+INGEST (parsers) → ANALYZE (LLM) → GENERATE (spec files) → VERIFY (acceptance checks) → EXPORT (agent-ready output)
+```
+
+intake processes requirements through a 5-phase pipeline:
+
+1. **Ingest** — Parse any input format into normalized `ParsedContent`
+2. **Analyze** — LLM extracts structured requirements, detects conflicts, deduplicates
+3. **Generate** — Produce 6 spec files + `spec.lock.yaml`
+4. **Verify** — Run executable acceptance checks against the implementation
+5. **Export** — Generate agent-ready output (architect, Claude Code, Cursor, generic)
+
+### The 6 Spec Files
+
+| File | Purpose |
+|------|---------|
+| `requirements.md` | What to build. Functional and non-functional requirements in EARS format. |
+| `design.md` | How to build it. Architecture, interfaces, technical decisions. |
+| `tasks.md` | In what order. Atomic tasks with dependencies. |
+| `acceptance.yaml` | How to verify. Executable checks: commands, patterns, file existence. |
+| `context.md` | Project context for the agent: stack, conventions, current state. |
+| `sources.md` | Full traceability: every requirement mapped to its original source. |
+
+---
+
+## Installation
+
+```bash
+pip install intake-ai-cli
+```
+
+Requires Python 3.12+. The CLI command is `intake`.
+
+### Development Setup
+
+```bash
+git clone https://github.com/your-org/intake-cli.git
+cd intake-cli
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```bash
+# Check your environment
+intake doctor
+
+# Generate a spec from a single source
+intake init "OAuth2 authentication system" -s requirements.md
+
+# Generate from multiple sources
+intake init "Payments feature" -s jira.json -s confluence.html -s notes.md
+
+# Use a preset for quick configuration
+intake init "API gateway" -s reqs.yaml --preset enterprise
+
+# Export for a specific agent
+intake init "User endpoint" -s reqs.pdf --format architect
+```
+
+---
+
+## Supported Input Formats
+
+| Format | Extensions | Parser |
+|--------|-----------|--------|
+| Markdown | `.md` | Front matter, heading-based sections |
+| Plain text | `.txt`, stdin (`-`) | Paragraph sections, Slack dumps |
+| YAML / JSON | `.yaml`, `.yml`, `.json` | Structured requirements |
+| PDF | `.pdf` | Text + tables via pdfplumber |
+| DOCX | `.docx` | Text, tables, headings, metadata via python-docx |
+| Jira export | `.json` (auto-detected) | Issues, comments, links, priorities |
+| Confluence export | `.html` (auto-detected) | Clean Markdown via BS4 + markdownify |
+| Images | `.png`, `.jpg`, `.webp`, `.gif` | LLM vision analysis |
+
+Format is auto-detected by file extension and content inspection. Jira JSON exports and Confluence HTML exports are distinguished automatically from generic JSON/HTML files.
+
+---
+
+## Commands
+
+| Command | Description | Status |
+|---------|-------------|--------|
+| `intake init` | Generate a spec from requirement sources | **Available** |
+| `intake add` | Add sources to an existing spec (incremental) | **Available** |
+| `intake verify` | Verify implementation against the spec | **Available** |
+| `intake export` | Export spec to agent-ready format | **Available** |
+| `intake show` | Show spec summary | **Available** |
+| `intake list` | List all specs in the project | **Available** |
+| `intake diff` | Compare two spec versions | **Available** |
+| `intake doctor` | Check environment and configuration health | **Available** |
+| `intake doctor --fix` | Auto-fix environment issues (install deps, create config) | **Available** |
+
+---
+
+## Configuration
+
+intake works with zero configuration — only an LLM API key is needed. For customization, create a `.intake.yaml`:
+
+```yaml
+llm:
+  model: claude-sonnet-4
+  max_cost_per_spec: 0.50
+  temperature: 0.2
+
+project:
+  name: my-project
+  language: en
+
+spec:
+  output_dir: ./specs
+  requirements_format: ears    # ears | user-stories | bdd | free
+  design_depth: moderate       # minimal | moderate | detailed
+  task_granularity: medium     # coarse | medium | fine
+  risk_assessment: true
+
+export:
+  default_format: generic      # architect | claude-code | cursor | kiro | generic
+```
+
+### Presets
+
+Skip the config file and use a preset:
+
+```bash
+intake init "My feature" -s reqs.md --preset minimal      # Fast, cheap, prototyping
+intake init "My feature" -s reqs.md --preset standard      # Balanced (default)
+intake init "My feature" -s reqs.md --preset enterprise    # Detailed, full traceability
+```
+
+### Configuration Priority
+
+```
+CLI flags > .intake.yaml > preset > hardcoded defaults
+```
+
+---
+
+## Examples
+
+See the [`examples/`](examples/) directory for ready-to-run scenarios:
+
+| Example | Description |
+|---------|-------------|
+| [`from-markdown`](examples/from-markdown/) | Single Markdown file with OAuth2 requirements |
+| [`from-jira`](examples/from-jira/) | Jira JSON export with 3 issues |
+| [`from-scratch`](examples/from-scratch/) | Free-text meeting notes |
+| [`multi-source`](examples/multi-source/) | Combining Markdown + Jira JSON + text notes |
+
+---
+
+## Architecture
+
+```
+src/intake/
+├── cli.py                  # Click CLI — thin adapter, no logic
+├── config/                 # Pydantic v2 models, presets, layered loader
+│   ├── schema.py           #   6 config models (LLM, Project, Spec, Verification, Export, Security)
+│   ├── presets.py           #   minimal / standard / enterprise presets
+│   ├── loader.py            #   Layered merge: defaults → preset → YAML → CLI
+│   └── defaults.py          #   Centralized constants
+├── ingest/                 # Phase 1 — 8 parsers, registry, auto-detection
+│   ├── base.py              #   ParsedContent dataclass + Parser Protocol
+│   ├── registry.py          #   Auto-detection + parser dispatch
+│   ├── markdown.py          #   .md with YAML front matter
+│   ├── plaintext.py         #   .txt, stdin, Slack dumps
+│   ├── yaml_input.py        #   .yaml/.yml/.json structured input
+│   ├── pdf.py               #   .pdf via pdfplumber
+│   ├── docx.py              #   .docx via python-docx
+│   ├── jira.py              #   Jira JSON exports (API + list format)
+│   ├── confluence.py        #   Confluence HTML via BS4 + markdownify
+│   └── image.py             #   Image analysis via LLM vision
+├── analyze/                # Phase 2 — LLM orchestration (async)
+│   ├── analyzer.py          #   Orchestrator: extraction → dedup → risk → design
+│   ├── prompts.py           #   3 system prompts (extraction, risk, design)
+│   ├── models.py            #   10 dataclasses for analysis pipeline
+│   ├── extraction.py        #   LLM JSON → typed AnalysisResult
+│   ├── dedup.py             #   Jaccard word similarity deduplication
+│   ├── conflicts.py         #   Conflict validation
+│   ├── questions.py         #   Open question validation
+│   ├── risks.py             #   Risk assessment parsing
+│   └── design.py            #   Design output parsing (tasks, checks)
+├── generate/               # Phase 3 — Jinja2 template rendering
+│   ├── spec_builder.py      #   Orchestrates 6 spec files + lock
+│   └── lock.py              #   spec.lock.yaml for reproducibility
+├── verify/                 # Phase 4 — Acceptance check engine
+│   ├── engine.py           #   4 check types: command, files_exist, pattern_*
+│   └── reporter.py         #   Terminal (Rich), JSON, JUnit XML reporters
+├── export/                 # Phase 5 — Agent-ready output
+│   ├── base.py             #   Exporter Protocol
+│   ├── registry.py         #   Format-based exporter dispatch
+│   ├── architect.py        #   pipeline.yaml generation
+│   └── generic.py          #   SPEC.md + verify.sh generation
+├── diff/                   # Spec comparison
+│   └── differ.py           #   Compare two specs by requirement/task IDs
+├── doctor/                 # Environment health checks
+│   └── checks.py            #   Python, API keys, deps, config validation
+├── llm/                    # LiteLLM wrapper (used by analyze/ only)
+│   └── adapter.py           #   Async completion, retry, cost tracking, budget
+├── templates/              # Jinja2 templates for spec generation
+│   ├── requirements.md.j2   #   FR, NFR, conflicts, open questions
+│   ├── design.md.j2         #   Components, files, tech decisions
+│   ├── tasks.md.j2          #   Task summary + detailed sections
+│   ├── acceptance.yaml.j2   #   Executable acceptance checks
+│   ├── context.md.j2        #   Project context for agents
+│   └── sources.md.j2        #   Source traceability mapping
+└── utils/                  # Shared utilities (logging, cost, detection)
+    ├── file_detect.py       #   Extension-based format detection
+    ├── project_detect.py    #   Auto-detect tech stack from project files
+    ├── cost.py              #   Cost accumulation with per-phase breakdown
+    └── logging.py           #   structlog configuration
+```
+
+**Key design principles:**
+
+- **Protocol over ABC** — All extension points use `typing.Protocol`
+- **Dataclasses for pipeline data, Pydantic for config** — Never mixed
+- **Async only in analyze/** — Everything else is synchronous
+- **Offline mode** — Parsing, verification, export, diff, doctor all work without LLM
+- **No magic strings** — All constants defined explicitly
+- **Budget enforcement** — LLM cost tracked per call with configurable limits
+
+---
+
+## Integration
+
+### With architect
+
+```bash
+intake init "Auth system" -s reqs.md --format architect
+architect pipeline specs/auth-system/pipeline.yaml
+```
+
+### With Claude Code
+
+```bash
+intake init "Payments" -s reqs.pdf --format claude-code
+# Generates CLAUDE.md + tasks + verify.sh
+```
+
+### With CI/CD
+
+```yaml
+# GitHub Actions
+- name: Verify spec compliance
+  run: |
+    pip install intake-ai-cli
+    intake verify specs/auth-system/ -p . --format junit
+```
+
+---
+
+## Development
+
+```bash
+# Run tests
+python -m pytest tests/ -v
+
+# Run tests with coverage
+python -m pytest tests/ --cov=intake --cov-report=term-missing
+
+# Lint
+ruff check src/ tests/
+
+# Type check (strict)
+mypy src/ --strict
+```
+
+Current test suite: **313 tests**, **83% coverage**.
+
+### Implementation Status
+
+| Phase | Module | Status |
+|-------|--------|--------|
+| Phase 1 — Ingest | `ingest/` (8 parsers + registry) | Implemented |
+| Phase 2 — Analyze | `analyze/` (orchestrator + 7 sub-modules) | Implemented |
+| Phase 3 — Generate | `generate/` (spec builder + 6 templates + lock) | Implemented |
+| Phase 4 — Verify | `verify/` (engine + 3 reporters) | Implemented |
+| Phase 5 — Export | `export/` (architect + generic) | Implemented |
+| Standalone | `doctor/`, `config/`, `llm/`, `utils/` | Implemented |
+| Standalone | `diff/` (spec differ) | Implemented |
+| CLI | All 8 commands wired end-to-end | Implemented |
+
+---
+
+## Model Support
+
+intake uses [LiteLLM](https://github.com/BerriAI/litellm) for LLM abstraction, supporting 100+ models:
+
+- **Anthropic**: Claude Sonnet, Claude Opus, Claude Haiku
+- **OpenAI**: GPT-4o, GPT-4, GPT-3.5
+- **Google**: Gemini Pro, Gemini Flash
+- **Local models**: Ollama, vLLM, etc.
+
+Set your API key:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# or
+export OPENAI_API_KEY=sk-...
+```
+
+---
+
+## License
+
+MIT