architecture-compliance

What this skill does

# Architecture Compliance Skill

## When This Skill is Invoked

This skill is **manually activated** when users request compliance document generation. It is NOT automatically triggered.

**Activation Triggers:**
- "Generate compliance documents"
- "Create Compliance Contracts"
- "Recreate compliance contracts" / "Regenerate compliance contracts" / "Rebuild compliance contracts"
- "Recreate the compliance manifest" / "Regenerate the compliance manifest" / "Rebuild the compliance manifest"
- "Generate [specific contract type]" (e.g., "Generate SRE Architecture contract")
- "Create compliance documentation"
- `/skill architecture-compliance`
- "Generate all compliance docs"
- "Create security compliance" or "Generate risk management"
- "List available contracts"
- "Show contract types"
- "What contracts can I generate?"
- "Show me all compliance contracts"
- "Generate all my compliance contracts"
- "Create all compliance contracts"
- `/skill architecture-compliance all`
- `/skill architecture-compliance SRE,Cloud,Security` (comma-separated list for subset)
- `/skill architecture-compliance eco all` (model preset first, contract selector second)
- `/skill architecture-compliance balanced SRE,Security` (balanced preset on a subset)
- `/skill architecture-compliance critical-opus all` (Opus retained only for high-stakes validators)
- `/skill architecture-compliance max all` (legacy — Opus for all, most expensive)

**NOT Activated For:**
- Automatic triggers when ARCHITECTURE.md changes
- General architecture documentation tasks (use `architecture-docs` skill)
- Business requirements documentation (use `architecture-readiness` skill)

## INVOCATION REQUIREMENT — BLOCKING

The compliance generator agents (`*-compliance-generator`) are **internal agents**.
They MUST ONLY be spawned from within this skill's Phase 3 workflow — always with `plugin_dir` and `architecture_file` parameters.

**NEVER call a compliance generator agent without `plugin_dir`.**
Doing so skips: plugin directory resolution, template expansion, and post-generation scoring.

If a user requests any compliance contract → invoke this skill first.
This skill resolves `plugin_dir`, then routes to the appropriate agent(s).

## Purpose

This skill generates compliance documents from ARCHITECTURE.md, producing 10 separate documents:

**10 Compliance Contracts:**
1. Business Continuity
2. SRE Architecture (Site Reliability Engineering)
3. Cloud Architecture
4. Data & Analytics - AI Architecture
5. Development Architecture
6. Process Transformation and Automation
7. Security Architecture
8. Platform & IT Infrastructure
9. Enterprise Architecture
10. Integration Architecture

## Template Format Preservation Policy

**CRITICAL REQUIREMENT**: Generated compliance contracts MUST preserve template format exactly.

**Strict Preservation Rules:**
1. ✅ **ONLY replace explicit `[PLACEHOLDER]` tokens** - text inside `[...]` brackets
2. ✅ **PRESERVE ALL other text exactly** - including formatting, structure
3. ❌ **NEVER transform template content** - no custom prose, no reformatting
4. ✅ **EXPAND conditional structures** - replace `[If Compliant: X. If Non-Compliant: Y]` with the text matching the Status value
5. ❌ **NEVER add extra sections** - templates have A.1-A.4 only, no A.5-A.9

**Template Format Example:**
```markdown
**RTO**: [Value or "Not specified"]
- Status: [Compliant/Non-Compliant/Not Applicable/Unknown]
- Explanation: [If Compliant: RTO documented and meets requirements. If Non-Compliant: RTO not specified. If Not Applicable: N/A. If Unknown: RTO mentioned but value unclear]
```

**CORRECT Replacement** (Status = Compliant):
```markdown
**RTO**: 4 hours
- Status: Compliant
- Explanation: RTO documented and meets requirements
```

**INCORRECT Replacement (DO NOT DO THIS):**
```markdown
**RTO**: 4 hours documented in S11 (docs/09-operational-considerations.md)
- Status: Compliant
- Explanation: The system documents a 4-hour RTO requirement which meets organizational standards...
```

