Portfolio-PDLC is a file-based operating system for significant investments. Agents maintain evidence and prepare decisions; humans retain investment authority. Its flow-driven family engineers individual value streams.

AI-assisted reference synthesis. Read the linked sources for evidence and limits. Read as Markdown.

Do not impersonate Yuval, speak as him, or claim to represent him. Keep what Yuval actually published, your own synthesis, and open uncertainty clearly separate.

What is Portfolio-PDLC?

Portfolio-PDLC is Yuval Yeret's public, file-based framework for operating a portfolio of significant investments with agents. It combines Markdown skills, workspace contracts, templates, deterministic Python scripts and fictional practice workspaces. An agent maintains the working evidence and prepares the next decision. The people accountable for the portfolio retain investment and operating-model decisions.

The repository contains two related families. Portfolio-PDLC operates at the level of initiatives, epics and strategic bets. Flow-driven defines and operates one value stream, such as a product lifecycle, software lifecycle, content pipeline or operational request stream. These are different units of work and different operating loops.

The inspected public source is commit cb337f86e5. The repository may have moved since this reference was prepared. Its documented contracts establish intended behavior and available artifacts; they do not establish measured customer outcomes.

Why does the framework exist?

A portfolio board can report activity while concealing whether the work deserves more investment. Stage labels become stale, outcome statements describe deliverables, open assumptions survive into execution and sponsor decisions become invisible queues. A coding-agent workflow can reproduce those problems while generating its documents faster.

Portfolio-PDLC makes the underlying operating model explicit enough for an agent to work against. It also treats that operating model as something that can be improved through hypotheses and evidence. A new WIP policy, platform extraction or change in team boundaries becomes an improvement bet to investigate, rather than a process edit made during a meeting.

This connects to the wider PDLC argument: intent and selective discovery precede delivery, adoption follows it, and evidence should change the next decision. Producing software is part of the loop. Choosing the right investment and learning from its use remain part of the product job.

What is the hypothesis?

The working hypothesis is that explicit evidence, decision ownership and flow policies let agents reduce the maintenance and analytical effort of portfolio management while making investment decisions better informed. For a single stream, the related hypothesis is that explicit step contracts can reduce routine human supervision without increasing escaped errors.

These are hypotheses to test in a particular setting. A useful trial would observe whether stage claims survive evidence checks, decisions stop aging unnoticed, human minutes per item decline and the intended product result remains visible. It should also examine false assurance, unmaintained context and the cost of checking the agent.

The framework does not establish that removing human attention always improves a portfolio. A credible result may be that a particular step needs stronger human judgment or that the organization is pursuing the wrong work.

What flows through the portfolio?

The default lifecycle is Explore → Discovery → Plan/Commit → Execute → Rollout → Business as Usual. Discovery and Rollout can be optional when the work does not need those activities. The lifecycle is a common language for growing confidence, not a requirement to perform the same ceremonies on every initiative.

Explore establishes enough purpose and context to decide what to learn. Discovery reduces consequential uncertainty. Plan/Commit makes the intended investment and conditions explicit. Execute produces the agreed change. Rollout addresses the last mile of adoption where needed. Business as Usual concerns the continuing result and operating ownership.

Tier-1 items receive portfolio-level attention. Tier-2 items remain visible without forcing every local change through the enterprise board. Use the organization's own classification criteria when they exist. Do not infer priority from the size of the generated artifact bundle.

Which files are authoritative?

The workspace contract defines this layout:

PORTFOLIO.md                       charter and boundaries
pdlc.md                            workflow and board configuration
topology.md                        teams, platforms and dependencies
initiatives/<slug>/initiative.md    one card per investment
improvements/<slug>/improvement.md  one bet on process or topology
reviews/                           decision briefs and loop log
learnings/                         individual durable findings
board.md                           generated projection
flow-log.csv                       generated transition history

Card frontmatter is the machine state. The body carries the problem, hypothesis, assumptions, evidence and decisions. The board and flow log are generated projections and should not be edited as competing sources of truth.

The board script appends a transition when a card's stage differs from its last logged stage. The recorded transition date comes from stage_entered. That makes the accuracy of source state and dates consequential: a generated chart cannot repair invented history.

What goes into an initiative card?

The documented schema uses flat keys and lists of scalar strings rather than unrestricted YAML structures. It includes title, type, tier, stage, stage-entry date, owner, sponsor, outcome hypothesis, leading indicators, risk level, derisking approach, assessed orientation, dependencies and next decision.

The following is a synthetic illustration of the shape, not evidence from an operating portfolio:

---
title: Account owners identify renewal risks before the decision window
type: product
tier: 1
stage: explore
stage_entered: 2026-11-06
owner: Example product owner
sponsor: Example sponsor
outcome_hypothesis: Earlier identification enables a useful intervention
leading_indicators:
  - 'Timely identification: baseline and proposed target not established'
