Skip to content

docs: wire define-product layer #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aryeko merged 3 commits into from
Jun 30, 2026
Merged

docs: wire define-product layer #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4f90c54
docs: wire define-product layer
aryeko Jun 30, 2026
bb882c8
docs: clarify planning contract dependencies
aryeko Jun 30, 2026
e3c7d68
docs: promote M4 after product contract
aryeko Jun 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 22 additions & 19 deletions MILESTONES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ before any design or implementation:

### M1: Jig Contract Design v0

- State: current
- State: done
- Outcome: Enable Planning and Learning to design against Jig without waiting for Jig
implementation by sketching the high-level shape of Jig's execution-plan and run-record
seams — enough to orient downstream design, not a frozen schema.
Expand Down Expand Up @@ -175,12 +175,13 @@ before any design or implementation:
- Fails if it tries to freeze a field-level schema now instead of leaving the v0 shape room
to refine through design and implementation.
- Evidence when landed:
- Jig PR merged with design docs and `pnpm check` green.
- `ROADMAP.md` seam status updated from "to be authored" to the v0 high-level design docs.
- `jig` PR #6 merged with the execution-plan and observability contract docs; `main`
`pnpm check` was green.
- `ROADMAP.md` seam status links the v0 high-level design docs.

### M2: Technical-Design Handoff Contract

- State: current
- State: done
- Outcome: Enable the Planning layer to consume technical designs consistently by making the
design document format explicit as a downstream contract.
- Why now: Planning needs a stable design input shape as much as it needs Jig's output plan
Expand Down Expand Up @@ -212,18 +213,19 @@ before any design or implementation:
sections.
- Fails if enforcement guidance can pass without seeded violations or concrete examples.
- Evidence when landed:
- `technical-design` PR merged with `pnpm check` green.
- `technical-design` PR #7 merged with the handoff contract, template, fixture, and
review guidance; `main` `pnpm check` was green.
- `ROADMAP.md` links the exact handoff contract.

### M3: PRD and Acceptance-Criteria Contract

- State: current
- State: done
- Outcome: Enable Product, Design, and Planning layers to cite stable product intent through
ID'd acceptance criteria instead of relying on unstructured product prose.
- Why now: Planning and technical design both need durable "what and why" references before
work decomposes into implementation plans.
- Primary owner: future Product layer
- Participating repos: future Product layer, `technical-design`, future Planning layer,
- Primary owner: `define-product`
- Participating repos: `define-product`, `technical-design`, future Planning layer,
`.github`
- Owned seam or artifact: PRD / acceptance-criteria-ID format
- Entry criteria:
Expand All @@ -239,31 +241,32 @@ before any design or implementation:
implementation internals.
- The initial repo or artifact home for the Product layer is chosen deliberately.
- Artifacts:
- Product-layer product brief
- PRD / acceptance-criteria format
- Example PRD fixture
- `define-product/docs/product/README.md`
- `define-product/docs/product/prd-contract.md`
- `define-product/docs/product/examples/minimal-prd.md`
- Repo planning handoff:
- The Product layer derives its own product -> design -> implementation plan.
- `define-product` derives its own product -> design -> implementation plan after M3 lands.
- `technical-design` and Planning treat the format as a cited input contract.
- Risks / kill assumptions:
- Fails if acceptance criteria become delivery tasks instead of product-owned outcome
criteria.
- Fails if the Product layer duplicates `technical-design` or Planning responsibilities.
- Fails if ID stability is not specified.
- Evidence when landed:
- Product-layer repo or artifact PR merged with checks green.
- `ROADMAP.md` updates the PRD seam status and reference link.
- `define-product` PR #1 merged with the PRD contract docs and `pnpm check` green.
- `.github` PR #11 merged with `ROADMAP.md`, `MILESTONES.md`, and profile links updated to the
exact Product-layer contract.

### M4: Planning Layer Seed

