@callumvass/forgeflow-pm

PRD and planning commands for Pi. Use this package when you want to go from an idea to a solid PRD, then to implementation-ready GitHub or Jira issues.

Install

npx pi install @callumvass/forgeflow-pm

Start here

Greenfield project

/init
# optionally create the initial bootstrap issue and run /implement on it
/continue

/init now writes both PRD.md and .forgeflow/BOOTSTRAP.md. The PRD stays human-readable; .forgeflow/BOOTSTRAP.md preserves exact blank-slate constraints such as starter/template identifiers, package manager choice, scaffold commands, versioned tooling requests, and explicit use/avoid constraints.

If you choose to create the bootstrap issue during /init, implement that slice first, then run /continue so forgeflow can update ## Done / ## Next from the actual codebase and create the next issue set.

If you prefer to refine the PRD before any issue creation, you can still run:

/prd-qa
# final review/edit of PRD.md
/create-gh-issues

Use /investigate only if you want a deeper spike before locking a major decision such as framework, auth, persistence, or testing.

Existing project

/continue "describe the next phase"

That updates PRD.md with ## Done / ## Next, QAs the next phase, then creates issues.

Commands

Command	What it does
/init	Draft a first PRD.md, capture bootstrap constraints, and optionally create the initial bootstrap issue
/prd-qa	Refine PRD.md through the full critic → architect → integrator loop, then prompt for one final review
/continue	Update PRD.md for the next phase on an existing project
/create-gh-issues	Turn PRD.md into vertical-slice GitHub issues
/create-gh-issue	Create one GitHub issue from a feature idea
/investigate	Research a topic, compare options, and write a spike/RFC markdown doc
/create-jira-issues	Turn Confluence PM docs into Jira issues
/atlassian-login	Authenticate to an OAuth-enabled Atlassian MCP server
/atlassian-status	Show Atlassian MCP auth status
/atlassian-logout	Remove stored Atlassian MCP credentials
/atlassian-read	Read a Jira issue or Confluence page by URL

Shared Pi UX

The PM extension shares the same Pi runtime and stage UX as forgeflow-dev.

That means PM runs now benefit from the same improved pipeline chrome:

• richer live status while a pipeline is running
• clearer stage titles and descriptions in rendered output
• /stages and Ctrl+Shift+S to drill into the latest forgeflow pipeline
• better session naming and stage timing visibility during long-running PM flows

This is especially useful for longer PRD, investigation, and issue-creation runs where you want to inspect what each stage actually did without leaving Pi.

What a good greenfield PRD should contain

After /prd-qa, a greenfield PRD should usually include:

• clear product goals and MVP flow
• scope and non-goals
• ## Technical Direction with the chosen stack/framework/testing/auth/persistence decisions where they materially matter
• ## Alternatives Considered for major project-shaping decisions, kept brief
• ## Locked Technical Inputs pointing to .forgeflow/BOOTSTRAP.md when /init captured exact bootstrap/tooling constraints

This gives you an easy review point before issue creation:

• "Use Vue, not React"
• "Use Clerk, not Better Auth"
• "Use ASP.NET Core Identity"
• "Keep this framework-light for MVP"

/create-gh-issues treats the chosen option as binding and alternatives as context only. If .forgeflow/BOOTSTRAP.md exists, exact starter/template identifiers, package manager choices, scaffold commands, versioned tooling choices, and explicit use/avoid constraints are binding too.

/investigate in plain English

/investigate is a general research command, not just a Confluence feature.

Use it when you want a deeper comparison before editing the PRD, for example:

/investigate "Compare auth options for this app in the chosen ecosystem"
/investigate "Compare suitable frontend/runtime choices for this project"
/investigate "Assess whether the current auth and cookie approach is safe"

It:

• explores the codebase
• checks existing dependencies and patterns
• can research the web
• writes a markdown spike/RFC document in the repo

Optional template support:

/investigate "Compare auth options" --template <url>

