outcome-engineering 0.1.0__tar.gz

outcome_engineering-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.3
+Name: outcome-engineering
+Version: 0.1.0
+Summary: Repo-native product graph tooling for Outcome Engineering.
+Requires-Dist: typer>=0.16.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Outcome Engineering
+
+Outcome Engineering is a framework for helping humans continuously challenge product thinking and invent valuable solutions that users and customers actually want, use, and pay for, in ways that work for the business.
+
+The core claim:
+
+> Product development should be modeled as a living intent graph where every product bet can be traced upward to its strategic purpose, downward to implementation, and sideways to the evidence and learning that shaped it.
+
+Traceability is the mechanism. Better product judgment and better product outcomes are the point.
+
+The graph provides structure for product work and gives agents a way to understand, organize, and challenge what is happening.
+
+The framework connects product vision, strategy, OKRs, outcomes, opportunity solution trees, assumptions, experiments, PRDs, user stories, acceptance criteria, code, tests, and evidence into one coherent system.
+
+It is not a replacement for human product judgment. Humans still set direction, talk to users, interpret nuance, and make decisions. Agentic engineering can help maintain structure, reframe opportunities, analyze assumptions, challenge output-thinking, expose what is known and unknown, generate options, implement code, run tests, and preserve traceability across the system.
+
+Agents can generate plausible opportunities, solutions, assumptions, stories, and analyses, but plausibility is not grounding. Synthetic artifacts remain hypotheses until supported by real customer, user, market, business, or technical evidence.
+
+## The Problem
+
+Most organizations lose intent as work moves through the product development process.
+
+A compelling product vision becomes a strategy deck. Strategy becomes OKRs. OKRs become roadmap items. Roadmap items become tickets. Tickets become code. Code ships. Somewhere along the way, the original customer need, business intent, assumptions, and evidence are often lost.
+
+The result is delivery without memory:
+
+- Teams ship outputs without knowing which outcome they serve.
+- Discovery evidence lives separately from delivery work.
+- User stories lose their connection to customer opportunities.
+- Code becomes hard to explain in product terms.
+- Learning arrives too late, or never updates the underlying product model.
+
+Outcome Engineering treats this as a structural problem.
+
+## The Model
+
+At the highest level:
+
+```text
+Vision
+  -> Strategy
+    -> OKRs
+      -> Outcomes
+        -> Opportunity Solution Trees
+          -> Opportunities
+            -> Solutions
+              -> Assumptions
+                -> Experiments
+                  -> Decisions
+                    -> PRDs
+                      -> User Stories
+                        -> Acceptance Criteria
+                          -> Code
+                            -> Tests
+                              -> Released Product
+```
+
+But this is not a one-way waterfall.
+
+Evidence and learning can happen throughout the graph:
+
+```text
+Any product belief
+  -> Evidence
+    -> Learning
+      -> Update the graph
+```
+
+Evidence can come from user interviews, customer conversations, sales calls, support conversations, analytics, prototype tests, assumption tests, usability sessions, technical spikes, experiments, production telemetry, and market observation.
+
+Quantitative data can show what is happening. Human discovery is needed to understand why it is happening.
+
+## Repository Structure
+
+- [docs/framework.md](docs/framework.md) defines the framework.
+- [docs/graph.md](docs/graph.md) describes the concept graph.
+- [docs/glossary.md](docs/glossary.md) defines the core terms.
+- [docs/example-structure.md](docs/example-structure.md) explains the example filesystem graph.
+
+## CLI
+
+The Python package is `outcome-engineering`. The command is `oe`.
+
+Real product repositories should store the graph at:
+
+```text
+product/
+```
+
+Install the bundled agent skill with Playwright-style project-local commands:
+
+```sh
+uv run oe install --skills --force
+uv run oe install --skills=agents --force
+```
+
+Inspect a product graph:
+
+```sh
+uv run oe validate product
+uv run oe tree product
+uv run oe list outcomes --root product
+uv run oe list opportunities --root product
+uv run oe list solutions --root product
+```
+
+Trace product intent before editing a product artifact or implementing from a PRD:
+
+```sh
+uv run oe trace solution.agent-central --root product
+uv run oe context solution.agent-central --root product
+```
+
+Read a node's canonical marker file:
+
+```sh
+uv run oe show outcome.delegation-confidence --root product
+uv run oe show opportunity.agents-lack-safe-access --root product
+uv run oe show prd.agent-central-mvp --root product
+```
+
+Create nodes deterministically:
+
+```sh
+uv run oe new outcome delegation-confidence --root product
+uv run oe new opportunity agents-lack-safe-access --root product --under outcome.delegation-confidence
+uv run oe new solution agent-central --root product --under opportunity.agents-lack-safe-access
+uv run oe new assumption operation-discovery-reduces-tool-overload --root product --under solution.agent-central
+uv run oe new experiment fake-connector-prototype --root product --under assumption.operation-discovery-reduces-tool-overload
+uv run oe new prd agent-central-mvp --root product --under solution.agent-central
+```
+
+Experiments can only live under assumptions.
+
+Try the example graph:
+
+```sh
+uv run oe create-example --force
+uv run oe validate examples/delegation-product-graph
+uv run oe tree examples/delegation-product-graph
+uv run oe context solution.agent-central --root examples/delegation-product-graph
+```
+
+Install the skill into explicit global agent-tool locations:
+
+```sh
+uv run oe install-skill --agent codex --force
+uv run oe install-skill --agent claude --force
+uv run oe install-skill --agent all --force
+```

