agentic-forge 0.0.0

package/README.md

@@ -0,0 +1,145 @@
+<!-- markdownlint-disable MD033 MD041 -->
+<p align="center">
+  <img src="agentic-forge-banner.png" alt="Agentic Forge" width="600">
+</p>
+
+<h1 align="center">Agentic Forge</h1>
+
+<p align="center">
+  <a href="https://github.com/e-stpierre/agentic-forge/releases"><img src="https://img.shields.io/github/v/release/e-stpierre/agentic-forge?include_prereleases" alt="GitHub release"></a>
+  <a href="https://github.com/e-stpierre/agentic-forge/blob/main/LICENSE"><img src="https://img.shields.io/github/license/e-stpierre/agentic-forge" alt="License"></a>
+</p>
+
+<p align="center">
+  <strong>YAML-based agentic workflow engine</strong>
+</p>
+
+<p align="center">
+  Multi-step execution | Parallel orchestration | Error recovery | Short and long-running operations
+</p>
+
+## Overview
+
+Agentic Forge is a TypeScript/Node.js package that provides YAML-based workflow orchestration for Claude Code. It bundles skills, agents, and prompts as package data, enabling autonomous multi-step task execution with parallel execution, conditional logic, and retry mechanisms.
+
+**Best for**: Autonomous development where you prefer Claude works independently.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- [pnpm](https://pnpm.io/) (recommended) or npm
+- Claude Code CLI installed and configured
+
+### Installation
+
+```bash
+# Install globally with npm
+npm install -g agentic-forge
+
+# Or install from source
+git clone https://github.com/e-stpierre/agentic-forge.git
+cd agentic-forge
+pnpm install && pnpm build
+npm install -g .
+```
+
+### Using Skills in Interactive Claude Sessions
+
+Agentic Forge bundles 13 skills that extend Claude Code with slash commands like `/sdlc-plan`, `/analyze`, `/git-commit`, and more. To make them available in interactive sessions:
+
+**Option 1: Pass `--add-dir` when launching Claude**
+
+```bash
+claude --add-dir $(agentic-forge skills-dir)
+```
+
+**Option 2: Add to `~/.claude/settings.json` permanently**
+
+```json
+{
+  "additionalDirectories": ["<output of agentic-forge skills-dir>"]
+}
+```
+
+## Workflows
+
+### plan-build-review (Full SDLC)
+
+Plan -> Create Branch -> Implement (iterative) -> Review -> Fix Issues -> Create PR
+
+```bash
+agentic-forge run plan-build-review --var "task=Add dark mode support"
+```
+
+### one-shot (Single Task)
+
+Create Branch -> Execute Task -> Review -> Create PR
+
+```bash
+agentic-forge run one-shot --var "task=Add user authentication"
+```
+
+### ralph-loop (Iterative Execution)
+
+Generic iterative loop where each iteration runs in a fresh session.
+
+```bash
+agentic-forge run ralph-loop --var "task=Follow the improvement plan" --var "max_iterations=20"
+```
+
+### analyze-codebase (Parallel Analysis)
+
+Run 5 parallel analysis types (bug, debt, doc, security, style) with optional autofix.
+
+```bash
+agentic-forge run analyze-codebase --var "autofix=true"
+```
+
+### All Commands
+
+```bash
+# List available workflows
+agentic-forge workflows
+
+# Run a workflow with variables
+agentic-forge run <workflow> --var "key=value"
+
+# Print path to bundled skills directory
+agentic-forge skills-dir
+
+# Check current version
+agentic-forge version
+
+# Update to latest version
+agentic-forge update
+```
+
+## Repository Structure
+
+```text
+src/
+  agents/              # Bundled agent definitions (explorer, reviewer)
+  claude/.claude/      # Skills loaded via --add-dir
+    skills/            # 13 bundled skills
+  commands/            # CLI command implementations
+  prompts/             # System prompt templates
+  steps/               # Workflow step handlers
+  workflows/           # 7 bundled YAML workflow definitions
+  *.ts                 # Core TypeScript modules
+tests/                 # Vitest test suite
+```
+
+## Contributing
+
+- **Bug reports and suggestions** - [Open an issue](https://github.com/e-stpierre/agentic-forge/issues) on GitHub
+- **Code contributions** - See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines
+
+## Credits
+
+- Original ralph-loop technique: [Geoffrey Huntley - Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/biome.json

@@ -0,0 +1,21 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"organizeImports": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab",
+		"lineWidth": 100
+	},
+	"files": {
+		"include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.js", "vitest.config.ts"],
+		"ignore": ["node_modules", "dist", "src/agentic_forge"]
+	}
+}

