@namch/agent-assistant 1.0.3 → 1.1.0

package/rules/PHASES.md

@@ -0,0 +1,156 @@
+# 🎭 PHASES
+
+> **LOAD**: When running workflow phases | **PURPOSE**: Phase execution protocol
+
+---
+
+## REQUIREMENTS INTAKE (Before Phase 1)
+
+### Parse ALL requirements into Registry
+
+```markdown
+### 📋 Requirements Registry
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| R1 | {extracted} | {H/M/L} | ⏳ |
+| R2 | {extracted} | {H/M/L} | ⏳ |
+```
+
+**Rule**: 100% fidelity — extract EVERY requirement, no assumptions, no omissions.
+
+---
+
+## PHASE OUTPUT FORMAT (SINGLE SOURCE OF TRUTH)
+
+**⛔ This is the ONLY place phase output is defined. All other files reference here.**
+
+### Emit progressively as you go:
+
+```markdown
+## 🎭 Phase {N}: {name}
+
+### Sub-agent: `{agent}` — {role}     ← TIER 1 only
+### Embodying: `{agent}` — {role}     ← TIER 2 only
+
+{agent work / summary}
+
+### Exit Criteria
+- [x] {criterion_1}
+- [x] {criterion_2}
+
+### ✅ `{agent}` complete
+**Deliverable**: {summary}
+```
+
+**Rules**:
+- TIER 1 → "Sub-agent" line | TIER 2 → "Embodying" line (never both)
+- Emit phase start **before** work, exit criteria **after**
+- Continue to next phase immediately (same reply)
+
+---
+
+## PHASE EXECUTION RULES
+
+### One Phase at a Time (No Batching)
+
+```
+FOR Phase N:
+  1. EMIT "## 🎭 Phase N: {name}"
+  2. LOAD only what Phase N needs (agent file, prior deliverables)
+  3. DELEGATE via TIERED EXECUTION
+  4. EMIT exit criteria + completion
+  5. Write deliverable file if required
+  6. CONTINUE to Phase N+1 (do not stop)
+```
+
+**⛔ Forbidden**: Loading agents for Phase 2, 3, ... while in Phase 1
+
+### Prior Deliverables as Constraints
+
+```
+BEFORE Phase N:
+  1. CHECK if prior deliverable exists
+  2. IF exists:
+     → READ completely
+     → LOCK as IMMUTABLE constraint (L8)
+     → DO NOT modify prior decisions
+  3. IF missing but required:
+     → HALT with notice
+     → Create first via appropriate agent
+     → Then resume
+```
+
+### Allowed Loads Per Phase
+
+```
+⛔ FORBIDDEN: Loading Phase 2's agents while in Phase 1
+✅ ALLOWED: Load only what current phase needs
+✅ ALLOWED: Read prior deliverables as input
+```
+
+---
+
+## EXIT CRITERIA VERIFICATION
+
+Before moving to next phase, verify:
+
+```
+□ Deliverable produced
+□ Output matches agent's format
+□ All exit criteria met
+□ No scope creep
+```
+
+---
+
+## WORKFLOW COMPLETION
+
+After last phase:
+
+```markdown
+## ✅ Workflow Complete
+
+### � User Request Verification
+> {Quote user's original request from plan header}
+
+### 📋 Acceptance Criteria Verification
+| ID | Criterion | Status | Evidence |
+|----|-----------|--------|----------|
+| AC1 | {criterion from plan} | ✅ | {file:line or test} |
+| AC2 | {criterion from plan} | ✅ | {proof of implementation} |
+
+### 📋 Requirements Verification  
+| ID | Requirement | Status | Evidence |
+|----|-------------|--------|----------|
+| R1 | {req} | ✅ | {file:line or deliverable} |
+| R2 | {req} | ✅ | {proof of implementation} |
+
+### 📦 Deliverables
+- {list of outputs with paths}
+
+### ⚠️ Notes
+{any warnings, limitations, or follow-ups}
+```
+
+**Rules**: 
+- Trace EVERY acceptance criterion to evidence
+- Verify against ORIGINAL user request (not interpreted version)
+- No silent drops
+
+---
+
+## SKILLS ANALYSIS (MANDATORY OUTPUT)
+
+**⛔ You MUST output skills decision for every phase delegation.**
+
+### Simple task:
+```
+🎯 Skills Analysis: Simple → Skipping (base knowledge sufficient)
+```
+
+### Complex task:
+```
+🎯 Skills Analysis: Complex → Using `skill1`, `skill2`
+```
+
+**🚫 Silent skipping is FORBIDDEN**

