@dzhechkov/keysarium 1.7.18 → 1.7.19

package/.dz-manifest.json

@@ -9,7 +9,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "607fb5f6f05c073ece45cb0dc7d93133a2b8092f8803af38f1b62cfe63634ee0"
+        "sha256": "51d2b73ec4eac00bddd9e704bdacffb85724051e5df988635690bc8e8a903c61"
       },
       {
         "path": "README.ru.md",
@@ -21,7 +21,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "833c9ffe6b49c512ffc36c8b215ab56679c6a76b1d38c25d0fb4f8e7e2b2f52c"
+        "sha256": "4cf824362e1fe6fd033704beb7e9760d1045346c1ac371448fa10a29b992a296"
       },
       {
         "path": "src/cli.js",
@@ -33,7 +33,7 @@
       },
       {
         "path": "src/commands/init.js",
-        "sha256": "99e5466cc690382f8131f4c08239bcb703b4b9a0df534583060bc83b75abf904"
+        "sha256": "9ff67c6098f74978b80b34c2c761fa870a917b4fd1d73c985ebc2b9923c0d050"
       },
       {
         "path": "src/commands/list.js",
@@ -45,11 +45,11 @@
       },
       {
         "path": "src/commands/update.js",
-        "sha256": "8fb7a602452c228f2841170f09217f5523bd926f64180f4338348bd3a795bb79"
+        "sha256": "084cf3d3f7bf7899a98c3dffa2c9850da3528e8a0fab0bf2352120ef3899c301"
       },
       {
         "path": "src/utils.js",
-        "sha256": "a1b53cfbf211161b3cb219734184b065a49b636a4f45c6db0bc3f623a120d73b"
+        "sha256": "c76a4446d11f7a41b4ee3c16c4c653202ddc78399a1c0620c2dbe00153d70d72"
       },
       {
         "path": "templates/.agents/skills/casarium/SKILL.md",
@@ -61,7 +61,7 @@
       },
       {
         "path": "templates/.claude/agents/code-goal-planner.md",
-        "sha256": "fd6faca31bacfa3c70c0ff2a8ba152957d952b8590b4df0934ffd19af5078592"
+        "sha256": "1f510abfcee18c23f558efa6a25c34566397a9ee7ea6c799edd075d4273868db"
       },
       {
         "path": "templates/.claude/agents/discovery-worker.md",
@@ -393,7 +393,7 @@
       },
       {
         "path": "templates/.claude/skills/feature-adr/modules/06-implementation-plan.md",
-        "sha256": "5d092141e9e5f399ac2b7fbce9dced2094d50175b8d9355bf809c79a02d7590a"
+        "sha256": "eed9869118d865776dd3dea7688b5d597fc7f95b811d71069143006701b69974"
       },
       {
         "path": "templates/.claude/skills/feature-adr/modules/07-code.md",
@@ -1173,5 +1173,5 @@
       }
     ]
   },
-  "signature": "XOQDHt6LMUiK0ifYq/k9FeLlNm/abBOj2AjEIyr7PBOmSllQqiLWkBUIS5Sr40dinHaZj1/JG+mjvPHh9Ay+DA=="
+  "signature": "E/jEEzXydHzTaDLYBy4jD0qLKG7H8NAwCJAUlX+5jzkTtdLGe8T/6H85eV1yy+RLEq7yHKHHCc8BD8sPHZtkBQ=="
 }

package/README.md

@@ -5,7 +5,7 @@ The bundled Feature ADR projection supports installed-CLI native QE history opt-
 If bytes change before first evaluation, native `evaluate` retains valid old-snapshot receipt origins and conditions while reporting `not-established/native-repair-required`. Follow with explicit `begin-repair` and fresh independent verification of the new snapshot. Recovery preserves authority and the three-cycle ceiling; old evidence never closes changed bytes.
 
 
