Connected projects
Many repositories. One product in view.
Share a single project record through a wrapper, or connect independent records through federation. Keep source history in each repository and make the relationships between the work visible.
Choose your layout
One shared record
Use a wrapper when related repositories share one roadmap and one .story/ directory. Keep code commits in each repository and project records in the wrapper. Choose this when the repositories share one planning record.
Connected project records
Use federation when each repository keeps its own stories and handovers. An orchestrator connects the nodes for dependency-aware recommendations. Existing project histories stay in place.
Read the federation walkthroughWrapper projects
One roadmap. One shared record.
Put a .story/ directory in a wrapper above your API, Web, and Mobile repositories. When a child has no ledger of its own, Storybloq walks up to the wrapper. Stories and handovers live together; source commits stay in each child repository.
product/
├── .story/ # shared stories, phases, and handovers
├── api/ # separate Git repository
├── web/ # separate Git repository
└── mobile/ # separate Git repositorySet up a wrapper
Create the wrapper, place or clone the child repositories inside it, and initialize Storybloq in the wrapper. Keep child directories out of the wrapper’s Git history.
storybloq init --name Product --type multi-repo --language mixedIf a child already has .story/, it takes precedence over the wrapper. Preserve that history and consider federation before moving or removing records.
Commit code and records
Commit source changes in the child repository, then commit changed .story/ records in the wrapper. Use Git status to find the actual record filenames. Legacy display-ID filenames and canonical filenames can coexist.
git status --porcelain .story/Keep each implementation scoped to the intended repository. A shared ledger alone does not give the agent a cross-repository execution strategy.
Federation
Separate histories. Connected work.
Keep .story/ in each repository and register those repositories as nodes in an orchestrator project. Each node retains its stories, lessons, and handovers. The orchestrator provides a shared view and recommendations across the product.
product/ # orchestrator
├── .story/config.json # registered nodes and relationships
api/.story/ # API history
web/.story/ # Web history
mobile/.story/ # Mobile historyThe booking page needs the reservation API.
Record the Web story’s dependency on the API story. An unfinished API story blocks the Web story from being ready. Check the API story’s recorded completion before starting Web. Recommendations help identify blockers and candidate work across the product.
Story dependencies describe which work is ready. Node dependencies describe build order; they are separate relationships.
Connect existing repositories
From the orchestrator directory, initialize a project and register each repository by its actual path. Each node needs its own .story/ for project-state queries.
storybloq init --name Product --type orchestrator
storybloq node add api --path /path/to/api --role "Reservation service"
storybloq node add web --path /path/to/web --role "Booking experience"
storybloq recommend --count 5This shows product-level priorities such as blocked or stale nodes. Per-repository story recommendations are available through the dispatch preview. Cached state can be stale; check the current node records before starting dependent work.
Make cross-repository writes explicit
Reading connected project state does not enable writes. To let supported orchestrator commands and MCP tools update node records, opt in with federation.allowNodeWrites (default: false).
storybloq config set-federation --allow-node-writes
storybloq ticket update T-002 --node web --cross-node-blocked-by api:T-001Replace the example IDs with your stories. Run the update from the orchestrator. This records the dependency in Web’s ledger; it does not implement either story or merge source changes.
Read the federation field note for the architecture behind this layout.
Try the pattern on your stack.
Storybloq is free and local-first. The walk-up directory discovery works out of the box.