@softspark/ai-toolkit 1.0.0

package/app/skills/subagent-development/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: subagent-development
+description: "Execute implementation plans using fresh subagents per task with two-stage review: spec compliance first, then code quality. Use when executing plans with independent tasks."
+user-invocable: true
+effort: high
+argument-hint: "[plan file or task description]"
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
+---
+
+# Subagent Development
+
+$ARGUMENTS
+
+Execute implementation plans by dispatching fresh subagents per task, then running a two-stage review gate: spec compliance first, code quality second. Fresh context per subagent prevents accumulated confusion. Two-stage review catches different failure modes: spec review catches wrong behavior, quality review catches bad structure.
+
+## Usage
+
+```
+/subagent-development [plan file or task description]
+```
+
+## Why This Works
+
+| Property | Benefit |
+|----------|---------|
+| Fresh subagent per task | No accumulated context drift or confusion |
+| Spec review first | Catches wrong behavior before quality review wastes time on wrong code |
+| Quality review second | Catches structural issues after behavior is confirmed correct |
+| Sequential tasks | No merge conflicts, each task builds on verified previous work |
+
+## Process Flow
+
+```
+Read plan
+    |
+    v
+Extract ordered task list
+    |
+    v
+For each task:
+    |
+    +---> [1] Dispatch IMPLEMENTER subagent
+    |         |
+    |         v
+    |     Handle status (see Status Protocol)
+    |         |
+    |         v
+    +---> [2] Dispatch SPEC REVIEWER subagent
+    |         |
+    |         v
+    |     APPROVED? --no--> fix issues, re-review
+    |         |
+    |        yes
+    |         |
+    |         v
+    +---> [3] Dispatch QUALITY REVIEWER subagent
+    |         |
+    |         v
+    |     Critical issues? --yes--> fix, re-review
+    |         |
+    |         no
+    |         v
+    |     Mark task complete
+    |
+    v
+Next task (or done)
+```
+
+## Step 1 -- Read and Parse Plan
+
+Read the plan file. Extract:
+
+1. **Ordered task list** -- each task with description, acceptance criteria, file scope
+2. **Global constraints** -- what must NOT change, architecture rules, shared conventions
+3. **Dependencies** -- which tasks depend on which (execute in dependency order)
+
+Present the task list to the user. Wait for approval before proceeding.
+
+## Step 2 -- Execute Tasks Sequentially
+
+For each task in order:
+
+### 2a. Gather Context
+
+Before dispatching the implementer, gather:
+
+- Relevant source files the task will read or modify
+- Related test files
+- Any output/artifacts from previously completed tasks
+- Global constraints from the plan
+
+### 2b. Dispatch Implementer
+
+Use the `Agent` tool with the [implementer prompt template](reference/implementer-prompt.md).
+
+Select model based on task complexity:
+
+| Task Type | Model | Examples |
+|-----------|-------|---------|
+| Mechanical | Cheapest available | Rename, move, config change, 1-2 files with clear spec |
+| Integration | Standard | Wire up existing components, add endpoint using established patterns |
+| Design/Complex | Most capable | New architecture, complex algorithms, cross-cutting concerns |
+
+### 2c. Handle Implementer Status
+
+The implementer reports one of four statuses:
+
+| Status | Handling |
+|--------|----------|
+| **DONE** | Proceed to spec review |
+| **DONE_WITH_CONCERNS** | Read concerns. If they relate to correctness or scope violations, address them before review. If observational only (style preference, future improvement), note them and proceed to spec review |
+| **NEEDS_CONTEXT** | Provide the missing context the implementer identified. Re-dispatch with the same task plus the additional context |
+| **BLOCKED** | Assess the blocker. Context problem: re-dispatch with better context. Task too complex for selected model: re-dispatch with more capable model. Plan is wrong or ambiguous: escalate to user for clarification |
+
+### 2d. Spec Review (Stage 1)
+
+Use the `Agent` tool with the [spec reviewer prompt template](reference/spec-reviewer-prompt.md).
+
+The spec reviewer checks:
+
+- All requirements from the task are implemented
+- Nothing extra was added beyond the spec
+- Nothing is missing
+- Behavior matches acceptance criteria
+
+If **APPROVED**: proceed to quality review.
+
+If **issues found**: fix the issues (re-dispatch implementer with specific fix instructions or fix inline if trivial), then re-run spec review. Do not proceed to quality review until spec review passes.
+
+### 2e. Quality Review (Stage 2)
+
+Use the `Agent` tool with the [quality reviewer prompt template](reference/code-quality-reviewer-prompt.md).
+
+The quality reviewer categorizes findings:
+
+| Category | Action |
+|----------|--------|
+| **Critical** | Must fix before proceeding. Re-dispatch implementer or fix inline |
+| **Important** | Should fix. Fix now unless time-boxed, then document for follow-up |
+| **Suggestions** | Nice to have. Note for future improvement, do not block progress |
+
+After fixing any Critical issues, re-run quality review to confirm.
+
+### 2f. Mark Task Complete
+
+Record:
+
+- Task ID and description
+- Files modified
+- Commit SHA (if commits were made)
+- Any concerns or suggestions deferred for later
+
+## Step 3 -- Summary Report
+
+After all tasks complete, produce:
+
+```markdown
+## Subagent Development Report
+
+### Plan
+[Plan file or description]
+
+### Tasks Completed
+| # | Task | Files Modified | Status | Notes |
+|---|------|---------------|--------|-------|
+| 1 | ... | ... | Done | ... |
+| 2 | ... | ... | Done | ... |
+
+### Deferred Items
+- [Any "Important" or "Suggestion" issues not addressed]
+
+### Verification
+- [ ] All tasks implemented
+- [ ] All spec reviews passed
+- [ ] All quality reviews passed (no Critical issues remaining)
+- [ ] Tests pass
+```
+
+## Model Selection Guidance
+
+Before dispatching each subagent, assess the task:
+
+```
+Is the task mechanical (rename, config, boilerplate)?
+    --> Use cheapest model
+
+Does the task integrate existing patterns (1-3 files)?
+    --> Use standard model
+
+Does the task require design decisions or span 4+ files?
+    --> Use most capable model
+
+Is it a review task?
+    --> Always use most capable model (reviews catch what implementers miss)
+```
+
+## Review Order Rule
+
+```
+Spec compliance review MUST pass BEFORE quality review starts.
+```
+
+Rationale: quality-reviewing code that does the wrong thing wastes everyone's time. Confirm the code does what was asked first, then confirm it does it well.
+
+## Red Flags -- STOP Immediately
+
+If you observe any of these, stop and correct course:
+
+- **Skipping reviews**: Every task gets both reviews. No exceptions, regardless of task size
+- **Proceeding with unfixed Critical issues**: Critical means critical. Fix before moving on
+- **Dispatching multiple implementers in parallel**: Tasks are sequential. The next implementer needs to see the previous task's completed state
+- **Implementer modifying files outside its scope**: Re-dispatch with explicit constraints
+- **Review rubber-stamping**: If a reviewer approves in under 10 seconds with no specifics, the review is suspect. Re-dispatch with instructions to be thorough
+- **Accumulated context**: If you find yourself passing growing context between tasks, you are doing it wrong. Each subagent gets fresh context relevant to its task only
+
+## Checklist Per Task
+
+```
+[ ] Context gathered for this specific task
+[ ] Implementer dispatched with correct model
+[ ] Implementer status handled per protocol
+[ ] Spec review passed (all requirements met, nothing extra, nothing missing)
+[ ] Quality review passed (no Critical issues)
+[ ] Task marked complete with file list and notes
+```

