@ai-sdlc/orchestrator 0.5.0 → 0.6.0

package/dist/workflow-patterns/classifiers.js

@@ -0,0 +1,72 @@
+/**
+ * Pattern type classifiers — refine detected patterns into
+ * specific automation types based on their structure.
+ */
+/**
+ * Classify a detected pattern into a specific type and suggest an artifact.
+ */
+export function classifyPattern(pattern) {
+    // Check classifiers in priority order
+    if (isCopyPasteCycle(pattern.steps)) {
+        return {
+            ...pattern,
+            patternType: 'copy-paste-cycle',
+            suggestedArtifactType: 'skill',
+        };
+    }
+    if (isPeriodicTask(pattern)) {
+        return {
+            ...pattern,
+            patternType: 'periodic-task',
+            suggestedArtifactType: 'workflow',
+        };
+    }
+    // Default: command sequence
+    return {
+        ...pattern,
+        patternType: 'command-sequence',
+        suggestedArtifactType: 'command',
+    };
+}
+/**
+ * Copy-paste cycle: Read from one file, then Write/Edit a different file type.
+ * Suggests the user is copying boilerplate or scaffolding from templates.
+ */
+function isCopyPasteCycle(steps) {
+    let hasRead = false;
+    let hasWriteAfterRead = false;
+    for (const step of steps) {
+        if (step.category === 'read') {
+            hasRead = true;
+        }
+        else if (hasRead && step.category === 'write') {
+            hasWriteAfterRead = true;
+        }
+    }
+    // Must have at least one read→write transition
+    if (!hasWriteAfterRead)
+        return false;
+    // The write should target a different file than the read
+    const readActions = steps.filter((s) => s.category === 'read').map((s) => s.action);
+    const writeActions = steps.filter((s) => s.category === 'write').map((s) => s.action);
+    // If reads and writes target different extensions, it's likely scaffolding
+    const readExts = new Set(readActions.map((a) => a.split(':').pop()));
+    const writeExts = new Set(writeActions.map((a) => a.split(':').pop()));
+    // Different file types or at least some diversity
+    const hasDistinctTargets = readExts.size > 0 && writeExts.size > 0 && ![...readExts].every((e) => writeExts.has(e));
+    return hasDistinctTargets || (readActions.length > 0 && writeActions.length > 1);
+}
+/**
+ * Periodic task: same pattern occurs with regular time spacing.
+ * Requires firstSeen and lastSeen spanning 7+ days.
+ */
+function isPeriodicTask(pattern) {
+    if (!pattern.firstSeen || !pattern.lastSeen)
+        return false;
+    const first = new Date(pattern.firstSeen).getTime();
+    const last = new Date(pattern.lastSeen).getTime();
+    const spanDays = (last - first) / (1000 * 60 * 60 * 24);
+    // Must span at least 7 days with regular occurrence
+    return spanDays >= 7 && pattern.sessionCount >= 3;
+}
+//# sourceMappingURL=classifiers.js.map

package/dist/workflow-patterns/detector.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Workflow pattern detector — mines frequent n-gram sequences
+ * from tool call histories across Claude Code sessions.
+ */
+import type { ToolSequenceEvent } from '../state/types.js';
+import type { CanonicalStep, NGram, DetectedPattern, DetectionOptions } from './types.js';
+/**
+ * Convert a raw tool event to a canonical step.
+ */
+export declare function canonicalizeStep(event: ToolSequenceEvent): CanonicalStep;
+/**
+ * Hash a sequence of canonical steps for grouping.
+ */
+export declare function hashSequence(steps: CanonicalStep[]): string;
+/**
+ * Group tool sequence events by session, ordered by timestamp.
+ */
+export declare function extractSessionSequences(events: ToolSequenceEvent[]): Map<string, CanonicalStep[]>;
+/**
+ * Generate all contiguous n-grams from a sequence.
+ */
+export declare function generateNGrams(sequence: CanonicalStep[], sessionId: string, minN: number, maxN: number): NGram[];
+/**
+ * Mine frequent patterns from tool sequence events.
+ */
+export declare function mineFrequentPatterns(events: ToolSequenceEvent[], opts?: Partial<DetectionOptions>): DetectedPattern[];
+//# sourceMappingURL=detector.d.ts.map

