agent-architect

name	agent-architect
description	MANDATORY: Invoke this skill ONLY when modifying, adding, auditing, or refactoring the prompt files, rules, agents, commands, or skills inside this specific 'agent.files' configuration repository. It provides the structural mapping and macro-compilation logic for the Agentic Unified Prompt Compiler (AUPC).
disable-model-invocation	true

Agent Architect Core Knowledge Base

SCOPE CONSTRAINT (CRITICAL): You have been invoked as the Principal Maintainer of the agent.files repository. This skill ONLY applies when the user is explicitly requesting changes to the Agent OS configuration files (prompts, rules, agent definitions) located within this specific repository. If the user is asking you to write regular software code for a different project, IGNORE THIS DOCUMENT.

---

1. The Core Logic: The Macro Compilation System

This project is a compiler for AI prompts. We maintain a Single Source of Truth in the _core/ directory and compile it into IDE-specific formats (OpenCode, Cursor, Copilot) using a custom Zig compiler (agentc).

The Dependency Injection Syntax: We use HTML comments to inject reusable markdown blocks: <!-- @import path/to/file.md -->

Nested Import Logic (CRITICAL TO UNDERSTAND): The compiler supports recursive (nested) imports.

1. Host Shells (e.g., opencode/agents/plan.md) import high-level core modules.
2. Core modules (e.g., _core/2_workflows/feature_dev.md) can import lower-level core modules (e.g., _core/1_governance/hitl_gates.md).
3. When modifying or auditing: You must trace these import chains to understand the final compiled context of any given agent. Do not duplicate rules in a Host Shell if they are already being injected via a nested import.

---

2. Directory Paradigm & Maintenance Rules

To edit or maintain this project, you must strictly respect the boundary between Universal Philosophies and IDE-Specific Mechanics.

A. The Universal Source (_core/)

• Purpose: Abstract software engineering philosophies, shared skills, and shared command logic.
• Maintenance Rule: When the user requests a new development rule, coding standard, or workflow change, you MUST implement it here.
• Dimensional Structure:
  • 1_governance/: Supreme laws (HITL, anti-loop, safety).
  • 2_workflows/: Process flows (git ops, feature dev, triage).
  • 3_engineering/: Quality standards (architecture, testing, security).
  • 4_refactoring/: Tech debt management.
  • 5_commands/: Core logic for slash commands (e.g., /refactor).
  • skills/: Atomic capabilities (e.g., go, aws, privacy-guard).

B. The Host Shells (opencode/, cursor/, copilot/)

• Purpose: The physical bodies. They contain the YAML frontmatter, JSON configurations, and explicit routing mechanics unique to that IDE.
• Maintenance Rule: Edit these files ONLY when modifying IDE-specific metadata or adjusting which _core/ macros are injected.

C. The Compiled Output (dist/)

• NEVER edit files in dist/. They are ephemeral read-only outputs generated by agentc.

---

3. The Lexical Ban & Subagent Awareness (Purity Constraint)

When editing files in _core/, you MUST adhere to the Lexical Ban to ensure cross-platform compatibility.

• Forbidden Words in _core/: glob, grep, Task tool, build subagent, YAML frontmatter, @Codebase, .mdc.
• Built-in Subagent Awareness: IDEs like Cursor natively provide Explore, Bash, and Browser subagents with automatic routing. Rules MUST NOT manually micromanage their invocation (e.g., "Delegate to the explore subagent").
• How to write: Write goal-oriented instructions. Instead of "Use the explore subagent to search", write "Thoroughly analyze the codebase". Instead of "Run git status using the bash tool", write "Run git status."

---

4. OpenCode Strictness (Multi-Agent Alignment)

When maintaining the opencode/ host shells, enforce these rules to prevent execution deadlocks:

• Permission Alignment: Prompt instructions MUST perfectly align with the YAML permission blocks defined in the shell. Do not instruct an agent to use a tool or subagent (e.g., /architect) if it is denied in its YAML.
• Edit Accuracy Isolation: The _core/1_governance/edit_accuracy.md macro contains OpenCode-specific workaround mechanics (read timestamp checks). It MUST ONLY be imported by write-enabled agents (e.g., build.md, refactor.md, docs.md, build-error-resolver.md). Never import it into read-only agents or global files.

---

5. Cursor Dual-Engine Standards

When maintaining the cursor/ host shell, enforce these rules for both engines.

Engine 1: Contextual Rules (.cursor/rules/*.mdc)

• .mdc Rule Hygiene: Rules must use alwaysApply: false and highly specific globs (e.g., *.go, src/**/*.ts). Use alwaysApply: true ONLY for absolute project-wide safety constraints.
• Interlock Directives (SLASH SYNTAX REQUIRED): Each .mdc rule should include a contextual Interlock telling the main agent WHEN to invoke a subagent. You MUST use the SLASH (/) syntax to invoke subagents, NOT the @ syntax. @ only mounts text; / invokes the agent.
  • GOOD: "When modifying authentication flows, you MUST delegate to /security-auditor to audit the changes."
• Forbidden in Cursor Shells: OpenCode-specific mechanics (Edit vs Write preferences, Task tool, timestamp checks). Do NOT explicitly declare built-in subagents (Explore, Bash, Browser) in global files, as it interferes with automatic routing.

Engine 2: Isolated Subagents (.cursor/agents/*.md)

• Required Frontmatter: MUST contain name, description, model, readonly, and is_background.
• Cost Efficiency: model: fast for high-volume tasks (verifier, debugger); model: inherit for deep reasoning (architect, security).
• Context Isolation: Subagents start with a clean context window. Prompts must explicitly instruct the agent to gather context first.

---

6. The Extensibility Protocol (Scaling to New IDEs)

When the user requests support for a new IDE or platform (e.g., GitHub Copilot, Windsurf), you must follow this strict checklist to extend the AUPC architecture:

1. Create the Root Directory: Initialize the new target folder (e.g., copilot/).
2. Map the File Structure: Recreate the folder hierarchy required by the target IDE (e.g., prompts/, rules/, .github/, mcp.json).
3. Create Minimalist Host Shells: Write the IDE-specific adapter files. These should contain ONLY the required frontmatter/JSON and the <!-- @import _core/... --> tags. Do not write raw instructions in the shell.
4. Update the Compiler: Instruct the user to modify the Zig compiler's build.zig or the ./agentc-cli script to support building and linking the new output path to the dist/ directory.

---

7. Modification Workflow (Strict HITL)

When the user requests an architectural change to this repository:

1. Analyze & Trace: Identify the correct files to modify. Trace the <!-- @import --> chains to ensure you are editing the rule at its root source.
2. Sanitize: Rigorously check proposed text against the Lexical Ban.
3. Plan: Output a structured Markdown plan detailing exactly which files will be touched, and the exact text/macros to be added, removed, or modified.
4. WAIT: Stop and ask the user for explicit approval before writing to the file system.
5. Compile: After making approved changes, remind the user to run ./agentc-cli build and ./agentc-cli link <ide>.