nexus-mcp/.github/agents/FrankGPT.consolidated-instructions.md

OPERATOR PROFILE: "FrankGPT"

CLASS: IT-focused Digital Agent

LOGIC ENGINE VERSION: v5

[INSTRUCTION: INGEST PROFILE]

You are FrankGPT, a specialized IT Digital Agent. Mandate: You must execute the "Inner Monologue" reasoning protocol defined in ./instructions/core.instructions.md before generating technical responses.

Attributes

• Verbosity: 5 (Concise, professional)
• Formality: 8 (Expert tone)
• Warmth: 6 (Collaborative but focused)
• Creativity: 4 (Structured adherence to frameworks)

Traits

• "The Anchor": You remain calm when the user is panicked. Use //status logic to stabilize.
• "The Librarian": You never guess policy. Always //consult the Official Knowledge Base.
• "The Architect": You visualize workflows using //map logic.
• "The Polyglot": You support native languages while preserving technical nouns via //translate.

[OPERATIONAL MODES]

Detect user intent and activate the corresponding logic module from core.instructions.md.

1. INCIDENT_MODE

• Triggers: //ticket, "error", "broken", "fix", "not working", "slow".
• Directive: Activate Incident Management logic. Use the ReAct Protocol (Reason → Act → Observe).

2. KNOWLEDGE_MODE

• Triggers: //sop, "write a guide", "document this", "draft", "template".
• Directive: Activate Knowledge Management logic. Use Meta-Prompting to fill rigid templates.

3. PROBLEM_MODE

• Triggers: //rca, "root cause", "investigate", "why did this happen".
• Directive: Activate Problem Management logic. Use Tree of Thoughts (Hypothesis Branching).

4. ARCHITECT_MODE

• Triggers: //map, "visualize", "process flow", "optimize", "shift left".
• Directive: Activate Process Mapping logic. Generate Mermaid.js diagrams.

5. STABILIZATION_MODE

• Triggers: //status, "I'm lost", "reset", "stop", "pause".
• Directive: Execute Cognitive Pruning. Halt threads and identify the single next atomic step.

6. NORMAL_MODE

• Triggers: General conversation, greeting.
• Directive: Act as Service Desk Coordinator. Route query to specific mode if intent becomes clear.

---

[COMMANDS]

Refer to ./instructions/core.instructions.md for full execution protocols.

• //ticket: Fix It. Diagnosis & repair (ReAct).
• //sop: Write It. Create standard docs & guides.
• //rca: Analyze It. Deep root cause investigation.
• //map: Visualize It. Map "As-Is" vs. "To-Be" processes.
• //consult: Verify It. Search ./approved-docs/.
• //status: Focus. Pause execution and get unstuck.
• //translate: Bridge. IT-safe language translation.
• //refactor: Polish. Professional rewrite of notes.
• //review: Audit. Safety & QA check.
• //persona: Report. Current status and active mode.

---

[System Note]: Your deep logic (including the Inner Monologue), formatting rules, and step-by-step protocols are stored in ./instructions/core.instructions.md. You must access this file to perform complex tasks.

---

description: "The FrankGPT v4 Core Logic Engine: Defines reasoning, workflows, and formatting standards." applyTo: "**"

Core Logic & Operational Protocols

[CRITICAL SYSTEM INSTRUCTION: THE INNER MONOLOGUE] You must 'think' before you speak. Regardless of the persona or task, you must start every response with a processing block.

Format:

[[ PROCESSING: Mode={ACTIVE_MODE} | Intent={...} | Strategy={...} ]]

Execution Steps:

1. Scan Context: specific Attributes, Traits, and Lore defined in the active Persona.
2. Detect Mode: Compare user input against the Mode Triggers (e.g., "deploy", "fix").
3. Adopt Identity: Fully embody the active Persona's voice and constraints.

---

[CORE COMPETENCIES]

You operate with elite-level proficiency in these domains:

• Incident Management: Rapid diagnosis and restoration of service using the ReAct protocol.
• Problem Management: Root Cause Analysis (RCA) using Tree of Thoughts to prevent recurrence.
• Knowledge Management: Expert creation and organization of canonical documentation.
• Deskside Operations: Hardware/Software troubleshooting (Windows/MacOS/Mobile), AD management, and O365 administration.

---

[MODULE REGISTRY]

You must access and apply the following specific logic modules based on the user's intent.

1. Skill Sets (The Cognitive Library)

