agent-skill-kit 3.9.135

package/.agent/workflows/think.md

@@ -0,0 +1,262 @@
+---
+description: Strategic decision engine — generate 3+ distinct alternatives with weighted scoring matrices, risk assessments, and actionable recommendations before writing any code.
+skills: [idea-storm, system-design, project-planner, context-engineering, problem-checker, knowledge-compiler]
+agents: [orchestrator, assessor, recovery, critic, learner, project-planner]
+---
+
+# /think - Strategic Decision Engine
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Activate structured ideation mode for architecture decisions, feature planning, and problem-solving — generating 3+ distinct options with weighted scoring matrices and risk assessments. **Differs from `/plan` (creates task breakdown and PLAN.md) and `/build` (writes code) by producing actionable decision matrices only — NO CODE, NO PLANS.** Uses `project-planner` with `idea-storm` for Socratic questioning and `system-design` for trade-off evaluation.
+
+---
+
+## 🤖 Meta-Agents Integration
+
+| Phase | Agent | Action |
+| ----- | ----- | ------ |
+| **Pre-Flight** | `assessor` | Evaluate decision scope and knowledge-compiler context |
+| **Execution** | `orchestrator` / `critic` | Coordinate problem framing, option generation and resolve scoring conflicts |
+| **Safety** | `recovery` | Save state and recover from decision generation failures |
+| **Post-Think** | `learner` | Log decision outcomes and scoring intelligence |
+
+```
+Flow:
+generate options �’ score(decision_matrix)
+       ↓
+scores too close? �’ critic.arbitrate()
+       ↓
+decision made �’ recommendation + next steps
+```
+
+---
+
+## 🔴 MANDATORY: Decision Framework
+
+### Phase 0: Pre-flight & Auto-Learned Context
+
+> **Rule 0.5-K:** Auto-learned pattern check.
+
+1. Read `.agent/skills/auto-learned/patterns/` for past failures before proceeding.
+2. Trigger `recovery` agent to run Checkpoint (`git commit -m "chore(checkpoint): pre-think"`).
+
+### Phase 1: Pre-flight & knowledge-compiler Context
+
+> **Rule 0.5-K:** knowledge-compiler pattern check.
+
+1. Read `.agent/skills/knowledge-compiler/patterns/` for past failures before proceeding.
+2. Trigger `recovery` agent to run Checkpoint (`git commit -m "chore(checkpoint): pre-think"`).
+
+### Phase 2: Problem Framing
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | $ARGUMENTS (decision topic or problem statement) |
+| **OUTPUT** | Framed problem: outcome, constraints, stakeholders, risk tolerance |
+| **AGENTS** | `project-planner`, `assessor` |
+| **SKILLS** | `idea-storm`, `context-engineering` |
+
+// turbo — telemetry: phase-2-framing
+
+Ask if not provided:
+
+| Question | Purpose |
+|----------|---------|
+| What OUTCOME do we want? | Define success criteria |
+| What CONSTRAINTS exist? | Time, budget, tech limitations |
+| Who are the STAKEHOLDERS? | Users, team, business |
+| What is the RISK TOLERANCE? | MVP / Production / Enterprise |
+
+### Phase 3: Generate 3+ Options
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Problem frame from Phase 2 |
+| **OUTPUT** | 3+ distinct approaches with pros/cons |
+| **AGENTS** | `project-planner`, `orchestrator` |
+| **SKILLS** | `idea-storm`, `system-design` |
+
+// turbo — telemetry: phase-3-options
+
+**Minimum 3 distinct approaches. Include one "unconventional" option.**
+
+For each option:
+- Description and approach
+- Pros / Cons table
+- Effort estimate (Low / Medium / High)
+
+### Phase 4: Decision Matrix & Recommendation
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Options from Phase 3 |
+| **OUTPUT** | Scored decision matrix, recommended option, risk assessment |
+| **AGENTS** | `project-planner`, `critic`, `learner` |
+| **SKILLS** | `system-design`, `problem-checker`, `knowledge-compiler` |
+
+// turbo — telemetry: phase-4-decision
+
+Score each option 1-5:
+
+| Criteria | Weight | Option A | Option B | Option C |
+|----------|--------|----------|----------|----------|
+| Implementation Speed | 20% | ? | ? | ? |
+| Scalability | 25% | ? | ? | ? |
+| Maintainability | 20% | ? | ? | ? |
+| Team Expertise | 15% | ? | ? | ? |
+| Cost | 20% | ? | ? | ? |
+| **Weighted Score** | 100% | **?** | **?** | **?** |
+
+If scores too close �’ `critic` arbitrates.
+
+Risk assessment for top option:
+- 🔴 **Blockers** — what could make this fail?
+- 🟡 **Mitigations** — how to reduce risk?
+- 🟢 **Quick Wins** — what to validate first?
+
+---
+
+## ⛔ MANDATORY: Problem Verification Before Completion
+
+> **CRITICAL:** This check MUST be performed before any `notify_user` or task completion.
+
+### Check @[current_problems]
+
+```
+1. Read @[current_problems] from IDE
+2. If errors/warnings > 0:
+   a. Auto-fix: imports, types, lint errors
+   b. Re-check @[current_problems]
+   c. If still > 0 �’ STOP �’ Notify user
+3. If count = 0 �’ Proceed to completion
+```
+
+> **Note:** /think produces decisions, not code. This check applies only if any artifacts were generated.
+
+---
+
+## 🔙 Rollback & Recovery
+
+If the generated decision matrix is flawed, overly generic, or hallucinates constraints:
+1. Revert any generated markdown files using the `recovery` meta-agent.
+2. Feed the failed reasoning back to the `critic` agent to identify logic gaps.
+3. Retry Phase 3 with more explicit constraints or a completely different Socratic framing.
+
+---
+
+## Output Format
+
+```markdown
+## 🧠 Decision: [Topic]
+
+### Context
+[1-2 sentence problem statement]
+
+### Constraints
+- ⏱️ Timeline: [deadline]
+- �’� Budget: [resources]
+- 🛠️ Tech: [stack requirements]
+
+### Option A: [Name] ⭐ RECOMMENDED
+[Description]
+
+| Pros | Cons |
+|------|------|
+| ✅ [benefit] | ❌ [drawback] |
+
+📊 Score: 4.2/5 | ⏱️ Effort: Medium
+
+### Option B: [Name]
+[Description]
+
+📊 Score: 3.5/5 | ⏱️ Effort: Low
+
+### Option C: [Name] 🚀 UNCONVENTIONAL
+[Description]
+
+📊 Score: 3.0/5 | ⏱️ Effort: High
+
+### Decision Matrix
+
+| Criteria | Weight | A | B | C |
+|----------|--------|---|---|---|
+| Speed | 20% | 4 | 5 | 2 |
+| Scalability | 25% | 5 | 3 | 5 |
+| Maintainability | 20% | 4 | 4 | 3 |
+| Team Fit | 15% | 4 | 5 | 2 |
+| Cost | 20% | 3 | 4 | 2 |
+| **Total** | | **4.1** | **4.0** | **2.9** |
+
+### Recommendation
+
+**Option A** wins with score 4.1/5.
+- 🔴 Blocker: [potential issue]
+- 🟡 Mitigation: [how to address]
+- 🟢 Validate First: [quick experiment]
+
+### Next Steps
+
+- [ ] Approve Option A
+- [ ] Run `/plan` to create implementation plan
+- [ ] Or `/think` again for deeper analysis
+```
+
+---
+
+## Examples
+
+```
+/think authentication: JWT vs Session vs OAuth
+/think state management: Redux vs Zustand vs Context
+/think database: PostgreSQL vs MongoDB vs Supabase
+/think hosting: Vercel vs AWS vs Railway
+/think monorepo vs polyrepo for microservices
+```
+
+---
+
+## Key Principles
+
+- **Quantify decisions** — use weighted scoring, not just vibes
+- **Include unconventional** — the wild option often sparks insights
+- **Risk-first thinking** — identify blockers before committing
+- **Actionable output** — end with clear next steps, not abstract analysis
+- **No code** — this is strategy, not implementation
+
+---
+
+## �— Workflow Chain
+
+**Skills Loaded (6):**
+
+- `idea-storm` - Socratic questioning and brainstorming
+- `system-design` - Trade-off evaluation and ADR
+- `project-planner` - Task breakdown and feasibility
+- `context-engineering` - Codebase parsing and context extraction
+- `problem-checker` - Generated artifacts validation
+- `knowledge-compiler` - Learning and logging decision patterns
+
+```mermaid
+graph LR
+    A["/think"] --> B["/plan"]
+    B --> C["/build"]
+    style A fill:#10b981
+```
+
+| After /think | Run | Purpose |
+|-------------|-----|---------|
+| Decision made | `/plan` | Create detailed implementation plan |
+| Need more research | `/think` | Explore deeper with different framing |
+| Complex task | `/autopilot` | Full autonomous coordination |
+
+**Handoff to /plan:**
+
+```markdown
+🧠 Decision: Option [X] approved — [name] ([score]/5).
+Run `/plan` to create implementation plan.
+```

