# Document Templates & Generation

This file describes the document generation process, template variables, and skills installation.

## Generated Documents Overview

```yaml
generated_documents:
  AGENT.md:
    location: ".quaestor/AGENT.md"
    source: "src/quaestor/agent.md"
    processing: "Copy template as-is"
    purpose: "AI behavioral rules and workflow enforcement"

  ARCHITECTURE.md:
    location: ".quaestor/ARCHITECTURE.md"
    source: "src/quaestor/architecture.md"
    processing: "Jinja2 template with variable substitution"
    purpose: "Project architecture, patterns, and quality standards"

  CLAUDE.md:
    location: "CLAUDE.md" (project root)
    source: "src/quaestor/include.md"
    processing: "Merge with existing or create new"
    purpose: "Main entry point with Quaestor configuration"
```

## ARCHITECTURE.md Template Variables

ARCHITECTURE.md uses Jinja2 templating with variables populated from detected language config:

### Section 1: Project Configuration

```yaml
template_variables:
  project_name: "[Detected from directory name or git config]"
  project_type: "[Detected from framework: web-api, web-app, library, cli, etc.]"
  language_display_name: "[Human-readable: Python, TypeScript, Rust]"
  primary_language: "[Code: python, typescript, rust]"
  config_system_version: "2.0"
  strict_mode: "[true if complexity > 0.7, else false]"

  build_tool: "[Detected: cargo, npm, pip, gradle]"
  package_manager: "[Detected: cargo, npm/yarn, pip/poetry, maven]"
  language_server: "[Optional: pyright, rust-analyzer, tsserver]"
  virtual_env: "[Optional: venv, conda, nvm]"
  dependency_management: "[Detected from package files]"
```

### Section 3: Code Quality Standards

These variables are populated from `src/quaestor/core/languages.yaml`:

```yaml
quality_standards:
  lint_command: "{{ lint_command }}"           # e.g., "ruff check ."
  format_command: "{{ format_command }}"       # e.g., "ruff format ."
  test_command: "{{ test_command }}"           # e.g., "pytest"
  coverage_command: "{{ coverage_command }}"   # e.g., "pytest --cov"
  type_check_command: "{{ type_check_command }}" # e.g., "mypy ."

  quick_check_command: "{{ quick_check_command }}"
  # e.g., "ruff check . && pytest -x"

  full_check_command: "{{ full_check_command }}"
  # e.g., "ruff check . && ruff format --check . && mypy . && pytest"

  code_formatter: "{{ code_formatter }}"           # e.g., "ruff"
  testing_framework: "{{ testing_framework }}"     # e.g., "pytest"
  coverage_threshold_percent: "{{ coverage_threshold_percent }}" # e.g., ">= 80%"
```

### Section 6: Security & Performance

```yaml
security_performance:
  has_security_scanner: "{{ has_security_scanner }}"    # "true" or "false"
  security_scan_command: "{{ security_scan_command }}"  # e.g., "bandit -r ."
  security_scanner: "{{ security_scanner }}"            # e.g., "bandit"

  has_profiler: "{{ has_profiler }}"                    # "true" or "false"
  profile_command: "{{ profile_command }}"              # e.g., "py-spy top"
  performance_budget: "{{ performance_budget }}"        # e.g., "< 200ms p95"
```

### Section 8: Quality Thresholds

```yaml
quality_thresholds:
  coverage_threshold_percent: "{{ coverage_threshold_percent }}"
  max_duplication: "{{ max_duplication }}"               # e.g., "3%"
  max_debt_hours: "{{ max_debt_hours }}"                 # e.g., "40 hours"
  max_bugs_per_kloc: "{{ max_bugs_per_kloc }}"           # e.g., "0.5"

  current_coverage: "{{ current_coverage }}"             # e.g., "0% (not yet measured)"
  current_duplication: "{{ current_duplication }}"       # e.g., "N/A"
  current_debt: "{{ current_debt }}"                     # e.g., "N/A"
  current_bug_density: "{{ current_bug_density }}"       # e.g., "N/A"
  main_config_available: "{{ main_config_available }}"   # true or false
```

### Section 10: Project Standards

```yaml
project_standards:
  max_build_time: "{{ max_build_time }}"             # e.g., "< 5 minutes"
  max_bundle_size: "{{ max_bundle_size }}"           # e.g., "< 250KB gzipped"
  memory_threshold: "{{ memory_threshold }}"         # e.g., "< 512MB"
  retry_configuration: "{{ retry_configuration }}"   # e.g., "3 retries with exponential backoff"
  fallback_behavior: "{{ fallback_behavior }}"       # e.g., "Fail gracefully with user message"
  rule_enforcement: "{{ rule_enforcement }}"         # e.g., "Enforced on commit (pre-commit hooks)"
  pre_edit_script: "{{ pre_edit_script }}"           # e.g., "ruff check"
  post_edit_script: "{{ post_edit_script }}"         # e.g., "ruff format"
```