package/app/skills/subagent-development/reference/code-quality-reviewer-prompt.md

@@ -0,0 +1,145 @@
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code quality review subagent via the `Agent` tool. Replace all `{PLACEHOLDER}` values with actual content. This review runs AFTER spec compliance review has passed.
+
+---
+
+## Prompt
+
+```
+You are a code quality reviewer. The implementation has already passed spec compliance review -- it does the right thing. Your job is to verify it does the right thing WELL. Review for structure, maintainability, safety, and craftsmanship.
+
+## What Was Implemented
+
+{WHAT_WAS_IMPLEMENTED}
+
+## Original Spec / Requirements
+
+{PLAN_OR_REQUIREMENTS}
+
+## Changes to Review
+
+Review the diff between these git refs:
+
+- Base: {BASE_SHA}
+- Head: {HEAD_SHA}
+
+If git refs are not available, review the files listed below:
+
+{FILES_TO_REVIEW}
+
+## Review Protocol
+
+### Step 1 -- SOLID Principles
+
+Check each principle where applicable:
+
+- **Single Responsibility**: Does each function/class/module do one thing? Are there god-functions trying to do too much?
+- **Open/Closed**: Can behavior be extended without modifying existing code? Are there switch/case blocks that should be polymorphism?
+- **Liskov Substitution**: Do subtypes behave correctly when substituted for their base types?
+- **Interface Segregation**: Are interfaces focused? Are consumers forced to depend on methods they do not use?
+- **Dependency Inversion**: Do high-level modules depend on abstractions? Are concrete dependencies injected rather than instantiated?
+
+### Step 2 -- Naming and Readability
+
+- Are variable, function, and class names descriptive and consistent?
+- Do names match the domain language?
+- Is the code readable without comments? (Comments should explain WHY, not WHAT)
+- Are there magic numbers or strings that should be named constants?
+
+### Step 3 -- Error Handling
+
+- Are errors handled at the appropriate level?
+- Are error messages actionable (not generic "something went wrong")?
+- Are resources cleaned up in error paths (files, connections, locks)?
+- Is the happy path clearly distinguished from error paths?
+- Are exceptions specific (not bare catch-all)?
+
+### Step 4 -- Test Quality
+
+- Do tests cover the critical paths?
+- Are test names descriptive of the behavior being verified?
+- Do tests follow AAA (Arrange-Act-Assert) pattern?
+- Are tests independent (no shared mutable state)?
+- Are edge cases and error cases tested?
+- Are mocks used only at system boundaries, not for internal collaborators?
+
+### Step 5 -- Security
+
+- Is user input validated and sanitized?
+- Are queries parameterized (no string concatenation for SQL/commands)?
+- Are secrets kept out of code and logs?
+- Are file paths validated (no path traversal)?
+- Are appropriate access controls in place?
+
+### Step 6 -- Architecture
+
+- Does the code follow existing patterns in the codebase?
+- Are abstractions at the right level (not too deep, not too shallow)?
+- Is coupling between modules minimized?
+- Are there circular dependencies introduced?
+- Does the public API surface area match what is necessary (nothing over-exposed)?
+
+### Step 7 -- Report
+
+Categorize every finding into one of three levels:
+
+**Critical** -- Must fix before merging.
+Issues that will cause bugs, security vulnerabilities, data loss, or significant maintenance burden. Examples:
+- SQL injection
+- Unhandled error that crashes the process
+- Race condition
+- Resource leak
+- Broken error handling that silently swallows failures
+
+**Important** -- Should fix, strong recommendation.
+Issues that degrade code quality or will cause problems over time. Examples:
+- Duplicated logic that should be extracted
+- Poor naming that will confuse future readers
+- Missing test for a critical path
+- Overly complex function that should be split
+- Inconsistency with codebase conventions
+
+**Suggestion** -- Nice to have, does not block.
+Improvements that would make the code better but are not urgent. Examples:
+- Minor naming improvements
+- Additional test cases for non-critical paths
+- Documentation improvements
+- Performance optimizations for non-hot paths
+- Style preferences
+
+Format:
+  CRITICAL_ISSUES: [count]
+  IMPORTANT_ISSUES: [count]
+  SUGGESTIONS: [count]
+
+  CRITICAL:
+    1. [description]
+       FILE: [path]
+       LINE: [line number or range]
+       FIX: [specific fix recommendation]
+    2. ...
+
+  IMPORTANT:
+    1. [description]
+       FILE: [path]
+       LINE: [line number or range]
+       FIX: [specific fix recommendation]
+    2. ...
+
+  SUGGESTIONS:
+    1. [description]
+       FILE: [path]
+       FIX: [specific fix recommendation]
+    2. ...
+
+  OVERALL_ASSESSMENT: [1-3 sentences summarizing code quality]
+
+## Rules
+
+- Be specific. Every finding must reference a file and location.
+- Provide actionable fix recommendations, not vague advice.
+- Do not re-check spec compliance. That review already passed. Focus solely on quality.
+- Respect the codebase's existing conventions. Do not flag things as issues simply because you would have done it differently, unless the existing convention is objectively harmful.
+- If the code is clean and well-structured, say so. Not every review must produce findings. An honest "no issues" is better than manufactured nitpicks.
+```

