@thecfguy/flowforge-core

Shared TypeScript types and Zod schemas for the FlowForge SDLC agent orchestration system.

This package is a zero-runtime-dependency foundation consumed by @thecfguy/flowforge-mcp-server and @thecfguy/flowforge-cli.

Installation

npm install @thecfguy/flowforge-core

What's inside

Schemas

SkillManifestSchema

Validates a parsed SKILL.md frontmatter block.

import { SkillManifestSchema } from '@thecfguy/flowforge-core';

const skill = SkillManifestSchema.parse({
  name: 'SDLC Planner',
  description: 'Plans implementation from a requirement',
  version: '1.0.0',
  author: 'flowforge',
  tags: ['sdlc', 'planning'],
  phase: 'plan',
  mcp_tools: ['initialize_project', 'report_stage', 'gate_check'],
});

Fields:

| Field | Type | Required | Description | |---|---|---|---| | name | string | ✓ | Human-readable skill name | | description | string | ✓ | What the skill does | | version | string | ✓ | Semver (e.g. 1.0.0) | | author | string | ✓ | Author or org name | | tags | string[] | — | Searchable tags (defaults to []) | | phase | SdlcPhase | ✓ | SDLC phase this skill handles | | mcp_tools | string[] | — | MCP tools the agent calls (defaults to []) |

AgentManifestSchema

Validates a project's .agent.yaml file.

import { AgentManifestSchema } from '@thecfguy/flowforge-core';

const manifest = AgentManifestSchema.parse({
  apiVersion: 'flowforge/v1',
  kind: 'AgentManifest',
  metadata: { name: 'my-project', stack: ['nodejs', 'typescript'] },
  skills: [
    { phase: 'plan' },
    { phase: 'develop' },
    // Point a phase at any existing file — FlowForge reads it and wraps it
    { phase: 'review', skillFile: './.claude/commands/review.md' },
  ],
});

metadata fields:

| Field | Type | Description | |---|---|---| | name | string | Project identifier | | version | string | Project version (default "1.0.0") | | stack | string[] | Technology stack tags | | description | string? | Optional description |

SkillRef fields (each entry in skills):

| Field | Type | Required | Description | |---|---|---|---| | phase | SdlcPhase | ✓ | SDLC phase | | source | string | — | Source identifier (default "@thecfguy/flowforge-skills") | | version | string | — | Version constraint (default "^1.0.0") | | skillFile | string | — | Path to a custom skill/agent file (relative to project root). Resolution priority: skillFile > ./skills/{phase}/SKILL.md > built-in |

orchestrator fields:

| Field | Type | Default | Description | |---|---|---|---| | maxCodingRetries | number | 3 | Max Develop retries on test failure | | maxReviewRetries | number | 2 | Max full-cycle retries on review gate fail | | impactGateThreshold | number | 6 | Max impact score before user prompt (0–10) | | qualityGateThreshold | number | 7 | Min quality score to pass review gate (0–10) | | testCommand | string | — | Test command used by the built-in Test phase agent |

PipelineRunSchema

Tracks the state of a single orchestrator execution.

import { PipelineRunSchema, StageStatus } from '@thecfguy/flowforge-core';

StageStatus values: "pending" | "running" | "complete" | "failed" | "gated"

SdlcPhase values: "plan" | "develop" | "test" | "review" | "docs" | "deploy" | "monitor"

Types

import type {
  SkillManifest,
  AgentManifest,
  SkillRef,       // { phase, source, version, skillFile? }
  McpConfig,
  OrchestratorConfig,
  PipelineRun,
  StageEntry,
  StageStatus,
  SdlcPhase,
  ProjectRegistry,
} from '@thecfguy/flowforge-core';

License

MIT