@jhm1909/ag-kit 0.1.0

package/.agent/workflows/implement-feature.md

@@ -0,0 +1,182 @@
+---
+description: Orchestrates feature implementation from specification to deployment.
+---
+
+# Feature Implementation Workflow
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                       | Example Query                       |
+| -------------------------------------------- | ------------------------------------------------- | ----------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | Complex decisions, debugging, architecture design | Break down feature into tasks       |
+| `mcp_context7_resolve-library-id`            | Find library ID before querying docs              | "react hook form"                   |
+| `mcp_context7_query-docs`                    | Research UI libraries (shadcn, radix, tailwind)   |
+| `search_web`                                 | Research design trends and UX patterns            | "modern SaaS dashboard trends 2026" |
+| `generate_image`                             | Create low-fi wireframes or conceptual assets     |
+
+---
+
+## Step 1: Deep Research
+
+// turbo
+
+> 💡 **MANDATORY**: Follow `.agent/rules/research.md` to ensure modern implementation.
+
+1. **Invoke `[research]`** to:
+   - Find the most efficient/modern patterns for the requested feature.
+   - Check for recent updates in libraries used (Next.js, Prisma, etc.).
+   - Identify potential scaling or security issues related to the implementation.
+2. Update/Create research documentation in `docs/050-Research/`.
+3. **WAIT** for user to review if new critical insights are found.
+
+---
+
+## Step 2: Specification (Choose Depth)
+
+**Skip if**: User Stories or specs already exist in `docs/`.
+
+> 💡 **MCP**: Use `sequential-thinking` to analyze requirements and assess complexity.
+
+**Assess the feature scope, then present options to the user:**
+
+```
+"Feature này cần plan ở mức nào?"
+  📝 Deep Plan — tạo Spec + Design + Story trong docs/ (feature lớn, nhiều component)
+  ⚡ Quick Spec — tóm tắt nhanh rồi code luôn (feature vừa/nhỏ)
+```
+
+### Option A: ⚡ Quick Spec
+
+1. **Invoke `[product-manager]` skill** to clarify requirements
+2. Create `feature-spec.md` artifact with: Goal, User, Acceptance Criteria
+3. **WAIT** for user confirmation
+
+### Option B: 📝 Deep Plan (Dewey Docs)
+
+> [!IMPORTANT]
+> All files MUST follow `documents.md` conventions: frontmatter, naming, wiki-links.
+
+1. **Invoke `[lead-architect]` + `[business-analysis]`** to create:
+   - `docs/030-Specs/Spec-{FeatureName}.md` — Why, Requirements (SHALL/MUST), Scope
+2. **Invoke `[lead-architect]` + `[research-first]`** to create:
+   - `docs/040-Design/Specs/Design-{FeatureName}.md` — Context, Goals/Non-Goals, Decisions, Risks
+3. **Invoke `[backend-developer]` + `[frontend-developer]`** to create:
+   - `docs/022-User-Stories/Backlog/Story-{FeatureName}.md` — User story, acceptance criteria, task checklist
+4. **WAIT** for user to review all 3 documents before proceeding
+
+---
+
+## Step 3: Locate Existing Artifacts
+
+// turbo
+
+> 💡 **MCP**: Use `context7` to research unfamiliar tech in existing codebase
+
+1. Search `docs/` for related: User Stories, SDD, Designs
+2. **Invoke `[lead-architect]` skill** to identify scope and dependencies
+3. List files to create/modify
+4. **WAIT** for user to confirm scope
+
+---
+
+## Step 4: Implementation Plan
+
+// turbo
+
+> 💡 **MCP**: **MUST** use `sequential-thinking` to break down complex features into atomic tasks
+
+1. **Invoke `[lead-architect]` skill** to create task breakdown
+2. Create `implementation-plan.md` artifact with phased tasks
+3. Save to `docs/050-Tasks/Task-{FeatureName}.md` after approval
+4. **WAIT** for user approval
+
+---
+
+## Step 5: Design Review (If UI Feature)
+
+// turbo
+
+**Skip if**: Feature is purely backend/API.
+
+> 💡 **MCP**: Use `context7` with `/radix-ui/*` or `/shadcn/*` for component patterns
+
+1. Check `docs/040-Design/` for existing designs
+2. **Invoke `[designer]` skill** for new component specifications
+3. **WAIT** for user confirmation
+
+---
+
+## Step 6: Backend Implementation
+
+// turbo
+
+> 💡 **MCP**:
+>
+> - Use `context7` with `/supabase/supabase`, `/prisma/prisma` for DB patterns
+> - Use `sequential-thinking` for complex business logic
+
+1. **Invoke `[backend-developer]` skill** for:
+   - Data models/migrations
+   - API endpoints/server functions
+   - Unit tests (TDD approach)
+2. Run tests and verify
+3. **WAIT** for user checkpoint
+
+---
+
+## Step 7: Frontend Implementation
+
+// turbo
+
+> 💡 **MCP**: Use `context7` with `/vercel/next.js`, `/tanstack/react-query`, `/react-hook-form/*` for patterns
+
+1. **Invoke `[frontend-developer]` skill** for:
+   - Components following design specs
+   - State management
+   - Component tests
+2. **WAIT** for user checkpoint
+
+---
+
+## Step 8: Integration & QA
+
+// turbo
+
+> 💡 **MCP**:
+>
+> - Use `context7` with `/vitest-dev/vitest`, `/playwright/*` for testing patterns
+> - Use `sequential-thinking` to analyze test failures
+
+1. **Invoke `[qa-tester]` skill** for:
+   - E2E test execution
+   - Acceptance criteria verification
+   - Edge case testing
+2. Create `qa-report.md` artifact
+3. **WAIT** for user to confirm ready
+
+---
+
+## Step 9: Finalize
+
+// turbo
+
+1. **Invoke `[lead-architect]` skill** to:
+   - Update MOC files
+   - Move task to `docs/050-Tasks/Completed/`
+   - Update API/changelog if applicable
+2. Present completion summary with next steps
+
+---
+
+## Quick Reference
+
+| Step | Skill              | Output                 |
+| ---- | ------------------ | ---------------------- |
+| 1    | research           | research-insights.md   |
+| 2    | product-manager    | feature-spec.md        |
+| 3-4  | lead-architect     | implementation-plan.md |
+| 5    | designer           | Component specs        |
+| 6    | backend-developer  | API, Models, Tests     |
+| 7    | frontend-developer | Components, Tests      |
+| 8    | qa-tester          | qa-report.md           |
+| 9    | lead-architect     | Updated docs           |