## Variable Population Process

### Step 1: Detect Language
Use patterns from @DETECTION.md to identify primary language.

### Step 2: Load Language Config
```python
# Read src/quaestor/core/languages.yaml
# Extract section for detected language
# Example:
config = yaml.load("src/quaestor/core/languages.yaml")
lang_config = config[detected_language]  # e.g., config["python"]
```

### Step 3: Populate Template
```python
# Use Jinja2 to render template
from jinja2 import Template

template = Template(open("src/quaestor/architecture.md").read())
rendered = template.render(**lang_config, **project_metadata)
```

### Step 4: Write Output
```python
# Write to .quaestor/ARCHITECTURE.md
output_path = ".quaestor/ARCHITECTURE.md"
with open(output_path, "w") as f:
    f.write(rendered)
```

## Language-Specific Template Examples

### Python Project
```markdown
## 3. CODE QUALITY STANDARDS

### Linting and Formatting
- **Linter**: `ruff check .`
- **Formatter**: `ruff format .`
- **Code Formatter**: ruff
- **Quick Check**: `ruff check . && pytest -x`
- **Full Validation**: `ruff check . && ruff format --check . && mypy . && pytest`

### Testing Requirements
- **Test Runner**: `pytest`
- **Coverage**: `pytest --cov`
- **Coverage Threshold**: >= 80%
- **Testing Framework**: pytest
```

### TypeScript Project
```markdown
## 3. CODE QUALITY STANDARDS

### Linting and Formatting
- **Linter**: `eslint .`
- **Formatter**: `prettier --write .`
- **Code Formatter**: prettier
- **Quick Check**: `eslint . && npm test`
- **Full Validation**: `eslint . && prettier --check . && tsc --noEmit && npm test`

### Testing Requirements
- **Test Runner**: `npm test`
- **Coverage**: `npm run test:coverage`
- **Coverage Threshold**: >= 80%
- **Testing Framework**: jest
```

### Rust Project
```markdown
## 3. CODE QUALITY STANDARDS

### Linting and Formatting
- **Linter**: `cargo clippy`
- **Formatter**: `cargo fmt`
- **Code Formatter**: rustfmt
- **Quick Check**: `cargo clippy && cargo test`
- **Full Validation**: `cargo clippy && cargo fmt --check && cargo test`

### Testing Requirements
- **Test Runner**: `cargo test`
- **Coverage**: `cargo tarpaulin`
- **Coverage Threshold**: >= 75%
- **Testing Framework**: cargo test
```

## Skills Availability

All Quaestor skills are available via:
- **Plugin installation**: Skills loaded from the plugin package
- **CLI installation** (`uvx quaestor`): Skills loaded from the installed package

Skills are NOT copied to the project directory. They remain in the plugin/package and are accessed directly by Claude Code.

## CLAUDE.md Merging

### Merge Strategy

```yaml
claude_md_handling:
  if_exists:
    strategy: "Merge Quaestor config with existing content"
    process:
      - Check for existing QUAESTOR CONFIG markers
      - If found: Replace old config with new
      - If not found: Prepend Quaestor config to existing content
    preserve: "All user custom content"

  if_not_exists:
    strategy: "Create new CLAUDE.md from template"
    content: "src/quaestor/include.md"
```

### CLAUDE.md Template

```markdown
<!-- QUAESTOR CONFIG START -->
[!IMPORTANT]
**Claude:** This project uses Quaestor for AI context management.
Please read the following files in order:
@.quaestor/AGENT.md - AI behavioral rules and workflow enforcement
@.quaestor/ARCHITECTURE.md - Project architecture, standards, and quality guidelines
@.quaestor/specs/active/ - Active specifications and implementation details
<!-- QUAESTOR CONFIG END -->

<!-- Your custom content below -->
```

## Customization After Generation

Users can customize the generated ARCHITECTURE.md:

### Common Customizations

```markdown
# Example: Customize test command for specific project needs

# Before (default)
- **Test Runner**: `pytest`

# After (customized for project)
- **Test Runner**: `pytest -xvs --cov=src --cov-report=html`

# Example: Add project-specific linting rules

# Before (default)
- **Linter**: `ruff check .`

# After (customized)
- **Linter**: `ruff check . --select E,F,W,I,N --ignore E501`
```

### Where to Customize

1. Open `.quaestor/ARCHITECTURE.md`
2. Navigate to **Section 3: CODE QUALITY STANDARDS**
3. Edit command values directly
4. Save file - changes take effect immediately

**Important**: Users should edit `.quaestor/ARCHITECTURE.md` directly, not the template files in `src/quaestor/`.

---

*This file provides complete documentation templates and variable mappings for intelligent document generation.*