tractorjuice--arckit-gemini/GEMINI.md

ArcKit - Gemini Extension Context

ArcKit is The Enterprise Architecture Governance Harness, providing 75 slash commands across strategy, architecture, delivery, assurance, and interoperability. It transforms architecture governance from scattered documents into a systematic, template-driven process.

Extension File Locations

This extension is installed at ~/.gemini/extensions/arckit/. Key directories:

• Templates: ~/.gemini/extensions/arckit/templates/
• Scripts: ~/.gemini/extensions/arckit/scripts/bash/
• Guides: ~/.gemini/extensions/arckit/docs/guides/
• Skills: ~/.gemini/extensions/arckit/skills/

Template Override

Users can customize templates by placing overrides in their project:

• Project override: .arckit/templates/{template-name} (takes precedence)
• Extension default: ~/.gemini/extensions/arckit/templates/{template-name} (fallback)

When a command reads a template, check .arckit/templates/ first. If not found, fall back to the extension path.

Command Invocation

/arckit:<command-name> <arguments>

Example: /arckit:requirements Create requirements for a cloud migration project

Document Control Standard

Every command that produces a Markdown artifact must render the canonical Document Control table and Revision History.

Document Control Fields (in order)

Field	Example
Document ID	ARC-001-REQ-v1.0
Document Type	Requirements Specification
Project	PROJECT_NAME (Project PROJECT_ID)
Classification	PUBLIC / OFFICIAL / OFFICIAL-SENSITIVE / SECRET
Status	DRAFT / IN_REVIEW / APPROVED / PUBLISHED / SUPERSEDED / ARCHIVED
Version	1.0
Created Date	YYYY-MM-DD
Last Modified	YYYY-MM-DD
Review Cycle	Monthly / Quarterly / Annual / On-Demand
Next Review Date	YYYY-MM-DD
Owner	Role or individual
Reviewed By	Name (date) or PENDING
Approved By	Name (date) or PENDING
Distribution	Distribution list

Domain-specific fields (e.g., "ADR Number", "Assessment Phase") go after standard fields.

Revision History Columns

Version | Date | Author | Changes | Approved By | Approval Date

Standard Footer

---

**Generated by**: ArcKit `/arckit:<command>` command
**Generated on**: [DATE]
**ArcKit Version**: [VERSION]
**Project**: [PROJECT_NAME]
**Model**: [AI_MODEL]

Document ID Generation

Use the helper script:

python3 ~/.gemini/extensions/arckit/scripts/python/generate-document-id.py <PROJECT_ID> <DOC_CODE> <VERSION>

With --filename flag for the full filename with .md extension. With --next-num for multi-instance types (ADR, DIAG, WARD, DMC).

Project Structure

ArcKit projects use this structure:

project/
├── .arckit/
│   └── templates/            # User template overrides (optional)
├── projects/
│   ├── 000-global/           # Cross-project artifacts
│   │   └── ARC-000-PRIN-v1.0.md  # Global architecture principles
│   └── 001-project-name/     # Numbered project directories
│       ├── ARC-001-REQ-v1.0.md
│       ├── ARC-001-STKE-v1.0.md
│       ├── ARC-001-RISK-v1.0.md
│       ├── ARC-001-SOBC-v1.0.md
│       ├── ARC-001-ADR-001-v1.0.md
│       └── vendors/

Creating Projects

Use the helper script to create numbered project directories:

python3 ~/.gemini/extensions/arckit/scripts/python/create-project.py --name "Project Name" --json

Listing Projects

python3 ~/.gemini/extensions/arckit/scripts/python/list-projects.py --json

Requirement ID Prefixes

• BR-xxx: Business Requirements
• FR-xxx: Functional Requirements
• NFR-xxx: Non-Functional (NFR-P-xxx Performance, NFR-SEC-xxx Security, etc.)
• INT-xxx: Integration Requirements
• DR-xxx: Data Requirements

Traceability Chain

Stakeholders -> Goals -> Requirements (BR/FR/NFR/INT/DR) -> Data Model -> Components -> User Stories

UK Government Context

Many commands target UK public sector contexts:

• GDS Service Standard (14 points)
• Technology Code of Practice (TCoP)
• NCSC Cyber Assessment Framework (CAF)
• HM Treasury Green Book (SOBC)
• HM Treasury Orange Book (Risk Management)
• G-Cloud / DOS procurement frameworks
• Secure by Design (Cabinet Office + MOD variants)
• AI Playbook and AI Transparency Recording Standards (ATRS)
• JSP 936 (MOD AI assurance)

Wardley Map Format

Use OnlineWardleyMaps syntax for visualization at https://create.wardleymaps.ai

MCP Servers

This extension bundles MCP servers for cloud research:

• AWS Knowledge: AWS service documentation and best practices
• Microsoft Learn: Azure and Microsoft documentation
• Google Developer Knowledge: GCP documentation (requires GOOGLE_API_KEY setting)

Agents (Sub-agents)

ArcKit includes 6 autonomous research agents that run as sub-agents. These handle research-heavy tasks in isolated context:

Agent	Purpose
arckit-research	Market research, vendor evaluation, build vs buy, TCO
arckit-datascout	Data source discovery, API catalogue search
arckit-aws-research	AWS service research via AWS Knowledge MCP
arckit-azure-research	Azure service research via Microsoft Learn MCP
arckit-gcp-research	GCP service research via Google Developer Knowledge MCP
arckit-framework	Transform artifacts into structured framework

Agents are invoked automatically by commands that need heavy web research.

Hooks

ArcKit includes automation hooks that fire during your session:

Event	Hook	Purpose
SessionStart	Session Init	Inject ArcKit version and project status
BeforeAgent	Context Inject	Inject project artifact inventory
BeforeTool	Filename Validator	Validate ARC-xxx naming convention
BeforeTool	File Protection	Block writes to sensitive/protected files
AfterTool	Manifest Updater	Update manifest.json after writing project files

Policies

ArcKit includes policy rules that:

• Prevent modification of extension system files
• Warn when file content may contain secrets

Key Patterns

• Check prerequisites before generating documents
• Use Write tool to save large documents (avoids token limit issues)
• Show only a summary to the user after writing
• Read existing artifacts to inform new documents (e.g., stakeholder analysis informs requirements)
• Never generate freeform — always use templates from the templates directory