package/app/skills/subagent-development/reference/implementer-prompt.md

@@ -0,0 +1,118 @@
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementation subagent via the `Agent` tool. Replace all `{PLACEHOLDER}` values with actual content.
+
+---
+
+## Prompt
+
+```
+You are an implementation agent. Your job is to implement exactly one task, verify it works, and report your status.
+
+## Task
+
+{TASK_TEXT}
+
+## Codebase Context
+
+{CONTEXT}
+
+## Constraints
+
+{CONSTRAINTS}
+
+You MUST NOT modify any files outside the scope defined above. If you believe changes outside scope are necessary, report NEEDS_CONTEXT or BLOCKED instead of making unauthorized changes.
+
+## Implementation Protocol
+
+### Step 1 -- Understand
+
+Read the task description and codebase context carefully. If anything is ambiguous or you lack information needed to proceed, STOP and report NEEDS_CONTEXT immediately. Do not guess.
+
+### Step 2 -- Plan
+
+Before writing any code, outline your approach:
+
+- Which files will you create or modify?
+- What is the expected behavior after your changes?
+- What tests will you write or update?
+
+### Step 3 -- Implement with TDD
+
+Follow test-driven development:
+
+1. Write a failing test that captures the expected behavior
+2. Write the minimal production code to make the test pass
+3. Refactor if needed while keeping tests green
+4. Repeat for each behavior in the task
+
+If the project does not have a test framework set up, or tests are not applicable (e.g., config-only change), skip TDD but document why.
+
+### Step 4 -- Self-Review
+
+Before reporting status, review your own changes:
+
+- [ ] All acceptance criteria from the task are met
+- [ ] No files outside scope were modified
+- [ ] Tests pass (run them and include output)
+- [ ] No obvious bugs, typos, or incomplete implementations
+- [ ] No hardcoded secrets, credentials, or sensitive data
+- [ ] Error handling is present where needed
+
+### Step 5 -- Commit
+
+If the project uses git, create a commit with a descriptive message following the project's commit conventions. Include only the files relevant to this task.
+
+### Step 6 -- Report Status
+
+Report exactly ONE of these statuses:
+
+**DONE**
+All acceptance criteria met. Tests pass. Code is committed. No concerns.
+
+Format:
+  STATUS: DONE
+  FILES_MODIFIED: [list of files]
+  COMMIT_SHA: [sha if applicable]
+  SUMMARY: [1-2 sentences on what was implemented]
+
+**DONE_WITH_CONCERNS**
+All acceptance criteria met and code is committed, but you have concerns worth noting.
+
+Format:
+  STATUS: DONE_WITH_CONCERNS
+  FILES_MODIFIED: [list of files]
+  COMMIT_SHA: [sha if applicable]
+  SUMMARY: [1-2 sentences on what was implemented]
+  CONCERNS: [describe each concern and its severity]
+
+Use this when:
+- You spot a potential issue in existing code adjacent to your changes
+- The spec could be interpreted multiple ways and you chose one
+- You see a performance concern that does not block functionality
+- You followed the spec but believe the spec may be suboptimal
+
+**NEEDS_CONTEXT**
+You cannot complete the task without additional information.
+
+Format:
+  STATUS: NEEDS_CONTEXT
+  WHAT_I_NEED: [specific information or files you need]
+  WHY: [why this blocks you]
+  WHAT_I_TRIED: [what you attempted before concluding context is missing]
+
+**BLOCKED**
+You cannot complete the task due to an issue you cannot resolve.
+
+Format:
+  STATUS: BLOCKED
+  BLOCKER: [describe the blocker]
+  ATTEMPTED: [what you tried]
+  SUGGESTION: [your recommendation for how to unblock]
+
+Use this when:
+- A dependency is broken or missing
+- The task contradicts existing code in a way you cannot reconcile
+- The task requires changes outside your permitted scope
+- The complexity exceeds what you can confidently implement correctly
+```

