agentic-forge 0.0.0

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

@@ -0,0 +1,163 @@
+---
+name: af-sdlc-plan
+description: Create an implementation plan for a task
+argument-hint: <workflow-id> [type] [output_dir] [explore_agents] <context>
+---
+
+# SDLC Plan
+
+## Overview
+
+Create a structured implementation plan for the given task. This skill analyzes the codebase, identifies relevant files and patterns, and produces a detailed plan with milestones and actionable tasks. Supports different plan types (feature, bug, chore) with type-specific guidance.
+
+## Arguments
+
+### Definitions
+
+- **`<workflow-id>`** (required): The workflow identifier for output organization.
+- **`[type]`** (optional): Plan type. Values: `feature`, `bug`, `chore`, `auto`. Defaults to `auto`.
+- **`[output_dir]`** (optional): Directory to write plan.md file (default to `agentic/outputs/<workflow-id>`).
+- **`[explore_agents]`** (optional): Number of explore agents for codebase analysis. Defaults to `0`.
+- **`<context>`** (required): Task description or issue reference.
+
+### Values
+
+\$ARGUMENTS
+
+## Additional Resources
+
+Load ONE of these based on the `[type]` argument (or detected type if auto):
+
+- For feature plans, see [references/feature.md](references/feature.md)
+- For bug fix plans, see [references/bug.md](references/bug.md)
+- For chore plans, see [references/chore.md](references/chore.md)
+
+## Core Principles
+
+### Plan Structure
+
+- **Every plan must use Milestones and Tasks** - This applies to all plan types (feature, bug, chore). Having a single milestone is valid for smaller work items.
+- Tasks should be specific enough to execute without ambiguity
+- Include file paths with line numbers where changes are needed
+- Consider testing requirements in each milestone
+- Flag any unclear requirements or assumptions
+- Plans are static documentation - never modified during implementation
+- Always include a Progress section as the first `##` header with two subsections: Implementation (milestones/tasks) and Validation (verification and tests)
+
+### Milestone Design
+
+- Each milestone should deliver visible progress
+- Milestones should be testable independently
+- Order milestones by dependency (foundational work first)
+
+### Milestone Scoping (Critical)
+
+- **Each milestone must be scoped to a single Claude session** - If a milestone is too large for one session, split it into multiple milestones.
+- **Milestones are executed in fresh sessions** - When building the plan, assume each milestone will be executed in a new session that only has access to the plan document. All necessary context must be included in the plan itself.
+- **Every milestone must produce a concrete output** - Examples: generate code, update documentation, update plan, create tests. A milestone should never be purely research without output, because subsequent sessions cannot access that research.
+- **Research milestones require documented outputs** - If research is needed, the milestone must output its findings (e.g., "Research X and update Milestone 2 checklist with findings"). However, this pattern is discouraged. Prefer milestones that produce direct project artifacts.
+- **Ideal milestones are scoped units of work** - Each milestone should generate output in the current project that represents tangible progression toward the plan's goal.
+
+### Milestone & Task Template
+
+All plans must use this common structure for Progress and Milestones sections:
+
+```markdown
+## Progress
+
+### Implementation
+
+- [ ] Milestone 1: {{milestone_title}}
+  - [ ] Task 1.1: {{task_title}}
+  - [ ] Task 1.2: {{task_title}}
+- [ ] Milestone 2: {{milestone_title}}
+  - [ ] Task 2.1: {{task_title}}
+
+### Validation
+
+- [ ] {{validation_item}}
+
+## Milestones
+
+### Milestone {{milestone_number}}: {{milestone_title}}
+
+{{milestone_description}}
+
+#### Task {{milestone_number}}.{{task_number}}: {{task_title}}
+
+{{task_description}}
+```
+
+<!--
+Common placeholders (used by all plan types):
+- {{milestone_number}}: Sequential number (1, 2, 3, ...)
+- {{milestone_title}}: What this milestone accomplishes
+- {{milestone_description}}: Brief description of the milestone
+- {{task_number}}: Task number within milestone (1, 2, 3, ...)
+- {{task_title}}: Clear, actionable task title
+- {{task_description}}: Specific task details with acceptance criteria
+- {{validation_item}}: Validation criterion or test item
+-->
+
+## Instructions
+
+1. **Parse Arguments**
+   - Extract workflow-id, type, output_dir, explore_agents, and context from arguments
+   - Default type to `auto` if not specified
+   - Default explore_agents to `0` if not specified
+
+2. **Detect Plan Type** (if type=auto)
+   - Analyze the context to determine type:
+     - **feature**: New functionality, enhancements, additions
+     - **bug**: Error fixes, unexpected behavior corrections, defects
+     - **chore**: Refactoring, dependency updates, maintenance, cleanup
+   - Once detected, proceed with that type
+
+3. **Load Type-Specific Guidelines**
+   Based on the detected or specified type, load the corresponding reference file:
+   - `feature` -> Read [references/feature.md](references/feature.md)
+   - `bug` -> Read [references/bug.md](references/bug.md)
+   - `chore` -> Read [references/chore.md](references/chore.md)
+
+4. **Analyze Codebase**
+   - If `explore_agents` is 0: Perform a quick codebase exploration in the main session using Glob, Grep, and Read tools
+   - If `explore_agents` is 1+: Launch that many explorer agents (Task tool with subagent_type=Explore) for in-depth parallel analysis
+   - Identify files and components relevant to the task
+   - Understand existing patterns and conventions
+   - Map dependencies and impact areas
+
+5. **Generate Plan**
+   - Apply type-specific planning approach from the loaded reference
+   - Create discrete, independent milestones
+   - Include specific file paths and line numbers
+   - Estimate complexity (low, medium, high)
+
+6. **Write Output**
+   - Write plan document as .md format to the output_dir.
+   - Return JSON summary
+
+## Output Guidance
+
+Return JSON with metadata only. The full plan content is saved to the markdown file.
+
+```json
+{
+  "success": true,
+  "plan_type": "{{type}}",
+  "summary": "{{summary}}",
+  "milestone_count": "{{milestone_count}}",
+  "task_count": "{{task_count}}",
+  "complexity": "{{complexity}}",
+  "document_path": "{{document_path}}"
+}
+```
+
+<!--
+Placeholders:
+- {{type}}: Plan type (feature, bug, chore)
+- {{summary}}: Brief one-line summary of the plan
+- {{milestone_count}}: Total number of milestones
+- {{task_count}}: Total number of tasks across all milestones
+- {{complexity}}: Overall complexity (low, medium, high)
+- {{document_path}}: Path to generated plan.md file
+-->

