productize-runtime
Explains Productize capabilities, CLI commands, core workflow skills, optional extension skills, configuration, artifact structure, reusable agents, and extensions. Use when the user asks how to use Productize, what commands are available, how the workflow pipeline works, or how to configure a workspace. Do not use for executing workflow steps — use the specific workflow skills (create-prd, create-techspec, create-tasks, execute-task, review-round, fix-reviews, final-verify, workflow-memory) instead.
- License 许可
- MIT
- 最近更新
- 2026-08-07
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- productize-runtime
- description
- Explains Productize capabilities, CLI commands, core workflow skills, optional extension skills, configuration, artifact structure, reusable agents, and extensions. Use when the user asks how to use Productize, what commands are available, how the workflow pipeline works, or how to configure a workspace. Do not use for executing workflow steps — use the specific workflow skills (create-prd, create-techspec, create-tasks, execute-task, review-round, fix-reviews, final-verify, workflow-memory) instead.
02 资源文件 4
- 参考文档references/cli-reference.md15.8 KB
- 参考文档references/config-reference.md13.4 KB
- 参考文档references/skills-reference.md9.3 KB
- 参考文档references/workflow-guide.md11.3 KB
03 SKILL.md 正文
Productize Reference Guide
Comprehensive reference for the Productize CLI and its daemon-backed product workflow runtime.
What Is Productize
Productize is a Go CLI and daemon-backed runtime for shipping products with AI agents. It keeps product work in markdown, syncs authored workflow artifacts into daemon state, supervises ACP-backed agent runs, and supports review/fix loops, reusable agents, extensions, memory, gates, and routed product skills.
Key characteristics:
- Agent-agnostic. Supports claude, codex, copilot, cursor-agent, droid, gemini, opencode, and pi as ACP runtimes.
- Skills-based. Bundled Productize workflow skills and Productize product-operating skills (installed via
productize setup) teach agents how to execute each workflow phase. - Artifact-driven. Planning and review artifacts live as markdown under
.productize/tasks/<slug>/, versioned alongside the codebase. - Daemon-backed runtime. A home-scoped daemon owns run state, workspace registration, snapshots, streams, and the synced
global.dbcatalog under~/.productize/. - Single binary runtime. The daemon is launched from the same binary; there are no external control planes.
Workflow Pipeline Overview
The standard development pipeline follows these phases in order. Each phase produces artifacts consumed by the next.
- Existing Project Onboarding --
productize onboard existing --agent <name>resolves the repository root, inventories existing code and documentation, generates project knowledge, installs Productize, and registers the workspace. - Setup (new repos or manual control) -- interactive
productize setupselects one agent target. Repeated--agentflags explicitly install into several targets;--all-agentsis the only all-target shortcut. - Ideation (optional) -- install and enable the first-party
idea-forgeextension, runproductize setup, then use/idea-forgeto expand a raw idea into a structured, research-backed spec at.productize/tasks/<slug>/_idea.md. - Requirements --
/create-prdcreates a business-focused Product Requirements Document at.productize/tasks/<slug>/_prd.mdwith ADRs. - Technical Design --
/create-techspectranslates the PRD into a technical specification at.productize/tasks/<slug>/_techspec.mdwith ADRs. - Task Decomposition --
/create-tasksbreaks down the PRD and TechSpec into independently implementable task files (task_01.md,task_02.md, etc.) and a master list at_tasks.md. - Execution --
productize tasks run <slug> --ide <runtime>dispatches task files to the configured AI agent. Execution is sequential by default;--concurrent Nenables bounded parallel execution of dependency-ready tasks. - Review --
/review-round(manual AI review) orproductize reviews fetch <slug> --provider coderabbit --pr <N>(external provider) produces review issue files underreviews-NNN/. - Remediation --
productize reviews fix <slug>processes review issues, triages, fixes, and verifies each one. - Archive --
productize archive --name <slug>moves fully completed workflows to.productize/tasks/_archived/, then refreshes project knowledge.
Repeat phases 7-8 until the review is clean, then merge.
digraph productize_pipeline {
"productize onboard existing" [shape=box];
"/idea-forge (optional)" [shape=box];
"/create-prd" [shape=box];
"/create-techspec" [shape=box];
"/create-tasks" [shape=box];
"productize tasks run" [shape=box];
"Review (manual or provider)" [shape=box];
"productize reviews fix" [shape=box];
"Reviews clean?" [shape=diamond];
"productize archive" [shape=doublecircle];
"productize onboard existing" -> "/idea-forge (optional)";
"/idea-forge (optional)" -> "/create-prd";
"/create-prd" -> "/create-techspec";
"/create-techspec" -> "/create-tasks";
"/create-tasks" -> "productize tasks run";
"productize tasks run" -> "Review (manual or provider)";
"Review (manual or provider)" -> "productize reviews fix";
"productize reviews fix" -> "Reviews clean?";
"Reviews clean?" -> "Review (manual or provider)" [label="no"];
"Reviews clean?" -> "productize archive" [label="yes"];
}
For a detailed step-by-step walkthrough of each phase, read references/workflow-guide.md.
CLI Commands Quick Reference
| Command | Purpose | Key Flags |
|---|---|---|
| Setup & Config | ||
productize onboard existing |
Integrate an existing repository, install agent assets, and register it | --agent, --dry-run, --skip-setup, --skip-register, --format |
productize init existing |
Create or refresh only .productize/project/ knowledge docs |
--dry-run, --exclude, --force, --format |
productize setup |
Install skills into one selected agent target by default | --agent, --all-agents, --skill, --global, --copy, --list, --yes |
productize setup cleanup |
Safely remove old managed agent targets | --keep-agent, --global, --dry-run, --yes, --format |
productize upgrade |
Update CLI to latest release | |
| Workflow Execution | ||
productize daemon |
Manage the home-scoped daemon lifecycle | start, status, stop |
productize workspaces |
Inspect and manage daemon workspace registrations | list, show, register, unregister, resolve |
productize tasks run |
Execute PRD task files through the daemon | --name, --concurrent, --verify-command, --format, --attach, --stream, --detach, --task-runtime |
productize exec |
Execute an ad hoc prompt | --agent, --format, --prompt-file, --persist, --run-id |
productize runs |
Attach, watch, and purge daemon-managed runs | attach, watch, purge |
| Review | ||
productize reviews fetch |
Fetch provider review comments | --provider, --pr, --name, --round |
productize reviews fix |
Process review issue files | --name, --round, --concurrent, --batch-size, --ide |
| Utilities | ||
productize tasks validate |
Validate task file metadata | --name, --tasks-dir, --format |
productize sync |
Reconcile workflow artifacts into daemon global.db, then refresh project knowledge |
--name, --root-dir, --tasks-dir |
productize archive |
Move daemon-eligible completed workflows to archive, then refresh project knowledge | --name, --root-dir, --tasks-dir |
productize migrate |
Convert legacy artifacts to frontmatter | --name, --dry-run, --reviews-dir |
| Agent Management | ||
productize agents list |
List resolved reusable agents | |
productize agents inspect |
View agent definition and defaults | <name> |
| Extensions | ||
productize ext list |
List extensions | |
productize ext inspect |
View extension details | <name> |
productize ext install |
Install an extension from a local path or GitHub repo archive | <source>, --remote, --ref, --subdir |
productize ext uninstall |
Remove an extension | <name> |
productize ext enable/disable |
Toggle extension | <name> |
productize ext doctor |
Diagnose extension issues |
Common flags shared by tasks run, exec, and reviews fix: --ide, --model, --reasoning-effort, --add-dir, --auto-commit, --dry-run.
For complete flag documentation, read references/cli-reference.md.
Core Skills Summary
| Skill | Trigger | When To Use | Do Not Use For |
|---|---|---|---|
create-prd |
/create-prd |
Building a Product Requirements Document | TechSpec, task breakdown, coding |
create-techspec |
/create-techspec |
Translating PRD into technical design | PRD creation, task execution |
create-tasks |
/create-tasks |
Decomposing PRD+TechSpec into task files | Execution, review |
execute-task |
(internal) | Executing a single PRD task (called by productize tasks run) |
Direct invocation, review work |
review-round |
/review-round |
Performing comprehensive code review | Fetching external reviews, fixing |
fix-reviews |
(internal) | Remediating review issues (called by productize reviews fix) |
Fetching reviews, task execution |
final-verify |
/final-verify |
Enforcing verification before completion claims | Early planning, brainstorming |
workflow-memory |
(internal) | Maintaining cross-task workflow memory | PR reviews, user preferences |
productize-runtime |
/productize-runtime |
Learning how to use the Productize CLI runtime | Executing workflow steps |
Productize Skills Summary
Productize skills are bundled alongside the Productize workflow skills. Use
/productize as the Productize router, or call namespaced skills directly when
the job is clear.
| Skill | Trigger | When To Use |
|---|---|---|
productize |
/productize |
Route product, strategy, growth, delivery, design, analytics, finance, launch, or AI-builder work |
productize-0-1 |
/productize-0-1 |
Turn a raw product idea or new capability bet into a first shipped slice |
productize-product-review |
/productize-product-review |
Review product scope, requirements, tradeoffs, and acceptance criteria |
productize-design-review |
/productize-design-review |
Review UX, hierarchy, interaction quality, and visual polish |
productize-eng-review |
/productize-eng-review |
Review architecture, implementation risk, data flow, and build readiness |
productize-qa |
/productize-qa |
Define or review verification evidence, scenarios, evals, and regression risk |
productize-release |
/productize-release |
Check ship readiness, rollback paths, launch blockers, and release evidence |
Optional Extension Skills
| Skill | Trigger | When To Use | Install Flow |
|---|---|---|---|
idea-forge |
/idea-forge |
Raw feature idea needs structured exploration before a PRD | productize ext install --yes itseffi/productize --remote github --ref <tag> --subdir extensions/idea-forge -> productize ext enable idea-forge -> productize setup |
For detailed skill descriptions and inputs/outputs, read references/skills-reference.md.
Artifact Directory Structure
.productize/
config.toml # Workspace configuration
project/
context.md # Project context pack for future work
conventions.md # Detected commands and instruction sources
architecture.md # Repository map and promoted architecture ADRs
decisions.md # Promoted durable ADR content and shared memory
constraints.md # Durable constraints and unresolved risks
manual.md # Optional human-authored additions; never generated
tasks/
<slug>/ # One directory per workflow
_idea.md # Idea spec (from idea-forge)
_prd.md # Product Requirements Document
_techspec.md # Technical Specification
_tasks.md # Master task list
task_01.md ... task_N.md # Individual task files
adrs/
adr-001.md ... adr-NNN.md # Architecture Decision Records
reviews-NNN/
issue_001.md ... issue_N.md # Review issues with round metadata in frontmatter
memory/
MEMORY.md # Shared workflow memory
task_01.md ... task_N.md # Per-task memory
_archived/
<timestamp>-<slug>/ # Archived completed workflows
agents/
<name>/ # Workspace-scoped reusable agents
AGENT.md # Agent definition
mcp.json # Optional MCP server config
extensions/ # Workspace-scoped extensions
Global paths:
~/.productize/agents/<name>/-- global reusable agents (workspace overrides global)~/.productize/extensions/-- user-scoped extensions~/.productize/runs/<run-id>/-- daemon-managed run artifacts and persisted exec sessions~/.productize/db/global.db-- daemon workspace, workflow, task, and review catalog
Project Knowledge Lifecycle
context.md, conventions.md, architecture.md, decisions.md, and
constraints.md are canonical generated read models. Productize owns and
rewrites them only when they carry the productize:project-knowledge marker.
Keep deliberate human-authored additions in .productize/project/manual.md.
productize onboard existingperforms the complete first-time integration and records repository Knowledge Coverage incontext.md.productize init existingexplicitly creates or refreshes only the read models.- A successful
productize synccatalogs authored workflow artifacts and then refreshes project knowledge. productize archivemoves an eligible workflow first and refreshes afterward, preserving durable ADR content and shared memory from archived workflows.
Idea, PRD, TechSpec, task-generation, and task-execution workflows read all five
canonical documents when present, plus manual.md when present. Product-facing
artifacts use architecture and constraints only for feasibility and boundaries.
Sync or archive can succeed while the derived refresh reports degraded: true.
Text output exposes the status, checksum, skipped paths, and warnings; JSON uses
the optional project_knowledge object with updated, unchanged, skipped,
warnings, source_checksum, and degraded. Resolve the warnings and run
productize sync again to repair stale knowledge.
Configuration
Workspace defaults live in .productize/config.toml. CLI flags always override config values.
[defaults]
ide = "claude"
model = "opus"
auto_commit = true
reasoning_effort = "high"
add_dirs = ["../shared-lib"]
[tasks]
types = ["frontend", "backend", "docs", "test", "infra", "refactor", "chore", "bugfix"]
[tasks.run]
concurrent = 1
include_completed = false
verify_command = "make verify"
[fix_reviews]
concurrent = 2
batch_size = 3
[fetch_reviews]
provider = "coderabbit"
nitpicks = false
[exec]
verbose = false
persist = false
For all fields, types, and defaults, read references/config-reference.md.
Reusable Agents and the Advisor Pattern
Reusable agents are standalone personas that can be invoked via productize exec --agent <name> or referenced by skills through run_agent.
Discovery order: workspace (.productize/agents/<name>/) overrides global (~/.productize/agents/<name>/).
Agent definition: Each agent has an AGENT.md with YAML frontmatter (title, description) and optional mcp.json for MCP server configuration.
Advisor agents shipped by the optional idea-forge extension:
| Agent | Perspective |
|---|---|
pragmatic-engineer |
Execution-focused, delivery speed, maintenance burden |
architect-advisor |
Long-term system coherence, boundaries, coupling |
security-advocate |
Attack vectors, compliance, data protection |
product-mind |
User impact, business value, opportunity cost |
stress-tester |
Challenges assumptions, surfaces risks, stress-tests |
the-thinker |
Cross-domain patterns, structural reframing |
Install flow: productize ext install --yes itseffi/productize --remote github --ref <tag> --subdir extensions/idea-forge -> productize ext enable idea-forge -> productize setup.
The idea-forge skill uses these agents in an advisor debate to challenge feature scope and surface risks.
Management commands: productize agents list, productize agents inspect <name>.
Extensions
Executable plugins that extend Productize at runtime via JSON-RPC 2.0 on stdin/stdout.
- Three scopes: bundled (shipped with Productize), user (
~/.productize/extensions/), workspace (.productize/extensions/). Workspace overrides user overrides bundled. - Disabled by default. Enable explicitly with
productize ext enable <name>or--extensionsflag onexec. - Capabilities: lifecycle observation, prompt decoration, plan injection, agent session modification, review provider registration.
- SDKs: TypeScript (
@productize/extension-sdk), Go (sdk/extension). - Scaffolding:
npx @productize/create-extensiongenerates extension boilerplate.
Management: productize ext list, productize ext inspect <name>, productize ext install <source>, productize ext uninstall <name>, productize ext enable/disable <name>, productize ext doctor.
Common Patterns
- For an existing repository, run
productize onboard existing --agent <name>before PRD creation. - Use
productize setupseparately for new repositories or manual installation control. Select one agent unless multiple explicit targets are required. - Use
productize setup cleanup --keep-agent <name> --dry-runwhen an older installation populated unwanted agent directories. Never delete drifted or unknown paths automatically. - Follow the pipeline in order: onboarding (existing repos) -> idea (optional) -> PRD -> TechSpec -> Tasks -> Execution -> Review -> Fix.
- Configure workspace defaults in
.productize/config.tomlto reduce repetitive CLI flags. - Run
productize tasks validate --name <slug>beforeproductize tasks runto catch metadata issues early. - Use
productize archiveto clean up fully completed workflows and keep the tasks directory focused. - Use
productize exec --agent <name>for ad hoc prompts with a specific advisor perspective. - Use
productize exec --persistto save session artifacts for later resumption with--run-id.
Anti-Patterns
- Skipping pipeline stages. Running
productize tasks runwithout a PRD and task files produces poor results. - Invoking
execute-taskdirectly. Useproductize tasks run, which handles dispatch, sequencing, memory, and tracking. - Mixing workflow skills out of order. Running
/create-taskswithout a PRD and TechSpec leads to shallow task decomposition. - Editing task file frontmatter manually. Use
productize migrateorproductize tasks validateto fix metadata issues programmatically. - Confusing skills with CLI commands. Skills (slash commands like
/create-prd) run inside an agent session. CLI commands (productize tasks run) run in the terminal. - Skipping verification. Always use
final-verifybefore claiming task completion or creating commits.
04 同仓库更多 Skills
workflow-memory
Maintains workflow-scoped task memory for Productize runs using .productize/tasks/<name>/memory/ files. Use when a task prompt provides workflow memory paths and requires the agent to read, update, compact, and promote durable context across PRD task executions. Do not use for PR review remediation, global user preferences, or programmatic event-log summarization.
review-round
Performs a comprehensive code review of a PRD implementation and generates a review round directory with issue files compatible with fix-reviews. Use when reviewing implemented PRD tasks, creating a manual review round without an external provider, or performing a quality audit of code changes. Do not use for fetching reviews from external providers, fixing existing review issues, executing PRD tasks, or editing source code.
productize
Productize root skill for building, shipping, operating, and growing AI products inside a coding harness. Routes work across thesis framing, discovery, research, positioning, finance, decision making, requirements, design, metrics, AI-builder execution, code implementation, verification, stakeholder narratives, growth, launch, operation, and learning workflows. Use when the user wants to build a product from zero, improve an existing product, or needs product work that spans multiple lifecycle stages before code, launch, operation, or growth execution.
productize-wwas
Why-What-Acceptance. Use when writing backlog items in Why-What-Acceptance format, breaking features into independent valuable work, or adding strategic context to delivery items.
productize-writing-plans
Create comprehensive implementation plans with bite-sized tasks. Use when you have requirements before touching code.
productize-write-spec
Write a feature spec or PRD from a problem statement or feature idea. Use when turning a vague idea into a structured document, scoping goals and non-goals, defining success metrics and acceptance criteria, or breaking a big ask into phases.