@hawkinside_out/workflow-improvement-tracker

> Agent Learning System for capturing, sharing, and applying working code patterns


The improvement-tracker package provides a comprehensive agent learning system that captures successful code patterns from your projects and makes them reusable across your entire development ecosystem.

✨ Features

$3

- 🧠 Smart Analysis - Automatically detects code structure, dependencies, and architecture
- 📁 Multi-file Support - Capture entire implementations with all related files
- 🔗 Dependency Detection - Identifies both production and development dependencies
- 🌐 Environment Variables - Captures required env vars with descriptions
- 🏗️ Architecture Detection - Recognizes patterns like request-response, middleware, etc.

$3

- 🔍 Semantic Search - Find patterns by keywords, category, or intent
- 📊 Usage Tracking - Track how often patterns are applied
- ⭐ Effectiveness Scores - Measure pattern success rates
- ⏰ Auto-deprecation - Patterns unused for 1+ year are auto-deprecated
- 🔒 Privacy-First - PII automatically stripped before storage

$3

- 🎯 CLI Commands - Full CLI integration with workflow solution:*
- 💾 File-based Storage - Patterns stored in .workflow/patterns/solutions/
- 📦 Schema Validation - Zod-powered schemas ensure data integrity
- 🔄 Pattern Versioning - Track pattern evolution over time

---

📦 Installation

``bash


Via pnpm (in monorepo)

pnpm add @hawkinside_out/workflow-improvement-tracker

Via npm

npm install @hawkinside_out/workflow-improvement-tracker
`

---

🚀 CLI Usage

$3

Capture working code from your project:

`bash


Interactive mode

workflow-agent solution:capture

With options

workflow-agent solution:capture \
--path ./src/auth \
--name "JWT Authentication" \
--category auth \
--tags "jwt,authentication,security"
`

The analyzer will:

1. Scan all files in the specified path
2. Detect dependencies and dev dependencies
3. Identify environment variables
4. Analyze code architecture
5. Create a reusable pattern

$3

Find patterns that match your needs:

`bash


Search by keyword

workflow-agent solution:search "authentication jwt"

Search with category filter

workflow-agent solution:search "user login" --category auth

Search with tag filter

workflow-agent solution:search "api" --tags "rest,middleware"
`

$3

View your pattern library:

`bash


List all patterns

workflow-agent solution:list

Filter by category

workflow-agent solution:list --category auth

Include deprecated patterns

workflow-agent solution:list --include-deprecated
`

$3

Apply a pattern to your current project:

`bash


Apply by ID

workflow-agent solution:apply sol_abc123

Apply without prompts

workflow-agent solution:apply sol_abc123 --yes

Dry run (preview only)

workflow-agent solution:apply sol_abc123 --dry-run
`

$3

Get insights into your pattern library:

`bash
workflow-agent solution:stats
`

Shows:

- Total patterns by category
- Most used patterns
- Highest effectiveness scores
- Deprecated pattern count

$3

Mark an outdated pattern as deprecated:

`bash
workflow-agent solution:deprecate sol_abc123 "Replaced by OAuth2 implementation"
`

---

📚 Programmatic API

$3

Analyze files and directories to extract code patterns:

`typescript
import { createCodeAnalyzer } from "@hawkinside_out/workflow-improvement-tracker";

// Create analyzer instance
const analyzer = createCodeAnalyzer();

// Analyze a single file
const fileResult = await analyzer.analyzeFile("/path/to/auth.ts");
console.log(fileResult.language); // 'typescript'
console.log(fileResult.imports); // ['jsonwebtoken', 'express']
console.log(fileResult.exports); // ['authenticateUser', 'generateToken']

// Analyze a directory
const dirResult = await analyzer.analyzeDirectory("/path/to/auth");
console.log(dirResult.files); // Array of file analysis results
console.log(dirResult.entryPoints); // ['index.ts']
console.log(dirResult.architecture); // 'middleware'

// Create a solution pattern from analyzed code
const pattern = await analyzer.createSolutionPattern("/path/to/auth", {
name: "JWT Authentication",
description: "Complete JWT auth implementation with refresh tokens",
category: "auth",
tags: ["jwt", "authentication", "security"],
author: "your-name",
});
`

$3

Store and retrieve solution patterns:

`typescript
import { PatternStore } from "@hawkinside_out/workflow-improvement-tracker";

// Create store instance
const store = new PatternStore("/path/to/project");

// Add a solution pattern
const result = await store.addSolutionPattern(pattern);
if (result.success) {
console.log("Pattern saved:", result.data.id);
}

