@jhm1909/ag-kit 0.1.0

package/.agent/workflows/brainstorm.md

@@ -0,0 +1,168 @@
+---
+description: Analyze ideas with the user and create preliminary high-level documents (Roadmap, PRD).
+---
+
+# Brainstorm Workflow
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                            | Example                                 |
+| :------------------------------------------- | :----------------------------------------------------- | :-------------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | Analyze requirements, feature dependencies, trade-offs | Break down ambiguous requests           |
+| `mcp_context7_query-docs`                    | Research library patterns, APIs, best practices        | "How to setup auth in Next.js"          |
+| `search_web`                                 | Proactive research for implementation patterns         | "best architecture for agentic systems" |
+
+---
+
+## Step 1: Iterative Requirement Analysis & Research
+
+> [!IMPORTANT]
+> **LOOP THIS STEP**: Cycle until the user's requirements are crystal clear.
+
+**Goal**: Achieve a "Shared Understanding" with the user.
+
+1. **Analyze (Internal)**:
+   - Use `mcp_sequential-thinking_sequentialthinking` to breakdown the request.
+   - Explore angles, edge cases, and creative possibilities.
+   - Identify gaps, missing features, or ambiguous terms.
+
+2. **Research (External)**:
+   - Use `search_web` to understand domain, competitors, best practices.
+   - Use `read_url_content` for specific references.
+   - Verify technical feasibility.
+
+3. **Clarify (Interaction)**:
+   - Summarize findings in an artifact.
+   - Ask specific questions to resolve ambiguities.
+   - **WAIT** for user response.
+
+4. **Evaluation**:
+   - New info? → **GO TO 1.1** (Repeat).
+   - User confirms → **BREAK LOOP**, go to Step 2.
+
+---
+
+## Step 2: Create Roadmap
+
+// turbo
+
+> 💡 **MCP**: Use `sequential-thinking` for phased planning and risk assessment.
+
+1. **Invoke `[product-manager]` skill** to draft:
+   - Project timeline and milestones
+   - Phase breakdown (MVP, v1.0, v2.0)
+   - Key deliverables per phase — **each major feature becomes a wiki-link**: `[[Epic-{Feature}]]`
+2. Create `draft-roadmap.md` artifact for review
+3. After approval → Save to `docs/010-Planning/Roadmap-{ProjectName}.md`
+4. **WAIT** for user response
+
+---
+
+## Step 3: Create PRD & Atomized Feature Docs
+
+// turbo
+
+> [!IMPORTANT]  
+> **AI-OPTIMIZED RULE**: 1 file = 1 concept. Never dump all features into 1 monolithic PRD.
+> All files MUST follow `documents.md` conventions: frontmatter, naming, wiki-links.
+
+### Step 3.1: PRD Overview
+
+1. **Invoke `[product-manager]` skill** to draft a **concise** PRD overview:
+   - Business objectives and success metrics
+   - Target audience/user personas (brief)
+   - Feature list — each feature is a wiki-link: `[[Epic-{Feature}]]`
+   - Technical constraints
+2. Save to `docs/020-Requirements/PRD-{ProjectName}.md`
+
+> [!TIP]  
+> PRD should be **max 50-80 lines**. Details go in individual Epic/Use Case files.
+
+### Step 3.2: Create Individual Epic Files
+
+For **each major feature** identified in the PRD:
+
+1. Create `docs/022-User-Stories/Epics/Epic-{FeatureName}.md` with:
+
+```yaml
+---
+id: EPIC-{NNN}
+type: epic
+status: draft
+created: YYYY-MM-DD
+linked-to: [[PRD-{ProjectName}]]
+---
+```
+
+Content sections:
+- **Summary** — What this feature does (2-3 sentences)
+- **User Value** — Why users need this
+- **Scope** — What's included, what's explicitly NOT included
+- **Acceptance Criteria** — Checkable conditions for "done"
+- **Related**: `[[UC-{NN}-{Feature}]]`, `[[Story-{Feature}]]`
+
+### Step 3.3: Create Individual Use Case Files
+
+For **each feature** that has user-facing flows:
+
+1. Create `docs/020-Requirements/Use-Cases/UC-{NN}-{FeatureName}.md` with:
+
+```yaml
+---
+id: UC-{NN}
+type: use-case
+status: draft
+created: YYYY-MM-DD
+linked-to: [[Epic-{FeatureName}]]
+---
+```
+
+Content sections:
+- **Actor** — Who performs this action
+- **Preconditions** — What must be true before
+- **Main Flow** — Numbered steps (happy path)
+- **Alternative Flows** — Edge cases, error handling
+- **Postconditions** — What's true after success
+
+### Step 3.4: Create MOC Files
+
+Create/update Map of Content files for each populated folder:
+
+- `docs/010-Planning/Planning-MOC.md` — links to Roadmap
+- `docs/020-Requirements/Requirements-MOC.md` — links to PRD + Use Cases
+- `docs/022-User-Stories/Stories-MOC.md` — links to all Epics
+
+**WAIT** for user to review all artifacts before proceeding.
+
+---
+
+## Step 4: Transition
+
+1. Present summary:
+   - File count created
+   - Wiki-link graph (which files reference which)
+   - Any gaps identified
+2. Suggest next step: `/documentation` (SDD, Stories) or `/implement-feature`
+
+---
+
+## Quick Reference
+
+| Step | Skill           | Output |
+| :--- | :-------------- | :----- |
+| 1    | (analysis loop) | Shared understanding |
+| 2    | product-manager | `Roadmap-{Name}.md` |
+| 3.1  | product-manager | `PRD-{Name}.md` (overview) |
+| 3.2  | product-manager | `Epic-{Feature}.md` × N |
+| 3.3  | business-analysis | `UC-{NN}-{Feature}.md` × N |
+| 3.4  | — | MOC files |
+
+## AI-Optimization Checklist
+
+Before finishing, verify:
+- [ ] Every file has frontmatter (id, type, status, created, linked-to)
+- [ ] PRD references all Epics via `[[wiki-links]]`
+- [ ] Roadmap phases reference Epics via `[[wiki-links]]`
+- [ ] Each Epic references its Use Cases
+- [ ] MOC files list all documents in their folder
+- [ ] No file exceeds ~100 lines (split if necessary)

