agentic-forge 0.0.0

package/src/claude/.claude/skills/sdlc-review/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: af-sdlc-review
+description: Review implementation quality and plan compliance
+argument-hint: <workflow-id> [plan] [output_dir] [severity]
+---
+
+# SDLC Review
+
+## Overview
+
+Review the implementation against quality standards and optionally against a plan. When a plan is provided, the review verifies plan compliance. Creates a review.md file in the specified output directory. When no plan is provided, the review examines the diff compared to the remote main branch.
+
+## Arguments
+
+### Definitions
+
+- **`<workflow-id>`** (required): The workflow identifier for output organization.
+- **`[plan]`** (optional): Path to plan document. When provided, review checks plan compliance.
+- **`[output_dir]`** (optional): Directory to write review.md file (default to `agentic/outputs/<workflow-id>`).
+- **`[severity]`** (optional): Minimum severity to report. Values: `minor`, `major`, `critical`. Defaults to `minor`.
+
+### Values
+
+\$ARGUMENTS
+
+## Core Principles
+
+- Review all changes thoroughly before reporting
+- When no plan is provided, review the diff against `origin/main` (or `origin/master` as fallback)
+- When a plan is provided, verify all milestones and tasks are completed
+- Report issues with accurate severity levels
+- Tests, lint, types, and build must pass for a successful review
+- Always create a review.md file in the output directory
+
+## Instructions
+
+1. **Parse Arguments**
+   - Extract workflow-id, plan, output_dir, and severity from arguments
+   - Default output_dir to `agentic/outputs/<workflow-id>` if not specified
+   - Default severity to `minor` if not specified
+
+2. **Determine Review Scope**
+   - If plan is provided: Load and parse the plan document
+   - If no plan: Fetch latest remote main branch and get diff
+
+3. **Run Quality Checks**
+   - **Test Suite**: Run all tests, verify coverage
+   - **Linter**: Check for linting errors
+   - **Type Checker**: Verify type correctness
+   - **Build**: Ensure project builds successfully
+
+4. **Review Changes**
+   - If plan provided:
+     - Verify all milestones completed
+     - Verify all tasks marked done
+     - Check for scope creep (unplanned changes)
+   - If no plan:
+     - Review all changed files in the diff
+     - Check for code quality issues
+     - Identify potential bugs or regressions
+
+5. **Generate Review Output**
+   - Aggregate all check results
+   - Filter issues by severity threshold
+   - Generate summary
+
+6. **Write Outputs**
+   - Create `review.md` file in the output_dir
+   - Return JSON output
+
+## Output Guidance
+
+### JSON Output
+
+Return JSON with review details:
+
+```json
+{
+  "success": true,
+  "review_passed": {{review_passed}},
+  "checks": {
+    "plan_compliance": {
+      "passed": {{plan_compliance_passed}},
+      "milestones_complete": {{milestones_complete}},
+      "milestones_total": {{milestones_total}}
+    },
+    "tests": {
+      "passed": {{tests_passed}},
+      "total": {{tests_total}},
+      "passing": {{tests_passing}},
+      "failing": {{tests_failing}},
+      "coverage": {{coverage_percent}}
+    },
+    "lint": {
+      "passed": {{lint_passed}},
+      "errors": {{lint_errors}},
+      "warnings": {{lint_warnings}}
+    },
+    "types": {
+      "passed": {{types_passed}},
+      "errors": {{type_errors}}
+    },
+    "build": {
+      "passed": {{build_passed}}
+    }
+  },
+  "issues": [{{issues_array}}],
+  "summary": "{{summary}}",
+  "document_path": "{{document_path}}"
+}
+```
+
+<!--
+Placeholders:
+- {{review_passed}}: Boolean indicating if review passed (true/false)
+- {{plan_compliance_passed}}: Boolean for plan compliance check (true/false/null if no plan)
+- {{milestones_complete}}, {{milestones_total}}: Integer counts for plan compliance (null if no plan)
+- {{tests_passed}}: Boolean for tests passing (true/false)
+- {{tests_total}}, {{tests_passing}}, {{tests_failing}}: Integer counts for test results
+- {{coverage_percent}}: Code coverage percentage (e.g., 82.5)
+- {{lint_passed}}: Boolean for lint check passing (true/false)
+- {{lint_errors}}, {{lint_warnings}}: Integer counts for lint results
+- {{types_passed}}: Boolean for type check passing (true/false)
+- {{type_errors}}: Integer count for type check errors
+- {{build_passed}}: Boolean for build passing (true/false)
+- {{issues_array}}: Array of issue objects with severity, category, message, file, line
+- {{summary}}: Human-readable summary of review results
+- {{document_path}}: Path to generated review.md file
+-->
+
+### Issue Schema
+
+```json
+{
+  "severity": "{{severity}}",
+  "category": "{{category}}",
+  "message": "{{message}}",
+  "file": "{{file}}",
+  "line": {{line}}
+}
+```
+
+<!--
+Placeholders:
+- {{severity}}: One of minor, major, critical
+- {{category}}: Check category (tests, lint, types, build, plan_compliance, code_quality)
+- {{message}}: Description of the issue
+- {{file}}: Path to the affected file (null if not applicable)
+- {{line}}: Line number where issue occurs (null if not applicable)
+-->
+
+### Review Document
+
+Create a `review.md` file in the output_dir with the following format:
+
+```markdown
+# Review
+
+**Status**: {{review_status}}
+**Date**: {{review_date}}
+
+## Progress
+
+- [ ] All issues resolved
+- [ ] Tests passing
+- [ ] Lint passing
+- [ ] Types passing
+- [ ] Build passing
+
+## Summary
+
+{{summary}}
+
+## Checks
+
+| Check           | Status                     | Details                                                                    |
+| --------------- | -------------------------- | -------------------------------------------------------------------------- |
+| Plan Compliance | {{plan_compliance_status}} | {{milestones_complete}}/{{milestones_total}} milestones                    |
+| Tests           | {{tests_status}}           | {{tests_passing}}/{{tests_total}} passing ({{coverage_percent}}% coverage) |
+| Lint            | {{lint_status}}            | {{lint_errors}} errors, {{lint_warnings}} warnings                         |
+| Types           | {{types_status}}           | {{type_errors}} errors                                                     |
+| Build           | {{build_status}}           | {{build_details}}                                                          |
+
+## Issues
+
+{{#if issues_exist}}
+| Severity | Category | File | Line | Message |
+|----------|----------|------|------|---------|
+{{#each issues}}
+| {{severity}} | {{category}} | {{file}} | {{line}} | {{message}} |
+{{/each}}
+{{else}}
+No issues found.
+{{/if}}
+```
+
+<!--
+Placeholders:
+- {{review_status}}: PASSED or FAILED
+- {{review_date}}: ISO 8601 date (YYYY-MM-DD)
+- {{summary}}: Human-readable summary of review results
+- {{plan_compliance_status}}: Checkmark or X emoji based on passed status
+- {{milestones_complete}}, {{milestones_total}}: Integer counts
+- {{tests_status}}: Checkmark or X emoji based on passed status
+- {{tests_passing}}, {{tests_total}}: Integer counts
+- {{coverage_percent}}: Code coverage percentage
+- {{lint_status}}: Checkmark or X emoji based on passed status
+- {{lint_errors}}, {{lint_warnings}}: Integer counts
+- {{types_status}}: Checkmark or X emoji based on passed status
+- {{type_errors}}: Integer count
+- {{build_status}}: Checkmark or X emoji based on passed status
+- {{build_details}}: Brief description of build result
+- {{issues_exist}}: Boolean indicating if there are issues to display
+- {{issues}}: Array of issue objects (severity, category, file, line, message)
+-->

