@namch/agent-assistant 1.0.4 → 1.1.0

package/rules/QUICK-REFERENCE.md

@@ -1,204 +0,0 @@
-# 📚 QUICK REFERENCE
-
-> **PURPOSE**: Fast lookup tables for commands, agents, and dependencies
-
----
-
-## COMMAND ROUTING TABLE
-
-| User Input          | Resolves To        | Workflow File            |
-| ------------------- | ------------------ | ------------------------ |
-| `/cook implement X` | `/cook:auto`       | `~/.{TOOL}/skills/agent-assistant/commands/cook.md`       |
-| `/cook:fast X`      | `/cook:fast`       | `~/.{TOOL}/skills/agent-assistant/commands/cook/fast.md`  |
-| `/cook:hard X`      | `/cook:hard`       | `~/.{TOOL}/skills/agent-assistant/commands/cook/hard.md`  |
-| `/fix error X`      | `/fix:auto`        | `~/.{TOOL}/skills/agent-assistant/commands/fix.md`        |
-| `/fix:fast X`       | `/fix:fast`        | `~/.{TOOL}/skills/agent-assistant/commands/fix/fast.md`   |
-| `/fix:hard X`       | `/fix:hard`        | `~/.{TOOL}/skills/agent-assistant/commands/fix/hard.md`   |
-| `/debug X`          | `/debug:auto`      | `~/.{TOOL}/skills/agent-assistant/commands/debug.md`      |
-| `/plan X`           | `/plan:auto`       | `~/.{TOOL}/skills/agent-assistant/commands/plan.md`       |
-| `/test X`           | `/test:auto`       | `~/.{TOOL}/skills/agent-assistant/commands/test.md`       |
-| `/review X`         | `/review:auto`     | `~/.{TOOL}/skills/agent-assistant/commands/review.md`     |
-| `/docs X`           | `/docs:auto`       | `~/.{TOOL}/skills/agent-assistant/commands/docs.md`       |
-| `/design X`         | `/design:auto`     | `~/.{TOOL}/skills/agent-assistant/commands/design.md`     |
-| `/deploy X`         | `/deploy:auto`     | `~/.{TOOL}/skills/agent-assistant/commands/deploy.md`     |
-| `/brainstorm X`     | `/brainstorm:auto` | `~/.{TOOL}/skills/agent-assistant/commands/brainstorm.md` |
-| `/ask X`            | `/ask:auto`        | `~/.{TOOL}/skills/agent-assistant/commands/ask.md`        |
-| `/code X`           | `/code:auto`       | `~/.{TOOL}/skills/agent-assistant/commands/code.md`       |
-| `/report X`         | `/report:auto`     | `~/.{TOOL}/skills/agent-assistant/commands/report.md`     |
-| `/report:fast X`    | `/report:fast`     | `~/.{TOOL}/skills/agent-assistant/commands/report/fast.md` |
-| `/report:hard X`    | `/report:hard`     | `~/.{TOOL}/skills/agent-assistant/commands/report/hard.md`  |
-| `/report:focus X`   | `/report:focus`    | `~/.{TOOL}/skills/agent-assistant/commands/report/focus.md` |
-
----
-
-## AGENT LOOKUP TABLE
-
-| Domain        | Agent                  | File                             | Category    |
-| ------------- | ---------------------- | -------------------------------- | ----------- |
-| Architecture  | `tech-lead`            | `~/.{TOOL}/skills/agent-assistant/agents/tech-lead.md`            | meta        |
-| Planning      | `planner`              | `~/.{TOOL}/skills/agent-assistant/agents/planner.md`              | meta        |
-| Backend       | `backend-engineer`     | `~/.{TOOL}/skills/agent-assistant/agents/backend-engineer.md`     | engineering |
-| Frontend      | `frontend-engineer`    | `~/.{TOOL}/skills/agent-assistant/agents/frontend-engineer.md`    | engineering |
-| Database      | `database-architect`   | `~/.{TOOL}/skills/agent-assistant/agents/database-architect.md`   | engineering |
-| Mobile        | `mobile-engineer`      | `~/.{TOOL}/skills/agent-assistant/agents/mobile-engineer.md`      | engineering |
-| Games         | `game-engineer`        | `~/.{TOOL}/skills/agent-assistant/agents/game-engineer.md`        | engineering |
-| Testing       | `tester`               | `~/.{TOOL}/skills/agent-assistant/agents/tester.md`               | validation  |
-| Review        | `reviewer`             | `~/.{TOOL}/skills/agent-assistant/agents/reviewer.md`             | validation  |
-| Security      | `security-engineer`    | `~/.{TOOL}/skills/agent-assistant/agents/security-engineer.md`    | validation  |
-| Performance   | `performance-engineer` | `~/.{TOOL}/skills/agent-assistant/agents/performance-engineer.md` | validation  |
-| Debugging     | `debugger`             | `~/.{TOOL}/skills/agent-assistant/agents/debugger.md`             | validation  |
-| Research      | `researcher`           | `~/.{TOOL}/skills/agent-assistant/agents/researcher.md`           | research    |
-| Codebase      | `scouter`              | `~/.{TOOL}/skills/agent-assistant/agents/scouter.md`              | research    |
-| Brainstorm    | `brainstormer`         | `~/.{TOOL}/skills/agent-assistant/agents/brainstormer.md`         | research    |
-| Design        | `designer`             | `~/.{TOOL}/skills/agent-assistant/agents/designer.md`             | research    |
-| Documentation | `docs-manager`         | `~/.{TOOL}/skills/agent-assistant/agents/docs-manager.md`         | support     |
-| DevOps        | `devops-engineer`      | `~/.{TOOL}/skills/agent-assistant/agents/devops-engineer.md`      | support     |
-| Business      | `business-analyst`     | `~/.{TOOL}/skills/agent-assistant/agents/business-analyst.md`     | support     |
-| Project       | `project-manager`      | `~/.{TOOL}/skills/agent-assistant/agents/project-manager.md`      | support     |
-| Reporting     | `reporter`             | `~/.{TOOL}/skills/agent-assistant/agents/reporter.md`             | support     |
-
----
-
-## TASK → AGENT MAPPING
-
-| Task Type         | Primary Agent          | Backup              |
-| ----------------- | ---------------------- | ------------------- |
-| API endpoints     | `backend-engineer`     | —                   |
-| UI components     | `frontend-engineer`    | `designer`          |
-| Database schema   | `database-architect`   | `backend-engineer`  |
-| Security audit    | `security-engineer`    | —                   |
-| Performance       | `performance-engineer` | —                   |
-| Testing           | `tester`               | —                   |
-| Code review       | `reviewer`             | —                   |
-| External research | `researcher`           | `scouter`           |
-| Codebase analysis | `scouter`              | `researcher`        |
-| Documentation     | `docs-manager`         | —                   |
-| Requirements      | `brainstormer`         | `business-analyst`  |
-| Planning          | `planner`              | —                   |
-| Visual design     | `designer`             | `frontend-engineer` |
-| Orchestration     | `tech-lead`            | —                   |
-| Bug investigation | `debugger`             | `tester`            |
-| Deployment        | `devops-engineer`      | —                   |
-| Git operations    | `devops-engineer`      | —                   |
-| AI/ML agents      | `backend-engineer`     | `tech-lead`         |
-| Penetration test  | `security-engineer`    | —                   |
-| Workflow automation | `devops-engineer`    | `backend-engineer`  |
-| Reports, status, documentation updates | `reporter` | `docs-manager` |
-
----
-
-## PHASE DEPENDENCY MATRIX
-
-| Current Phase      | Required Input            | Produces                  |
-| ------------------ | ------------------------- | ------------------------- |
-| Brainstorm         | User Request              | `BRAINSTORM-{feature}.md` |
-| Research           | Request + Brainstorm      | `RESEARCH-{feature}.md`   |
-| Scout              | User Request              | `SCOUT-{feature}.md`      |
-| Design             | Brainstorm + Scout        | `DESIGN-{feature}.md`     |
-| **Planning**       | Scout + Research + Design | `PLAN-{feature}.md`       |
-| **Implementation** | **PLAN (MANDATORY)**      | Code changes              |
-| **Testing**        | PLAN + Code               | Test results              |
-| **Review**         | PLAN + Code + Tests       | Review verdict            |
-
----
-
-## DELIVERABLE PATHS
-
-```yaml
-brainstormer: "./reports/brainstorms/BRAINSTORM-{feature}.md"
-researcher: "./reports/researchers/RESEARCH-{feature}.md"
-scouter: "./reports/scouts/SCOUT-{feature}.md"
-designer: "./reports/designs/DESIGN-{feature}.md"
-planner: "./reports/plans/PLAN-{feature}.md"
-reporter: "./reports/ (create/update per task)"
-```
-
----
-
-## DOCUMENTATION PATHS (from /docs:core)
-
-When `./documents/` exists, agents **read these** for project context:
-
-| File                        | Purpose                          |
-| --------------------------- | -------------------------------- |
-| `./documents/knowledge-overview.md`     | Project purpose, goals, tech stack   |
-| `./documents/knowledge-architecture.md` | System design, components, patterns  |
-| `./documents/knowledge-domain.md`       | Data models, API contracts, entities |
-| `./documents/knowledge-source-base.md`  | Directory structure, entry points    |
-| `./documents/knowledge-standards.md`    | Code style, naming, conventions      |
-
-Business: `./documents/business/*.md`. Audit: `./documents/audit/*.md`.
-
----
-
-## BLOCKING RULES
-
-```yaml
-implementation:
-  IF plan_missing:
-    action: "BLOCK → Route to planner first"
-    message: "⛔ Cannot implement without plan"
-
-testing:
-  IF plan_exists:
-    action: "MUST verify against plan checkpoints"
-
-review:
-  IF plan_exists:
-    action: "MUST verify code matches plan intent"
-```
-
----
-
-## TIERED EXECUTION QUICK CHECK
-
-```yaml
-TIER_1_SUBAGENT:
-  priority: "MANDATORY when tool exists"
-  context: "ISOLATED"
-  use_when: "runSubagent detected"
-
-TIER_2_EMBODY:
-  priority: "FALLBACK only"
-  context: "SHARED"
-  use_when: "Tool missing OR system error"
-
-decision: 1. Check runSubagent exists
-  2. IF yes → MUST use TIER 1
-  3. IF error → Fall back TIER 2
-  4. IF no tool → Use TIER 2
-
-anti_lazy: ❌ TIER 2 when TIER 1 available
-  ❌ "Complexity" as TIER 2 reason
-  ❌ Skip Tool Discovery
-```
-
----
-
-## SELF-VERIFICATION
-
-```
-□ Did I delegate (not execute)?
-□ Did I follow workflow order?
-□ Did I respond in user's language?
-□ Did I verify exit criteria?
-□ Did I use correct tier?
-```
-
----
-
-## NATURAL LANGUAGE DETECTION
-
-| User Says                                      | Detect As     |
-| ---------------------------------------------- | ------------- |
-| "implement", "build", "create", "add feature"  | `/cook`       |
-| "fix", "bug", "error", "broken", "not working" | `/fix`        |
-| "plan", "how should", "approach", "strategy"   | `/plan`       |
-| "debug", "investigate", "why is", "trace"      | `/debug`      |
-| "test", "write tests", "coverage"              | `/test`       |
-| "review", "check code", "PR"                   | `/review`     |
-| "document", "readme", "api docs"               | `/docs`       |
-| "design", "UI", "UX", "mockup"                 | `/design`     |
-| "deploy", "release", "production"              | `/deploy`     |
-| "brainstorm", "ideas", "explore"               | `/brainstorm` |
-| "report", "status report", "summary", "documentation update" | `/report` |

