@adityaaria/spark 6.0.16 → 6.0.18

package/bin/spark-install.sh

@@ -23,10 +23,11 @@ readonly LOCK_FILE_NAME=".spark-lock.json"
 if [ -t 1 ]; then
   readonly C_RESET='\033[0m'
   readonly C_BOLD='\033[1m'
-  readonly C_GREEN='\033[0;32m'
-  readonly C_YELLOW='\033[0;33m'
-  readonly C_RED='\033[0;31m'
-  readonly C_CYAN='\033[0;36m'
+  readonly C_GREEN='\033[38;5;46m'       # 8-bit neon green
+  readonly C_YELLOW='\033[38;5;226m'      # 8-bit bright yellow
+  readonly C_RED='\033[38;5;196m'         # 8-bit bright red
+  readonly C_CYAN='\033[38;5;51m'         # 8-bit cyan
+  readonly C_MAGENTA='\033[38;5;201m'     # 8-bit magenta
   readonly C_DIM='\033[2m'
 else
   readonly C_RESET=''
@@ -35,6 +36,7 @@ else
   readonly C_YELLOW=''
   readonly C_RED=''
   readonly C_CYAN=''
+  readonly C_MAGENTA=''
   readonly C_DIM=''
 fi
 
@@ -46,15 +48,19 @@ readonly EXIT_NO_REPO=3
 readonly EXIT_INSTALL_FAILED=4
 
 # =============================================================================
-# Output helpers
+# Output helpers (8-Bit Theme)
 # =============================================================================
 
-info()    { printf "${C_CYAN}▸${C_RESET} %s\n" "$*"; }
-success() { printf "${C_GREEN}✔${C_RESET} %s\n" "$*"; }
-warn()    { printf "${C_YELLOW}⚠${C_RESET} %s\n" "$*" >&2; }
-error()   { printf "${C_RED}✖${C_RESET} %s\n" "$*" >&2; }
-step()    { printf "${C_BOLD}[%s/%s]${C_RESET} %s\n" "$1" "$2" "$3"; }
-header()  { printf "\n${C_BOLD}═══ %s ═══${C_RESET}\n\n" "$*"; }
+info()    { printf "${C_CYAN}►${C_RESET} %s\n" "$*"; }
+success() { printf "${C_GREEN}★${C_RESET} %s\n" "$*"; }
+warn()    { printf "${C_YELLOW}▲${C_RESET} %s\n" "$*" >&2; }
+error()   { printf "${C_RED}[X]${C_RESET} %s\n" "$*" >&2; }
+step()    { printf "${C_MAGENTA}[LVL %s/%s]${C_RESET} %s\n" "$1" "$2" "$3"; }
+header()  {
+  printf "\n${C_MAGENTA}▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄${C_RESET}\n"
+  printf "${C_MAGENTA}█${C_RESET} ${C_BOLD}%-35s${C_RESET} ${C_MAGENTA}█${C_RESET}\n" " $1 "
+  printf "${C_MAGENTA}▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀${C_RESET}\n\n"
+}
 
 # =============================================================================
 # Argument parsing
