agent-architecture-skill

name	agent-architecture-skill
description	Generate architecture-level agent context (no code细节) for Terrain projects.

Agent Architecture Context Skill

Produce agent/context.md — a dense, architecture-oriented document for Coding Agents and Ask mode.

NOT this skill's job

• Full source code or compressed signatures (that's agent/repomix.md — Ask reads via grep/read_file)
• Human-friendly long-form narrative (that's human/ Litho docs)

Output contract

When Terrain runs context generation, return the complete markdown document as your reply; Terrain persists it as agent/context.md. Do not write the output file yourself in that mode — a reply that is only a completion summary will overwrite a good on-disk document.

When a prompt explicitly delegates file writing to you (no “Terrain will persist your reply” clause), write to TERRAIN_AGENT_CONTEXT_OUTPUT or the path given in the prompt.

Required sections (Markdown ## headings), in the language specified by the prompt's LANGUAGE directive (Chinese names below; English equivalents in parentheses — the prompt's explicit section list takes precedence):

1. 项目概览 (Project Overview) — purpose, consumers, key constraints (≤120 words)
2. 架构设计 (Architecture) — containers, layers, major dependencies (table/bullets)
3. 模块地图 (Module Map) — table: Module | Responsibility | Primary paths (≤12 rows)
4. 核心流程 (Core Flows) — 2–4 critical flows as numbered steps (no code)
5. 技术选型 (Tech Stack) — stack, frameworks, infra (bullet list)
6. 系统边界 (System Boundaries) — external APIs, DBs, third-party, trust boundaries
7. 代码映射索引 (Code Map Index) — table: Concept | Location (paths only) | Notes (≤15 rows)

Developer meta (terrain-meta.json)

Repositories may ship one or more terrain-meta.json files (repo root, .terrain/, or nested). Before generating context, Terrain programmatically collects referenced files and injects them into the LLM prompt. The bundle is also written to agent/meta-inputs.md.

See terrain-meta.example.json in this skill directory.

Schema (version 1)

{
  "version": 1,
  "hints": {
    "module_roots": ["crates/", "src/"],
    "notes": "Free-form team hints"
  },
  "inputs": [
    { "label": "Modules doc", "type": "file", "path": "docs/architecture.md" },
    { "label": "ADRs", "type": "glob", "pattern": "docs/adr/*.md", "optional": true },
    { "label"      
  

Input types: file (path relative to repo or meta file), glob, inline. Each input may set optional and max_chars (default 3500).

How to use meta in output

• Treat collected meta as authoritative for 模块地图 and 系统边界
• Supplement with grep_agent_pack for path discovery only
• Do not invent modules that contradict developer meta
• Rule-based modules/ stubs are deprecated — synthesis is LLM-driven from meta + repomix

Rules

• Hard limit: ≤14000 characters — trimmed to 16 KiB on save if exceeded
• Macro sections (1–3) must be the densest; sections 4–7 can be shorter
• No function bodies, no code blocks > 3 lines
• Path references only — implementation detail lives in agent/repomix.md
• Use grep_agent_pack only to discover paths, never paste grep output
• Prefer tables and bullet lists over prose

ACP mode (Terrain)

When Terrain runs context generation in ACP mode, native function tools are unavailable. Use the terrain tools CLI instead:

terrain tools pack-meta --project {slug}
terrain tools grep-pack --project {slug} --pattern "module_name"
terrain tools read-pack-file --project {slug} --file src/foo.rs --start-line 1 --end-line 80

See terrain-ask-skill for the full CLI reference. Do not read the live repository filesystem.

Environment variables set by Terrain:

Variable	Purpose
TERRAIN_AGENT_ARCH_SKILL	This skill directory
TERRAIN_AGENT_CONTEXT_OUTPUT	Write target for agent/context.md
TERRAIN_KNOWLEDGE_ROOT	Project .terrain/ directory
TERRAIN_PROJECT_SLUG	Project slug
TERRAIN_REPO_PATH	Repository root

How Ask consumes this

• Macro: 项目概览 + 架构设计 + 模块地图 preloaded in the question
• Meso: other sections fetched on demand via read_agent_context(section=…)
• Micro: source code via grep_agent_pack → read_agent_pack_file