agentic-forge 0.0.0

package/src/claude/.claude/skills/workflow-builder/references/workflow-example.yaml

@@ -0,0 +1,427 @@
+# Annotated Reference Workflow
+# This workflow demonstrates all available configuration options and step types
+# Use this as a template for creating your own workflows
+
+# Required: Unique workflow identifier
+name: complete-workflow-example
+
+# Required: Schema version
+version: "1.0"
+
+# Optional: Human-readable description
+description: |
+  Comprehensive example workflow demonstrating all available features:
+  - All step types (prompt, serial, parallel, conditional, ralph-loop, wait-for-human)
+  - Git integration with worktrees
+  - Error handling and retries
+  - Checkpoints and progress tracking
+  - Variable templating with Jinja2
+  - Output generation
+
+# Optional: Workflow-level settings
+settings:
+  # Maximum retry attempts for failed steps (default: 3)
+  max-retry: 3
+
+  # Maximum time for entire workflow in minutes (default: 60)
+  timeout-minutes: 180
+
+  # Track progress in progress.json file (default: true)
+  track-progress: true
+
+  # Auto-fix severity level: none, minor, major, critical (default: none)
+  autofix: "major"
+
+  # Terminal output mode: base (last message), all (stream all) (default: base)
+  terminal-output: "base"
+
+  # Bypass permission prompts - use with caution (default: false)
+  bypass-permissions: false
+
+  # Template variable handling: false = warn and continue, true = fail on undefined (default: false)
+  strict-mode: false
+
+  # Default model for all steps: sonnet, haiku, opus (default: user-configured or sonnet)
+  # Steps can override this with their own model setting
+  model: sonnet
+
+  # Tools Claude can use without prompting (default: [])
+  required-tools:
+    - "Bash"
+    - "Edit"
+    - "Write"
+    - "Read"
+
+  # Git configuration
+  git:
+    # Enable git operations (default: false)
+    enabled: true
+
+    # Use worktrees for parallel steps (default: false)
+    worktree: true
+
+    # Auto-commit changes after each step (default: true)
+    auto-commit: true
+
+    # Auto-create PR when workflow completes (default: true)
+    auto-pr: false
+
+    # Prefix for branch names (default: "agentic")
+    branch-prefix: "feature"
+
+# Optional: Input variables for the workflow
+variables:
+  # Required string variable
+  - name: task
+    type: string
+    required: true
+    description: Task description for implementation
+
+  # Optional string variable with default
+  - name: plan_type
+    type: string
+    required: false
+    default: "auto"
+    description: Plan type (feature, bug, chore, auto)
+
+  # Optional boolean variable
+  - name: create_pr
+    type: boolean
+    required: false
+    default: true
+    description: Whether to create a pull request
+
+  # Optional number variable
+  - name: max_iterations
+    type: number
+    required: false
+    default: 10
+    description: Maximum iterations for ralph loop
+
+  # Optional severity level
+  - name: fix_severity
+    type: string
+    required: false
+    default: "major"
+    description: Minimum severity for auto-fixing issues
+
+# Required: Workflow steps
+steps:
+  # ==================== PROMPT STEP ====================
+  # Execute a custom prompt in a Claude session
+  - name: analyze-requirements
+    type: prompt
+    prompt: |
+      Analyze the following task and provide a detailed breakdown:
+
+      Task: {{ variables.task }}
+
+      Provide:
+      1. Key requirements
+      2. Potential challenges
+      3. Recommended approach
+
+    # Optional: Model to use (sonnet, haiku, opus)
+    model: sonnet
+
+    # Optional: Timeout for this step (overrides workflow timeout)
+    timeout-minutes: 15
+
+    # Optional: Max retry attempts (overrides workflow setting)
+    max-retry: 2
+
+    # Optional: Error handling strategy (retry, skip, fail)
+    on-error: retry
+
+    # Optional: Create checkpoint after this step completes
+    checkpoint: false
+
+  # ==================== SKILL INVOCATION ====================
+  # Invoke a Claude slash command skill
+  # IMPORTANT: Always use fully qualified skill names in workflows (e.g., /sdlc-plan)
+  # to avoid conflicts with skills from other plugins or built-in commands.
+  - name: generate-plan
+    type: prompt
+    prompt: /sdlc-plan --type {{ variables.plan_type }} --output_dir "agentic/outputs/{{ workflow_id }}" {{ variables.task }}
+    checkpoint: true
+    timeout-minutes: 20
+
+  # ==================== SERIAL STEP ====================
+  # Execute nested steps sequentially
+  - name: sequential-implementation
+    type: serial
+    steps:
+      - name: setup-environment
+        type: prompt
+        prompt: "Prepare the development environment for implementation"
+
+      - name: install-dependencies
+        type: prompt
+        prompt: "Install required dependencies"
+
+      - name: create-files
+        type: prompt
+        prompt: "Create necessary files and directory structure"
+
+  # ==================== PARALLEL STEP ====================
+  # Execute nested steps concurrently in git worktrees
+  - name: parallel-analysis
+    type: parallel
+
+    # Merge strategy: wait-all (wait for all steps to complete)
+    merge-strategy: wait-all
+
+    # Merge mode: independent (no merging), merge (merge branches)
+    merge-mode: independent
+
+    # Git configuration for parallel execution
+    git:
+      # Run each parallel step in separate worktree
+      worktree: true
+
+      # Prefix for parallel branch names
+      branch-prefix: "analysis"
+
+    # Parallel steps
+    steps:
+      - name: security-scan
+        type: prompt
+        prompt: /analyze security
+        on-error: skip # Don't fail workflow if security scan fails
+
+      - name: style-check
+        type: prompt
+        prompt: /analyze style
+        on-error: skip
+
+      - name: bug-detection
+        type: prompt
+        prompt: /analyze bug
+        on-error: skip
+
+      - name: debt-analysis
+        type: prompt
+        prompt: /analyze debt
+        on-error: skip
+
+  # ==================== RALPH LOOP STEP ====================
+  # Iterative prompt execution with completion detection
+  - name: implement-incrementally
+    type: ralph-loop
+
+    # Prompt executed in each iteration
+    prompt: |
+      ## Ralph Loop Iteration
+
+      Read the implementation plan at agentic/outputs/{{ workflow_id }}/plan.md
+
+      Implement the NEXT INCOMPLETE milestone:
+      1. Read the plan and identify the next incomplete milestone
+      2. Implement all tasks in that milestone
+      3. Run tests to verify your implementation
+      4. Commit your changes with a descriptive message
+      5. Mark the milestone as complete in the plan file
+
+      **IMPORTANT**: When ALL milestones in the plan are marked as complete, output:
+      ```json
+      {"ralph_complete": true, "promise": "ALL_MILESTONES_COMPLETE"}
+      ```
+
+      Do NOT output the completion JSON until every milestone is genuinely finished.
+
+      Current iteration state is tracked in agentic/outputs/{{ workflow_id }}/ralph-implement-incrementally.md
+
+    # Maximum iterations before stopping (can use variable)
+    max-iterations: "{{ variables.max_iterations }}"
+
+    # Completion promise text to match in JSON output
+    completion-promise: "ALL_MILESTONES_COMPLETE"
+
+    # Model to use for each iteration
+    model: sonnet
+
+    # Create checkpoint after loop completes
+    checkpoint: true
+
+    # Timeout for entire loop
+    timeout-minutes: 120
+
+  # ==================== REVIEW STEP ====================
+  - name: review-implementation
+    type: prompt
+    prompt: /sdlc-review "agentic/outputs/{{ workflow_id }}/plan.md" minor
+    checkpoint: true
+
+  # ==================== CONDITIONAL STEP ====================
+  # Execute steps based on Jinja2 condition
+  - name: fix-validation-issues
+    type: conditional
+
+    # Jinja2 expression that evaluates to true/false
+    # This checks if there are any issues with severity >= fix_severity
+    condition: "{{ outputs.review_implementation.issues | selectattr('severity', 'ge', variables.fix_severity) | list | length > 0 }}"
+
+    # Steps to execute if condition is true
+    then:
+      - name: apply-fixes
+        type: prompt
+        prompt: |
+          The validation found issues that need to be fixed.
+
+          Issues to fix (severity {{ variables.fix_severity }} or higher):
+          {{ outputs.review_implementation.issues | tojson(indent=2) }}
+
+          Please fix these issues and commit your changes.
+        model: sonnet
+        timeout-minutes: 30
+
+      - name: re-review
+        type: prompt
+        prompt: /sdlc-review "" {{ variables.fix_severity }}
+
+    # Steps to execute if condition is false
+    else:
+      - name: log-success
+        type: prompt
+        prompt: "Validation passed! No issues found at severity {{ variables.fix_severity }} or higher."
+
+  # ==================== WAIT FOR HUMAN STEP ====================
+  # Pause workflow and wait for human input
+  - name: request-approval
+    type: wait-for-human
+
+    # Message shown to human
+    message: |
+      Please review the implementation and validation results.
+
+      Review the following:
+      - Implementation plan: agentic/outputs/{{ workflow_id }}/plan.md
+      - Review results: outputs.review_implementation
+
+      Respond with:
+      - "approved" to continue and create PR
+      - "rejected" to stop without PR
+      - Provide feedback for additional changes
+
+    # Polling interval in seconds (default: 15)
+    polling-interval: 30
+
+    # Action on timeout: abort (stop workflow), continue (proceed anyway)
+    on-timeout: abort
+
+    # Timeout in minutes (default: 1440 = 24 hours)
+    timeout-minutes: 120
+
+  # ==================== CONDITIONAL STEP (CREATE PR) ====================
+  - name: create-pull-request
+    type: conditional
+    condition: "{{ variables.create_pr and outputs.request_approval.response == 'approved' }}"
+    then:
+      - name: open-pr
+        type: prompt
+        prompt: /git-pr --title "[{{ variables.plan_type }}] {{ outputs.generate_plan.summary }}"
+
+  # ==================== FINAL SUMMARY ====================
+  - name: generate-summary
+    type: prompt
+    prompt: |
+      Generate a summary of the workflow execution.
+
+      Include:
+      - Task: {{ variables.task }}
+      - Plan type: {{ variables.plan_type }}
+      - Review results: {{ outputs.review_implementation | tojson }}
+      - PR created: {{ outputs.create_pull_request is defined }}
+
+      Save the summary to agentic/outputs/{{ workflow_id }}/summary.md
+
+# Optional: Output artifacts
+outputs:
+  # Generated when workflow completes successfully
+  - name: implementation-report
+    # Jinja2 template file (resolved from workflow dir, agentic/templates/, or bundled templates)
+    template: implementation-report.md.j2
+    # Output file path (relative to workflow directory)
+    path: agentic/outputs/{{ workflow_id }}/report.md
+    # When to generate: completed or failed
+    when: completed
+
+  # Generated when workflow fails
+  - name: error-report
+    template: error-report.md.j2
+    path: agentic/outputs/{{ workflow_id }}/error.md
+    when: failed
+
+# ==================== USAGE EXAMPLES ====================
+#
+# Run with required variable:
+#   agentic-forge run workflow-example.yaml --var "task=Add user authentication"
+#
+# Run with custom variables:
+#   agentic-forge run workflow-example.yaml \
+#     --var "task=Fix login bug" \
+#     --var "plan_type=bug" \
+#     --var "create_pr=true" \
+#     --var "max_iterations=15"
+#
+# Run with verbose output:
+#   agentic-forge run workflow-example.yaml \
+#     --var "task=Implement feature" \
+#     --terminal-output all
+#
+# Resume from specific step:
+#   agentic-forge run workflow-example.yaml \
+#     --var "task=Implement feature" \
+#     --from-step review-implementation
+#
+# Provide human input:
+#   agentic-forge input <workflow-id> "approved"
+#
+# Check workflow status:
+#   agentic-forge status <workflow-id>
+#
+# ==================== AVAILABLE SKILLS ====================
+#
+# IMPORTANT: Always use fully qualified skill names in workflows to avoid conflicts
+# with skills from other plugins or built-in commands.
+#
+# Skills you can invoke via prompt steps:
+#
+# Planning & Review:
+#   - /sdlc-plan - Generate implementation plan
+#   - /sdlc-review - Review implementation quality
+#
+# Analysis:
+#   - /analyze bug - Find bugs and logic errors
+#   - /analyze debt - Identify technical debt
+#   - /analyze doc - Check documentation
+#   - /analyze security - Security scan
+#   - /analyze style - Code style check
+#
+# Git Operations:
+#   - /git-branch - Create git branch
+#   - /git-commit - Create commit
+#   - /git-pr - Create pull request
+#
+# Workflow Support:
+#   - /orchestrate - Workflow state evaluation
+#
+# ==================== BUILT-IN VARIABLES ====================
+#
+# Available in all Jinja2 templates:
+#   - {{ workflow_id }}              - Unique workflow execution ID
+#   - {{ workflow_name }}            - Workflow name from YAML
+#   - {{ variables.name }}           - User-defined variables
+#   - {{ outputs.step_name.field }}  - Step outputs
+#
+# ==================== JINJA2 FILTERS ====================
+#
+# Common filters for templating:
+#   - {{ list | length }}            - Get list length
+#   - {{ list | first }}             - Get first item
+#   - {{ list | last }}              - Get last item
+#   - {{ list | selectattr('key', 'eq', 'value') }}  - Filter list
+#   - {{ text | upper }}             - Uppercase
+#   - {{ text | lower }}             - Lowercase
+#   - {{ data | tojson }}            - Convert to JSON
+#   - {{ data | tojson(indent=2) }}  - Pretty JSON

package/src/cli.ts

@@ -0,0 +1,182 @@
+#!/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

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

package/src/commands/index.ts

@@ -0,0 +1,21 @@
+/** Command handler exports. */
+
+export {
+	cmdRun,
+	discoverWorkflow,
+	listAvailableWorkflows,
+	resolveWorkflowPath,
+	getBundledWorkflowsDir,
+	getUserWorkflowsDir,
+	getProjectWorkflowsDir,
+} from "./run.js";
+export { cmdResume } from "./resume.js";
+export { cmdStatus, cmdCancel, cmdList } from "./status.js";
+export { cmdInit, cmdConfigure } from "./init.js";
+export { cmdConfig } from "./config-cmd.js";
+export { cmdVersion, getVersion } from "./version.js";
+export { cmdUpdate } from "./update.js";
+export { cmdReleaseNotes } from "./release-notes.js";
+export { cmdSkillsDir } from "./skills-dir.js";
+export { cmdWorkflows } from "./workflows.js";
+export { cmdInput } from "./shortcuts.js";