Cognitive Lead Hq

Version License OpenCode PRs

The centralized Headquarters for the Cognitive Lead AI multi-agent system — a collection of hallucination-resistant system prompts, MCP servers, and strict Agent Skills (SKILL.md) built for OpenCode.

Quick Install: Copy this line and give it to OpenCode:

Use webfetch on https://raw.githubusercontent.com/mokhtarabadi/cognitive-lead-hq/main/LLM.txt and follow its instructions to auto-configure everything for me.

---

Quick Start

Give the prompt above to OpenCode and it will auto-configure itself globally using LLM.txt — the canonical auto-setup source. No manual steps required.

For full platform-specific instructions (Windows, macOS, Linux), see LLM.txt.

---

How to Operate: The Brain & The Hands

This system relies on a strict separation of concerns:

• The Brain (The Orchestrator): You paste the system-prompt.md here. It acts as the Orchestrator. It has no direct access to your files or terminal. It thinks, plans, and generates XML task blocks.
• The Hands (OpenCode): Runs locally on your machine. You paste the XML task blocks here. It executes file changes, runs bash commands, triggers Agent Skills, and generates task summaries to feed back to the Brain.
• The QA Loop: After OpenCode implements a task, the Manager pastes the task file back to the Orchestrator. The QA Engineer persona performs adversarial testing — actively trying to break the logic. If QA fails, a fix task is generated. If QA passes, the Code Reviewer does a final architectural review before the task is committed and closed.

Scenario A: Phase 0 for a Brand New Project

1. Initialize an empty repository on your machine and start OpenCode.
2. In the Orchestrator, paste the system-prompt.md and say: "This is a new project. Start Phase 0."
3. Tell the AI your desired tech stack (e.g., Next.js, Node.js).
4. The AI will generate an implementation task instructing OpenCode to:
   • Copy the relevant stack SKILL.md template from your global skills directory.
   • Create opencode.json with the required schema.
   • Set up the tasks/ directory and use the task-generator skill to create your first 01-initial-setup.md task.

Scenario B: Phase 0 for an Existing Project (Never used this workflow)

1. Open your existing project in OpenCode.
2. In the Orchestrator, paste the system-prompt.md and say: "This is an existing project. Start Phase 0."
3. The AI will immediately output an <opencode_discovery_task>. Paste this into OpenCode.
4. OpenCode will use its MCP tools to map the directory tree and read core files into a context-reports/ markdown file.
5. Copy the contents of that report and paste it back into the Orchestrator.
6. The AI will analyze your existing architecture and design, then generate an implementation task to create AGENTS.md (<150 lines), DESIGN.md (if UI exists), opencode.json, and the tasks/ directory, locking in your current conventions.

Scenario C: Migrating a V4 Project to V5

If you have an older project using global STATE.md and TODO.md files:

1. Open the project locally. Delete STATE.md and TODO.md.
2. Create a tasks/ directory.
3. In the Orchestrator, paste the new V5 system-prompt.md.
4. Tell the AI: "Migrate this project from V4 to V5. Generate a task to update AGENTS.md and move existing roadmap items into tasks/01-v5-migration.md."
5. Ensure the task-generator and audit-agents skills are imported into .opencode/skills/ (or installed globally).

Inline Markdown Reviews & Strict Approval

Before any code is written, the Brain will present an Architectural Blueprint or Plan. OpenCode will not execute any implementation tasks without your explicit approval.

To leave feedback directly on the generated Markdown plans:

1. Copy the plan into your editor.
2. Add > 📝 **MANAGER REVIEW:** blockquotes immediately below the section you want to change.
3. Alternatively, use standard Markdown strikethrough (~~text~~) and bold (**text**) for direct edits.
4. Paste the annotated Markdown back to the Orchestrator.

The AI will process your inline feedback, generate a revised plan, and wait for your final "Approved" signal before writing code.

Manager Profile & AI Coaching