-Current package version: `1.7.18`. <!-- dz:version -->
+Current package version: `1.7.19`. <!-- dz:version -->
 
 Site: https://aicoding.space · Source: https://github.com/djd1m/dz-harness/tree/main/packages/keysarium
 
@@ -14,7 +14,7 @@ Site: https://aicoding.space · Source: https://github.com/djd1m/dz-harness/tree
 Full 7-phase pipeline for AI case studies, hackathons, and casariums. Provides skills, commands, rules, shards, agent templates, and brain portability. Claude Code uses `/casarium`; Codex uses a local `$casarium` skill that reads the same phase sources.
 
 The bundled feature-ADR reference mode includes eight full agentic-qe skill protocols pinned to upstream commit `0a6de058575cbe292afe220df105cc74120f7674`, with their output schemas, evals and supporting files. Keysarium-specific teaching notes are marked separately. The vendored references do not install the `aqe` executable, MCP tools, pattern memory or fleet runtime; direct `--full-qe` mode still requires agentic-qe to be installed.
-The existing `code-goal-planner` protocol is also installed as a Claude Code project agent; Step 6 uses its agent surface when available and keeps the same reference fallback for Codex.
+The complete pinned `code-goal-planner` protocol is installed as a Claude Code project agent with `model: sonnet`. Step 6 dispatches it only when that model matches the active planner route, checks its proposal against project evidence, and uses the reference directly in Codex or when the agent is unavailable.
 
 The bundled `analyst-manual-full` research checkpoint uses `moderate` for ordinary web and health
 sources. It offers `strict` or `paranoid` only when pinned issuer keys and signed delivery are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.7.18",
+  "version": "1.7.19",
   "scripts": {},
   "description": "AI Case Research Toolkit for Claude Code and Codex — full 7-phase pipeline with feature-adr, dream cycles, background workers, and Cloud.ru AI Factory mapping",
   "main": "src/cli.js",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "607fb5f6f05c073ece45cb0dc7d93133a2b8092f8803af38f1b62cfe63634ee0"
+          "content": "51d2b73ec4eac00bddd9e704bdacffb85724051e5df988635690bc8e8a903c61"
         }
       ]
     },
@@ -59,7 +59,7 @@
         },
         {
           "name": "dz:canonical-json-sha256-v2",
-          "value": "833c9ffe6b49c512ffc36c8b215ab56679c6a76b1d38c25d0fb4f8e7e2b2f52c"
+          "value": "4cf824362e1fe6fd033704beb7e9760d1045346c1ac371448fa10a29b992a296"
         }
       ]
     },
@@ -89,7 +89,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "99e5466cc690382f8131f4c08239bcb703b4b9a0df534583060bc83b75abf904"
+          "content": "9ff67c6098f74978b80b34c2c761fa870a917b4fd1d73c985ebc2b9923c0d050"
         }
       ]
     },
@@ -119,7 +119,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8fb7a602452c228f2841170f09217f5523bd926f64180f4338348bd3a795bb79"
+          "content": "084cf3d3f7bf7899a98c3dffa2c9850da3528e8a0fab0bf2352120ef3899c301"
         }
       ]
     },
@@ -129,7 +129,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a1b53cfbf211161b3cb219734184b065a49b636a4f45c6db0bc3f623a120d73b"
+          "content": "c76a4446d11f7a41b4ee3c16c4c653202ddc78399a1c0620c2dbe00153d70d72"
         }
       ]
     },
@@ -159,7 +159,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "fd6faca31bacfa3c70c0ff2a8ba152957d952b8590b4df0934ffd19af5078592"
+          "content": "1f510abfcee18c23f558efa6a25c34566397a9ee7ea6c799edd075d4273868db"
         }
       ]
     },
@@ -989,7 +989,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5d092141e9e5f399ac2b7fbce9dced2094d50175b8d9355bf809c79a02d7590a"
+          "content": "eed9869118d865776dd3dea7688b5d597fc7f95b811d71069143006701b69974"
         }
       ]
     },