If no template is provided, forgeflow uses a default structure. Confluence templates are supported, but not required.

How issue creation works

/create-gh-issues creates vertical slices for autonomous implementation. Each issue:

• delivers one user-observable flow
• includes a trigger test
• names one owning boundary and public entry point
• carries forward the chosen technical direction from the PRD

On greenfield repos, /create-gh-issues should usually create one small initial scaffold/bootstrap issue first, then the first product slice after it.

That scaffold issue should:

• establish the chosen app/runtime shape and baseline test harness
• establish the first reusable boundary beneath the broad source root
• stay small and observable rather than absorbing the first substantial product feature

Later issues should depend directly or transitively on that scaffold issue.

Generic roots such as src/, app/, server/, client/, test/, and tests/ are treated as roots, not owning boundaries. On greenfield repos, the first slices must establish real feature/domain boundaries beneath those roots so later implementation does not drift into a flat source tree.

Jira and Confluence

If you use Atlassian, configure Atlassian MCP once:

export ATLASSIAN_MCP_URL=https://your-atlassian-mcp.example.com/mcp
export ATLASSIAN_MCP_REDIRECT_URI=http://127.0.0.1:33389/callback
# Optional when your MCP server requires a pre-registered OAuth client
export ATLASSIAN_MCP_CLIENT_ID=...
export ATLASSIAN_MCP_CLIENT_SECRET=...
# Optional OAuth scope override
export ATLASSIAN_MCP_SCOPE="read:jira-work read:confluence-content.all"
# Optional site hint for Jira URL generation, multi-site setups,
# and MCP servers that expose separate Jira/Confluence cloud resources for one site
export ATLASSIAN_URL=https://yourcompany.atlassian.net

Then run:

/atlassian-login
/atlassian-status

Extra notes:

• /atlassian-read <url> reads a Jira issue or Confluence page into chat
• /create-jira-issues turns Confluence PM docs into Jira issues
• /investigate can optionally use a Confluence template URL and prefetch Jira/Confluence links mentioned in the topic
• /atlassian-logout removes the stored Atlassian MCP login

Set ATLASSIAN_JIRA_PROJECT unless you provide an example Jira ticket URL that lets forgeflow infer the project key.

Auto skill loading

PM pipelines also shortlist relevant skills before /init, /continue, /investigate, /create-gh-issue, and /create-gh-issues. This uses the same common local/global roots as forgeflow-dev, including existing .claude/skills, .copilot/skills, .codex/skills, .opencode/skills, .agents/skills, and pi-native skill directories. Skills stay in place; forgeflow reads them where the team already keeps them.

Configuration

Optional config lives in:

• project: .forgeflow.json
• global: ~/.pi/agent/forgeflow.json

Example:

{
  "agents": {
    "prd-critic": { "thinkingLevel": "high" },
    "prd-architect": { "thinkingLevel": "medium" },
    "gh-issue-creator": { "thinkingLevel": "high" },
    "investigator": { "thinkingLevel": "high" }
  },
  "skills": {
    "enabled": true,
    "extraPaths": ["~/company-shared-skills", "./tools/skills"],
    "maxSelected": 4
  },
  "sessions": {
    "persist": true,
    "archiveRuns": 20,
    "archiveMaxAge": 30
  }
}

Valid thinkingLevel values: off, minimal, low, medium, high, xhigh.

Sessions

PM sub-agent stages now run through the Pi SDK rather than by spawning nested Pi processes. They still keep resumable session files under .forgeflow/run/<runId>/, so you can inspect the exact stage lineage on disk when needed.

Each persisted stage appends a hidden handoff note with its final output plus the main files, searches, edits, and shell commands it used. Later forked stages inherit that note as context, which reduces avoidable rediscovery across a run.

On success runs are archived; on failure they are left in place so you can inspect or resume them.

See also

• Root README: ../../README.md
• Dev package: ../dev/README.md