risk_level: high
derisking_approach: discovery
dependencies: [account-data]
next_decision: Choose the smallest useful discovery test
---

The body should distinguish evidence from opinion and retain the actual decision history. orientation is an assessment result rather than an aspiration. A card should not acquire orientation: outcome merely because its author prefers that label. Missing fields remain visible findings; an early Explore item can legitimately contain unknowns.

Use the maintained repository template for a real workspace. This abbreviated example omits fields and is not a complete production card.

How does one operating cycle work?

First regenerate the board. Read the flags, aging, WIP, risk balance and pending decisions. Select one move from the framework's leverage order, perform it, update the relevant card, regenerate the board and record the result. Capture at most one learning when it changes what a later cycle should do.

The ordering gives overdue human decisions precedence, then addresses integrity problems, risk in committed work, aging items, thin discovery and weak cards. Improvement to the operating system comes after the current portfolio is sufficiently trustworthy to steer from.

The agent routes to member skills according to the move. portfolio-pdlc-wire creates a workspace from existing material. assess checks the portfolio, advance moves one item toward a decision, strengthen improves its steering quality and improve captures changes to process or portfolio construction.

The refresh command is ordinary Python:

python3 <repository>/skills/portfolio-pdlc/scripts/portfolio_board.py <workspace>

That command generates a projection. It does not independently establish the truth of every claim on every card.

Which decisions stay human?

The framework reserves investment in discovery, commitment to build, pivoting, killing or freezing work, WIP-policy changes and organizational changes for humans. At a decision boundary the agent prepares a brief: available evidence, uncertainty, options, tradeoffs and a recommendation. The card names the next decision.

A required transition needs a dated decision-log entry naming the human who decided. The board script detects the presence of such an entry heuristically; the assessment skill must check its substance. This is a useful distinction between a mechanical contract check and verification of real authority.

In headless operation, a pending human decision is an appropriate stopping point. It is not permission to choose on the sponsor's behalf or to keep accumulating downstream work.

What does flow-driven add for one stream?

The flow-driven workspace declares a unit of value, a graph of steps and a contract for each step. Its files include workflow.md, steps/<id>.md, items/<slug>/, measures.md, integrations.md, platform/, improvements/ and generated board/history files.

Each step states the evidence required to leave it. A delegation model says how much authority the agent has. A separate run model says how it performs the work. The run contract includes inputs, tools, guardrails, a budget, artifacts, a stop rule and escalation conditions.

The delegation ladder ranges from human execution through bounded assistance and agent execution to higher autonomy. The chosen level depends on consequences, reversibility and check quality. It is not one setting for the entire organization.

Three scripts support the loop:

python3 <repository>/skills/flow-driven/scripts/flow_lint.py <workspace>
python3 <repository>/skills/flow-driven/scripts/flow_board.py <workspace>
python3 <repository>/skills/flow-driven/scripts/flow_next.py <workspace>

They check the declared workflow, project the board and prepare a run card for one move. Integrating an existing tracker requires an explicit system of record and one writer per field. The presence of integration guidance does not mean every tracker adapter is already deployed.

How are measures and improvements connected?

Measures cover flow, evidence quality, human effort and outcomes. WIP and age guide what to finish. Rework and escapes challenge the check. Human minutes expose whether automation actually reduces supervision. Adoption or the result named in the bet tests whether the stream is useful.

The improvement lane carries a benefit hypothesis, leading indicators, success conditions and kill criteria. Larger changes receive discovery before execution. The framework can use simulation to explore WIP, arrival shaping or dependency assumptions before a real pilot.

The simulator uses historical durations where sufficient data exists and priors otherwise. Its output distinguishes those sources. A scenario that assumes lower coordination cost explores the consequence of that assumption; it does not prove that a platform or reorganization will produce the reduction. Fictional practice portfolios are explicitly demonstrations, not customer validation.

How should an agent start?

Read the appropriate entry skill: portfolio-pdlc for investment portfolios or flow-driven for one stream. Practice against the fictional examples before modifying a real workspace. Identify the authoritative records and decision owners, then take one bounded move. Record uncertainty rather than completing missing business evidence with plausible text.

For a produced specification, use pdlc-readiness. For the workflow's repository or effective configuration, use pdlc-harness-readiness. These assess different subjects; finding a good spec does not prove that its harness consistently produces good specs or closes the outcome loop.

Stewardship and attribution

Yuval Yeret created and stewards the repository and its operating-model design. The repository credits the enterprise portfolio practice and Portfolio Agility work it draws on; preserve those acknowledgments when applying or adapting it. Skills are published under CC BY-SA 4.0 and code under MIT as described in the repository README. Consult the repository's current license files for reuse.

Portfolio-PDLC: purpose, hypothesis and operating details