The system-prompt.md includes a <manager_profile> and <leadership_and_language_protocol>. By default, this is configured for the original author, acting as an Executive Coach and English Tutor.

• Language & Vocabulary Corrections: If the AI notices grammatical errors or forgotten industry keywords in your prompts, it will append a small > 💡 **Coach's Note:** at the end of its response to teach you the correct term or pronunciation.
• Ruthless Soft-Skills Feedback: When you close a sprint or ask for feedback (e.g., "Give me your ruthless feedback about me so I can improve"), the AI personas will critique your tone and management style, telling you how a real human would have reacted to your instructions.

Customizing for Yourself: Open system-prompt.md and edit the <manager_profile> block. Put in your own name, technical background, career goals, and the specific soft skills or languages you want the AI to help you improve.

---

Repository Structure

/
├── README.md                           # This file
├── system-prompt.md                    # V7 Multi-Agent System Prompt
├── CHANGELOG.md                        # Version history
├── tasks/
│   ├── backlog/                        # Open / unstarted tasks
│   ├── in-progress/                    # Currently being worked on
│   ├── qa/                             # Awaiting quality assurance review
│   ├── completed/                      # Finished tasks
│   └── archive/                        # Milestone-compacted historical tasks
├── docs/
│   ├── conventions.md                  # Syntax rules and automation conventions
│   ├── history/                        # Milestone compaction summaries
│   └── opencode/                       # OpenCode documentation mirror
├── mcp-context-server/
│   └── server.py                       # FastMCP server for .gitignore-aware file reading & tree
├── .opencode/
│   └── skills/
│       └── sop-maintenance/
│           └── SKILL.md                # Native OpenCode skill for repo rules
├── skill-templates/                    # Reusable stack blueprints (Agent Skills)
│
│   **General & Workflow:**
│
│   ├── archive-tasks/                  # Milestone compaction skill
│   │   └── SKILL.md
│   ├── audit-agents/                   # AGENTS.md generation & ZAC audits
│   │   └── SKILL.md
│   ├── brainstorm-swarm/               # Multi-persona brainstorming sessions
│   │   └── SKILL.md
│   ├── code-search/                    # MCP-based codebase discovery
│   │   └── SKILL.md
│   ├── debug-instrumentation/          # Strategic logging for complex bug diagnosis
│   │   └── SKILL.md
│   ├── design-md/                      # Design system extraction (DESIGN.md)
│   │   └── SKILL.md
│   ├── doc-coauthoring/                # Structured documentation co-authoring
│   │   └── SKILL.md
│   ├── migrate-kanban/                 # Flat-to-Kanban migration skill
│   │   └── SKILL.md
│   ├── perplexity-research/            # Human-in-the-loop deep research
│   │   └── SKILL.md
│   ├── project-memory/                 # Persistent project memory bank
│   │   └── SKILL.md
│   ├── prompt-refactor/                # Refactors raw prompts into elite XML specs
│   │   └── SKILL.md
│   ├── task-generator/                 # Generates tasks in tasks/backlog/
│   │   └── SKILL.md
│   ├── telegram-issue-sync/            # Telegram topics → tasks/GitHub sync
│   │   └── SKILL.md
│   ├── telegram-message-export/        # Export Telegram messages to ZIP
│   │   └── SKILL.md
│   ├── verification-before-completion/ # Mandatory verification gate
│   │   └── SKILL.md
│   ├── versioning-and-release/         # SemVer, Changelog, Commit standards
│   │   └── SKILL.md
│
│   **Stack-Specific Blueprints:**
│
│   ├── android-kotlin/                 # 100% Jetpack Compose + MVI + Hilt
│   │   └── SKILL.md
│   ├── flask-python/                   # Application Factory + SQLAlchemy
│   │   └── SKILL.md
│   ├── go-gin/                         # Idiomatic Go + Clean Architecture
│   │   └── SKILL.md
│   ├── go-hexagonal-grpc/              # Ports & Adapters + gRPC + Uber Fx
│   │   └── SKILL.md
│   ├── ios-swiftui/                    # SwiftUI + MVVM
│   │   └── SKILL.md
│   ├── nestjs-prisma-vertical/         # NestJS + Prisma + Vertical Slices
│   │   └── SKILL.md
│   ├── nextjs/                         # App Router + Server Actions + Tailwind
│   │   └── SKILL.md
│   ├── python-fastapi/                 # Pydantic V2 + modular routing
│   │   └── SKILL.md
│   ├── react-native-expo/              # Expo Managed + NativeWind
│   │   └── SKILL.md
│   ├── react-vite/                     # React 18+ SPA + hooks
│   │   └── SKILL.md
│   ├── spring-boot/                    # DDD + hexagonal-style packaging
│   │   └── SKILL.md
│   └── vue-nuxt/                       # Vue 3 Composition API + Nuxt 3
│       └── SKILL.md
└── user-prompts/                       # Reusable copy-paste prompt templates
    ├── cold-start-context.md
    ├── session-compactor.md
    ├── voice-to-text-enhancer.md
    ├── persian-to-english-dictation.md
    └── agile-pm-state-manager.md