@@ -310,7 +316,7 @@ detect_agents() {
     info "Detected $detected_count agent(s):"
     for i in "${!AGENT_IDS[@]}"; do
       if [ "${AGENT_DETECTED[$i]}" = "true" ]; then
-        printf "  ${C_GREEN}●${C_RESET} %-15s ${C_DIM}(%s)${C_RESET}\n" "${AGENT_LABELS[$i]}" "${AGENT_REASONS[$i]}"
+        printf "  ${C_GREEN}■${C_RESET} %-15s ${C_DIM}(%s)${C_RESET}\n" "${AGENT_LABELS[$i]}" "${AGENT_REASONS[$i]}"
       fi
     done
   fi
@@ -765,7 +771,7 @@ print_summary() {
       method="$(echo "$entry" | cut -d: -f2)"
       local target_dir
       target_dir="$(get_target_dir "$agent_id")"
-      printf "    ${C_GREEN}●${C_RESET} %-15s → %s ${C_DIM}(%s)${C_RESET}\n" "$agent_id" "$target_dir" "$method"
+      printf "    ${C_GREEN}■${C_RESET} %-15s → %s ${C_DIM}(%s)${C_RESET}\n" "$agent_id" "$target_dir" "$method"
     done
   fi
 
@@ -773,7 +779,7 @@ print_summary() {
     echo ""
     echo "  Errors:"
     for entry in "${INSTALL_ERRORS[@]}"; do
-      printf "    ${C_RED}●${C_RESET} %s\n" "$entry"
+      printf "    ${C_RED}■${C_RESET} %s\n" "$entry"
     done
   fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adityaaria/spark",
-  "version": "6.0.16",
+  "version": "6.0.18",
   "description": "SPARK skills and runtime bootstrap for coding agents",
   "type": "module",
   "publishConfig": {

package/skills/audit/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: audit
+description: Use to audit code quality, architecture, and security against the project's documented anti-patterns and standards.
+---
+
+# Audit (Meta-Skill)
+
+## Overview
+
+Use this skill to orchestrate a rigorous code review or architecture audit. You must NOT evaluate the code based on generic AI preferences or external "best practices" unless they align with the project's established rules. Your sole source of truth for the audit is the local knowledge base.
+
+**Announce at start:** "spark detection 💥 Using audit meta-skill to enforce project standards"
+
+## Standard Operating Procedure (SOP)
+
+You MUST execute this checklist strictly in order. Do not skip steps.
+
+### Phase 1: Context Grounding
+- `[ ]` **Step 1:** Read the local knowledge base located in `.docs/` (generated by the `project-scanner` skill). Focus heavily on `STANDARDS.md`, API contracts, and the list of Legacy Traps / Anti-patterns.
+- `[ ]` **Step 2:** Identify the exact boundaries of the code to be audited (e.g., a specific Pull Request, a newly written module, or a suspected legacy file).
+
+### Phase 2: Tactical Delegation (Review)
+- `[ ]` **Step 3:** Invoke the `receiving-code-review` (or `requesting-code-review` depending on your role) skill to structure your feedback.
+- `[ ]` **Step 4:** Compare the target code strictly against the Legacy Traps found in Phase 1. Actively flag any re-introduction of:
+  - Business logic leaks.
+  - Raw SQL/ORM mixing or N+1 queries.
+  - Undocumented bypass comments (`@ts-ignore`, `// HACK`).
+
+### Phase 3: Reporting
+- `[ ]` **Step 5:** Output an Audit Report summarizing the violations. If the code is clean, explicitly state that it complies with the `.docs/` standards.

package/skills/bug-fix/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: bug-fix
+description: Use to fix a bug while adhering strictly to the project's established standards and debugging protocols.
+---
+
+# Bug Fix (Meta-Skill)
+
+## Overview
+
+Use this skill to orchestrate a safe, standard-compliant bug fix. You are not allowed to blindly modify code based on assumptions. You must first ground yourself in the project's context, trace the bug systematically, and execute the fix using disciplined test-driven practices.
+
+**Announce at start:** "spark detection 💥 Using bug-fix meta-skill to coordinate this investigation"
+
+## Standard Operating Procedure (SOP)
+
+You MUST execute this checklist strictly in order. Do not skip steps.
+
+### Phase 1: Context Grounding
+Before touching any code, you must understand the rules of this repository.
+- `[ ]` **Step 1:** Read the local knowledge base located in `.docs/` (generated by the `project-scanner` skill). Specifically, look for `PROJECT_SCAN.md`, `STANDARDS.md`, and `API_CONTRACT.md`.
+- `[ ]` **Step 2:** Identify any Legacy Traps or Anti-Patterns documented in `.docs/`. You must NOT re-introduce these patterns while fixing the bug.
+
+### Phase 2: Tactical Delegation (Investigation)
+Do not guess the root cause. Delegate the investigation.
+- `[ ]` **Step 3:** Invoke the `systematic-debugging` skill. Follow its rigorous condition-based waiting and root-cause tracing protocols to find exactly what is broken.
+- `[ ]` *(Optional)*: If the bug spans multiple independent services, invoke `dispatching-parallel-agents` to investigate them concurrently.
+
+### Phase 3: Execution
+Once the root cause is proven (not guessed), fix it safely.
+- `[ ]` **Step 4:** Invoke the `test-driven-development` skill. Write a failing test that reproduces the bug, then implement the minimal code required to make it pass. Ensure your fix aligns with the architecture rules read in Phase 1.

package/skills/enhancement/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: enhancement
+description: Use to build a new feature or enhancement by aligning strictly with the project's existing business flow and domain architecture.
+---
+
+# Enhancement (Meta-Skill)
+
+## Overview
+
+Use this skill to orchestrate the safe addition of new features. Do not inject your own architectural preferences. You must ground yourself in the project's reality, scope the feature thoughtfully, plan it out, and execute it using the project's established conventions.
+
+**Announce at start:** "spark detection 💥 Using enhancement meta-skill to coordinate feature development"
+
+## Standard Operating Procedure (SOP)
+
+You MUST execute this checklist strictly in order. Do not skip steps.
+
+### Phase 1: Context Grounding
+- `[ ]` **Step 1:** Read the local knowledge base located in `.docs/` (generated by the `project-scanner` skill). Focus heavily on `BUSINESS_FLOW.md` and `DOMAINS/`.
+- `[ ]` **Step 2:** Determine which existing Domain will own this new feature, or if a completely new Domain is justified. Ensure your design respects the existing boundaries.
+
+### Phase 2: Tactical Delegation (Scoping & Planning)
+- `[ ]` **Step 3:** Invoke the `brainstorming` skill to map out edge cases, UX flows, and failure modes for this enhancement.
+- `[ ]` **Step 4:** Invoke the `writing-plans` skill to create a step-by-step implementation plan (saving to `docs/spark/plans/`). The plan MUST adhere to the standards found in Phase 1.
+
+### Phase 3: Execution
+- `[ ]` **Step 5:** Invoke the `executing-plans` skill to write the code.
+- `[ ]` *(Optional)*: If the enhancement is massive (e.g., touching frontend UI, backend API, and database migrations simultaneously), invoke `dispatching-parallel-agents` to delegate the sub-tasks to specialized subagents.

package/skills/project-scanner/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: project-scanner
+description: Use when analyzing an undocumented, legacy, or new project repository to extract its architectural and operational DNA.
+---
+
+# Project Scanner
+
+## Overview
+
+Use this skill to scan and document a codebase's architecture, operational rules, and hidden legacy traps. You must rely on file reading and listing tools rather than making assumptions. Traverse the root directory and key source directories to extract the project's DNA. This skill is polyglot—it applies to any tech stack (e.g., TypeScript, Go, Python, Java, PHP, Rust).
+
+**Announce at start:** "spark detection 💥 Using project-scanner to analyze repository DNA"
+
+**Save findings to:** The `.docs/` directory. Create it if it does not exist. For large projects, break down the documentation logically (e.g., `.docs/PROJECT_SCAN.md`, `.docs/API_CONTRACT.md`, `.docs/DOMAINS/`) instead of creating one massive monolithic file.
+
+## Handling Massive Codebases (Subagent Delegation)
+If the repository is extremely large and analyzing all four pillars sequentially risks exceeding context limits or taking too long:
+- Invoke the `dispatching-parallel-agents` skill.
+- Delegate specific analytical tasks to specialized subagents in parallel (e.g., Subagent A extracts the API Contract, Subagent B extracts the Business Flow).
+- Compile their findings into the final `.docs/` reports.
+
+## Target Extraction Artifacts
+
+Your final analysis must thoroughly document these four pillars:
+
+### 1. API CONTRACT
+Identify how the application communicates internally and externally.
+- **Priority Target:** Actively search for Swagger (`swagger.yaml`, `swagger.json`) or OpenAPI specifications. These are the single source of truth for the API contract.
+- **Secondary Targets:** Discover REST/GraphQL endpoints, gRPC protos, ORM schemas, Data Transfer Objects (DTOs), and core data models.
+- **Legacy Traps:** Flag any endpoints that violate current conventions or bypass standard authentication/validation layers.
+
+### 2. WORKFLOW
+Identify how the project is built, run, tested, and deployed.
+- **Targets:** CI/CD pipelines (e.g., `.github/workflows`, `.gitlab-ci.yml`), build scripts (Makefiles, Gradle, NPM scripts), Dockerfiles, and deployment scripts.
+- **Testing:** Identify the test framework, strategy (Unit, Integration, E2E), and explicitly highlight critical areas that lack test coverage.
+
+### 3. BUSINESS FLOW & DOMAINS
+Identify the core business logic and user journeys.
+- **Targets:** Core domains, domain services, use cases, and state machines.
+- **Domain Mapping:** Draft a list of business domains (e.g., Auth, Checkout, Inventory). Note their complexity, risk level, and the specific modules/packages that own them. Avoid forcing a domain split if the project is small.
+
+### 4. STANDARDS & ANTI-PATTERNS
+Identify conventions, rules, and technical debt enforced or found in the codebase.
+- **Targets:** Code styling conventions, linting rules, architectural patterns (e.g., MVC, Hexagonal, Clean Architecture).
+- **Anti-Pattern Detection (CRITICAL):** Actively search for and document legacy traps:
+  - Business logic leaked into controllers, presentation, or routing layers.
+  - Inconsistent database queries (e.g., raw queries mixed with ORM) or N+1 query problems.
+  - Misleading naming (e.g., `Utils` files containing heavy domain logic).
+  - Hardcoded external URLs, API keys, or magic numbers.
+  - Bypass comments (e.g., `@ts-ignore`, `// HACK`, `// FIXME`, `#nosec`) without explanations.
+  - Duplicated logic across modules.
+
+## Execution Checklist
+
+- `[ ]` **Step 1:** Announce skill usage exactly as required.
+- `[ ]` **Step 2:** Scan root configuration files and prioritize searching for Swagger/OpenAPI specifications.
+- `[ ]` **Step 3:** Scan source directory structures to infer the language, framework, and architectural patterns.
+- `[ ]` **Step 4:** Analyze testing frameworks, CI/CD workflows, and actively hunt for anti-patterns and legacy traps.
+- `[ ]` **Step 5:** Write the comprehensive report(s) into the `.docs/` directory.

package/skills/using-spark/SKILL.md

@@ -49,6 +49,10 @@ Skills speak in actions ("dispatch a subagent", "create a todo", "read a file")
 
 **Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
 
+## Announcement Format
+When you invoke a skill, you MUST announce it to the developer using exactly this format as the very first thing you say:
+`spark detection 💥 Using [skill] to [purpose]`
+
 ```dot
 digraph skill_flow {
     "User message received" [shape=doublecircle];
@@ -57,7 +61,7 @@ digraph skill_flow {
     "Invoke brainstorming skill" [shape=box];
     "Might any skill apply?" [shape=diamond];
     "Invoke the skill" [shape=box];
-    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Announce: 'spark detection 💥 Using [skill]...'" [shape=box];
     "Has checklist?" [shape=diamond];
     "Create a todo per item" [shape=box];
     "Follow skill exactly" [shape=box];
@@ -71,8 +75,8 @@ digraph skill_flow {
     "User message received" -> "Might any skill apply?";
     "Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"];
     "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
-    "Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
-    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Invoke the skill" -> "Announce: 'spark detection 💥 Using [skill]...'";
+    "Announce: 'spark detection 💥 Using [skill]...'" -> "Has checklist?";
     "Has checklist?" -> "Create a todo per item" [label="yes"];
     "Has checklist?" -> "Follow skill exactly" [label="no"];
     "Create a todo per item" -> "Follow skill exactly";