agentic-forge 0.0.0

package/.gitattributes

@@ -0,0 +1,24 @@
+# Enforce LF line endings for all text files
+* text=auto eol=lf
+
+# Explicitly set common file types
+*.md text eol=lf
+*.txt text eol=lf
+*.json text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.toml text eol=lf
+*.sh text eol=lf
+*.js text eol=lf
+*.ts text eol=lf
+*.html text eol=lf
+*.css text eol=lf
+*.xml text eol=lf
+
+# Keep binary files as-is
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary

package/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-format:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint and format check
+        run: pnpm check
+
+  test:
+    name: Tests (Node ${{ matrix.node-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node-version: ["20", "22"]
+      fail-fast: false
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run tests with coverage
+        run: pnpm test -- --coverage

package/.markdownlint-cli2.jsonc

@@ -0,0 +1,16 @@
+{
+  "config": {
+    "default": true,
+    "MD013": false, // Line length
+    "MD024": {
+      "siblings_only": true // Multiple headings with the same content
+    },
+    "MD025": {
+      "front_matter_title": "" // Don't treat frontmatter title as an h1
+    },
+    "MD033": false, // Inline HTML (used in README badges/layout)
+    "MD041": false // First line heading (not applicable to all .md files)
+  },
+  "globs": ["**/*.md"],
+  "ignores": ["agentic", "**/node_modules", ".git", "dist", "build"]
+}

package/.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+pnpm-lock.yaml
+.git

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "proseWrap": "preserve",
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "none"
+}

package/.vscode/agentic-forge.code-workspace

@@ -0,0 +1,26 @@
+{
+  "folders": [
+    {
+      "path": ".."
+    }
+  ],
+  "settings": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.wordWrap": "on",
+    "files.exclude": {
+      "**/.git": true
+    },
+    "search.exclude": {
+      "**/.git": true
+    },
+    "markdownlint.run": "onSave",
+    "prettier.resolveGlobalModules": false
+  },
+  "extensions": {
+    "recommendations": [
+      "esbenp.prettier-vscode",
+      "davidanson.vscode-markdownlint"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## 0.7.0 - 2026-04-04
+
+- **Breaking:** Full rewrite from Python to TypeScript/Node.js
+- **Breaking:** Renamed package from `agentic-sdlc` to `agentic-forge` (CLI command also renamed)
+- **Breaking:** Removed Claude Code marketplace dependency; skills now loaded via `--add-dir`
+- **Breaking:** Replaced Jinja2 templates with Nunjucks for template rendering
+- **Breaking:** Distribution changed from PyPI (`uv tool install`) to npm (`npm i -g agentic-forge`)
+- Ported all 14 CLI command handlers to TypeScript with Commander.js
+- Ported workflow executor, orchestrator, and checkpoint manager to TypeScript
+- Ported all step executors (prompt, serial, parallel, conditional, ralph-loop) with shared base class
+- Ported runner module with Claude CLI subprocess management and stream-JSON parsing
+- Ported progress tracking, signal management, and workflow logger
+- Ported parallel step executor with git worktree management
+- Added `skills-dir` command to print bundled skills path for `--add-dir` integration
+- Skills, agents, and prompts bundled as npm package data
+- Repository restructured: flat layout at root instead of `plugins/agentic-sdlc/`
+- Added Biome for TypeScript/JSON linting and formatting
+- Added markdownlint-cli2 for Markdown linting
+- Added Vitest test suite
+- CI updated from Python (pytest, uv) to Node.js (pnpm, vitest, biome)
+- Fixed wait-for-human progress state and parallel concurrency cap
+- Fixed 5 major correctness issues from code review
+
+## 0.6.0 - 2026-02-15
+
+- Added `workflow-builder` skill for creating, updating, explaining, validating, and debugging workflows
+- Added parallel branch display in terminal with multi-branch status updates (BASE mode)
+- Added queue-based message streaming for parallel steps (ALL mode)
+- Added stream-JSON parsing for real-time Claude output processing
+- Added model name detection and display in step headers (e.g., `sonnet-4.5`)
+- Added `strict-mode` setting for failing on undefined template variables
+- Added config file copy during `init` command
+- Added comprehensive test coverage for console, runner, init, parser, and step modules
+- Rewrote console output module with `ParallelOutputHandler` for parallel execution display
+- Increased default `max_iterations` from 5-10 to 25 across all workflows
+- Changed `create_pr` default to `false` across all workflows
+- Changed `bypass-permissions` default to `false` in ralph-loop workflow
+- Set `terminal-output: base` as explicit default in plan-build-review and ralph-loop workflows
+- Consolidated workflow documentation from `docs/` into `workflow-builder` skill references
+- Fixed workflow resume losing state on re-run
+- Fixed fix-issues step in plan-build-review reading wrong file for review output
+- Fixed JSON template placeholders in fix-issues step replaced with proper syntax
+
+## 0.5.0 - 2026-01-25
+
+- Converted all CLI commands to skills for consistency and reusability
+- Added `create-skill` skill for generating new skills from templates
+- Renamed `validate` command to `sdlc-review` skill
+- Prefixed plan and review skills with `sdlc-` to avoid naming conflicts with Claude Code built-ins
+- Added workflow-id argument support across skills
+- Fixed step output and reference handling between workflow steps
+- Fixed full skill name usage in workflows to avoid command conflicts
+
+## 0.4.0 - 2026-01-25
+
+- Added `fix-analysis` skill for iteratively fixing issues from analysis documents
+- Added `workflows` CLI command to list available workflows with descriptions
+- Removed `/build`, `one-shot`, and `analyze` CLI commands in favor of workflow-based execution
+- Refactored analyze workflows to use the new `fix-analysis` skill
+- Removed experimental-plugins directory
+- Fixed `git-pr` command to fetch and compare against remote base branch to avoid stale local branch issues
+
+## 0.3.0 - 2026-01-24
+
+- Standardized US English spelling across all code, commands, and documentation (e.g., `analyse` to `analyze`)
+- Renamed workflow files from `analyse-*.yaml` to `analyze-*.yaml` and `demo-workflow.yaml` to `demo.yaml`
+- Removed interactive-sdlc plugin
+
+## 0.2.0 - 2026-01-21
+
+- Added `version` command to display installed version
+- Added `release-notes` command to display release notes from CHANGELOG.md
+- Added `update` command for self-updating from local marketplace
+- Added `add-improvement` command for tracking improvement suggestions
+- Added workflow auto-discovery with search order: project-local, user-global, bundled
+- Added `--list` flag for `run` command to list all available workflows
+- Added demo workflow for showcasing capabilities
+- Fixed `list` command to correctly find workflow progress files in `agentic/outputs/`
+- Fixed workflow logging to capture agent messages in both base and terminal-output modes
+- Fixed ralph-loop first iteration template evaluation
+- Fixed plan output when used in workflow context
+- Fixed plan-build-validate build step failures and ralph failure handling
+
+## 0.1.0 - 2026-01-20
+
+- Initial release of agentic-sdlc
+- YAML-based workflow orchestration with sequential, parallel, and Ralph loop step types
+- Checkpoint manager for session state tracking
+- Python CLI for workflow management (`run`, `init`)
+- Core commands: plan, build, validate, analyze, orchestrate
+- Git commands: git-branch, git-commit, git-pr
+- Explorer and reviewer agents for specialized tasks
+- Jinja2 templates for plans, reports, and analysis outputs
+- Git worktree support for parallel step execution
+- Console output module for workflow progress display
+- Plugin discovery and download system with marketplace structure
+- Claude GitHub Actions for CI
+- NuGet vulnerability detection and security analysis commands

package/CLAUDE.md

@@ -0,0 +1,158 @@
+# 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

@@ -0,0 +1,152 @@
+# 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Étienne St-Pierre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.