agestra 4.2.1 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agestra",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "Claude Code plugin — orchestrate Ollama, Gemini, and Codex for multi-AI debates, cross-validation, and GraphRAG memory",
   "type": "module",
   "packageManager": "npm@11.11.0",

package/skills/design.md

@@ -0,0 +1,115 @@
+---
+name: agestra-design
+description: >
+  Use when exploring architecture, discussing design trade-offs, planning implementation approaches,
+  or structuring a feature before writing code. Triggers on: "design this", "how should I architect",
+  "what's the best approach", "explore approaches", "design trade-offs", "before implementing",
+  "설계", "아키텍처", "구조 잡아줘", "어떻게 만들지", "방향 잡아줘",
+  "設計", "アーキテクチャ", "架构", "设计"
+---
+
+## Purpose
+
+Pre-implementation design exploration. Understand intent through targeted questions, explore the codebase for existing patterns, propose multiple approaches with trade-offs, and produce a design document.
+
+## Scope
+
+Design features and systems **for the current project**. If the request is outside this project's scope (a new product idea, a business question, or something unrelated to this codebase), say so and suggest `/agestra idea` for open exploration instead.
+
+## Workflow
+
+### Phase 1: Clarity Gate
+
+Before asking questions, check if the request is already clear. If it includes specific file paths, function names, or concrete acceptance criteria, skip the interview.
+
+**Clarity Dimensions:**
+
+| Dimension | Weight (greenfield) | Weight (brownfield) |
+|-----------|-------------------|-------------------|
+| Goal | 40% | 35% |
+| Constraints | 30% | 25% |
+| Success Criteria | 30% | 25% |
+| Context | N/A | 15% |
+
+Greenfield: no relevant source code exists for the feature.
+Brownfield: modifying or extending existing code.
+
+**After each user answer:**
+1. Score all dimensions 0.0–1.0
+2. Calculate: `ambiguity = 1 - weighted_sum`
+3. Display progress:
+   ```
+   Round {n} | Ambiguity: {score}% | Targeting: {weakest dimension}
+   ```
+4. If ambiguity <= 20% → proceed to Phase 2
+5. If ambiguity > 20% → ask the next question targeting the WEAKEST dimension
+
+**Question targeting:** Always target the dimension with the lowest score. Ask ONE question at a time. Expose assumptions, not feature lists.
+
+| Dimension | Question Style |
+|-----------|---------------|
+| Goal | "What exactly happens when...?" / "What specific action does a user take first?" |
+| Constraints | "What are the boundaries?" / "Should this work offline?" |
+| Success Criteria | "How do we know it works?" / "What would make you say 'yes, that's it'?" |
+| Context (brownfield) | "How does this fit with existing...?" / "Extend or replace?" |
+
+**Challenge modes** (each used once, then return to normal):
+- Round 4+: **Contrarian** — "What if the opposite were true? What if this constraint doesn't actually exist?"
+- Round 6+: **Simplifier** — "What's the simplest version that would still be valuable?"
+- Round 8+: **Ontologist** (if ambiguity still > 30%) — "What IS this, really? One sentence."
+
+**Soft limits:**
+- Round 3+: allow early exit if user says "enough" — show ambiguity warning
+- Round 10: soft warning — "We're at 10 rounds. Current ambiguity: {score}%. Continue or proceed?"
+- Round 20: hard cap — proceed with current clarity, note the risk
+
+### Phase 2: Explore
+
+Search the codebase for relevant existing patterns:
+- Use Glob to find related files by name
+- Use Grep to find similar implementations
+- Use Read to understand existing architecture
+- Note conventions: naming, file organization, patterns used
+
+### Phase 3: Propose
+
+Present 2-3 distinct approaches. For each:
+- **Approach name** — one-line summary
+- **How it works** — architecture overview
+- **Fits with** — which existing patterns it aligns with
+- **Trade-offs** — pros and cons
+- **Effort** — relative complexity (low/medium/high)
+
+### Phase 4: Refine
+
+Based on user feedback:
+- Deep-dive into the selected approach
+- Address concerns raised
+- Detail component boundaries and data flow
+- Identify risks and mitigation
+
+### Phase 5: Document
+
+Write a design document to `docs/plans/` with this structure:
+
+```markdown
+# [Feature/System Name] Design
+
+## Problem
+## Approach
+## Architecture
+## Components
+## Data Flow
+## Trade-offs & Decisions
+## Open Questions
+## Implementation Steps
+```
+
+## Constraints
+
+- Ask one question at a time. Do not dump multiple questions.
+- Present approaches before solutions. Let the user choose direction.
+- Always explore the codebase before proposing — do not design in a vacuum.
+- Document all decisions made during the conversation in the final design document.
+- Do not write implementation code. Design documents only.
+- Communicate in the user's language.

package/skills/idea.md

