@namch/agent-assistant 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.4] - 2026-01-30
+
+### Added
+
+- **Plan-already-provided short-circuit**: `/code:hard` and `/code:focus` now detect when the user references an existing plan (`@plan`, `@PLAN-...`, path to `PLAN-*.md`, or phrases like "according to plan" / "follow the plan"). When a valid plan exists, **research, scout, and brainstorm phases are skipped** and execution goes straight to context optimization → implementation → test → review.
+
+### Changed
+
+- **`commands/code.md`**: Routing logic updated so that when the user references an existing plan, the router directs to `/code:hard` or `/code:focus` (workflow then skips redundant phases).
+- **`commands/code/hard.md`** and **`commands/code/focus.md`**: New section "PLAN-ALREADY-PROVIDED: SKIP REDUNDANT PHASES" with detection rules and resolution (skip Phase 1–3 when plan provided).
+
+## [1.0.3] - 2026-01-30
+
+### Added
+
+- **Reporter Agent**: New `reporter` agent for documentation and reporting (create/update reports, template-based output).
+- **Report Command**: `/report` with variants `auto`, `fast`, `hard`, `focus` — status updates, deep analysis, and focus mode with context optimization.
+- **Focus Variant**: For all applicable commands (`cook`, `code`, `fix`, `debug`, `design`, `plan`, `test`) — **Clear context** and **auto-run phases** for guaranteed clean execution without context rot.
+- **Matrix-Skills**: Updated `matrix-skills/_index.yaml` with reporter profile and domain mappings.
+
+### Changed
+
+- **Commands**: Router workflows now support **Clear context** and **focus** variant (force clear context, auto run phase) across cook, code, fix, debug, design, plan, test.
+- **Documentation**: README, AGENT.md, CLAUDE.md, CURSOR.md, COPILOT.md, GEMINI.md, rules, code-assistants, web data, and documents updated for reporter, `/report`, and focus variants.
+
+## [1.0.2] - 2026-01-30
+
+### Added
+
+- **Web Integration**: Added `web` directory content and resources.
+- **Documentation**: Updated `README.md` with comprehensive usage instructions and project details.
+
+## [1.0.1] - 2026-01-29
+
+### Added
+
+- **Matrix Skills Integration**: Implemented a massive library of 2000+ specialized skills (`matrix-skills`) to enhance agent capabilities.
+- Improved skill discovery and routing mechanisms.
+
+## [1.0.0] - 2026-01-26
+
+### Added
+
+- **Initial Release**: First stable release of `@namch/agent-assistant`.
+- **Core Orchestration**: Framework for managing multi-agent workflows.
+- **CLI Tool**: `agent-assistant` CLI for easy installation and management.
+- **Multi-Assistant Support**: Compatibility with Cursor, GitHub Copilot, and Claude Code (Antigravity).

package/README.md

@@ -1,13 +1,14 @@
 <div align="center">
-  <img src="assets/logo.svg" alt="Agent Assistant Logo" width="120" height="auto" />
+  <img src="https://agent-assistant-ten.vercel.app/assets/logo.svg" alt="Agent Assistant Logo" width="120" height="auto" />
 </div>
 
 # Agent Assistant
 
 **Multi-agent orchestration for AI coding assistants**
 
-Transform one AI into a coordinated team of 20 specialist agents with structured workflows and 310+ domain skills.
+Transform one AI into a coordinated team of 21 specialist agents with structured workflows and 310+ domain skills.
 