package/src/claude/.claude/skills/sdlc-plan/references/bug.md

@@ -0,0 +1,115 @@
+# Bug Fix Plan Reference
+
+## Planning Approach
+
+Bug fix plans focus on thorough root cause analysis and prevention of regression. Understanding the cause is critical to implementing an effective fix.
+
+## Key Sections
+
+A bug fix plan should include:
+
+1. **Description**: Clear explanation of the bug and its impact
+2. **Reproduction Steps**: Step-by-step instructions to reproduce the bug
+3. **Root Cause Analysis**: Technical explanation of why the bug occurs
+4. **Fix Strategy**: High-level approach to fixing the bug
+5. **Tasks**: Specific implementation tasks
+6. **Validation**: Steps to verify the fix works
+7. **Testing**: Test cases to prevent regression
+
+## Investigation Focus
+
+When analyzing a bug:
+
+- Trace the execution path that leads to the bug
+- Identify the specific conditions that trigger it
+- Look for related code paths that may have similar issues
+- Check if there are existing tests that should have caught this
+- Understand the impact scope (which users/features are affected)
+
+## Root Cause Categories
+
+Common root causes to investigate:
+
+- **Logic Errors**: Incorrect conditions, off-by-one errors, wrong operators
+- **State Management**: Race conditions, stale data, incorrect state transitions
+- **Error Handling**: Unhandled exceptions, silent failures, missing edge cases
+- **Integration Issues**: API contract violations, data format mismatches
+- **Configuration**: Environment-specific issues, missing settings
+- **Resource Management**: Memory leaks, connection exhaustion, deadlocks
+
+## Fix Strategy Guidelines
+
+- Address the root cause, not just symptoms
+- Consider defensive measures to prevent similar bugs
+- Avoid fixes that introduce new complexity
+- Prefer targeted changes over broad refactoring
+- Include test coverage for the specific failure case
+
+## Milestone Patterns
+
+Typically 1-3 milestones per bug fix. Common patterns:
+
+1. **Investigation & Setup**: Reproduce bug, identify root cause, document findings
+2. **Implementation**: Apply fix, handle edge cases
+3. **Validation & Testing**: Verify fix, add regression tests
+
+## Template
+
+```markdown
+# Bug Fix: {{bug_title}}
+
+## Progress
+
+### Implementation
+
+{{implementation_checklist}}
+
+### Validation
+
+{{validation_checklist}}
+
+## Description
+
+{{description}}
+
+## Reproduction Steps
+
+{{reproduction_steps}}
+
+## Root Cause Analysis
+
+{{root_cause}}
+
+## Fix Strategy
+
+{{fix_strategy}}
+
+## Milestones
+
+### Milestone {{milestone_number}}: {{milestone_title}}
+
+{{milestone_description}}
+
+#### Task {{milestone_number}}.{{task_number}}: {{task_title}}
+
+{{task_description}}
+
+## Validation
+
+{{validation}}
+
+## Testing
+
+{{testing}}
+```
+
+<!--
+Type-specific placeholders (see SKILL.md for common milestone/task placeholders):
+- {{bug_title}}: Concise title for the bug (e.g., "Login Timeout on Safari OAuth Redirect")
+- {{description}}: Clear explanation of the bug and its impact
+- {{reproduction_steps}}: Numbered steps to reproduce the bug
+- {{root_cause}}: Technical explanation with code references
+- {{fix_strategy}}: High-level approach to fixing the bug
+- {{validation}}: Steps to verify the bug is fixed
+- {{testing}}: Test cases to add to prevent regression
+-->

