@coldpress/core

coldpress-os

An AI-native development framework that drives the full lifecycle of AI-assisted software projects — from bootstrap to deployment to evolution.

coldpress-os is Agent Skills-compatible and implements the Spec → Plan → Implement → Review spine, expanded to 11 phases (Shape A — v0.3.0) with sacred-doc governance, multi-agent orchestration, and the forward-carry quartet.

The 11 phases: Bootstrap · Discovery · Tech Stack · Planning · Design · Architecture · Breakdown · Implementation · Deployment · Operate · Evolve. (Phases 5 & 6 added in v0.3.0-alpha — see CHANGELOG.)

One framework. One format. Two runtimes. Pluggable stack packs.

Install

npm install -g @coldpress/core

Requires Node.js >=22 and Claude Code (the CLI or the Agent SDK) on your machine. Python >=3.10 is additionally required for coldpress graph rebuild and the document-ingest skill; install on demand with pip install graphifyy markitdown docling when you reach Phase 2.

Quick Start

coldpress init my-project
cd my-project
claude   # or: use the Agent SDK

coldpress init prompts you for a project name, slug, and user name, then scaffolds:

• coldpress.yaml — project configuration (Phase-1 fields only; later phases write back as you progress)
• CLAUDE.md — framework routing for Butler (your main Claude Code session)
• .claude/agents/ — 11 subagent definitions (analyst, pm, ux-designer, architect, developer, qa, scrum-master, communicator, reviewer, devops, valet)
• .claude/skills/ — ~128 thin wrappers pointing at canonical skills (built from 85 atomic + 67 lifecycle SKILL.md sources)
• _context/ — produced artefacts (planning, design, implementation, testing, tracking, handoffs, audit, sacred docs)
• _input/ — raw inputs, legacy refs, vendor drops, assets
• secure/ — credential manifest + pre-commit secret-scan hook
• coldpress-os/ — framework files (read-only; upgraded via coldpress update)
• AGENTS.md + .cursor/rules/ + .roomodes + .openhands/microagents/ + .clinerules/ — interop outputs so the project feels native in any agent tool

New to coldpress-os? Read the First 10 Minutes or see the TaskPulse example for a full lifecycle demo.

Runtime compatibility

coldpress-os's .claude/ tree loads unchanged under both runtimes:

• Claude Code CLI (interactive dev-time) — claude in the project directory.
• @anthropic-ai/claude-agent-sdk (programmatic / CI pipelines) — import the SDK, point it at the project; all subagents and skills resolve.

See test/agent-sdk-compat.test.ts for the compatibility smoke test.

Commands

coldpress init [project-name]     Scaffold a new project
coldpress update                  Regenerate interop outputs (AGENTS.md, Cursor, Roo, OpenHands, Cline)
coldpress feedback                Open GitHub Issues in your browser
coldpress upgrade                 Print upgrade instructions
coldpress --version               Print installed version

Lifecycle phases (Shape A — v0.3.0-alpha)

11 phases, structured as Spec → Plan → Implement → Review expanded with the forward-carry quartet and a silent-divergence guard at the Design → Architecture boundary.

Phase	Name	Owner	Purpose
1	Bootstrap	butler	Project init, intake, graph-prime, working-mode detection
2	Discovery	@analyst	Research, personas, context, idea validation, product brief
3	Tech Stack	@architect	Stack discovery, evaluation rubric, locking, env provisioning
4	Planning	@pm	PRD authoring + section-scoped re-validation (PRD-only post-split)
5	Design (new)	@ux-designer	UX spec, brand guidelines, prototype, narrative, design-deltas
6	Architecture (new)	@architect	Sacred architecture.md + ADRs incl. REQUIRED ADRs for flagged design-deltas (silent-divergence guard)
7	Breakdown	@pm + @scrum-master	Epics, stories, parallelization strategy, PERT chart
8	Implementation	@developer + @qa	Dev-story, code-review, QA automation, wave orchestration
9	Deployment	@devops	Readiness checks, security scan, dep audit, observability, deploy
10	Operate	@devops	Sprint status, correct-course, incident-response, ops-deltas
11	Evolve (final)	@reviewer	Retrospective, product evolution, innovation strategy → next-iteration Phase 1

