Archeia Init

Workflow

Phase 1: Detection

Before exploring the repo, check if .archeia/ already exists.

• If .archeia/ exists: ask the user whether to refresh (regenerate Layer 3 docs only, preserve all Layer 2 docs) or overwrite (regenerate everything from scratch). Refresh is the default recommendation.
• If .archeia/ does not exist: proceed with full init.

Phase 2: Exploration

Read repo files in this exact priority order. Within each category, read files alphabetically. Stop exploring after reading ~30 files total — shift to generation if the budget is reached. If a critical file is discovered late, reading it is fine.

Priority 1 — Root manifests (read all that exist): package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json, pom.xml, build.gradle, Mix.exs, deno.json

Priority 2 — Root configs (read all that exist): tsconfig.json, tsconfig*.json, ruff.toml, pyproject.toml [tool.*], .eslintrc*, .prettierrc*, biome.json, Makefile, Justfile, Taskfile.yml, Dockerfile, docker-compose.yml, fly.toml, render.yaml, railway.json, vercel.json, netlify.toml

Priority 3 — Root docs (read all that exist): README.md, CONTRIBUTING.md, CHANGELOG.md, AGENTS.md, CLAUDE.md

Priority 4 — CI/CD (read first 3 files alphabetically): .github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml

Priority 5 — Test setup (read config files, not test bodies): tests/conftest.py, jest.config.*, vitest.config.*, test/test_helper.*, .nycrc, pytest.ini, setup.cfg [tool:pytest], phpunit.xml

Priority 6 — Source sampling (read first 5 files alphabetically): Files in src/, lib/, app/, or the primary source directory. Focus on entry points and module index files (index.*, main.*, app.*, mod.rs).

Priority 7 — Existing .archeia/ (if refreshing): All files in .archeia/ to understand current state.

Inference Signal Table

Use this table to map discovered files to conclusions. When signals conflict, follow the priority order: manifest content > file extensions > directory structure > README claims.

Phase 3: Layer 3 Generation

Generate Layer 3 docs in this order (respecting dependencies):

1. Read templates/ARCHITECTURE.md frontmatter and body
2. Generate .archeia/ARCHITECTURE.md from collected signals
3. Read templates/SYSTEM.json example
4. Generate .archeia/SYSTEM.json — follow the example structure exactly, replacing example data with evidence from this repo. Rules:
   • system: exactly one object, sourced from manifest + README
   • people: infer from README audience, auth roles, route groups. Empty [] if none found
   • external_systems: every external service confirmed by manifest deps or docker-compose
   • relationships: connect every entity. Every source/target must resolve to an id above
   • Every entity needs evidence array with at least one file path
   • IDs are kebab-case, deterministic from entity names
   • Descriptions are one sentence, no marketing language
   • Do NOT list internal modules as external systems
5. Read templates/CONTAINERS.json example
6. Generate .archeia/CONTAINERS.json — follow the example structure. Rules:
   • system_boundary: must match system from SYSTEM.json (same id, name, description)
   • containers: runtime units (processes, databases, caches), NOT source directories. type is one of: webapp | api | database | cache | queue | filesystem | worker | cli
   • external_systems: carried forward from SYSTEM.json, must match exactly
   • relationships: container-to-container and container-to-external
   • people_container_mappings: include only if SYSTEM.json has people, omit key otherwise
   • For monoliths: still decompose if distinct runtime concerns exist
   • Infer from: docker-compose services, workspace packages, Dockerfiles, entry points
7. Read templates/COMPONENTS.json example
8. Generate .archeia/COMPONENTS.json — follow the example structure. Rules:
   • containers: one entry per container from CONTAINERS.json with internal source code. Skip containers with no app-side code (e.g., managed databases without schema code)
   • components: code-level modules (directories/packages, not files). type is one of: module | service | controller | repository | middleware | handler | library | config Prefix IDs with container ID (e.g., api-routes, worker-jobs)
   • external_systems: include only if components talk directly to externals
   • relationships: focus on architecturally significant connections (layer crossings, module boundaries, external integrations). Do NOT enumerate every import
   • Infer from: directory structure, import statements, module index files
   • Map ARCHITECTURE.md Module Boundaries to components within containers
9. Read templates/STANDARDS.md frontmatter and body
10. Generate .archeia/STANDARDS.md (may reference ARCHITECTURE for topology)
11. Read templates/GUIDE.md frontmatter and body
12. Generate .archeia/GUIDE.md (may reference ARCHITECTURE + STANDARDS)

For each generated file:

• Follow the template's Required Sections exactly
• Include Conditional Sections only when evidence supports them
• Cite evidence: every factual claim must reference a file path
• Use <!-- INSUFFICIENT EVIDENCE: [description] --> for gaps
• Do not include the template frontmatter in output
• Do not use marketing language or unsupported superlatives

Phase 4: Self-Validation

After generating all Layer 3 docs, run a validation pass:

Step 1 — Rubric check: Re-read each generated file. For each template's quality rubric (listed at the bottom of the template), verify the output meets every criterion. Fix issues inline using the Edit tool. One fix pass maximum — if an issue persists after one fix attempt, note it and move on.

