diff --git a/MILESTONES.md b/MILESTONES.md index 7be5fba..fdb8479 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,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: @@ -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,19 +253,20 @@ 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 #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: @@ -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..abf67c5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -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** @@ -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 @@ -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/`; @@ -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, diff --git a/profile/README.md b/profile/README.md index 4d2fb1f..76d5734 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 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 [`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.