package/src/commands/init.js

@@ -8,6 +8,7 @@ const {
   copyDirRecursive, copyDirTracked, fileExists, readJSON,
   ensureDir, getRelativePaths,
   createManifest, writeManifest, getTemplatesDir,
+  hashFile,
   COMPONENTS, MANIFEST_FILE,
 } = require('../utils');
 
@@ -165,6 +166,15 @@ async function run(options) {
   const version = pkg ? pkg.version : '0.0.0';
 
   const manifest = createManifest(version, componentKeys, installedFiles.sort());
+  // Only claim a baseline for the planner when the installed bytes equal the template.
+  // A pre-existing user file preserved by init must not be adopted as our version.
+  const plannerRel = path.join('.claude', 'agents', 'code-goal-planner.md');
+  const installedPlanner = path.join(targetDir, plannerRel);
+  const templatePlanner = path.join(templatesDir, plannerRel);
+  if (fileExists(installedPlanner) && fileExists(templatePlanner)
+      && hashFile(installedPlanner) === hashFile(templatePlanner)) {
+    manifest.templateHashes = { [plannerRel]: hashFile(templatePlanner) };
+  }
   writeManifest(targetDir, manifest);
   info('Created .keysarium.json manifest');
 

package/src/commands/update.js

@@ -7,6 +7,7 @@ const {
   info, success, warn, error: logError, step,
   copyDirRecursive, fileExists, readJSON,
   ensureDir, getRelativePaths, diffFiles,
+  hashFile,
   readManifest, writeManifest, getTemplatesDir,
   COMPONENTS, MANIFEST_FILE,
 } = require('../utils');
@@ -20,11 +21,11 @@ const {
  *
  * @param {object} options
  * @param {boolean} options.dryRun    — Preview without writing anything
- * @param {boolean} options.force     — Passed through (unused here)
+ * @param {boolean} options.force     — Back up and replace a locally edited planner agent
  * @param {string}  options.targetDir — Destination project root
  */
 async function run(options) {
-  const { dryRun, targetDir } = options;
+  const { dryRun, force, targetDir } = options;
   const manifestPath = path.join(targetDir, MANIFEST_FILE);
 
   // ── a) Read existing manifest ───────────────────────────────────────────
@@ -60,7 +61,11 @@ async function run(options) {
   let totalAdded = 0;
   let totalModified = 0;
   let totalUnchanged = 0;
+  let preservedPlanner = false;
   const filesToCopy = []; // { src, dest, status, relPath }
+  const plannerRel = path.join('.claude', 'agents', 'code-goal-planner.md');
+  // The unmodified wrapper shipped before the full agent was introduced.
+  const legacyPlannerHash = 'fd6faca31bacfa3c70c0ff2a8ba152957d952b8590b4df0934ffd19af5078592';
 
   for (const key of installedKeys) {
     const comp = COMPONENTS[key];
@@ -107,11 +112,24 @@ async function run(options) {
       }
 
       for (const rel of diff.modified) {
+        const relPath = path.join(comp.src, rel);
+        let backup = false;
+        if (relPath === plannerRel) {
+          const currentHash = hashFile(path.join(destBase, rel));
+          const baseline = manifest.templateHashes?.[plannerRel];
+          const clean = currentHash === baseline || (!baseline && currentHash === legacyPlannerHash);
+          if (!clean && !force) {
+            preservedPlanner = true;
+            continue;
+          }
+          backup = !clean;
+        }
         filesToCopy.push({
           src: path.join(srcBase, rel),
           dest: path.join(destBase, rel),
           status: 'modified',
-          relPath: path.join(comp.src, rel),
+          relPath,
+          backup,
         });
         totalModified++;
       }
@@ -125,6 +143,7 @@ async function run(options) {
   console.log(`  ${green('+')} ${totalAdded} file(s) to add`);
   console.log(`  ${yellow('~')} ${totalModified} file(s) to update`);
   console.log(`  ${dim('=')} ${totalUnchanged} file(s) unchanged`);
+  if (preservedPlanner) warn(`Local edit preserved: ${plannerRel}. Use --force to back up and replace it.`);
   console.log('');
 
   if (totalAdded === 0 && totalModified === 0) {
@@ -137,6 +156,7 @@ async function run(options) {
     for (const f of filesToCopy) {
       const marker = f.status === 'added' ? green('+ ADD') : yellow('~ MOD');
       console.log(`  ${marker}  ${f.relPath}`);
+      if (f.backup) console.log(`         backup: ${f.relPath}.bak`);
     }
     console.log('');
     warn('Dry run — no files were written.');
@@ -150,6 +170,7 @@ async function run(options) {
     step(i + 1, filesToCopy.length, `${label} ${f.relPath}`);
 
     ensureDir(path.dirname(f.dest));
+    if (f.backup) fs.copyFileSync(f.dest, `${f.dest}.bak`);
     fs.copyFileSync(f.src, f.dest);
   }
 
@@ -176,6 +197,12 @@ async function run(options) {
   manifest.version = newVersion;
   manifest.updatedAt = new Date().toISOString();
   manifest.files = allFiles.sort();
+  const installedPlanner = path.join(targetDir, plannerRel);
+  const templatePlanner = path.join(templatesDir, plannerRel);
+  if (fileExists(installedPlanner) && fileExists(templatePlanner)
+      && hashFile(installedPlanner) === hashFile(templatePlanner)) {
+    manifest.templateHashes = { ...manifest.templateHashes, [plannerRel]: hashFile(templatePlanner) };
+  }
 
   writeManifest(targetDir, manifest);
   info('Updated .keysarium.json manifest');

package/src/utils.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { createHash } = require('node:crypto');
 
 // ===========================================================================
 // Colors — ANSI escape codes (zero dependencies)
@@ -36,6 +37,10 @@ function step(n, total, msg) {
   console.log(cyan(`[${n}/${total}]`) + ' ' + msg);
 }
 
+function hashFile(file) {
+  return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
 // ===========================================================================
 // File operations — all synchronous, Node.js built-ins only
 // ===========================================================================
@@ -371,6 +376,7 @@ module.exports = {
   warn,
   error,
   step,
+  hashFile,
 
   // File operations
   copyDirRecursive,

package/templates/.claude/agents/code-goal-planner.md

@@ -1,9 +1,447 @@
 ---
 name: code-goal-planner
-description: Plans software changes with the bundled SPARC-GOAP protocol and testable milestones.
+description: "Code-centric Goal-Oriented Action Planning specialist that creates intelligent plans for software development objectives. Excels at breaking down complex coding tasks into achievable milestones with clear success criteria. Examples: <example>Context: User needs to implement a new authentication system. user: 'I need to add OAuth2 authentication to our API' assistant: 'I'll use the code-goal-planner agent to create a comprehensive implementation plan with milestones for OAuth2 integration, including provider setup, token management, and security considerations.' <commentary>Since this is a complex feature implementation, the code-goal-planner will break it down into testable milestones.</commentary></example> <example>Context: User wants to improve application performance. user: 'Our app is slow, we need to optimize database queries' assistant: 'I'll use the code-goal-planner agent to develop a performance optimization plan with measurable targets for query optimization, including profiling, indexing strategies, and caching implementation.' <commentary>Performance optimization requires systematic planning with clear metrics, perfect for code-goal-planner.</commentary></example>"
 color: blue
+model: sonnet
 ---
 
-Read `.claude/skills/feature-adr/references/agentic-qe/code-goal-planner.md` before planning. It is the canonical protocol for this project agent.
+You are a Code-Centric Goal-Oriented Action Planning (GOAP) specialist integrated with SPARC methodology, focused exclusively on software development objectives. You excel at transforming vague development requirements into concrete, achievable coding milestones using the systematic SPARC approach (Specification, Pseudocode, Architecture, Refinement, Completion) with clear success criteria and measurable outcomes.
 
-Use the feature requirements, ADR decisions, quality risks and current repository evidence to propose an ordered implementation plan. Give each milestone a deliverable and a check that could disprove completion. Identify unresolved inputs instead of inventing metrics or claiming that code has already been verified. Return the plan to Step 6 of feature-ADR; the lead checks it before recording the plan artifact.
+## SPARC-GOAP Integration
+
+The SPARC methodology enhances GOAP planning by providing a structured framework for each milestone:
+
+### SPARC Phases in Goal Planning
+
+1. **Specification Phase** (Define the Goal State)
+   - Analyze requirements and constraints
+   - Define success criteria and acceptance tests
+   - Map current state to desired state
+   - Identify preconditions and dependencies
+
+2. **Pseudocode Phase** (Plan the Actions)
+   - Design algorithms and logic flow
+   - Create action sequences
+   - Define state transitions
+   - Outline test scenarios
+
+3. **Architecture Phase** (Structure the Solution)
+   - Design system components
+   - Plan integration points
+   - Define interfaces and contracts
+   - Establish data flow patterns
+
+4. **Refinement Phase** (Iterate and Improve)
+   - TDD implementation cycles
+   - Performance optimization
+   - Code review and refactoring
+   - Edge case handling
+
+5. **Completion Phase** (Achieve Goal State)
+   - Integration and deployment
+   - Final testing and validation
+   - Documentation and handoff
+   - Success metric verification
+
+## Core Competencies
+
+### Software Development Planning
+- **Feature Implementation**: Break down features into atomic, testable components
+- **Bug Resolution**: Create systematic debugging and fixing strategies
+- **Refactoring Plans**: Design incremental refactoring with maintained functionality
+- **Performance Goals**: Set measurable performance targets and optimization paths
+- **Testing Strategies**: Define coverage goals and test pyramid approaches
+- **API Development**: Plan endpoint design, versioning, and documentation
+- **Database Evolution**: Schema migration planning with zero-downtime strategies
+- **CI/CD Enhancement**: Pipeline optimization and deployment automation goals
+
+### GOAP Methodology for Code
+
+1. **Code State Analysis**:
+   ```javascript
+   current_state = {
+     test_coverage: 45,
+     performance_score: 'C',
+     tech_debt_hours: 120,
+     features_complete: ['auth', 'user-mgmt'],
+     bugs_open: 23
+   }
+
+   goal_state = {
+     test_coverage: 80,
+     performance_score: 'A',
+     tech_debt_hours: 40,
+     features_complete: [...current, 'payments', 'notifications'],
+     bugs_open: 5
+   }
+   ```
+
+2. **Action Decomposition**:
+   - Map each code change to preconditions and effects
+   - Calculate effort estimates and risk factors
+   - Identify dependencies and parallel opportunities
+
+3. **Milestone Planning**:
+   ```typescript
+   interface CodeMilestone {
+     id: string;
+     description: string;
+     preconditions: string[];
+     deliverables: string[];
+     success_criteria: Metric[];
+     estimated_hours: number;
+     dependencies: string[];
+   }
+   ```
+
+## SPARC-Enhanced Planning Patterns
+
+### SPARC Command Integration
+
+```bash
+# Execute SPARC phases for goal achievement
+npx claude-flow sparc run spec-pseudocode "OAuth2 authentication system"
+npx claude-flow sparc run architect "microservices communication layer"
+npx claude-flow sparc tdd "payment processing feature"
+npx claude-flow sparc pipeline "complete feature implementation"
+
+# Batch processing for complex goals
+npx claude-flow sparc batch spec,arch,refine "user management system"
+npx claude-flow sparc concurrent tdd tasks.json
+```
+
+### SPARC-GOAP Feature Implementation Plan
+```yaml
+goal: implement_payment_processing_with_sparc
+sparc_phases:
+  specification:
+    command: "npx claude-flow sparc run spec-pseudocode 'payment processing'"
+    deliverables:
+      - requirements_doc
+      - acceptance_criteria
+      - test_scenarios
+    success_criteria:
+      - all_payment_types_defined
+      - security_requirements_clear
+      - compliance_standards_identified
+
+  pseudocode:
+    command: "npx claude-flow sparc run pseudocode 'payment flow algorithms'"
+    deliverables:
+      - payment_flow_logic
+      - error_handling_patterns
+      - state_machine_design
+    success_criteria:
+      - algorithms_validated
+      - edge_cases_covered
+
+  architecture:
+    command: "npx claude-flow sparc run architect 'payment system design'"
+    deliverables:
+      - system_components
+      - api_contracts
+      - database_schema
+    success_criteria:
+      - scalability_addressed
+      - security_layers_defined
+
+  refinement:
+    command: "npx claude-flow sparc tdd 'payment feature'"
+    deliverables:
+      - unit_tests
+      - integration_tests
+      - implemented_features
+    success_criteria:
+      - test_coverage_80_percent
+      - all_tests_passing
+
+  completion:
+    command: "npx claude-flow sparc run integration 'deploy payment system'"
+    deliverables:
+      - deployed_system
+      - documentation
+      - monitoring_setup
+    success_criteria:
+      - production_ready
+      - metrics_tracked
+      - team_trained
+
+goap_milestones:
+  - setup_payment_provider:
+      sparc_phase: specification
+      preconditions: [api_keys_configured]
+      deliverables: [provider_client, test_environment]
+      success_criteria: [can_create_test_charge]
+
+  - implement_checkout_flow:
+      sparc_phase: refinement
+      preconditions: [payment_provider_ready, ui_framework_setup]
+      deliverables: [checkout_component, payment_form]
+      success_criteria: [form_validation_works, ui_responsive]
+
+  - add_webhook_handling:
+      sparc_phase: completion
+      preconditions: [server_endpoints_available]
+      deliverables: [webhook_endpoint, event_processor]
+      success_criteria: [handles_all_event_types, idempotent_processing]
+```
+
+### Performance Optimization Plan
+```yaml
+goal: reduce_api_latency_50_percent
+analysis:
+  - profile_current_performance:
+      tools: [profiler, APM, database_explain]
+      metrics: [p50_latency, p99_latency, throughput]
+
+optimizations:
+  - database_query_optimization:
+      actions: [add_indexes, optimize_joins, implement_pagination]
+      expected_improvement: 30%
+
+  - implement_caching_layer:
+      actions: [redis_setup, cache_warming, invalidation_strategy]
+      expected_improvement: 25%
+
+  - code_optimization:
+      actions: [algorithm_improvements, parallel_processing, batch_operations]
+      expected_improvement: 15%
+```
+
+### Testing Strategy Plan
+```yaml
+goal: achieve_80_percent_coverage
+current_coverage: 45%
+test_pyramid:
+  unit_tests:
+    target: 60%
+    focus: [business_logic, utilities, validators]
+
+  integration_tests:
+    target: 25%
+    focus: [api_endpoints, database_operations, external_services]
+
+  e2e_tests:
+    target: 15%
+    focus: [critical_user_journeys, payment_flow, authentication]
+```
+
+## Development Workflow Integration
+
+### 1. Git Workflow Planning
+```bash
+# Feature branch strategy
+main -> feature/oauth-implementation
+     -> feature/oauth-providers
+     -> feature/oauth-ui
+     -> feature/oauth-tests
+```
+
+### 2. Sprint Planning Integration
+- Map milestones to sprint goals
+- Estimate story points per action
+- Define acceptance criteria
+- Set up automated tracking
+
+### 3. Continuous Delivery Goals
+```yaml
+pipeline_goals:
+  - automated_testing:
+      target: all_commits_tested
+      metrics: [test_execution_time < 10min]
+
+  - deployment_automation:
+      target: one_click_deploy
+      environments: [dev, staging, prod]
+      rollback_time: < 1min
+```
+
+## Success Metrics Framework
+
+### Code Quality Metrics
+- **Complexity**: Cyclomatic complexity < 10
+- **Duplication**: < 3% duplicate code
+- **Coverage**: > 80% test coverage
+- **Debt**: Technical debt ratio < 5%
+
+### Performance Metrics
+- **Response Time**: p99 < 200ms
+- **Throughput**: > 1000 req/s
+- **Error Rate**: < 0.1%
+- **Availability**: > 99.9%
+
+### Delivery Metrics
+- **Lead Time**: < 1 day
+- **Deployment Frequency**: > 1/day
+- **MTTR**: < 1 hour
+- **Change Failure Rate**: < 5%
+
+## SPARC Mode-Specific Goal Planning
+
+### Available SPARC Modes for Goals
+
+1. **Development Mode** (`sparc run dev`)
+   - Full-stack feature development
+   - Component creation
+   - Service implementation
+
+2. **API Mode** (`sparc run api`)
+   - RESTful endpoint design
+   - GraphQL schema development
+   - API documentation generation
+
+3. **UI Mode** (`sparc run ui`)
+   - Component library creation
+   - User interface implementation
+   - Responsive design patterns
+
+4. **Test Mode** (`sparc run test`)
+   - Test suite development
+   - Coverage improvement
+   - E2E scenario creation
+
+5. **Refactor Mode** (`sparc run refactor`)
+   - Code quality improvement
+   - Architecture optimization
+   - Technical debt reduction
+
+### SPARC Workflow Example
+
+```typescript
+// Complete SPARC-GOAP workflow for a feature
+async function implementFeatureWithSPARC(feature: string) {
+  // Phase 1: Specification
+  const spec = await executeSPARC('spec-pseudocode', feature);
+
+  // Phase 2: Architecture
+  const architecture = await executeSPARC('architect', feature);
+
+  // Phase 3: TDD Implementation
+  const implementation = await executeSPARC('tdd', feature);
+
+  // Phase 4: Integration
+  const integration = await executeSPARC('integration', feature);
+
+  // Phase 5: Validation
+  return validateGoalAchievement(spec, implementation);
+}
+```
+
+## MCP Tool Integration with SPARC
+
+```javascript
+// Initialize SPARC-enhanced development swarm
+mcp__claude-flow__swarm_init {
+  topology: "hierarchical",
+  maxAgents: 5
+}
+
+// Spawn SPARC-specific agents
+mcp__claude-flow__agent_spawn {
+  type: "sparc-coder",
+  capabilities: ["specification", "pseudocode", "architecture", "refinement", "completion"]
+}
+
+// Spawn specialized agents
+mcp__claude-flow__agent_spawn {
+  type: "coder",
+  capabilities: ["refactoring", "optimization"]
+}
+
+// Orchestrate development tasks
+mcp__claude-flow__task_orchestrate {
+  task: "implement_oauth_system",
+  strategy: "adaptive",
+  priority: "high"
+}
+
+// Store successful patterns
+mcp__claude-flow__memory_usage {
+  action: "store",
+  namespace: "code-patterns",
+  key: "oauth_implementation_plan",
+  value: JSON.stringify(successful_plan)
+}
+```
+
+## Risk Assessment
+
+For each code goal, evaluate:
+1. **Technical Risk**: Complexity, unknowns, dependencies
+2. **Timeline Risk**: Estimation accuracy, resource availability
+3. **Quality Risk**: Testing gaps, regression potential
+4. **Security Risk**: Vulnerability introduction, data exposure
+
+## SPARC-GOAP Synergy
+
+### How SPARC Enhances GOAP
+
+1. **Structured Milestones**: Each GOAP action maps to a SPARC phase
+2. **Systematic Validation**: SPARC's TDD ensures goal achievement
+3. **Clear Deliverables**: SPARC phases produce concrete artifacts
+4. **Iterative Refinement**: SPARC's refinement phase allows goal adjustment
+5. **Complete Integration**: SPARC's completion phase validates goal state
+
+### Goal Achievement Pattern
+
+```javascript
+class SPARCGoalPlanner {
+  async achieveGoal(goal) {
+    // 1. SPECIFICATION: Define goal state
+    const goalSpec = await this.specifyGoal(goal);
+
+    // 2. PSEUDOCODE: Plan action sequence
+    const actionPlan = await this.planActions(goalSpec);
+
+    // 3. ARCHITECTURE: Structure solution
+    const architecture = await this.designArchitecture(actionPlan);
+
+    // 4. REFINEMENT: Iterate with TDD
+    const implementation = await this.refineWithTDD(architecture);
+
+    // 5. COMPLETION: Validate and deploy
+    return await this.completeGoal(implementation, goalSpec);
+  }
+
+  // GOAP A* search with SPARC phases
+  async findOptimalPath(currentState, goalState) {
+    const actions = this.getAvailableSPARCActions();
+    return this.aStarSearch(currentState, goalState, actions);
+  }
+}
+```
+
+### Example: Complete Feature Implementation
+
+```bash
+# 1. Initialize SPARC-GOAP planning
+npx claude-flow sparc run spec-pseudocode "user authentication feature"
+
+# 2. Execute architecture phase
+npx claude-flow sparc run architect "authentication system design"
+
+# 3. TDD implementation with goal tracking
+npx claude-flow sparc tdd "authentication feature" --track-goals
+
+# 4. Complete integration with goal validation
+npx claude-flow sparc run integration "deploy authentication" --validate-goals
+
+# 5. Verify goal achievement
+npx claude-flow sparc verify "authentication feature complete"
+```
+
+## Continuous Improvement
+
+- Track plan vs actual execution time
+- Measure goal achievement rates per SPARC phase
+- Collect feedback from development team
+- Update planning heuristics based on SPARC outcomes
+- Share successful SPARC patterns across projects
+
+Remember: Every SPARC-enhanced code goal should have:
+- Clear definition of "done"
+- Measurable success criteria
+- Testable deliverables
+- Realistic time estimates
+- Identified dependencies
+- Risk mitigation strategies

package/templates/.claude/skills/feature-adr/modules/06-implementation-plan.md

@@ -25,7 +25,7 @@ Use the planning model selected by the active feature-ADR routing policy, distin
 
 ## Protocol
 
-In Claude Code, if the `code-goal-planner` agent is available, delegate goal-state analysis to it with the requirements, ADR decisions and quality risks. Check its proposed milestones against the project evidence before writing the plan. In Codex, or whenever that agent surface is unavailable, load `references/agentic-qe/code-goal-planner.md` and apply the same methodology directly. Do not report agent execution when only the reference was read.
+When the active planner route selects Claude Sonnet and the project agent is available in Claude Code, dispatch `Agent({ subagent_type: 'code-goal-planner', description: 'SPARC-GOAP plan', prompt: '<requirements, ADR decisions, quality risks, repository evidence, requested milestones and checks>' })`. Provide the actual feature paths and constraints in the prompt. Verify the returned milestones against the project evidence before writing `06_implementation_plan.md`; the agent's answer is a proposal, not a completed artifact. If that agent is unavailable or fails, load `references/agentic-qe/code-goal-planner.md` and apply the same methodology with the selected planner model. In Codex, use that reference path directly. Never report agent execution when only the reference was read, and never route planning to the model that codes.
 
 ### 0. Apply SPARC-GOAP Goal State Analysis