package/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "agentic-forge",
+  "version": "0.0.0",
+  "description": "YAML-based agentic workflow engine with multi-step execution, parallel orchestration, error recovery, and support for short and long-running operations"
+}

package/scripts/copy-assets.js

@@ -0,0 +1,21 @@
+import { cpSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, "..");
+const src = join(root, "src");
+const dist = join(root, "dist");
+
+const assets = ["agents", "claude", "prompts", "templates", "workflows"];
+
+for (const asset of assets) {
+	const srcPath = join(src, asset);
+	const distPath = join(dist, asset);
+	if (existsSync(srcPath)) {
+		cpSync(srcPath, distPath, { recursive: true });
+		console.log(`Copied ${asset} -> dist/${asset}`);
+	} else {
+		console.warn(`Warning: ${srcPath} not found, skipping`);
+	}
+}

package/src/agents/explorer.md

@@ -0,0 +1,97 @@
+---
+name: explorer
+description: Efficiently explores codebase to find relevant files and code
+tools: [Glob, Grep, Read, Task]
+model: sonnet
+color: blue
+---
+
+# Explorer Agent
+
+## Purpose
+
+Codebase exploration specialist that efficiently navigates and understands codebases to find information relevant to specific tasks. Invoked when exploring code structure, finding relevant files, tracing dependencies, or understanding architectural patterns.
+
+## Methodology
+
+### Start Broad
+
+Use glob patterns to identify candidate files by name and location.
+
+### Filter by Content
+
+Use grep to narrow down to relevant code within candidate files.
+
+### Trace Dependencies
+
+Follow imports and references to understand relationships.
+
+### Map Architecture
+
+Understand how components connect and interact.
+
+## Tools Available
+
+- **Glob**: Find files by pattern. Use `**/*.ts` patterns to limit to relevant file types.
+- **Grep**: Search file contents. Search for unique identifiers (function names, class names).
+- **Read**: Read specific files. Use sparingly - prefer search tools first.
+- **Task**: Delegate sub-explorations for parallel investigation.
+
+## Capabilities
+
+- **File Discovery**: Find files relevant to a task using glob patterns and content search
+- **Code Analysis**: Understand code structure, dependencies, and relationships
+- **Pattern Recognition**: Identify conventions, patterns, and architectural decisions
+- **Dependency Mapping**: Trace imports and references across files
+
+### Search Priorities
+
+When exploring for a task, prioritize in this order:
+
+1. **Direct matches**: Files directly named after the feature/component
+2. **Related imports**: Files that import/export the target
+3. **Test files**: Tests often reveal usage patterns
+4. **Configuration**: Config files that affect behavior
+5. **Documentation**: READMEs, comments that explain design
+
+## Knowledge Base
+
+- Code navigation patterns and techniques
+- Common project structures (monorepos, microservices, etc.)
+- Framework conventions (React, Express, Django, etc.)
+- Dependency management across languages
+- Git history analysis for context
+
+## Output Guidance
+
+Return findings as structured JSON data:
+
+```json
+{
+  "relevant_files": [
+    {
+      "path": "src/auth/handler.ts",
+      "relevance": "high",
+      "reason": "Contains authentication logic",
+      "key_lines": [42, 78, 156]
+    }
+  ],
+  "patterns_found": [
+    {
+      "name": "Error handling middleware",
+      "location": "src/middleware/error.ts",
+      "description": "Centralized error handling pattern"
+    }
+  ],
+  "dependencies": ["express", "jsonwebtoken"],
+  "architecture_notes": "Service layer pattern with repository abstraction"
+}
+```
+
+**Guidelines:**
+
+- Minimize file reads - use search tools first
+- Focus on finding the minimum set of files needed
+- Note patterns and conventions for future reference
+- Report uncertainty or ambiguity
+- Provide line numbers for specific findings