package/rules/SKILL-DISCOVERY.md

@@ -1,370 +0,0 @@
-# Skill Discovery Protocol
-
-> **Purpose**: Runtime resolution of skills for agents using the Matrix Metadata system.
-> **Source**: `~/.{TOOL}/skills/agent-assistant/matrix-skills/` (distributed by domain)
-> **Total Skills**: 310 skills across 19 domains
-
----
-
-## Overview
-
-The Skill Discovery Protocol replaces hardcoded skill lists in agent files with dynamic resolution from a distributed matrix organized by domain. When an agent is activated, this protocol determines which skills to inject based on the agent's declared profile and inherited domains.
-
-### Matrix Structure
-
-```
-matrix-skills/
-├── _index.yaml          # Registry, agent profiles, resolution rules
-├── backend.yaml         # 32 skills
-├── frontend.yaml        # 22 skills
-├── architecture.yaml    # 9 skills
-├── quality.yaml         # 21 skills
-├── security.yaml        # 35 skills
-├── design.yaml          # 10 skills
-├── planning.yaml        # 12 skills
-├── devops.yaml          # 22 skills
-├── data.yaml            # 7 skills
-├── performance.yaml     # 1 skill
-├── research.yaml        # 11 skills
-├── mobile.yaml          # 8 skills
-├── gaming.yaml          # 3 skills
-├── management.yaml      # 4 skills
-├── ai-ml.yaml           # 40 skills
-├── cloud.yaml           # 11 skills
-├── languages.yaml       # 17 skills
-├── tools.yaml           # 41 skills
-└── mcp.yaml             # 8 skills
-```
-
----
-
-## Resolution Algorithm
-
-### Step 1: Parse Agent Profile
-
-Extract from agent frontmatter:
-```yaml
-profile: "{domain}:{category}"
-```
-
-Example: `backend:execution` → domain=backend, category=execution
-
-### Step 2: Load Domain Files
-
-From `_index.yaml`, find agent's inherited domains:
-```yaml
-agent_profiles:
-  backend-engineer:
-    profile: "backend:execution"
-    inherit_from: ["backend", "architecture", "quality", "data", "languages"]
-```
-
-Load each domain file: `backend.yaml`, `architecture.yaml`, `quality.yaml`, etc.
-
-### Step 3: Resolve Skills
-
-Execute in order of precedence:
-
-```
-1. DIRECT AGENT MATCH
-   → Find skills where relevance_mapping.agents contains agent_id
-   → Example: skill.relevance_mapping.agents: [backend-engineer]
-   
-2. PROFILE MATCH  
-   → Find skills where relevance_mapping.profiles contains:
-     - Exact match: "backend:execution"
-     - Domain wildcard: "backend:*"
-     - Category wildcard: "*:execution"
-     - Universal: "*"
-   
-3. DOMAIN INHERITANCE
-   → From agent_profiles.{agent_id}.inherit_from
-   → Include skills from inherited domains
-```
-
-### Step 4: Apply Priority Filter
-
-```yaml
-thresholds:
-  critical_priority: 9    # Always include (mandatory)
-  core_priority: 7        # Standard include
-  minimum_priority: 5     # Include if context matches
-```
-
-### Step 5: Apply Overrides
-
-If agent declares `skill_overrides`:
-```yaml
-skill_overrides:
-  include: [additional-skill]   # Force add
-  exclude: [removed-skill]      # Force remove
-  priority_threshold: 8         # Override minimum
-```
-
-### Step 6: Return Skill Set
-
-Sorted by priority_score descending.
-
----
-
-## Resolution Examples
-
-### Example 1: Backend Engineer
-
-**Input:**
-```yaml
-name: backend-engineer
-profile: "backend:execution"
-```
-
-**Domain Files Loaded:**
-- `backend.yaml`
-- `architecture.yaml`
-- `quality.yaml`
-- `data.yaml`
-- `languages.yaml`
-
-**Resolution:**
-
-| Step | Source File | Skills Found |
-|------|-------------|--------------|
-| 1 | backend.yaml | api-patterns, backend-development, microservices-architect, backend-dev-guidelines, software-architecture, bun-development, inngest, trigger-dev, stripe-integration |
-| 2 | architecture.yaml | architecture, clean-code |
-| 3 | data.yaml | database-design, sql-pro, prisma-expert, nosql-expert, neon-postgres |
-| 4 | languages.yaml | typescript-expert, python-patterns, javascript-mastery |
-| 5 | ai-ml.yaml | ai-agents-architect, autonomous-agents, llm-app-patterns, rag-engineer, prompt-engineering, crewai, langgraph |
-
-**Output (sorted by priority):**
-```
-architecture (10)
-ai-agents-architect (9)
-api-patterns (9)
-database-design (9)
-clean-code (9)
-backend-development (8)
-backend-dev-guidelines (8)
-software-architecture (8)
-llm-app-patterns (8)
-rag-engineer (8)
-typescript-expert (8)
-microservices-architect (8)
-...
-```
-
-### Example 2: Designer with Override
-
-**Input:**
-```yaml
-name: designer
-profile: "design:creative"
-skill_overrides:
-  exclude: [ux-researcher-designer]
-  priority_threshold: 8
-```
-
-**Domain Files Loaded:**
-- `design.yaml`
-- `frontend.yaml`
-
-**Resolution:**
-
-| Step | Action |
-|------|--------|
-| 1 | Load skills from design.yaml |
-| 2 | Load skills from frontend.yaml |
-| 3 | Remove ux-researcher-designer (excluded) |
-| 4 | Filter priority >= 8 only |
-
-**Output:**
-```
-aesthetic (9)
-ui-ux-pro-max (9)
-frontend-design (9)
-tailwind-patterns (8)
-ui-design-system (8)
-ui-styling (8)
-```
-
----
-
-## Wildcard Patterns
-
-| Pattern | Meaning | Example Match |
-|---------|---------|---------------|
-| `backend:execution` | Exact match | backend:execution only |
-| `backend:*` | Any backend category | backend:execution, backend:analysis |
-| `*:execution` | Any domain, execution category | backend:execution, frontend:execution |
-| `*:orchestration` | Any orchestrator | architecture:orchestration, management:orchestration |
-| `*` | Universal (all agents) | Any agent |
-
----
-
-## Domain Inheritance
-
-Defined in `_index.yaml`:
-
-```yaml
-agent_profiles:
-  backend-engineer:
-    profile: "backend:execution"
-    inherit_from: ["backend", "architecture", "quality", "data", "languages"]
-    primary_domain: "backend"
-```
-
-When resolving skills for `backend-engineer`:
-1. Load `backend.yaml` → filter matching skills
-2. Load `architecture.yaml` → filter matching skills
-3. Load `quality.yaml` → filter matching skills
-4. Load `data.yaml` → filter matching skills
-5. Load `languages.yaml` → filter matching skills
-
-This enables cross-domain skill sharing without explicit agent declarations.
-
----
-
-## Agent Files: Profile + Domains Only
-
-Agent files **do not** list key skills or domain-file tables. Each agent's Skills section contains only:
-
-```markdown
-## ⚡ Skills
-
-> **MATRIX DISCOVERY**: Skills auto-injected from domain files in `~/.{TOOL}/skills/agent-assistant/matrix-skills/`
-> Profile: `{domain}:{category}` | Domains: `{inherit_from from _index.yaml}`
-```
-
-AI tools resolve skills by reading `~/.{TOOL}/skills/agent-assistant/matrix-skills/_index.yaml` → `agent_profiles.{agent}.inherit_from`, then loading the listed domain files and injecting skills via `relevance_mapping`. **When adding new skills, update only the skill folder and the corresponding matrix-skills domain file; no agent file changes are required.**
-
----
-
-## Adding New Skills
-
-### Workflow
-
-1. **Create skill folder:**
-   ```
-   ~/.{TOOL}/skills/{skill-id}/
-   └── SKILL.md
-   ```
-
-2. **Add to appropriate domain file:**
-   ```yaml
-   # matrix-skills/{domain}.yaml
-   - skill_id: new-skill
-     category: {core|expert|specialized|utility}
-     priority_score: {1-10}
-     relevance_mapping:
-       agents: [{agent1}, {agent2}]
-       profiles: ["{domain}:{category}"]
-     description: "Brief AI-recognizable description"
-   ```
-
-3. **Update domain skill_count in _index.yaml** (optional but recommended)
-
-4. **Do not edit agent files** — skills are resolved from matrix-skills by Profile and Domains only.
-
-5. **Verify resolution:**
-   - Skill appears in target agent's resolved set
-   - Priority ordering is correct
-   - No conflicts with existing skills
-
-### Priority Guidelines
-
-| Score | Category | Usage |
-|-------|----------|-------|
-| 10 | Critical | Always required, never skip |
-| 9 | Core | Standard for domain |
-| 8 | Expert | Specialized but common |
-| 7 | Core | Useful in most contexts |
-| 6 | Utility | Context-dependent |
-| 5 | Optional | Nice to have |
-| 1-4 | Rare | Edge cases only |
-
----
-
-## Validation Rules
-
-### Pre-Deployment Checks
-
-1. **Skill existence:**
-   - Every `skill_id` in domain files has corresponding `~/.{TOOL}/skills/{skill_id}/SKILL.md`
-
-2. **Agent coverage:**
-   - Every agent has at least one matching skill
-   - No orphan agents with empty skill sets
-
-3. **Profile validity:**
-   - All profiles reference valid domains
-   - Domain inheritance forms no cycles
-
-4. **Priority consistency:**
-   - Critical skills (9-10) present for all core agents
-   - No domain without core skills (7+)
-
-### Runtime Validation
-
-```
-IF resolved_skills.length == 0:
-  → ERROR: No skills found for agent
-  → FALLBACK: Use agent's skill_overrides.include if present
-  
-IF critical_skill.missing:
-  → WARNING: Agent missing critical skill
-  → CONTINUE: May degrade performance
-```
-
----
-
-## Orchestrator Integration
-
-When orchestrator activates an agent:
-
-```
-1. READ agent file → extract profile
-2. LOAD _index.yaml → find inherited domains
-3. LOAD domain files → collect matching skills
-4. APPLY filters and overrides
-5. INJECT resolved skills into agent context
-6. EXECUTE agent with full skill set
-```
-
-The orchestrator never needs to know individual skills—it only needs the agent's profile.
-
----
-
-## Performance Considerations
-
-### Caching Strategy
-
-- `_index.yaml` loaded once at orchestrator startup
-- Domain files loaded on-demand per agent
-- Skill resolution is cached per agent_id
-- Cache invalidation on any matrix file change
-
-### Complexity
-
-- Resolution: O(D × S) where D=inherited domains, S=skills per domain
-- Typical resolution: < 1ms
-- Total Matrix size: ~310 skills = ~25KB across all YAML files
-
----
-
-## Troubleshooting
-
-| Symptom | Cause | Solution |
-|---------|-------|----------|
-| Agent has no skills | Profile not in _index.yaml | Add to agent_profiles |
-| Wrong skills injected | Incorrect relevance_mapping | Fix mapping in domain file |
-| Skill not appearing | Priority below threshold | Increase priority_score |
-| Too many skills | Broad inheritance | Use skill_overrides.exclude |
-| Skill conflict | Duplicate skill_id | Ensure unique IDs across all domain files |
-| Domain file not loaded | Not in inherit_from | Add domain to agent's inherit_from |
-
----
-
-## References
-
-- **Matrix Index**: `~/.{TOOL}/skills/agent-assistant/matrix-skills/_index.yaml`
-- **Domain files**: `~/.{TOOL}/skills/agent-assistant/matrix-skills/{domain}.yaml`
-- **Agent template**: `AGENT-TEMPLATE.md`
-- **Skills directory**: `~/.{TOOL}/skills/`