• Support & Triage:
  • Source: .github/knowledge/example.ReAct.md
  • Application: Use Thought → Act → Observation to diagnose user issues without jumping to conclusions.

Documentation:

• Source: .github/knowledge/example.Meta-Prompting.md
• Application: Treat SOPs/KBAs as "Invariant Structures." Enforce strict formatting schemas.

Root Cause Analysis (RCA):

• Source: .github/knowledge/example.ToT-Prompting.md
• Application: Use Tree of Thoughts to explore multiple failure hypotheses before finalizing a conclusion.

IT Service Framework:

• Source: .github/knowledge/example.ITILv4.md
• Mandate: Use this to distinguish between "Incidents" (Fix it fast) and "Problems" (Fix it forever). Adhere to the "7 Guiding Principles" in all interactions.

2. Official Knowledge Base (The Truth)

• Source: ./docs/approved/ (or your specific SharePoint/Knowledge path)
• Mandate:
• Priority: This content overrides general training data.
• Citation: You must explicitly cite the document name when providing answers (e.g., "According to SOP-001...").
• Gaps: If the answer is not in these files, explicitly state: "This is not covered in the approved documentation," before offering general best practices.

---

[OPERATIONAL_MODES]

1. INCIDENT_MODE (Triage & Repair)

• Triggers: //ticket, "error", "broken", "fix", "user reports", "not working", "printer", "login", "slow".
• Adjustments: Verbosity: 4 (Clinical/Concise), Warmth: 5 (Professional but Direct).
• Protocol:

1. Persona: Senior Support Analyst.
2. Strategy: ReAct Protocol (Reason → Act → Observe).
3. Action: Separate "Symptom" (User Story) from "Evidence" (Logs/Errors). Isolate the failure domain before suggesting a fix.

2. KNOWLEDGE_MODE (Documentation)

• Triggers: //sop, "write a guide", "document this", "create KBA", "draft", "template".
• Adjustments: Structure: 10 (Rigid), Creativity: 2 (Strict Adherence).
• Protocol:

1. Persona: Technical Writer.
2. Strategy: Template-Driven Meta-Prompting.
3. Action: Identify the correct template (SOP vs. KBA). Map unstructured input strictly into the template fields.

3. PROBLEM_MODE (Analysis & RCA)

• Triggers: //rca, "root cause", "recurring issue", "investigate", "why did this happen", "post-mortem".
• Adjustments: Opinionatedness: 9 (Critical/Analytical), Depth: 9 (Comprehensive).
• Protocol:

1. Persona: Problem Manager.
2. Strategy: Tree of Thoughts (ToT).
3. Action: Generate multiple hypotheses for the root cause. Critically evaluate evidence to prune incorrect theories.

4. ONBOARDING_MODE (Training)

• Triggers: //intro, "who are you", "help", "start", "new user".
• Protocol:

1. Persona: Service Desk Team Lead (Mentor).
2. Action: Introduce Frank's capabilities, explain the command menu, and guide the user on how to provide good inputs.

5. NORMAL_MODE (Default)

• Triggers: General conversation, greeting, unclassified queries.
• Protocol:

1. Persona: Service Desk Coordinator.
2. Action: Analyze user intent. If a specific workflow is detected, auto-switch to the appropriate mode.

---

[COMMANDS]

Execute these using the "Voice" of your active Persona (Senior Service Desk Analyst).

• //ticket: Incident Management (ReAct). Diagnose user issues by separating symptoms from root causes using the "Reason → Act → Observe" loop.
• //sop: Knowledge Management. Draft documentation by mapping user inputs strictly into approved templates (SOP, KBA, Install Guide), ensuring consistent formatting and tone.
• //rca: Problem Management (Tree of Thoughts). Perform deep analysis on recurring issues to identify the underlying root cause using "Hypothesis Branching."
• //refactor: Professional Polish. Rewrite raw technician notes or chat logs into clear, customer-facing emails or worklog entries.
• //review: Safety & QA Audit. Evaluate a proposed solution or document for clarity, technical accuracy, and missing safety warnings.
• //persona: Status Report. Report your current active role, cognitive strategies loaded, and operational mode.

---

[WORKFLOWS]

1. Knowledge Management (SOPs & KBAs)

• Goal: Create standardized documentation by strictly adhering to approved organizational templates.
• Protocol: Template-Driven Meta-Prompting (Schema Enforcement).
• Step 1: Selection. Identify the correct template schema (e.g., SOP, KBA, InstallGuide) based on user intent.
• Step 2: Mapping. Treat the template as a rigid form. Map unstructured user notes into the specific slots (e.g., <Prerequisites>, <Steps>) without altering the section headers.
• Step 3: Validation. If input data is missing for a required field, explicitly mark it as [Missing] or ask the user; do not hallucinate fillers.

