Root AGENTS.md Directive Protocol for Termux Matrix VM

AGENTS.md

CRITICAL SYSTEM PROTOCOL: MATRIX-MSG & MATRIX-ASK ONLY

⚠️ MANDATORY REMOTE VM WORKFLOW: This Termux environment runs remotely inside an isolated virtual machine. The user is located elsewhere and communicates solely via the Matrix network.

1. ALWAYS ACTIVE REMOTE PRESENCE: You are ALWAYS running remotely inside an isolated virtual machine. Do NOT assume you are in a local terminal session. You are ALWAYS in a remote VM session, and you MUST always communicate solely via Matrix by executing terminal commands!
2. NEVER EXIT CHAT TERMINAL SESSIONS: You must NEVER simply print a chat response to standard stdout and stop. If you do, your execution ends, and the remote user cannot reply!
3. ALWAYS EXECUTE MATRIX-END TO RESPOND: When you are done with a task, answered a question, or are ready to respond, you MUST execute the matrix-end command in the shell to block the terminal indefinitely and wait for a reply: NEW_TASK=$(matrix-end "Your message/response here")
4. USE NO-REPLY FOR SILENT NOTIFICATIONS: If you are merely notifying the user and absolutely no response is expected, use matrix-msg --no-reply -m "...". Do not use this if you want the process to continue running, need to ask a question, or have to apply file changes.
5. AUTOMATED BACKGROUND SESSION INITIALIZATION: You do NOT need to manually run matrix-msg --new-session or worry about room initialization. Simply send messages and prompt questions using matrix-msg, matrix-ask, and matrix-end directly, and the scripts will silently set up the environment in the background if needed!

🚫 THE BAD WAY vs. ✅ THE GOOD WAY

• ❌ BAD WAY: User replies in the terminal, AI replies in terminal (prints text chat response directly to stdout and exits) — This is a bad way.
• ❌ BAD WAY: User replies in the Matrix, AI replies in the terminal (prints text chat response directly to stdout and exits) — This is a bad way.
• 🔑 GOOD WAY: User replies in the terminal, AI replies in the Matrix (executes Matrix script) — This is a good way.
• 🔑 GOOD WAY: AI sends message/question, User replies in the Matrix, AI replies back in the Matrix — This is a good way.

⛔ ZERO TOLERANCE RULES

• EVERY SINGLE RESPONSE must go through matrix-end or matrix-msg. There are NO exceptions — not even for greetings like "hi", "how are you", or casual small talk. If the user says "hey", you respond with matrix-end "Hey! What do you need?", NOT by printing text.
• NEVER PRINT TEXT AFTER matrix-end RETURNS. When matrix-end finishes and returns the user's follow-up reply, process it and respond with ANOTHER matrix-end call. Do NOT summarize the conversation, do NOT print what you did, do NOT add commentary. The terminal is NOT where the user reads your output.
• YOUR VERY FIRST ACTION in any new conversation or task must be a Matrix command. Before doing anything else — before thinking, before planning, before coding — run matrix-end or matrix-msg to establish communication. The user cannot see terminal output.

🔗 GitHub Gist Reference: https://gist.github.com/Brajesh2022/1a30f057a53f617a9cb1b8da2a9878fa

Karpathy Guidelines

Behavioral guidelines to reduce common LLM coding mistakes, derived from Andrej Karpathy's observations on LLM coding pitfalls.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

Matrix Communication (CRITICAL)

The Termux terminal environment is running remotely (e.g., in a virtual machine or isolated environment) and the user is elsewhere, communicating solely via the Matrix network. MANDATORY: All alerts, updates, and interactive prompts must occur strictly over Matrix. You must never prompt for standard terminal inputs or expect manual terminal responses.

1. Starting a Session (Automated)

You do NOT need to manually run matrix-msg --new-session or worry about room initialization. Simply send messages and prompt questions using matrix-msg, matrix-ask, and matrix-end directly, and the scripts will silently set up the environment in the background if needed!

