From 4f90c548cddce101ae837627eeb4e8d78ee4dd5c Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Tue, 30 Jun 2026 22:55:15 +0300 Subject: [PATCH 1/3] docs: wire define-product layer --- MILESTONES.md | 37 ++++++++++++++++++++----------------- ROADMAP.md | 32 ++++++++++++++++++-------------- profile/README.md | 40 ++++++++++++++++++++-------------------- 3 files changed, 58 insertions(+), 51 deletions(-) diff --git a/MILESTONES.md b/MILESTONES.md index 7be5fba..2a4a056 100644 --- a/MILESTONES.md +++ b/MILESTONES.md @@ -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. @@ -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 @@ -212,7 +213,8 @@ 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 @@ -222,8 +224,8 @@ before any design or implementation: 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: @@ -239,11 +241,11 @@ 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 @@ -251,8 +253,9 @@ before any design or implementation: - 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 merged with the PRD contract docs and `pnpm check` green. + - `.github` PR merged with `ROADMAP.md`, `MILESTONES.md`, and profile links updated to the + exact Product-layer contract. ### M4: Planning Layer Seed @@ -262,8 +265,8 @@ before any design or implementation: - 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: @@ -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. diff --git a/ROADMAP.md b/ROADMAP.md index 531c2a9..1c9daf7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -20,12 +20,12 @@ 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. +stages already exist as repos (`define-product`, `technical-design`, `jig`); two are planned +(Planning, Learning). `.github` is org infrastructure, not a lifecycle stage. > 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** @@ -41,12 +41,12 @@ coupled only by a small set of **shared contracts (seams)**. Pin down each seam' 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. -| 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 @@ -107,16 +107,20 @@ 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 +- **Next step:** land the M3 product contract, then 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:** legacy `docs/product/supporting-products/define-product.md`; v0.7 skill +- **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]` @@ -153,7 +157,7 @@ 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. +3. **`define-product`** — M3 product contract bootstrap is current and independent. 4. **Planning layer** — designable in parallel once Jig's execution-plan schema and technical-design's document format are pinned (both owners exist). 5. **Learning loop** — designable in parallel once Jig's records seam is pinned. diff --git a/profile/README.md b/profile/README.md index 4d2fb1f..528c7ea 100644 --- a/profile/README.md +++ b/profile/README.md @@ -1,15 +1,15 @@ # agentic-workflow-kit > A polyrepo family for an agentic software-development lifecycle: product intent -> technical -> design -> delivery -> learning. +> design -> planning -> delivery -> learning. `agentic-workflow-kit` is the public umbrella for standalone, composable repositories. Each repo is independently useful, but together they form a lifecycle for turning software intent into designed, implemented, reviewed, and improved systems. -This organization carries the full lifecycle as standalone products — from product definition through -technical design to delivery. **Jig**, the delivery/execution engine, is the suite's main product and -lives here. +This organization carries the full lifecycle as standalone products, from product definition through +technical design, planning, delivery, and learning. **Jig**, the delivery/execution engine, is the +suite's main runtime product and lives here. ## Why Polyrepo @@ -22,20 +22,19 @@ repo can stay focused without inventing its own vocabulary. ## Repositories -| Repo | Role | Status | -| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | -| [`technical-design`](https://github.com/agentic-workflow-kit/technical-design) | Design layer: frame, author, review-loop, enforce, and orchestrate technical designs. | Ready locally; GitHub shell prepared | -| [`jig`](https://github.com/agentic-workflow-kit/jig) | Delivery / execution engine: runs an approved plan under policy into reviewed, landed work, or a deliberate stop. The tool you run (`@agentic-workflow-kit/jig`). | Early; product layer drafted, design/impl next | -| Product layer | Define-product and PRD authoring upstream of design. | Planned | -| Planning layer | Decompose design into the execution plan Jig runs. | Planned | -| Learning loop | Capture run outcomes and feed them back into future work. | Planned | +| Repo | Role | Status | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| [`define-product`](https://github.com/agentic-workflow-kit/define-product) | Product layer: PRD authoring and stable, ID'd acceptance criteria upstream of design. | Seeded; M3 contract bootstrap | +| [`technical-design`](https://github.com/agentic-workflow-kit/technical-design) | Design layer: frame, author, review-loop, enforce, and orchestrate technical designs. | Built; planning handoff contract pinned | +| [`jig`](https://github.com/agentic-workflow-kit/jig) | Delivery / execution engine: runs an approved plan under policy into reviewed, landed work, or a deliberate stop. The tool you run (`@agentic-workflow-kit/jig`). | Early; product and contract design seeded | +| Planning layer | Decompose design into the execution plan Jig runs. | Planned | +| Learning loop | Capture run outcomes and feed them back into future work. | Planned | ## Lifecycle ```text -PRODUCT ---------> DESIGN ----------> DELIVERY --------> LEARNING -define / PRD technical-design plan -> jig (run) feedback loop - repo this org back into layers +PRODUCT ---------> DESIGN ----------> PLANNING --------> DELIVERY --------> LEARNING +define / PRD technical-design design -> plan jig (run) feedback loop ``` The repos are meant to compose without becoming tightly coupled. Each should have a crisp purpose, @@ -55,10 +54,11 @@ The shared vocabulary is intentionally small: ## Current Focus -The first design-stage layer is `technical-design`: a set of AI skills for right-sized architecture, -reviewable decisions, and enforceable boundaries. `jig`, the suite's execution engine, now has its -product layer drafted; its engineering design and implementation are being built next. +The current org focus is M3: bootstrapping `define-product` with the PRD and acceptance-criteria +contract that Technical Design and Planning cite. This is Product-layer work, not Planning or +design-to-plan mechanics. -Start with [`technical-design`](https://github.com/agentic-workflow-kit/technical-design) for the -design-stage skills, or follow [`jig`](https://github.com/agentic-workflow-kit/jig) — the execution -engine — as it takes shape. +Start with [`define-product`](https://github.com/agentic-workflow-kit/define-product) for product +intent and acceptance-criteria IDs, [`technical-design`](https://github.com/agentic-workflow-kit/technical-design) +for design-stage skills, or [`jig`](https://github.com/agentic-workflow-kit/jig) for the execution +engine. From bb882c856eac9acf3969dca9a78000045fcfced9 Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Tue, 30 Jun 2026 23:00:29 +0300 Subject: [PATCH 2/3] docs: clarify planning contract dependencies --- ROADMAP.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 1c9daf7..2c6054c 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -23,9 +23,10 @@ define / PRD technical-design design -> plan jig (run) feed [seeded] [built] [planned] [early] [planned] ``` -Each stage produces a **durable, structured artifact** that is the next stage's input. Two +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. +(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** @@ -39,7 +40,7 @@ stages already exist as repos (`define-product`, `technical-design`, `jig`); two 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 | | --------------------------------------------------------- | ------------------ | ------------------------------ | ------------------------------------------------------------------------------- | @@ -127,11 +128,12 @@ parallel. The current sequence is tracked in [`MILESTONES.md`](./MILESTONES.md). - **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/`; @@ -158,12 +160,13 @@ parallel. The current sequence is tracked in [`MILESTONES.md`](./MILESTONES.md). observability records). Highest leverage: unblocks Planning and Learning by shape. 2. **`technical-design` hardening** — fully independent. 3. **`define-product`** — M3 product contract bootstrap is current and independent. -4. **Planning layer** — designable in parallel once Jig's execution-plan schema and - technical-design's document format are pinned (both owners exist). +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, From e3c7d68a75b764366d93fdf9e29fbb37e27db933 Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Tue, 30 Jun 2026 23:04:53 +0300 Subject: [PATCH 3/3] docs: promote M4 after product contract --- MILESTONES.md | 8 ++++---- ROADMAP.md | 8 ++++---- profile/README.md | 6 +++--- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/MILESTONES.md b/MILESTONES.md index 2a4a056..fdb8479 100644 --- a/MILESTONES.md +++ b/MILESTONES.md @@ -219,7 +219,7 @@ before any design or implementation: ### 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 @@ -253,13 +253,13 @@ before any design or implementation: - Fails if the Product layer duplicates `technical-design` or Planning responsibilities. - Fails if ID stability is not specified. - Evidence when landed: - - `define-product` PR merged with the PRD contract docs and `pnpm check` green. - - `.github` PR merged with `ROADMAP.md`, `MILESTONES.md`, and profile links updated to the + - `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 diff --git a/ROADMAP.md b/ROADMAP.md index 2c6054c..abf67c5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -114,9 +114,8 @@ parallel. The current sequence is tracked in [`MILESTONES.md`](./MILESTONES.md). reference. - **Owns the seam:** the PRD / acceptance-criteria-ID format. - **Depends on:** nothing upstream. Sits at the head of the lifecycle. -- **Next step:** land the M3 product contract, then 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. +- **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 @@ -159,7 +158,8 @@ 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. **`define-product`** — M3 product contract bootstrap is current and independent. +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. diff --git a/profile/README.md b/profile/README.md index 528c7ea..76d5734 100644 --- a/profile/README.md +++ b/profile/README.md @@ -54,9 +54,9 @@ The shared vocabulary is intentionally small: ## Current Focus -The current org focus is M3: bootstrapping `define-product` with the PRD and acceptance-criteria -contract that Technical Design and Planning cite. This is Product-layer work, not Planning or -design-to-plan mechanics. +The current org focus is M4: seeding the Planning layer so approved technical designs can become +Jig-ready execution plans without re-deciding product or design scope. M3 seeded `define-product` +with the PRD and acceptance-criteria contract that Technical Design and Planning cite. Start with [`define-product`](https://github.com/agentic-workflow-kit/define-product) for product intent and acceptance-criteria IDs, [`technical-design`](https://github.com/agentic-workflow-kit/technical-design)