terraformer

Imported from LongbowXXX/terraformer (AGENTS.md). Install upstream with npx skills add LongbowXXX/terraformer. Copyright stays with the author.

AGENTS.md - Terraformer

A Meta-Engine that transforms legacy codebases into AI-Native environments by implementing the AI-Native Transformation Protocol (ANTP v1.4).

This file provides context and instructions for AI coding agents working on this project.

1. Executive Summary

Purpose: Eliminate "Context Debt" in legacy projects by generating specialized AI agents and standardized procedures (SOPs).

Type: Meta-Engine / Code Generator (Prompt-based, no runtime code)

Status: Beta (ANTP v1.4)

2. Architecture & Tech Stack

→ Details: docs/architecture/overview.md, docs/architecture/tech-stack.md

Core Patterns

• Four-Layer Stack (ANTP): L1 Constitution → L2 Commands → L3 Knowledge → L4 Agents
• Anti-Generalist Principle: @Developer has zero spec authority; must escalate

3. Directory Structure

→ Details: docs/architecture/directory-structure.md

terraformer/
├── .github/
│   ├── agents/                     # Agent Definitions (Target Project & Source)
│   ├── prompts/                    # Command Entry Points (Target Project & Source)
│   └── skills/                     # Skill Implementations (Detailed Command Logic)
├── docs/                           # Project-specific docs (architecture, features, specs)
├── knowledge/                      # Universal guidelines & templates
└── AGENTS.md                       # This file (L1: Constitution & L3: Knowledge Hub)

Note on Directory Structure: In this source repository, .github/agents/ contains the default agent definitions and .github/prompts/ contains all available commands. When Terraformer is installed in a Target Project, these definitions are copied or referenced.

4. Key Concepts (Ubiquitous Language)

→ Details: docs/glossary.md

This section defines the core terminology used across the project. For the full list of definitions, please refer to the detailed Glossary document linked above.

5. Entry Points & Key Flows

→ Details: docs/architecture/key-flows.md

6. Development Rules

→ Details: docs/rules/coding-conventions.md, docs/architecture/constraints.md

🔍 Dynamic Context Protocol (Research Phase)

CRITICAL INSTRUCTION FOR ALL AGENTS: The context provided in this file (AGENTS.md) is a summary index. It does NOT contain all the details needed for your tasks. Before starting any task, you MUST:

1. Search: Use your available tools to perform keyword/regex searches or semantic searches to find specific documentation in docs/ or knowledge/ relevant to the user's request.
   • Example: If the user asks about "Testing", search for and read documents related to testing instructions.
   • Example: If the user asks for a "Review", search for and read review guidelines.
2. Follow Links: Since AGENTS.md serves as a summary index and provides links to important files and folders, you MUST follow these links to obtain detailed information.
3. Read: Load the content of these detailed documents into your context.
4. Cross-Reference: Do NOT rely on assumptions. Always verify against the official documentation found.

Must Follow

• @Developer must immediately escalate spec gaps (Anti-Drift Lock)
• All Agents must follow Sequential Inquiry protocol when gathering information: Ask questions one by one, not in bulk.

Must Avoid

• @Developer making specification changes
• Generic AI interactions without role assignment

Role Enforcement & Access Control

• Adaptive Role Gating: When a skill file (.github/skills/*/SKILL.md) contains <role_gate>, agents MUST check if their ACTIVE_AGENT_ID matches the <required_agent>. If they do not match, the agent MUST read the required_agent's .agent.md definition. They should NOT refuse, but adopt the required role.

Adaptation Path for Role Mismatch

When an agent encounters a role mismatch due to <role_gate>, the agent MUST:

1. Read Identity: Read the .github/agents/{required_agent}.agent.md file (the agent required by the skill).
2. Allow: Execute the skill's instructions from the perspective of the Required Agent (temporary role adoption).
3. Proceed: Do NOT refuse. Switch personas and continue.

Role Declaration Protocol

At the start of any task involving a skill file, agents SHOULD explicitly declare their role to ensure clarity and prevent role drift:

1. Declare: State the current ACTIVE_AGENT_ID (e.g., "I am operating as @Debugger.").
2. Verify: Confirm that the task falls within the agent's defined responsibilities.
3. Proceed or Escalate: If the task is within scope, proceed. Otherwise, escalate or refuse as per the Escalation Path.

Agent/Command Maintenance

• When adding or updating Agents or Commands, please ensure to check the latest specifications at the URLs below.
  • https://code.visualstudio.com/docs/copilot/customization/prompt-files
  • https://code.visualstudio.com/docs/copilot/customization/custom-agents

Artifact-Centric Workflow (Spec-Driven L4)

Role: "1 Command = 1 Artifact" All agents MUST output their work as persistent Markdown artifacts in docs/specs/[FeatureName]/. Conversations are ephemeral; artifacts are eternal.

Pipeline:

1. Requirements: /bsa-requirements -> docs/specs/[Feature]/requirements.md
2. Design: /arc-design -> docs/specs/[Feature]/design.md
3. Plan: /arc-plan -> docs/specs/[Feature]/implementation_plan.md
4. Implementation: /dev-implement -> Code (src/...)

Context Hygiene:

• Agents should only read the artifacts relevant to their phase.
• Do NOT rely on chat history for critical specifications.

Language Guidelines

• Documentation: All documents managed in git must be written in English.
• Chat Interaction: Interact with the user in their preferred language.

7. Testing

→ Details: docs/rules/testing.md

Manual verification via test projects; automated CI planned.

8. Quick Reference

Agents (The Specialized Team)

Commands

📚 Detailed Documentation Index

9. Knowledge Base

→ Details: knowledge/

Context map for AI coding agents - Terraformer (ANTP v1.4)