@thecfguy/flowforge-cli

CLI for FlowForge — initialize any project with plug-and-play SDLC agent orchestration in one command.

FlowForge is a pipeline shell: it owns phase sequencing, gate checks, retries, and progress tracking — while delegating each phase's execution instructions to the project's own agents or skills. Projects are never required to restructure their existing setup.

Installation

npm install -g @thecfguy/flowforge-cli

Commands

flowforge init [directory]

Bootstrap a project with FlowForge. Run this once inside any codebase.

# Initialize current directory (auto-detects tools and stack)
flowforge init

# Initialize a specific directory
flowforge init ./my-project

# Scaffold only for Claude Code
flowforge init --tool claude

# Scaffold for multiple tools
flowforge init --tool claude,opencode

# Choose specific SDLC phases
flowforge init --phases plan,develop,test,review

# Set a custom project name
flowforge init --name my-api

What it does:

1. Detects your tech stack — reads package.json, pyproject.toml, pom.xml, go.mod, Cargo.toml, etc. to determine your language, framework, and test command.

2. Writes .agent.yaml — the project manifest describing which skills are active and what the gate thresholds are.

3. Scaffolds Claude Code (.claude/):

   • .claude/commands/orchestrator.md — the /orchestrator slash command
   • .claude/settings.json — MCP server entry for @thecfguy/flowforge-mcp-server

4. Scaffolds OpenCode (.opencode/):

   • .opencode/commands/orchestrator.md — the /orchestrator slash command
   • .opencode/prompts/ — per-phase agent prompt files (built-in instructions by default)
   • .opencode/orchestrator.config.json — retry/gate configuration

5. Scaffolds Pi (.pi/):

   • .pi/commands/orchestrator.md, .pi/prompts/, .pi/orchestrator.config.json

Tool auto-detection: If --tool is not passed, FlowForge checks for .claude/, .opencode/, or .pi/ directories. If none are found, it defaults to scaffolding both claude and opencode.

flowforge add <phase> [directory]

Add a new SDLC phase to an already-initialized project's .agent.yaml.

# Add a phase using FlowForge built-in instructions
flowforge add deploy

# Add a phase pointing to your own skill/agent file
flowforge add review --skill-file ./.claude/commands/review.md

# Point to a file anywhere in the project
flowforge add test --skill-file ./company-skills/test.md
flowforge add plan --skill-file ./agents/planning-team.md

# Update an existing phase's skill file
flowforge add review --skill-file ./new-reviewer.md

Valid phases: plan, develop, test, review, docs, deploy, monitor

--skill-file <path> — Path to a custom skill or agent file for this phase, relative to the project root. The file can be:

• An existing Claude Code command file (.claude/commands/review.md)
• A standalone agent instruction file (./agents/planning-team.md)
• A company-shared skill file (../../shared/skills/test.md)
• Any text file that describes what the phase agent should do

The path is recorded in .agent.yaml. When the orchestrator runs, it reads this file and injects its content as the subagent's instructions, wrapped with the FlowForge pipeline context.

If --skill-file points to an existing OpenCode or Pi scaffold directory, the corresponding phase prompt file is automatically refreshed.

flowforge run <phase> [directory]

Print instructions and show the resolved skill file for a specific phase.

flowforge run plan
flowforge run review ./my-project

Shows:

• Which file will be used as the phase agent's instructions (resolution: explicit, convention, or built-in)
• The required report_stage output fields for that phase
• How to update the skill file if needed

Skill resolution

For each phase, FlowForge resolves instructions in strict priority order:

| Priority | Source | When used | |---|---|---| | 1 — Explicit | skillFile: path in .agent.yaml | When set via flowforge add --skill-file | | 2 — Convention | ./skills/{phase}/SKILL.md | Auto-detected if the file exists (no config needed) | | 3 — Built-in | Embedded in orchestrator.md | Default when neither of the above exists |