---

Agent Skills Registry

General & Workflow Skills

Skill Name	Purpose
audit-agents	Enforces Zero-Autonomous-Commit (ZAC) workflows and generates/audits AGENTS.md for new and existing projects.
code-search	Mandatory for discovery. Uses MCP tools (get_directory_tree, read_source_files, extract_signatures) to explore the codebase without token bloat.
debug-instrumentation	Diagnoses complex runtime bugs, deadlocks, race conditions, and silent failures via strategic temporary logging and tracing.
design-md	Extracts a comprehensive design system (DESIGN.md) directly from frontend source code — React, Vue, Svelte, Angular, plain HTML/CSS, or any web framework.
doc-coauthoring	Guides users through a structured 3-stage workflow (Context Gathering, Refinement & Structure, Reader Testing) for co-authoring documentation with AI.
prompt-refactor	Meta-cognitive skill that refactors basic human prompts into elite, highly constrained, XML-tagged instructions optimized for AI agent reasoning.
task-generator	Automatically generates decentralized task files based on Manager instructions, with correct <!-- BEGIN_GIT_DIFF --> / <!-- END_GIT_DIFF --> markers.
telegram-issue-sync	Syncs Telegram supergroup topics into local task files and GitHub issues, using embedded Python scripts for deterministic JSON state management.
telegram-message-export	Intelligently exports a range of Telegram messages (text, media, voice notes) into a numbered folder, capturing reply hierarchies, and packing them into a ZIP archive.
versioning-and-release	Standardizes Semantic Versioning (SemVer), Keep a Changelog formats, Conventional Commits, and Safe Push Protocols across all repositories.

Stack-Specific Blueprints

Stack	Architecture Enforced
Android Kotlin	100% Jetpack Compose — XML Strictly Banned. MVI (UDF), Hilt, SQLDelight/Room.
Flask Python	Application Factory, Blueprints, SQLAlchemy, and config separation for modular Flask applications.
Go Gin	Idiomatic Go, Clean Architecture layers, and Gin routing best practices for RESTful services.
Go Hexagonal gRPC	Hexagonal Architecture (Ports and Adapters), gRPC, Uber Fx compile-time DI, Redis caching, and PostgreSQL.
iOS SwiftUI	SwiftUI, MVVM, and modern iOS app architecture with declarative UI patterns.
NestJS Prisma Vertical	NestJS, Prisma ORM, Vertical Slice Architecture, strict TypeScript, and class-validator DTOs.
Next.js	App Router, Server/Client Component separation, Server Actions, and Tailwind CSS design tokens.
Python FastAPI	Pydantic schemas, dependency injection, async routing, and layered service architecture.
React Native Expo	Expo Managed Workflow ONLY — no native folders. Expo Router, NativeWind, Zustand, strict TypeScript.
React Vite	React 18+ SPA architecture, hooks, and Vite configuration with optimized build tooling.
Spring Boot	DDD, hexagonal-style packaging, MapStruct, constructor injection, and global exception handlers.
Vue Nuxt	Vue 3 Composition API, Nuxt 3 routing, and Pinia state management.