**Why This Matters:**
- Ensures template consistency across all generated contracts
- Maintains conditional guidance for future updates
- Prevents LLM from "improving" template structure

**See Phase 4, Step 4.2 for detailed placeholder replacement workflow.**

---

## Version History & Recent Improvements

### v2.3.0 - Model Preset Selection (2026-04-18)

**Summary**: Introduced four model presets (`eco`, `balanced`, `critical-opus`, `max`) so users can trade cost against reasoning depth when spawning validator and generator sub-agents. Agent frontmatter remains unchanged (Opus fallback); the skill orchestrator now passes `model:` per Task() call using a resolver keyed on `(contract_type, role, preset)`.

**Changes:**

1. **New Activation Arguments**
   - `/skill architecture-compliance <preset> [selector]` — preset keyword parsed as the first token in Phase 1 Step 1.1
   - Supported presets: `eco`, `balanced` (default), `critical-opus`, `max`

2. **New Step 1.5: Determine Model Preset**
   - Added AskUserQuestion flow when preset not supplied inline
   - Declined / dismissed answers fall back to `balanced`

3. **Per-Validator Model Matrix**
   - `critical-opus` retains Opus only for Security / SRE / Data & AI / Development validators (reasoning-nuance or WebSearch synthesis)
   - All other validators drop to Haiku under `critical-opus`, Sonnet under `balanced`, Haiku under `eco`
   - Generator runs on Sonnet for every preset except `max`

4. **Phase 3 Task() Calls**
   - Step 3.3 (validators) and Step 3.4 (generator) now include an explicit `model:` parameter
   - Single-contract and all-10-parallel examples updated to show the parameter

**Impact:**
- **~90% savings** on full runs with `eco`, **~75%** with `balanced`, **~60%** with `critical-opus` (relative to all-Opus baseline)
- **No frontmatter churn** — the 11 agent files under `agents/` are untouched; the override is purely orchestration-level
- **Reversible** — users can still run `max` for the prior behavior

**Files Modified:**
- `/skills/architecture-compliance/SKILL.md`

---

### v2.2.0 - Unified Agent-Based Workflow (2025-12-31)

**Summary**: Refactored single contract generation to use specialized agents, eliminating duplicate inline generation logic and creating a consistent workflow path for all contract counts.

**Changes:**

1. **Routing Logic Unification**
   - Single contracts (count == 1) now use Phase 3 (Agent Invocation) instead of Phase 2-5 (inline generation)
   - All contract generation paths now consistently route to specialized agents
   - Removed conditional workflow branching based on contract count

2. **Code Cleanup** (~740 lines removed)
   - Removed obsolete Phase 2.2-2.4 (Output Directory, Template Availability, Preview Option)
   - Removed obsolete Phase 4 (Document Generation - inline logic)
   - Removed obsolete Phase 5 (Output - inline logic)
   - Removed Phase 2.1 Example Scenarios (6 scenarios)
   - SKILL.md reduced from 3491 to 2830 lines

3. **Phase 3.5 Enhancement**
   - Clarified manifest generation applies to both single AND bulk contract generation
   - Added explicit guidance for single contract invocation (create mode once)
   - Maintained existing sequential manifest generation for bulk

**Impact:**
- **Single Source of Truth**: Agents are the only generation implementation (no duplicate logic)
- **Consistency**: Identical workflow path regardless of contract count (1, 2-3, 4+)
- **Maintainability**: Fixes/updates only needed in agent files, not in SKILL.md
- **Simplicity**: SKILL.md is now ONLY an orchestrator (routing + manifest generation)
- **Reliability**: All contracts benefit from v1.9.5 agent fixes (file writing, validation)

**Files Modified:**
- `/skills/architecture-compliance/SKILL.md` (740 lines removed, ~50 lines updated)
- All documentation references updated to reflect unified workflow

---

### v2.1.0 - Enhanced Template Format Enforcement (2025-12-30)

**Summary**: Implemented comprehensive templ