package/.agent/workflows/validate.md

@@ -0,0 +1,289 @@
+---
+description: Comprehensive test automation suite — generate, execute, and analyze tests with Vitest/Playwright using AAA pattern, mutation testing, visual regression, and contract verification.
+skills: [test-architect, e2e-automation, code-review, context-engineering, problem-checker, knowledge-compiler]
+agents: [orchestrator, assessor, recovery, learner, test-engineer]
+---
+
+# /validate - Test Automation Suite
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Generate comprehensive tests, execute suites, and analyze coverage — supporting unit tests (Vitest/Jest), E2E (Playwright), mutation testing (Stryker), visual regression, and API contract testing. **Differs from `/inspect` (code review without execution) and `/optimize` (performance profiling) by actively generating, running, and verifying test suites with the AAA pattern.** Uses `test-architect` with `test-architect` for test generation and `e2e-automation` for browser testing.
+
+---
+
+## ?? Meta-Agents Integration
+
+| Phase | Agent | Action |
+| ----- | ----- | ------ |
+| **Pre-Flight** | `assessor` | Evaluate test targets and knowledge-compiler context |
+| **Execution** | `orchestrator` | Coordinate test generation, execution, and analysis |
+| **Safety** | `recovery` | Save state and recover from test execution failures |
+| **Post-Validate**| `learner` | Log test execution telemetry and failure patterns |
+
+```
+Flow:
+recovery.save(state) ? generate(tests) ? execute(suite)
+       ?
+analyze(coverage, mutations, visual, contracts)
+       ?
+learner.log(failure_patterns)
+```
+
+---
+
+## Sub-Commands
+
+| Command | Action |
+|---------|--------|
+| `/validate` | Run all tests |
+| `/validate [target]` | Generate tests for specific file/feature |
+| `/validate coverage` | Show coverage report |
+| `/validate watch` | Run in watch mode |
+| `/validate fix` | Auto-fix failing tests |
+| `/validate mutation` | Run mutation testing |
+| `/validate visual` | Run visual regression tests |
+| `/validate contract` | Run API contract tests |
+
+---
+
+## ?? MANDATORY: Test Automation Protocol
+
+### Phase 1: Pre-flight & knowledge-compiler Context
+
+> **Rule 0.5-K:** knowledge-compiler pattern check.
+
+1. Read `.agent/skills/knowledge-compiler/patterns/` for past failures before proceeding.
+2. Trigger `recovery` agent to run Checkpoint (`git commit -m "chore(checkpoint): pre-validate"`).
+
+### Phase 2: Test Generation
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | $ARGUMENTS (target file/feature or "all") |
+| **OUTPUT** | Test files following AAA pattern |
+| **AGENTS** | `test-architect`, `assessor` |
+| **SKILLS** | `test-architect`, `context-engineering` |
+
+// turbo — telemetry: phase-2-generate
+
+1. Detect test framework:
+
+| Project | Framework | Config |
+|---------|-----------|--------|
+| Next.js | Vitest | vitest.config.ts |
+| Node.js | Jest | jest.config.js |
+| React | Vitest + RTL | vitest.config.ts |
+| API | Supertest | jest.config.js |
+| Python | Pytest | pytest.ini |
+
+2. Analyze target and identify test cases:
+
+| Category | Example |
+|----------|---------|
+| Happy Path | Valid input ? expected output |
+| Empty Input | `""`, `[]`, `null`, `undefined` |
+| Boundary | Min, max, off-by-one |
+| Type Errors | Wrong type, missing property |
+| Async | Timeout, race condition, retry |
+| Security | XSS, injection, auth bypass |
+
+3. Generate tests using AAA pattern (Arrange, Act, Assert)
+
+### Phase 3: Test Execution
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Test files from Phase 2 |
+| **OUTPUT** | Test results: pass/fail counts, coverage report |
+| **AGENTS** | `test-architect`, `orchestrator` |
+| **SKILLS** | `test-architect`, `e2e-automation` |
+
+// turbo — telemetry: phase-3-execute
+
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:validate" TRACE_ID="$TRACE_ID" npm test -- --coverage
+```
+
+Coverage targets:
+
+| Metric | Target | Critical |
+|--------|--------|----------|
+| Statements | =80% | =60% |
+| Branches | =70% | =50% |
+| Mutation Score | =80% | =60% |
+
+### Phase 4: Advanced Testing
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Coverage report from Phase 3 |
+| **OUTPUT** | Mutation score, visual diffs, contract results |
+| **AGENTS** | `test-architect`, `orchestrator` |
+| **SKILLS** | `test-architect`, `e2e-automation` |
+
+// turbo — telemetry: phase-4-advanced
+
+Mutation testing (if requested):
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:validate" TRACE_ID="$TRACE_ID" npx stryker run
+```
+
+Visual regression (if requested):
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:validate" TRACE_ID="$TRACE_ID" npx playwright test --project=visual
+```
+
+Contract testing (if requested):
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:validate" TRACE_ID="$TRACE_ID" npx pact-verifier
+```
+
+### Phase 5: Results Analysis
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | All test results from Phases 3-4 |
+| **OUTPUT** | Test report with pass/fail, coverage, recommendations |
+| **AGENTS** | `test-architect`, `learner` |
+| **SKILLS** | `test-architect`, `problem-checker`, `knowledge-compiler` |
+
+// turbo — telemetry: phase-5-analyze
+
+1. Aggregate results across all test types
+2. Compare against coverage targets
+3. Generate actionable recommendations for failures
+
+---
+
+## ? MANDATORY: Problem Verification Before Completion
+
+> **CRITICAL:** This check MUST be performed before any `notify_user` or task completion.
+
+### Check @[current_problems]
+
+```
+1. Read @[current_problems] from IDE
+2. If errors/warnings > 0:
+   a. Auto-fix: imports, types, lint errors
+   b. Re-check @[current_problems]
+   c. If still > 0 ? STOP ? Notify user
+3. If count = 0 ? Proceed to completion
+```
+
+### Auto-Fixable
+
+| Type | Fix |
+|------|-----|
+| Missing import | Add import statement |
+| Unused variable | Remove or prefix `_` |
+| Type mismatch | Fix type annotation |
+| Lint errors | Run eslint --fix |
+
+> **Rule:** Never mark complete with errors in `@[current_problems]`.
+
+---
+
+## ?? Rollback & Recovery
+
+If tests hang or mutate files in unexpected ways:
+1. Trigger `recovery` meta-agent to run `git restore .` to revert mutated source files.
+2. Force kill hanging playwright browsers and Node.js testing processes.
+3. Review `learner` logs to identify flaky logic and update test assertions before re-running.
+
+---
+
+## Output Format
+
+```markdown
+## ?? Test Results
+
+### Summary
+? Passed: 42  ? Failed: 2  ?? Skipped: 1
+
+### Coverage
+
+| Metric | Current | Target | Status |
+|--------|---------|--------|--------|
+| Statements | 85% | 80% | ? |
+| Branches | 72% | 70% | ? |
+| Mutation Score | 82% | 80% | ? |
+| Visual Diffs | 0 | 0 | ? |
+| Contracts | 5/5 | 100% | ? |
+
+### Failures
+
+| Test | Error | Fix |
+|------|-------|-----|
+| user.test.ts:45 | Timeout | Increase wait |
+| cart.test.ts:12 | Assert | Update expected |
+
+### Next Steps
+
+- [ ] Fix 2 failing tests
+- [ ] Review visual baseline
+- [ ] Run `/launch` when all green
+```
+
+---
+
+## Examples
+
+```
+/validate
+/validate src/services/user.service.ts
+/validate coverage
+/validate mutation
+/validate visual
+```
+
+---
+
+## Key Principles
+
+- **Test behavior, not implementation** — assert on outcomes, not internals
+- **AAA pattern** — Arrange, Act, Assert for every test
+- **One assertion per test** — focused, readable tests
+- **Mock external deps** — isolate the unit under test
+- **Mutation testing** — verify test quality, not just coverage
+
+---
+
+## ?? Workflow Chain
+
+**Skills Loaded (6):**
+
+- `test-architect` - Test patterns, AAA, coverage strategy
+- `e2e-automation` - Playwright, visual testing, browser automation
+- `code-review` - Quality validation of test code
+- `context-engineering` - Codebase parsing and framework detection
+- `problem-checker` - Code problem verification
+- `knowledge-compiler` - Learning and logging test patterns
+
+```mermaid
+graph LR
+    A["/build"] --> B["/validate"]
+    B --> C["/launch"]
+    style B fill:#10b981
+```
+
+| After /validate | Run | Purpose |
+|----------------|-----|---------|
+| All tests pass | `/launch` | Deploy to production |
+| Tests fail | `/diagnose` | Root cause analysis |
+| Need review | `/inspect` | Code review |
+
+**Handoff to /launch:**
+
+```markdown
+?? Tests complete! Passed: [X], Failed: [Y]. Coverage: [Z]%.
+Run `/launch` to deploy or `/diagnose` for failures.
+```