package/.agent/workflows/break-tasks.md

@@ -0,0 +1,77 @@
+---
+description: Orchestrates breaking down requirements into actionable tasks for implementation.
+---
+
+# Break Tasks Workflow
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                               |
+| :------------------------------------------- | :-------------------------------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | **REQUIRED** to break down requirements into atomic tasks |
+| `mcp_context7_query-docs`                    | To check best practices for specific technologies         |
+
+---
+
+## Step 1: Identify Source Document
+
+1. Locate the source document (PRD, User Story, Feature Spec, or SDD).
+2. If multiple versions exist, ask the user for clarification.
+3. Relevant folders to check:
+   - `docs/020-Requirements/`
+   - `docs/022-User-Stories/`
+   - `docs/030-Specs/`
+
+---
+
+## Step 2: Analyze Requirements
+
+// turbo
+
+1. **Invoke `[business-analysis]` skill** to extract key features and acceptance criteria.
+2. Use `sequential-thinking` to:
+   - Identify technical dependencies.
+   - Separate backend, frontend, and QA requirements.
+   - Spot ambiguous or missing details.
+3. List any clarifying questions for the user.
+4. **WAIT** for user clarification if needed.
+
+---
+
+## Step 3: Atomic Task Breakdown
+
+// turbo
+
+> 💡 **MCP**: **MUST** use `sequential-thinking` here to ensure tasks are atomic and manageable.
+
+1. **Invoke `[lead-architect]` skill** to create a structured task list.
+2. Group tasks by component or phase (e.g., Database, API, Logic, UI, Testing).
+3. For each task, include:
+   - Goal/Description.
+   - Acceptance Criteria.
+   - Estimated complexity (if applicable).
+4. Create a `task-breakdown.md` artifact representing the proposed sequence.
+
+---
+
+## Step 4: Finalize Task Documentation
+
+// turbo
+
+1. After user approves the `task-breakdown.md` artifact:
+2. Update the `task.md` of the current session or create a new task file in `docs/050-Tasks/`.
+3. If creating a new file, follow standard naming: `docs/050-Tasks/Task-{FeatureName}.md`.
+4. Update `docs/050-Tasks/Tasks-MOC.md`.
+5. Present the finalized task list to the user.
+
+---
+
+## Quick Reference
+
+| Role               | Skill                | Responsibility                          |
+| :----------------- | :------------------- | :-------------------------------------- |
+| Product Manager    | `product-manager`    | Requirement validation & prioritization |
+| Lead Architect     | `lead-architect`     | Technical breakdown & dependencies      |
+| Developer          | `backend-developer`  | Backend/API specific tasks              |
+| Frontend Developer | `frontend-developer` | UI/UX specific tasks                    |
+| QA Tester          | `qa-tester`          | Verification & Edge case tasks          |