Forward-carry quartet — design-deltas (P5 exit) · architecture-deltas (P7 entry) · implementation-deltas (P11 retrospective) · ops-deltas (P11 retrospective). Each delta resolves via four reconciliation options: accept_into_prd, reject, flag_for_architecture_ADR, park_for_phase_11.

Subagents

11 subagents under Shape A. Two added in v0.3.0-alpha (@reviewer, @devops) take Phase 11 and Phases 9–10 respectively.

Slug	Model	Primary phases	Role
analyst	sonnet	2	Research, personas, idea validation, synthesis, product brief
architect	opus	3, 6	Tech stack (P3); sacred architecture + ADRs incl. silent-divergence-guard (P6)
pm	sonnet	4, 7	PRD lifecycle (P4); epic oversight + breakdown (P7)
ux-designer	sonnet	5	UX design spec, brand guidelines, prototypes, narrative
scrum-master	haiku	7	Sprint planning (sub-dispatched from @pm at P7)
developer	sonnet	8	Implementation (standard or quick mode)
qa	sonnet	8	Testing (rapid or strategic mode); sub-dispatched from @developer
devops	sonnet	9, 10	Deployment (P9 ship-path) → operate (P10 steady-state); two phase-modes
reviewer	opus	11	Retrospective, product evolution, innovation strategy (final phase)
communicator	sonnet	cross-cutting	Documentation, narratives, presentations
valet	sonnet	meta	Framework evolution, meta skills

Each subagent's definition lives at .claude/agents/<slug>.md in your scaffolded project. Pattern 7 transitions (19 transition records) formalise agent boundaries at phase entry / exit / sub-phase / reconciliation handoffs.

Key concepts

• Subagents are real Claude Code agents with independent context windows, tools, and models. Butler (your main session) dispatches them via the Agent tool. Not prompt-persona costume changes.
• Skills are the atomic unit of work. Each is self-contained with frontmatter + step-files + references.
• Stack packs are pluggable skill sets for specific technology stacks. Six ship in-tree at v0.3.0-alpha: vibe-coder-fullstack (Convex + Next.js + Clerk), cli-npm-publishable (TypeScript + tsup + Vitest), browser-extension (WXT + Manifest V3), static-single-page, static-multipage-blog (Astro variants), and seo-pack (cross-archetype audit/content/local/schema/technical). Activated via stack_pack: in coldpress.yaml after Phase-3 stack-locking.
• Sacred documents — _context/sacred/{context,tech-stack,prd,architecture,pert-chart}.md — are protected by governance change workflows in coldpress-os/governance/.
• _context/ vs _input/ — produced artefacts vs material fed into the project. Inputs are not written by any skill.

Architecture

@coldpress/core/
├── src/              # CLI + generators (TypeScript)
├── template/         # Scaffolded into consumer projects (11-subagent set)
├── lifecycle/        # 11-phase Shape A skill organisation (67 SKILL.md)
├── skills/           # ~85 atomic reusable skills + 6 stack packs
├── agents/           # Subagent schema + registry
├── schemas/          # ~30 JSON / Zod schemas (sacred docs, handoffs, audit, design)
├── orchestrator/     # Parallelization engine specs
├── governance/       # Sacred-doc change workflows + 4 reconciliation options
├── data/             # Portable knowledge assets (CSV/YAML, method playbook)
├── templates/        # Document / design / infrastructure / prompt-snippet templates
├── plugin/           # Claude Code plugin marketplace tree (~128 spec-compliant SKILL.md)
└── docs/             # Framework documentation

Claude Code plugin marketplace

/plugin marketplace add coldpress-labs/coldpress-os
/plugin install @coldpress/core

Installs the full skill library as an Agent Skills–compliant plugin. Source lives under plugin/skills/, regenerated by npm run build:skills from the rich internal SKILL.md corpus.

Updating

npm update -g @coldpress/core   # pull the latest release

Inside an existing project:

coldpress update   # regenerate AGENTS.md / Cursor / Roo / OpenHands / Cline outputs

How it relates to other tools