// Search for patterns
const searchResults = await store.searchSolutionPatterns({
keywords: ["authentication"],
category: "auth",
limit: 10,
});

// Get pattern by ID
const patternResult = await store.getSolutionPatternById("sol_abc123");

// List all patterns
const allPatterns = await store.listSolutionPatterns();

// Record pattern usage
await store.recordSolutionUsage("sol_abc123", {
projectContext: "e-commerce-app",
effectiveness: 0.95,
});

// Get statistics
const stats = await store.getSolutionStats();
console.log(stats.data.totalPatterns);
console.log(stats.data.byCategory);
console.log(stats.data.mostUsed);
`

$3

All patterns are validated using Zod schemas:

`typescript
import {
SolutionPatternSchema,
SolutionDependencySchema,
SolutionCodeSnippetSchema,
SolutionEnvironmentVarSchema,
SolutionCategorySchema,
} from "@hawkinside_out/workflow-improvement-tracker";

// Validate a pattern
const validatedPattern = SolutionPatternSchema.parse(rawData);

// Validate category
const category = SolutionCategorySchema.parse("auth"); // Valid
`

---

📐 Pattern Schema

A Solution Pattern contains:

`typescript
interface SolutionPattern {
id: string; // Unique ID (sol_*)
name: string; // Human-readable name
description: string; // Detailed description
category: SolutionCategory; // auth, api, database, etc.
tags: string[]; // Searchable tags

// Code content
codeSnippets: SolutionCodeSnippet[]; // The actual code
dependencies: SolutionDependency[]; // Required packages
environmentVars: SolutionEnvVar[]; // Required env vars
fileStructure?: string; // Directory layout

// Metadata
author?: string;
sourceProject?: string;
createdAt: Date;
updatedAt: Date;

// Usage tracking
usageCount: number;
effectivenessScore: number; // 0-1 based on feedback

// Lifecycle
deprecated: boolean;
deprecatedAt?: Date;
deprecationReason?: string;
}
`

$3

Available solution categories:

- auth - Authentication & authorization
- api - API design & endpoints
- database - Database schemas & queries
- testing - Test utilities & patterns
- ui - User interface components
- devops - CI/CD & infrastructure
- performance - Optimization patterns
- security - Security implementations
- integrations - Third-party integrations
- utilities - Helper functions & utilities
- architecture - Structural patterns
- error-handling - Error management
- other - Miscellaneous patterns

---

🔧 Configuration

Patterns are stored in your project's .workflow/patterns/solutions/ directory:

`
.workflow/
└── patterns/
└── solutions/
├── sol_abc123.json
├── sol_def456.json
└── ...
`

Each pattern is stored as a separate JSON file for easy version control and sharing.

---

🧪 Testing

The package includes comprehensive tests:

`bash


Run all tests

pnpm test

Run with coverage

pnpm test:coverage

Run specific test file

npx vitest run code-analyzer.test.ts
`

Test coverage includes:

- 53 tests for CodeAnalyzer
- 37 tests for PatternStore
- 45 tests for Schema validation
- 14 E2E tests for CLI commands

---

📊 Example Workflow

$3

`bash


You just finished implementing JWT auth in your project

ls src/auth/

index.ts jwt.service.ts middleware.ts types.ts

`

$3

`bash
workflow-agent solution:capture \
--path ./src/auth \
--name "JWT Auth with Refresh Tokens" \
--category auth \
--tags "jwt,refresh-tokens,express"

✓ Captured 4 files

✓ Detected 3 dependencies: jsonwebtoken, express, bcrypt

✓ Found 2 env vars: JWT_SECRET, JWT_REFRESH_SECRET

✓ Pattern saved: sol_xyz789

`

$3

`bash
mkdir new-project && cd new-project
workflow-agent init
`

$3

`bash
workflow-agent solution:search "jwt authentication"

Found 3 patterns:

1. JWT Auth with Refresh Tokens (auth) ⭐ 0.95

2. Basic JWT Auth (auth) ⭐ 0.88

3. OAuth2 + JWT Hybrid (auth) ⭐ 0.92

`

$3

`bash
workflow-agent solution:apply sol_xyz789

Preview:

- Create src/auth/index.ts

- Create src/auth/jwt.service.ts

- Create src/auth/middleware.ts

- Create src/auth/types.ts

- Install: jsonwebtoken, express, bcrypt

- Add env vars: JWT_SECRET, JWT_REFRESH_SECRET

#

Apply pattern? (y/n) y

✓ Pattern applied successfully!

``

---

🤝 Contributing

Contributions are welcome! See the main CONTRIBUTING.md for guidelines.

📄 License

MIT © HawkinsideOut