agile-context-engineering 0.2.2 → 0.5.0

package/skills/research-external-solution/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: research-external-solution
+description: COMPREHENSIVE, IN-DEPTH, CODE-LEVEL Analysis of User Story Implementation in External Repository
+argument-hint: "story=<file-path|github-url> external-codebase=<source-path|github-url> [external-docs=<weblink|filepath>]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, AskUserQuestion, Glob, Grep, WebFetch
+model: opus
+effort: max
+context: fork
+agent: ace-code-discovery-analyst
+---
+
+# Research External Solution
+
+Perform a COMPREHENSIVE, IN-DEPTH, CODE-LEVEL ANALYSIS of how a specific story's functionality is implemented in an external reference system.
+
+## When to Use
+
+- After `/ace:plan-story` -- once story requirements (pass 1-2) are complete
+- Anytime a story references an external system or reference implementation
+- When a story or feature references an external codebase to learn from
+- When you need to understand how an industry-standard system implements specific functionality
+- When you want to extract algorithms, patterns, and implementation details from reference code
+
+## Input
+
+### Required
+
+- **`story`** -- Story source:
+  - **File path**: Path to a markdown file containing the story (from plan-story command)
+  - **GitHub URL or issue number**: GitHub story reference
+  - Must be a valid, accessible file or GitHub issue.
+  - Contains the user story and acceptance criteria that define what to analyze.
+  - **Requirements for the analysis are extracted from this story.**
+  - If not valid, stop and prompt the user.
+
+- **`external-codebase`** -- Path or GitHub repo to the external industry-standard system to analyze:
+  - If local path: Confirm folder exists and contains source code
+  - If GitHub URL: Verify repository accessibility
+
+### Optional
+
+- **`external-docs`** -- Link or path to external system documentation:
+  - If weblink: Verify URL is accessible
+  - If filepath: Verify file exists and is readable
+  - **PREFER using context7 MCP server** when installed -- it provides up-to-date library documentation automatically.
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) -- complete orchestration process with all steps
+- **External solution template**: Read [external-solution-template.xml](external-solution-template.xml) -- output format for the analysis
+- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` -- ACE output formatting rules
+
+## Process
+
+Use the `ace-code-discovery-analyst` agent for code discovery.
+
+The Environment Context above contains the preprocessed INIT JSON -- use it directly instead of running the init script manually. The workflow's step 1 setup can skip the init bash call since that data is already available.
+
+Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, approvals, commits).
+
+This is NOT a high-level overview -- it's a DEEP DIVE into:
+- EXACT code implementations with line-by-line analysis
+- COMPLETE algorithms and formulas extracted verbatim from code
+- ALL design patterns with actual code examples
+- EVERY file, function, and constant involved in the story
+- FULL execution paths traced 5+ levels deep minimum
+
+All output is written ONLY to the analysis file -- no GitHub updates, no modifications to the story file.
+
+## Artifacts
+
+```
+.ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-story_name>/external-analysis.md
+```
+
+## Example Usage
+
+```
+# Example with file path story and GitHub external repo
+/ace:research-external-solution \
+  story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md \
+  external-codebase=https://github.com/tradingview/lightweight-charts \
+  external-docs=https://tradingview.github.io/lightweight-charts/
+
+# Example with GitHub story and local external repo
+/ace:research-external-solution \
+  story=https://github.com/owner/repo/issues/83 \
+  external-codebase=src/external/lightweight-charts/
+
+# Example with context7 (no external-docs needed)
+/ace:research-external-solution \
+  story=.ace/artifacts/product/e1-charts/f2-rendering/s3-canvas/s3-canvas.md \
+  external-codebase=https://github.com/tradingview/lightweight-charts
+```
+
+## Next Steps
+
+- Continue with story refinement -- integration analysis (pass 4) and technical solution (pass 5)
+- `/ace:research-external-solution story=... external-codebase=...` -- Analyze another story
+- `/ace:help` -- Check project initialization status

package/skills/research-external-solution/script.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+/**
+ * research-external-solution skill script — Entry point for ace-tools operations
+ * needed by the research-external-solution skill.
+ *
+ * Subcommands:
+ *   init [story-param]        Environment detection for research-external-solution workflow
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const path = require('path');
+
+const {
+  loadConfig, pathExists, safeReadFile, loadSettings, resolveModel,
+  execCommand, output, error,
+} = require('../../shared/lib/ace-core');
+
+const {
+  classifyStoryParam, extractStoryMetadata, extractStoryRequirements,
+  extractWikiReferences,
+  computeStoryPaths,
+} = require('../../shared/lib/ace-story');
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const raw = args.includes('--raw');
+const cmd = args[0];
+
+switch (cmd) {
+  case 'init':
+    cmdInit(cwd, raw, args.slice(1).filter(a => a !== '--raw').join(' ') || undefined);
+    break;
+  case 'verify-path-exists': {
+    const targetPath = args.slice(1).filter(a => a !== '--raw').join(' ');
+    if (!targetPath) error('verify-path-exists requires path argument');
+    const exists = pathExists(cwd, targetPath);
+    output({ exists, path: targetPath }, raw, String(exists));
+    break;
+  }
+  default:
+    error(`Unknown command: ${cmd}\nAvailable: init, verify-path-exists`);
+}
+
+// ─── Init: Research Story ───────────────────────────────────────────────────
+
+/**
+ * Environment detection for the research-external-solution workflow.
+ *
+ * Replicates cmdInitResearchStory from ace-tools.js:
+ * 1. loadConfig, detect git/gh CLI/github_project
+ * 2. classifyStoryParam — validate story source
+ * 3. Load story content (from file or GitHub)
+ * 4. extractStoryMetadata, extractStoryRequirements, extractWikiReferences
+ * 5. computeStoryPaths or derive from file location
+ * 6. Check artifact existence (external/integration analysis, feature file)
+ * 7. Verify wiki doc existence
+ * 8. Output JSON with all data
+ */
+function cmdInit(cwd, raw, storyParam) {
+  const config = loadConfig(cwd);
+
+  // ── Environment detection ──
+  const has_git = pathExists(cwd, '.git');
+  const has_gh_cli = (() => {
+    try {
+      const { execSync } = require('child_process');
+      execSync('gh --version', { stdio: 'pipe' });
+      return true;
+    } catch { return false; }
+  })();
+  const github_project = (() => {
+    const settings = loadSettings(cwd);
+    return settings.github_project;
+  })();
+
+  // ── Classify the story parameter ──
+  const classified = classifyStoryParam(storyParam);
+
+  // Early exit if invalid
+  if (classified.type === null || classified.type === 'invalid') {
+    output({
+      analyst_model: resolveModel(cwd, 'ace-code-integration-analyst'),
+      mapper_model: resolveModel(cwd, 'ace-wiki-mapper'),
+      commit_docs: config.commit_docs,
+      has_git, has_gh_cli, github_project,
+      story_source: null,
+      story_valid: false,
+      story_error: classified.reason || 'No story parameter provided',
+      story: { id: null, title: null, status: null, size: null },
+      feature: { id: null, title: null },
+      epic: { id: null, title: null },
+      user_story: null, description: null, acceptance_criteria_count: 0,
+      paths: null,
+      has_external_analysis: false, has_integration_analysis: false, has_feature_file: false,
+      wiki_references: { system_wide: [], subsystem_docs: [], total_count: 0 },
+      wiki_docs_exist: { existing: [], missing: [] },
+    }, raw);
+    return;
+  }
+
+  // ── Load story content ──
+  let storyContent = null;
+  let storySource = classified.type === 'file' ? 'file' : 'github';
+  let storyError = null;
+  let storyFilePath = null;
+
+  if (classified.type === 'file') {
+    const resolvedPath = path.isAbsolute(classified.filePath)
+      ? classified.filePath
+      : path.join(cwd, classified.filePath);
+    if (!pathExists(cwd, classified.filePath)) {
+      storyError = `Story file not found: ${classified.filePath}`;
+    } else {
+      storyContent = safeReadFile(resolvedPath);
+      storyFilePath = classified.filePath;
+      if (!storyContent) storyError = `Could not read story file: ${classified.filePath}`;
+    }
+  } else {
+    // github-url or issue-number
+    if (!has_gh_cli) {
+      storyError = 'GitHub CLI (gh) not installed. Cannot fetch GitHub issues.';
+    } else {
+      const repo = classified.repo || (github_project.repo || null);
+      if (!repo) {
+        storyError = 'No repository configured. Provide a full GitHub URL or configure github_project.repo in settings.';
+      } else {
+        const ghResult = execCommand(
+          `gh issue view ${classified.issueNumber} --repo ${repo} --json title,body,labels,state`,
+          cwd
+        );
+        if (!ghResult) {
+          storyError = `Could not fetch GitHub issue #${classified.issueNumber} from ${repo}.`;
+        } else {
+          try {
+            const issue = JSON.parse(ghResult);
+            storyContent = issue.body || '';
+            if (storyContent && !storyContent.match(/^#\s+/m)) {
+              storyContent = `# ${issue.title}\n\n${storyContent}`;
+            }
+          } catch {
+            storyError = `Failed to parse GitHub issue response for #${classified.issueNumber}.`;
+          }
+        }
+      }
+    }
+  }
+
+  // ── Extract metadata & requirements ──
+  const metadata = extractStoryMetadata(storyContent);
+  const requirements = extractStoryRequirements(storyContent);
+  const wikiRefs = extractWikiReferences(storyContent);
+
+  // ── Compute paths ──
+  let paths = null;
+  if (storyFilePath) {
+    const resolvedPath = path.isAbsolute(storyFilePath)
+      ? storyFilePath
+      : path.join(cwd, storyFilePath);
+    const storyDir = path.dirname(resolvedPath);
+    const relStoryDir = path.relative(cwd, storyDir).replace(/\\/g, '/');
+    const storySlug = path.basename(storyDir);
+    const featureDir = path.dirname(storyDir);
+    const relFeatureDir = path.relative(cwd, featureDir).replace(/\\/g, '/');
+    const featureSlug = path.basename(featureDir);
+
+    paths = {
+      epic_slug: null,
+      feature_slug: featureSlug,
+      story_slug: storySlug,
+      story_dir: relStoryDir,
+      story_file: storyFilePath.replace(/\\/g, '/'),
+      external_analysis_file: `${relStoryDir}/external-analysis.md`,
+      integration_analysis_file: `${relStoryDir}/integration-analysis.md`,
+      feature_dir: relFeatureDir,
+      feature_file: `${relFeatureDir}/${featureSlug}.md`,
+    };
+  } else if (metadata.epic.id && metadata.feature.id && metadata.id) {
+    paths = computeStoryPaths(
+      metadata.epic.id, metadata.epic.title || '',
+      metadata.feature.id, metadata.feature.title || '',
+      metadata.id, metadata.title || ''
+    );
+  }
+
+  // ── Check artifact existence ──
+  const has_external_analysis = paths ? pathExists(cwd, paths.external_analysis_file) : false;
+  const has_integration_analysis = paths ? pathExists(cwd, paths.integration_analysis_file) : false;
+  const has_feature_file = paths ? pathExists(cwd, paths.feature_file) : false;
+
+  // ── Verify wiki doc existence ──
+  const allWikiPaths = [...wikiRefs.system_wide, ...wikiRefs.subsystem_docs.map(d => d.path)];
+  const wikiExisting = [];
+  const wikiMissing = [];
+  for (const wikiPath of allWikiPaths) {
+    if (pathExists(cwd, wikiPath)) {
+      wikiExisting.push(wikiPath);
+    } else {
+      wikiMissing.push(wikiPath);
+    }
+  }
+
+  // ── Build result ──
+  const result = {
+    analyst_model: resolveModel(cwd, 'ace-code-integration-analyst'),
+    mapper_model: resolveModel(cwd, 'ace-wiki-mapper'),
+    commit_docs: config.commit_docs,
+    has_git, has_gh_cli, github_project,
+    story_source: storySource,
+    story_valid: storyContent !== null && storyError === null,
+    story_error: storyError,
+    story: {
+      id: metadata.id,
+      title: metadata.title,
+      status: metadata.status,
+      size: metadata.size,
+    },
+    feature: metadata.feature,
+    epic: metadata.epic,
+    user_story: requirements.user_story,
+    description: requirements.description,
+    acceptance_criteria_count: requirements.acceptance_criteria_count,
+    paths,
+    has_external_analysis,
+    has_integration_analysis,
+    has_feature_file,
+    wiki_references: wikiRefs,
+    wiki_docs_exist: {
+      existing: wikiExisting,
+      missing: wikiMissing,
+    },
+  };
+
+  output(result, raw);
+}