Step 2 — File-existence verification: Extract every file path cited in the generated docs (paths like package.json, src/index.ts, etc.). Use Glob to verify each path exists in the repo. Remove or annotate any citation where the file does not exist.

Step 3 — Validation summary: Print a summary for the user:

• Number of Layer 3 docs generated
• Number of files read during exploration
• Number of issues found and fixed in validation
• Number of fabricated paths caught and removed
• Any remaining gaps (sections marked INSUFFICIENT EVIDENCE)

Phase 5: Layer 2 Preparation

If this is a full init (not just Layer 3 refresh):

1. Ask only the questions the repo cannot answer reliably — decisions, constraints, preferences, and assumptions require human confirmation.
2. Generate Layer 2 docs using their templates.
3. Write or refresh AGENTS.md and CLAUDE.md.

If this is a Layer 3 refresh: skip this phase, preserve existing Layer 2 docs.

Phase 6: Finalization

1. Offer to migrate good existing docs into the Archeia structure.
2. Offer GitHub Action and PR-template guidance when maintenance should be automated.
3. Confirm changes through a normal diff or pull request, not a custom approval flow.

Operating Rules

• Every factual claim must cite a file path as evidence.
• When evidence is insufficient, use <!-- INSUFFICIENT EVIDENCE: ... -->.
• When signals conflict, follow signal priority: manifest > extensions > structure > README claims.
• Prefer short, high-signal docs agents can reload frequently.
• Use template structure as the output skeleton, not as final prose.
• Do not position the historical scanner or cloud service as the current product.
• Do not invent technologies, frameworks, or dependencies not found in evidence.
• Do not use marketing language, superlatives, or filler phrases.

Expected Outputs

Layer 3 (auto-generated, no human input):

• .archeia/ARCHITECTURE.md
• .archeia/SYSTEM.json
• .archeia/CONTAINERS.json
• .archeia/COMPONENTS.json
• .archeia/STANDARDS.md
• .archeia/GUIDE.md

Layer 2 (requires human confirmation):

• .archeia/DECISIONS.md
• .archeia/CONSTRAINTS.md
• .archeia/PREFERENCES.md
• .archeia/ASSUMPTIONS.md

Synthesis (combines Layer 2 + Layer 3):

• AGENTS.md
• CLAUDE.md

Worked Example

Below is a condensed example of what .archeia/ARCHITECTURE.md should look like for a Node.js Express API project. This demonstrates evidence-citing style, section structure, and appropriate level of detail.

# Architecture

## System Overview

This is a Node.js REST API built with Express and TypeScript. It serves as the
backend for a task management application.

**Evidence:** `package.json` (Express 4.18, TypeScript 5.3), `tsconfig.json`
(strict mode, ES2022 target)

## Topology

- **Type:** Single-process HTTP server (monolith)
- **Primary areas:** `src/routes/`, `src/services/`, `src/models/`
- **External systems:** PostgreSQL (via `pg` in dependencies), Redis
  (via `ioredis` in dependencies)

**Evidence:** `package.json` dependencies, `src/` directory structure,
`docker-compose.yml` (postgres and redis services)

## Module Boundaries

| Module | Path | Responsibility | Dependencies |
|--------|------|---------------|-------------|
| Routes | `src/routes/` | HTTP request handling | Services |
| Services | `src/services/` | Business logic | Models |
| Models | `src/models/` | Data access, ORM models | pg driver |
| Middleware | `src/middleware/` | Auth, logging, error handling | — |

**Evidence:** `src/` directory listing, import patterns in `src/routes/index.ts`

## Data Flow

1. HTTP request → Express middleware chain (`src/middleware/`)
2. Route handler (`src/routes/`) validates input
3. Service layer (`src/services/`) executes business logic
4. Model layer (`src/models/`) queries PostgreSQL
5. Response serialized and returned

**Evidence:** `src/routes/tasks.ts` imports from `src/services/taskService.ts`,
which imports from `src/models/task.ts`

## Build and Development

- **Package manager:** pnpm (`pnpm-lock.yaml` present)
- **Build:** `tsc` via `package.json` scripts.build
- **Dev server:** `tsx watch` via `package.json` scripts.dev
- **Test runner:** vitest (`vitest.config.ts` present)

**Evidence:** `package.json` scripts section, `pnpm-lock.yaml`, `vitest.config.ts`

## Change Notes

- **High-risk areas:** `src/models/` (database schema changes),
  `src/middleware/auth.ts` (authentication logic)
- **Stable areas:** `src/routes/` (thin handlers, low logic density)
- **Open questions:** None at Layer 3 — architecture decisions deferred to
  DECISIONS.md

Maintenance Modes

Choose the lightest mode that fits the repo:

• inline doc updates during normal coding work
• drift captured in a dedicated PR
• GitHub Action-based maintenance for scheduled or review-time checks

Done When

The run is successful when:

• the key docs exist or were refreshed
• the instructions reflect current repo reality
• every factual claim cites a file path as evidence
• the self-validation pass found no remaining critical gaps
• the user can review the result through normal git workflows