apt-mcp-agent-setup 1.0.0 → 1.1.1

package/src/templates/CLAUDE.md

@@ -16,9 +16,9 @@ Default label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-h
 
 Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
 
-### FE Web design
+### FE Web design (taste-skill)
 
-Anti-slop frontend design rules for landing pages, portfolios, and redesigns.
+Anti-slop frontend design skill for landing pages, portfolios, and redesigns.
 
 - `ui-style-rules` — anti-slop design rules, typography, color calibration, layout discipline for code generation.
 - `web-mockup-gen` — web design image/mockup generation (image-only, no code).
@@ -42,3 +42,67 @@ Tool selection rules, index policies, memory conventions, and auto-skill activat
 - Code search: `code_search` (default), `grep_search` (non-code only)
 - Impact: `impact_analysis` (always update index first)
 - Memory: `remember` / `recall` / `read_knowledge` (see conventions in mcp-tools.md)
+
+---
+
+## Session Start Protocol (MANDATORY)
+
+At the start of every session:
+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.
+
+---
+
+## Auto-Trigger Skills (MANDATORY)
+
+### Workflow Skills — auto-trigger based on request type:
+
+| Skill | Trigger Conditions | Agent Action |
+|---|---|---|
+| `spec-clarification` | Design decision, architecture choice, plan review, "should we X or Y?" | Load SKILL.md → Start alignment session |
+| `bug-diagnostics` | Bug report, error log, "fails", "crashes", "/debug" | Load SKILL.md → Reproduce → minimise → hypothesise → fix |
+| `task-breakdown` | Plan/PRD just completed, "break down", "create tickets" | Load SKILL.md → Convert plan to vertical-slice issues |
+| `prd-gen` | New feature/product description with enough context for spec | Load SKILL.md → Extract PRD from conversation context |
+| `prototype` | "mockup", "explore options", unclear UI/logic | Load SKILL.md → Pick branch (logic vs UI) → Build throwaway prototype |
+| `tdd-loop` | Feature implementation, bug fix, "write tests", "red-green" | Load SKILL.md → Apply RED-GREEN-REFACTOR loop |
+
+### UI/UX Design Skills — auto-trigger when touching UI/design:
+
+| Skill | Trigger Conditions | Agent Action |
+|---|---|---|
+| `ui-style-rules` | Any web UI task: page layout, component styling, redesign | Load SKILL.md → Apply anti-slop design rules |
+| `web-mockup-gen` | "mockup web", "design page", web UI concept needed before coding | Load SKILL.md → Generate web design reference images (no code) |
+| `mobile-mockup-gen` | "mockup app", "design screen", mobile UI concept needed before coding | Load SKILL.md → Generate mobile screen mockups in phone frames |
+| `mobile-rules` | Any mobile UI implementation: Flutter widget, screen, touch interaction | Load SKILL.md → Apply platform conventions, touch patterns |
+| `flutter-*` | Flutter-specific tasks: layout fix, routing, serialization, testing | Auto-select matching flutter skill based on task type |
+
+**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/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/design-config.md

@@ -0,0 +1,52 @@
+# Design Tools Configuration
+
+How the design-to-code skills connect to external design tools.
+
+## Figma (if configured)
+
+| Setting | Value |
+|---|---|
+| **MCP Server** | `GLips/Figma-Context-MCP` |
+| **Auth** | `FIGMA_ACCESS_TOKEN` env var (Personal Access Token, free) |
+| **Mode** | Read-only — extracts layout, styles, assets |
+| **Get token** | https://www.figma.com/developers/api#access-tokens |
+
+### Usage
+
+Paste a Figma file or frame URL in chat:
+```
+https://figma.com/file/{fileKey}/{fileName}
+https://figma.com/file/{fileKey}?node-id={nodeId}
+```
+
+Agent auto-detects → extracts design → generates code.
+
+## Stitch (if configured)
+
+| Setting | Value |
+|---|---|
+| **MCP Server** | `@_davideast/stitch-mcp` |
+| **Auth** | Google account (browser login) |
+| **Mode** | Collaborative — agent creates → user tweaks → agent pulls code |
+| **Cost** | Free (Google Labs Beta) |
+| **Enable** | `STITCH_ENABLED=true` env var |
+
+### Usage
+
+Ask agent to design a screen:
+```
+"Design login page cho banking app"
+"Tạo giao diện dashboard từ specs này"
+```
+
+Agent creates on Stitch → shares link → user tweaks → says "pull code".
+
+## Environment Variables
+
+```bash
+# Figma (free)
+export FIGMA_ACCESS_TOKEN=figd_xxxxx
+
+# Stitch (free beta)
+export STITCH_ENABLED=true
+```

package/src/templates/jira-config.md

@@ -0,0 +1,52 @@
+# Jira Configuration
+
+PM preset connects to Jira for project management. This file defines connection details and conventions.
+
+## Primary Jira (Bank/Client)
+
+- **URL:** ${JIRA_PRIMARY_URL}
+- **Auth Method:** API Token (Cloud) / PAT (Server/Data Center)
+- **Default Project:** ${JIRA_PRIMARY_PROJECT}
+- **Type:** Cloud / Server / Data Center
+
+## Secondary Jira (Internal) — Optional
+
+- **URL:** ${JIRA_SECONDARY_URL}
+- **Auth Method:** PAT
+- **Default Project:** ${JIRA_SECONDARY_PROJECT}
+
+## Credentials Storage
+
+Credentials are stored as environment variables, **NOT** in this file:
+
+| Variable | Description |
+|---|---|
+| `JIRA_PRIMARY_URL` | Primary Jira base URL |
+| `JIRA_PRIMARY_USERNAME` | Email (Cloud) or username (Server) |
+| `JIRA_PRIMARY_TOKEN` | API Token (Cloud) or PAT (Server) |
+| `JIRA_SECONDARY_URL` | Secondary Jira base URL (optional) |
+| `JIRA_SECONDARY_USERNAME` | Secondary Jira username (optional) |
+| `JIRA_SECONDARY_TOKEN` | Secondary Jira token (optional) |
+
+## When a skill says "query Jira"
+
+Use the `pm-search-tasks` tool with JQL syntax. Example:
+```
+pm-search-tasks jql="status != Done AND dueDate < now() ORDER BY dueDate ASC"
+```
+
+## When a skill says "create task on Jira"
+
+Use the `pm-create-task` tool. **Always confirm with user before executing write operations.**
+
+## When a skill says "update Jira"
+
+Use the `pm-update-task` or `pm-change-status` tool. Show the change summary and ask for confirmation.
+
+## Switching between Jira instances
+
+If two Jira instances are configured, specify which one when querying:
+- Primary (default): bank/client Jira
+- Secondary: internal company Jira
+
+The agent defaults to the primary Jira unless the user explicitly asks for the internal one.

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`