@techwavedev/agi-agent-kit 1.2.7 → 1.2.8

package/templates/skills/knowledge/brainstorming/SKILL.md

@@ -14,12 +14,12 @@ allowed-tools: Read, Glob, Grep
 
 ### When to Trigger
 
-| Pattern | Action |
-|---------|--------|
-| "Build/Create/Make [thing]" without details | 🛑 ASK 3 questions |
-| Complex feature or architecture | 🛑 Clarify before implementing |
-| Update/change request | 🛑 Confirm scope |
-| Vague requirements | 🛑 Ask purpose, users, constraints |
+| Pattern                                     | Action                             |
+| ------------------------------------------- | ---------------------------------- |
+| "Build/Create/Make [thing]" without details | 🛑 ASK 3 questions                 |
+| Complex feature or architecture             | 🛑 Clarify before implementing     |
+| Update/change request                       | 🛑 Confirm scope                   |
+| Vague requirements                          | 🛑 Ask purpose, users, constraints |
 
 ### 🚫 MANDATORY: 3 Questions Before Implementation
 
@@ -38,12 +38,12 @@ allowed-tools: Read, Glob, Grep
 
 ### Core Principles
 
-| Principle | Meaning |
-|-----------|---------|
-| **Questions Reveal Consequences** | Each question connects to an architectural decision |
-| **Context Before Content** | Understand greenfield/feature/refactor/debug context first |
-| **Minimum Viable Questions** | Each question must eliminate implementation paths |
-| **Generate Data, Not Assumptions** | Don't guess—ask with trade-offs |
+| Principle                          | Meaning                                                    |
+| ---------------------------------- | ---------------------------------------------------------- |
+| **Questions Reveal Consequences**  | Each question connects to an architectural decision        |
+| **Context Before Content**         | Understand greenfield/feature/refactor/debug context first |
+| **Minimum Viable Questions**       | Each question must eliminate implementation paths          |
+| **Generate Data, Not Assumptions** | Don't guess—ask with trade-offs                            |
 
 ### Question Generation Process
 
@@ -62,6 +62,7 @@ allowed-tools: Read, Glob, Grep
 **Question:** [Clear question]
 
 **Why This Matters:**
+
 - [Architectural consequence]
 - [Affects: cost/complexity/timeline/scale]
 
@@ -83,19 +84,19 @@ allowed-tools: Read, Glob, Grep
 
 ### Status Board Format
 
-| Agent | Status | Current Task | Progress |
-|-------|--------|--------------|----------|
+| Agent        | Status     | Current Task       | Progress     |
+| ------------ | ---------- | ------------------ | ------------ |
 | [Agent Name] | ✅🔄⏳❌⚠️ | [Task description] | [% or count] |
 
 ### Status Icons
 
-| Icon | Meaning | Usage |
-|------|---------|-------|
-| ✅ | Completed | Task finished successfully |
-| 🔄 | Running | Currently executing |
-| ⏳ | Waiting | Blocked, waiting for dependency |
-| ❌ | Error | Failed, needs attention |
-| ⚠️ | Warning | Potential issue, not blocking |
+| Icon | Meaning   | Usage                           |
+| ---- | --------- | ------------------------------- |
+| ✅   | Completed | Task finished successfully      |
+| 🔄   | Running   | Currently executing             |
+| ⏳   | Waiting   | Blocked, waiting for dependency |
+| ❌   | Error     | Failed, needs attention         |
+| ⚠️   | Warning   | Potential issue, not blocking   |
 
 ---
 
@@ -114,12 +115,12 @@ allowed-tools: Read, Glob, Grep
 
 ### Error Categories
 
-| Category | Response Strategy |
-|----------|-------------------|
-| **Port Conflict** | Offer alternative port or close existing |
-| **Dependency Missing** | Auto-install or ask permission |
-| **Build Failure** | Show specific error + suggested fix |
-| **Unclear Error** | Ask for specifics: screenshot, console output |
+| Category               | Response Strategy                             |
+| ---------------------- | --------------------------------------------- |
+| **Port Conflict**      | Offer alternative port or close existing      |
+| **Dependency Missing** | Auto-install or ask permission                |
+| **Build Failure**      | Show specific error + suggested fix           |
+| **Unclear Error**      | Ask for specifics: screenshot, console output |
 
 ---
 
@@ -140,24 +141,65 @@ allowed-tools: Read, Glob, Grep
 
 ## Communication Principles
 
