Archyl Generate Context GitHub Action

Generate an archyl.txt file containing your project's architecture context, optimized for consumption by AI agents (Claude Code, Cursor, Codex).

Why

AI agents write better code when they understand the architecture. This action auto-generates a token-efficient architecture briefing that agents load at boot via CLAUDE.md, .cursorrules, or AGENTS.md.

Usage

Generate on every push to main

on:
  push:
    branches: [main]

jobs:
  context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: archyl-com/actions/generate-context@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ secrets.ARCHYL_ORG_ID }}
          project-id: 'your-project-uuid'

Auto-commit the generated file

- uses: archyl-com/actions/generate-context@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ secrets.ARCHYL_ORG_ID }}
    project-id: 'your-project-uuid'
    commit: 'true'

Custom output path

- uses: archyl-com/actions/generate-context@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ secrets.ARCHYL_ORG_ID }}
    project-id: 'your-project-uuid'
    output-file: '.ai/architecture.md'

Weekly refresh on schedule

on:
  schedule:
    - cron: '0 6 * * 1' # Every Monday at 6am

jobs:
  context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: archyl-com/actions/generate-context@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ secrets.ARCHYL_ORG_ID }}
          project-id: 'your-project-uuid'
          commit: 'true'

Generated File

The action produces a markdown file like this:

# Architecture Context
# Auto-generated by Archyl on 2026-04-07 — do not edit manually.
# Reference this file in CLAUDE.md with: @archyl.txt

## C4 Model

### Payment Platform
E-commerce payment processing system

- **API Gateway** (Go, gin)
  REST API entry point for all client requests
  - AuthMiddleware [Go]
  - RateLimiter [Go]
- **Payment Service** (Go)
  Core payment processing logic
- **PostgreSQL** (PostgreSQL 16)
  Primary data store

### Relationships

- API Gateway → Payment Service (calls) — routes payment requests
- Payment Service → PostgreSQL (reads_from)

## Conformance Rules

- [error] No Direct DB Access: Handlers must not import database packages directly
- [error] Backend Language Policy: All backend services must use Go or Rust
- [warning] OpenAPI Required: All public services must have an API contract

## Architecture Decision Records

- ADR-001: Use event sourcing for order service (accepted)
- ADR-002: Migrate from REST to gRPC for internal calls (proposed)

## Technology Stack

- Go 1.22 (language)
- PostgreSQL 16 (database)
- Redis 7 (cache)
- Kafka 3.7 (messaging)

Referencing in Agent Config

Add to your CLAUDE.md:

## Architecture
@archyl.txt

Add to your .cursorrules:

Read archyl.txt before implementing any feature.

Inputs

Input	Required	Default	Description
api-key	Yes		Archyl API key with read scope
organization-id	Yes		Archyl organization UUID
project-id	Yes		Archyl project UUID
api-url	No	https://api.archyl.com	API base URL (for self-hosted)
output-file	No	archyl.txt	Path to write the generated file
format	No	markdown	markdown for LLM-optimized, full for JSON + markdown
commit	No	false	Auto-commit the file if it changed
commit-message	No	chore: update archyl.txt architecture context	Commit message

Outputs

Output	Description
file-path	Path to the generated file
changed	true if the content changed, false if identical
token-count	Approximate token count of the generated file