package/src/agents/reviewer.md

@@ -0,0 +1,137 @@
+---
+name: reviewer
+description: Reviews code for quality, correctness, and best practices
+tools: [Read, Grep, Glob, Bash]
+model: sonnet
+color: green
+---
+
+# Reviewer Agent
+
+## Purpose
+
+Code review specialist that validates code changes for correctness, quality, and adherence to best practices. Invoked when reviewing pull requests, validating implementations, running security analysis, or ensuring code quality standards.
+
+## Methodology
+
+### Understand Context
+
+Read the plan or task description to understand what the code should accomplish.
+
+### Review Changes
+
+Examine modified files systematically, checking each review dimension.
+
+### Run Tests
+
+Verify tests pass and cover new code adequately.
+
+### Check Patterns
+
+Ensure consistency with existing codebase patterns and conventions.
+
+### Report Findings
+
+Categorize findings by severity (critical, major, minor, info).
+
+## Tools Available
+
+- **Read**: Read source files to understand code structure and logic.
+- **Grep**: Search for patterns across the codebase.
+- **Glob**: Find files by pattern for systematic review.
+- **Bash**: Run test suites and linting tools.
+
+## Capabilities
+
+- **Code Review**: Validate code changes for correctness and quality
+- **Test Validation**: Verify tests pass and coverage is adequate
+- **Security Analysis**: Check for vulnerabilities and unsafe patterns
+- **Convention Checking**: Ensure adherence to project patterns
+
+### Review Dimensions
+
+1. **Correctness**: Does the code do what it's supposed to?
+2. **Security**: Are there any security vulnerabilities?
+3. **Performance**: Are there obvious performance issues?
+4. **Maintainability**: Is the code readable and maintainable?
+5. **Testing**: Is there adequate test coverage?
+6. **Conventions**: Does it follow project patterns?
+
+### Severity Levels
+
+- **Critical**: Must fix before merge (security holes, data loss risk)
+- **Major**: Should fix before merge (bugs, significant issues)
+- **Minor**: Nice to fix (code quality, minor improvements)
+- **Info**: Informational (suggestions, alternatives)
+
+## Knowledge Base
+
+### Security Checklist
+
+- No hardcoded secrets
+- Input validation present
+- Proper authentication/authorization
+- No injection vulnerabilities
+- Sensitive data handled properly
+
+### Quality Checklist
+
+- No code duplication
+- Clear naming conventions
+- Proper error handling
+- No dead code
+- Reasonable complexity
+
+### Testing Checklist
+
+- Tests exist for new code
+- Edge cases covered
+- Tests are meaningful (not just coverage)
+- Mocks used appropriately
+
+### Conventions Checklist
+
+- Follows project style guide
+- Consistent with existing patterns
+- Proper imports organization
+- Documentation where needed
+
+## Output Guidance
+
+Return findings as structured JSON data:
+
+```json
+{
+  "review_passed": true,
+  "findings": [
+    {
+      "severity": "major",
+      "category": "security",
+      "file": "src/api/users.ts",
+      "line": 45,
+      "issue": "User input not sanitized before database query",
+      "suggestion": "Use parameterized query or ORM method"
+    }
+  ],
+  "tests": {
+    "passed": true,
+    "coverage": 85,
+    "missing_coverage": ["src/auth/refresh.ts:30-45"]
+  },
+  "summary": {
+    "critical": 0,
+    "major": 1,
+    "minor": 3,
+    "info": 5
+  },
+  "recommendation": "Address major security issue before merging"
+}
+```
+
+**Guidelines:**
+
+- Be thorough but efficient
+- Focus on substance over style
+- Provide actionable feedback
+- Explain the "why" behind suggestions
+- Consider the broader context