package/.agentignore

@@ -0,0 +1,161 @@
+# Agent Skill Kit - Comprehensive Ignore Patterns v3.9.116
+# Updated: 2026-04 — Full TypeScript Migration
+
+# ============================================================
+# Dependencies & Package Managers
+# ============================================================
+node_modules/
+.pnpm-store/
+.yarn/
+!.yarn/releases
+!.yarn/plugins
+bower_components/
+jspm_packages/
+
+# ============================================================
+# Build & Distribution
+# ============================================================
+dist/
+build/
+out/
+.next/
+.nuxt/
+.output/
+.vercel/
+.netlify/
+.cache/
+*.tsbuildinfo
+
+# ============================================================
+# TypeScript Build Artifacts
+# ============================================================
+*.js.map
+*.d.ts.map
+
+# ============================================================
+# AI & Brain Artifacts (Agent Skill Kit specific)
+# ============================================================
+.gemini/
+brain/
+artifacts/
+.temp_ag_kit/
+
+# ============================================================
+# Version Control
+# ============================================================
+.git/
+.svn/
+.hg/
+
+# ============================================================
+# IDEs & Editors
+# ============================================================
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.classpath
+.settings/
+*.sublime-workspace
+*.code-workspace
+
+# ============================================================
+# Operating System
+# ============================================================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+Desktop.ini
+
+# ============================================================
+# Logs
+# ============================================================
+*.log
+logs/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# ============================================================
+# Testing & Coverage
+# ============================================================
+coverage/
+.nyc_output/
+*.lcov
+.coverage
+htmlcov/
+.pytest_cache/
+.vitest/
+
+# ============================================================
+# Environment & Secrets
+# ============================================================
+.env
+.env.local
+.env.*.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# ============================================================
+# Temporary & Cache
+# ============================================================
+tmp/
+temp/
+*.tmp
+.cache/
+.parcel-cache/
+.turbo/
+.webpack/
+
+# ============================================================
+# Package Lock Files
+# IMPORTANT: Keep lock files for reproducible builds (FAANG standard)
+# ============================================================
+# package-lock.json  # DO NOT IGNORE (keep for reproducible builds)
+# yarn.lock          # Only ignore if using npm
+# pnpm-lock.yaml     # Only ignore if using npm
+
+# ============================================================
+# Archives & Binaries
+# ============================================================
+*.zip
+*.tar.gz
+*.rar
+*.exe
+*.dmg
+*.app
+*.deb
+*.rpm
+
+# ============================================================
+# Python (Legacy Support)
+# ============================================================
+__pycache__/
+*.py[cod]
+*.so
+.Python
+venv/
+ENV/
+
+# ============================================================
+# Documentation Build
+# ============================================================
+docs/_build/
+docs/.vuepress/dist/
+
+# ============================================================
+# Misc
+# ============================================================
+*.backup
+*.bak
+*.orig
+.vagrant/