outcome_engineering-0.1.0/README.md

@@ -0,0 +1,150 @@
+# Outcome Engineering
+
+Outcome Engineering is a framework for helping humans continuously challenge product thinking and invent valuable solutions that users and customers actually want, use, and pay for, in ways that work for the business.
+
+The core claim:
+
+> Product development should be modeled as a living intent graph where every product bet can be traced upward to its strategic purpose, downward to implementation, and sideways to the evidence and learning that shaped it.
+
+Traceability is the mechanism. Better product judgment and better product outcomes are the point.
+
+The graph provides structure for product work and gives agents a way to understand, organize, and challenge what is happening.
+
+The framework connects product vision, strategy, OKRs, outcomes, opportunity solution trees, assumptions, experiments, PRDs, user stories, acceptance criteria, code, tests, and evidence into one coherent system.
+
+It is not a replacement for human product judgment. Humans still set direction, talk to users, interpret nuance, and make decisions. Agentic engineering can help maintain structure, reframe opportunities, analyze assumptions, challenge output-thinking, expose what is known and unknown, generate options, implement code, run tests, and preserve traceability across the system.
+
+Agents can generate plausible opportunities, solutions, assumptions, stories, and analyses, but plausibility is not grounding. Synthetic artifacts remain hypotheses until supported by real customer, user, market, business, or technical evidence.
+
+## The Problem
+
+Most organizations lose intent as work moves through the product development process.
+
+A compelling product vision becomes a strategy deck. Strategy becomes OKRs. OKRs become roadmap items. Roadmap items become tickets. Tickets become code. Code ships. Somewhere along the way, the original customer need, business intent, assumptions, and evidence are often lost.
+
+The result is delivery without memory:
+
+- Teams ship outputs without knowing which outcome they serve.
+- Discovery evidence lives separately from delivery work.
+- User stories lose their connection to customer opportunities.
+- Code becomes hard to explain in product terms.
+- Learning arrives too late, or never updates the underlying product model.
+
+Outcome Engineering treats this as a structural problem.
+
+## The Model
+
+At the highest level:
+
+```text
+Vision
+  -> Strategy
+    -> OKRs
+      -> Outcomes
+        -> Opportunity Solution Trees
+          -> Opportunities
+            -> Solutions
+              -> Assumptions
+                -> Experiments
+                  -> Decisions
+                    -> PRDs
+                      -> User Stories
+                        -> Acceptance Criteria
+                          -> Code
+                            -> Tests
+                              -> Released Product
+```
+
+But this is not a one-way waterfall.
+
+Evidence and learning can happen throughout the graph:
+
+```text
+Any product belief
+  -> Evidence
+    -> Learning
+      -> Update the graph
+```
+
+Evidence can come from user interviews, customer conversations, sales calls, support conversations, analytics, prototype tests, assumption tests, usability sessions, technical spikes, experiments, production telemetry, and market observation.
+
+Quantitative data can show what is happening. Human discovery is needed to understand why it is happening.
+
+## Repository Structure
+
+- [docs/framework.md](docs/framework.md) defines the framework.
+- [docs/graph.md](docs/graph.md) describes the concept graph.
+- [docs/glossary.md](docs/glossary.md) defines the core terms.
+- [docs/example-structure.md](docs/example-structure.md) explains the example filesystem graph.
+
+## CLI
+
+The Python package is `outcome-engineering`. The command is `oe`.
+
+Real product repositories should store the graph at:
+
+```text
+product/
+```
+
+Install the bundled agent skill with Playwright-style project-local commands:
+
+```sh
+uv run oe install --skills --force
+uv run oe install --skills=agents --force
+```
+
+Inspect a product graph:
+
+```sh
+uv run oe validate product
+uv run oe tree product
+uv run oe list outcomes --root product
+uv run oe list opportunities --root product
+uv run oe list solutions --root product
+```
+
+Trace product intent before editing a product artifact or implementing from a PRD:
+
+```sh
+uv run oe trace solution.agent-central --root product
+uv run oe context solution.agent-central --root product
+```
+
+Read a node's canonical marker file:
+
+```sh
+uv run oe show outcome.delegation-confidence --root product
+uv run oe show opportunity.agents-lack-safe-access --root product
+uv run oe show prd.agent-central-mvp --root product
+```
+
+Create nodes deterministically:
+
+```sh
+uv run oe new outcome delegation-confidence --root product
+uv run oe new opportunity agents-lack-safe-access --root product --under outcome.delegation-confidence
+uv run oe new solution agent-central --root product --under opportunity.agents-lack-safe-access
+uv run oe new assumption operation-discovery-reduces-tool-overload --root product --under solution.agent-central
+uv run oe new experiment fake-connector-prototype --root product --under assumption.operation-discovery-reduces-tool-overload
+uv run oe new prd agent-central-mvp --root product --under solution.agent-central
+```
+
+Experiments can only live under assumptions.
+
+Try the example graph:
+
+```sh
+uv run oe create-example --force
+uv run oe validate examples/delegation-product-graph
+uv run oe tree examples/delegation-product-graph
+uv run oe context solution.agent-central --root examples/delegation-product-graph
+```
+
+Install the skill into explicit global agent-tool locations:
+
+```sh
+uv run oe install-skill --agent codex --force
+uv run oe install-skill --agent claude --force
+uv run oe install-skill --agent all --force
+```