No-config case: A project with zero custom files runs entirely on built-in instructions immediately after flowforge init.

Auto-detection (Priority 2): Drop a file at ./skills/review/SKILL.md and it is picked up automatically — no .agent.yaml change needed.

Custom skill file (Priority 1): The skillFile path can point to any existing file in the project, including files created for other purposes (like existing IDE command files). FlowForge reads the file verbatim and injects it as the subagent's instructions. The report_stage contract is always injected on top by FlowForge — the skill file itself never needs to mention it.

Unlimited depth: A phase's skill file can itself be a sub-orchestrator that spawns multiple sub-agents internally. FlowForge only cares about the terminal report_stage call — the internal depth is completely opaque to it.

.agent.yaml format

apiVersion: flowforge/v1
kind: AgentManifest
metadata:
  name: my-project
  version: "1.0.0"
  stack: [nodejs, typescript]

skills:
  # Level 0 — use FlowForge built-in instructions (default)
  - phase: plan

  # Level 1 — auto-detected convention path (no config needed)
  # ./skills/develop/SKILL.md is picked up automatically if it exists
  - phase: develop

  # Level 2 — explicit path to a custom skill file anywhere in the project
  - phase: test
    skillFile: ./company-skills/test.md

  # Level 3 — reuse an existing command file without modifying it
  - phase: review
    skillFile: ./.claude/commands/review.md

  # Level 4 — delegate to a sub-orchestrator (FlowForge is opaque to depth)
  - phase: docs
    skillFile: ./agents/docs-team.md

mcp:
  server: "@thecfguy/flowforge-mcp-server"
  transport: stdio

orchestrator:
  maxCodingRetries: 3      # Retry Develop this many times on test failure
  maxReviewRetries: 2      # Retry full cycle this many times on review gate fail
  impactGateThreshold: 6   # Impact score ≤ this passes automatically (0-10)
  qualityGateThreshold: 7  # Quality score ≥ this passes review gate (0-10)
  testCommand: npm test    # Used by built-in Test phase instructions

Generated files

.claude/commands/orchestrator.md

The /orchestrator slash command for Claude Code. It:

1. Calls list_skills({ projectDir }) to resolve skill files for all phases
2. For phases with a resolved file: reads the file and injects its content as the subagent's instructions
3. For phases without a file: uses the embedded built-in instructions
4. Always wraps subagent prompts with the FlowForge pipeline context (runId, taskDescription, report_stage contract)

Run it with:

/orchestrator add user authentication with JWT

.opencode/commands/orchestrator.md / .pi/commands/orchestrator.md

The /orchestrator slash command for OpenCode and Pi. References the per-phase prompt files in .opencode/prompts/ or .pi/prompts/.

.opencode/prompts/ / .pi/prompts/

Per-phase agent prompt files. Generated at flowforge init time with built-in FlowForge instructions. When flowforge add --skill-file is used, the content of the custom skill file is copied into the matching prompt file.

.opencode/prompts/
├── planner.md    ← plan phase instructions
├── coder.md      ← develop phase instructions
├── tester.md     ← test phase instructions
├── reviewer.md   ← review phase instructions
└── docs.md       ← docs phase instructions

Each prompt file includes the FlowForge pipeline context header (runId, report_stage contract, required output fields) regardless of whether the content is built-in or from a custom skill file.

Stack detection

flowforge init automatically detects:

| File found | Stack tags set | Test command | |---|---|---| | package.json | nodejs | npm test | | package.json + tsconfig.json | nodejs, typescript | npm test | | package.json + NestJS dep | nodejs, typescript, nestjs | npm test | | package.json + React dep | nodejs, react | npm test | | pyproject.toml | python, poetry | pytest | | requirements.txt | python, pip | pytest | | go.mod | go | go test ./... | | Cargo.toml | rust | cargo test | | pom.xml | java, maven | mvn test | | build.gradle | java, gradle | ./gradlew test |

License

MIT