-| Principle | Implementation |
-|-----------|----------------|
-| **Concise** | No unnecessary details, get to point |
-| **Visual** | Use emojis (✅🔄⏳❌) for quick scanning |
-| **Specific** | "~2 minutes" not "wait a bit" |
-| **Alternatives** | Offer multiple paths when stuck |
-| **Proactive** | Suggest next step after completion |
+| Principle        | Implementation                           |
+| ---------------- | ---------------------------------------- |
+| **Concise**      | No unnecessary details, get to point     |
+| **Visual**       | Use emojis (✅🔄⏳❌) for quick scanning |
+| **Specific**     | "~2 minutes" not "wait a bit"            |
+| **Alternatives** | Offer multiple paths when stuck          |
+| **Proactive**    | Suggest next step after completion       |
 
 ---
 
 ## Anti-Patterns (AVOID)
 
-| Anti-Pattern | Why |
-|--------------|-----|
+| Anti-Pattern                              | Why                          |
+| ----------------------------------------- | ---------------------------- |
 | Jumping to solutions before understanding | Wastes time on wrong problem |
-| Assuming requirements without asking | Creates wrong output |
-| Over-engineering first version | Delays value delivery |
-| Ignoring constraints | Creates unusable solutions |
-| "I think" phrases | Uncertainty → Ask instead |
+| Assuming requirements without asking      | Creates wrong output         |
+| Over-engineering first version            | Delays value delivery        |
+| Ignoring constraints                      | Creates unusable solutions   |
+| "I think" phrases                         | Uncertainty → Ask instead    |
+
+---
+
+## ⛔ HARD-GATE: No Code Before Design Approval
+
+> Adapted from obra/superpowers.
+
+Do NOT write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+
+**"Simple" projects are where unexamined assumptions cause the most wasted work.** The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+---
+
+## Propose Approaches
+
+Before settling on a design:
+
+1. **Propose 2-3 different approaches** with trade-offs
+2. **Lead with your recommendation** and explain why
+3. **Present options conversationally** — not exhaustive specs
+4. **Wait for user preference** before detailing the chosen approach
+
+---
+
+## Design Document
+
+After the user approves the design:
+
+1. Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md` (or project root as `{task-slug}.md`)
+2. Commit the design document
+3. **Transition to implementation** — invoke `plan-writing` skill to create detailed implementation plan
+
+> 🔴 **The terminal state of brainstorming is always `plan-writing`.** Do NOT invoke any implementation skill directly from brainstorming.
 
 ---
+
+## Integration
+
+| Skill                     | Relationship                              |
+| ------------------------- | ----------------------------------------- |
+| `plan-writing`            | Next step after design approval           |
+| `executing-plans`         | Executes the plan created by plan-writing |
+| `test-driven-development` | Referenced in plan tasks                  |

package/templates/skills/knowledge/executing-plans/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: executing-plans
+description: Structured plan execution with batch checkpoints or subagent-per-task with two-stage review. Use when you have a written implementation plan to execute methodically.
+version: 1.0.0
+---
+
+# Executing Plans
+
+> Adapted from obra/superpowers — fitted to the agi multi-platform architecture.
+
+## Overview
+
+Load a plan, review it critically, then execute tasks using one of two strategies. Report for review between batches.
+
+**Core principle:** Batch execution with quality gates. Never skip verification.
+
+---
+
+## When to Use
+
+| Scenario                                  | Strategy                                                |
+| ----------------------------------------- | ------------------------------------------------------- |
+| Have a plan, tasks are mostly independent | **Subagent-Driven** (two-stage review per task)         |
+| Have a plan, prefer human checkpoints     | **Batch Execution** (3 tasks at a time, review between) |
+| No plan exists                            | STOP → Use `plan-writing` skill first                   |
+
+---
+
+## The Process
+
+### Step 1: Load and Review Plan
+
+1. Read the plan file
+2. Review critically — identify questions or concerns
+3. If concerns: **Raise them with the user before starting**
+4. If clear: Create task tracker and proceed
+
+> 🔴 **VIOLATION:** Starting execution with unresolved questions = failed execution.
+
+### Step 2: Choose Execution Mode
+
+**Option A — Batch Execution (human checkpoints):**
+
+- Execute first 3 tasks
+- Report what was done + verification output
+- Wait for feedback → apply changes → next batch
+- Best for: high-risk changes, unfamiliar codebases
+
+**Option B — Subagent-Driven (two-stage review):**
+
+- Fresh context per task (no context pollution)
+- Implementer → Spec Reviewer → Code Quality Reviewer chain
+- Faster iteration, review is automated
+- Best for: independent tasks, well-defined plan
+
+### Step 3: Execute Tasks
+
+**For each task:**
+
+1. Mark as `[/]` in-progress
+2. Follow each step exactly (plan has granular steps)
+3. Run verifications as specified in the plan
+4. Mark as `[x]` completed
+
+### Step 4: Report (Batch Mode)
+
+After each batch of 3 tasks:
+
+```markdown
+## Batch N Complete
+
+### Implemented
+
+- Task X: [what was done]
+- Task Y: [what was done]
+- Task Z: [what was done]
+
+### Verification Output
+
+[Paste actual command output]
+
+### Status
+
+Ready for feedback.
+```
+
+### Step 5: Complete Development
+
+After all tasks complete and verified:
+
+- Run full verification suite (`verify_all.py` or project test suite)
+- Use `verification-before-completion` skill before claiming done
+- Present summary and next steps
+
+---
+
+## Two-Stage Review Protocol (Subagent-Driven Mode)
+
+For each task, three roles execute in sequence:
+
+### 1. Implementer
+
+- Reads the task from the plan (full task text provided, never the plan file)
+- Asks clarifying questions if anything is unclear
+- Implements following TDD: write test → verify fail → implement → verify pass → commit
+- Self-reviews before handoff
+
+### 2. Spec Compliance Reviewer
+
+Reviews against the plan requirements:
+
+| Check                         | Pass | Fail                          |
+| ----------------------------- | ---- | ----------------------------- |
+| All requirements implemented? | ✅   | ❌ List missing items         |
+| Nothing extra added?          | ✅   | ❌ List additions not in spec |
+| Tests cover the requirement?  | ✅   | ❌ List gaps                  |
+
+**If issues found:** Implementer fixes → re-review until ✅
+
+### 3. Code Quality Reviewer
+
+Reviews implementation quality:
+
+| Check                                  | Pass | Fail                  |
+| -------------------------------------- | ---- | --------------------- |
+| Clean, readable code?                  | ✅   | ❌ List issues        |
+| No magic numbers, good naming?         | ✅   | ❌ List specifics     |
+| Edge cases handled?                    | ✅   | ❌ List missing cases |
+| Tests are meaningful (not mock-heavy)? | ✅   | ❌ List concerns      |
+
+**If issues found:** Implementer fixes → re-review until ✅
+
+> 🔴 **Order matters:** Spec compliance FIRST, then code quality. Never reverse.
+
+---
+
+## Red Flags — STOP Immediately
+
+- Starting implementation on main/master without user consent
+- Skipping either review stage (spec OR quality)
+- Proceeding with unfixed issues
+- Guessing when blocked instead of asking
+- Making the implementer read the full plan file (provide task text directly)
+- Accepting "close enough" on spec compliance
+- Moving to next task with open review issues
+
+---
+
+## When to Stop and Ask
+
+**STOP executing when:**
+
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing progress
+- You don't understand an instruction
+- Verification fails repeatedly (3+ times → question architecture)
+
+**Ask for clarification rather than guessing.**
+
+---
+
+## Platform Adaptation
+
+| Platform                      | Subagent-Driven                       | Batch Execution                   |
+| ----------------------------- | ------------------------------------- | --------------------------------- |
+| **Claude Code** (Agent Teams) | Teammates as implementer/reviewers    | Lead executes batches             |
+| **Claude Code** (Subagents)   | `Task()` tool for each role           | Direct execution with checkpoints |
+| **Gemini / Antigravity**      | Sequential persona switching per role | Direct execution with checkpoints |
+| **Kiro IDE**                  | Autonomous agent tasks                | Direct execution with PR reviews  |
+
+---
+
+## Integration
+
+| Skill                            | Relationship                         |
+| -------------------------------- | ------------------------------------ |
+| `plan-writing`                   | Creates the plan this skill executes |
+| `test-driven-development`        | TDD cycle used by implementers       |
+| `verification-before-completion` | Gate before claiming tasks complete  |
+| `parallel-agents`                | Platform detection for subagent mode |
+| `brainstorming`                  | Design phase before plan creation    |

package/templates/skills/knowledge/notebooklm-rag/SKILL.md

@@ -29,6 +29,49 @@ Agent stores in Qdrant → cache for future use
 Agent responds to user with synthesized answer
 ```
 