• Anthropic Agent Skills — compatible + complementary. Coldpress-os's skills conform to the Agent Skills SKILL.md spec (emitted to plugin/skills/). Installable as a Claude Code plugin via /plugin marketplace add coldpress-labs/coldpress-os. We wrap Anthropic's first-party skills where they overlap with our subagents (docx / pdf / pptx / xlsx under @communicator, webapp-testing under @qa, mcp-builder under @architect, skill-creator under @valet). See docs/agent-skills-compatibility.md.
• BMAD-METHOD — lineage. Coldpress-os is a soft-fork of BMAD v6.2.2 (pinned upstream, no rebase — cherry-pick only). Full attribution in NOTICE.md.
• GitHub Copilot Workspace — shared spine, richer expansion. Both implement Spec → Plan → Implement → Review. Coldpress-os expands the 4-stage spine into 11 phases (Shape A) with sacred-doc governance and typed inter-phase handoffs. See docs/spec-plan-implement-review-mapping.md.
• Graphify — vendored upstream. Indexer + retrieval core at graph/vendor/graphify/. coldpress graph rebuild invokes it; coldpress graph query reads the output.

Documentation

Guide	Description
First 10 Minutes	Hands-on setup walkthrough — zero to a running project
Example Walkthrough	Full lifecycle demo with a sample project (TaskPulse)
Troubleshooting & FAQ	Common issues and solutions
Architecture	Internal technical reference
Spec → Plan → Implement → Review mapping	11-phase Shape A lifecycle grouped under the industry-standard spine
Agent Skills compatibility	How coldpress-os fits the Anthropic Agent Skills ecosystem
Template Registry	Every template — by category, phase, consuming skill
Skill Discovery Index	Every skill grouped by phase + cross-cutting utilities
Subagent × Phase Matrix	11-subagent × 11-phase reference — which subagents do what in which phases
Phase → Subfolder Mapping	Canonical _context/* destinations per phase
coldpress.yaml schema	Per-field phase ownership + write-back contract
Interop generator	AGENTS.md, Cursor, Roo, OpenHands, Cline — spec + tool translation
SKILL.md generator spec	Agent Skills spec compliance + field mapping
Anthropic skill wrapping	Where coldpress-os delegates to Anthropic's first-party skills
Secure pattern	secure/manifest.yaml + credential loader pattern
Decision trees	How Butler routes your intent to skills
Flow map	Visual mapping of phases, skills, and subagents
Glossary	Defined terms
Stack pack guide	Authoring a new technology stack pack
Subagent customization	Modes, overrides, custom agents
Step-file spec	Format specification for workflow step files

Contributing

Feedback flows from projects to coldpress-os via GitHub Issues and PRs. Use coldpress feedback to open the issue form in your browser. See CONTRIBUTING.md for the full guide and CODE_OF_CONDUCT.md for community standards.

Security: please do not open public issues for vulnerabilities. See SECURITY.md for private disclosure.

Acknowledgments

coldpress-os stands on the shoulders of four open-source projects, each of which contributed substantial ideas, code, and craft. All are MIT-licensed, and all are credited in full in NOTICE.md and docs/attribution-audit.md.

• BMAD-METHOD by BMad Code, LLC — the core agent-skill-workflow architecture, document templates, and most utility and review skills. coldpress-os is a direct derivative of BMAD v6.2.2; this framework would not exist in its current form without theirs.
• Creative Intelligence Suite (CIS) by BMad Code, LLC — contributes the brainstorming, design-thinking, problem-solving, innovation-strategy, and storytelling workflows used across Discovery and Planning.
• BMAD-METHOD-WDS (Whiteport Design System) by Mårten Angner / Whiteport Collective — contributes the opinionated UX design workflow (wds-0 through wds-8), design templates, trigger maps, and scenario-driven design methodology powering the ux-designer subagent.
• Graphify by Safi Shamsi — the indexer + retrieval core behind coldpress-os's knowledge graph. Graphify v4 is vendored verbatim at graph/vendor/graphify/ and provides tree-sitter-based AST indexing across 20+ languages plus markdown/document ingestion with graph extraction.

"BMad", "BMad Method", "BMad Core", "Whiteport", and "Whiteport Design System" are trademarks of their respective owners. coldpress-os is an independent project and is not affiliated with or endorsed by any of the above.

License

MIT — see LICENSE.

Built by ColdPress Labs. Built with intention. Scaled with purpose.