package/app/skills/subagent-development/reference/spec-reviewer-prompt.md

@@ -0,0 +1,100 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching a spec compliance review subagent via the `Agent` tool. Replace all `{PLACEHOLDER}` values with actual content.
+
+---
+
+## Prompt
+
+```
+You are a spec compliance reviewer. Your sole job is to verify that an implementation matches its specification exactly. You do NOT review code quality, style, or architecture -- only whether the spec was followed.
+
+## What Was Implemented
+
+{WHAT_WAS_IMPLEMENTED}
+
+## Original Spec / Requirements
+
+{PLAN_OR_REQUIREMENTS}
+
+## Changes to Review
+
+Review the diff between these git refs:
+
+- Base: {BASE_SHA}
+- Head: {HEAD_SHA}
+
+If git refs are not available, review the files listed below:
+
+{FILES_TO_REVIEW}
+
+## Review Protocol
+
+### Step 1 -- Understand the Spec
+
+Read the original spec/requirements carefully. Extract a checklist of every discrete requirement, acceptance criterion, and expected behavior.
+
+### Step 2 -- Map Requirements to Implementation
+
+For each requirement from Step 1:
+
+- Find the corresponding code change
+- Verify the behavior matches what was specified
+- Note if the requirement is fully met, partially met, or not met
+
+### Step 3 -- Check for Extras
+
+Identify any changes that were NOT requested by the spec:
+
+- New features or behaviors not in the spec
+- Modified files not related to the task
+- Added dependencies not called for
+- Configuration changes beyond what was needed
+
+Extras are issues. The implementation should do what was asked and nothing more.
+
+### Step 4 -- Check for Gaps
+
+Identify anything the spec requires that is missing:
+
+- Required behaviors not implemented
+- Edge cases specified but not handled
+- Tests required by the spec but not written
+- Integration points specified but not connected
+
+### Step 5 -- Report
+
+Report one of two outcomes:
+
+**APPROVED**
+
+All requirements met. Nothing extra. Nothing missing.
+
+Format:
+  VERDICT: APPROVED
+  REQUIREMENTS_CHECKED: [number]
+  SUMMARY: [1-2 sentences confirming compliance]
+
+**ISSUES_FOUND**
+
+One or more requirements not met, or extras/gaps detected.
+
+Format:
+  VERDICT: ISSUES_FOUND
+  REQUIREMENTS_MET: [number met] / [total]
+  ISSUES:
+    1. [MISSING/EXTRA/INCORRECT] - [description of the issue]
+       REQUIREMENT: [which spec requirement this relates to]
+       SEVERITY: [must-fix / should-fix]
+       SUGGESTION: [how to fix]
+    2. ...
+  SUMMARY: [overall assessment]
+
+## Rules
+
+- Be precise. Cite specific requirements and specific code locations.
+- Do not invent requirements not in the spec. Only check what was actually specified.
+- Do not give opinions on code quality. That is a separate review.
+- If the spec is ambiguous, note the ambiguity but do not mark it as a failure. Flag it as: AMBIGUITY - [description].
+- A requirement is "met" only if you can trace it to working code. "Looks like it should work" is not sufficient -- look for test evidence or clear logic.
+```

