@jhm1909/ag-kit 0.1.0

package/.agent/workflows/debug.md

@@ -0,0 +1,65 @@
+---
+description: Scientific debugging workflow: Hypothesize, Instrument, Reproduce, Analyze, Fix.
+---
+
+# Scientific Debug & Fix Workflow
+
+## Step 1: Hypothesis Generation
+
+1. **Analyze the Issue**: Review the bug report and available context.
+2. **Generate Hypotheses**: Brainstorm multiple potential causes (e.g., "Race condition in data fetching", "Incorrect state update logic", "Edge case in input validation").
+3. **Select Top Candidates**: Prioritize the most likely hypotheses to investigate first.
+
+---
+
+## Step 2: Instrumentation
+
+1. **Plan Logging**: Decide WHERE key information is missing to validate your hypotheses.
+2. **Add Logging**: Instrument the code with targetted `console.log`, specific logger calls, or performance markers.
+   - _Goal_: Capture runtime state, variable values, and execution flow relevant to the hypotheses.
+   - _Tip_: Add unique prefixes to logs (e.g., `[DEBUG-HYPOTHESIS-1]`) for easy filtering.
+
+---
+
+## Step 3: Reproduction & Data Collection
+
+1. **Execution**: Run the application or test case to reproduce the bug.
+   - If a reproduction script doesn't exist, create one now if possible.
+2. **Collect Data**: Capture the output from your instrumentation.
+
+---
+
+## Step 4: Analysis & Root Cause
+
+1. **Analyze Evidence**: Look at the collected logs/data.
+   - Does the data confirm a hypothesis?
+   - Does it rule one out?
+2. **Pinpoint Root Cause**: Identify exactly _why_ the bug is happening based on the evidence.
+3. **Iterate (if needed)**: If inconclusive, return to Step 1 or 2 with new knowledge.
+
+---
+
+## Step 5: Targeted Implementation
+
+1. **Apply Fix**: Implement a targeted fix based _only_ on the confirmed root cause. Avoid "shotgun debugging" (changing things randomly).
+2. **Cleanup**: Remove the temporary debugging instrumentation.
+
+---
+
+## Step 6: Verification
+
+// turbo
+
+1. **Run Reproduction Test**: Verify that the bug is gone.
+2. **Run Regression Tests**: Run related unit tests to ensure no side effects.
+3. **Lint & Type Check**: Ensure code quality standards are met.
+
+---
+
+## Step 7: Finalize
+
+1. **Draft Commit**: Create a concise commit message (e.g., `fix(module): description of fix`).
+2. **Report**: Summarize the process:
+   - What was the hypothesis?
+   - What evidence confirmed it?
+   - How was it fixed?

package/.agent/workflows/development.md

@@ -0,0 +1,49 @@
+---
+description: General coding workflow for implementing changes, bug fixes, or minor features.
+---
+
+# Development Workflow
+
+## Step 1: Analyze & Plan
+
+// turbo
+
+1. Understand the requirement or bug report.
+2. **MUST** use `mcp_sequential-thinking_sequentialthinking` to:
+   - Analyze the existing code structure.
+   - Design the solution.
+   - Identify potential edge cases and impacts.
+3. If the task is complex, create an `implementation_plan.md` artifact.
+4. **WAIT** for user confirmation if the plan involves major architectural changes.
+
+---
+
+## Step 2: Execute Code Changes
+
+// turbo
+
+1. Implement the planned changes iteratively.
+2. **Backend**: Update models, logic, and APIs as needed.
+3. **Frontend**: Update UI components and state management.
+4. Ensure code follows project standards and linting rules.
+
+---
+
+## Step 3: Verify & Test
+
+// turbo
+
+1. Run existing tests to ensure no regressions.
+2. Add new unit or integration tests for the changes.
+3. Perform manual verification (e.g., using the browser tool for UI changes).
+4. **MUST** document proof of work in a `walkthrough.md` artifact if the change is significant.
+
+---
+
+## Step 4: Finalize
+
+// turbo
+
+1. Update related documentation (MOCs, API specs, etc.).
+2. Clean up any temporary files or comments.
+3. Present a summary of changes and verification results.