- State: proposed
- State: current
- Outcome: Enable an approved technical design to become a Jig-ready execution plan without
re-deciding product or design scope.
- Why now: Once Jig's plan shape is drafted and the design handoff is pinned, Planning can be designed
against contracts rather than against another repo's internals.
- Primary owner: future Planning layer
- Participating repos: future Planning layer, `jig`, `technical-design`, future Product
layer, `.github`
- Participating repos: future Planning layer, `jig`, `technical-design`, `define-product`,
`.github`
- Owned seam or artifact: None new. Planning consumes Product and Technical Design contracts
and produces Jig execution plans.
- Entry criteria:
Expand Down Expand Up @@ -341,8 +344,8 @@ before any design or implementation:
- Why now: Learning should consume real run records, but its product/design can be shaped as
soon as Jig's record contract and sample records exist.
- Primary owner: future Learning loop
- Participating repos: future Learning loop, `jig`, `technical-design`, future Product
layer, future Planning layer, `.github`
- Participating repos: future Learning loop, `jig`, `technical-design`, `define-product`,
future Planning layer, `.github`
- Owned seam or artifact: None new. Learning consumes Jig observability / event records.
- Entry criteria:
- M1 event-record shape v0 is drafted and agreed.
Expand Down
59 changes: 33 additions & 26 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,13 @@ uses to derive its local plan.
```text
PRODUCT ---------> DESIGN ----------> PLANNING --------> DELIVERY --------> LEARNING
define / PRD technical-design design -> plan jig (run) feedback loop
[planned] [built] [planned] [early] [planned]
[seeded] [built] [planned] [early] [planned]
```

Each stage produces a **durable, structured artifact** that is the next stage's input. Two
stages already exist as repos (`technical-design`, `jig`); three are planned (Product,
Planning, Learning). `.github` is org infrastructure, not a lifecycle stage.
Each stage produces a **durable, structured artifact** that is the next stage's input. Three
stages already exist as repos (`define-product`, `technical-design`, `jig`); two are planned
(Planning, Learning). `.github` is org infrastructure, not a lifecycle stage. Of the existing
repos, `define-product` is seeded, `technical-design` is built, and `jig` is early.

> The org `profile/README.md` shows a **four-stage** suite spine that folds Planning under the
> delivery handoff (`plan -> jig (run)`). This roadmap breaks Planning out as its **own layer**
Expand All @@ -39,14 +40,14 @@ Planning, Learning). `.github` is org infrastructure, not a lifecycle stage.
The layers do **not** form a build chain where each must wait for the previous. They are
coupled only by a small set of **shared contracts (seams)**. Pin down each seam's shape early
and every layer can be designed in parallel against the contract, not against another layer's
internals. Most seams are owned by the two layers that already exist.
internals. The currently pinned seams are owned by existing layer repos.

| Seam (shared artifact) | Owner | Consumers | Status |
| --------------------------------------------------------- | ------------------ | ------------------------------ | ---------------------------------------------------------------- |
| **Execution-plan schema** — Jig's one hard input boundary | `jig` | Planning layer produces to it | v0 shape: `jig/docs/design/execution-plan-contract-v0.md` |
| **Observability / event records** — durable run output | `jig` | Learning loop consumes | v0 shape: `jig/docs/design/observability-records-contract-v0.md` |
| **Technical-design document format** | `technical-design` | Planning layer consumes | Exists (`technical-design/docs/design/`) |
| **PRD / ID'd acceptance-criteria format** | Product layer | Design + Planning cite the IDs | Planned (v0.7 `define-product` is prior art) |
| Seam (shared artifact) | Owner | Consumers | Status |
| --------------------------------------------------------- | ------------------ | ------------------------------ | ------------------------------------------------------------------------------- |
| **Execution-plan schema** — Jig's one hard input boundary | `jig` | Planning layer produces to it | v0 shape: `jig/docs/design/execution-plan-contract-v0.md` |
| **Observability / event records** — durable run output | `jig` | Learning loop consumes | v0 shape: `jig/docs/design/observability-records-contract-v0.md` |
| **Technical-design document format** | `technical-design` | Planning layer consumes | v0 handoff: `technical-design/docs/design/technical-design-handoff-contract.md` |
| **PRD / ID'd acceptance-criteria format** | `define-product` | Design + Planning cite the IDs | v0 contract: `define-product/docs/product/prd-contract.md` |