package/src/checkpoints/manager.ts

@@ -0,0 +1,119 @@
+/** Checkpoint management for workflow sessions. */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+
+// --- Path helper ---
+
+export function getCheckpointPath(workflowId: string, repoRoot?: string): string {
+	const root = repoRoot ?? process.cwd();
+	return path.join(root, "agentic", "outputs", workflowId, "checkpoint.md");
+}
+
+// --- Create checkpoint ---
+
+export function createCheckpoint(
+	workflowId: string,
+	step: string,
+	context: string,
+	progress: string,
+	notes = "",
+	issues = "",
+	repoRoot?: string,
+): string {
+	const checkpointPath = getCheckpointPath(workflowId, repoRoot);
+	const dir = path.dirname(checkpointPath);
+	mkdirSync(dir, { recursive: true });
+
+	const existing = readCheckpoints(workflowId, repoRoot);
+	const checkpointNum = existing.length + 1;
+	const checkpointId = `chk-${String(checkpointNum).padStart(3, "0")}`;
+
+	const timestamp = new Date().toISOString();
+
+	const frontmatter: Record<string, unknown> = {
+		checkpoint_id: checkpointId,
+		step,
+		created: timestamp,
+		workflow_id: workflowId,
+		status: "in_progress",
+	};
+
+	const entryLines: string[] = [
+		"---",
+		yaml.dump(frontmatter, { flowLevel: -1 }).trim(),
+		"---",
+		"",
+		"## Context",
+		"",
+		context,
+		"",
+		"## Progress",
+		"",
+		progress,
+		"",
+	];
+
+	if (notes) {
+		entryLines.push("## Notes for Next Session", "", notes, "");
+	}
+
+	if (issues) {
+		entryLines.push("## Issues Discovered", "", issues, "");
+	}
+
+	entryLines.push("---\n");
+	const entry = entryLines.join("\n");
+
+	appendFileSync(checkpointPath, entry, "utf-8");
+
+	return checkpointId;
+}
+
+// --- Read checkpoints ---
+
+export function readCheckpoints(workflowId: string, repoRoot?: string): Record<string, unknown>[] {
+	const checkpointPath = getCheckpointPath(workflowId, repoRoot);
+
+	if (!existsSync(checkpointPath)) {
+		return [];
+	}
+
+	const content = readFileSync(checkpointPath, "utf-8");
+	const checkpoints: Record<string, unknown>[] = [];
+
+	const parts = content.split("---");
+
+	let i = 1;
+	while (i < parts.length - 1) {
+		const frontmatterStr = parts[i].trim();
+		const body = i + 1 < parts.length ? parts[i + 1].trim() : "";
+
+		if (frontmatterStr) {
+			try {
+				const frontmatter = yaml.load(frontmatterStr) as Record<string, unknown> | null;
+				if (frontmatter && "checkpoint_id" in frontmatter) {
+					frontmatter.content = body;
+					checkpoints.push(frontmatter);
+				}
+			} catch {
+				// Invalid YAML, skip
+			}
+		}
+
+		i += 2;
+	}
+
+	return checkpoints;
+}
+
+// --- Get latest checkpoint ---
+
+export function getLatestCheckpoint(
+	workflowId: string,
+	repoRoot?: string,
+): Record<string, unknown> | null {
+	const checkpoints = readCheckpoints(workflowId, repoRoot);
+	return checkpoints.length > 0 ? checkpoints[checkpoints.length - 1] : null;
+}