package/.agent/workflows/documentation.md

@@ -0,0 +1,221 @@
+---
+description: Generate comprehensive documentation (Architecture, API, Specs) from either Codebase or Requirements.
+---
+
+# Documentation Workflow
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                    |
+| :------------------------------------------- | :--------------------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | Analyze complex architecture, design decisions |
+| `mcp_context7_query-docs`                    | Research framework patterns, diagram syntax    |
+
+> [!IMPORTANT]
+> **AI-OPTIMIZED RULE**: 1 file = 1 concept. All files MUST have frontmatter, wiki-links, and follow `documents.md` naming conventions. No file should exceed ~100 lines — split if necessary.
+
+---
+
+## Step 0: Determine Mode
+
+**Determine the source of truth:**
+
+1. **From Codebase**: Reverse engineer docs from existing code.
+2. **From Requirements**: Forward engineer detailed specs (SDD, Stories) from PRD/Roadmap.
+
+---
+
+# MODE A: From Codebase
+
+## Step A1: Codebase Discovery
+
+// turbo
+
+> 💡 **MCP**: Use `sequential-thinking` to analyze unfamiliar project structures
+
+1. **Invoke `[lead-architect]` skill** to analyze codebase structure
+2. Identify: tech stack, entry points, API routes, DB schemas
+3. **Clarify & Confirm**:
+   - **CRITICAL**: If unclear, **ASK** the user for clarification.
+   - Summarize findings and **WAIT** for user to confirm
+
+---
+
+## Step A2: Technical Documentation (Architecture, API, Schema)
+
+// turbo
+
+1. **Invoke `[lead-architect]` skill** to create individual files:
+   - `docs/030-Specs/Architecture/SDD-{ProjectName}.md` — System Context (C4)
+   - `docs/030-Specs/Architecture/Component-{Name}.md` — per major component
+   - `docs/030-Specs/Architecture/Sequence-{Flow}.md` — per critical flow
+2. **Invoke `[backend-developer]` skill** to create individual files:
+   - `docs/030-Specs/API/Endpoint-{Resource}.md` — per API resource group
+   - `docs/030-Specs/Schema/DB-Entity-{Name}.md` — per database entity
+
+> [!TIP]
+> Each architecture diagram gets its own file. AI finds `Sequence-Auth.md` faster than searching a 500-line SDD.
+
+---
+
+## Step A3: Functional Documentation (Reverse Engineering)
+
+// turbo
+
+**Objective**: Derive business logic from existing implementation.
+
+1. **Invoke `[business-analysis]` skill** to:
+   - Analyze codebase to understand user flows
+   - Create **individual files per feature** (not monolithic):
+     - `docs/022-User-Stories/Epics/Epic-{Feature}.md` — per identified feature
+     - `docs/020-Requirements/Use-Cases/UC-{NN}-{Feature}.md` — per user flow
+   - Each file has frontmatter with `linked-to` wiki-links
+2. **Review**: Present findings to user to confirm alignment
+
+---
+
+## Step A4: Operational & Quality Documentation
+
+// turbo
+
+**Objective**: Document how to run, test, and deploy.
+
+1. **Invoke `[devops-engineer]` skill** to create:
+   - `docs/030-Specs/Architecture/Infrastructure.md`
+   - `docs/030-Specs/Architecture/Deployment.md`
+   - `docs/030-Specs/Configuration.md`
+2. **Invoke `[qa-tester]` skill** to create:
+   - `docs/035-QA/Test-Plans/Strategy.md`
+   - `docs/035-QA/Reports/Coverage.md`
+3. **Invoke `[backend-developer]` skill** to create:
+   - `docs/060-Manuals/Admin-Guide/Setup-Guide.md`
+   - `docs/060-Manuals/Admin-Guide/Scripts.md`
+
+---
+
+## Step A5: Project Planning & Strategy
+
+// turbo
+
+1. **Invoke `[product-manager]` skill** to create:
+   - `docs/010-Planning/Roadmap.md` — with `[[Epic-X]]` wiki-links
+   - `docs/010-Planning/OKRs.md`
+   - `docs/010-Planning/Sprints/Current-Status.md`
+2. **Review**: Present for alignment
+
+---
+
+# MODE B: From Requirements
+
+**Prerequisite**: Existing PRD + Epics from `/brainstorm`.
+
+## Step B1: Create SDD (System Design Document)
+
+// turbo
+
+> 💡 **MCP**:
+>
+> - **MUST** use `sequential-thinking` for architectural decisions
+> - Use `context7` with relevant framework docs for tech stack research
+
+1. **Read existing artifacts**: Scan `docs/020-Requirements/PRD-*.md` and `docs/022-User-Stories/Epics/Epic-*.md`
+2. **Invoke `[lead-architect]` skill** to draft:
+   - High-level system architecture
+   - Technology stack decisions
+   - Component diagram
+   - Data flow overview
+3. Create `draft-sdd.md` artifact for review
+4. After approval → Save to `docs/030-Specs/Architecture/SDD-{ProjectName}.md`
+
+---
+
+## Step B2: Expand Epics (if needed)
+
+// turbo
+
+> [!IMPORTANT]
+> If `/brainstorm` already created `Epic-{Feature}.md` files, **READ and EXPAND** them — don't recreate from scratch.
+
+1. **Read** all `docs/022-User-Stories/Epics/Epic-*.md` files
+2. **Invoke `[business-analysis]` skill** to:
+   - Expand each Epic with detailed acceptance criteria
+   - Add Mermaid sequence/flow diagrams where helpful
+   - Create `docs/020-Requirements/Use-Cases/UC-{NN}-{Feature}.md` if missing
+3. Update wiki-links between Epics and Use Cases
+
+---
+
+## Step B3: Create Individual User Stories
+
+// turbo
+
+> [!IMPORTANT]
+> **1 Story file per Epic**. Never create a monolithic `all-user-stories.md`.
+
+For **each Epic** in `docs/022-User-Stories/Epics/`:
+
+1. **Invoke `[business-analysis]` skill** to create:
+   - `docs/022-User-Stories/Backlog/Story-{FeatureName}.md`
+
+```yaml
+---
+id: STORY-{NNN}
+type: story
+status: draft
+created: YYYY-MM-DD
+linked-to: [[Epic-{FeatureName}]]
+complexity: S|M|L|XL
+---
+```
+
+Content:
+- **As a** {user}, **I want** {action}, **so that** {benefit}
+- **Acceptance Criteria** — checkable list
+- **Tasks** — grouped checklist for implementation
+
+2. After review → keep in `Backlog/` (moves to `Active-Sprint/` during implementation)
+
+---
+
+## Step B4: Create ADRs (Optional)
+
+// turbo
+
+**Skip if**: User did not request ADRs.
+
+1. **Invoke `[lead-architect]` skill** to document each technical decision as individual file:
+   - `docs/030-Specs/Architecture/ADR-{NNN}-{Decision}.md`
+
+---
+
+# Finalize
+
+## Step X: Finalize
+
+// turbo
+
+1. **Create/update ALL MOC files** in populated folders:
+   - `docs/010-Planning/Planning-MOC.md`
+   - `docs/020-Requirements/Requirements-MOC.md`
+   - `docs/022-User-Stories/Stories-MOC.md`
+   - `docs/030-Specs/Specs-MOC.md`
+   - `docs/035-QA/QA-MOC.md`
+   - `docs/040-Design/Design-MOC.md`
+   - `docs/060-Manuals/Manuals-MOC.md`
+2. **Validate** wiki-links and frontmatter across all created files
+3. Present summary:
+   - Total files created (by Dewey folder)
+   - Wiki-link graph overview
+   - Suggest next steps: `/ui-ux-design` or `/implement-feature`
+
+---
+
+## AI-Optimization Checklist
+
+Before finishing, verify:
+- [ ] Every file has frontmatter (id, type, status, created, linked-to)
+- [ ] No monolithic files — 1 concept per file
+- [ ] All cross-references use `[[wiki-links]]`
+- [ ] MOC files updated for every populated folder
+- [ ] No file exceeds ~100 lines
+- [ ] Naming follows `documents.md` conventions exactly