package/src/claude/.claude/skills/workflow-builder/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: af-workflow-builder
+description: Create, update, explain, validate, and debug agentic-forge YAML workflows with comprehensive schema knowledge
+argument-hint: <request>
+disable-model-invocation: true
+---
+
+# Workflow Builder
+
+## Overview
+
+Create, update, explain, validate, and debug agentic-forge YAML workflows. This skill has comprehensive knowledge of every workflow property, step type, setting, and pattern. Use it when you need to author new workflows, modify existing ones, understand workflow features, check YAML correctness, or troubleshoot execution issues.
+
+## Arguments
+
+### Definitions
+
+- **`<request>`** (required): Free-form description of what you want. Examples: "create a workflow that plans and reviews a feature", "update my-workflow.yaml to add a parallel step", "explain how ralph-loop works", "validate my-workflow.yaml", "debug why my conditional always takes the else branch"
+
+### Values
+
+\$ARGUMENTS
+
+## Additional Resources
+
+- For the complete annotated workflow example, see [workflow-example.yaml](references/workflow-example.yaml)
+- For the complete schema reference with all properties, types, and defaults, see [REFERENCE.md](references/REFERENCE.md)
+
+## Core Principles
+
+- Always produce valid YAML that conforms to the workflow schema
+- Use kebab-case for all YAML keys (e.g., `timeout-minutes`, `max-retry`, `on-error`)
+- Use kebab-case for step names and workflow names (e.g., `analyze-codebase`, `implement-feature`)
+- Use snake_case for variable names (e.g., `max_iterations`, `fix_severity`)
+- Use skill names without prefix in prompt steps (e.g., `/sdlc-plan`)
+- Keep workflows focused: prefer composing simple workflows over one massive workflow
+- Every workflow requires `name`, `version: "1.0"`, and at least one step
+- Include descriptions on the workflow and variables for documentation
+- When updating workflows, read the existing file first and preserve structure
+- When validating, check: required fields, valid step types, valid setting values, variable type consistency, no nested parallel steps
+- When debugging, look for: undefined template variables, incorrect condition expressions, missing completion-promise in ralph loops, timeout issues
+
+## Skill-Specific Guidelines
+
+### Operation Modes
+
+**Create** - Generate a complete workflow YAML from a description:
+
+1. Ask clarifying questions if the request is ambiguous
+2. Choose appropriate step types for the task
+3. Define variables for configurable values
+4. Set reasonable defaults for settings and timeouts
+5. Write the YAML file to the requested location (default: project root or `agentic/workflows/`)
+
+**Update** - Modify an existing workflow YAML:
+
+1. Read the existing workflow file
+2. Understand the current structure
+3. Apply the requested changes
+4. Preserve comments and formatting where possible
+
+**Explain** - Answer questions about workflow features:
+
+1. Reference the schema to provide accurate information
+2. Include examples from the reference workflow
+3. Explain defaults and valid values
+
+**Validate** - Check a workflow YAML for correctness:
+
+1. Read the workflow file
+2. Check against the schema (required fields, valid types, valid values)
+3. Report issues with specific field references
+4. Suggest fixes for each issue found
+
+**Debug** - Help troubleshoot workflow execution issues:
+
+1. Read the workflow YAML and any error output
+2. Check for common issues (undefined variables, incorrect conditions, missing fields)
+3. Check `agentic/outputs/<workflow-id>/progress.json` if available
+4. Suggest specific fixes
+
+### Step Type Selection Guide
+
+| Step Type        | Use When                                           |
+| ---------------- | -------------------------------------------------- |
+| `prompt`         | Single task, skill invocation, or simple operation |
+| `serial`         | Multiple tasks that must run in sequence           |
+| `parallel`       | Independent tasks that can run concurrently        |
+| `conditional`    | Branching logic based on variables or outputs      |
+| `ralph-loop`     | Iterative work with unknown iteration count        |
+| `wait-for-human` | Pause for human review, approval, or input         |
+
+### Model Selection Strategy
+
+| Model    | Best For                                            |
+| -------- | --------------------------------------------------- |
+| `haiku`  | Quick tasks: validation, formatting, small analysis |
+| `sonnet` | Default: implementation, review, planning           |
+| `opus`   | Complex reasoning: architecture, large refactors    |
+
+Priority: step `model` > `settings.model` > config default > `sonnet`
+
+### Common Patterns
+
+**Plan-Build-Review**: plan (prompt) -> implement (ralph-loop) -> review (prompt) -> conditional fix -> conditional PR
+
+**Parallel Analysis**: parallel step with multiple analyze prompts, each with `on-error: skip`
+
+**Iterative Implementation**: ralph-loop with completion-promise, reading a plan file each iteration
+
+**Gated Deployment**: implement -> review -> wait-for-human approval -> conditional deploy
+
+### Common Debugging Issues
+
+| Symptom                                | Likely Cause                                   | Fix                                                              |
+| -------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------- |
+| "Missing required variable"            | Variable not passed via `--var`                | Add `--var "name=value"` to CLI or set `default`                 |
+| Conditional always takes else          | Condition expression evaluates to falsy        | Check Jinja2 expression syntax and variable names                |
+| Ralph loop never completes             | Completion JSON not output or promise mismatch | Verify `completion-promise` matches the `promise` field in JSON  |
+| Template variable shows as `{{ ... }}` | Undefined variable in lenient mode             | Define the variable or enable `strict-mode: true` to catch early |
+| Step timeout                           | Task exceeds `timeout-minutes`                 | Increase step or workflow `timeout-minutes`                      |
+| "Nested parallel steps not allowed"    | Parallel step inside another parallel          | Flatten structure or use serial inside parallel                  |
+
+## Instructions
+
+1. **Identify the operation** from the user's request (create, update, explain, validate, or debug)
+2. **Load reference material**: Read [REFERENCE.md](references/REFERENCE.md) for schema details and [workflow-example.yaml](references/workflow-example.yaml) for patterns
+3. **For create operations**:
+   a. Determine which step types are needed
+   b. Identify what variables should be configurable
+   c. Choose appropriate settings (git, timeouts, model)
+   d. Generate the complete YAML with comments explaining key sections
+   e. Write the file to the appropriate location
+4. **For update operations**:
+   a. Read the existing workflow YAML file
+   b. Understand the current structure and intent
+   c. Apply the requested modifications
+   d. Validate the result is still correct
+5. **For explain operations**:
+   a. Reference the schema to provide accurate, complete answers
+   b. Include relevant examples
+   c. Mention defaults, valid values, and edge cases
+6. **For validate operations**:
+   a. Read the workflow YAML file
+   b. Check all required fields are present
+   c. Verify step types have their required properties
+   d. Check variable references in templates exist in the variables section
+   e. Report all issues found with suggestions
+7. **For debug operations**:
+   a. Read the workflow YAML and any error output or progress files
+   b. Identify the root cause of the issue
+   c. Provide a specific fix with updated YAML
+
+## Output Guidance
+
+After completing the operation, output a JSON object:
+
+```json
+{
+  "status": "completed",
+  "operation": "create | update | explain | validate | debug",
+  "workflow": {
+    "name": "workflow-name",
+    "path": "path/to/workflow.yaml"
+  },
+  "summary": "Brief description of what was done",
+  "issues": [],
+  "suggestions": []
+}
+```
+
+For validate operations, populate `issues`:
+
+```json
+{
+  "issues": [
+    {
+      "severity": "error | warning",
+      "field": "steps[0].type",
+      "message": "Invalid step type: 'loop'",
+      "suggestion": "Use 'ralph-loop' instead"
+    }
+  ]
+}
+```