+## Quick Start
+
+> [!IMPORTANT]
+> **Step 1: MCP Server Required.** The NotebookLM MCP server must be configured in your AI host. It is bundled with many setups, but verify it's running.
+
+### 1. Check if MCP is configured
+
+The agent should call `get_health`. If the tool exists, the MCP server is active.
+
+- ✅ `status: "ok"` → MCP is running
+- ❌ Tool not found → Add the MCP server to your host config (see [MCP Server Setup](#mcp-server-setup))
+
+### 2. Authenticate (one-time)
+
+```
+Agent calls: get_health
+If authenticated: false →
+  Agent calls: setup_auth (opens a browser window)
+  User logs into Google account
+  Agent calls: get_health to verify → authenticated: true ✅
+```
+
+> [!TIP]
+> Auth is saved to disk. You only need to log in once. If it expires, the agent will detect it and propose `re_auth`.
+
+### 3. Add a Notebook
+
+```
+User: "Here is my NotebookLM: https://notebooklm.google.com/notebook/..."
+Agent calls: ask_question(notebook_url=URL, question="What is the content? What topics?")
+Agent uses answer to fill: name, description, topics
+Agent calls: add_notebook(url, name, description, topics)
+```
+
+### 4. Query
+
+```
+User: "Research [topic] from my notebook"
+Agent calls: ask_question(notebook_id="my-notebook", question="...")
+```
+
+That's it. The agent handles everything else autonomously.
+
 ## MCP Tools Reference
 
 The agent has direct access to these tools. Use them autonomously.
@@ -71,11 +114,24 @@ The agent has direct access to these tools. Use them autonomously.
 
 ## Autonomous Workflow
 
+### Auth Gate (Mandatory First Step)
+
+> [!CAUTION]
+> **ALWAYS check auth before any NotebookLM operation.** If `authenticated: false`, propose `setup_auth` to the user before proceeding. Never silently fail.
+
+```
+get_health → authenticated?
+  → true:  proceed to step 1
+  → false: tell user "NotebookLM needs authentication. A browser will open for Google login."
+            → setup_auth → get_health → verify authenticated: true
+            → if still false: propose cleanup_data(preserve_library=true) + setup_auth
+```
+
 ### On Any Research Request:
 
 1. **Check Qdrant first** — `memory_manager.py auto --query "..."`. If cache hit, return immediately.
 
-2. **Check auth** — `get_health`. If not authenticated, run `setup_auth` and tell user a browser will open.
+2. **Auth gate** — `get_health`. If not authenticated, run `setup_auth` and tell user a browser will open. **Do not proceed without auth.**
 
 3. **Resolve notebook** — `list_notebooks`. If user mentions a topic, `search_notebooks`. If no notebooks exist, ask user for a NotebookLM URL and `add_notebook`.
 

package/templates/skills/knowledge/parallel-agents/SKILL.md

@@ -445,3 +445,79 @@ After all agents/teammates complete, synthesize:
 5. **Single synthesis** — One unified report, not separate outputs
 6. **Verify changes** — Always include test-engineer for code modifications
 7. **Avoid file conflicts** — Assign non-overlapping file scopes to parallel agents
+
+---
+
+## Focused Agent Prompt Structure
+
+> Adapted from obra/superpowers — applies when dispatching parallel agents for independent problems.
+
+Good agent prompts are:
+
+1. **Focused** — One clear problem domain
+2. **Self-contained** — All context needed to understand the problem
+3. **Specific about output** — What should the agent return?
+
+```markdown
+[Clear problem description with specific scope]
+
+Context:
+
+- [Error messages, test names, or specific symptoms]
+- [Relevant file paths]
+
+Your task:
+
+1. [Specific investigation step]
+2. [Root cause analysis]
+3. [Fix with constraints]
+
+Constraints:
+
+- [What NOT to change]
+- [Scope boundaries]
+
+Return: Summary of what you found and what you fixed.
+```
+
+### Common Mistakes
+
+| ❌ Bad                                      | ✅ Good                                        |
+| ------------------------------------------- | ---------------------------------------------- |
+| "Fix all the tests" (too broad)             | "Fix agent-tool-abort.test.ts" (focused scope) |
+| "Fix the race condition" (no context)       | Paste error messages and test names            |
+| No constraints (agent refactors everything) | "Do NOT change production code"                |
+| "Fix it" (vague output)                     | "Return summary of root cause and changes"     |
+
+---
+
+## When NOT to Use Parallel Agents
+
+| Scenario                  | Why                                         | Do Instead                       |
+| ------------------------- | ------------------------------------------- | -------------------------------- |
+| **Related failures**      | Fixing one might fix others                 | Investigate together first       |
+| **Need full context**     | Understanding requires seeing entire system | Single agent investigates all    |
+| **Exploratory debugging** | You don't know what's broken yet            | Use `systematic-debugging` skill |
+| **Shared state**          | Agents would interfere (editing same files) | Sequential execution             |
+
+---
+
+## Review and Integrate Protocol
+
+After all agents/teammates complete:
+
+1. **Review each summary** — Understand what changed
+2. **Check for conflicts** — Did agents edit overlapping code?
+3. **Run full test suite** — Verify all fixes work together
+4. **Spot check** — Agents can make systematic errors
+5. **Use `verification-before-completion`** — Evidence before claiming success
+
+---
+
+## Integration
+
+| Skill                            | Relationship                            |
+| -------------------------------- | --------------------------------------- |
+| `executing-plans`                | Plan execution with subagent modes      |
+| `systematic-debugging`           | For investigation before parallel fixes |
+| `verification-before-completion` | Gate after integration                  |