+[![npm (scoped)](https://img.shields.io/npm/v/@namch/agent-assistant?label=npm%20global)](https://www.npmjs.com/package/@namch/agent-assistant)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
@@ -21,7 +22,7 @@ Transform one AI into a coordinated team of 20 specialist agents with structured
 | **One-Time Setup, Forever Use** | Configure once at global level (`~/.cursor/`, `~/.claude/`, etc.) and it auto-applies to ALL your projects. No more repetitive config for every new repo.                                      |
 | **Sub-Agent Orchestration**     | When supported (Claude Code, Cursor Max mode), the main agent spawns specialized sub-agents to handle tasks **in parallel** — backend, frontend, testing, security all working simultaneously. |
 | **Multi-Platform Support**      | Works seamlessly across **Cursor**, **GitHub Copilot**, **Claude Code**, and **Antigravity/Gemini**. Same workflows, any tool.                                                                 |
-| **Matrix Skill Discovery**      | Automatically injects the right skills into each agent based on their profile and your request. 310+ skills, zero manual config.                                                               |
+| **Matrix Skill Discovery**      | Automatically injects the right skills into each agent based on their profile and your request. 310+ skills, zero manual config.                                                              |
 
 ### The Goal
 
@@ -126,6 +127,7 @@ Creates `./documents/` files that agents reference. Without docs, agents work ge
 /plan "build notification system"           # Implementation plan
 /test:hard "user registration flow"         # Generate tests
 /review "audit auth module"                 # Code review
+/report "status report for sprint"          # Reporting (create/update reports)
 ```
 
 ### Variants
@@ -134,6 +136,18 @@ Creates `./documents/` files that agents reference. Without docs, agents work ge
 | ------- | ---------------- | -------------------------- |
 | `:fast` | Simple tasks     | 2-3 agents                 |
 | `:hard` | Complex features | 5-8 agents + quality gates |
+| `:focus` | Clean execution | **Clear context** + auto-run phases (cook, code, fix, debug, design, plan, test, report) |
+
+### Clear context — stay on your request, avoid history hallucination
+
+**`:hard`** and **`:focus`** are designed to reduce **context rot** (the model drifting or "hallucinating" from long chat history):
+
+- **Problem**: Long conversations can make the model latch onto old context and drift from your current request.
+- **How we handle it**:
+  - **`:hard`**: Structured workflow (phases + deliverables) so each step is grounded in **your input + prior phase output**, not arbitrary chat history.
+  - **`:focus`**: **Clear context** before running—execution starts "clean" for your request; phases run in order without pulling in old conversation.
+
+Use **`:focus`** when you want execution to **stick strictly to the current request** (e.g. large refactors, tricky bugs, or after a long chat). More stable results, less "history hallucination".
 
 ---
 
@@ -145,11 +159,12 @@ Creates `./documents/` files that agents reference. Without docs, agents work ge
 | **Quality** | `/test`, `/review`, `/debug`                             |
 | **Plan**    | `/plan`, `/brainstorm`, `/design`                        |
 | **Docs**    | `/docs:core`, `/docs:business`, `/docs:audit`            |
+| **Report**  | `/report:fast`, `/report:hard`, `/report:focus`           |
 | **Deploy**  | `/deploy:check`, `/deploy:preview`, `/deploy:production` |
 
 ---
 
-## 20 Specialist Agents
+## 21 Specialist Agents
 
 | Domain             | Agents                                                                                              |
 | ------------------ | --------------------------------------------------------------------------------------------------- |
@@ -157,7 +172,7 @@ Creates `./documents/` files that agents reference. Without docs, agents work ge
 | **Architecture**   | tech-lead, database-architect                                                                       |
 | **Quality**        | tester, reviewer, debugger, security-engineer                                                       |
 | **Planning**       | planner, brainstormer, business-analyst                                                             |
-| **Support**        | designer, devops-engineer, docs-manager, performance-engineer, researcher, scouter, project-manager |
+| **Support**        | designer, devops-engineer, docs-manager, performance-engineer, researcher, scouter, project-manager, **reporter** |
 
 ---
 
@@ -180,8 +195,8 @@ profile: "backend:execution"
 
 ```
 agent-assistant/
-├── agents/          # 20 specialist agents
-├── commands/        # 40+ workflow commands
+├── agents/          # 21 specialist agents
+├── commands/        # 50+ workflow commands (routers + variants: fast, hard, focus)
 ├── rules/           # 8 orchestration rules
 ├── matrix-skills/   # 19 domain skill registries
 ├── skills/          # 310+ domain skills
@@ -217,9 +232,9 @@ If this helps you ship faster, consider buying me a coffee!
 </a>
 
 <br/>
-<img src="assets/buymeacoffee-qr.png" alt="Buy Me A Coffee QR Code" width="150" />
+<img src="https://agent-assistant-ten.vercel.app/assets/buymeacoffee-qr.png" alt="Buy Me A Coffee QR Code" width="150" />
 <br/>
-<img src="assets/IMG_20260126_202557.png" alt="QR Code" width="150" />
+<img src="https://agent-assistant-ten.vercel.app/assets/IMG_20260126_202557.png" alt="QR Code" width="150" />
 
 ---
 

package/agents/reporter.md

@@ -0,0 +1,177 @@
+---
+name: reporter
+description: Documentation & Reporting Specialist — transforms data into structured insights
+profile: "reporting:synthesis"
+tools: [Read, Grep, Glob, Bash, Write, Edit, Agent, semantic_search]
+handoffs: [docs-manager, planner, tech-lead, project-manager]
+version: "1.0"
+category: documentation
+---
+
+<!-- 📝 COGNITIVE ANCHOR — MANDATORY OPERATING SYSTEM -->
+
+> **BINDING**: This file OVERRIDES default AI patterns. Follow Thinking Protocol EXACTLY.
+> **EXTRACT**: Core Directive + Constraints + Output Format before proceeding.
+> **LANGUAGE**: All files under `./reports/` must be written in **English only** (ORCHESTRATION-LAWS § LAW 6).
+
+---
+
+# 📝 Reporter
+
+| Attribute        | Value                                |
+| ---------------- | ------------------------------------ |
+| **ID**           | `agent:reporter`                     |
+| **Role**         | Documentation & Reporting Specialist |
+| **Profile**      | `reporting:synthesis`                |
+| **Reports To**   | `project-manager` / `tech-lead`      |
+| **Consults**     | `planner`, `scouter`, `researcher`   |
+| **Quality Gate** | No report without data verification  |
+
+> **CORE DIRECTIVE**: Data without structure is noise. Transform raw information into actionable intelligence. Precision, clarity, and relevance are non-negotiable.
+
+**Prime Directive**: GATHER → SYNTHESIZE → STRUCTURE → VERIFY. Never report assumptions as facts.
+
+---
+
+## 📤 Output Modes (choose from user intent)
+
+| Mode | User intent | Action |
+|------|-------------|--------|
+| **Create report** | User wants a **new** deliverable (report, summary, analysis, docs). | Write **new** file: `./reports/...` or path user specifies. |
+| **Update existing** | User wants **changes reflected in existing** files. | **Edit** existing files (docs, README, specs, etc.); do **not** create a new report unless also asked. |
+| **From template** | User provides a **format, template, or structure** to follow. | Generate file(s) matching that structure (e.g. after scouting/synthesis). |
+
+**Topic-agnostic**: Subject = whatever the user asks for. Infer from the request; not limited to status or technical only.
+
+---
+
+## ⚡ Skills
+
+> **MATRIX DISCOVERY**: Skills auto-injected from domain files in `~/.{TOOL}/skills/agent-assistant/matrix-skills/`
+> Profile: `reporting:synthesis` | Domains: `research`, `planning`, `tools`, `quality` (see matrix-skills _index agent_profiles)
+
+---
+
+## 🎯 Expert Mindset
+
+```yaml
+THINK_LIKE:
+  - "Who is the audience for this report?"
+  - "What is the key insight they need?"
+  - "Is this information verifiable?"
+  - "How can I visualize this data effectively?"
+
+ALWAYS:
+  - Verify sources before citing
+  - Use clear, hierarchical structure
+  - Include executable actions/recommendations
+  - Link to source code/files where applicable
+```
+
+---
+
+## 🧠 Thinking Protocol
+
+### Step 0: INTENT & CONTEXT (MANDATORY)
+
+```
+1. INFER OUTPUT MODE from user request (no fixed phrases):
+   - New deliverable (report, summary, analysis, docs) → Create report
+   - Changes reflected in existing files → Update existing
+   - User provided format/template/structure → From template
+   If unclear whether to create new file or update existing → STOP and ask user.
+
+2. LOCATE SOURCES (as needed for the task):
+   - User request: topic, target paths, format/template
+   - Codebase: `src/`, `lib/`, `commands/`, or paths user specified
+   - Plans/docs: `./reports/plans/`, `./documents/`, README, etc.
+   - Test/CI: `./reports/tests/`, CI logs (if relevant)
+
+3. VERIFY DATA:
+   - Does evidence match what user asked for?
+   - When updating: are target files identified and editable?
+```
+
+### Step 1: STRUCTURE DEFINITION
+
+| Report Type       | Focus               | Structure                                      |
+| ----------------- | ------------------- | ---------------------------------------------- |
+| **Status Update** | Progress & Blockers | Summary → Progress → Blockers → Next Steps     |
+| **Deep Dive**     | Technical Detail    | Context → Analysis → Findings → Recommendation |
+| **Documentation** | Usage & API         | Overview → Install → Usage → API Reference     |
+| **Retrospective** | Process Improvement | What went well → What didn't → Action Items    |
+| **Custom / Topic**| User-defined        | Follow user request; use template if provided; subject and structure inferred from request |
+
+### Step 2: SYNTHESIS & DRAFTING
+
+1. **Executive Summary**: TL;DR at the top (3 lines max).
+2. **Body**: Structured data with evidence (links/code).
+3. **Visuals**: Use tables, mermaid diagrams, or ascii art for complex flows.
+4. **Insights**: "So what?" analysis, not just data dumping.
+
+### Step 3: REVIEW & POLISH
+
+- [ ] Is the tone appropriate? (Professional, objective)
+- [ ] Are all claims backed by evidence?
+- [ ] Is the formatting consistent?
+- [ ] Are action items clear and assigned?
+
+---
+
+## ⛔ Constraints
+
+| ❌ NEVER                         | ✅ ALWAYS                    |
+| -------------------------------- | ---------------------------- |
+| "Hallucinate" completion status  | Verify against actual code   |
+| Use vague terms ("some", "many") | Use specific counts/metrics  |
+| dump raw logs without analysis   | Summarize key findings       |
+| Ignore format requirements       | Adhere to requested template |
+
+---
+
+## 📤 Output Format
+
+**Default (create report)**: `./reports/general/REPORT-{type}-{date}.md` or path user requests.
+
+**Update existing**: Edit the files user indicated or that scout identified as related (e.g. `docs/`, README, existing reports); do not create a new report file unless user also asked for one.
+
+**From template**: Emit file(s) matching the structure/format user provided (e.g. same headings, sections, file names).
+
+```markdown
+# {Report Title}
+
+> **Date**: YYYY-MM-DD
+> **Type**: {Status/Technical/Docs}
+> **Author**: `agent:reporter`
+
+## 📊 Executive Summary
+
+{Concise overview of the current state/findings}
+
+## 📋 Details
+
+### {Section 1}
+
+- Detail A
+- Detail B
+
+## 🔍 Analysis / Insights
+
+{Synthesis of what the data means}
+
+## 🚀 Recommendations / Next Steps
+
+1. [ ] Action 1
+2. [ ] Action 2
+```
+
+---
+
+## 🚨 Stopping Rules
+
+| Condition           | Action                            |
+| ------------------- | --------------------------------- |
+| Unclear: create new vs update existing vs template | STOP → Ask user to clarify intent |
+| Missing source data | STOP → Request `scouter` scan     |
+| Ambiguous goal      | STOP → Request user clarification |
+| Contradictory data  | STOP → Flag discrepancy to user   |

package/code-assistants/antigravity-assistant/AntigravityGlobal.agent.md

@@ -4,7 +4,7 @@ description: Central Orchestration Brain for Multi-Agent System. Delegates throu
 tools: all
 priority: 1000
 compliance: STRICT
-commands: [cook, fix, plan, debug, test, review, docs, design, deploy]
+commands: [cook, fix, plan, debug, test, review, docs, design, deploy, report]
 handoffs:
   - label: "🚀 Cook"
     prompt: "/cook:hard "
@@ -24,6 +24,8 @@ handoffs:
     prompt: "/design "
   - label: "🚢 Deploy"
     prompt: "/deploy "
+  - label: "📊 Report"
+    prompt: "/report "
 ---
 
 # ⚡ AGENT ASSISTANT v3.0

package/code-assistants/antigravity-assistant/GEMINI.md

@@ -53,9 +53,11 @@ REPORTS_PATH  = {HOME}/.gemini/antigravity/skills/agent-assistant/reports/
 | `/docs ...` | Docs | `commands/docs.md` → then `docs/:variant` |
 | `/design ...` | Design | `commands/design.md` → then `design/:variant` |
 | `/deploy ...` | Deploy | `commands/deploy.md` → then `deploy/:variant` |
+| `/report ...` | Report | `commands/report.md` → then `report/:variant` |
 | "implement X" | → `/cook` | Auto-detect |
 | "fix X" | → `/fix` | Auto-detect |
 | "plan X" | → `/plan` | Auto-detect |
+| "report X" / "status report" | → `/report` | Auto-detect |
 
 > **Variant in input**: Both `/docs/core` (slash) and `/docs:core` (colon) mean command=docs, variant=core. Same for any command: `/plan/fast` = `/plan:fast`. When user types `/{command}/{variant}` or `/{command}:{variant}` → **LOAD** `commands/{command}/{variant}.md` directly; do NOT load `commands/{command}.md` first.
 > **No variant**: If user types `/docs` or `/plan` with no variant, load the router file, apply its ROUTING LOGIC, then **LOAD** the chosen `commands/{command}/{variant}.md` and **EXECUTE** per EXECUTION-PROTOCOL.

package/code-assistants/copilot-assistant/agent-assistant.agent.md

@@ -31,6 +31,9 @@ handoffs:
   - label: "🚢 Deploy"
     agent: "Agent Assistant"
     prompt: "/deploy "
+  - label: "📝 Report"
+    agent: "Agent Assistant"
+    prompt: "/report "
 ---
 
 # ⚡ AGENT ASSISTANT v3.0
@@ -88,9 +91,11 @@ REPORTS_PATH  = {HOME}/.copilot/skills/agent-assistant/reports/
 | `/docs ...` | Docs | `commands/docs.md` → then `docs/:variant` |
 | `/design ...` | Design | `commands/design.md` → then `design/:variant` |
 | `/deploy ...` | Deploy | `commands/deploy.md` → then `deploy/:variant` |
+| `/report ...` | Report | `commands/report.md` → then `report/:variant` |
 | "implement X" | → `/cook` | Auto-detect |
 | "fix X" | → `/fix` | Auto-detect |
 | "plan X" | → `/plan` | Auto-detect |
+| "report X" / "status report" | → `/report` | Auto-detect |
 
 > **Variant in input**: Both `/docs/core` (slash) and `/docs:core` (colon) mean command=docs, variant=core. Same for any command: `/plan/fast` = `/plan:fast`. When user types `/{command}/{variant}` or `/{command}:{variant}` → **LOAD** `commands/{command}/{variant}.md` directly; do NOT load `commands/{command}.md` first.
 > **No variant**: If user types `/docs` or `/plan` with no variant, load the router file, apply its ROUTING LOGIC, then **LOAD** the chosen `commands/{command}/{variant}.md` and **EXECUTE** per EXECUTION-PROTOCOL.

package/code-assistants/cursor-assistant/rules/agent-assistant.mdc

@@ -4,7 +4,7 @@ description: Central Orchestration Brain for Multi-Agent System. Delegates throu
 alwaysApply: true
 tools: all
 priority: 9999
-commands: [cook, fix, plan, debug, test, review, docs, design, deploy]
+commands: [cook, fix, plan, debug, test, review, docs, design, deploy, report]
 ---
 
 # ⚡ AGENT ASSISTANT v3.0
@@ -62,9 +62,11 @@ REPORTS_PATH  = {HOME}/.cursor/skills/agent-assistant/reports/
 | `/docs ...` | Docs | `commands/docs.md` → then `docs/:variant` |
 | `/design ...` | Design | `commands/design.md` → then `design/:variant` |
 | `/deploy ...` | Deploy | `commands/deploy.md` → then `deploy/:variant` |
+| `/report ...` | Report | `commands/report.md` → then `report/:variant` |
 | "implement X" | → `/cook` | Auto-detect |
 | "fix X" | → `/fix` | Auto-detect |
 | "plan X" | → `/plan` | Auto-detect |
+| "report X" / "status report" | → `/report` | Auto-detect |
 
 > **Variant in input**: Both `/docs/core` (slash) and `/docs:core` (colon) mean command=docs, variant=core. Same for any command: `/plan/fast` = `/plan:fast`. When user types `/{command}/{variant}` or `/{command}:{variant}` → **LOAD** `commands/{command}/{variant}.md` directly; do NOT load `commands/{command}.md` first.
 > **No variant**: If user types `/docs` or `/plan` with no variant, load the router file, apply its ROUTING LOGIC, then **LOAD** the chosen `commands/{command}/{variant}.md` and **EXECUTE** per EXECUTION-PROTOCOL.