outcome_engineering-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "outcome-engineering"
+version = "0.1.0"
+description = "Repo-native product graph tooling for Outcome Engineering."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.16.0",
+]
+
+[project.scripts]
+oe = "outcome_engineering.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.9.0"]
+build-backend = "uv_build"
+

outcome_engineering-0.1.0/src/outcome_engineering/__init__.py

@@ -0,0 +1,4 @@
+"""Outcome Engineering CLI package."""
+
+__version__ = "0.1.0"
+

outcome_engineering-0.1.0/src/outcome_engineering/cli.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from outcome_engineering.example import create_example
+from outcome_engineering.graph import (
+    create_node,
+    discover_nodes,
+    find_node,
+    find_nodes_by_kind,
+    marker_content,
+    node_ancestors,
+    supporting_files,
+    validate as validate_graph,
+)
+from outcome_engineering.model import KIND_TO_RELATIONSHIP
+from outcome_engineering.skill_installer import install_project_skill, install_skill, install_skill_for_agent
+
+app = typer.Typer(help="Outcome Engineering product graph tooling.")
+
+
+@app.command(
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def install(
+    ctx: typer.Context,
+    force: bool = typer.Option(False, "--force", help="Replace the target skill directory if it already exists."),
+) -> None:
+    """Install bundled assets, including the oe-cli skill."""
+    try:
+        skill_value = parse_skills_option(ctx.args)
+        installed_at = install_project_skill(skill_value, force=force)
+    except ValueError as error:
+        typer.echo(str(error))
+        raise typer.Exit(code=1) from error
+    except FileExistsError as error:
+        typer.echo(str(error))
+        raise typer.Exit(code=1) from error
+
+    typer.echo(f"Installed oe-cli skill at {installed_at}")
+
+
+@app.command()
+def validate(
+    path: Path = typer.Argument(Path("product"), help="Product graph root to validate."),
+) -> None:
+    """Validate a product graph directory."""
+    issues = validate_graph(path)
+    if not issues:
+        typer.echo(f"OK: {path} is a valid product graph")
+        return
+
+    typer.echo(f"Invalid product graph: {path}")
+    for issue in issues:
+        typer.echo(f"- {issue.path}: {issue.message}")
+    raise typer.Exit(code=1)
+
+
+@app.command("tree")
+def tree_command(
+    path: Path = typer.Argument(Path("product"), help="Product graph root to print."),
+) -> None:
+    """Print the product graph tree."""
+    issues = validate_graph(path)
+    if issues:
+        typer.echo(f"Invalid product graph: {path}")
+        for issue in issues:
+            typer.echo(f"- {issue.path}: {issue.message}")
+        raise typer.Exit(code=1)
+
+    root = path.resolve()
+    typer.echo(str(path))
+    top_level = [node for node in discover_nodes(root) if node.parent is None and node.kind not in {"vision", "strategy"}]
+    for index, node in enumerate(top_level):
+        print_node(node, prefix="", is_last=index == len(top_level) - 1)
+
+
+@app.command("create-example")
+def create_example_command(
+    output: Path = typer.Option(
+        Path("examples/delegation-product-graph"),
+        "--output",
+        "-o",
+        help="Directory to create.",
+    ),
+    force: bool = typer.Option(False, "--force", help="Replace output directory if it already exists."),
+) -> None:
+    """Create an example product graph."""
+    try:
+        create_example(output, force=force)
+    except FileExistsError as error:
+        typer.echo(str(error))
+        raise typer.Exit(code=1) from error
+    typer.echo(f"Created example product graph at {output}")
+
+
+@app.command("install-skill")
+def install_skill_command(
+    agent: str = typer.Option("codex", "--agent", "-a", help="Agent tool target: codex, claude, or all."),
+    target: Path | None = typer.Option(None, "--target", "-t", help="Exact skill install directory. Overrides --agent."),
+    force: bool = typer.Option(False, "--force", help="Replace the target skill directory if it already exists."),
+) -> None:
+    """Install the bundled oe-cli agent skill."""
+    try:
+        installed_paths = [install_skill(target=target, force=force)] if target is not None else install_skill_for_agent(agent, force=force)
+    except (FileExistsError, ValueError) as error:
+        typer.echo(str(error))
+        raise typer.Exit(code=1) from error
+    for installed_at in installed_paths:
+        typer.echo(f"Installed oe-cli skill at {installed_at}")
+
+
+@app.command()
+def trace(
+    selector: str = typer.Argument(..., help="Node id, slug, node directory, or marker file path."),
+    root: Path = typer.Option(Path("product"), "--root", "-r", help="Product graph root."),
+) -> None:
+    """Show where a node sits in the product graph."""
+    issues = validate_graph(root)
+    if issues:
+        typer.echo(f"Invalid product graph: {root}")
+        for issue in issues:
+            typer.echo(f"- {issue.path}: {issue.message}")
+        raise typer.Exit(code=1)
+
+    node = find_node(root, selector)
+    if node is None:
+        typer.echo(f"Node not found or ambiguous: {selector}")
+        raise typer.Exit(code=1)
+
+    typer.echo(f"{node.kind}: {node.slug}")
+    typer.echo(f"id: {node.id}")
+    typer.echo(f"path: {node.path}")
+    typer.echo(f"marker: {node.marker_file}")
+    if node.parent is not None:
+        typer.echo(f"parent: {node.parent.id}")
+        typer.echo(f"relationship: {node.relationship}")
+    else:
+        typer.echo("parent: <root>")
+
+    ancestors = node_ancestors(node)
+    if ancestors:
+        typer.echo("")
+        typer.echo("Trace:")
+        for ancestor in ancestors:
+            typer.echo(f"- {ancestor.kind}: {ancestor.slug}")
+        typer.echo(f"- {node.kind}: {node.slug}")
+
+    if node.children:
+        typer.echo("")
+        typer.echo("Children:")
+        for child in node.children:
+            typer.echo(f"- {child.kind}: {child.slug}")
+
+
+@app.command("list")
+def list_command(
+    kind: str | None = typer.Argument(None, help="Optional node kind to list."),
+    root: Path = typer.Option(Path("product"), "--root", "-r", help="Product graph root."),
+) -> None:
+    """List graph nodes."""
+    issues = validate_graph(root)
+    if issues:
+        typer.echo(f"Invalid product graph: {root}")
+        for issue in issues:
+            typer.echo(f"- {issue.path}: {issue.message}")
+        raise typer.Exit(code=1)
+
+    if kind is not None and kind.endswith("s"):
+        kind = kind[:-1]
+    if kind is not None and kind not in KIND_TO_RELATIONSHIP:
+        supported = ", ".join(sorted(KIND_TO_RELATIONSHIP))
+        typer.echo(f"unsupported node kind {kind!r}; expected one of: {supported}")
+        raise typer.Exit(code=1)
+
+    nodes = find_nodes_by_kind(root, kind)
+    for node in nodes:
+        typer.echo(f"{node.id}\t{node.path}")
+
+
+@app.command()
+def show(
+    selector: str = typer.Argument(..., help="Node id, slug, node directory, or marker file path."),
+    root: Path = typer.Option(Path("product"), "--root", "-r", help="Product graph root."),
+) -> None:
+    """Print a node's marker file."""
+    node = load_valid_node(root, selector)
+    typer.echo(marker_content(node).rstrip())
+
+
+@app.command()
+def context(
+    selector: str = typer.Argument(..., help="Node id, slug, node directory, or marker file path."),
+    root: Path = typer.Option(Path("product"), "--root", "-r", help="Product graph root."),
+) -> None:
+    """Print deterministic context around a node for an agent."""
+    node = load_valid_node(root, selector)
+    ancestors = node_ancestors(node)
+
+    typer.echo(f"# Context: {node.id}")
+    typer.echo("")
+    typer.echo("## Trace")
+    for ancestor in ancestors:
+        typer.echo(f"- {ancestor.id} ({ancestor.marker_file})")
+    typer.echo(f"- {node.id} ({node.marker_file})")
+
+    if node.children:
+        typer.echo("")
+        typer.echo("## Children")
+        for child in node.children:
+            typer.echo(f"- {child.id} ({child.marker_file})")
+
+    files = supporting_files(node)
+    if files:
+        typer.echo("")
+        typer.echo("## Supporting Files")
+        for path in files:
+            typer.echo(f"- {path}")
+
+    if ancestors:
+        typer.echo("")
+        typer.echo("## Ancestor Content")
+        for ancestor in ancestors:
+            typer.echo("")
+            typer.echo(f"### {ancestor.id}")
+            typer.echo("")
+            typer.echo(marker_content(ancestor).rstrip())
+
+    typer.echo("")
+    typer.echo("## Node Content")
+    typer.echo("")
+    typer.echo(marker_content(node).rstrip())
+
+
+@app.command("new")
+def new_command(
+    kind: str = typer.Argument(..., help=f"Node kind: {', '.join(sorted(KIND_TO_RELATIONSHIP))}."),
+    slug: str = typer.Argument(..., help="Filesystem slug for the node."),
+    root: Path = typer.Option(Path("product"), "--root", "-r", help="Product graph root."),
+    under: str | None = typer.Option(None, "--under", "-u", help="Parent node id, slug, path, or marker file."),
+    title: str | None = typer.Option(None, "--title", "-t", help="Human-readable title."),
+) -> None:
+    """Create a product graph node in the valid location."""
+    root.mkdir(parents=True, exist_ok=True)
+    issues = validate_graph(root)
+    if issues:
+        typer.echo(f"Invalid product graph: {root}")
+        for issue in issues:
+            typer.echo(f"- {issue.path}: {issue.message}")
+        raise typer.Exit(code=1)
+
+    try:
+        node = create_node(root, kind=kind, slug=slug, title=title, under=under)
+    except (ValueError, FileExistsError) as error:
+        typer.echo(str(error))
+        raise typer.Exit(code=1) from error
+
+    typer.echo(f"Created {node.id}")
+    typer.echo(f"path: {node.path}")
+    typer.echo(f"marker: {node.marker_file}")
+
+
+def load_valid_node(root: Path, selector: str):
+    issues = validate_graph(root)
+    if issues:
+        typer.echo(f"Invalid product graph: {root}")
+        for issue in issues:
+            typer.echo(f"- {issue.path}: {issue.message}")
+        raise typer.Exit(code=1)
+
+    node = find_node(root, selector)
+    if node is None:
+        typer.echo(f"Node not found or ambiguous: {selector}")
+        raise typer.Exit(code=1)
+    return node
+
+
+def parse_skills_option(args: list[str]) -> str:
+    if not args:
+        raise ValueError("nothing to install; use --skills or --skills=agents")
+
+    value: str | None = None
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "--skills":
+            value = "claude"
+        elif arg.startswith("--skills="):
+            value = arg.split("=", 1)[1] or "claude"
+        else:
+            raise ValueError(f"unknown install option: {arg}")
+        index += 1
+
+    if value is None:
+        raise ValueError("nothing to install; use --skills or --skills=agents")
+    return value
+
+
+def print_node(node, prefix: str, is_last: bool) -> None:
+    branch = "`-- " if is_last else "|-- "
+    typer.echo(f"{prefix}{branch}{node.kind}: {node.slug}")
+    child_prefix = prefix + ("    " if is_last else "|   ")
+    for index, child in enumerate(node.children):
+        print_node(child, child_prefix, index == len(node.children) - 1)
+
+
+if __name__ == "__main__":
+    app()