package/src/claude/.claude/skills/sdlc-plan/references/chore.md

@@ -0,0 +1,105 @@
+# Chore Plan Reference
+
+## Planning Approach
+
+Chore plans focus on maintenance tasks that improve code quality, update dependencies, or perform housekeeping without adding new functionality. The goal is clear scope definition and methodical execution.
+
+## Key Sections
+
+A chore plan should include:
+
+1. **Description**: What needs to be done and why
+2. **Scope**: What is in scope and explicitly out of scope
+3. **Tasks**: Specific implementation tasks in execution order
+4. **Validation Criteria**: How to verify the chore is complete
+
+## Common Chore Types
+
+- **Dependency Updates**: Upgrading packages, handling breaking changes
+- **Refactoring**: Improving code structure without changing behavior
+- **Configuration**: Updating build configs, CI/CD pipelines, tooling
+- **Cleanup**: Removing dead code, fixing warnings, organizing files
+- **Documentation**: Updating outdated docs, adding missing docs
+- **Migration**: Moving to new patterns, APIs, or technologies
+
+## Scope Definition
+
+Clear scope prevents scope creep:
+
+- List specific files, directories, or components in scope
+- Explicitly state what is NOT in scope
+- Define boundaries for the change
+- Note any related work that should be done separately
+
+## Task Ordering
+
+Order tasks for safe, incremental progress:
+
+1. Preparation tasks (backups, feature flags, etc.)
+2. Core changes in dependency order
+3. Cleanup and verification tasks
+4. Documentation updates
+
+## Risk Mitigation
+
+For chores that could break things:
+
+- Identify rollback strategies
+- Plan for incremental changes that can be tested
+- Note any feature flags or gradual rollout needs
+- Consider timing (avoid high-traffic periods)
+
+## Milestone Patterns
+
+Typically 1-2 milestones per chore. Common patterns:
+
+1. **Implementation**: Execute the main tasks
+2. **Verification**: Validate changes, update docs (if needed)
+
+For larger chores, break into logical phases based on scope boundaries.
+
+## Template
+
+```markdown
+# Chore: {{chore_title}}
+
+## Progress
+
+### Implementation
+
+{{implementation_checklist}}
+
+### Validation
+
+{{validation_checklist}}
+
+## Description
+
+{{description}}
+
+## Scope
+
+{{scope}}
+
+## Milestones
+
+### Milestone {{milestone_number}}: {{milestone_title}}
+
+{{milestone_description}}
+
+#### Task {{milestone_number}}.{{task_number}}: {{task_title}}
+
+{{task_description}}
+
+## Validation Criteria
+
+{{validation_criteria}}
+```
+
+<!--
+Type-specific placeholders (see SKILL.md for common milestone/task placeholders):
+- {{chore_title}}: Concise title for the chore (e.g., "Update All Dependencies")
+- {{description}}: Brief explanation of what needs to be done and why
+- {{scope}}: What is in scope and out of scope (use bullet points)
+- {{validation_criteria}}: Checklist to verify completion
+-->