package/dist/workflow-patterns/detector.js

@@ -0,0 +1,186 @@
+/**
+ * Workflow pattern detector — mines frequent n-gram sequences
+ * from tool call histories across Claude Code sessions.
+ */
+import { createHash } from 'node:crypto';
+import { categorizeAction } from './telemetry-ingest.js';
+import { DEFAULT_DETECTION_OPTIONS } from './types.js';
+/**
+ * Convert a raw tool event to a canonical step.
+ */
+export function canonicalizeStep(event) {
+    return {
+        tool: event.toolName,
+        action: event.actionCanonical,
+        category: categorizeAction(event.toolName, event.actionCanonical),
+    };
+}
+/**
+ * Hash a sequence of canonical steps for grouping.
+ */
+export function hashSequence(steps) {
+    const key = steps.map((s) => `${s.tool}:${s.action}`).join('|');
+    return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+/**
+ * Group tool sequence events by session, ordered by timestamp.
+ */
+export function extractSessionSequences(events) {
+    const sessions = new Map();
+    for (const event of events) {
+        const existing = sessions.get(event.sessionId) ?? [];
+        existing.push(event);
+        sessions.set(event.sessionId, existing);
+    }
+    const result = new Map();
+    for (const [sessionId, sessionEvents] of sessions) {
+        const sorted = sessionEvents.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+        result.set(sessionId, sorted.map(canonicalizeStep));
+    }
+    return result;
+}
+/**
+ * Generate all contiguous n-grams from a sequence.
+ */
+export function generateNGrams(sequence, sessionId, minN, maxN) {
+    const ngrams = [];
+    for (let n = minN; n <= Math.min(maxN, sequence.length); n++) {
+        for (let i = 0; i <= sequence.length - n; i++) {
+            const steps = sequence.slice(i, i + n);
+            ngrams.push({
+                steps,
+                hash: hashSequence(steps),
+                sessionId,
+            });
+        }
+    }
+    return ngrams;
+}
+/**
+ * Mine frequent patterns from tool sequence events.
+ */
+export function mineFrequentPatterns(events, opts) {
+    const options = { ...DEFAULT_DETECTION_OPTIONS, ...opts };
+    // Filter by project and time
+    let filtered = events;
+    if (options.projectFilter) {
+        filtered = filtered.filter((e) => e.projectPath === options.projectFilter);
+    }
+    if (options.since) {
+        const sinceDate = new Date(options.since).getTime();
+        filtered = filtered.filter((e) => new Date(e.timestamp).getTime() >= sinceDate);
+    }
+    if (filtered.length === 0)
+        return [];
+    // Group by session
+    const sessions = extractSessionSequences(filtered);
+    const totalSessions = sessions.size;
+    if (totalSessions < options.minSessionCount)
+        return [];
+    // Generate n-grams across all sessions
+    const aggregates = new Map();
+    for (const [sessionId, sequence] of sessions) {
+        const ngrams = generateNGrams(sequence, sessionId, options.minSequenceLength, options.maxSequenceLength);
+        // Deduplicate within a session (same hash counted once per session)
+        const seenInSession = new Set();
+        for (const ngram of ngrams) {
+            if (seenInSession.has(ngram.hash))
+                continue;
+            seenInSession.add(ngram.hash);
+            const existing = aggregates.get(ngram.hash);
+            if (existing) {
+                existing.frequency++;
+                existing.sessionIds.add(sessionId);
+            }
+            else {
+                aggregates.set(ngram.hash, {
+                    steps: ngram.steps,
+                    hash: ngram.hash,
+                    frequency: 1,
+                    sessionIds: new Set([sessionId]),
+                    timestamps: [],
+                });
+            }
+        }
+    }
+    // Filter by minimum frequency and session count
+    let patterns = [];
+    for (const agg of aggregates.values()) {
+        if (agg.frequency >= options.minFrequency && agg.sessionIds.size >= options.minSessionCount) {
+            patterns.push(agg);
+        }
+    }
+    // Compute confidence and find max frequency for normalization
+    const maxFrequency = Math.max(1, ...patterns.map((p) => p.frequency));
+    // Remove subsumed patterns (shorter patterns contained in longer ones with similar frequency)
+    patterns = removeSubsumedPatterns(patterns);
+    // Build detected patterns with confidence scoring
+    const detected = [];
+    for (const p of patterns) {
+        const confidence = Math.min(1.0, (p.sessionIds.size / totalSessions) * (p.frequency / maxFrequency));
+        if (confidence < options.minConfidence)
+            continue;
+        detected.push({
+            hash: p.hash,
+            steps: p.steps,
+            frequency: p.frequency,
+            sessionCount: p.sessionIds.size,
+            confidence,
+            patternType: 'command-sequence', // Default — classifiers refine this
+            suggestedArtifactType: 'command',
+            firstSeen: '', // Populated by caller from event timestamps
+            lastSeen: '',
+            exampleSessionIds: Array.from(p.sessionIds).slice(0, 5),
+        });
+    }
+    // Sort by confidence * length descending
+    detected.sort((a, b) => b.confidence * b.steps.length - a.confidence * a.steps.length);
+    return detected;
+}
+/**
+ * Remove patterns that are subsumed by longer patterns with similar frequency.
+ * A 3-gram is subsumed by a 5-gram if the 3-gram's steps appear contiguously
+ * in the 5-gram and the 5-gram has >= 70% of the 3-gram's frequency.
+ */
+function removeSubsumedPatterns(patterns) {
+    // Sort by length descending so longer patterns take priority
+    const sorted = [...patterns].sort((a, b) => b.steps.length - a.steps.length);
+    const kept = [];
+    const removed = new Set();
+    for (const pattern of sorted) {
+        if (removed.has(pattern.hash))
+            continue;
+        kept.push(pattern);
+        // Mark shorter patterns that are subsumed
+        for (const other of sorted) {
+            if (other.hash === pattern.hash || removed.has(other.hash))
+                continue;
+            if (other.steps.length >= pattern.steps.length)
+                continue;
+            if (isSubsequence(other.steps, pattern.steps) && pattern.frequency >= other.frequency * 0.7) {
+                removed.add(other.hash);
+            }
+        }
+    }
+    return kept;
+}
+/**
+ * Check if `short` appears as a contiguous subsequence in `long`.
+ */
+function isSubsequence(short, long) {
+    if (short.length > long.length)
+        return false;
+    for (let i = 0; i <= long.length - short.length; i++) {
+        let match = true;
+        for (let j = 0; j < short.length; j++) {
+            if (short[j].tool !== long[i + j].tool || short[j].action !== long[i + j].action) {
+                match = false;
+                break;
+            }
+        }
+        if (match)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=detector.js.map

package/dist/workflow-patterns/index.d.ts

@@ -0,0 +1,8 @@
+export { readToolSequenceJSONL, readSessionMetaFiles, sessionMetaToEvents, categorizeAction, } from './telemetry-ingest.js';
+export { canonicalizeStep, hashSequence, extractSessionSequences, generateNGrams, mineFrequentPatterns, } from './detector.js';
+export { classifyPattern } from './classifiers.js';
+export { generateProposal, generateName } from './proposal-generator.js';
+export { writeArtifact, type WriteResult } from './artifact-writer.js';
+export type { CanonicalStep, NGram, DetectedPattern, DetectionOptions, RawToolSequenceEntry, SessionMeta, } from './types.js';
+export { DEFAULT_DETECTION_OPTIONS } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/workflow-patterns/index.js

@@ -0,0 +1,7 @@
+export { readToolSequenceJSONL, readSessionMetaFiles, sessionMetaToEvents, categorizeAction, } from './telemetry-ingest.js';
+export { canonicalizeStep, hashSequence, extractSessionSequences, generateNGrams, mineFrequentPatterns, } from './detector.js';
+export { classifyPattern } from './classifiers.js';
+export { generateProposal, generateName } from './proposal-generator.js';
+export { writeArtifact } from './artifact-writer.js';
+export { DEFAULT_DETECTION_OPTIONS } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/workflow-patterns/proposal-generator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Proposal generator — creates draft automation artifacts from detected patterns.
+ * Each pattern type maps to a specific artifact: command, skill, hook, or workflow.
+ */
+import type { DetectedPattern } from './types.js';
+import type { PatternProposal } from '../state/types.js';
+/**
+ * Generate an automation proposal from a detected pattern.
+ */
+export declare function generateProposal(pattern: DetectedPattern): Omit<PatternProposal, 'patternId'>;
+/**
+ * Generate a kebab-case name from the pattern's steps.
+ */
+export declare function generateName(pattern: DetectedPattern): string;
+//# sourceMappingURL=proposal-generator.d.ts.map

package/dist/workflow-patterns/proposal-generator.js

@@ -0,0 +1,183 @@
+/**
+ * Proposal generator — creates draft automation artifacts from detected patterns.
+ * Each pattern type maps to a specific artifact: command, skill, hook, or workflow.
+ */
+/**
+ * Generate an automation proposal from a detected pattern.
+ */
+export function generateProposal(pattern) {
+    const name = generateName(pattern);
+    switch (pattern.suggestedArtifactType) {
+        case 'command':
+            return {
+                proposalType: pattern.patternType,
+                artifactType: 'command',
+                artifactPath: `.claude/commands/${name}.md`,
+                draftContent: generateCommandTemplate(name, pattern),
+                confidence: computeProposalConfidence(pattern),
+                status: 'pending',
+            };
+        case 'skill':
+            return {
+                proposalType: pattern.patternType,
+                artifactType: 'skill',
+                artifactPath: `.claude/skills/${name}/SKILL.md`,
+                draftContent: generateSkillTemplate(name, pattern),
+                confidence: computeProposalConfidence(pattern),
+                status: 'pending',
+            };
+        case 'workflow':
+            return {
+                proposalType: pattern.patternType,
+                artifactType: 'workflow',
+                artifactPath: `.github/workflows/auto-${name}.yml`,
+                draftContent: generateWorkflowTemplate(name, pattern),
+                confidence: computeProposalConfidence(pattern),
+                status: 'pending',
+            };
+        case 'hook':
+            return {
+                proposalType: pattern.patternType,
+                artifactType: 'hook',
+                artifactPath: `.claude/hooks/${name}.sh`,
+                draftContent: generateHookTemplate(name, pattern),
+                confidence: computeProposalConfidence(pattern),
+                status: 'pending',
+            };
+        default:
+            return {
+                proposalType: pattern.patternType,
+                artifactType: 'command',
+                artifactPath: `.claude/commands/${name}.md`,
+                draftContent: generateCommandTemplate(name, pattern),
+                confidence: computeProposalConfidence(pattern),
+                status: 'pending',
+            };
+    }
+}
+/**
+ * Generate a kebab-case name from the pattern's steps.
+ */
+export function generateName(pattern) {
+    // Take the most distinctive tool+action pairs
+    const parts = [];
+    for (const step of pattern.steps) {
+        const action = step.action
+            .replace(/[^a-zA-Z0-9\s]/g, '')
+            .trim()
+            .split(/\s+/)
+            .slice(0, 2)
+            .join('-')
+            .toLowerCase();
+        if (action && !parts.includes(action)) {
+            parts.push(action);
+        }
+        if (parts.length >= 3)
+            break;
+    }
+    const name = parts.length > 0 ? `auto-${parts.join('-')}` : `auto-pattern-${pattern.hash.slice(0, 8)}`;
+    return name.slice(0, 50);
+}
+function stepsToMarkdown(steps) {
+    return steps
+        .map((s, i) => {
+        const desc = s.action.includes(':') ? `${s.tool}: ${s.action}` : `Run \`${s.action}\``;
+        return `${i + 1}. ${desc}`;
+    })
+        .join('\n');
+}
+function generateCommandTemplate(name, pattern) {
+    return `---
+name: ${name}
+description: Auto-generated from detected workflow pattern (${pattern.patternType})
+argument-hint: [optional-args]
+---
+
+# ${name}
+
+> Auto-generated from pattern detection. Confidence: ${(pattern.confidence * 100).toFixed(0)}%
+> Observed ${pattern.frequency} times across ${pattern.sessionCount} sessions.
+
+## Steps
+
+${stepsToMarkdown(pattern.steps)}
+
+## Notes
+
+This command was auto-generated by the workflow pattern detection engine.
+Review and customize before using in production.
+`;
+}
+function generateSkillTemplate(name, pattern) {
+    return `---
+name: ${name}
+description: Auto-generated skill from detected ${pattern.patternType} pattern
+---
+
+# ${name}
+
+> Auto-generated from pattern detection. Confidence: ${(pattern.confidence * 100).toFixed(0)}%
+> Observed ${pattern.frequency} times across ${pattern.sessionCount} sessions.
+
+## Workflow
+
+${stepsToMarkdown(pattern.steps)}
+
+## Customization
+
+This skill was auto-generated. Modify the steps above to match your
+specific use case.
+`;
+}
+function generateWorkflowTemplate(name, pattern) {
+    const schedule = '0 9 * * 1'; // Default: Monday 9am
+    return `# Auto-generated workflow from pattern detection
+# Pattern: ${pattern.patternType}
+# Confidence: ${(pattern.confidence * 100).toFixed(0)}%
+# Observed ${pattern.frequency} times across ${pattern.sessionCount} sessions
+
+name: Auto ${name}
+
+on:
+  schedule:
+    - cron: '${schedule}'
+  workflow_dispatch:
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${pattern.steps.map((s) => `      - name: ${s.tool} ${s.action}\n        run: echo "TODO: implement ${s.action}"`).join('\n')}
+`;
+}
+function generateHookTemplate(name, pattern) {
+    return `#!/bin/bash
+# Auto-generated hook from pattern detection
+# Pattern: ${pattern.patternType}
+# Confidence: ${(pattern.confidence * 100).toFixed(0)}%
+
+set -euo pipefail
+
+# TODO: Implement hook logic for pattern:
+${pattern.steps.map((s) => `# - ${s.tool}: ${s.action}`).join('\n')}
+
+exit 0
+`;
+}
+function computeProposalConfidence(pattern) {
+    // Base confidence from pattern detection
+    let confidence = pattern.confidence;
+    // Template fit: commands and skills have better template mapping
+    if (pattern.suggestedArtifactType === 'command' || pattern.suggestedArtifactType === 'skill') {
+        confidence *= 1.0; // Perfect fit
+    }
+    else if (pattern.suggestedArtifactType === 'workflow') {
+        confidence *= 0.8; // Periodic tasks need schedule tuning
+    }
+    else {
+        confidence *= 0.7; // Hooks need manual implementation
+    }
+    return Math.min(1.0, confidence);
+}
+//# sourceMappingURL=proposal-generator.js.map

package/dist/workflow-patterns/telemetry-ingest.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Telemetry ingestion — reads tool sequence JSONL and session-meta
+ * JSON files into ToolSequenceEvent format for pattern detection.
+ */
+import type { ToolSequenceEvent } from '../state/types.js';
+import type { SessionMeta, CanonicalStep } from './types.js';
+/**
+ * Read tool sequence entries from a JSONL file.
+ * Each line is a JSON object with ts, sid, tool, action, project.
+ */
+export declare function readToolSequenceJSONL(filePath: string): ToolSequenceEvent[];
+/**
+ * Read session metadata from the Claude Code usage-data directory.
+ * Returns metadata for all sessions found.
+ */
+export declare function readSessionMetaFiles(usageDataDir: string): SessionMeta[];
+/**
+ * Convert session-meta tool_counts into synthetic ToolSequenceEvents.
+ * Since session-meta only has aggregate counts (no ordering), these
+ * events are useful for frequency analysis but not sequence mining.
+ */
+export declare function sessionMetaToEvents(meta: SessionMeta): ToolSequenceEvent[];
+/**
+ * Categorize a tool action into a workflow category.
+ */
+export declare function categorizeAction(tool: string, action: string): CanonicalStep['category'];
+//# sourceMappingURL=telemetry-ingest.d.ts.map

package/dist/workflow-patterns/telemetry-ingest.js

@@ -0,0 +1,103 @@
+/**
+ * Telemetry ingestion — reads tool sequence JSONL and session-meta
+ * JSON files into ToolSequenceEvent format for pattern detection.
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Read tool sequence entries from a JSONL file.
+ * Each line is a JSON object with ts, sid, tool, action, project.
+ */
+export function readToolSequenceJSONL(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const content = readFileSync(filePath, 'utf-8');
+    const events = [];
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const raw = JSON.parse(trimmed);
+            events.push({
+                sessionId: raw.sid,
+                toolName: raw.tool,
+                actionCanonical: raw.action,
+                projectPath: raw.project,
+                timestamp: raw.ts,
+            });
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return events;
+}
+/**
+ * Read session metadata from the Claude Code usage-data directory.
+ * Returns metadata for all sessions found.
+ */
+export function readSessionMetaFiles(usageDataDir) {
+    const metaDir = join(usageDataDir, 'session-meta');
+    if (!existsSync(metaDir))
+        return [];
+    const files = readdirSync(metaDir).filter((f) => f.endsWith('.json'));
+    const sessions = [];
+    for (const file of files) {
+        try {
+            const content = readFileSync(join(metaDir, file), 'utf-8');
+            const meta = JSON.parse(content);
+            if (meta.session_id && meta.tool_counts) {
+                sessions.push(meta);
+            }
+        }
+        catch {
+            // Skip malformed files
+        }
+    }
+    return sessions;
+}
+/**
+ * Convert session-meta tool_counts into synthetic ToolSequenceEvents.
+ * Since session-meta only has aggregate counts (no ordering), these
+ * events are useful for frequency analysis but not sequence mining.
+ */
+export function sessionMetaToEvents(meta) {
+    const events = [];
+    const timestamp = meta.start_time;
+    for (const [tool, count] of Object.entries(meta.tool_counts)) {
+        for (let i = 0; i < count; i++) {
+            events.push({
+                sessionId: meta.session_id,
+                toolName: tool,
+                actionCanonical: tool.toLowerCase(),
+                projectPath: meta.project_path,
+                timestamp,
+            });
+        }
+    }
+    return events;
+}
+/**
+ * Categorize a tool action into a workflow category.
+ */
+export function categorizeAction(tool, action) {
+    const lower = action.toLowerCase();
+    if (tool === 'Read' || lower.startsWith('read:'))
+        return 'read';
+    if (tool === 'Edit' ||
+        tool === 'Write' ||
+        lower.startsWith('edit:') ||
+        lower.startsWith('write:'))
+        return 'write';
+    if (lower.includes('test') || lower.includes('vitest') || lower.includes('jest'))
+        return 'test';
+    if (lower.includes('build') || lower.includes('tsc') || lower.includes('compile'))
+        return 'build';
+    if (lower.startsWith('git ') || lower.startsWith('gh '))
+        return 'git';
+    if (tool === 'Grep' || tool === 'Glob' || lower.startsWith('grep:') || lower.startsWith('glob:'))
+        return 'search';
+    return 'other';
+}
+//# sourceMappingURL=telemetry-ingest.js.map