feat: wire userConfig values into templates, commands, and hooks

[tractorjuice]

Follow-up to #210. The userConfig schema is declared in arckit-claude/.claude-plugin/plugin.json (v4.6.12) and the two API-key fields are wired through .mcp.json, but the three non-secret fields are declared-but-unused.

This issue tracks the consumption work to make those values actually flow into generated artifacts.

Fields to wire

Key	Where it should be consumed
organisation_name	Document Control Owner / header in every template
default_classification	Document Control Classification field default
governance_framework	Command + agent prompts (UK Gov vs Generic toggle)

Proposed work

1. Templates (arckit-claude/templates/*.md and .arckit/templates/*.md)

Replace hard-coded placeholders in Document Control blocks:

• [PUBLIC / OFFICIAL / OFFICIAL-SENSITIVE / SECRET] → ${user_config.default_classification} with current placeholder as fallback hint
• [OWNER_NAME_AND_ROLE] → reference ${user_config.organisation_name} where appropriate
• Decide whether to substitute in the template file itself or have the generating command perform the substitution before writing

2. Commands and agents

• Pick the commands/agents whose output differs by governance regime (e.g. requirements, sobc, service-standard, caf, tcop) and have them check ${user_config.governance_framework} to enable/disable UK Gov-specific sections.
• For Generic: skip GDS Service Standard / TCoP / NCSC CAF / Orange Book / Green Book sections; keep core architecture/risk/business case content.
• For UK Gov (default): keep current behaviour.
• Relates to Non UK-specific version of arc-kit #304 (Non UK-specific version of arc-kit) — the governance_framework flag is the mechanism by which Non UK-specific version of arc-kit #304 ships.

3. Hooks (arckit-claude/hooks/)

• Audit hook scripts for places where org-specific behaviour belongs (e.g. classification validation, owner-field validation) and read CLAUDE_PLUGIN_OPTION_<KEY> env vars where useful.
• Likely candidates: validate-arc-filename.mjs, any Document Control validators, score validators.

4. Converter

• Confirm scripts/converter.py still handles non-Claude targets cleanly once template substitution lands (it already rewrites ${user_config.KEY} → ${KEY} in .mcp.json, but template rewriting may need analogous handling so Codex/Gemini/OpenCode/Copilot users get sensible defaults).

5. Tests

• Install plugin fresh in a test repo, configure all three values, generate a representative artifact (/arckit.requirements), and verify the values appear in Document Control.
• Run the same flow with governance_framework=Generic and confirm UK Gov sections drop out.

Out of scope

• Adding new userConfig fields beyond the five already declared.
• Changing the schema validator behaviour (Claude Code core).

References

• Parent: feat: add userConfig to plugin manifest for org-level settings #210
• Related: Non UK-specific version of arc-kit #304 (Non UK-specific version of arc-kit), feat: adopt Claude Code v2.1.83–2.1.128 plugin capabilities #215 (Claude Code 2.1.83–2.1.114 capabilities tracking)
• Docs: https://code.claude.com/docs/en/plugins-reference#user-configuration

[Drago-cod]

Hi @tractorjuice, thanks for the detailed breakdown on this—really clear direction

The approach of wiring userConfig into templates, commands, and hooks makes a lot of sense, especially keeping substitutions centralized and consistent across distributions.

A few thoughts/questions:

Templates:
The placeholder strategy using {{ user_config.* }} looks clean. Do you plan to standardize fallback behavior if a value is missing, or should templates fail explicitly?
Commands & agents:
I like the separation between core and governance-specific prompts. Maybe worth clarifying how extensible this will be if new governance regimes are added later.
Hooks:
The idea of keeping logic close to where it belongs is solid. Just wondering if there’s any risk of duplication between hooks and validators (e.g., classification or owner-field validation).
Converter:
Good call reusing the existing substitution logic. Might be worth documenting clearly how .arcconfig and templates stay in sync to avoid drift.
Tests:
The plan looks good—especially verifying output in Document Control. Maybe consider adding edge cases (e.g., missing or malformed config values).

Overall, this looks like a strong step toward making configuration more flexible and reusable across setups.

[tractorjuice]

Status update — partials shipped, command-side consumption still open

Reviewing the codebase against this issue's checklist:

Shipped

• arckit-claude/templates/_partials/document-control-uk.md
• arckit-claude/templates/_partials/document-control-uae.md
• arckit-claude/templates/_partials/RENDERING.md defining the <!-- DOC-CONTROL-HEADER --> marker resolution rules
• Several templates (e.g. requirements-template.md) now reference the marker rather than hard-coding the Document Control block
• The userConfig schema in arckit-claude/.claude-plugin/plugin.json is wired for GOOGLE_API_KEY and DATA_COMMONS_API_KEY via .mcp.json

Still open — no command currently substitutes user_config values

grep -l "user_config\|organisation_name" arckit-claude/commands/*.md returns zero matches. So:

• Pick the commands whose templates use <!-- DOC-CONTROL-HEADER --> and have them actually read ${user_config.organisation_name} / ${user_config.default_classification} / ${user_config.governance_framework} and substitute at write time
• Decide whether substitution happens in the template file (rendered by the command) or in the command logic before Write
• Audit hooks for CLAUDE_PLUGIN_OPTION_<KEY> consumption (validators that should respect the configured default classification)
• Confirm scripts/converter.py rewrites ${user_config.KEY} → ${KEY} in non-Claude targets for any new template substitutions (already done for .mcp.json)
• End-to-end test: enable plugin with all three values set, run /arckit:requirements, verify Document Control reflects them; flip governance_framework=Generic, verify UK Gov sections drop

The template/partials work is a meaningful chunk done — leaving this issue open scoped to the command/hook substitution layer.