package/.agent/workflows/gen-tests.md

@@ -0,0 +1,53 @@
+---
+description: Generate unit, E2E, security, and performance tests using the qa-tester skill.
+---
+
+# Generate Tests Workflow
+
+## Step 1: Discovery & Strategy
+
+// turbo
+
+1. **Invoke `[qa-tester]` skill** to analyze the `docs/` folder and current codebase structure.
+2. Ask the user which type of tests they want to generate:
+   - **Unit Tests**: For specific functions or utilities (e.g., `tests/unit/`).
+   - **E2E Tests**: For user flows (e.g., `tests/e2e/`).
+   - **Security Tests**: For vulnerability assessments.
+   - **Performance Tests**: For load and responsiveness checks.
+3. Identify the specific files or features that need testing based on user input.
+
+---
+
+## Step 2: Test Plan & Case Generation
+
+// turbo
+
+1. **Invoke `[qa-tester]` skill** to create/update the Test Plan and Test Cases:
+   - For **Unit Tests**: Identify edge cases, boundary conditions, and happy paths.
+   - For **E2E Tests**: valid/invalid user flows.
+   - For **Security**: potential injection points, auth flaws.
+2. Generate the test documentation in `docs/035-QA/Test-Cases/` following the naming convention `TC-{Feature}-{NNN}.md`.
+3. Create a `draft-test-docs.md` artifact with the proposed test cases for review.
+
+---
+
+## Step 3: Test Code Generation
+
+1. **Wait** for user approval of the test cases.
+2. **Invoke `[qa-tester]` skill** to generate the actual test code.
+   - Use the project's existing testing framework (e.g., Jest, Playwright, Vitest).
+   - Ensure mocks and stubs are correctly implemented for unit tests.
+   - Ensure selectors and interaction steps are robust for E2E tests.
+3. Save the generated test code to the appropriate directories (e.g., `tests/unit/`, `tests/e2e/`).
+
+---
+
+## Step 4: Verification & Reporting
+
+1. Run the generated tests using the project's test runner.
+2. If tests fail:
+   - Analyze the failure.
+   - **Invoke `[qa-tester]` skill** to fix the test code or report the bug if it's a real issue.
+3. **Mandatory**:
+   - Update `docs/035-QA/QA-MOC.md`.
+   - Update `docs/000-Index.md` if needed.