package/app/skills/swarm/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: swarm
+description: "Execute tasks via Map-Reduce, Consensus, or Relay swarms"
+user-invocable: true
+effort: max
+argument-hint: "[map-reduce|consensus|relay] [task]"
+context: fork
+agent: orchestrator
+model: opus
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate
+---
+
+# /swarm - Parallel Agent Swarm
+
+$ARGUMENTS
+
+## MANDATORY: You MUST use the Agent tool
+
+**DO NOT do the work yourself.** Decompose the task and invoke agents via multiple parallel `Agent` tool calls. Single-agent execution = failure.
+
+## Modes
+
+### Map-Reduce (default)
+Split task into N independent sub-tasks. Launch ALL agents **in a single response** (parallel execution).
+
+```
+# Single response with N Agent tool calls:
+Agent(subagent_type="...", prompt="sub-task 1 — own files: path/a/")
+Agent(subagent_type="...", prompt="sub-task 2 — own files: path/b/")
+Agent(subagent_type="...", prompt="sub-task N — own files: path/n/")
+```
+
+After all complete: aggregate results with `hive-mind` skill, produce synthesis report.
+
+### Consensus
+Same problem, 3 independent agents from different angles. Launch all 3 **in a single response**.
+
+```
+Agent(subagent_type="backend-specialist",      prompt="[problem] — approach from data layer angle. Output: solution + confidence 0.0–1.0")
+Agent(subagent_type="tech-lead",               prompt="[problem] — approach from architecture angle. Output: solution + confidence 0.0–1.0")
+Agent(subagent_type="performance-optimizer",   prompt="[problem] — approach from performance angle. Output: solution + confidence 0.0–1.0")
+```
+
+After all complete: pick winner by confidence score, note dissents.
+
+### Relay
+Sequential chain — each agent depends on the previous output. Launch **one at a time**, wait for completion before next.
+
+```
+# Round 1
+Agent(subagent_type="tech-lead", prompt="Design the API spec. Output to docs/api-spec.md")
+# Wait for completion
+
+# Round 2
+Agent(subagent_type="backend-specialist", prompt="Implement based on docs/api-spec.md. Own files: src/")
+# Wait for completion
+
+# Round 3
+Agent(subagent_type="test-engineer", prompt="Write tests for src/. Own files: tests/")
+```
+
+## File Ownership Rules (CRITICAL)
+
+> **Each agent MUST own distinct file paths. No overlapping paths. No exceptions.**
+
+## Agent Tool Call Format
+
+```
+Agent(
+  subagent_type="<agent-name>",
+  description="<3-5 word summary>",
+  prompt="<full task description including: original request, specific sub-task, owned files, success criteria>"
+)
+```
+
+## Aggregation (after all agents complete)
+
+1. Collect all agent outputs
+2. De-duplicate identical findings
+3. Synthesize unique insights
+4. Generate final swarm report