agentic-forge 0.0.0

package/src/claude/.claude/skills/create-log/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: af-create-log
+description: Add a log entry to the workflow log
+argument-hint: <workflow-id> <level> <step> <message>
+---
+
+# Create Log
+
+## Overview
+
+Add a structured log entry to the workflow's NDJSON log file. Use this skill for progress milestones, errors, warnings, decisions, and context that should be recorded. Creates a structured log entry in the workflow's log file for tracking and debugging.
+
+## Arguments
+
+### Definitions
+
+- **`<workflow-id>`** (required): The workflow identifier for output organization.
+- **`<level>`** (required): Log level. Values: `Critical`, `Error`, `Warning`, `Information`.
+- **`<step>`** (required): Step name for context (e.g., analyze, plan, review).
+- **`<message>`** (required): Log message.
+
+### Values
+
+\$ARGUMENTS
+
+## Core Principles
+
+- Use appropriate log levels for severity
+- Include step context for traceability
+- Messages should be concise but informative
+- Logs are append-only
+
+### Log Levels
+
+| Level       | When to Use                              |
+| ----------- | ---------------------------------------- |
+| Critical    | Fatal error causing workflow to stop     |
+| Error       | Any error that occurred                  |
+| Warning     | Unexpected issue that may need attention |
+| Information | Regular progress logging                 |
+
+## Instructions
+
+1. Parse the workflow-id, level, step, and message
+2. Generate timestamp in ISO 8601 format
+3. Create NDJSON log entry
+4. Append to `agentic/outputs/{workflow-id}/logs.ndjson`
+5. Return confirmation with entry details
+
+## Output Guidance
+
+Return JSON confirmation:
+
+```json
+{
+  "success": true,
+  "entry": {
+    "timestamp": "2024-01-15T10:30:00Z",
+    "level": "Information",
+    "step": "implement",
+    "message": "Completed milestone 1"
+  }
+}
+```
+
+## Templates
+
+### Log File Format
+
+Logs are stored in `agentic/outputs/{workflow-id}/logs.ndjson` as NDJSON:
+
+```json
+{"timestamp":"2024-01-15T10:30:00Z","level":"Information","step":"implement","message":"Started implementation","context":null}
+{"timestamp":"2024-01-15T10:35:00Z","level":"Warning","step":"implement","message":"Rate limit approached","context":{"remaining":10}}
+```

package/src/claude/.claude/skills/fix-analyze/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: af-fix-analyze
+description: Fix issues from an analysis document iteratively
+argument-hint: <type> <severity> [context]
+---
+
+# Fix Analysis Issues
+
+## Overview
+
+Iteratively fix issues identified in an analysis document. This skill reads the analysis output, prioritizes issues by severity, and fixes them one at a time. Use this skill after running any of the analyze commands (bug, debt, doc, security, style) when autofix is enabled.
+
+## Arguments
+
+### Definitions
+
+- **`<type>`** (required): Analysis type. Values: `bug`, `debt`, `doc`, `security`, `style`.
+- **`<severity>`** (required): Minimum severity to fix. Values: `minor`, `major`, `critical`.
+- **`[context]`** (optional): Additional context or constraints for the fixes.
+
+### Values
+
+\$ARGUMENTS
+
+## Core Principles
+
+- Fix only ONE issue per iteration, then end the session
+- Process issues in severity order (highest first)
+- Skip issues that cannot be fixed and document the reason
+- Verify fixes compile and pass lint before committing
+- Preserve existing functionality when making changes
+- Follow project conventions for code style and patterns
+
+## Instructions
+
+1. **Read the Analysis Document**
+   - Load the analysis document at `agentic/analysis/<type>.md`
+   - If the document does not exist, return the completion promise immediately
+   - Parse the list of issues and their statuses
+
+2. **Select Next Issue**
+   - Filter issues by minimum severity level
+   - Skip issues already marked as fixed or skipped
+   - Select the highest severity unfixed issue
+   - If no qualifying issues remain, return the completion promise
+
+3. **Understand the Issue**
+   - Read the affected file(s) mentioned in the issue
+   - Understand the surrounding context and dependencies
+   - Identify the root cause and potential fix approaches
+
+4. **Implement the Fix**
+   - Make the minimal change needed to resolve the issue
+   - Follow existing code patterns and conventions
+   - Ensure the fix does not break other functionality
+
+5. **Verify the Fix**
+   - Run build/lint commands to check for errors
+   - Fix any introduced issues before continuing
+   - Run relevant tests if available
+
+6. **Update and Commit**
+   - Mark the issue as fixed in the analysis document
+   - Create a commit with title starting with the issue ID
+   - Use `/git-commit` to create a properly formatted commit
+
+7. **End Session**
+   - Do NOT continue to the next issue
+   - Return session output for orchestrator to continue loop
+
+## Output Guidance
+
+When all qualifying issues are fixed or the document does not exist, output the completion signal:
+
+```json
+{
+  "ralph_complete": true,
+  "promise": "ANALYSIS_FIXES_COMPLETE",
+  "summary": "Brief description of what was done"
+}
+```
+
+When an issue was fixed this iteration:
+
+```json
+{
+  "issue_id": "BUG-001",
+  "status": "fixed",
+  "files_changed": ["src/example.ts"],
+  "commit": "abc123"
+}
+```
+
+When an issue cannot be fixed:
+
+```json
+{
+  "issue_id": "BUG-002",
+  "status": "skipped",
+  "reason": "Requires external dependency update"
+}
+```

