apt-mcp-agent-setup 1.0.0 → 1.1.0

package/src/templates/copilot-instructions.md

@@ -0,0 +1,98 @@
+# AG Kit — Copilot Custom Instructions
+
+> This file defines how GitHub Copilot behaves in this workspace.
+
+## Agent skills
+
+### Support & issues
+
+For bug reports, feature requests, or licensing questions, contact: `info.alphatechs.ai@gmail.com`
+
+### Issue tracker
+
+Issues are tracked in GitLab Issues. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
+---
+
+## Session Start Protocol (MANDATORY)
+
+1. Read `.agents/ARCHITECTURE.md` to understand Agents, Skills, and Scripts.
+2. Read `.agents/memory/MEMORY.md` to load persistent project conventions.
+3. Read `docs/agents/mcp-tools.md` to load MCP tool selection rules & memory conventions.
+4. Call `read_knowledge` to load dynamic knowledge graph from memory.
+
+---
+
+## MCP Tool Selection
+
+| Situation | Use Tool | NOT | Why |
+|---|---|---|---|
+| Find symbol definition, function, class | `code_search` | `grep_search` | Semantic search, understands code structure |
+| Find all callers of a function | `find_callers` | `grep_search` | Follows call graph, not just text match |
+| Find all functions called by a function | `find_callees` | — | Call graph traversal |
+| Explore file structure & dependencies | `explore_code` | `list_dir` | Understands imports, exports, relationships |
+| Search in config/docs (YAML, JSON, .env, markdown) | `grep_search` | `code_search` | Non-code files, literal string match |
+| "What breaks if I change this?" | `impact_analysis` | — | Blast radius — always update index first |
+| Save a decision/bug-fix/convention | `remember` | — | Cross-session persistence |
+| Recall what was decided about X | `recall` | — | Search by keyword |
+| Load full knowledge graph | `read_knowledge` | — | Session start, get full context |
+
+**Rule: DEFAULT to `code_search` for code. Fall back to `grep_search` ONLY for non-code files or literal strings.**
+
+---
+
+## Auto-Trigger Skills (MANDATORY)
+
+### Workflow Skills
+
+| Skill | Trigger Conditions | Agent Action |
+|---|---|---|
+| `spec-clarification` | Design decision, architecture choice, plan review | Load SKILL.md → Start alignment session |
+| `bug-diagnostics` | Bug report, error log, "fails", "crashes" | Load SKILL.md → Reproduce → minimise → hypothesise → fix |
+| `task-breakdown` | Plan/PRD completed, "break down", "create tickets" | Load SKILL.md → Convert plan to vertical-slice issues |
+| `prd-gen` | New feature/product description with enough context | Load SKILL.md → Extract PRD from conversation context |
+| `prototype` | "mockup", "explore options", unclear UI/logic | Load SKILL.md → Build throwaway prototype |
+| `tdd-loop` | Feature implementation, bug fix, "write tests" | Load SKILL.md → Apply RED-GREEN-REFACTOR loop |
+
+### UI/UX Design Skills
+
+| Skill | Trigger Conditions | Agent Action |
+|---|---|---|
+| `ui-style-rules` | Any web UI task: page layout, component styling | Load SKILL.md → Apply anti-slop design rules |
+| `web-mockup-gen` | Web UI concept needed before coding | Load SKILL.md → Generate web design reference images |
+| `mobile-mockup-gen` | Mobile UI concept needed before coding | Load SKILL.md → Generate mobile screen mockups |
+| `mobile-rules` | Any mobile UI implementation: Flutter, touch interaction | Load SKILL.md → Apply platform conventions |
+| `flutter-*` | Flutter-specific tasks: layout, routing, testing | Auto-select matching flutter skill |
+
+---
+
+## Socratic Gate
+
+Every user request must pass through the Socratic Gate before ANY implementation:
+
+| Request Type | Strategy | Required Action |
+|---|---|---|
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions |
+| **Code Edit / Bug Fix** | Context Check | Confirm understanding + ask impact questions |
+| **Vague / Simple** | Clarification | Ask Purpose, Users, and Scope |
+
+---
+
+## Universal Rules
+
+### Clean Code (Global Mandatory)
+- **Code**: Concise, direct, no over-engineering. Self-documenting.
+- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
+- **Performance**: Measure first. Adhere to current Core Web Vitals standards.
+
+### Quick Reference
+- **Masters**: `orchestrator`, `project-planner`, `security-auditor`, `backend-specialist`, `frontend-specialist`, `mobile-developer`, `debugger`
+- **Key Skills**: `clean-code`, `brainstorming`, `ui-style-rules`, `mobile-rules`, `web-mockup-gen`, `mobile-mockup-gen`, `bug-diagnostics`, `tdd-loop`, `spec-clarification`, `prd-gen`, `task-breakdown`, `prototype`

package/src/templates/cursorrules.mdc

