agentic-forge 0.0.0 → 0.7.1

package/CLAUDE.md

@@ -1,158 +0,0 @@
-# Claude Context: agentic-forge Repository
-
-## Project 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.
-
-## Purpose
-
-The agentic-forge repository aims to:
-
-1. **Share Best Practices**: Provide battle-tested automation patterns and workflows
-2. **Accelerate Development**: Offer ready-to-use components that solve common problems
-3. **Automate Development**: Offer reusable and flexible workflows that enable the automation of development tasks during the whole SDLC life-cycle
-
-## Repository Structure
-
-### `src/`
-
-TypeScript source code for the CLI and workflow orchestration engine.
-
-#### `agents/`
-
-Bundled sub-agent configurations for specialized, autonomous task execution (`explorer.md`, `reviewer.md`). Agents should be self-contained and focused on a specific domain or task.
-
-#### `claude/.claude/skills/`
-
-Bundled skills loaded via `--add-dir`. Skills are reusable Claude Code slash commands. Each skill is a directory in kebab-case containing a `SKILL.md` file.
-
-#### `commands/`
-
-CLI command implementations (`run`, `init`, `update`, `skills-dir`, `workflows`, etc.).
-
-#### `prompts/`
-
-System prompt templates used by the workflow runner.
-
-#### `steps/`
-
-Workflow step handlers (prompt, parallel, serial, conditional, ralph-loop).
-
-#### `workflows/`
-
-Bundled YAML workflow definitions (7 workflows: `plan-build-review`, `one-shot`, `ralph-loop`, `analyze-codebase`, `analyze-codebase-merge`, `analyze-single`, `demo`).
-
-### `tests/`
-
-Vitest test suite for all TypeScript source code.
-
-### `agentic/`
-
-Runtime directory for workflow configuration, outputs, and logs.
-
-## Development Guidelines
-
-### Language Style
-
-Use US English spelling in all code, comments, documentation, and UI strings when a word has both UK and US variants (e.g., "analyze" not "analyse", "color" not "colour", "canceled" not "cancelled").
-
-### Naming Conventions
-
-- **Agents**: Use descriptive names with domain prefix (e.g., `explorer.md`, `reviewer.md`)
-- **Skills**: Directory name in kebab-case with `SKILL.md` inside (e.g., `analyze/SKILL.md`, `git-commit/SKILL.md`)
-- **Workflows**: Descriptive kebab-case YAML files (e.g., `plan-build-review.yaml`)
-
-### Documentation Guidelines
-
-- **Character encoding**: Code files must use ASCII only. Documentation and markdown files (skills, agents, READMEs) may use minimal emojis where they add clarity (e.g., checkmarks, robot emoji for Claude attribution). Avoid decorative emoji use.
-- **Workflow diagrams**: Use arrow notation (`->`) for workflow documentation instead of long multi-line ASCII boxes. Example: `Plan -> Implement -> Review -> Output` is preferred over complex box diagrams
-
-### File Formats
-
-- **Agents**: Markdown (`.md`) files in `src/agents/`
-- **Skills**: `SKILL.md` files in skill directories: `src/claude/.claude/skills/<skill-name>/SKILL.md`
-- **Workflows**: YAML files in `src/workflows/`
-- **TypeScript Source**: TypeScript modules in `src/` with root `package.json`
-
-**Placeholder Convention:**
-
-Prompt templates use **Mustache/Handlebars-style placeholders** with the following format:
-
-```markdown
-## {{section_title}}
-
-{{content}}
-
-<!--
-Instructions:
-- Replace {{content}} with the actual content
-- Additional guidance for this section
-- Suggested elements (include others as needed):
-  - Element 1
-  - Element 2
--->
-```
-
-**Key principles:**
-
-- Use `{{variable_name}}` for all placeholders (not `<placeholder>` or other formats)
-- Include HTML comments with instructions below each section
-- Mark suggested elements as "include others as needed" to allow flexibility
-- Required sections must be present; optional sections can be omitted
-- Section names must match the template exactly (case-sensitive)
-
-**Validation:**
-
-Use the `/normalize` command to validate prompt files against templates:
-
-```bash
-# Validate all prompts in the repository
-/normalize
-
-# Validate specific files or directories
-/normalize src/claude/.claude/skills/
-
-# Auto-fix non-compliant files
-/normalize --autofix src/claude/.claude/skills/
-```
-
-### Shell Commands
-
-Run shell commands directly without prefixing with `cd` to the repository root. The working directory is already set correctly, and unnecessary `cd` prefixes create distinct command strings that trigger extra permission prompts.
-
-```bash
-# Good
-git status
-pnpm test
-
-# Bad - unnecessary cd causes extra permission approval
-cd "c:/Repositories/agentic-forge" && git status
-```
-
-### Code Style and Formatting
-
-CI validates format, lint, and tests on all pull requests. Run locally before opening a pull request:
-
-```bash
-pnpm check          # Format and lint (biome)
-pnpm test           # Vitest tests
-```
-
-## Technical Considerations
-
-### Workflow Engine Changes
-
-When modifying the workflow engine in `src/`, you must update the workflow-builder skill reference files to keep them in sync:
-
-- `src/claude/.claude/skills/workflow-builder/references/REFERENCE.md` - Complete schema reference
-- `src/claude/.claude/skills/workflow-builder/references/workflow-example.yaml` - Annotated reference workflow
-
-Changes to workflow settings, step types, or features require updates to both files.
-
-### Node.js Development
-
-- **Always use `pnpm` for package management**: This repository uses pnpm for all Node.js operations
-- **Building**: Use `pnpm build` (runs `tsc` + asset copy script)
-- **Testing**: Use `pnpm test` (runs Vitest)
-- **Linting**: Use `pnpm check` (runs Biome)
-- **Development**: Use `pnpm dev` for TypeScript watch mode