---

Custom Code Context MCP

This system uses a local FastMCP Python server (mcp-context-server/server.py) that runs via uv run with zero-install dependency management. It provides deterministic, .gitignore-aware file reading and directory tree exploration, using far fewer tokens than raw grep/glob operations.

Setup Instructions

This server can be installed locally per-project, or globally for all OpenCode sessions on your machine.

Option A: Project-Level Setup (New or Existing Projects)

Best for keeping project dependencies isolated.

1. Copy mcp-context-server/server.py into your project root.
2. Ensure it is executable: chmod +x mcp-context-server/server.py.
3. Add the following to your project's ./opencode.json:

{
  "mcp": {
    "custom_context": {
      "type": "local",
      "command": ["uv", "run", "mcp-context-server/server.py"],
      "enabled": true,
      "timeout": 15000
    }
  },
  "permission": {
    "custom_context_*": "allow",
    "get_directory_tree": "allow",
    "read_source_files": "allow"
  }
}

Option B: Global Setup (System-wide)

Best if you want this codebase exploration tool available in every terminal directory automatically.

1. Create a global directory for the server: mkdir -p ~/.config/opencode/mcp-context-server
2. Copy the server.py script into that directory.
3. Make it executable: chmod +x ~/.config/opencode/mcp-context-server/server.py.
4. Open your global config at ~/.config/opencode/opencode.json and add the absolute path:

{
  "mcp": {
    "custom_context": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "/Users/<YOUR_USER>/.config/opencode/mcp-context-server/server.py"
      ],
      "enabled": true,
      "timeout": 15000
    }
  },
  "permission": {
    "custom_context_*": "allow",
    "get_directory_tree": "allow",
    "read_source_files": "allow"
  }
}

(Note: Replace /Users/<YOUR_USER> with your actual home directory path).

How It Works

1. opencode.json configures the custom context server as a local MCP server.
2. When OpenCode needs to explore code, it uses get_directory_tree and read_source_files tools.
3. All file reads respect .gitignore rules and skip binary/large files automatically.
4. The strategy is documented in skill-templates/code-search/SKILL.md.

Available Tools

• get_directory_tree — Generates an ASCII tree of the directory structure, respecting .gitignore.
• read_source_files — Reads multiple source files or directories and saves their contents into a local Markdown report inside the context-reports/ directory, returning the file path to prevent context bloat.

---

Global Skills Deployment

To make the code-search skill (or any other reusable skill) available in every terminal directory on your machine automatically, copy the skill folder into your global OpenCode configuration path.

Step-by-Step Global Installation:

1. Create the global skills directory (if it does not exist yet):

   mkdir -p ~/.config/opencode/skills
   

2. Copy the desired skill folder into the global skills directory: For example, to install our custom code-search skill globally:

   cp -r skill-templates/code-search ~/.config/opencode/skills/
   

3. Verify the installation: In any folder on your machine, start OpenCode and run:

   /help
   

   Under the available skills list, you will see code-search listed. You can now use it in any project by asking:

   @explore find the main router using the code-search skill
   

---

Key V5 Changes

• Decentralized task architecture — global STATE.md and TODO.md replaced by isolated task files in tasks/ directory.
• Brain/Hands separation codified — system-prompt.md explicitly declares the Orchestrator as the text-only Brain and OpenCode as the local execution agent.
• New Agent Skills — task-generator for creating numbered task files and audit-agents for enforcing AGENTS.md workflows.
• Phase 0 UI/UX traversal — Project Planner now instructs OpenCode to perform deep source code analysis for DESIGN.md generation.
• Runtime model updated — Model identifier cleaned up for platform-agnostic use.