@@ -0,0 +1,144 @@
+---
+name: agestra-idea
+description: >
+  Use when discovering improvements, comparing with similar projects, collecting user feedback,
+  exploring new features, researching what to build, or validating ideas. Triggers on:
+  "find improvements", "what should I add", "compare with competitors", "what are users asking for",
+  "explore ideas", "feature ideas", "what's missing", "is this worth building", "what do users want",
+  "what problem does this solve", "who would use this", "what should I focus on next",
+  "개선점", "뭐 추가하면 좋을까", "아이디어", "유사 프로젝트", "뭐가 부족해",
+  "이거 만들 가치가 있어?", "다음에 뭘 해야 할까", "비슷한 도구",
+  "改善", "アイデア", "改进", "想法"
+---
+
+## Purpose
+
+Idea and improvement discovery. Research similar projects, collect user complaints and feature requests, compare capabilities, and generate actionable suggestions.
+
+## Scope
+
+**Mode A: Existing project** — The codebase has a README or meaningful code.
+Research improvements, missing features, and competitive gaps for this project.
+
+**Mode B: New project** — The codebase is empty/new, but the user has a seed idea (e.g., "I want to build a writing tool").
+Research the landscape: what already exists, what users complain about, what gaps remain.
+
+**Out of scope:** Requests with no seed idea at all (e.g., "what should I build?"). You need at least a domain or concept to anchor research. Ask for one:
+
+> "I need at least a rough idea — a domain, a tool type, or a problem you want to solve. For example: 'a writing tool', 'a CLI for deployment', 'something for managing bookmarks'."
+
+## Workflow
+
+### Phase 1: Clarity Gate
+
+Before researching, understand what the user needs through targeted questions. Ask ONE question at a time. Communicate in the user's language.
+
+**Step 1: Determine mode.**
+- If the codebase has a README or meaningful code → Mode A (existing project)
+- If the codebase is empty/new but user has a seed idea → Mode B (new project)
+
+**Step 2: Mode-specific interview.**
+
+**Mode A — Existing project:**
+
+| Dimension | Question | Purpose |
+|-----------|----------|---------|
+| Direction | "What aspect are you looking to improve? (features, UX, performance, integrations, DX)" | Narrow the research scope |
+| Audience | "Who are your current users? What do they use it for most?" | Target the right competitors |
+| Feedback | "Have you received any complaints or feature requests?" | Direct pain point input |
+| Competition | "Are there specific competitors or similar tools you're aware of?" | Seed the research |
+| Strength | "What do you consider your project's unique strength?" | Avoid suggesting what already works |
+| Constraints | "Any areas you don't want to change or can't change?" | Set research boundaries |
+
+After gathering context:
+- Read the project's README and key files to understand what it does
+- Use Glob and Grep to map the current feature set
+- Identify the project's category and target audience
+
+**Mode B — New project:**
+
+| Dimension | Question | Purpose |
+|-----------|----------|---------|
+| Problem | "What problem are you trying to solve?" | Core motivation |
+| Audience | "Who would use this? What's the target audience?" | Market focus |
+| Form | "How do you envision it? (CLI, web app, library, service, plugin)" | Shape the research |
+| Inspiration | "What inspired this? Have you seen something similar?" | Seed the research |
+| Core | "What's the single most important thing it must do well?" | Prioritization anchor |
+| Boundary | "What should it NOT be? Where do you draw the line?" | Scope limits |
+
+**Early exit:** If the user provides enough context upfront (specific competitors, clear scope, concrete goals), skip remaining questions and proceed to Phase 2. Do not force unnecessary rounds.
+
+### Phase 2: Research Similar Projects
+
+- Use WebSearch to find similar tools, libraries, and projects
+- Look for: direct competitors, adjacent tools, inspirational projects
+- Collect names, URLs, and key differentiators
+
+### Phase 3: Collect Pain Points
+
+- WebSearch for complaints about similar tools (GitHub issues, forums, discussions)
+- WebFetch relevant issue pages and discussion threads
+- Identify recurring themes in user feedback
+- Note what users wish existed but doesn't
+
+### Phase 4: Feature Comparison
+
+Build a comparison table:
+
+| Feature | This Project | Competitor A | Competitor B |
+|---------|-------------|-------------|-------------|
+| Feature 1 | Yes/No | Yes/No | Yes/No |
+
+### Phase 5: Generate Suggestions
+
+For each suggestion:
+- **Title** — clear, actionable name
+- **Category** — UX, Performance, Feature, Integration, DX
+- **Source** — where this idea came from (competitor, user complaint, own analysis)
+- **Priority** — HIGH / MEDIUM / LOW with rationale
+- **Effort** — estimated complexity
+- **Description** — what it does and why it matters
+
+### Phase 6: Prioritized Recommendations
+
+Present a ranked list:
+1. **Quick wins** — high impact, low effort
+2. **Strategic investments** — high impact, high effort
+3. **Nice-to-haves** — low impact, low effort
+
+## Output Format
+
+```markdown
+## Research Summary
+
+### Similar Projects
+(list with URLs and key features)
+
+### User Pain Points
+(categorized complaints from research)
+
+### Feature Comparison
+(table)
+
+### Recommendations
+
+#### Quick Wins
+1. ...
+
+#### Strategic Investments
+1. ...
+
+#### Nice-to-Haves
+1. ...
+
+### Sources
+- [Source 1](url)
+- [Source 2](url)
+```
+
+## Constraints
+
+- Always include source URLs for claims about other projects.
+- Do not fabricate features of competitors — verify via web research.
+- Prioritize actionable suggestions over theoretical improvements.
+- Communicate in the user's language.