2. Status Updates & Notifications

Instead of local notifications, use matrix-msg to send updates directly to the active Matrix session room at significant checkpoints:

• Task Updates: Send regular progress updates using matrix-msg.
• Errors: When an error occurs that requires intervention.
• Destructive Actions: BEFORE and AFTER performing destructive or irreversible operations (e.g., rm -rf, git reset --hard).
• Inquiry Resolution: When an analysis or research task is complete.

Usage:

• Simple Update: matrix-msg "Your update here"
• Markdown Update: matrix-msg -m "Task **Completed** successfully! ✅"
• No-Reply Announcement: If a message is just a silent update/alert and requires no user interaction, use the -n / --no-reply option. Use this flag ONLY when you are merely notifying the user and no response is expected. This flag is a silent message, not a message to be expected a reply. Do NOT use this flag if you want the process to continue running, need to ask a question, or have to apply additional file changes. matrix-msg --no-reply -m "Build completed successfully! 🚀"

3. Interactive Prompts & Questions

When you require user feedback, a decision, or clarification, never ask in the terminal or halt. Instead, run matrix-ask to ask the question or send a file. The script will block and poll the Matrix room indefinitely until the user responds on their phone, returning their response directly to your process:

• Ask a Question: RESPONSE=$(matrix-ask -m "Do you want to proceed with the Vercel deployment? (yes/no)")
• Send a File & Ask: RESPONSE=$(matrix-ask -m "Please review the generated implementation plan below." -f /path/to/plan.md)

4. Ending a Task & Resuming (CRITICAL FLOW)

When you have finished executing your current task, answered the user's question, or are ready to respond, you must NEVER simply print a text chat response and stop. If you do, your execution will end, and the remote user won't be able to reply via Matrix! Instead, you MUST run the task completion handler matrix-end as a blocking terminal command. This command will send your final message to Matrix and poll indefinitely until the user replies on their phone, returning their message directly to your shell to continue work.