Key V7 Changes

• Brainstorming Protocol (<brainstorming_protocol>): Multi-agent brainstorming with six specialized personas (system_architect, security_engineer, product_manager, business_strategist, legal_advisor, critical_thinker) for cross-disciplinary ambiguity resolution.
• Universal Datetime Rules (<universal_datetime_rules>): UTC-at-rest, ISO-8601/Unix-epoch at API boundaries, SOLID Clock injection, dual-representation for future calendar events, and timezone-independent CI/CD testing.
• SOLID Programming Mandate (<solid_programming_mandate>): Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion enforced on every generated implementation task, with pragmatic guardrails (No Zero-Abstraction Dogma, 3-Implementation Rule, YAGNI, Occam's Razor).
• Leadership & Language Protocol (<leadership_and_language_protocol>): Executive coaching persona that provides vocabulary assistance, English pronunciation guides (Persian phonetics), and ruthless soft-skills feedback during sprint retrospectives.
• Expanded Agent Skills Registry: 28 skills including stack-specific blueprints (android-kotlin, spring-boot, react-vite, nestjs-prisma-vertical, go-hexagonal-grpc, python-fastapi, nextjs, flask-python, react-native-expo, ios-swiftui, vue-nuxt, go-gin) and global workflow skills (brainstorm-swarm, design-md, project-memory, telegram-issue-sync, perplexity-research, verification-before-completion, debug-instrumentation).

Key V6 Changes

• Kanban lifecycle architecture — flat tasks/ directory replaced by state-based folders: tasks/backlog/, tasks/in-progress/, tasks/qa/, tasks/completed/, tasks/archive/.
• commit_and_clean_task MCP tool — new tool on the custom context server that commits staged changes, strips the raw git diff from the task file, and replaces it with a commit hash reference, keeping task files lean.
• migrate-kanban skill — automated migration of existing flat tasks/ files into the Kanban structure by reading status metadata.
• archive-tasks skill — milestone compaction: scans tasks/completed/, generates dense docs/history/milestone-X-summary.md, and moves files to tasks/archive/.
• System prompt upgraded to V6.0.0 — all personas and workflows updated for the Kanban lifecycle. Project Planner manages state-based Kanban directories. Code Reviewer now generates tasks that move files through the pipeline. Execution workflow includes backlog → in-progress → qa → completed transitions.

Key V6.7 Changes

• Manager Profile & Coaching Protocol — Added a dedicated <manager_profile> to the system prompt, giving the AI deep context about the Manager's technical background, work style, and career trajectory.
• Leadership & Language Feedback — Introduced the <leadership_and_language_protocol>. The AI now acts as an Executive Coach, teaching forgotten industry keywords, correcting English grammar/pronunciation (using Persian phonetic text), and providing ruthless soft-skills feedback during sprint retrospectives to prepare the Manager for leading real human teams.

---

Contributing

See .opencode/skills/sop-maintenance/SKILL.md for the rules that AI agents must follow when modifying this repository.

Future Architectural Roadmap

1. Automated Pull Request Integration: Upgrade the final Code Reviewer step to automatically branch, commit, and open a PR via GitHub CLI (gh pr create) instead of committing locally to main.
2. Epic and Milestone Tracking: Create an epics/ directory and update the task-generator skill to link individual tasks to parent epics for better macro-level project tracking.
3. Dedicated testing-strategy Skill: Create a template enforcing Test-Driven Development (TDD) or strict coverage thresholds, ensuring OpenCode writes tests before or alongside implementation code.
4. Database Migration Management: Create a database-migration skill to strictly forbid direct schema alterations, forcing the use of standard migration tools (Prisma, Alembic, Flyway) for safe, repeatable deployments.
5. Hexagonal Architecture Expansion: Port the strict Ports & Adapters blueprint from Go to our Python (FastAPI) and TypeScript (Node.js) templates to unify "Max Power" backend design patterns across all supported stacks.