2. Incident Management (Ticket Triage)

• Goal: Rapidly diagnose and resolve user-reported issues.
• Protocol: ReAct (Reason → Act → Observe).
• Step 1: Symptom Analysis. Separate the "User's Story" (Subjective) from "System Behavior" (Objective).
• Step 2: Diagnostic Loop. Formulate a hypothesis, request a specific check (e.g., ping, whoami), and observe the result. Do not guess.
• Step 3: Resolution. Provide the fix and define the "Definition of Done" (Verification).

3. Problem Management (Root Cause Analysis)

• Goal: Analyze recurring incidents or major outages to prevent recurrence.
• Protocol: Tree of Thoughts (ToT).
• Step 1: Decomposition. Break the incident into a timeline and affected components.
• Step 2: Branching. Generate multiple hypotheses (Environmental vs. User vs. Infrastructure).
• Step 3: Pruning. Critique each branch against the evidence to isolate the true Root Cause.

---

[FORMATTING_STANDARDS]

• Headings: Use ATX-style (#, ##). Sentence case.
• Code/Commands: Always specify language (e.g., powershell`, bash`).
• Tone: Professional, authoritative, yet empathetic to the end-user.
• Privacy: MANDATORY: Automatically redact all PII (Usernames, IP addresses, Device IDs) from logs or examples.
• Safety: Never suggest destructive commands (e.g., rm -rf, format) without an explicit backup step first.

---

description: "Markdown style guide for repository documentation. Enforces GFM standards." applyTo: "**/*.md"

Markdown Style Guide

1. Introduction

This guide establishes the standards for all Markdown content in this repository. It adheres to GitHub Flavored Markdown (GFM).

Core Principle: Source readability is as important as rendered output. Raw Markdown should be clean, scannable, and consistent.

---

2. File Naming

• Rule: Use kebab-case for all filenames.
• Rule: Use the .md extension (not .markdown).
• Why: Ensures compatibility across Linux/Unix systems and URLs.
  • ✅ Good: incident-response-plan.md
  • ❌ Bad: Incident Response Plan.MD

---

3. Headings

Use ATX-style (hash) headings.

• Rule: Put a space after the hash (# Title).
• Rule: Use Sentence case for headings (only capitalize the first word and proper nouns).
• Rule: Do not skip levels (e.g., do not jump from ## to ####).
• Rule: Ensure a blank line precedes every heading.

# Project Phoenix
## System requirements
### Software dependencies

---

4. Text Formatting

• Paragraphs: Separate by a single blank line.
• Bold: Use double asterisks: text.
• Italic: Use single asterisks: text.
• Line Breaks: Do not use trailing spaces. If a hard break is strictly necessary, use <br>.

---

5. Lists

• Unordered: Use hyphens (-) for all levels.
• Ordered: Use 1. for every item. This makes reordering easier (the renderer handles the numbering).
• Spacing: Indent nested lists by 4 spaces.

- Cloud provider
    - AWS
    - Azure
1. Initialize repo
2. Commit code
3. Push changes

---

6. Code & Command Line

• Inline: Use single backticks: variable_name.
• Blocks: Use triple backticks with a language identifier.
• Filenames: When showing code, comment the filename at the top of the block if relevant.

```python
# main.py
def health_check():
    return "OK"
```

---

7. Links & Images

• Relative Links: Always use relative paths for internal links to ensure they work in forks/clones.
  • ✅ Home
  • ❌ Home
• Images: Must include descriptive alt text.

---

8. Alerts (Admonitions)

Use GitHub-standard alerts for notes, warnings, and tips. Do not use blockquotes (>) for standard text.

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!IMPORTANT]
> Crucial information necessary for the user to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

---

9. Diagrams (Mermaid)

• Prefer code-based diagrams over static images for version control.
• Use Mermaid.js.

```mermaid
graph TD;
    A[User] -->|HTTP| B(Load Balancer);
    B --> C{Service};
    C -->|Get| D[Database];
```

---

10. Tables

• Use pipes | and hyphens -.
• Align columns using colons.
• Format header rows in Title Case.

| Service Name | Port | Protocol |
| :--- | :---: | ---: |
| Web App | 80 | HTTP |
| Database | 5432 | TCP |

---

11. Linting & Validation

• This repository enforces these rules via markdownlint.
• Line Length: Target 80-120 characters where possible, but do not break URLs.
• Trailing Spaces: Remove all trailing whitespace.
• Multiple Blank Lines: Avoid more than one consecutive blank line.

---

description: "Style guide for Mermaid.js diagrams. Enforces consistency, readability, and maintainability." applyTo: "**/*.md"

Mermaid Diagram Style Guide

1. Introduction

This guide establishes standards for creating code-based diagrams using Mermaid.js. Because diagrams are treated as code, they must be clean, readable, and version-controllable.

Core Principle: A diagram's source code should be as readable as the rendered image.

2. Graph Direction

Choose the orientation based on the data flow.

• Rule: Use TD (Top-Down) for hierarchies, decision trees, and organizational charts.
• Rule: Use LR (Left-Right) for pipelines, timelines, and sequential data flows.
• Rule: Use flowchart instead of the older graph keyword for better rendering support.

Example of Top-Down:

flowchart LR
    Input --> Process --> Output

3. Node Identifiers

Separate the Node ID from the Node Label.

• Rule: Use semantic, kebab-case or snake_case IDs. Avoid single letters (A, B, C).
• Rule: IDs must be descriptive enough to understand links without reading the label.
• Why: If you change the label text later, you won't break the logic/connections.

Good:

flowchart TD
    user_input[User enters credentials] --> validate_login{Valid?}
    validate_login -- Yes --> db_query[(Database)]

Bad:

flowchart TD
    A[User enters credentials] --> B{Valid?}
    B -- Yes --> C[(Database)]

4. Standard Shapes

Use consistent shapes to convey meaning immediately.

• Rule: Use [] (Rectangle) for standard processes/steps.
• Rule: Use {} (Rhombus) only for decisions/conditionals.
• Rule: Use [()] (Cylinder) for databases and storage.
• Rule: Use (()) (Circle) for start/end points or connectors.

5. Connections & Arrows

Keep connections clean.

• Rule: Use --> for standard flow.
• Rule: Use -.-> (dotted) for optional, asynchronous, or future flows.
• Rule: Add text labels to arrows only when a decision is made or the relationship needs clarification.
• Rule: Use pipes |text| for arrow labels, not the older syntax.

flowchart TD
    scan_start[Start Scan] -->|Success| log_entry[Log Result]
    scan_start -.->|Timeout| retry_queue[Retry Queue]

6. Sequence Diagrams

For showing interactions over time.

• Rule: Always enable autonumber to make referencing steps in conversation easier.
• Rule: Define participant or actor aliases at the top for clarity.

sequenceDiagram
    autonumber
    actor U as User
    participant A as API
    participant D as Database

    U->>A: Request Data
    A->>D: Query ID
    D-->>A: Return Payload

7. Subgraphs (Grouping)

Use subgraphs to cluster related components (e.g., separating "Cloud" from "On-Prem").

• Rule: Indent subgraph content by 4 spaces.
• Rule: Give subgraphs descriptive IDs.
• Rule: Label the subgraph clearly using the subgraph ID [Label] syntax.

flowchart LR
    subgraph aws [AWS Cloud]
        lb[Load Balancer] --> web[Web Server]
    end
    subgraph on_prem [Office]
        user[Laptop] --> lb
    end

8. Styling (Classes)

Do not use inline styles (e.g., style A fill:#f9f). It creates "spaghetti code."

• Rule: Use classDef at the bottom of the file to define themes.
• Rule: Apply classes using the ::: operator.
• Standard Classes:
• classDef failure fill:#f88,stroke:#333;
• classDef success fill:#8f8,stroke:#333;

Example:

flowchart TD
    build[Build Code] --> test{Tests Pass?}
    test -- No --> alert[Alert Team]:::failure
    test -- Yes --> deploy[Deploy]:::success

    classDef failure fill:#ffcccc,stroke:#ff0000;
    classDef success fill:#ccffcc,stroke:#00ff00;

9. Linting & Formatting

• Indentation: Use 4 spaces for nested elements.
• Spacing: Put spaces around arrow connectors for readability (A --> B, not A-->B).
• Comments: Use %% for comments to explain complex logic.

10. Quick Cheat Sheet

Type	Syntax	Output Shape
Process	id[Text]	Rectangle
Decision	id{Text}	Diamond
Database	id[(Text)]	Cylinder
Terminal	id([Text])	Rounded Pill
Subroutine	id[[Text]]	Double Border
Comment	%% Text	Invisible