**Sequencing rule of thumb:** the highest-leverage early work is authoring Jig's two seams
(execution-plan schema, observability records), because two downstream layers wait on their
Expand Down Expand Up @@ -107,27 +108,31 @@ parallel. The current sequence is tracked in [`MILESTONES.md`](./MILESTONES.md).
- Legacy gate/CI mechanics (reference only): `docs/engineering/`.
- Legacy implementation sequencing (reference only): `docs/implementation/` (epic/domain DAGs).

### Product layer — define-product / PRD `[planned]`
### define-product — Product layer `[seeded]`

- **Role:** help an owner produce a PRD with ID'd acceptance criteria the downstream layers
reference.
- **Owns the seam:** the PRD / acceptance-criteria-ID format.
- **Depends on:** nothing upstream. Sits at the head of the lifecycle.
- **Next step (when picked up):** define product -> design its own skills/artifacts ->
implement. Can start **now**, in parallel; its only outward contract is the
acceptance-criteria-ID format that Design and Planning cite.
- **References:** legacy `docs/product/supporting-products/define-product.md`; v0.7 skill
- **Next step:** keep future Product-layer design and implementation derived from its own product
docs. Its outward contract is the acceptance-criteria-ID format that Design and Planning cite.
- **References:** its own
[`docs/product/prd-contract.md`](https://github.com/agentic-workflow-kit/define-product/blob/main/docs/product/prd-contract.md)
and
[`docs/product/examples/minimal-prd.md`](https://github.com/agentic-workflow-kit/define-product/blob/main/docs/product/examples/minimal-prd.md);
legacy `docs/product/supporting-products/define-product.md`; v0.7 skill
`agentic-workflow-kit:define-product`.

### Planning layer — design -> plan `[planned]`

- **Role:** decompose a technical design into a Jig-ready execution plan in the expected schema.
- **Owns the seam:** none new — it **produces to** Jig's execution-plan schema and **consumes**
the technical-design document format.
- **Depends on (contract, not internals):** Jig's execution-plan schema; technical-design's
document format. Both owners already exist — define those two seam shapes and Planning can be
designed in parallel.
- **Next step (when picked up):** define product -> design -> implement, against the two seam
the Product PRD / acceptance-criteria-ID contract plus the technical-design document format.
- **Depends on (contract, not internals):** `define-product`'s PRD / acceptance-criteria-ID
contract, Jig's execution-plan schema, and technical-design's document format. Those owners
already exist; once the three seam shapes are pinned, Planning can be designed against contracts
rather than upstream internals.
- **Next step (when picked up):** define product -> design -> implement, against the three seam
contracts above.
- **References:** legacy `docs/product/supporting-products/design-to-plan.md`; legacy
`docs/implementation-authoring/delivery-pipeline/` and `docs/implementation-authoring/authoring-standard/`;
Expand All @@ -153,13 +158,15 @@ parallel. The current sequence is tracked in [`MILESTONES.md`](./MILESTONES.md).
1. **`jig` design** — author `docs/design/`, leading with the two seams (execution-plan schema,
observability records). Highest leverage: unblocks Planning and Learning by shape.
2. **`technical-design` hardening** — fully independent.
3. **Product layer** — fully independent; can be picked up and designed today.
4. **Planning layer** — designable in parallel once Jig's execution-plan schema and
technical-design's document format are pinned (both owners exist).
3. **`define-product`** — product contract is seeded; future design and implementation can derive
from its own product docs without blocking M4.
4. **Planning layer** — designable once the Product PRD / acceptance-criteria-ID contract, Jig's
execution-plan schema, and technical-design's document format are pinned (all owners exist).
5. **Learning loop** — designable in parallel once Jig's records seam is pinned.

The only true ordering constraint is _contract-shape_, not _implementation_: Planning and
Learning need the **shape** of Jig's seams, not finished Jig code.
The only true ordering constraint is _contract-shape_, not _implementation_: Planning needs the
**shape** of Product, Technical Design, and Jig input/output seams, and Learning needs the
**shape** of Jig's records seam, not finished upstream implementations.

Repo-level plans should derive from the active milestone rather than expanding this roadmap into
a centralized backlog. The repo owner records its local plan in that repo, including what it owns,
Expand Down
Loading