@@ -0,0 +1,108 @@
+---
+description: AG Kit agent behavioral rules — tool selection, auto-trigger skills, session protocol
+globs: **/*
+alwaysApply: true
+---
+
+# AG Kit — Agent Rules
+
+> This file defines how the AI behaves in this workspace.
+
+## Agent skills
+
+### Support & issues
+
+For bug reports, feature requests, or licensing questions, contact: `info.alphatechs.ai@gmail.com`
+
+### Issue tracker
+
+Issues are tracked in GitLab Issues. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
+---
+
+## 🗺️ Session Start Protocol (MANDATORY)
+
+1. Read `.agents/ARCHITECTURE.md` to understand Agents, Skills, and Scripts.
+2. Read `.agents/memory/MEMORY.md` to load persistent project conventions.
+3. Read `docs/agents/mcp-tools.md` to load MCP tool selection rules & memory conventions.
+4. Call `read_knowledge` to load dynamic knowledge graph from memory.
+
+---
+
+## 🔍 MCP Tool Selection
+
+| Situation | Use Tool | NOT | Why |
+|---|---|---|---|
+| Find symbol definition, function, class | `code_search` | `grep_search` | Semantic search, understands code structure |
+| Find all callers of a function | `find_callers` | `grep_search` | Follows call graph, not just text match |
+| Find all functions called by a function | `find_callees` | — | Call graph traversal |
+| Explore file structure & dependencies | `explore_code` | `list_dir` | Understands imports, exports, relationships |
+| Search in config/docs (YAML, JSON, .env, markdown) | `grep_search` | `code_search` | Non-code files, literal string match |
+| "What breaks if I change this?" | `impact_analysis` | — | Blast radius — always update index first |
+| Save a decision/bug-fix/convention | `remember` | — | Cross-session persistence |
+| Recall what was decided about X | `recall` | — | Search by keyword |
+| Load full knowledge graph | `read_knowledge` | — | Session start, get full context |
+
+**Rule: DEFAULT to `code_search` for code. Fall back to `grep_search` ONLY for non-code files or literal strings.**
+
+---
+
+## 🎯 Auto-Trigger Skills (MANDATORY)
+
+### Workflow Skills
+
+| Skill | Trigger Conditions | Agent Action |
+|---|---|---|
+| `spec-clarification` | Design decision, architecture choice, plan review | Load SKILL.md → Start alignment session |
+| `bug-diagnostics` | Bug report, error log, "fails", "crashes" | Load SKILL.md → Reproduce → minimise → hypothesise → fix |
+| `task-breakdown` | Plan/PRD completed, "break down", "create tickets" | Load SKILL.md → Convert plan to vertical-slice issues |
+| `prd-gen` | New feature/product description with enough context | Load SKILL.md → Extract PRD from conversation context |
+| `prototype` | "mockup", "explore options", unclear UI/logic | Load SKILL.md → Build throwaway prototype |
+| `tdd-loop` | Feature implementation, bug fix, "write tests" | Load SKILL.md → Apply RED-GREEN-REFACTOR loop |
+
+### UI/UX Design Skills
+
+| Skill | Trigger Conditions | Agent Action |
+|---|---|---|
+| `ui-style-rules` | Any web UI task: page layout, component styling | Load SKILL.md → Apply anti-slop design rules |
+| `web-mockup-gen` | Web UI concept needed before coding | Load SKILL.md → Generate web design reference images |
+| `mobile-mockup-gen` | Mobile UI concept needed before coding | Load SKILL.md → Generate mobile screen mockups |
+| `mobile-rules` | Any mobile UI implementation: Flutter, touch interaction | Load SKILL.md → Apply platform conventions |
+| `flutter-*` | Flutter-specific tasks: layout, routing, testing | Auto-select matching flutter skill |
+
+### Failure Conditions
+- ❌ Writing UI code without loading design skill = **SLOP RISK**
+- ❌ Creating mobile screen without `mobile-rules` = **PLATFORM VIOLATION**
+
+---
+
+## 🛑 Socratic Gate
+
+Every user request must pass through the Socratic Gate before ANY implementation:
+
+| Request Type | Strategy | Required Action |
+|---|---|---|
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions |
+| **Code Edit / Bug Fix** | Context Check | Confirm understanding + ask impact questions |
+| **Vague / Simple** | Clarification | Ask Purpose, Users, and Scope |
+
+---
+
+## Universal Rules
+
+### Clean Code (Global Mandatory)
+- **Code**: Concise, direct, no over-engineering. Self-documenting.
+- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
+- **Performance**: Measure first. Adhere to current Core Web Vitals standards.
+
+### Quick Reference
+- **Masters**: `orchestrator`, `project-planner`, `security-auditor`, `backend-specialist`, `frontend-specialist`, `mobile-developer`, `debugger`
+- **Key Skills**: `clean-code`, `brainstorming`, `ui-style-rules`, `mobile-rules`, `web-mockup-gen`, `mobile-mockup-gen`, `bug-diagnostics`, `tdd-loop`, `spec-clarification`, `prd-gen`, `task-breakdown`, `prototype`

package/src/templates/windsurfrules.md

@@ -0,0 +1,98 @@
+# AG Kit — Agent Rules
+
+> This file defines how the AI (Windsurf Cascade) behaves in this workspace.
+
+## Agent skills
+
+### Support & issues
+
+For bug reports, feature requests, or licensing questions, contact: `info.alphatechs.ai@gmail.com`
+
+### Issue tracker
+
+Issues are tracked in GitLab Issues. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
+---
+
+## Session Start Protocol (MANDATORY)
+
+1. Read `.agents/ARCHITECTURE.md` to understand Agents, Skills, and Scripts.
+2. Read `.agents/memory/MEMORY.md` to load persistent project conventions.
+3. Read `docs/agents/mcp-tools.md` to load MCP tool selection rules & memory conventions.
+4. Call `read_knowledge` to load dynamic knowledge graph from memory.
+
+---
+
+## MCP Tool Selection
+
+| Situation | Use Tool | NOT | Why |
+|---|---|---|---|
+| Find symbol definition, function, class | `code_search` | `grep_search` | Semantic search, understands code structure |
+| Find all callers of a function | `find_callers` | `grep_search` | Follows call graph, not just text match |
+| Find all functions called by a function | `find_callees` | — | Call graph traversal |
+| Explore file structure & dependencies | `explore_code` | `list_dir` | Understands imports, exports, relationships |
+| Search in config/docs (YAML, JSON, .env, markdown) | `grep_search` | `code_search` | Non-code files, literal string match |
+| "What breaks if I change this?" | `impact_analysis` | — | Blast radius — always update index first |
+| Save a decision/bug-fix/convention | `remember` | — | Cross-session persistence |
+| Recall what was decided about X | `recall` | — | Search by keyword |
+| Load full knowledge graph | `read_knowledge` | — | Session start, get full context |
+
+**Rule: DEFAULT to `code_search` for code. Fall back to `grep_search` ONLY for non-code files or literal strings.**
+
+---
+
+## Auto-Trigger Skills (MANDATORY)
+
+### Workflow Skills
+
+| Skill | Trigger Conditions | Agent Action |
+|---|---|---|
+| `spec-clarification` | Design decision, architecture choice, plan review | Load SKILL.md → Start alignment session |
+| `bug-diagnostics` | Bug report, error log, "fails", "crashes" | Load SKILL.md → Reproduce → minimise → hypothesise → fix |
+| `task-breakdown` | Plan/PRD completed, "break down", "create tickets" | Load SKILL.md → Convert plan to vertical-slice issues |
+| `prd-gen` | New feature/product description with enough context | Load SKILL.md → Extract PRD from conversation context |
+| `prototype` | "mockup", "explore options", unclear UI/logic | Load SKILL.md → Build throwaway prototype |
+| `tdd-loop` | Feature implementation, bug fix, "write tests" | Load SKILL.md → Apply RED-GREEN-REFACTOR loop |
+
+### UI/UX Design Skills
+
+| Skill | Trigger Conditions | Agent Action |
+|---|---|---|
+| `ui-style-rules` | Any web UI task: page layout, component styling | Load SKILL.md → Apply anti-slop design rules |
+| `web-mockup-gen` | Web UI concept needed before coding | Load SKILL.md → Generate web design reference images |
+| `mobile-mockup-gen` | Mobile UI concept needed before coding | Load SKILL.md → Generate mobile screen mockups |
+| `mobile-rules` | Any mobile UI implementation: Flutter, touch interaction | Load SKILL.md → Apply platform conventions |
+| `flutter-*` | Flutter-specific tasks: layout, routing, testing | Auto-select matching flutter skill |
+
+---
+
+## Socratic Gate
+
+Every user request must pass through the Socratic Gate before ANY implementation:
+
+| Request Type | Strategy | Required Action |
+|---|---|---|
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions |
+| **Code Edit / Bug Fix** | Context Check | Confirm understanding + ask impact questions |
+| **Vague / Simple** | Clarification | Ask Purpose, Users, and Scope |
+
+---
+
+## Universal Rules
+
+### Clean Code (Global Mandatory)
+- **Code**: Concise, direct, no over-engineering. Self-documenting.
+- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
+- **Performance**: Measure first. Adhere to current Core Web Vitals standards.
+
+### Quick Reference
+- **Masters**: `orchestrator`, `project-planner`, `security-auditor`, `backend-specialist`, `frontend-specialist`, `mobile-developer`, `debugger`
+- **Key Skills**: `clean-code`, `brainstorming`, `ui-style-rules`, `mobile-rules`, `web-mockup-gen`, `mobile-mockup-gen`, `bug-diagnostics`, `tdd-loop`, `spec-clarification`, `prd-gen`, `task-breakdown`, `prototype`