package/CONTRIBUTING.md

@@ -1,152 +0,0 @@
-# Contributing to Agentic Forge
-
-Thank you for your interest in contributing! This guide will help you get started.
-
-## Ways to Contribute
-
-- **Report bugs** - Found something broken? [Open an issue](https://github.com/e-stpierre/agentic-forge/issues)
-- **Suggest features** - Have an idea for a new workflow or enhancement? [Let us know](https://github.com/e-stpierre/agentic-forge/issues)
-- **Improve docs** - Fix typos, clarify explanations, add examples
-- **Write code** - Bug fixes, new skills, improvements to existing ones
-
-## Development Setup
-
-### Prerequisites
-
-- [Claude Code](https://claude.ai/code) installed
-- Git
-- Node.js 20+
-- [pnpm](https://pnpm.io/) for package management
-
-### Local Development
-
-```bash
-# Clone the repo
-git clone https://github.com/e-stpierre/agentic-forge.git
-cd agentic-forge
-
-# Install dependencies
-pnpm install
-
-# Build
-pnpm build
-
-# Run tests
-pnpm test
-
-# Run format and lint checks
-pnpm check
-```
-
-## Making Changes
-
-### Branch Naming
-
-- `feature/description` - New features
-- `fix/description` - Bug fixes
-- `doc/description` - Documentation updates
-- `refactor/description` - Refactoring
-
-### Commit Messages
-
-Write clear, concise commit messages that describe the change. For example: `Add retry logic to workflow executor` or `Fix validation error in analyze skill`.
-
-### Code Formatting
-
-Run format, lint, and test checks locally before submitting a PR:
-
-```bash
-pnpm check          # Format and lint (Biome)
-pnpm test           # Vitest tests
-```
-
-## Internal Tools
-
-- **`/normalize`** - Validate prompt files and READMEs against templates. Use `--autofix` to auto-fix issues.
-
-## Project Structure
-
-```text
-src/
-  agents/              # Sub-agent definitions (.md)
-  claude/.claude/      # Skills loaded via --add-dir
-    skills/            # Bundled skills (slash commands)
-  commands/            # CLI command implementations
-  prompts/             # System prompt templates
-  steps/               # Workflow step handlers
-  workflows/           # YAML workflow definitions
-  *.ts                 # Core TypeScript modules
-tests/                 # Vitest test suite
-```
-
-### Naming Conventions
-
-- **Agents**: descriptive with domain prefix (`explorer.md`, `reviewer.md`)
-- **Skills**: directory name in kebab-case with `SKILL.md` inside (`analyze/SKILL.md`, `git-commit/SKILL.md`)
-- **Workflows**: descriptive kebab-case YAML files (`plan-build-review.yaml`)
-
-### Prompt Templates
-
-All prompts must follow the templates in the repository. Use the `/normalize` command inside Claude Code to validate.
-
-```bash
-# Validate all prompts
-/normalize
-
-# Validate specific files
-/normalize src/claude/.claude/skills/my-skill/
-
-# Auto-fix non-compliant files
-/normalize --autofix src/claude/.claude/skills/
-```
-
-## Pull Request Process
-
-### Workflow
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Make your changes
-4. Run `pnpm check` to verify formatting
-5. Run `pnpm test` to run the test suite
-6. Run `/normalize` (inside Claude Code) to validate prompt files
-7. Commit your changes with clear messages
-8. Push to your fork
-9. Open a pull request
-
-### PR Checklist
-
-- [ ] CI pipeline passes (format, lint, tests)
-- [ ] Prompt templates validated (`/normalize`)
-- [ ] CHANGELOG updated if applicable
-- [ ] Changes tested with Claude Code
-
-## Reporting Issues
-
-### Bug Reports
-
-Include:
-
-- Steps to reproduce
-- Expected vs actual behavior
-- Agentic Forge version
-- Claude Code version
-
-### Feature Requests
-
-Include:
-
-- Description of the feature
-- Use case / motivation
-
-## Code of Conduct
-
-Be respectful and constructive. We're all here to build useful tools together.
-
-## Questions?
-
-[Open an issue](https://github.com/e-stpierre/agentic-forge/issues) with the `question` label.
-
----
-
-Thank you for contributing to Agentic Forge!

package/biome.json

@@ -1,21 +0,0 @@
-{
-	"$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/scripts/copy-assets.js

@@ -1,21 +0,0 @@
-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/checkpoints/manager.ts

@@ -1,119 +0,0 @@
-/** 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;
-}

package/src/cli.ts

@@ -1,182 +0,0 @@
-#!/usr/bin/env node
-
-/** CLI entry point for agentic-forge command. */
-
-import { Command } from "commander";
-
-import {
-	cmdCancel,
-	cmdConfig,
-	cmdConfigure,
-	cmdInit,
-	cmdInput,
-	cmdList,
-	cmdReleaseNotes,
-	cmdResume,
-	cmdRun,
-	cmdSkillsDir,
-	cmdStatus,
-	cmdUpdate,
-	cmdVersion,
-	cmdWorkflows,
-	getVersion,
-} from "./commands/index.js";
-
-const program = new Command()
-	.name("agentic-forge")
-	.version(getVersion())
-	.description("Agentic workflow orchestration for Claude Code");
-
-// run command
-program
-	.command("run")
-	.argument("[workflow]", "workflow name or path to YAML file")
-	.option("--list", "list all available workflows")
-	.option("--var <key=value...>", "set workflow variable (can be used multiple times)")
-	.option("--from-step <step>", "resume from a specific step")
-	.option("--terminal-output <mode>", "terminal output granularity (base or all)")
-	.action(async (workflow: string | undefined, opts: Record<string, unknown>) => {
-		await cmdRun({
-			workflow,
-			listWorkflows: opts.list as boolean | undefined,
-			vars: opts.var as string[] | undefined,
-			fromStep: opts.fromStep as string | undefined,
-			terminalOutput: opts.terminalOutput as string | undefined,
-		});
-	});
-
-// resume command
-program
-	.command("resume")
-	.argument("<workflow_id>", "workflow ID to resume")
-	.option("--terminal-output <mode>", "terminal output granularity (base or all)")
-	.action(async (workflowId: string, opts: Record<string, unknown>) => {
-		await cmdResume({
-			workflowId,
-			terminalOutput: opts.terminalOutput as string | undefined,
-		});
-	});
-
-// status command
-program
-	.command("status")
-	.argument("<workflow_id>", "workflow ID")
-	.action((workflowId: string) => {
-		cmdStatus(workflowId);
-	});
-
-// cancel command
-program
-	.command("cancel")
-	.argument("<workflow_id>", "workflow ID to cancel")
-	.action((workflowId: string) => {
-		cmdCancel(workflowId);
-	});
-
-// list command
-program
-	.command("list")
-	.option("--status <status>", "filter by status (running, completed, failed, paused)")
-	.action((opts: Record<string, unknown>) => {
-		cmdList(opts.status as string | undefined);
-	});
-
-// input command
-program
-	.command("input")
-	.argument("<workflow_id>", "workflow ID")
-	.argument("<response>", "response to provide")
-	.action((workflowId: string, response: string) => {
-		cmdInput(workflowId, response);
-	});
-
-// configure command
-program
-	.command("configure")
-	.description("Configure plugin settings")
-	.action(() => {
-		cmdConfigure();
-	});
-
-// init command
-program
-	.command("init")
-	.description("Copy bundled workflow templates to local project")
-	.option("--force", "overwrite existing workflow files")
-	.option("--list", "list available bundled workflows without copying")
-	.action((opts: Record<string, unknown>) => {
-		cmdInit({
-			force: opts.force as boolean | undefined,
-			listOnly: opts.list as boolean | undefined,
-		});
-	});
-
-// config command with subcommands
-const configCmd = program.command("config").description("Get or set configuration");
-
-configCmd
-	.command("get")
-	.argument("<key>", "configuration key (dot notation)")
-	.action((key: string) => {
-		cmdConfig("get", key);
-	});
-
-configCmd
-	.command("set")
-	.argument("<key>", "configuration key (dot notation)")
-	.argument("<value>", "value to set")
-	.action((key: string, value: string) => {
-		cmdConfig("set", key, value);
-	});
-
-// version command
-program
-	.command("version")
-	.description("Show version information")
-	.action(() => {
-		cmdVersion();
-	});
-
-// release-notes command
-program
-	.command("release-notes")
-	.argument("[version]", "show release notes for a specific version")
-	.option("--latest", "show only the most recent version's release notes")
-	.action((specificVersion: string | undefined, opts: Record<string, unknown>) => {
-		cmdReleaseNotes({
-			specificVersion,
-			latest: opts.latest as boolean | undefined,
-		});
-	});
-
-// skills-dir command
-program
-	.command("skills-dir")
-	.description("Print path to bundled skills directory")
-	.action(() => {
-		cmdSkillsDir();
-	});
-
-// update command
-program
-	.command("update")
-	.description("Update agentic-forge to the latest version")
-	.option("--check", "check for updates without installing")
-	.action((opts: Record<string, unknown>) => {
-		cmdUpdate({
-			check: opts.check as boolean | undefined,
-		});
-	});
-
-// workflows command
-program
-	.command("workflows")
-	.description("List available workflows with descriptions")
-	.option("-v, --verbose", "show workflow variables and full descriptions")
-	.action((opts: Record<string, unknown>) => {
-		cmdWorkflows({
-			verbose: opts.verbose as boolean | undefined,
-		});
-	});
-
-program.parse();

package/src/commands/config-cmd.ts

@@ -1,28 +0,0 @@
-/** Config command handler. */
-
-import { getConfigValue, setConfigValue } from "../config.js";
-
-export function cmdConfig(configCommand: string, key: string, value?: string): void {
-	if (configCommand === "get") {
-		const result = getConfigValue(key);
-		if (result === null) {
-			process.stderr.write(`Key not found: ${key}\n`);
-			process.exit(1);
-		}
-		if (typeof result === "object" && result !== null) {
-			process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-		} else {
-			process.stdout.write(`${result}\n`);
-		}
-	} else if (configCommand === "set") {
-		if (value === undefined) {
-			process.stderr.write("Usage: agentic-forge config set <key> <value>\n");
-			process.exit(1);
-		}
-		setConfigValue(key, value);
-		process.stdout.write(`Set ${key} = ${value}\n`);
-	} else {
-		process.stderr.write("Usage: agentic-forge config get|set <key> [value]\n");
-		process.exit(1);
-	}
-}