@adityaaria/spark 6.0.17 → 6.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adityaaria/spark",
-  "version": "6.0.17",
+  "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.