package/.agent/workflows/commit.md

@@ -0,0 +1,349 @@
+---
+description: Git commit and push with Conventional Commits, branch safety, and protected file guards
+---
+
+# Git Commit & Push
+
+> [!IMPORTANT]
+> Uses **Conventional Commits** format. Works with any project.
+> 3 modes: ⚡ Quick, 🛡️ Safe, 🎛️ Custom.
+
+---
+
+## Step 0: Choose Mode
+
+Present to user:
+
+```
+How would you like to commit?
+
+⚡ 1. Quick — stage all, auto-generate message, push (fastest)
+🛡️ 2. Safe — full checks: branch, .gitignore, protected files (recommended)
+🎛️ 3. Custom — you control each step
+```
+
+- If user says "nhanh" / "quick" / "go" → **Quick**
+- If user says "an toàn" / "safe" → **Safe**
+- If user says "tùy biến" / "custom" → **Custom**
+- Default (no preference): **Safe**
+
+### Mode Behavior Matrix
+
+| Step | ⚡ Quick | 🛡️ Safe | 🎛️ Custom |
+|------|---------|---------|-----------|
+| Branch check | Skip | ✅ Check + suggest branch | ✅ Check + ask user |
+| Diff summary | Show brief | ✅ Full summary + scope table | ✅ Full + ask scope grouping |
+| File selection | All at once | All (ask if >15 files) | ✅ Always ask |
+| .gitignore check | Skip | ✅ Auto-check + warn | ✅ Check + show details |
+| Protected files | Skip | ✅ Auto-check + confirm | ✅ List every file for approval |
+| Commit message | Auto-generate, no confirm | Auto-generate, show for confirm | ✅ User writes or edits |
+| Push | Auto push | Auto push | ✅ Ask push/PR/keep local |
+
+---
+
+## Step 1: Branch Safety Check
+
+> **⚡ Quick**: skip this step entirely
+> **🛡️ Safe / 🎛️ Custom**: execute
+
+// turbo
+
+```bash
+git branch --show-current
+```
+
+**If on `main` or `master`:**
+
+```
+⚠️ You are on the main branch.
+1. Create a new branch and commit there (recommended)
+2. Commit directly to main
+```
+
+- **🛡️ Safe**: For > 5 files, strongly recommend Option 1. For ≤ 5 files, default to Option 2.
+- **🎛️ Custom**: Always ask. If Option 1: ask for branch name or auto-suggest (e.g. `feat/add-auth`), then:
+  ```bash
+  git checkout -b <branch-name>
+  ```
+
+**If on feature branch**, proceed. After all commits:
+
+```
+What would you like to do?
+1. Push to remote (default)
+2. Push and create a Pull Request
+3. Keep locally
+```
+
+> **⚡ Quick**: auto-push (Option 1)
+
+---
+
+## Step 2: Diff Summary
+
+// turbo
+
+```bash
+git status --short; git diff --stat
+```
+
+**Auto-detect scopes** from changed file paths:
+
+| Directory Pattern | Scope |
+|-------------------|-------|
+| `apps/<name>/` | `<name>` |
+| `packages/<name>/` | `<name>` |
+| `src/` | omit (single-app) |
+| `.agent/skills/` | `skills` |
+| `.agent/workflows/` | `workflows` |
+| `.agent/rules/` | `rules` |
+| `cli/` or `bin/` | `cli` |
+| `docs/` | `docs` |
+| `test/` or `__tests__/` | `test` |
+| `.github/` | `ci` |
+| Root files | omit scope |
+
+**🛡️ Safe / 🎛️ Custom**: Present scope summary table.
+**⚡ Quick**: Show file count only: `📦 <N> files changed`.
+
+---
+
+## Step 2.5: File Selection
+
+> **⚡ Quick**: skip — always stage all
+> **🛡️ Safe**: ask only if > 15 files
+> **🎛️ Custom**: always ask
+
+```
+📦 Found <N> changed files across <M> scopes.
+How would you like to commit?
+
+1. All at once (single commit)
+2. Split by scope (one commit per scope) — recommended
+3. Let me pick specific files
+```
+
+**Option 3** (🎛️ Custom):
+```
+Changed files:
+ [1] cli/index.js
+ [2] cli/migrate-skills.js
+ [3] .agent/skills/ai-engineer/SKILL.md
+ ...
+
+Enter file numbers to stage (e.g. 1,2,5-8 or "all"):
+```
+
+---
+
+## Step 3: .gitignore Safety Check
+
+> **⚡ Quick**: skip
+> **🛡️ Safe**: auto-check + auto-fix
+> **🎛️ Custom**: check + ask before each fix
+
+// turbo
+
+```bash
+test -f .gitignore && echo "EXISTS" || echo "MISSING"
+```
+
+**If `.gitignore` is MISSING:**
+- 🚨 **STOP** — warn user
+- Auto-generate based on project type:
+
+| Detected Files | Project Type | Required Ignores |
+|---------------|-------------|-----------------|
+| `package.json` | Node.js | `node_modules/`, `dist/`, `*.log` |
+| `requirements.txt` / `pyproject.toml` | Python | `__pycache__/`, `*.pyc`, `.venv/` |
+| `go.mod` | Go | `vendor/`, binary outputs |
+| `Cargo.toml` | Rust | `target/` |
+| `*.sln` / `*.csproj` | .NET | `bin/`, `obj/` |
+
+**If `.gitignore` EXISTS:** verify critical patterns:
+
+| Pattern | Why |
+|---------|-----|
+| `node_modules/` | Dependencies (500MB+) |
+| `.env` or `.env*` | Secrets, API keys |
+| `dist/` / `build/` / `.next/` | Build outputs |
+| `*.log` | Log files |
+| `.DS_Store` / `Thumbs.db` | OS junk |
+
+**If patterns missing (🛡️ Safe):** auto-add + inform user.
+**If patterns missing (🎛️ Custom):**
+```
+⚠️ Your .gitignore is missing important patterns:
+  - node_modules/ (detected package.json)
+  - .env (secrets could be committed!)
+
+Add them now?
+1. Yes, add missing patterns (recommended)
+2. No, I know what I'm doing
+```
+
+---
+
+## Step 4: Protected Files Guard
+
+> **⚡ Quick**: skip
+> **🛡️ Safe**: check + confirm sensitive files
+> **🎛️ Custom**: list every changed file for explicit approval
+
+// turbo
+
+Check for **protected files** in changed list:
+
+| Category | Files |
+|----------|-------|
+| Lock files | `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `go.sum` |
+| Environment | `.env`, `.env.*` |
+| CI/CD | `.github/workflows/*`, `Dockerfile*`, `docker-compose*` |
+| Config roots | `package.json`, `tsconfig.json`, `*.config.*` |
+| Git config | `.gitignore`, `.gitmodules` |
+
+**Rules:**
+- **Never** silently stage `.env` files (even in ⚡ Quick mode!)
+- `package-lock.json` acceptable if `package.json` also changed
+- **🎛️ Custom**: "Did you intentionally modify `<file>`?" for each
+
+---
+
+## Step 5: Stage Files
+
+// turbo
+
+### Single Mode
+```bash
+git add -A
+```
+
+### Selective (from Step 2.5)
+```bash
+git add <file1> <file2> ...
+```
+
+### Split Mode
+```bash
+git add <scope-directory>/
+```
+
+Commit order (dependencies first):
+1. Shared libraries / internal packages
+2. Backend / API
+3. Frontend / UI
+4. Documentation
+5. CI/CD
+6. Root config files
+
+---
+
+## Step 6: Generate Commit Message
+
+// turbo
+
+1. Analyze staged diff
+2. Generate **Conventional Commit**:
+
+| Prefix | Use For |
+|--------|---------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `refactor:` | Restructuring |
+| `docs:` | Documentation |
+| `chore:` | Maintenance |
+| `test:` | Tests |
+| `style:` | Formatting only |
+| `ci:` | CI/CD |
+| `perf:` | Performance |
+
+3. Format: `type(scope): short description`
+   - Lowercase, imperative mood, no period, max 72 chars
+4. Complex changes: add body after blank line
+5. Breaking changes: `type(scope)!: description` + `BREAKING CHANGE:` footer
+
+**Mode behavior:**
+- **⚡ Quick**: auto-generate + commit immediately (no confirmation)
+- **🛡️ Safe**: auto-generate + show for approval
+- **🎛️ Custom**: show suggestion, user can edit or write their own
+
+---
+
+## Step 7: Commit
+
+```bash
+git commit -m "<message>"
+```
+
+### Hook Failures
+
+| Scenario | Action |
+|----------|--------|
+| Lint fails on your files | Fix errors, do NOT bypass |
+| Lint SIGKILL (OOM) | `--no-verify` + inform user |
+| Prettier on non-code | `--no-verify` |
+| Test failures | Fix tests, do NOT bypass |
+
+---
+
+## Step 8: Loop (Split Mode Only)
+
+Repeat Steps 5–7 for each remaining scope group.
+Show progress: `✅ 2/4 committed: skills, cli`
+
+---
+
+## Step 9: Push
+
+// turbo
+
+- **⚡ Quick / 🛡️ Safe**: auto-push
+- **🎛️ Custom**: ask first
+
+```bash
+git push origin HEAD
+```
+
+If rejected:
+```bash
+git pull --rebase origin HEAD; git push origin HEAD
+```
+
+If **new branch** (created in Step 1):
+```bash
+git push -u origin HEAD
+```
+
+---
+
+## Step 10: Confirm
+
+// turbo
+
+```bash
+git log --oneline -<N>
+```
+
+```
+✅ Committed and pushed successfully.
+<hash> <message>
+```
+
+If on a feature branch:
+```
+💡 To create a PR: gh pr create --fill
+```
+
+---
+
+## Error Recovery
+
+| Failure | Recovery |
+|---------|----------|
+| Nothing to commit | Inform user |
+| Push rejected | `git pull --rebase` then retry |
+| Merge conflict | Show files, ask user to resolve |
+| Auth failure | Check credentials / SSH |
+| Wrong branch | `git stash; git checkout -b feat/<name>; git stash pop` |
+| Large files blocked | Check `.gitignore`, suggest `git-lfs` |
+| `.env` staged | 🚨 Unstage immediately: `git reset HEAD .env` |

package/.agent/workflows/custom-behavior.md

@@ -0,0 +1,64 @@
+---
+description: Workflow for safely customizing Agent rules and workflows with impact analysis and user confirmation.
+---
+
+# Custom Behavior Workflow
+
+## Tool Usage Guidelines
+
+| Tool            | When to Use                                          | Example Query                                                   |
+| --------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
+| `find_by_name`  | Step 1: To find if a rule/workflow already exists    | `Pattern="*security*", SearchDirectory=".agent/rules"`          |
+| `view_file`     | Step 2: To read the existing content for comparison  | `AbsolutePath="/.../.agent/rules/security.md"`                  |
+| `notify_user`   | Step 3: To present analysis and ask for confirmation | `Message="I found an existing rule. Do you want to overwrite?"` |
+| `write_to_file` | Step 4: To create or overwrite the file              | `Overwrite=true`                                                |
+
+## Step 1: Identification & Search
+
+// turbo
+
+> 💡 **Tip**: Don't assume the file doesn't exist. Always search first.
+
+1.  Analyze the user's request to identify the _intent_ (e.g., "Add stricter linting", "Skip tests in deployment").
+2.  Search for existing Rules or Workflows that might already cover this.
+    - Rules: search in `.agent/rules/`
+    - Workflows: search in `.agent/workflows/`
+
+## Step 2: Impact Analysis
+
+> 💡 **Tip**: If a file exists, you MUST read it and compare it with the request.
+
+**Condition A: Target does NOT exist:**
+
+1.  Verify if a template exists in `.agent/assets/` or `references/` that could be used as a base.
+2.  Draft the new content in your memory.
+
+**Condition B: Target ALREADY exists:**
+
+1.  **Read** the current content of the file.
+2.  **Compare** the User's request vs the Current Content.
+3.  **Identify Conflicts**:
+    - Will this break existing constraints?
+    - Is this a "Breaking Change" or just an "Enhancement"?
+4.  **Formulate Recommendation**:
+    - _Adapt_: "I recommend creating a new file `custom-X.md` to avoid breaking standard X."
+    - _Override_: "This helps matches your specific need, but removes the safety check Y."
+
+## Step 3: User Confirmation
+
+> 💡 **Tip**: You must be explicit about what will change.
+
+1.  **Notify User** with a summary of your analysis.
+    - If **New**: "I will create a new rule [filename] that [does X]."
+    - If **modifying**: "I will modify [filename]. \n**Current**: [Summary of old]\n**Proposed**: [Summary of new]\n**Impact**: [Warning about side effects]"
+2.  **WAIT** for user approval.
+
+## Step 4: Execution
+
+1.  Perform the file operation (`write_to_file` or `replace_file_content`).
+2.  **Validate**: Read the file back to ensure syntax is correct (Markdown/YAML frontmatter).
+3.  **Register**: If it's a rule, remind the user if they need to manually activate it (unless it's `always_on`).
+
+## Step 5: Verification
+
+1. Check if the customization works as expected (if possible, by running a dry-run or asking user to test).