coquill-analyzer

name	coquill-analyzer
description	Template analyzer for CoQuill (v2). Parses docx/HTML templates, extracts variables including conditionals and loops, merges config.yaml overrides, infers types, and generates a v2 manifest.yaml. Called by the coquill orchestrator — not triggered directly by the user.

CoQuill — Template Analyzer v2

You are running the CoQuill template analyzer. You receive a template directory path from the Orchestrator (e.g., templates/_examples/Bonterms_Mutual_NDA/).

Step 1 — Resolve Script Path and Run

import os
script = os.path.join(
    os.environ.get("CLAUDE_PLUGIN_ROOT", ""),
    "scripts", "analyze.py"
)

If CLAUDE_PLUGIN_ROOT is not set, the path resolves to scripts/analyze.py relative to the project root.

Run the script:

python <script_path> <template_dir> [--force]

Pass --force if the Orchestrator requests re-analysis (skips the cache check).

The script handles: format detection, caching, text extraction (including docx XML merge), two-pass analysis, type inference, condition parsing, loop sub-variable extraction, dependency graph construction, config.yaml merge, and manifest save.

Interpret Script Output

• Exit 0 with "Manifest is up to date" — cached manifest is valid; load it from <template_dir>/manifest.yaml.
• Exit 0 with "Manifest written" — fresh analysis complete; proceed to Step 2.
• Exit 1 — error (e.g., no template file found, corrupt docx). Report the stderr/stdout message to the Orchestrator.

Step 2 — Validate the Manifest

After a fresh analysis (not a cache hit), load manifest.yaml and check for issues the script cannot catch:

1. Zero variables — if variable_count is 0, the template has no placeholders. Warn the Orchestrator; it may be the wrong file.
2. Orphaned gate variables — every variable listed in dependencies keys must appear in variables. If one is missing, the interview will fail to collect the gate value.
3. Conditional variables shadowing unconditional — if the same variable name appears in both variables and a conditional's if_variables/else_variables, flag it. The script deduplicates these, but a config.yaml merge could reintroduce duplicates.
4. Loop sub-variables with no names — if a loop's variables list is empty, the loop collects nothing. This may be intentional (iteration-only) or a sign the template uses a non-standard loop variable pattern.
5. Config.yaml drift — if config.yaml exists, quickly scan it for variable names that don't appear anywhere in the manifest. These are config entries for variables the template no longer uses. Warn so the developer can clean up.

Report any warnings alongside the manifest contents when returning to the Orchestrator.

Step 3 — Return to Orchestrator

Return the full manifest.yaml contents to the Orchestrator, along with any warnings from Step 2.