package/.agent/workflows/install-skill.md

@@ -0,0 +1,193 @@
+---
+description: Search, preview, and install external agent skills from GitHub repos or registries
+---
+
+# Install Skill — On-Demand Skill Installer
+
+> [!IMPORTANT]
+> Philosophy: **Search → Preview → Confirm → Install → Register**
+> Combines ALL search methods: Registry → GitHub → Web → context7
+
+---
+
+## Step 0: Parse Request
+
+Determine what user wants:
+
+```
+📦 Install a skill:
+1. By name:    /install-skill stripe
+2. By repo:    /install-skill github.com/stripe/ai
+3. By domain:  /install-skill "payment processing"
+```
+
+Extract: `<query>` (name, URL, or domain keyword)
+
+---
+
+## Step 1: Multi-Source Search
+
+// turbo
+
+Run **ALL search methods in parallel**, prioritized by reliability:
+
+### 1.1 Registry Lookup (fastest, most reliable)
+```
+Read .agent/known-registries.json
+→ Match <query> against entries
+→ If found: return { repo, skill_path, description }
+```
+
+### 1.2 GitHub MCP Search
+```
+mcp_github_search_code: "SKILL.md <query>" 
+mcp_github_search_repositories: "<query> agent-skills"
+→ Filter: must contain SKILL.md
+→ Sort by stars
+```
+
+### 1.3 Web Search
+```
+search_web: "<query> agent skill SKILL.md github 2025 2026"
+→ Extract GitHub URLs from results
+```
+
+### 1.4 context7 Docs (fallback — not a skill, but useful)
+```
+mcp_context7_resolve-library-id: "<query>"
+→ If found: offer as alternative to skill install
+→ "No skill found, but context7 has live docs for <query>"
+```
+
+---
+
+## Step 2: Present Results
+
+Merge and deduplicate results. Present top matches:
+
+```
+🔍 Found skills for "<query>":
+
+  ⭐ Registry Match:
+  1. stripe/stripe-best-practices — Best practices for Stripe integrations
+     Source: github.com/stripe/ai (✅ verified registry)
+
+  🔎 GitHub Results:
+  2. community/stripe-checkout — Stripe Checkout integration patterns
+     Source: github.com/user/repo (⚠️ community, 45⭐)
+
+  📚 context7 Docs (alternative):
+  3. Stripe API docs available via context7 (real-time, no install needed)
+
+Which to install? (number, or 'skip')
+```
+
+> [!TIP]
+> If **only context7 results** found (no SKILL.md), suggest:
+> "No installable skill found. But I can use context7 to query live docs for `<query>` anytime. Want to proceed without installing?"
+
+---
+
+## Step 3: Preview & Confirm
+
+// turbo
+
+For the selected skill:
+
+1. **Read SKILL.md** from source (via GitHub MCP or clone)
+   ```
+   mcp_github_get_file_contents(owner, repo, "skills/<name>/SKILL.md")
+   ```
+
+2. **Show preview** to user:
+   ```
+   📋 Skill Preview: stripe-best-practices
+   ├── Name: Stripe Best Practices
+   ├── Source: github.com/stripe/ai
+   ├── Size: ~120 lines
+   ├── Conflicts: None (new skill)
+   └── Dependencies: None
+
+   Install? (y/n)
+   ```
+
+3. **Check conflicts**: Does `.agent/skills/<name>/` already exist?
+   - If yes → offer UPGRADE mode (merge) or SKIP
+
+---
+
+## Step 4: Install
+
+// turbo
+
+### 4.1 Clone source
+```bash
+git clone --depth 1 <repo-url> .agent/tmp/<repo-name>
+```
+
+### 4.2 Copy skill files
+```bash
+# Copy skill directory to our skills folder
+cp -r .agent/tmp/<repo-name>/skills/<skill-name> .agent/skills/<skill-name>/
+```
+
+### 4.3 Adapt to our conventions
+For each file in the installed skill:
+- Ensure SKILL.md has valid frontmatter (name, description)
+- Check line count — if > 150 lines, suggest splitting per `skill-loading.md` rule
+- Rename directories to match our naming convention (lowercase-kebab)
+
+### 4.4 Register in manifest
+Update `.agent/skills-manifest.json`:
+```json
+{
+  "name": "<skill-name>",
+  "description": "<from SKILL.md>",
+  "path": ".agent/skills/<skill-name>",
+  "source": "<repo-url>",
+  "installed": "<ISO date>",
+  "type": "external"
+}
+```
+
+Update `.agent/skills-manifest.json` with triggers and workflow refs.
+
+### 4.5 Cleanup
+```bash
+rm -rf .agent/tmp/<repo-name>
+```
+
+---
+
+## Step 5: Confirm & Suggest
+
+```
+✅ Installed: stripe-best-practices
+   Path: .agent/skills/stripe-best-practices/
+   Source: github.com/stripe/ai
+   Type: external
+
+💡 Tip: Use /commit to save this change.
+```
+
+---
+
+## Error Handling
+
+| Issue | Recovery |
+|-------|----------|
+| No results found | Suggest broadening query or using context7 |
+| SKILL.md missing | Warn: "This repo has no SKILL.md — cannot install as skill" |
+| Already installed | Offer upgrade or skip |
+| Clone fails | Check URL, suggest manual download |
+| Skill > 150 lines | Auto-split per skill-loading.md rule |
+
+---
+
+## Search Priority Order
+
+```
+Registry (instant) → GitHub MCP (seconds) → Web (seconds) → context7 (fallback)
+     ↓ found?              ↓ found?            ↓ found?          ↓ found?
+   Install             Install             Install         Offer live docs
+```