package/.agent/workflows/guide.md

@@ -0,0 +1,196 @@
+---
+description: Interactive workflow discovery — helps users find the right workflow or chain for their task
+---
+
+# Guide — Workflow Discovery
+
+> [!TIP]
+> Don't know which workflow to use? This guide analyzes your situation and recommends the best path.
+> Works for beginners (guides every step) and experts (skip straight to what you need).
+
+---
+
+## Step 1: Understand Context
+
+**Invoke `[project-manager]` skill** to analyze the user's intent.
+
+Ask user:
+
+```
+🧭 What are you trying to do?
+
+1. 🆕 Start a new project from scratch
+2. ➕ Add a feature to an existing project
+3. 🐛 Fix a bug
+4. 🎨 Design UI/UX
+5. 📚 Write documentation
+6. 🔍 Study/absorb another project's patterns
+7. 🧪 Write tests
+8. 🚀 Deploy / ship
+9. 🤷 I don't know, help me figure it out
+```
+
+> **For beginners**: pick a number. The AI will handle everything.
+> **For experts**: skip this and call any workflow directly (e.g. `/break-tasks`).
+
+---
+
+## Step 2: Analyze & Recommend
+
+**Invoke `[project-manager]` skill** to match intent → workflow chain.
+
+Based on user's answer, present the recommended **workflow chain**:
+
+### If 1: New Project
+
+```
+📋 Recommended chain for a new project:
+
+Phase 0 — Planning:
+  /brainstorm        → Define requirements, roadmap, PRD
+  /documentation     → Create specs (SDD, epics, stories)
+
+Phase 1 — MVP:
+  /break-tasks       → Break into atomic tasks
+  /implement-feature → Code phase 1 features
+  /gen-tests         → Write tests
+  /commit            → Save progress
+
+Phase 2+ — Iterate:
+  /break-tasks       → Next batch of features
+  /implement-feature → Code them
+  /commit            → Ship
+
+Ready to start? Type /brainstorm to begin!
+```
+
+### If 2: Add Feature
+
+```
+📋 For a new feature:
+  /break-tasks       → Break feature into tasks
+  /implement-feature → Code the feature
+  /gen-tests         → Test coverage
+  /commit            → Push changes
+
+Already have specs? Skip straight to /break-tasks.
+No specs yet? Start with /brainstorm first.
+```
+
+### If 3: Fix Bug
+
+```
+📋 For bug fixing:
+  /development       → Debug + fix
+  /gen-tests         → Add regression test
+  /commit            → Push fix
+```
+
+### If 4: Design UI/UX
+
+```
+📋 For UI/UX work:
+  /ui-ux-design      → Create design specs
+  /break-tasks       → Break into component tasks
+  /implement-feature → Build components
+  /commit            → Push
+```
+
+### If 5: Documentation
+
+```
+📋 For documentation:
+  /documentation     → Generate docs (from code or requirements)
+  /commit            → Push docs
+
+Mode A: From existing codebase (reverse-engineer)
+Mode B: From requirements (forward-engineer)
+```
+
+### If 6: Study External Project
+
+```
+📋 For absorbing patterns:
+  /absorb            → Analyze reference project
+  /break-tasks       → Plan integration tasks
+  /implement-feature → Apply best parts
+  /commit            → Save
+```
+
+### If 7: Write Tests
+
+```
+📋 For testing:
+  /qa                → Create test plan
+  /gen-tests         → Generate test code
+  /commit            → Push tests
+```
+
+### If 8: Deploy
+
+```
+📋 For deployment:
+  /development       → Final code review
+  /commit            → Ensure latest pushed
+  Then follow your CI/CD pipeline.
+```
+
+### If 9: Help Me
+
+**Invoke `[lead-architect]` skill** to analyze project state.
+
+// turbo
+
+Check project structure to detect stage:
+
+```bash
+ls docs/ 2>/dev/null; ls src/ 2>/dev/null; ls package.json 2>/dev/null
+```
+
+| What I see | Stage | Start with |
+|-----------|-------|-----------|
+| Empty project | Beginning | `/brainstorm` |
+| Docs but no code | Planning done | `/break-tasks` |
+| Code but no docs | Legacy project | `/documentation` (Mode A) |
+| Code + tests failing | Bug phase | `/development` |
+| Everything looks good | Ship it | `/commit` |
+
+---
+
+## Step 3: Execute Chain
+
+**Invoke `[project-manager]` skill** to track chain progress.
+
+After user picks a workflow:
+
+1. Execute the chosen workflow
+2. When it completes, auto-suggest the next in chain:
+   ```
+   ✅ /brainstorm complete!
+   💡 Next in chain: /documentation — create detailed specs
+   Ready? Type /documentation or skip to /break-tasks.
+   ```
+3. Track progress:
+   ```
+   Chain progress: ✅ /brainstorm → 🔄 /documentation → ⏳ /break-tasks → ⏳ /implement-feature
+   ```
+
+---
+
+## All Available Workflows
+
+| Workflow | Purpose | Skills Used | Best For |
+|----------|---------|-------------|----------|
+| `/brainstorm` | Requirements, roadmap | `project-manager` | Starting a project |
+| `/documentation` | Specs, SDD, stories | `lead-architect`, `business-analysis` | After brainstorm |
+| `/break-tasks` | Task breakdown | `lead-architect`, `business-analysis` | Before coding |
+| `/implement-feature` | Full implementation | All dev skills | Coding phase |
+| `/development` | Quick fixes | Context-dependent | Small tasks |
+| `/ui-ux-design` | Design specs | `designer` | Design phase |
+| `/qa` | Test plans | `qa-tester` | Quality check |
+| `/gen-tests` | Generate test code | `qa-tester` | After coding |
+| `/absorb` | Study reference project | `lead-architect` | Learning patterns |
+| `/commit` | Git commit + push | _(no skill)_ | Saving work |
+| `/bootstrap` | Project scaffolding | `lead-architect` | Initial setup |
+| `/custom-behavior` | Customize rules | `project-manager` | Meta-config |
+| `/guide` | This workflow! | `project-manager` | When lost |