package/skills/research-external-solution/script.test.js

@@ -0,0 +1,134 @@
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SCRIPT = path.join(__dirname, 'script.js');
+
+/**
+ * Create a minimal ACE project structure in a temp directory.
+ */
+function createTestProject() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+
+  // .ace/config.json
+  const aceDir = path.join(tmpDir, '.ace');
+  fs.mkdirSync(aceDir, { recursive: true });
+  fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+    version: '0.1.0',
+    projectName: 'test-project',
+    model_profile: 'quality',
+    commit_docs: true,
+    github: { enabled: false },
+  }, null, 2));
+
+  // .ace/settings.json
+  fs.writeFileSync(path.join(aceDir, 'settings.json'), JSON.stringify({
+    model_profile: 'quality',
+    commit_docs: true,
+    agent_teams: false,
+    github_project: { enabled: false, gh_installed: false, repo: '', project_number: null, owner: '' },
+  }, null, 2));
+
+  return tmpDir;
+}
+
+/**
+ * Create a story file in the test project.
+ */
+function createStoryFile(tmpDir, relPath, content) {
+  const fullPath = path.join(tmpDir, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content, 'utf-8');
+  return relPath;
+}
+
+function runScript(subcommand, args, cwd) {
+  return execSync(`node "${SCRIPT}" ${subcommand} ${args}`, {
+    cwd,
+    encoding: 'utf-8',
+    timeout: 10000,
+  });
+}
+
+function cleanup(tmpDir) {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('research-external-solution script', () => {
+
+  describe('init', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns valid JSON with environment detection for a story file', () => {
+      const storyContent = [
+        '# S1: Add Login Button',
+        '**Feature**: F1 User Auth | **Epic**: E1 Platform',
+        '**Status**: Todo | **Size**: 3 | **Sprint**: — | **Link**: —',
+        '',
+        '## User Story',
+        '',
+        '> As a user,',
+        '> I want to click a login button,',
+        '> so that I can access my account.',
+        '',
+        '## Description',
+        '',
+        'Adds a login button to the header.',
+        '',
+        '## Acceptance Criteria',
+        '',
+        '### Scenario: Click login button',
+        '',
+        '**Given** the user is on the homepage',
+        '**When** they click "Login"',
+        '**Then** they see the login form',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-platform/f1-user-auth/s1-add-login-button/s1-add-login-button.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('init', storyPath, tmpDir));
+
+      assert.ok(result.analyst_model, 'should have analyst_model');
+      assert.ok(result.mapper_model, 'should have mapper_model');
+      assert.strictEqual(result.story_valid, true, 'story should be valid');
+      assert.strictEqual(result.story_source, 'file');
+      assert.strictEqual(result.story.id, 'S1');
+      assert.strictEqual(result.story.title, 'Add Login Button');
+      assert.strictEqual(result.acceptance_criteria_count, 1);
+      assert.ok(result.paths, 'should have computed paths');
+      assert.ok(result.wiki_references, 'should have wiki_references');
+      assert.ok(result.wiki_docs_exist, 'should have wiki_docs_exist');
+    });
+
+    it('errors on init without story param', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.strictEqual(result.story_valid, false);
+    });
+
+    it('handles non-existent story file gracefully', () => {
+      const result = JSON.parse(runScript('init', 'nonexistent/story.md', tmpDir));
+      assert.strictEqual(result.story_valid, false);
+      assert.ok(result.story_error.includes('not found'));
+    });
+  });
+
+  describe('error handling', () => {
+    it('errors on unknown command', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+  });
+});

