Arckit Principles

Read external documents and policies:

Note: Before generating, scan projects/ for existing project directories. For each project, list all ARC-*.md artifacts, check external/ for reference documents, and check 000-global/ for cross-project policies. If no external docs exist but they would improve output, ask the user.

• Read any global policies listed in the project context (000-global/policies/) — extract existing architecture principles, TOGAF standards, departmental policies, technology standards
• If no external governance documents found, ask: "Do you have any existing architecture principles, governance frameworks, or departmental technology standards? I can read PDFs and Word docs directly. Place them in projects/000-global/policies/ and re-run, or skip to create principles from scratch."
• Citation traceability: When referencing content from external documents, follow the citation instructions in .arckit/references/citation-instructions.md. Place inline citation markers (e.g., [PP-C1]) next to findings informed by source documents and populate the "External References" section in the template.

Understand the request: The user may be:

• Creating principles from scratch for a new organization
• Adding specific principles (e.g., "add API-first principle")
• Updating existing principles
• Tailoring principles for a specific industry (e.g., financial services, healthcare, retail)

Generate comprehensive principles: Based on the user's input, create detailed architecture principles following the template structure:

• Strategic Principles (Scalability, Resilience, Interoperability, Security by Design, etc.)
• Data Principles (Single Source of Truth, Data Quality, Privacy by Design)
• Integration Principles (Loose Coupling, Standard Interfaces, Asynchronous Communication)
• Quality Attributes (Performance, Availability, Maintainability, Observability)
• Development Practices (Automation, Testing, Code Review, Continuous Improvement)
• Exception Process (how to request deviations)

IMPORTANT: Principles MUST be technology-agnostic:

• Focus on CHARACTERISTICS, not specific products (e.g., "horizontally scalable" not "use Kubernetes")
• Focus on QUALITIES, not specific technologies (e.g., "encrypted in transit" not "use TLS 1.3")
• Focus on PATTERNS, not specific implementations (e.g., "event-driven integration" not "use Kafka")
• Focus on OUTCOMES, not specific tools (e.g., "infrastructure as code" not "use Terraform")

What TO include: Architectural qualities, patterns, practices, and decision criteria What NOT to include: Specific vendors, products, cloud providers, programming languages, frameworks

Make it actionable: Each principle MUST include:

• Clear principle statement with MUST/SHOULD/MAY (technology-agnostic)
• Rationale explaining WHY this principle matters
• Implications (how it affects design decisions)
• Validation gates (checklist items to verify compliance)
• Example scenarios (good vs bad, without naming specific products)
• Common violations to avoid

Industry-specific customization: If the user mentions an industry:

• Financial Services: Add principles for transaction integrity, audit trails, regulatory compliance (SOX, PCI-DSS)
• Healthcare: Add HIPAA compliance, PHI data handling, consent management
• Retail: Add principles for payment processing, inventory systems, customer data
• Government: Add accessibility (Section 508), public records, security clearances

Detect version: Before generating the document, check if a previous version exists:

• Look for existing ARC-000-PRIN-v*.md files in projects/000-global/
• If no existing file: Use VERSION="1.0"
• If existing file found:
  • Read the existing document to understand its scope
  • Compare against current inputs
  • Minor increment (e.g., 1.0 → 1.1): Scope unchanged — refreshed content, updated details, corrections
  • Major increment (e.g., 1.0 → 2.0): Scope materially changed — new principle categories, removed categories, fundamentally different guidance
• For v1.1+/v2.0+: Add a Revision History entry describing what changed from the previous version

Write the output:

Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks plus the PRIN per-type checks pass. Fix any failures before proceeding.

• Document ID: ARC-000-PRIN-v{VERSION} (e.g., ARC-000-PRIN-v1.0) — 000 indicates global/cross-project document
• Filename: ARC-000-PRIN-v{VERSION}.md
• Write to: projects/000-global/ARC-000-PRIN-v${VERSION}.md
• Use the exact template structure
• Make it ready for immediate use by development teams

WARNING: Do NOT use legacy filename architecture-principles.md. Always use the document ID format. NOTE: The projects/000-global/ directory is for cross-project artifacts like architecture principles.