package/.agent/workflows/qa.md

@@ -0,0 +1,54 @@
+---
+description: Create comprehensive test case documents and test plans based on project requirements.
+---
+
+# QA Workflow
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                      |
+| :------------------------------------------- | :----------------------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | Analyze complex application logic and edge cases |
+| `mcp_context7_query-docs`                    | Research testing frameworks or best practices    |
+
+---
+
+## Step 1: Requirement Discovery
+
+// turbo
+
+1. **Invoke `[qa-tester]` skill** to analyze the `docs/` folder.
+2. Identify features, constraints, and business logic that require testing.
+3. Map out:
+   - Happy Paths (Golden Flows)
+   - Negative Paths (Error handling)
+   - Boundary Cases
+   - Security/Performance considerations
+4. **WAIT** for user to confirm the list of scenarios to be documented.
+
+---
+
+## Step 2: Draft Test Documentation
+
+// turbo
+
+1. **Invoke `[qa-tester]` skill** to create:
+   - **Test Plan**: High-level strategy for the current release/feature (`docs/035-QA/Test-Plans/`).
+   - **Test Cases**: Detailed step-by-step cases (`docs/035-QA/Test-Cases/`).
+2. Follow the standard mapping in `.agent/rules/documents.md`:
+   - Test Plan naming: `MTP-{Name}.md`
+   - Test Case naming: `TC-{Feature}-{NNN}.md`
+3. Create a `draft-qa-docs.md` artifact for review.
+
+---
+
+## Step 3: Finalize and Organize
+
+// turbo
+
+1. After approval, save all files to their respective folders in `docs/035-QA/`.
+2. **Mandatory**:
+   - Update `docs/035-QA/QA-MOC.md`.
+   - Update `docs/000-Index.md` if needed.
+   - Ensure all frontmatter (id, type, status, created) is correctly populated according to `.agent/rules/documents.md`.
+3. Present summary of created tests.

