281 lines
8.8 KiB
Markdown
281 lines
8.8 KiB
Markdown
# 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.*
|