Generate Compliance Contracts (Contratos de Adherencia) from ARCHITECTURE.md files
This skill is manually activated when users request compliance document generation. It is NOT automatically triggered.
Activation Triggers:
/skill architecture-compliance/skill architecture-compliance all/skill architecture-compliance SRE,Cloud,Security (comma-separated list for subset)NOT Activated For:
architecture-docs skill)architecture-readiness skill)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).
This skill generates compliance documents from ARCHITECTURE.md, producing 10 separate documents:
10 Compliance Contracts:
CRITICAL REQUIREMENT: Generated compliance contracts MUST preserve template format exactly.
Strict Preservation Rules:
[PLACEHOLDER] tokens - text inside [...] brackets[If Compliant: X. If Non-Compliant: Y] with the text matching the Status valueTemplate Format Example:
**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):
**RTO**: 4 hours
- Status: Compliant
- Explanation: RTO documented and meets requirements
INCORRECT Replacement (DO NOT DO THIS):
**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:
See Phase 4, Step 4.2 for detailed placeholder replacement workflow.
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:
Routing Logic Unification
Code Cleanup (~740 lines removed)
Phase 3.5 Enhancement
Impact:
Files Modified:
/skills/architecture-compliance/SKILL.md (740 lines removed, ~50 lines updated)Summary: Implemented comprehensive template preservation mandate and pre-write validation across all 10 compliance generation agents.
Changes:
PHASE 0: Template Preservation Mandate (All agents)
PHASE 4.5: Comprehensive Pre-Write Validation (All agents)
Validation Utility (New tool)
validate-contract-structure.ts for automated format verificationbun skills/architecture-compliance/utils/validate-contract-structure.ts <contract-file>Impact:
Files Modified:
/agents/ (PHASE 0 + PHASE 4.5 added)/skills/architecture-compliance/utils/validate-contract-structure.tsIMPORTANT: The following format rules are MANDATORY and validated with BLOCKING severity. Violations will prevent contract generation.
After "### A.4 Change History", the template includes shared sections via @include directives.
These are already expanded by resolve-includes.ts and appear as ## Header (H2).
YOU MUST PRESERVE THEM AS H2 - DO NOT ADD A.5+ NUMBERING
### A.5 Data Extracted Successfully## Data Extracted SuccessfullyValidation Rule: forbidden_section_numbering will BLOCK any sections numbered A.5 or higher.
Document Control MUST use table format: | Field | Value |
NEVER convert tables to bold field lists
❌ WRONG:
**Document ID**: VALUE
**Template Version**: VALUE
✅ CORRECT:
| Field | Value |
|-------|-------|
| Document ID | VALUE |
| Template Version | VALUE |
Validation Rule: document_control_table will BLOCK contracts without proper table format.
Preserve ALL markdown structures exactly:
| separators)- or *)[PLACEHOLDER] tokens - nothing elseWhy This Matters:
See Phase 4, Step 4.2 for detailed format preservation workflow.
CRITICAL REQUIREMENT: All compliance contracts must maintain strict source traceability to ARCHITECTURE.md.
Rules:
Allowed Extraction Methods:
When Data is Missing:
[PLACEHOLDER: Not specified in docs/NN-name.md]Example:
**RTO**: [PLACEHOLDER: Not specified in docs/09-operational-considerations.md]
Optional Reference: Industry standard for Tier 1 applications: 4 hours RTO (NIST SP 800-34)
Note: Add RTO value to docs/09-operational-considerations.md (Operational Considerations → Backup and Recovery)
Audit Compliance: This policy ensures all generated compliance documents are fully auditable with verifiable sources, meeting regulatory requirements for documentation traceability.
To support flexible contract selection and validation, the following aliases and keywords are recognized:
| Contract Type | Aliases | Keywords |
|---|---|---|
| Business Continuity | continuity, bcm, disaster recovery | business, continuity, recovery, rto, rpo, backup |
| SRE | site reliability, sre, reliability | sre, slo, sli, error budget, monitoring, observability |
| Cloud Architecture | cloud, infrastructure as code, iac | cloud, aws, azure, gcp, deployment, regions |
| Data & AI Architecture | data, ai, ml, analytics, machine learning, data ai | data, ai, ml, analytics, pipeline, model, hallucination |
| Development Architecture | development, dev, coding standards | development, coding, stack, framework, languages, tools |
| Process Transformation | automation, process, transformation | process, automation, rpa, efficiency, workflow |
| Security Architecture | security, infosec, cybersecurity | security, authentication, encryption, compliance, oauth |
| IT Infrastructure | infrastructure, platforms, it | infrastructure, platform, database, compute, capacity |
| Enterprise Architecture | enterprise, ea, strategic | enterprise, strategic, modularity, governance, alignment |
| Integration Architecture | integration, api, middleware | integration, api, messaging, event, microservices |
Purpose: Eliminate duplication across 10 compliance templates by extracting common sections into reusable files.
Directory: /skills/architecture-compliance/shared/
Components:
Include Syntax:
<!-- @include shared/sections/file.md --><!-- @include-with-config shared/sections/file.md config=domain-name -->Processing: Includes are resolved during template loading (Phase 4, Step 4.1) before placeholder replacement.
Benefits:
Example (Business Continuity template):
<!-- @include-with-config shared/sections/document-control.md config=business-continuity -->
Resolves to the Document Control table with {{variables}} replaced from shared/config/business-continuity.json.
For detailed usage: See shared/README.md
Output Directory: /compliance-docs/ (relative to ARCHITECTURE.md location)
File Naming Pattern:
[CC-NNN-contract-type]_[PROJECT_NAME]_[DATE].md
Examples:
CC-010-sre-architecture_JobScheduler_2025-11-26.mdCC-001-business-continuity_PaymentGateway_2025-11-26.mdCC-004-development-architecture_JobScheduler_2025-11-26.mdRegeneration Behavior:
Additional Outputs:
COMPLIANCE_MANIFEST.md: Index of all generated compliance documents with metadataArchitecture documentation uses a multi-file structure where ARCHITECTURE.md is a navigation index (~130 lines) and section content lives in separate docs/ files. This eliminates the need for line-offset based reads — each section is an independent file that can be read directly.
Step 1: Read Navigation Index
Read ARCHITECTURE.md (full file, ~130 lines) to get:
- Project name (H1 header)
- Links to docs/ section files
Step 2: Identify Required docs/ Files
For each contract type, consult SECTION_MAPPING_GUIDE.md to determine:
- Primary files (80%+ of content)
- Secondary files (15-30% of content)
- Tertiary files (<15% of content)
Step 3: Read docs/ Files Directly
Read only required docs/ files in full (no offset/limit needed)
Example for SRE Architecture:
- docs/08-scalability-and-performance.md: SLOs, SLIs, latency targets
- docs/09-operational-considerations.md: Monitoring, DR, runbooks
Total: 2-3 focused files vs all 12 docs/ files
Step 4: Cache Extracted Data
Extract data once, cache for contract generation
Avoid re-reading same files for multiple contracts
Multi-File Approach:
1. Read ARCHITECTURE.md (~130 lines) — get project name
2. Read docs/08-scalability-and-performance.md — SLOs, latency, throughput
3. Extract performance metrics, cache
4. Read docs/09-operational-considerations.md — monitoring, incidents, DR
5. Extract operational data, cache
6. Generate contract from cached data
Total: 3 files, each read in full, no offset calculations needed
When users request a list of available contracts (e.g., "list contracts", "show contract types", "what contracts are available"), display the following summary:
Available Compliance Contracts (10 total):
To generate contracts:
For more details on any contract type, see: /skills/architecture-compliance/contracts/CONTRACT_TYPES_REFERENCE.md
After displaying the contract list, ask:
"Which compliance contract(s) would you like to generate?"
User Options:
Step 1.1: Detect User Intent
Parse user request to determine which contracts to generate:
Intent Types:
"all" keyword → Generate all 10 contracts
Comma-separated list → Generate specific subset of contracts
Single contract name → Generate one contract (existing workflow)
Parsing Logic:
1. Normalize input: lowercase, trim whitespace, remove punctuation
2. Check for "all" keyword (in patterns like "all compliance", "all my", "all contracts")
- If found → selected_contracts = ALL_10_CONTRACT_TYPES
3. Check for delimiter patterns (comma, "and", "or")
- If found → split input, parse each token as contract name
- Use alias matching for each token (see lines 173-188)
- selected_contracts = [matched contract types]
4. Otherwise → single contract mode
- Use exact or fuzzy matching (existing logic, lines 410-431)
- selected_contracts = [single contract type]
Output: selected_contracts = array of 1-10 contract types
Step 1.2: Locate ARCHITECTURE.md
Search order:
1. Current directory
2. Parent directory
3. /docs subdirectory
4. Ask user for location
Step 1.3: Validate Structure
Check for:
- ARCHITECTURE.md as navigation index (~130 lines)
- docs/ directory with section files
- Required docs/ files exist for the selected contract types
Step 1.4: Clarify User Intent
If ambiguous, ask:
- "Which compliance documents would you like to generate?"
Options: All 11, Specific contract(s), By category (security, cloud, etc.)
Step 2.1: Contract Selection and Workflow Routing
Based on selected_contracts from Step 1.1:
Routing Logic:
# ALL contract generation now uses specialized agents (v2.0+)
# No inline generation logic in SKILL.md
IF selected_contracts.length >= 1:
# AGENT-BASED GENERATION (All contract counts)
# Single contract (count == 1): Invoke one agent sequentially
# Multiple contracts (count >= 2): Invoke agents in parallel
# See Phase 3: Agent Invocation below
proceed_to_phase_3()
# Skip to Phase 3: Agent Invocation
Single Contract Validation (when selected_contracts.length == 1):
Validation Process:
1. Normalize user input: Convert to lowercase, trim whitespace
2. Check for exact match against contract type names and aliases (see Aliases table above)
- If match found → Proceed to Step 2.2
3. If no match found:
- Calculate similarity scores using:
* Keyword matching (40% weight): Count matching words between user input and contract names/keywords
* Substring matching (30% weight): Check if user input is substring of contract name or vice versa
* Fuzzy matching (30% weight): Calculate edit distance for typo tolerance
- Select top 3 contract types with highest similarity scores
- Use AskUserQuestion to offer alternatives:
```
The contract type "[USER_INPUT]" is not recognized.
Did you mean one of these?
- [Alternative 1 Name]: [Brief description]
- [Alternative 2 Name]: [Brief description]
- [Alternative 3 Name]: [Brief description]
```
- If user selects alternative → Use selected contract type
- If user selects "Other" → List all 10 contract types with descriptions and let user choose
Output: Validated contract type
Bulk Contracts Validation (when selected_contracts.length > 1):
1. For each contract in selected_contracts:
- Validate template exists: templates/cc-NNN-contract-type.template.md
- Validate validation config exists: validation/cc-NNN-contract-type-template-validation.json
2. If any templates missing:
- Warn user: "Template not found for [CC-NNN-contract-type]"
- Offer options:
a) Skip missing contracts, generate remaining ones
b) Cancel entire operation
3. Output: validated_contracts = [contracts with templates available]
Step 3.1: Resolve Plugin Directory
Step A — Try Glob (dev mode / running from within the plugin directory):
Glob pattern: **/skills/architecture-compliance/SKILL.md
If a result is returned: strip the "/skills/architecture-compliance/SKILL.md" suffix → plugin_dir. Done — skip Step B.
Step B — Call resolve-plugin-dir.ts from the marketplace installation (installed plugin): If Glob returned nothing, run:
bun ~/.claude/plugins/marketplaces/shadowx4fox-solution-architect-marketplace/skills/architecture-compliance/utils/resolve-plugin-dir.ts
Capture stdout. If non-empty: use it as plugin_dir. Done.
If both steps yield nothing: STOP and report:
ERROR: Cannot resolve plugin_dir. Run from within the plugin dev directory, or ensure the plugin is installed via the shadowx4fox-solution-architect-marketplace.
Store plugin_dir for inclusion in all agent prompts.
Step 3.2: Resolve Compliance Docs Directory
Determine the absolute path where contracts will be written:
compliance_docs_dir = dirname(realpath(architecture_file)) + "/compliance-docs"
This is needed for the pipeline in Phase 4.
Step 3.2.1: Clean Up Old Contracts
Before generating new contracts, remove existing contracts for the selected types to prevent stale dated files from accumulating:
# For each selected contract type, delete any existing files matching the prefix
# Example: rm compliance-docs/CC-001-business-continuity_*.md
for prefix in [selected contract prefixes]:
rm -f compliance_docs_dir/PREFIX_*.md
Only delete prefixes for the contract types being generated (from selected_contracts). Use the contract type → filename prefix mapping:
| Contract Type | Filename Prefix |
|---|---|
| business-continuity | CC-001-business-continuity |
| cloud | CC-002-cloud-architecture |
| data-ai | CC-003-data-ai-architecture |
| development | CC-004-development-architecture |
| enterprise | CC-005-enterprise-architecture |
| integration | CC-006-integration-architecture |
| platform | CC-007-platform-it-infrastructure |
| process | CC-008-process-transformation |
| security | CC-009-security-architecture |
| sre | CC-010-sre-architecture |
Run all deletions in a single rm -f command. If compliance-docs/ does not exist yet, skip this step.
Step 3.3: Spawn Validators (FIRST)
⛔ Validators MUST run before generators. Each validator performs external checks (EOL verification via WebSearch, stack validation) and returns a VALIDATION_RESULT block. The generator needs this result to populate the contract correctly.
Invoke validators for the selected contracts in a single message (parallel):
| Contract Type | Validator | Subagent Type |
|---|---|---|
| Business Continuity | Aegis Validator | solutions-architect-skills:business-continuity-validator |
| SRE Architecture | Prometheus Validator | solutions-architect-skills:sre-validator |
| Cloud Architecture | Atlas Validator | solutions-architect-skills:cloud-validator |
| Data & AI Architecture | Mnemosyne Validator | solutions-architect-skills:data-ai-validator |
| Development Architecture | Hephaestus Validator | solutions-architect-skills:development-validator |
| Process Transformation | Hermes Validator | solutions-architect-skills:process-validator |
| Security Architecture | Argus Validator | solutions-architect-skills:security-validator |
| Platform & IT Infrastructure | Vulcan Validator | solutions-architect-skills:platform-validator |
| Enterprise Architecture | Athena Validator | solutions-architect-skills:enterprise-validator |
| Integration Architecture | Iris Validator | solutions-architect-skills:integration-validator |
Validator prompt template:
Validate [Contract Type] compliance.
architecture_file: [absolute path to ARCHITECTURE.md]
plugin_dir: [plugin_dir resolved in Step 3.1]
Each validator returns a VALIDATION_RESULT: block. Collect and store all results before proceeding to Step 3.4.
Step 3.4: Spawn Generators (with validation results)
After all validators complete, invoke generators for the selected contracts. Include the validator's VALIDATION_RESULT in each generator's prompt.
All generators use the single universal agent solutions-architect-skills:compliance-generator. The contract_type parameter determines which config and template to use.
Generator prompt template (includes contract_type and validation result):
Generate compliance contract.
contract_type: [config name, e.g., cloud]
architecture_file: [absolute path to ARCHITECTURE.md]
plugin_dir: [plugin_dir resolved in Step 3.1]
VALIDATION_RESULT:
[paste the full VALIDATION_RESULT block returned by the validator for this contract type]
Invoke all selected generators in a single message (parallel).
Single contract example:
# Step 1: Spawn validator
validator_result = Task(
subagent_type="solutions-architect-skills:development-validator",
prompt="Validate Development Architecture compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]",
description="Hephaestus — Development Architecture Validator"
)
# Step 2: Spawn universal generator with contract_type and validation result
Task(
subagent_type="solutions-architect-skills:compliance-generator",
prompt="Generate compliance contract.\ncontract_type: development\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n" + validator_result,
description="CC-004 — Development Architecture"
)
All 10 contracts — Step 1 (validators, single message, all parallel):
Task(subagent_type="solutions-architect-skills:business-continuity-validator", description="Aegis — Business Continuity Validator", prompt="Validate Business Continuity compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:sre-validator", description="Prometheus — SRE Architecture Validator", prompt="Validate SRE Architecture compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:cloud-validator", description="Atlas — Cloud Architecture Validator", prompt="Validate Cloud Architecture compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:data-ai-validator", description="Mnemosyne — Data & AI Architecture Validator", prompt="Validate Data & AI Architecture compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:development-validator", description="Hephaestus — Development Architecture Validator", prompt="Validate Development Architecture compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:process-validator", description="Hermes — Process Transformation Validator", prompt="Validate Process Transformation compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:security-validator", description="Argus — Security Architecture Validator", prompt="Validate Security Architecture compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:platform-validator", description="Vulcan — Platform & IT Infrastructure Validator", prompt="Validate Platform & IT Infrastructure compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:enterprise-validator", description="Athena — Enterprise Architecture Validator", prompt="Validate Enterprise Architecture compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]"),
Task(subagent_type="solutions-architect-skills:integration-validator", description="Iris — Integration Architecture Validator", prompt="Validate Integration Architecture compliance.\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]")
All 10 contracts — Step 2 (universal generator × 10, single message, all parallel):
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-001 — Business Continuity", prompt="Generate compliance contract.\ncontract_type: business-continuity\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[BC_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-010 — SRE", prompt="Generate compliance contract.\ncontract_type: sre\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[SRE_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-002 — Cloud", prompt="Generate compliance contract.\ncontract_type: cloud\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[CLOUD_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-003 — Data & AI", prompt="Generate compliance contract.\ncontract_type: data-ai\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[DATA_AI_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-004 — Development", prompt="Generate compliance contract.\ncontract_type: development\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[DEV_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-008 — Process", prompt="Generate compliance contract.\ncontract_type: process\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[PROCESS_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-009 — Security", prompt="Generate compliance contract.\ncontract_type: security\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[SECURITY_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-007 — Platform", prompt="Generate compliance contract.\ncontract_type: platform\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[PLATFORM_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-005 — Enterprise", prompt="Generate compliance contract.\ncontract_type: enterprise\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[ENTERPRISE_VALIDATION_RESULT]"),
Task(subagent_type="solutions-architect-skills:compliance-generator", description="CC-006 — Integration", prompt="Generate compliance contract.\ncontract_type: integration\narchitecture_file: ./ARCHITECTURE.md\nplugin_dir: [plugin_dir]\n\n[INTEGRATION_VALIDATION_RESULT]")
Step 3.5: Collect Results
After all tasks complete, check for failures. If any agent failed:
After all agents complete, run the post-generation pipeline in a single Bash call. This calculates validation scores, updates contract fields, and writes COMPLIANCE_MANIFEST.md:
bun [plugin_dir]/skills/architecture-compliance/utils/post-generation-pipeline.ts \
--compliance-docs-dir [compliance_docs_dir] \
--project "[PROJECT_NAME]"
What the pipeline does:
compliance-docs-dir for *.md files (excluding COMPLIANCE_MANIFEST.md)COMPLIANCE_MANIFEST.md with all contracts in one passError handling: If pipeline fails, report the error. Contracts are already written — only scoring and manifest are affected. The user can re-run the pipeline manually.
Step 5.0: Verify Unfilled Placeholders
After the pipeline runs, scan each generated contract for unfilled pipeline-owned placeholders. Use Grep tool for each contract file: