recipe-platform

Orchestration hub for the recipe management system. This repo is not deployed and has no runtime — it exists to coordinate development across two sibling repos:

Repo	Role
recipe-platform (this repo)	Orchestration hub
recipe-backend	REST API server — Express 5, TypeORM, PostgreSQL
recipe-app	React SPA — React 19, Vite, TailwindCSS, PWA

What lives here

api-contract/ — The @recipe/contract npm package. Both sibling repos install it via npm install file:../recipe-platform/api-contract and compile against it. A contract change breaks both repos at compile time, making API drift impossible.

docs/epics/ — Epics written by the Business Analyst agent: how an idea too large for one spec splits into feature specs, in which order, and the decisions that span them.

docs/features/ — Feature specs written by the Business Analyst agent. Each spec is the input to the planning pipeline and the source of truth for what a feature does and why.

docs/adr/ — Cross-cutting Architecture Decision Records. Decisions that affect both repos consistently are recorded here so future sessions don't re-litigate them.

.claude/agents/ — Agent definitions (ba, architect) that encode requirements and architecture domain knowledge for Claude Code.

.claude/skills/ — Workflow skills (/plan-feature, /implement-feature, /review-feature) that drive the multi-repo development pipeline with human sign-off gates.

plugins/recipe-workflow/ — Claude Code plugin with the skills all three repos share (pr-feedback, check-workspace, adr, implement-plan, review-implementation). .claude-plugin/marketplace.json publishes it as a plugin marketplace, which each repo enables in its .claude/settings.json.

scripts/release.sh — Tags a production release of the backend, the frontend, or both. It computes the next bug-fix, feature or major version (or checks a custom one) from the existing tags, shows a summary, and on confirmation pushes lowercase v* tags on main, backend first. If stage has commits that are not on main yet, it points to the open release PRs, or offers to open the missing ones, and stops until they are merged; it also stops when main has nothing new since the last tag. --dry-run walks through everything without tagging. Use it instead of the Forgejo UI, which creates uppercase V* tags that the release workflows don't react to.

scripts/create-release-pr.sh — Opens the release PR (stage → main) of the backend, the frontend, or both, titled Release: … after the PRs merged into stage. release.sh calls it; it can also be run on its own. It never merges. It takes the Forgejo token from the environment or, if it is not set there, from the Claude Code settings, so the token is stored only once.

Both scripts need git, curl and jq.

Getting started

See ONBOARDING.md.

How features are built

See the Workflow section in CLAUDE.md for the full pipeline and docs/howto-feature-workflow.md for a step-by-step guide. The short version:

1. claude --agent ba in recipe-platform — talk to the Business Analyst agent (Ivar) directly to discuss and write a feature spec (docs/features/<NNN>-<slug>.md), after an epic (docs/epics/E<NN>-<slug>.md, approved on its own) if the idea splits into several specs
2. /plan-feature docs/features/<NNN>-<slug>.md — architect review, then parallel planning in both repos
3. /implement-feature <NNN>-<slug> — parallel implementation, opens PRs against stage
4. /review-feature <NNN>-<slug> — parallel review against plans and spec

Human sign-off is required at every gate.