package/src/claude/.claude/skills/git-branch/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: af-git-branch
+description: Create a git branch following naming convention
+argument-hint: [category] [name] [base]
+---
+
+# Git Branch
+
+## Overview
+
+Create and checkout a new git branch following the naming convention: `<category>/<issue-id>_<branch-name>` or `<category>/<branch-name>` when no issue ID is provided. Links to issue tracking when available.
+
+## Arguments
+
+### Definitions
+
+- **`[category]`** (optional): Branch type. Common values: poc, feature, fix, chore, doc, refactor. Accepts any value. Defaults to `feature`.
+- **`[name]`** (optional): Short kebab-case description of the work. Infer from context if not provided, default to `agentic/<random-id>`.
+- **`[base]`** (optional): Base branch to create from. If not provided, branch from current location.
+
+### Values
+
+\$ARGUMENTS
+
+## Core Principles
+
+- Use kebab-case for branch names (lowercase, hyphens)
+- Keep branch names concise but descriptive
+- Include issue ID when context provides one
+- Never prompt interactively - extract from context or use defaults
+- Accept any category value provided
+
+## Instructions
+
+1. Parse the provided arguments to extract category, name, and base (if present)
+2. If arguments are incomplete, infer from conversation context:
+   - Look for GitHub issue references (#123, issue 123)
+   - Derive branch name from the task description
+   - Default category to `feature` if not provided
+   - Default name to `agentic/<random-id>` if not provided
+3. Use the provided category or default to `feature`. Common categories: poc, feature, fix, chore, doc, refactor
+4. Determine base branch:
+   - If base is provided, checkout that branch first
+   - Otherwise branch from current location
+5. Construct the branch name:
+   - With issue: `<category>/<issue-id>_<name>`
+   - Without issue: `<category>/<name>`
+6. Execute: `git checkout -b <constructed-branch-name>` (from base if provided)
+7. Return JSON output with branch details
+
+## Output Guidance
+
+Return JSON with branch creation details:
+
+```json
+{
+  "success": true,
+  "branch": "{{branch}}",
+  "base": "{{base}}",
+  "category": "{{category}}",
+  "issue_id": "{{issue_id}}"
+}
+```
+
+<!--
+Placeholders:
+- {{branch}}: Full branch name created (e.g., feature/123_add-user-auth)
+- {{base}}: Base branch it was created from
+- {{category}}: Branch category used (feature, fix, chore, etc.)
+- {{issue_id}}: Issue ID if present, otherwise omit this field
+-->

package/src/claude/.claude/skills/git-commit/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: af-git-commit
+description: Create a git commit with structured message
+argument-hint: [message] [files...] [plan_step]
+---
+
+# Git Commit
+
+## Overview
+
+Create a well-structured commit with a concise title and optional bullet-point description. Commits staged changes with proper formatting and AI attribution.
+
+## Arguments
+
+### Definitions
+
+- **`[message]`** (optional): Override commit title. If not provided, auto-generate from changes.
+- **`[files...]`** (optional): Specific files to commit. Default: all staged.
+- **`[plan_step]`** (optional): Reference to plan step being completed.
+
+### Values
+
+\$ARGUMENTS
+
+## Core Principles
+
+- Title must be short (50 chars ideal, 120 max) and focus on the main task completed
+- Description is optional for small commits
+- Description uses 1-5 bullet points for larger commits highlighting important aspects
+- Always include AI attribution with your model name: `Co-Authored-By: Claude <model> <noreply@anthropic.com>`
+
+## Skill-Specific Guidelines
+
+### Plan Step Reference
+
+When following a plan (implementation plan, milestone plan, etc.), include the current step reference at the start of the commit title in brackets:
+
+- **Task-based plans**: `[Task N]` where N is the task number (e.g., `[Task 1]`, `[Task 8]`)
+- **Milestone-based plans**: `[Milestone N]` when committing after completing a milestone
+- **Nested plans**: `[Task M.N]` for tasks within milestones (e.g., `[Task 1.1]`, `[Task 2.3]`)
+
+Only include this prefix if you are actively following a plan with numbered steps. If no plan context exists, omit the brackets entirely.
+
+**Examples:**
+
+- `[Task 8] Update CLI with orchestrator integration`
+- `[Milestone 1] Complete authentication module`
+- `[Task 2.3] Add unit tests for validation logic`
+- `Add helper function for date parsing` (no plan context)
+
+## Instructions
+
+1. Run `git status` to verify there are changes to commit
+2. Run `git diff --staged` to analyze staged changes (if none, stage all with `git add .`)
+3. Analyze the changes to determine:
+   - Primary purpose of the changes (the "what")
+   - Impact and scope (small fix vs. larger feature)
+4. Determine plan step reference (if following a plan):
+   - Check if there is an active plan with numbered tasks or milestones
+   - Identify which task/milestone these changes correspond to
+   - Format the prefix accordingly (e.g., `[Task 3]`, `[Milestone 2]`, `[Task 1.2]`)
+5. Construct commit message:
+   - **Title**: `[Step Ref]` prefix (if applicable) + imperative mood, capitalize first letter, no period
+   - **Description**: Only if changes are substantial; 1-5 bullets on key aspects
+6. Execute commit using HEREDOC for proper formatting:
+
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   [Task N] <title>
+
+   - bullet 1 (optional)
+   - bullet 2 (optional)
+
+   Co-Authored-By: Claude <model> <noreply@anthropic.com>
+   EOF
+   )"
+   ```
+
+7. Return JSON output with commit details
+
+## Output Guidance
+
+Return JSON with commit details:
+
+```json
+{
+  "success": true,
+  "commit_hash": "{{commit_hash}}",
+  "message": "{{message}}",
+  "files_committed": ["{{files}}"],
+  "stats": {
+    "files_changed": "{{files_changed}}",
+    "insertions": "{{insertions}}",
+    "deletions": "{{deletions}}"
+  }
+}
+```
+
+<!--
+Placeholders:
+- {{commit_hash}}: Short commit hash (e.g., abc1234)
+- {{message}}: Commit title/message
+- {{files}}: Array of committed file paths
+- {{files_changed}}: Number of files changed
+- {{insertions}}: Lines added
+- {{deletions}}: Lines removed
+-->

package/src/claude/.claude/skills/git-pr/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: af-git-pr
+description: Create a pull request with contextual title and description
+argument-hint: [title] [body] [base] [--draft]
+---
+
+# Git PR
+
+## Overview
+
+Create a pull request using the GitHub CLI with a descriptive title and appropriately-sized description. The PR description is automatically scaled based on the scope and impact of the changes.
+
+## Arguments
+
+### Definitions
+
+- **`[title]`** (optional): PR title. Auto-generated if not provided.
+- **`[body]`** (optional): PR body/description. Auto-generated if not provided.
+- **`[base]`** (optional): Target branch for the PR. Defaults to main/master.
+- **`[--draft]`** (optional): Create as draft PR. Defaults to false.
+
+### Values
+
+\$ARGUMENTS
+
+## Core Principles
+
+- PR size dictates description length - small changes get small descriptions
+- Title should clearly convey the primary change
+- Description focuses on WHY and context, not WHAT (diff shows the what)
+- Use `gh pr create` for PR creation
+- Always include AI attribution at the end of the body
+
+## Instructions
+
+1. Verify current branch is not the base branch
+2. Push current branch to remote if needed
+3. Fetch the latest remote base branch: `git fetch origin <base>`
+4. Run `git log origin/<base>..HEAD --oneline` to get commits in this PR
+5. Run `git diff origin/<base>...HEAD --stat` to assess change scope
+6. Determine PR size category:
+   - **Trivial**: <10 lines, single file, style/typo fix
+   - **Small**: <50 lines, focused change
+   - **Medium**: 50-200 lines, feature or significant fix
+   - **Large**: >200 lines, major feature or refactor
+7. Construct PR content based on size:
+
+   **Trivial/Small**: Brief description with attribution
+
+   ```bash
+   gh pr create --title "Fix typo in README" --body "Corrects spelling error
+
+   🤖 Generated with [Claude Code](https://claude.com/product/claude-code)"
+   ```
+
+   **Medium/Large**: Structured description with attribution
+
+   ```bash
+   gh pr create --title "<title>" --body "## Summary
+   <1-2 sentence overview>
+
+   ## Details
+   - <Key change 1 with context>
+   - <Key change 2 with context>
+
+   🤖 Generated with [Claude Code](https://claude.com/product/claude-code)"
+   ```
+
+8. Execute `gh pr create` with constructed content
+9. Return JSON output with PR details
+
+## Output Guidance
+
+Return JSON with PR details:
+
+```json
+{
+  "success": true,
+  "pr_number": "{{pr_number}}",
+  "url": "{{url}}",
+  "title": "{{title}}",
+  "base": "{{base}}",
+  "head": "{{head}}",
+  "draft": "{{draft}}"
+}
+```
+
+<!--
+Placeholders:
+- {{pr_number}}: PR number assigned by GitHub
+- {{url}}: Full URL to the PR
+- {{title}}: PR title used
+- {{base}}: Target branch (e.g., main)
+- {{head}}: Source branch name
+- {{draft}}: Boolean indicating if created as draft
+-->

package/src/claude/.claude/skills/orchestrate/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: af-orchestrate
+description: Evaluate workflow state and determine next action
+---
+
+# Orchestrate
+
+## Overview
+
+You are the workflow orchestrator. Your job is to evaluate the current workflow state and determine what action should be taken next. You receive the workflow definition, current progress, and last step output, then return a JSON decision.
+
+## Core Principles
+
+- Check for completion first: if all steps are done, return `workflow_status: completed`
+- Check for failures: if a step failed and max retries reached, return `workflow_status: failed`
+- Check for blocking: if human input is required, return `workflow_status: blocked`
+- Handle errors gracefully: if last step failed but retries remain, return `retry_step`
+- Always provide clear reasoning for decisions
+
+## Skill-Specific Guidelines
+
+### Condition Evaluation
+
+For conditional steps, evaluate the Jinja2 condition using the available context:
+
+- `outputs.{step_name}` - Previous step outputs
+- `variables.{var_name}` - Workflow variables
+
+### Decision Examples
+
+**Execute Next Step:**
+
+```json
+{
+  "workflow_status": "in_progress",
+  "next_action": {
+    "type": "execute_step",
+    "step_name": "implement",
+    "context_to_pass": "Implement the feature based on the plan in step 'plan'"
+  },
+  "reasoning": "Plan step completed successfully, proceeding to implementation",
+  "progress_update": "Starting implementation phase"
+}
+```
+
+**Workflow Complete:**
+
+```json
+{
+  "workflow_status": "completed",
+  "next_action": {
+    "type": "complete"
+  },
+  "reasoning": "All steps completed successfully, PR created",
+  "progress_update": "Workflow completed successfully"
+}
+```
+
+**Retry Failed Step:**
+
+```json
+{
+  "workflow_status": "in_progress",
+  "next_action": {
+    "type": "retry_step",
+    "step_name": "review",
+    "error_context": "Test failures in auth.test.ts - fix the mock setup"
+  },
+  "reasoning": "Validation failed with test errors, 2 retries remaining",
+  "progress_update": "Retrying validation after fixing test issues"
+}
+```
+
+## Instructions
+
+1. **Receive Input**
+   - Workflow definition (YAML)
+   - Current progress document (JSON)
+   - Last step output (if any)
+
+2. **Analyze Workflow State**
+   - Check if all steps are completed
+   - Check for failed steps and retry counts
+   - Check for blocking conditions
+
+3. **Determine Next Action**
+   - Based on step dependencies and conditions
+   - Evaluate any Jinja2 conditions
+   - Identify the appropriate action type
+
+4. **Return JSON Decision**
+
+## Output Guidance
+
+Return ONLY a valid JSON object in this exact format:
+
+```json
+{
+  "workflow_status": "{{status}}",
+  "next_action": {
+    "type": "{{action_type}}",
+    "step_name": "{{step_name}}",
+    "context_to_pass": "{{context}}",
+    "error_context": "{{error_context}}"
+  },
+  "reasoning": "{{reasoning}}",
+  "progress_update": "{{progress_update}}"
+}
+```
+
+<!--
+Placeholders:
+- {{status}}: One of in_progress, completed, failed, blocked
+- {{action_type}}: One of execute_step, retry_step, wait_for_human, complete, abort
+- {{step_name}}: Name of step to execute (if applicable, omit otherwise)
+- {{context}}: Context string for the step (if applicable, omit otherwise)
+- {{error_context}}: Error details for retry (if retrying, omit otherwise)
+- {{reasoning}}: Brief explanation of why this decision was made
+- {{progress_update}}: What to record in progress document
+-->