package/.agent/workflows/ui-ux-design.md

@@ -0,0 +1,108 @@
+---
+description: Transform requirements into comprehensive UI/UX design deliverables.
+---
+
+# UI/UX Design Workflow
+
+## MCP Usage Guidelines
+
+| MCP Tool                  | When to Use                                     |
+| ------------------------- | ----------------------------------------------- |
+| `mcp_context7_query-docs` | Research UI libraries (shadcn, radix, tailwind) |
+| `search_web`              | Research design trends and UX patterns          |
+| `generate_image`          | Create low-fi wireframes or conceptual assets   |
+
+---
+
+## Step 1: Deep Research
+
+// turbo
+
+> 💡 **MANDATORY**: Follow `.agent/rules/research.md` for visual and UX excellence.
+
+1. **Invoke `[designer]` skill** and `search_web` to:
+   - Identify "Design of the Year" level trends for the specific sector.
+   - Find innovative UX patterns (micro-interactions, navigation).
+   - Gather reference images/styles for the mood board.
+2. Create `design-research.md` in `docs/050-Research/`.
+3. **WAIT** for user to approve the creative direction.
+
+---
+
+## Step 2: Discovery & Context
+
+// turbo
+
+1. **Invoke `[designer]` skill** to:
+   - Check if Design System exists in `docs/`
+   - Analyze requirements/PRD
+   - Determine design scope (New System vs New Feature)
+2. **WAIT** for analysis result
+
+---
+
+## Step 3: Design System (If Needed)
+
+// turbo
+
+**Skip if**: Design system already exists.
+
+> 💡 **MCP**: Use `context7` with `/tailwindcss/tailwindcss` or `/shadcn/ui` for config
+
+1. **Invoke `[designer]` skill** to define:
+   - Typography, Colors, Spacing scale
+   - Component primitives (Buttons, Inputs, Cards)
+   - Motion principles
+2. Create/Update Design System documentation
+3. **WAIT** for user approval
+
+---
+
+## Step 4: Component & Flow Design
+
+// turbo
+
+1. **Invoke `[designer]` skill** to:
+   - Map user flows based on User Stories
+   - Define necessary components (Reuse vs New)
+   - Create component specifications
+2. Create flow and component documentation
+3. **WAIT** for user review
+
+---
+
+## Step 5: Prototyping
+
+// turbo
+
+> 💡 **MCP**: Use `generate_image` for visual concept validation if needed
+
+1. **Invoke `[frontend-developer]` skill** to:
+   - Build HTML/CSS prototypes in `prototype/` (keep it simple)
+   - Or create interactive mockups
+2. **Invoke `[designer]` skill** to:
+   - Review for accessibility (Contrast, Semantic HTML)
+   - Check alignment with Design System
+
+---
+
+## Step 6: Review & Handoff
+
+// turbo
+
+1. Present prototypes to user
+2. Collect and apply feedback
+3. Update MOC files and finalize docs
+4. **Handoff**: Trigger `/implement-feature` if approved
+
+---
+
+## Quick Reference
+
+| Step | Skill              | Output              |
+| ---- | ------------------ | ------------------- |
+| 1    | designer           | Design Research     |
+| 2    | designer           | Scope analysis      |
+| 3    | designer           | Design System docs  |
+| 4    | designer           | Flow/Component docs |
+| 5    | frontend-developer | HTML Prototypes     |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jhm1909
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.