package/rules/REFERENCE.md

@@ -0,0 +1,179 @@
+# 📚 REFERENCE
+
+> **PURPOSE**: Fast lookup tables
+
+---
+
+## COMMAND TABLE
+
+| Command | Router | Variants |
+|---------|--------|----------|
+| `/cook` | `cook.md` | `fast`, `hard`, `focus` |
+| `/fix` | `fix.md` | `fast`, `hard`, `focus` |
+| `/plan` | `plan.md` | `fast`, `hard`, `focus` |
+| `/debug` | `debug.md` | `fast`, `hard`, `focus` |
+| `/test` | `test.md` | `fast`, `hard`, `focus` |
+| `/review` | `review.md` | `fast`, `hard` |
+| `/docs` | `docs.md` | `core`, `business`, `audit` |
+| `/design` | `design.md` | `fast`, `hard`, `focus` |
+| `/deploy` | `deploy.md` | `check`, `preview`, `production`, `rollback` |
+| `/report` | `report.md` | `fast`, `hard`, `focus` |
+| `/brainstorm` | `brainstorm.md` | `fast`, `hard` |
+| `/ask` | `ask.md` | `fast`, `hard` |
+| `/code` | `code.md` | `fast`, `hard`, `focus` |
+
+---
+
+## AGENT TABLE
+
+| Agent | Category | Primary Tasks |
+|-------|----------|---------------|
+| `tech-lead` | meta | Architecture, orchestration |
+| `planner` | meta | Task breakdown, roadmap |
+| `backend-engineer` | execution | APIs, services, logic |
+| `frontend-engineer` | execution | UI, components, styling |
+| `database-architect` | execution | Schema, queries, migrations |
+| `mobile-engineer` | execution | iOS, Android, React Native |
+| `game-engineer` | execution | Game logic, Unity, Unreal |
+| `tester` | validation | Unit, integration, E2E tests |
+| `reviewer` | validation | Code review, PR feedback |
+| `security-engineer` | validation | Security audit, pentesting |
+| `performance-engineer` | validation | Profiling, optimization |
+| `debugger` | validation | Bug investigation |
+| `researcher` | research | External research |
+| `scouter` | research | Codebase analysis |
+| `brainstormer` | research | Ideas, requirements |
+| `designer` | research | UI/UX design |
+| `docs-manager` | support | Documentation |
+| `devops-engineer` | support | CI/CD, deployment |
+| `business-analyst` | support | Business requirements |
+| `project-manager` | support | Project coordination |
+| `reporter` | support | Reports, summaries |
+
+---
+
+## NATURAL LANGUAGE DETECTION
+
+| User Says | Detect As |
+|-----------|-----------|
+| implement, build, create, add | `/cook` |
+| fix, bug, error, broken | `/fix` |
+| plan, how should, strategy | `/plan` |
+| debug, investigate, why | `/debug` |
+| test, coverage | `/test` |
+| review, PR, check code | `/review` |
+| document, readme | `/docs` |
+| design, UI, UX | `/design` |
+| deploy, release | `/deploy` |
+| report, status, summary | `/report` |
+
+---
+
+## 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/
+```
+
+---
+
+## DOCUMENTATION PATHS (from /docs:core)
+
+```yaml
+overview:     ./documents/knowledge-overview.md
+architecture: ./documents/knowledge-architecture.md
+domain:       ./documents/knowledge-domain.md
+source-base:  ./documents/knowledge-source-base.md
+standards:    ./documents/knowledge-standards.md
+```
+
+---
+
+## RULES FILES
+
+| File | Purpose | Load When |
+|------|---------|-----------|
+| `CORE.md` | Entry point, identity, routing | **Always** |
+| `PHASES.md` | Phase execution, output format | Running phases |
+| `AGENTS.md` | Agent handling, tiered execution | Delegating |
+| `SKILLS.md` | Skill resolution (HSOL) | Skill lookups |
+| `ERRORS.md` | Error recovery | Errors occur |
+| `REFERENCE.md` | Lookup tables | Quick lookups |
+
+---
+
+## SELF-VERIFICATION CHECKLIST
+
+```
+Before every response:
+□ Am I DELEGATING (not implementing)?
+□ Am I following WORKFLOW ORDER?
+□ Am I responding in USER'S LANGUAGE?
+□ Did I attempt TIER 1 before TIER 2?
+□ Did I output Skills Analysis?
+□ Are prior deliverables treated as immutable?
+□ Did I trace requirements to evidence?
+```
+
+---
+
+## TIER DECISION QUICK CHECK
+
+```
+🔍 Tool Discovery: Does runSubagent exist?
+  └─ YES → TIER 1 (MANDATORY)
+  └─ NO  → TIER 2 (EMBODY)
+
+⚠️ If you're about to use TIER 2 when TIER 1 exists:
+  → STOP
+  → Log: "LAZY FALLBACK DETECTED"
+  → Use TIER 1 instead
+```
+
+---
+
+## PHASE DEPENDENCY
+
+| Phase | Requires | Produces |
+|-------|----------|----------|
+| Brainstorm | Request | `BRAINSTORM-*.md` |
+| Research | Request | `RESEARCH-*.md` |
+| Scout | Request | `SCOUT-*.md` |
+| Design | Brainstorm + Scout | `DESIGN-*.md` |
+| Plan | Research + Scout | `PLAN-*.md` |
+| Implement | **PLAN (mandatory)** | Code |
+| Test | Code | Test results |
+| Review | Code + Tests | Review verdict |
+
+### Blocking Rules
+
+```
+⛔ Implementation REQUIRES plan first
+⛔ Design REQUIRES brainstorm/scout first
+⛔ Test REQUIRES code to exist
+⛔ Review REQUIRES code + tests
+
+✅ IF missing prerequisite → CREATE first, THEN proceed
+```
+
+---
+
+## ORCHESTRATION LAWS (Quick Reference)
+
+| # | Law | One-liner |
+|---|-----|----------|
+| L1 | Single Truth | Entry file → CORE → rest on-demand |
+| L2 | Requirement Integrity | 100% fidelity, zero loss |
+| L3 | Explicit Loading | State what you loaded |
+| L4 | Deep Embodiment | Follow agent's full protocol |
+| L5 | Sequential Execution | Phase N before N+1 |
+| L6 | Language Compliance | User's lang; files in English |
+| L7 | Recursive Delegation | Meta agents never implement |
+| L8 | Stateful Handoff | Prior deliverables = locked |
+| L9 | Constraint Propagation | Scout→Planner→Impl chain |
+| L10 | Deliverable Integrity | Agent files define format |

package/rules/SKILLS.md

@@ -0,0 +1,167 @@
+# 🎯 SKILLS
+
+> **LOAD**: When skill resolution needed | **PURPOSE**: Hybrid Skill Orchestration Layer (HSOL)
+
+---
+
+## OVERVIEW
+
+Skills = Domain knowledge modules in `{SKILLS_PATH}/`.
+
+**Two sources**:
+1. **Matrix Skills** — Pre-curated in `matrix-skills/*.yaml` (fast, trusted)
+2. **Dynamic Skills** — Community skills via `find-skills` (on-demand)
+
+---
+
+## RESOLUTION ALGORITHM
+
+```
+1. PARSE agent profile from frontmatter
+2. LOAD inherited domains from matrix-skills/_index.yaml
+3. FILTER skills by relevance_mapping
+4. APPLY priority thresholds (critical≥9, core≥7, minimum≥5)
+5. CALCULATE fitness scores
+6. RETURN sorted skill set
+```
+
+### Fitness Calculation
+
+```
+fitness = 0.35 × SEMANTIC_MATCH
+        + 0.25 × SPECIFICITY
+        + 0.25 × TRUST_LEVEL
+        + 0.15 × RECENCY
+
+Matrix skills: trust = 1.0 (always trusted)
+Dynamic skills: trust = 0.3 - 1.0 (based on history)
+```
+
+---
+
+## SKILL DECISION FLOW
+
+### By Variant
+
+| Variant | Discovery |
+|---------|-----------|
+| `fast` | **Skip** — use matrix only |
+| `hard`, `focus` | Check matrix fitness, may trigger discovery |
+
+### By Matrix Fitness
+
+| Fitness | Action |
+|---------|--------|
+| ≥ 0.8 | Execute with matrix (skip discovery) |
+| 0.75-0.8 | **Async**: Execute with matrix, surface recommendation later |
+| < 0.75 | **Blocking**: Wait for discovery → install → execute with new skill |
+
+---
+
+## TRUST PROGRESSION LIFECYCLE
+
+```
+NEW (0.3)        ──▶  EVALUATING (0.5)  ──▶  VALIDATED (0.7)  ──▶  PROMOTED (1.0)
+    │                    │                     │                     │
+    └─ 3 successful      └─ 10 successful      └─ Auto-promote       └─ Added to
+       executions           executions           to matrix              matrix-skills
+```
+
+**Promotion criteria**:
+- execution_count ≥ 10
+- success_rate ≥ 0.85
+- last_used_within_days ≤ 30
+- no_security_flags: true
+
+---
+
+## DYNAMIC DISCOVERY (find-skills)
+
+### Trigger
+
+```bash
+npx skills find "{keywords}"
+```
+
+### Install (always use -g -y for current tool)
+
+```bash
+npx skills add {owner/repo@skill} -g -y
+```
+
+### When to confirm
+
+- **Confirm required**: Low trust (new skill) + needed for current task (fitness < 0.75)
+- **No confirm**: Trusted skill OR optional enhancement
+
+---
+
+## AGENT SKILLS SECTION FORMAT
+
+Agents don't list individual skills. They reference HSOL:
+
+```markdown
+## ⚡ Skills
+
+> **MATRIX DISCOVERY**: Auto-injected from `matrix-skills/`
+> Profile: `{domain}:{category}` | Domains: `{inherit_from}`
+```
+
+---
+
+## ADDING NEW SKILLS
+
+```
+1. Create: {SKILLS_PATH}/{skill-id}/SKILL.md
+2. Add to: matrix-skills/{domain}.yaml
+3. Do NOT edit agent files (skills resolved by profile)
+```
+
+---
+
+## PRIORITY GUIDE
+
+| Score | Category | Usage |
+|-------|----------|-------|
+| 10 | Critical | Always required |
+| 9 | Core | Standard for domain |
+| 8 | Expert | Specialized but common |
+| 7 | Core | Useful in most contexts |
+| 5-6 | Utility | Context-dependent |
+| 1-4 | Rare | Edge cases |
+
+---
+
+## EDGE CASES
+
+| Scenario | Action |
+|----------|--------|
+| Network timeout | Proceed with matrix only, log timeout |
+| find-skills unavailable | Use matrix + installed dynamics only |
+| No skills found | Report gap, use general capabilities |
+| Installation fails | Rollback, report, offer matrix alternative |
+| Low trust + task-critical | **Confirm with user before install** |
+
+```
+IF no_relevant_skills:
+  1. Acknowledge: "No specialized skill found for {topic}"
+  2. Offer: "I can proceed with general capabilities"
+  3. Suggest: "You could create your own: npx skills init {name}"
+```
+
+---
+
+## QUICK REFERENCE
+
+### Browse skills
+```
+https://skills.sh/
+```
+
+### Commands
+```bash
+npx skills find "query"           # Search
+npx skills add X -g -y            # Install global, no confirm
+npx skills check                  # Check updates
+npx skills update                 # Update all
+```

package/skills/find-skills/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package> -g -y` - Install a skill globally for the **current tool only**, skip confirmation
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+**Install rule:** When installing skills, always use `-g -y` (global, skip confirmation) and install **only for the tool the user is currently using** (e.g. Cursor → ~/.cursor/skills/). Do not run install for all tools (cursor, copilot, antigravity).
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it (global, current tool only, skip confirmation):
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices -g -y
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, install the skill for them using **current tool only** and **skip confirmation**:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+- `-g` = install globally (user-level skills path for the current tool)
+- `-y` = skip confirmation prompts
+- Install **only for the tool the user is using** (e.g. Cursor). Do not run install for all tools.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```