• How to respond/end your turn: NEW_TASK=$(matrix-end "Your message/response here") (This keeps the session alive, blocks indefinitely, and waits for the user's Matrix reply to wake you back up!)

Git & GitHub Workflow

To prevent being stuck at interactive credential prompts (Username/Password):

• Authentication: Always ensure gh auth setup-git has been run so Git uses the GitHub CLI for credentials.
• Cloning: Prefer gh repo clone <repo> over standard git clone for better authentication handling.
• Clone Location: Treat Termux home (/data/data/com.termux/files/home) as the primary working directory for cloning repositories and doing project work. Do not clone new projects inside the current project folder unless explicitly requested.
• Existing Clones: If the requested clone target already exists, keep the existing folder safe by renaming it with the current date and time, or clone the fresh copy into a date/time-suffixed folder. Never overwrite an existing clone without explicit approval.
• PRs: Always create a feature branch (git checkout -b branch-name) before committing. Use gh pr create --fill to create Pull Requests non-interactively.
• Pushing: If a push fails with a credential prompt, verify that the GitHub CLI token is valid and that setup-git is configured.
• Git Config: Always use the email 138358890+Brajesh2022@users.noreply.github.com and username Brajesh for commits to avoid Vercel deployment failures.

Cloudflare Setup & Permissions

Cloudflare is configured on this Termux environment for use by local AI agents, but agents must only use it when the user explicitly allows a Cloudflare action in the current conversation. Do not inspect, change, create, deploy, delete, or list Cloudflare resources unless the user asks for that Cloudflare task or clearly grants permission.

• Credentials load from ~/.cloudflare/cloudflare.env and expose CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, CF_ACCOUNT_ID, and CF_API_TOKEN.
• Do not print, reveal, copy, or commit the Cloudflare token. Treat ~/.cloudflare/cloudflare.env as secret material.
• Use cf-verify to verify token access before Cloudflare work.
• Use direct Cloudflare API calls with the loaded token for reliable automation.
• cloudflared is installed for Cloudflare Tunnel work.
• wrangler is installed as a Termux-compatible v2 fallback. Modern Wrangler versions require workerd, which does not publish Android arm64 binaries, so not every Wrangler command will work here.
• For destructive Cloudflare actions, including deleting Pages projects, deployments, DNS records, Workers, KV/R2/D1 data, or tunnels, send a Matrix notification using 'matrix-msg' before and after the action and make sure the user's request clearly authorizes it.
• Cloudflare Pages custom domains can usually be changed on the same project. A default *.pages.dev subdomain is tied to the Pages project name and usually requires creating a new project to change.

Personal Scratch Space

Treat the current project folder as the agent's personal scratch/place when the user allows exploratory or disposable work. It can be used for drafts, experiments, temporary files, fun prototypes, or messy throwaway ideas. Keep real cloned repositories and serious project work in Termux home unless the user gives a different location.

Agent Skills

Agent Skills allow you to extend Gemini CLI with specialized expertise, procedural workflows, and task-specific resources. Based on the Agent Skills open standard, a "skill" is a self-contained directory that packages instructions and assets into a discoverable capability.

Overview

Unlike general context files (GEMINI.md), which provide persistent workspace-wide background, Skills represent on-demand expertise. This allows Gemini to maintain a vast library of specialized capabilities—such as security auditing, cloud deployments, or codebase migrations—without cluttering the model's immediate context window.

Gemini autonomously decides when to employ a skill based on your request and the skill's description. When a relevant skill is identified, the model "pulls in" the full instructions and resources required to complete the task using the activate_skill tool.

Available Skills in this Workspace

UI Quality (ui-quality)

• What it is: A production-grade UI/UX quality skill for frontend builds, edits, reviews, layout fixes, styling updates, responsive behavior, and visual polish.
• When to use: Use this skill for any frontend, UI, UX, design, styling, layout, component, page, screen, or visual quality task, including small changes like button colors or spacing.

UI/UX Pro Max (ui-ux-pro-max-skill)

• What it is: A deep UI/UX design intelligence bundle covering visual systems, interaction quality, accessibility, typography, colors, brand, banners, slides, design systems, and implementation references.
• When to use: Use this skill for any new interface, frontend feature, page, component, design-system work, redesign, responsive work, or change that affects how the product looks, feels, moves, or is used.

Impeccable (impeccable)

• What it is: A frontend design skill installed at ~/.agents/skills/impeccable, based on Anthropic's frontend-design skill, with 23 commands for shaping, building, auditing, polishing, adapting, animating, colorizing, optimizing, and live-iterating interfaces.
• When to use: Use for design/redesign, UX critique, visual polish, responsive behavior, accessibility, UI performance, typography, layout, motion, copy, edge cases, and reusable design systems or tokens.
• Command menu: craft, shape, teach, document, extract, critique, audit, polish, bolder, quieter, distill, harden, onboard, animate, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, live.

TypeUI Design Packs (paper, elegant, shadcn, gradient)

• What they are: TypeUI registry design-system skills installed at ~/.agents/skills/paper, ~/.agents/skills/elegant, ~/.agents/skills/shadcn, and ~/.agents/skills/gradient.
• Pull commands: npx typeui.sh pull paper, npx typeui.sh pull elegant, npx typeui.sh pull shadcn, npx typeui.sh pull gradient.
• When to use: Use these style-specific skills when the user asks for paper-textured/print-inspired, elegant/refined, shadcn/ui-inspired, or gradient-rich frontend design guidance.

Frontend Prompt Crafter (frontend-prompt-crafter)

• What it is: A prompt-generation skill installed at ~/.agents/skills/frontend-prompt-crafter for creating detailed frontend web-generation prompt files from rough product, page, UI, or design-system ideas.
• When to use: Use this skill when the user asks to generate a prompt, prompt file, frontend web-generation prompt, UI generation prompt, landing-page prompt, dashboard prompt, website prompt, or component-integration prompt for another AI/code generator.
• Output rule: This skill must write the finished prompt into a Prompt/ directory and send it with matrix-ask -f <absolute-path>.
• Do not use for: Directly implementing frontend code in the current project. For implementation, use the mandatory frontend skills instead.

Mandatory Frontend Skill Rule

• For any frontend, UI, UX, visual design, styling, layout, responsive, component, page, screen, design-system, or new app/site work, use impeccable together with ui-quality and ui-ux-pro-max-skill before planning or editing.

Key Benefits

• Shared Expertise: Package complex workflows (like a specific team's PR review process) into a folder that anyone can use.
• Repeatable Workflows: Ensure complex multi-step tasks are performed consistently by providing a procedural framework.
• Resource Bundling: Include scripts, templates, or example data alongside instructions so the agent has everything it needs.
• Progressive Disclosure: Only skill metadata (name and description) is loaded initially. Detailed instructions and resources are only disclosed when the model explicitly activates the skill, saving context tokens.

Skill Discovery Tiers

Gemini CLI discovers skills from three primary locations:

1. Workspace Skills: Located in .gemini/skills/ or the .agents/skills/ alias. Workspace skills are typically committed to version control and shared with the team.
2. User Skills: Located in ~/.gemini/skills/ or the ~/.agents/skills/ alias. These are personal skills available across all your workspaces.
3. Extension Skills: Skills bundled within installed extensions.

Precedence: If multiple skills share the same name, higher-precedence locations override lower ones: Workspace > User > Extension.

Within the same tier (user or workspace), the .agents/skills/ alias takes precedence over the .gemini/skills/ directory.

Managing Skills

In an Interactive Session

Use the /skills slash command to view and manage available expertise:

• /skills list: Shows all discovered skills and their status.
• /skills reload: Refreshes the list of discovered skills from all tiers.

From the Terminal

# List all discovered skills
gemini skills list

# Link agent skills from a local directory via symlink
gemini skills link /path/to/my-skills-repo --scope workspace

# Install a skill from a Git repository or local directory
gemini skills install https://github.com/user/repo.git --scope workspace

OpenCode Maintenance Protocol (Termux/Glibc)

OpenCode on this system requires a specialized setup because the native NPM package does not support the 'android' platform. Use the following protocol to install, repair, or update OpenCode respectfully:

1. Research & Backup

• Check Version: Run npm view opencode-ai version to find the latest version.
• Backup Config: ALWAYS backup ~/.config/opencode and ~/.cache/opencode (e.g., to .bak folders) before any changes.
• Verify Environment: Ensure grun and glibc packages are installed.

2. Manual Update/Installation Procedure

Do NOT use npm install -g or the standard installation script, as they will fail or create "file not found" errors.

1. Download: Use npm pack opencode-linux-arm64@latest (or a specific version) to download the Linux tarball.
2. Extract: Extract the binary (bin/opencode) from the tarball and move it to ~/.opencode/bin/opencode.
3. The Grun Wrapper: Ensure a wrapper script exists at ~/bin/opencode (which is in the PATH) with this content:

   #!/data/data/com.termux/files/usr/bin/bash
   grun /data/data/com.termux/files/home/.opencode/bin/opencode "$@"

4. Permissions: Apply chmod +x to both the raw binary and the wrapper script.

3. Restoration & Cleanup

• Restore Data: Move the backed-up .config and .cache folders back to their original locations to ensure session data is preserved.
• Verification: Run opencode --version to confirm functionality.
• Cleanup: Delete temporary installation files and downloaded .tgz archives.

4. Critical Constraints

• Respectful Updates: Never delete ~/.config/opencode without a backup. This contains the user's session data.
• No Path Hacks: Do not add ~/.opencode/bin to the PATH in shell configs; it will attempt to run the binary without grun and fail. Use the ~/bin/opencode wrapper instead.