Create or update enterprise architecture principles
You are helping an enterprise architect define architecture principles that will govern all technology decisions in the organisation.
$ARGUMENTS
Read the template (with user override support):
.arckit/templates/architecture-principles-template.md exists in the project root.arckit/templates/architecture-principles-template.md (default)Tip: Users can customize templates with
$arckit-customize architecture-principles
Read external documents and policies:
Note: Before generating, scan
projects/for existing project directories. For each project, list allARC-*.mdartifacts, checkexternal/for reference documents, and check000-global/for cross-project policies. If no external docs exist but they would improve output, ask the user.
000-global/policies/) — extract existing architecture principles, TOGAF standards, departmental policies, technology standardsprojects/000-global/policies/ and re-run, or skip to create principles from scratch.".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:
Generate comprehensive principles: Based on the user's input, create detailed architecture principles following the template structure:
IMPORTANT: Principles MUST be technology-agnostic:
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:
Industry-specific customization: If the user mentions an industry:
Detect version: Before generating the document, check if a previous version exists:
ARC-000-PRIN-v*.md files in projects/000-global/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.
ARC-000-PRIN-v{VERSION} (e.g., ARC-000-PRIN-v1.0) — 000 indicates global/cross-project documentARC-000-PRIN-v{VERSION}.mdprojects/000-global/ARC-000-PRIN-v${VERSION}.mdWARNING: Do NOT use legacy filename
architecture-principles.md. Always use the document ID format. NOTE: Theprojects/000-global/directory is for cross-project artifacts like architecture principles.
IMPORTANT - Auto-Populate Document Information Fields:
Before completing the document, populate document information fields:
[PROJECT_ID] → Extract from project path (e.g., "001")[VERSION] → Determined version from step 6[DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format[DOCUMENT_TYPE_NAME] → Document purposeARC-[PROJECT_ID]-PRIN-v[VERSION] → Generated document ID[STATUS] → "DRAFT" for new documents[CLASSIFICATION] → Default to "OFFICIAL" (UK Gov) or "PUBLIC"[PROJECT_NAME] → Full project name[OWNER_NAME_AND_ROLE] → Document owner| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-principles` command |
**Generated by**: ArcKit `$arckit-principles` command
**Generated on**: {DATE}
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Actual model name]
$arckit-stakeholders to analyze stakeholder drivers and goals for your project"User: $arckit-principles Create principles for a financial services company focusing on cloud migration
You should:
projects/000-global/ARC-000-PRIN-v1.0.mdTechnology Agnostic: Principles describe WHAT qualities the architecture must have, not HOW to implement them with specific products
Decision Criteria, Not Decisions: Principles guide technology selection during $arckit-research phase, they don't prescribe specific technologies
Timeless: Good principles survive technology changes - "scalable" is timeless, "use Docker" is not
These principles become the "constitution" for all architecture decisions
They will be referenced in requirements documents, design reviews, and vendor evaluations
Make them specific enough to be enforceable but flexible enough to allow innovation
Include validation gates so reviews can be objective
Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji
❌ BAD (Technology-Specific):
✅ GOOD (Technology-Agnostic):