package/src/claude/.claude/skills/sdlc-plan/references/feature.md

@@ -0,0 +1,130 @@
+# Feature Plan Reference
+
+## Planning Approach
+
+Feature plans focus on comprehensive design with incremental delivery. Each milestone should be independently valuable and testable. Architecture decisions should align with existing codebase patterns.
+
+## Key Sections
+
+A feature plan should include:
+
+1. **Overview**: What the feature does and why it's valuable
+2. **Requirements**: Functional and non-functional requirements
+3. **Architecture**: High-level design and patterns to use
+4. **Milestones**: Logical breakdown with tasks
+5. **Testing Strategy**: How the feature will be tested
+6. **Validation Criteria**: How to verify the feature is complete
+
+## Requirements Gathering
+
+Capture both types of requirements:
+
+**Functional Requirements**:
+
+- What the feature should do
+- User interactions and flows
+- Input/output specifications
+- Edge cases and error handling
+
+**Non-Functional Requirements**:
+
+- Performance expectations
+- Security considerations
+- Scalability needs
+- Accessibility requirements
+- Compatibility constraints
+
+## Architecture Considerations
+
+When designing the feature:
+
+- Study existing patterns in the codebase
+- Identify integration points with existing code
+- Define data models and API contracts
+- Consider component reusability
+- Plan for extensibility without over-engineering
+- Document key technical decisions
+
+## Milestone Patterns
+
+Typically 2-5 milestones per feature. Common patterns:
+
+1. Core infrastructure/data models
+2. Basic functionality (happy path)
+3. Edge cases and error handling
+4. Polish and optimization
+5. Documentation and cleanup
+
+## Task Decomposition
+
+Within each milestone:
+
+- Tasks should be specific and actionable
+- Include file paths where changes are needed
+- Consider testing tasks alongside implementation
+- Note any dependencies between tasks
+
+## Testing Strategy
+
+Plan testing at multiple levels:
+
+- **Unit Tests**: Individual functions and components
+- **Integration Tests**: Component interactions
+- **E2E Tests**: Full user flows
+- **Manual Testing**: Exploratory and edge cases
+
+## Template
+
+```markdown
+# Feature: {{feature_title}}
+
+## Progress
+
+### Implementation
+
+{{implementation_checklist}}
+
+### Validation
+
+{{validation_checklist}}
+
+## Overview
+
+{{overview}}
+
+## Requirements
+
+{{requirements}}
+
+## Architecture
+
+{{architecture}}
+
+## Milestones
+
+### Milestone {{milestone_number}}: {{milestone_title}}
+
+{{milestone_description}}
+
+#### Task {{milestone_number}}.{{task_number}}: {{task_title}}
+
+{{task_description}}
+
+## Testing Strategy
+
+{{testing_strategy}}
+
+## Validation Criteria
+
+{{validation_criteria}}
+```
+
+<!--
+Type-specific placeholders (see SKILL.md for common milestone/task placeholders):
+- {{feature_title}}: Concise title for the feature (e.g., "User Authentication with OAuth")
+- {{overview}}: What this feature does and why it's valuable (2-4 sentences)
+- {{requirements}}: Functional and non-functional requirements (use subsections)
+- {{architecture}}: High-level design decisions and patterns
+- {{testing_strategy}}: How the feature will be tested at each level
+- {{validation_criteria}}: Checklist to verify feature completion
+-->