prodc
Product management as code: user needs in YAML, each traced to the evidence a real user gave and the test that proves it is delivered. For teams that keep product work in the repo, next to the code.
prodc reads plain YAML files and your test suite and shows you the gaps. It does not call a model, host a UI, or replace your tracker. Two rules carry it:
- A need with no evidence is an opinion. Write down who asked (an interview quote, a ticket, an email) or prodc flags the need as an opinion.
- "Done" is a claim your tests back. You never mark a need delivered. You attach a proof
(a locator into your test suite) and
prodc statusresolves it: DELIVERED, PENDING, HOLE, or BROKEN. The state is read from the repo, not remembered from a standup.
Why prodc
- Versus Jira, Linear, other trackers. A tracker records work items and a status someone set
by hand. prodc records needs and computes their status from the tests. No assignees, sprints,
comments, or notifications. Keep the tracker for the work; keep prodc for "did a real user ask
for this, and does a test prove it?" They connect at the edges: a source can be a ticket
locator (checked read-only against GitLab with
[sources.<name>] kind = "gitlab"), a proof can be any script (kind = "command"), andprodc syncfires a hook when a need changes state. - Versus a PRD in Notion or a wiki. A document says what should be true; nothing checks it
later. prodc's files are validated on every load, linted in CI, and reviewed in merge requests
like code. "Is this done?" is answered by
prodc show N-1. - Versus plain YAML in the repo. You could keep this structure by hand. prodc adds the schema, proof resolution against real test suites, the evidence ladder, the lint, and write-back commands that keep the files consistent.
What it does not do. It does not run your tests, call an LLM, or ping a tracker on its own. It does not model the full discovery loop (opportunity-solution trees, parallel solution testing); it records needs, the evidence under them, and the decisions taken on them.
Install
pip install prodc # or: uv add prodc
Python 3.12+. The only runtime dependency is PyYAML.
Quickstart
Three files: where prodc looks, what people need, and a test you have probably already written.
prodc.toml
[prodc]
files = ["needs/*.yaml"]
[proofs.web]
kind = "gherkin"
paths = ["features/*.feature"]
delivered = ["@implemented"]
pending = ["@pending"]
needs/jordan.yaml
who: jordan
needs:
- id: N-1
text: "see which orders are past due at a glance"
must: true
sources:
- kind: primary
who: Jordan
date: 2026-09-20
quote: "I lose the past-due ones in the list"
proofs:
- "web:orders.feature#Past due orders are highlighted"
- id: N-2
text: "export the day's delivery run sheet"
sources:
- kind: secondary
locator: issues.md#N-2
date: 2026-09-21
- id: N-3
text: "implement a settings page"
features/orders.feature
Feature: Orders board
@implemented
Scenario: Past due orders are highlighted
Given an order whose due date has passed
When I open the orders board
Then the order is highlighted as past due
Run the board (output trimmed; the real one also carries a legend and phrasing hints):
$ prodc status
gaps: 2 HOLE · 1 opinion coverage 1/3 (33%)
jordan 1 DELIVERED 2 HOLE
provenance: 1 primary · 1 secondary · 0 assumption · 1 opinion
N-2 HOLE export the day's delivery run sheet secondary
N-3 HOLE implement a settings page opinion
⚠ text may be a solution in disguise (starts with 'implement')
!! N-1 DELIVERED* 1/1 see which orders are past due at a glance primary:Jordan
⚠ DELIVERED on an unattested proof link — warrant not reviewed
- N-1 is DELIVERED because a tagged scenario proves it (
*= declared by tag, no test results loaded yet). - N-2 is a HOLE: evidence, but no proof.
- N-3 is an opinion: neither.
Close the loop from the command line. Each write command rewrites one YAML file, re-validates the whole model, and prints the diff.
# trace the opinion to evidence
prodc capture N-3 --kind primary --who Jordan --date 2026-10-01 \
--quote "I keep changing the printer in three places"
# add the scenario to your suite, tagged @pending until it is green:
# @pending
# Scenario: Export the run sheet
# then point the need at it:
prodc set N-2 proofs+="web:orders.feature#Export the run sheet"
prodc status # gaps: 1 PENDING · 1 HOLE — the scenario exists, so N-2 is PENDING, not BROKEN
# (skip writing the scenario and the proof points at nothing: BROKEN, lint exits 1)
prodc lint # CI gate: exit 1 on a BROKEN proof or a must-have with no evidence
Rename a scenario without updating the need and the proof turns BROKEN; prodc lint exits 1.
That is the whole idea: the board cannot drift from the code.
Key features
- Evidence ladder. A source is
primary(the user's own words),secondary(a report, a ticket, an internal doc), orassumption(a guess). With neither primary nor secondary, the need is an opinion:lintfails a must-have opinion,status --strictfails on any. - Proofs resolve against the repo. Adapters for Gherkin scenarios and tags, pytest node ids,
file existence, human sign-off, prototypes, citations, eval metric gates, external results files,
and a generic
commandhook. Feed it cucumber-json or junit XML and declared states become real. - Five states, honest semantics. DELIVERED, PENDING, HOLE, BROKEN, UNRESOLVED. A HOLE is never a failure; BROKEN always is; a proof in an absent sibling repo is UNRESOLVED, not BROKEN.
- Flows. A need with
childrenrolls them up, withseamproofs for the behaviour between steps. Any BROKEN child breaks the flow; a flow is DELIVERED only when every child and seam is green. - Machine-checked roll-up.
tests/test_models.pybuilds a musil model of the lifecycle and explores every reachable state against the real resolver, so the documented invariants cannot drift from the code. - Write-back that respects your files.
set,capture,accept,attest,withdraw,addsplice one need's block back into the original YAML, keeping other comments. All take--dry-runand--expect-sha. - Boards for humans.
status,show,brief,plan,report --format html(a self-contained interactive viewer),portfolio, anddiffagainst a snapshot. The read commands take--json; exit codes are fixed (0 ok, 1 gate failed, 2 config or load error). - Coding-agent playbook.
prodc agent >> AGENTS.mdteaches an agent to act as the project's product manager: read the board, capture evidence with honest provenance, find proofs, gate before a handoff. An agent may recordassumptionorsecondarysources;primaryis reserved for a real user's own words.prodc guideis the short human onboarding guide.
prodc also models goals, releases, roles, principles, decisions, attestations, withdrawals and
settled answers, and ships hygiene commands (dupes, recurrence, suggest); the
docs have the full surface.
Links
- Repository: https://gitlab.com/cardona-oss/prodc
- PyPI: https://pypi.org/project/prodc/
- Changelog: CHANGELOG.md
- Documentation: https://cardona-oss.gitlab.io/prodc/ (Quickstart, Commands, Model, Config, Lifecycle)
Contributing
Toolchain, CI, and the release process live in CONTRIBUTING.md; build and test
instructions for coding agents are in AGENTS.md. In short: make setup
then make check (lint + typecheck + test); moon run :ci is what CI runs.
License
MIT © Jorge Cardona. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for prodc 0.4.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| prodc-0.4.8.tar.gz | 171.6 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| prodc-0.4.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 296.1 kB
Release files / prodc-0.4.8.tar.gz
| Download URL | prodc-0.4.8.tar.gz |
|---|---|
| Size | 171.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f9e7f69e5ba4ef3eb0f842bf489b32de2404014e3a1eaa6c55902a311cdd76a1
|
|
BLAKE2b-256 checksum How to use checksums |
6897a279a21256b46b1af4b62310389315a89aa8c799db8ebc781c1685489eb1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / prodc-0.4.8-py3-none-any.whl
| Download URL | prodc-0.4.8-py3-none-any.whl |
|---|---|
| Size | 124.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6832982771214a19b1310a4017f106f1c93cc951d3fe3b3964d6a75aedc4d3e4
|
|
BLAKE2b-256 checksum How to use checksums |
ef94625d469ab7ba9710c52cb18f4370bd5eab0de592f3e4491a5ca0deea0cea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for prodc 0.4.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
