@mclawnet/agent 0.5.9 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mclawnet/agent",
-  "version": "0.5.9",
+  "version": "0.6.2",
   "type": "module",
   "exports": {
     ".": {
@@ -13,18 +13,20 @@
   },
   "files": [
     "dist",
-    "cli.js"
+    "cli.js",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
+    "commander": "^14.0.3",
     "ws": "^8.19.0",
-    "@mclawnet/shared": "0.1.0",
+    "@mclawnet/claude-adapter": "0.1.1",
+    "@mclawnet/swarm": "0.1.0",
     "@mclawnet/logger": "0.1.1",
     "@mclawnet/memory": "0.1.0",
-    "@mclawnet/swarm": "0.1.0",
-    "@mclawnet/claude-adapter": "0.1.1"
+    "@mclawnet/shared": "0.1.0"
   },
   "devDependencies": {
     "@types/node": "^22",

package/skills/academic-search/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: academic-search
+description: Search and analyze academic literature across arXiv, Google Scholar, Semantic Scholar, and PubMed. Use when asked to find research papers, conduct a literature review, summarize academic findings, or investigate the state of the art on a scientific or technical topic.
+disable-model-invocation: true
+---
+
+# Academic Search
+
+A systematic academic literature search and analysis skill that helps researchers find, evaluate, and synthesize scholarly papers across multiple databases. Follows a structured five-phase process: define scope, search, filter, analyze, and synthesize.
+
+## When to Use
+
+Activate this skill when:
+- Searching for academic papers on a specific topic
+- Conducting a literature review or survey
+- Investigating the state of the art in a research area
+- Finding seminal or highly-cited papers on a subject
+- Summarizing or explaining academic papers
+- Comparing research methodologies or findings across studies
+- Building a bibliography or reference list for a project
+
+## When NOT to Use
+
+- **General web research** — use the `deep-research` skill for non-academic topics
+- **GitHub or open source research** — use the `github-deep-research` skill
+- **News or current events** — use `deep-research` with web search
+- **Internal codebase questions** — search the code directly
+
+## Search Process
+
+Follow these five phases in order. Complete each phase before moving to the next.
+
+### Phase 1: Define Scope
+
+Before searching, establish clear boundaries for the literature search.
+
+- **Research question**: State the specific question in one or two sentences.
+- **Key concepts**: Break the topic into 3-5 core concepts or themes.
+- **Inclusion criteria**: Date range, languages, publication types, domains.
+- **Exclusion criteria**: Non-peer-reviewed, tangentially related, outdated methods.
+- **Depth target**: Broad survey (20-50 papers) or focused review (5-15 papers).
+
+Ask the user to confirm scope before proceeding.
+
+### Phase 2: Search
+
+**Query formulation principles:**
+- Use Boolean operators: `(transformer OR attention mechanism) AND (machine translation)`
+- Include synonyms and alternate terminology for key concepts
+- Start broad, then narrow based on initial result volume
+
+**Database-specific guidance:**
+
+| Database | Best For | Query Tips |
+|---|---|---|
+| **arXiv** | CS, physics, math | Search by category (cs.CL, cs.CV). Check recent preprints. |
+| **Google Scholar** | Cross-disciplinary | Use "cited by" and "related articles" for discovery. |
+| **Semantic Scholar** | AI/ML, NLP, biomedical | Leverage citation graphs and TLDR summaries. |
+| **PubMed** | Biomedical, clinical | Use MeSH terms. Filter by study type (RCT, meta-analysis). |
+
+**Search strategy:**
+1. Run the primary query on 2-3 databases.
+2. Identify 3-5 highly relevant seed papers from initial results.
+3. Use citation chaining: check references (backward) and citing papers (forward).
+4. Refine queries if initial results miss key aspects of the topic.
+
+### Phase 3: Filter and Evaluate
+
+**Quality signals (in order of reliability):**
+1. **Venue**: Recognized peer-reviewed journal or top-tier conference (NeurIPS, ACL, Nature, JAMA).
+2. **Citation count**: High citations relative to paper age. Normalize by field and year.
+3. **Methodology rigor**: Clear experimental design, appropriate baselines, reproducible results.
+4. **Recency**: For fast-moving fields, prefer last 2-3 years. For established fields, include seminal older works.
+
+**Red flags:** Predatory journals, no experimental validation, unsupported claims, missing baselines.
+
+### Phase 4: Analyze
+
+For each selected paper, extract:
+
+```
+### [Paper Title]
+- **Authors**: [Names] | **Year**: [Year] | **Venue**: [Journal/Conference]
+- **Citations**: [Count] | **URL/DOI**: [Link]
+- **Problem**: What problem does this paper address?
+- **Method**: What approach or technique is proposed?
+- **Key results**: Main quantitative or qualitative findings
+- **Limitations**: Acknowledged or observed limitations
+- **Relevance**: [High/Medium/Low] to the research question
+```
+
+**Reading strategy:** Abstract and conclusion first, then figures and tables, then introduction. Read methodology only for High-relevance papers.
+
+### Phase 5: Synthesize
+
+- Identify common themes, agreements, and contradictions across studies.
+- Group papers by methodology, finding, or perspective.
+- Note gaps in the literature where further research is needed.
+- Highlight how ideas in the field evolved over time.
+- Draw conclusions supported by the body of evidence, not single papers.
+
+## Output Format
+
+```markdown
+# Literature Review: [Topic]
+
+## Research Question
+[1-2 sentence statement]
+
+## Search Summary
+- **Databases searched**: [List]
+- **Date range**: [Start - End]
+- **Papers screened**: [N] | **Papers included**: [N]
+
+## Key Findings
+### Theme 1: [Title]
+[Summary across multiple papers. Cite using [Author, Year] format.]
+### Theme 2: [Title]
+[Summary]
+
+## State of the Art
+[Current best methods/results/understanding, with citations]
+
+## Open Questions and Gaps
+- [Gap 1]
+- [Gap 2]
+
+## References
+1. Author A et al. (Year). "Title." *Venue*. DOI/URL
+2. Author B et al. (Year). "Title." *Venue*. DOI/URL
+```
+
+## Citation Management
+
+- Use **[Author, Year]** for in-text citations (e.g., [Vaswani et al., 2017]).
+- For 3+ authors, use first author followed by "et al."
+- In References, include: all authors, year, full title, venue, and DOI or URL.
+- Sort references by first appearance or alphabetically, per user preference.
+- Flag any paper lacking a DOI or stable URL so the user can verify access.
+
+## Guidelines
+
+- **Do not fabricate papers.** Never invent titles, authors, or results. If unsure whether a paper exists, say so.
+- **Acknowledge knowledge limits.** For very recent work, recommend the user search databases directly and share results for analysis.
+- **Prefer primary sources.** Cite the original paper, not a blog post or secondary summary.
+- **Be explicit about uncertainty.** If you recall a result but not exact numbers, state the figures are approximate.
+- **Adapt depth to the request.** A quick "find me 3 papers on X" needs a different response than "conduct a full literature review."

package/skills/architecture/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: architecture
+description: Analyze and design software architecture with focus on scalability, maintainability, and clean separation of concerns. Use when planning new features, refactoring systems, evaluating tech debt, or making architectural decisions that affect multiple components.
+---
+
+# Software Architecture
+
+Analyze and design software architecture for scalable, maintainable systems. This skill provides a systematic framework for architectural analysis, design principles, pattern selection, and decision documentation.
+
+## Overview
+
+Architecture work spans three activities:
+
+1. **Analysis** — Understanding an existing system's structure, dependencies, and quality attributes
+2. **Design** — Proposing changes or new structures that satisfy requirements and constraints
+3. **Decision** — Choosing among alternatives with explicit trade-off reasoning and documentation
+
+Every architectural recommendation should be grounded in concrete analysis of the codebase, not abstract theory. Read the code, map the dependencies, then advise.
+
+## When to Use
+
+- Planning a new feature that touches multiple modules or services
+- Refactoring a system to reduce coupling or improve scalability
+- Making technology choices (database, message broker, framework)
+- Evaluating technical debt and prioritizing remediation
+- Reviewing a proposed architecture before implementation begins
+- Breaking a monolith into services or reorganizing a monorepo
+- Designing API contracts between teams or systems
+
+## When NOT to Use
+
+- **Implementation details** — Use the pair-programming skill for writing code
+- **Code-level review** — Use the code-review skill for reviewing diffs and PRs
+- **Test design** — Use the testing skill for test strategy and coverage
+- **Quick bug fixes** — Architecture analysis is overkill for isolated bug fixes
+
+## Architecture Analysis Framework
+
+Follow these five steps in order. Each step builds on the previous one.
+
+### Step 1: Map Component Dependency Graph
+
+Identify every module, package, or service and draw the dependency arrows between them.
+
+**Actions:**
+- List all top-level modules/packages and their stated responsibilities
+- For each module, identify its imports/dependencies on other modules
+- Identify external dependencies (third-party libraries, services, databases)
+- Group tightly-connected modules into clusters
+- Visualize as a directed graph
+
+**What to look for:**
+- Modules with many incoming edges (high afferent coupling) — foundational, high-risk to change
+- Modules with many outgoing edges (high efferent coupling) — fragile, break when dependencies change
+- Isolated modules with no connections — potentially dead code
+- Unexpected dependencies that cross domain boundaries
+
+### Step 2: Identify Coupling Points
+
+Coupling is the degree to which modules depend on each other. Lower coupling means easier change.
+
+**Types of coupling (worst to least harmful):**
+
+1. **Content coupling** — One module modifies the internal state of another directly
+2. **Common coupling** — Multiple modules read/write the same shared mutable state
+3. **Temporal coupling** — Modules must be called in a specific order to work correctly
+4. **Control coupling** — One module passes a flag that controls another's behavior
+5. **Data coupling** — Modules share data through parameters (acceptable when minimal and well-defined)
+
+**For each coupling point, document:**
+- Which modules are involved
+- What type of coupling it is
+- What the concrete risk is
+- A remediation suggestion
+
+### Step 3: Check for Circular Dependencies
+
+Circular dependencies make systems hard to understand, test, and deploy independently.
+
+**Detection:** Walk the dependency graph and identify cycles, including indirect ones (A → B → C → A).
+
+**Resolution strategies (simplest first):**
+1. **Extract interface** — Define an abstraction that both modules depend on
+2. **Dependency inversion** — Lower-level module defines interface, higher-level implements
+3. **Event-based decoupling** — Replace direct calls with event publication/subscription
+4. **Merge modules** — If truly inseparable, they may belong together
+5. **Extract shared logic** — Move shared piece into a new lower-level module
+
+### Step 4: Evaluate Separation of Concerns
+
+Each module should have a single, well-defined responsibility.
+
+**Check these boundaries:**
+- **Presentation vs. Business Logic** — UI components should not contain business rules
+- **Business Logic vs. Data Access** — Domain logic should not know how data is stored
+- **Configuration vs. Runtime** — Configuration should be loaded once and injected
+- **Cross-cutting concerns** — Logging, auth, error handling should be handled consistently
+
+**Responsibility assignment check:**
+- Can you describe each module's responsibility in one sentence without using "and"?
+- If a requirement changes, how many modules need modification?
+- Are there modules that change frequently for unrelated reasons?
+
+### Step 5: Assess Scalability Bottlenecks
+
+Identify where the system will strain under increased load.
+
+**Categories:**
+1. **I/O bound** — N+1 queries, unbounded result sets, synchronous I/O on hot paths, missing connection pooling
+2. **Compute bound** — O(n²) algorithms on growing datasets, blocking event loops, missing caching
+3. **State bound** — Unbounded caches, growing queues without backpressure, shared mutable state requiring locks
+4. **Network bound** — Chatty inter-service communication, missing circuit breakers, no timeout/retry policies
+
+**For each bottleneck, document:**
+- Where it is and what triggers it
+- Current impact and projected impact at 10x load
+- Proposed mitigation with effort estimate
+
+## Design Principles
+
+### SOLID Principles
+
+**Single Responsibility (SRP)** — Each module has exactly one reason to change.
+- Good: `UserRepository` handles only persistence. `UserValidator` handles only validation.
+- Bad: `UserService` handles validation, persistence, email, and logging.
+- Watch for: "Manager" or "Handler" classes that grow without bound.
+
+**Open/Closed (OCP)** — Open for extension, closed for modification.
+- Good: Plugin system where new functionality is added by registering new plugins.
+- Bad: Giant switch statement modified every time a new type is added.
+- Watch for: Growing if/else chains based on type discrimination.
+
+**Liskov Substitution (LSP)** — Subtypes must be usable wherever their base type is expected.
+- Good: All `Logger` implementations can be swapped without changing calling code.
+- Bad: `ReadOnlyRepository` extends `Repository` but throws on `save()`.
+- Watch for: Subclasses that override methods to throw "not supported."
+
+**Interface Segregation (ISP)** — No client should depend on methods it does not use.
+- Good: Separate `Readable`, `Writable`, `Deletable` interfaces.
+- Bad: `DataStore` interface with 30 methods where most implementations need 5.
+- Watch for: Implementations leaving many methods as no-ops.
+
+**Dependency Inversion (DIP)** — Depend on abstractions, not concretions.
+- Good: `NotificationService` depends on `MessageSender` interface; concrete implementations injected.
+- Bad: `NotificationService` directly imports and instantiates `SmtpClient`.
+- Watch for: `new` keyword inside business logic creating infrastructure objects.
+
+## Architecture Patterns
+
+Choose patterns based on the problem. Every pattern has a cost; only use one when the problem it solves is real.
+
+### Dependency Injection
+**Use when:** Decoupling for testability or flexibility.
+**Trade-off:** Adds indirection; constructor parameter lists can grow.
+
+### Event-Driven Architecture
+**Use when:** Components need loose coupling or asynchronous workflows.
+**Trade-off:** Harder to trace execution flow. Eventual consistency. Requires correlation IDs.
+
+### Repository Pattern
+**Use when:** Abstracting data access from business logic.
+**Trade-off:** Can become leaky if you need storage-specific features. Keep interfaces minimal.
+
+### Strategy Pattern
+**Use when:** Multiple interchangeable algorithms or behaviors selected at runtime.
+**Trade-off:** Adds interfaces and classes. Only worth it with genuinely multiple strategies.
+
+### Adapter Pattern
+**Use when:** Integrating with external systems whose interface does not match yours.
+**Trade-off:** One more layer. Keep adapters thin — translate only, no logic.
+
+### CQRS
+**Use when:** Read and write workloads have very different performance characteristics.
+**Trade-off:** Significant complexity. Data synchronization between models. Only at scale.
+
+### Saga Pattern
+**Use when:** Coordinating multi-step processes across services where each step may fail.
+**Trade-off:** Complex failure handling. Requires idempotent operations. Use only for genuine distributed transactions.
+
+## Decision Framework
+
+Every significant architectural decision should follow this process.
+
+### 1. Establish Context
+- Hard constraints (budget, timeline, team size, compliance)
+- Quality attribute requirements (latency, throughput, availability, security)
+- Existing architecture state
+- Stakeholder priorities
+
+### 2. Enumerate Options
+- At least two viable options. Include "do nothing" when applicable.
+- For each: effort estimate (T-shirt size), operational complexity, risk level.
+
+### 3. Analyze Trade-offs
+- What you gain and sacrifice per option.
+- Quantify where possible ("adds ~200ms latency" > "adds some latency").
+
+### 4. Make and Record the Decision
+- Chosen option and primary rationale.
+- Understandable to someone not in the room.
+
+### 5. Plan Consequences
+- Follow-up tasks. Migration steps if replacing existing approach.
+- Review date or trigger condition for revisiting.
+
+## ADR Template
+
+```markdown
+# ADR-[NUMBER]: [SHORT TITLE]
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Date
+[YYYY-MM-DD]
+
+## Context
+[What problem are we facing? What constraints exist?]
+
+## Options Considered
+
+### Option 1: [Name]
+- Effort: [Low / Medium / High]
+- Risk: [Low / Medium / High]
+- Pros: [List]
+- Cons: [List]
+
+### Option 2: [Name]
+- Effort: [Low / Medium / High]
+- Risk: [Low / Medium / High]
+- Pros: [List]
+- Cons: [List]
+
+## Decision
+[Chosen option and rationale.]
+
+## Consequences
+- [What becomes easier]
+- [What becomes harder]
+- [Follow-up actions]
+- [Review trigger]
+```
+
+## Architecture Review Checklist
+
+**Structural Integrity**
+- [ ] All modules have a single, clearly stated responsibility
+- [ ] Dependency graph has no circular dependencies
+- [ ] Dependencies flow from high-level policy to low-level detail
+- [ ] External dependencies are isolated behind adapters or interfaces
+- [ ] No module depends on more than 5-7 other internal modules
+
+**Quality Attributes**
+- [ ] Latency-critical paths identified with performance budgets
+- [ ] Failure modes identified with mitigation strategies
+- [ ] Horizontally scalable at expected bottleneck points
+- [ ] Security boundaries explicit (authentication, authorization, data isolation)
+
+**Operability**
+- [ ] Deployable incrementally (no big-bang releases)
+- [ ] Health checks and monitoring points defined
+- [ ] Configuration externalized and environment-specific
+- [ ] Logging supports tracing requests across components
+
+**Evolvability**
+- [ ] New features addable without modifying core modules
+- [ ] Known future requirements accommodatable without redesign
+- [ ] Key decisions documented in ADRs
+
+## Common Anti-Patterns
+
+### God Class / God Module
+**Symptom:** One module everything depends on, mixed responsibilities.
+**Fix:** Decompose by responsibility. Extract focused modules one at a time.
+
+### Distributed Monolith
+**Symptom:** Microservices deployed together, sharing databases, synchronous call chains.
+**Fix:** Make services truly independent or merge back into monolith.
+
+### Leaky Abstractions
+**Symptom:** Callers need to understand implementation details behind an interface.
+**Fix:** Redesign interface to hide details. If impossible, remove the abstraction.
+
+### Premature Optimization
+**Symptom:** Complex caching or async patterns before any measured performance problem.
+**Fix:** Start simple. Measure under realistic load. Optimize only the measured bottleneck.
+
+### Golden Hammer
+**Symptom:** Same technology applied to every problem regardless of fit.
+**Fix:** Evaluate each problem on its merits. Different parts of a system can use different patterns.
+
+### Accidental Complexity
+**Symptom:** Codebase harder to work with than the problem domain requires.
+**Fix:** Ask "what would we lose if we removed this layer?" If nothing, remove it.

package/skills/changelog-generator/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: changelog-generator
+description: Generate user-facing changelogs from git commit history by categorizing changes and transforming technical commits into clear release notes. Use when preparing release notes, creating product update summaries, or documenting changes for customers.
+disable-model-invocation: true
+---
+
+# Changelog Generator
+
+This skill transforms technical git commits into polished, user-friendly changelogs that your customers and users will actually understand and appreciate.
+
+## When to Use This Skill
+
+- Preparing release notes for a new version
+- Creating weekly or monthly product update summaries
+- Documenting changes for customers
+- Writing changelog entries for app store submissions
+- Generating update notifications
+- Creating internal release documentation
+- Maintaining a public changelog/product updates page
+
+## When NOT to Use
+
+- **Internal commit history review** — use `git log` directly
+- **Technical documentation** — use the `technical-writing` skill
+- **Blog posts or marketing announcements** — use the `content-research-writer` skill
+- **Code review** — use the `code-review` skill
+
+## What This Skill Does
+
+1. **Scans Git History**: Analyzes commits from a specific time period or between versions
+2. **Categorizes Changes**: Groups commits into logical categories (features, improvements, bug fixes, breaking changes, security)
+3. **Translates Technical → User-Friendly**: Converts developer commits into customer language
+4. **Formats Professionally**: Creates clean, structured changelog entries
+5. **Filters Noise**: Excludes internal commits (refactoring, tests, etc.)
+6. **Follows Best Practices**: Applies changelog guidelines and your brand voice
+
+## How to Use
+
+### Basic Usage
+
+From your project repository:
+
+```
+Create a changelog from commits since last release
+```
+
+```
+Generate changelog for all commits from the past week
+```
+
+```
+Create release notes for version 2.5.0
+```
+
+### With Specific Date Range
+
+```
+Create a changelog for all commits between March 1 and March 15
+```
+
+### With Custom Guidelines
+
+```
+Create a changelog for commits since v2.4.0, using my changelog 
+guidelines from CHANGELOG_STYLE.md
+```
+
+## Example
+
+**User**: "Create a changelog for commits from the past 7 days"
+
+**Output**:
+```markdown
+# Updates - Week of March 10, 2024
+
+## ✨ New Features
+
+- **Team Workspaces**: Create separate workspaces for different 
+  projects. Invite team members and keep everything organized.
+
+- **Keyboard Shortcuts**: Press ? to see all available shortcuts. 
+  Navigate faster without touching your mouse.
+
+## 🔧 Improvements
+
+- **Faster Sync**: Files now sync 2x faster across devices
+- **Better Search**: Search now includes file contents, not just titles
+
+## 🐛 Fixes
+
+- Fixed issue where large images wouldn't upload
+- Resolved timezone confusion in scheduled posts
+- Corrected notification badge count
+```
+
+**Inspired by:** Manik Aggarwal's use case from Lenny's Newsletter
+
+## Tips
+
+- Run from your git repository root
+- Specify date ranges for focused changelogs
+- Use your CHANGELOG_STYLE.md for consistent formatting
+- Review and adjust the generated changelog before publishing
+- Save output directly to CHANGELOG.md
+
+## Related Use Cases
+
+- Creating GitHub release notes
+- Writing app store update descriptions
+- Generating email updates for users
+- Creating social media announcement posts
+