package/{agile-context-engineering/workflows/research-external-solution.xml → skills/research-external-solution/workflow.xml}

@@ -33,12 +33,10 @@
         <step name="setup" order="1">
             **MANDATORY FIRST STEP — Execute environment detection and story initialization:**
 
-            ```bash
-            INIT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js init research-story {story_param})
-            ```
+            INIT is available from the preprocessed Environment Context above — do NOT re-run init.
 
-            This single call validates the story parameter, extracts metadata/requirements/wiki
-            references, computes all paths and slugs, and checks artifact existence.
+            This preprocessing validated the story parameter, extracted metadata/requirements/wiki
+            references, computed all paths and slugs, and checked artifact existence.
 
             Parse INIT JSON for:
             - **Environment**: `has_git`, `has_gh_cli`, `github_project`, `analyst_model`
@@ -229,7 +227,7 @@
 
             Verify file exists:
             ```bash
-            DOCS_EXISTS=$(node ~/.claude/agile-context-engineering/src/ace-tools.js verify-path-exists {filepath} --raw)
+            DOCS_EXISTS=$(node "${CLAUDE_SKILL_DIR}/script.js" verify-path-exists {filepath} --raw)
             ```
 
             **If not exists:** Display warning (non-fatal):

package/skills/research-integration-solution/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: research-integration-solution
+description: COMPREHENSIVE, IN-DEPTH System Integration Analysis for Integrating a New Story into the Existing Codebase
+argument-hint: "story=<file-path|github-url>"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, AskUserQuestion, Glob, Grep, Agent
+model: opus
+effort: max
+context: fork
+agent: ace-code-integration-analyst
+---
+
+# Research Integration Solution
+
+Perform a COMPREHENSIVE, IN-DEPTH System Integration Analysis that ensures new story implementations integrate seamlessly with existing systems.
+
+## When to Use
+
+- After `/ace:plan-story` -- once story requirements (pass 1-2) are complete
+- After `/ace:research-external-solution` -- if external analysis was performed (pass 3)
+- Anytime you need to understand how a story integrates with the existing codebase
+- When story requirements and wiki references are available (passes 1-2 complete)
+- When you need to identify refactoring needs, integration points, and hardcoded values to replace
+- When you need a comprehensive analysis to guide AI agents implementing the story
+
+## Input
+
+### Required
+
+- **`story`** -- Story source:
+  - **File path**: Path to a markdown file containing the story (from plan-story command)
+  - **GitHub URL or issue number**: GitHub story reference
+  - Must be a valid, accessible file or GitHub issue.
+  - Contains the user story, acceptance criteria, and Relevant Wiki references that define what to analyze and which wiki docs to load.
+  - **Requirements and wiki references are extracted from this story.**
+  - If not valid, stop and prompt the user.
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) -- complete orchestration process with all steps
+- **Integration solution template**: Read [integration-solution-template.xml](integration-solution-template.xml) -- output format for the analysis
+- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` -- ACE output formatting rules
+
+## Process
+
+Use the `ace-code-integration-analyst` agent for code integration analysis.
+
+The Environment Context above contains the preprocessed INIT JSON -- use it directly instead of running the init script manually. The workflow's step 1 setup can skip the init bash call since that data is already available.
+
+Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end. Preserve all workflow gates (validation, approvals, commits).
+
+**[MANDATORY]** Identify how a new story would PROPERLY integrate with the existing codebase while maintaining architectural integrity, maintainability, and extensibility while strictly following CODING STANDARDS.
+
+The analysis covers:
+- Architecture compatibility with Clean Architecture layers
+- Existing patterns to follow (with specific file references)
+- Required refactoring (with justification)
+- CRITICAL: Hardcoded values and placeholder code that MUST be replaced
+- Integration points across all architectural layers
+- Impact analysis on existing code flows
+- Implementation guidelines and testing strategy
+- Complete AI implementation context for the executing agent
+
+All output is written ONLY to the analysis file -- no GitHub updates, no modifications to the story file.
+
+## Artifacts
+
+```
+.ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-story_name>/integration-analysis.md
+```
+
+## Example Usage
+
+```
+# Example with file path story
+/ace:research-integration-solution \
+  story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
+
+# Example with GitHub story
+/ace:research-integration-solution \
+  story=https://github.com/owner/repo/issues/83
+
+# Example with just issue number (uses current repo)
+/ace:research-integration-solution \
+  story=83
+```
+
+## Next Steps
+
+- Continue with story refinement -- technical solution (pass 5)
+- `/ace:research-integration-solution story=...` -- Analyze another story
+- `/ace:help` -- Check project initialization status

package/{agile-context-engineering/templates/product/story-integration-solution.xml → skills/research-integration-solution/integration-solution-template.xml}

@@ -526,6 +526,7 @@
                     - **Patterns**: Design patterns in use with examples
                     - **Cross-Cutting Concerns**: Shared concerns (auth, logging, errors, etc.)
                     - **Guides**: How-to guides for common implementation tasks
+                    - **Walkthroughs**: Deep tutorial-style flow explanations with actual code snippets
                     - **Decisions (ADRs)**: Architecture decisions that constrain design
                     - **Architecture**: Subsystem architecture documents