Skip to main content

Product Development Flow — branch, deliberate, merge, resolve

canonical · pm · updated 2026-09-05 · source

Mechanism note (2026-06-26): plans are now GitHub issues / efforts, not MDX files in apps/admin/src/plans/ (ADR-006). The philosophy below stands; the current mechanism lives in .claude/rules/effort-model.md and plan-engine.md.

Philosophy of how the product evolves: the Master Plan is the trunk; each effort is a subplan that branches off, executes, gets approved in a meeting, merges into the product, and is marked resolved — like git-flow, but for plans. Nothing floats without a link to history.

1. Principle​

Every change to the product is born from a subplan linked to the product timeline. This way we always know whether one effort intercepts or touches another (present or future). A subplan without a link is a risk: we couldn't tell whether it collides with a future plan. Hence: branch with context, execute, approve, merge, resolve.

2. The tree (Master Plan ↔ subplans) — git-flow analogy​

GitHereWhat it is
develop (trunk)Master Plan (the board/roadmap view over open efforts)the single direction of the product
feature branchEffort (parent GitHub issue + native sub-issues + worktree, effort-model.md)a bounded effort
commit/PRthe effort's sub-issue commits + ONE PRthe actual delivery
merge to developparent issue closed + merged PRabsorbed into the product
tag/releaseroadmap milestonea stable cut

The effort's parent issue IS the plan (no file) — see effort-model.md; its code lives in the effort/<N>-<slug> worktree (rules in branch-naming.md). One effort = one parent issue = one branch = one PR.

3. Lifecycle of a subplan​

Draft  →  Active (branch + worktree)  →  Agency meeting + approval  →  merge  →  Complete (resolved)
  1. Branch with context — its place in the timeline and its dependencies are declared in the frontmatter (§6). The system/PM detects interference with present or future plans before starting.
  2. Execute — one step at a time; another subplan can be branched in parallel safely (isolated worktrees, lockfile rule, merge order — §5).
  3. Agency meeting + approval — the agency (group of required agents) deliberates (council/board meeting), produces minutes + a recommendation, and José approves (human gate). Only then is it merged.
  4. Merge + resolve — the PR lands, the subplan moves to Complete, and stays visible in the timeline as history.

4. Agencies (groups of agents that deliver)​

An agency is the set of agents a solution requires (e.g. Tech Lead + Frontend + QA + Security). They deliberate in a meeting (the engine's council node), deliver a solution, and nothing executes without José's approval (except explicitly authorized work). Specific jobs run on demand; high-risk ones always pass through the human gate. The agent roster and their model live in .claude/agents/ and in @tedos/engine (roles + council).

5. Guards (why branching is safe)​

  • Isolated worktree per branch (one checkout per effort) — branch-naming.md.
  • Main/develop read-only; hooks block direct edits/commits.
  • Lockfile rule: one PR touching the deps graph at a time.
  • Merge order: deps first, risk:low before risk:high, lockfile-touching one at a time.
  • Bounded mixed PRs (size:XL = split it).

That's why several subplans can branch off in parallel without corrupting each other.

---
title: 'Tu Empresa Digital OS — <topic>'
role: PM | Tech Lead | Designer | Frontend | Backend | DevOps | QA | Security | Research
status: Draft | Active | Complete
parent: tedos-pm-master-plan # links to the trunk (never "unlinked")
timeline: 'Phase N' # position in the Master Plan roadmap
dependsOn: [<issue|plan>] # must come after
blocks: [<issue|plan>] # blocks
branch: '<kind>/<issue>-<slug>' # the effort's git branch
issue: <n>
date: YYYY-MM-DD
version: '1.0'
tags: [...]
---

parent + timeline + dependsOn/blocks are what prevent one effort from intercepting another. The Master Plan (§7 index) lists all live subplans — it is the registry.

7. UI — the user understands what's happening​

The surface (apps/admin) must make this flow visible, just as /app/run makes the engine's execution visible:

  • Product timeline — subplans as nodes per phase, with their status (Draft/Active/Complete) and dependencies (what touches what).
  • Agency meetings — minutes + recommendation + José's approval button (gate).
  • Status of each effort — branch, PR, risk, what it blocks.

Principle: the user never guesses. They see the tree, the meetings, the approvals, and the merges — legible product development, not a black box.

8. Relationship to other rules​

plan-output-format.md (MDX format) · branch-naming.md (branches/merge) · agent-execution-routing.md (which engine runs) · mempalace.md (memory). This philosophy orchestrates them into a single narrative: one trunk, many branches with context, meetings with approval, traceable merges.