outcome-engineering 0.1.0__py3-none-any.whl

outcome_engineering/__init__.py

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

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()

outcome_engineering/example.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ExampleNode:
+    slug: str
+    kind: str
+    title: str
+    body: str
+    children: dict[str, list["ExampleNode"]] = field(default_factory=dict)
+    files: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def marker_file(self) -> str:
+        return f"{self.kind.upper()}.md"
+
+
+def write_file(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content.rstrip() + "\n", encoding="utf-8")
+
+
+def render_node(node: ExampleNode) -> str:
+    return f"""# {node.title}
+
+```yaml
+type: {node.kind}
+id: {node.kind}.{node.slug}
+status: example
+```
+
+{node.body}
+"""
+
+
+def write_node(base: Path, node: ExampleNode) -> None:
+    node_dir = base / node.slug
+    write_file(node_dir / node.marker_file, render_node(node))
+
+    for relative_path, content in node.files.items():
+        write_file(node_dir / relative_path, content)
+
+    for relationship, children in node.children.items():
+        for child in children:
+            write_node(node_dir / relationship, child)
+
+
+def example_graph() -> ExampleNode:
+    return ExampleNode(
+        slug="delegation-confidence",
+        kind="outcome",
+        title="Delegation Confidence",
+        body="""Knowledge workers trust delegated agent work enough to use it for real recurring tasks.
+
+## Measures
+
+- A user delegates at least one recurring task to an agent.
+- The delegated task completes with reviewable output.
+- The user would choose to delegate the same task again.
+
+## Known / Unknown
+
+- Known: users want help turning messy work into agent-usable instructions.
+- Unknown: whether safe tool access or better task framing is the larger blocker.""",
+        files={
+            "notes.md": """# Notes
+
+This outcome is intentionally broad enough to contain multiple opportunity branches.
+""",
+        },
+        children={
+            "opportunities": [
+                ExampleNode(
+                    slug="users-do-not-know-what-to-delegate",
+                    kind="opportunity",
+                    title="Users Do Not Know What To Delegate",
+                    body="""Users can sense that agents could help, but they struggle to identify which parts of their work are good delegation candidates.
+
+## Evidence
+
+- Workshop participants often start with vague work categories instead of concrete recurring tasks.
+- Delegation candidates become clearer after an interview about recent work.""",
+                    files={
+                        "evidence/interview-patterns.md": """# Interview Patterns
+
+Example evidence placeholder. In a real product graph this would link to interview notes, clips, transcripts, or synthesis.
+""",
+                    },
+                    children={
+                        "opportunities": [
+                            ExampleNode(
+                                slug="recurring-work-is-hard-to-describe",
+                                kind="opportunity",
+                                title="Recurring Work Is Hard To Describe",
+                                body="""Users often know how to do a task themselves, but cannot easily describe the process, edge cases, inputs, and quality bar for an agent.""",
+                                children={
+                                    "solutions": [
+                                        ExampleNode(
+                                            slug="delegation-interview",
+                                            kind="solution",
+                                            title="Delegation Interview",
+                                            body="""An agent-guided interview helps the user describe one concrete task, then expands outward to map related work.""",
+                                            children={
+                                                "assumptions": [
+                                                    ExampleNode(
+                                                        slug="interview-produces-better-task-descriptions",
+                                                        kind="assumption",
+                                                        title="Interview Produces Better Task Descriptions",
+                                                        body="""If an agent interviews the user about a concrete recent task, the resulting task description will be more actionable than a blank-form prompt.""",
+                                                        children={
+                                                            "experiments": [
+                                                                ExampleNode(
+                                                                    slug="compare-blank-form-vs-interview",
+                                                                    kind="experiment",
+                                                                    title="Compare Blank Form Vs Interview",
+                                                                    body="""Ask users to describe the same delegation candidate through a blank form and through an interview. Compare completeness, confidence, and agent execution quality.""",
+                                                                )
+                                                            ]
+                                                        },
+                                                    )
+                                                ],
+                                                "prds": [
+                                                    ExampleNode(
+                                                        slug="delegation-interview-mvp",
+                                                        kind="prd",
+                                                        title="Delegation Interview MVP",
+                                                        body="""Build the smallest flow that interviews a user about one recurring task and turns the answers into a reusable agent instruction artifact.
+
+## Acceptance Criteria
+
+- The interview anchors on one concrete recent task.
+- The output includes inputs, steps, edge cases, quality bar, and stop-and-ask conditions.
+- The output can be used by an agent in a fresh context.""",
+                                                    )
+                                                ],
+                                            },
+                                        )
+                                    ]
+                                },
+                            )
+                        ]
+                    },
+                ),
+                ExampleNode(
+                    slug="agents-lack-safe-access-to-tools",
+                    kind="opportunity",
+                    title="Agents Lack Safe Access To Tools",
+                    body="""Even when a user knows what to delegate, the agent may lack safe, discoverable, permissioned access to the systems needed to do the work.""",
+                    children={
+                        "solutions": [
+                            ExampleNode(
+                                slug="agent-central",
+                                kind="solution",
+                                title="Agent Central",
+                                body="""A capability platform where administrators configure and publish safe operations that agents can discover and execute through a small MCP surface.""",
+                                children={
+                                    "assumptions": [
+                                        ExampleNode(
+                                            slug="operation-discovery-reduces-tool-overload",
+                                            kind="assumption",
+                                            title="Operation Discovery Reduces Tool Overload",
+                                            body="""Agents will perform better when they can search and describe operations instead of receiving a very large static tool list.""",
+                                            children={
+                                                "experiments": [
+                                                    ExampleNode(
+                                                        slug="fake-connector-prototype",
+                                                        kind="experiment",
+                                                        title="Fake Connector Prototype",
+                                                        body="""Build an in-memory connector prototype and observe whether agents can discover, describe, and execute the right operation without needing one MCP tool per capability.""",
+                                                    )
+                                                ]
+                                            },
+                                        ),
+                                        ExampleNode(
+                                            slug="admins-will-curate-agent-capabilities",
+                                            kind="assumption",
+                                            title="Admins Will Curate Agent Capabilities",
+                                            body="""Organizations will assign someone to configure, publish, and govern the operations made available to agents.""",
+                                        ),
+                                    ],
+                                    "prds": [
+                                        ExampleNode(
+                                            slug="agent-central-mvp",
+                                            kind="prd",
+                                            title="Agent Central MVP",
+                                            body="""Validate the smallest useful loop for low-context agent operation discovery and execution.
+
+## Acceptance Criteria
+
+- Agents can search operations.
+- Agents can describe a selected operation.
+- Agents can execute a valid GraphQL operation.
+- Runtime permission checks allow or deny execution.""",
+                                        )
+                                    ],
+                                },
+                            )
+                        ]
+                    },
+                ),
+            ]
+        },
+    )
+
+
+def create_example(root: Path, force: bool) -> None:
+    if root.exists():
+        if not force:
+            raise FileExistsError(f"{root} already exists. Re-run with --force to replace it.")
+        shutil.rmtree(root)
+
+    write_file(
+        root / "VISION.md",
+        """# Vision
+
+Enable knowledge workers to securely and effectively delegate work to AI agents.
+""",
+    )
+    write_file(
+        root / "STRATEGY.md",
+        """# Strategy
+
+Focus on recurring knowledge work where better task framing and safer tool access can make delegation feel trustworthy.
+""",
+    )
+    write_node(root / "outcomes", example_graph())
+

outcome_engineering/graph.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from outcome_engineering.model import (
+    ALLOWED_CHILD_RELATIONSHIPS,
+    KIND_TO_MARKER_FILE,
+    KIND_TO_RELATIONSHIP,
+    MARKER_FILES,
+    PARENT_KIND_TO_CHILD_KIND,
+    RELATIONSHIP_TO_CHILD_KIND,
+    ProductNode,
+    ValidationIssue,
+)
+
+
+def marker_files_in(path: Path) -> list[Path]:
+    return sorted(child for child in path.iterdir() if child.is_file() and child.name in MARKER_FILES)
+
+
+def discover_nodes(root: Path) -> list[ProductNode]:
+    root = root.resolve()
+    nodes: list[ProductNode] = []
+
+    def visit_node_dir(path: Path, parent: ProductNode | None, relationship: str | None) -> ProductNode | None:
+        markers = marker_files_in(path)
+        if len(markers) != 1:
+            return None
+
+        marker = markers[0]
+        node = ProductNode(
+            path=path,
+            kind=MARKER_FILES[marker.name],
+            marker_file=marker,
+            slug=path.name,
+            parent=parent,
+            relationship=relationship,
+            children=[],
+        )
+        nodes.append(node)
+
+        child_nodes: list[ProductNode] = []
+        for rel_dir in relationship_dirs(path):
+            for child_dir in sorted(child for child in rel_dir.iterdir() if child.is_dir()):
+                child = visit_node_dir(child_dir, node, rel_dir.name)
+                if child is not None:
+                    child_nodes.append(child)
+
+        node.children.extend(child_nodes)
+        return node
+
+    for child in sorted(root.iterdir()):
+        if child.is_dir() and child.name in RELATIONSHIP_TO_CHILD_KIND:
+            for node_dir in sorted(grandchild for grandchild in child.iterdir() if grandchild.is_dir()):
+                visit_node_dir(node_dir, None, child.name)
+
+    for marker in marker_files_in(root):
+        nodes.append(
+            ProductNode(
+                path=root,
+                kind=MARKER_FILES[marker.name],
+                marker_file=marker,
+                slug=root.name,
+                parent=None,
+                relationship=None,
+                children=[],
+            )
+        )
+
+    return nodes
+
+
+def find_node(root: Path, selector: str) -> ProductNode | None:
+    root = root.resolve()
+    selector_path = Path(selector)
+    if selector_path.exists():
+        resolved_selector = selector_path.resolve()
+        for node in discover_nodes(root):
+            if node.path == resolved_selector or node.marker_file == resolved_selector:
+                return node
+        return None
+
+    matches = [node for node in discover_nodes(root) if node.id == selector or node.slug == selector]
+    if len(matches) == 1:
+        return matches[0]
+    return None
+
+
+def find_nodes_by_kind(root: Path, kind: str | None = None) -> list[ProductNode]:
+    nodes = [node for node in discover_nodes(root) if node.kind not in {"vision", "strategy"}]
+    if kind is None:
+        return sorted(nodes, key=lambda node: (node.kind, node.slug, str(node.path)))
+    return sorted((node for node in nodes if node.kind == kind), key=lambda node: (node.slug, str(node.path)))
+
+
+def node_ancestors(node: ProductNode) -> list[ProductNode]:
+    ancestors: list[ProductNode] = []
+    current = node.parent
+    while current is not None:
+        ancestors.append(current)
+        current = current.parent
+    return list(reversed(ancestors))
+
+
+def create_node(root: Path, kind: str, slug: str, title: str | None, under: str | None) -> ProductNode:
+    root = root.resolve()
+    if kind not in KIND_TO_RELATIONSHIP:
+        supported = ", ".join(sorted(KIND_TO_RELATIONSHIP))
+        raise ValueError(f"unsupported node kind {kind!r}; expected one of: {supported}")
+
+    parent: ProductNode | None = None
+    parent_kind = "root"
+    parent_path = root
+    if kind != "outcome":
+        if under is None:
+            raise ValueError(f"{kind} requires --under")
+        parent = find_node(root, under)
+        if parent is None:
+            raise ValueError(f"parent not found: {under}")
+        parent_kind = parent.kind
+        parent_path = parent.path
+    elif under is not None:
+        raise ValueError("outcome cannot use --under; outcomes live under the product graph root")
+
+    allowed_child_kinds = PARENT_KIND_TO_CHILD_KIND.get(parent_kind, set())
+    if kind not in allowed_child_kinds:
+        allowed = ", ".join(sorted(allowed_child_kinds)) or "none"
+        raise ValueError(f"cannot create {kind} under {parent_kind}; allowed child kinds: {allowed}")
+
+    relationship = KIND_TO_RELATIONSHIP[kind]
+    node_path = parent_path / relationship / slug
+    if node_path.exists():
+        raise FileExistsError(f"{node_path} already exists")
+
+    marker = KIND_TO_MARKER_FILE[kind]
+    node_path.mkdir(parents=True)
+    marker_path = node_path / marker
+    marker_path.write_text(render_template(kind, slug, title or title_from_slug(slug)), encoding="utf-8")
+
+    return ProductNode(
+        path=node_path,
+        kind=kind,
+        marker_file=marker_path,
+        slug=slug,
+        parent=parent,
+        relationship=relationship,
+        children=[],
+    )
+
+
+def render_template(kind: str, slug: str, title: str) -> str:
+    sections = {
+        "outcome": "## Measures\n\n- TODO\n\n## Known / Unknown\n\n- Known: TODO\n- Unknown: TODO\n",
+        "opportunity": "## Evidence\n\n- TODO\n\n## Known / Unknown\n\n- Known: TODO\n- Unknown: TODO\n",
+        "solution": "## Product Risks\n\n- Value: TODO\n- Usability: TODO\n- Feasibility: TODO\n- Viability: TODO\n\n## Assumptions\n\n- TODO\n",
+        "assumption": "## Risk Type\n\nTODO\n\n## How This Could Be False\n\nTODO\n",
+        "experiment": "## Tests Assumption\n\nTODO\n\n## Success / Failure Signal\n\nTODO\n\n## Decision It Informs\n\nTODO\n",
+        "prd": "## Problem\n\nTODO\n\n## User Stories\n\n- TODO\n\n## Acceptance Criteria\n\n- TODO\n",
+    }
+    body = sections[kind]
+    return f"""# {title}
+
+```yaml
+type: {kind}
+id: {kind}.{slug}
+status: draft
+```
+
+{body}
+"""
+
+
+def title_from_slug(slug: str) -> str:
+    return " ".join(part.capitalize() for part in slug.replace("_", "-").split("-") if part)
+
+
+def marker_content(node: ProductNode) -> str:
+    return node.marker_file.read_text(encoding="utf-8")
+
+
+def supporting_files(node: ProductNode) -> list[Path]:
+    relationship_names = set(RELATIONSHIP_TO_CHILD_KIND)
+    return sorted(
+        path
+        for path in node.path.rglob("*")
+        if path.is_file()
+        and path != node.marker_file
+        and not any(part in relationship_names for part in path.relative_to(node.path).parts[:-1])
+    )
+
+
+def relationship_dirs(path: Path) -> list[Path]:
+    return sorted(child for child in path.iterdir() if child.is_dir() and child.name in RELATIONSHIP_TO_CHILD_KIND)
+
+
+def validate(root: Path) -> list[ValidationIssue]:
+    root = root.resolve()
+    issues: list[ValidationIssue] = []
+
+    if not root.exists():
+        return [ValidationIssue(root, "path does not exist")]
+    if not root.is_dir():
+        return [ValidationIssue(root, "path is not a directory")]
+
+    seen_ids: dict[str, Path] = {}
+
+    for path in sorted([root, *[p for p in root.rglob("*") if p.is_dir()]]):
+        markers = marker_files_in(path)
+        if path == root:
+            root_marker_names = {marker.name for marker in markers}
+            unexpected_root_markers = root_marker_names - {"VISION.md", "STRATEGY.md"}
+            if unexpected_root_markers:
+                issues.append(ValidationIssue(path, f"root has invalid marker files: {', '.join(sorted(unexpected_root_markers))}"))
+            continue
+        if len(markers) > 1:
+            issues.append(ValidationIssue(path, f"node directory has multiple marker files: {', '.join(m.name for m in markers)}"))
+            continue
+        if len(markers) == 1:
+            marker = markers[0]
+            kind = MARKER_FILES[marker.name]
+            node_id = f"{kind}.{path.name}"
+            if node_id in seen_ids:
+                issues.append(ValidationIssue(path, f"duplicate node id {node_id}; first seen at {seen_ids[node_id]}"))
+            else:
+                seen_ids[node_id] = path
+
+            parent_info = parent_node_and_relationship(root, path)
+            if path == root:
+                continue
+            if parent_info is None:
+                issues.append(ValidationIssue(path, "node is not inside a valid relationship directory"))
+                continue
+            parent_path, relationship = parent_info
+            expected_kinds = RELATIONSHIP_TO_CHILD_KIND[relationship]
+            if kind not in expected_kinds:
+                issues.append(
+                    ValidationIssue(
+                        path,
+                        f"{marker.name} is not valid under {relationship}/; expected {', '.join(sorted(expected_kinds))}",
+                    )
+                )
+            if relationship == "experiments":
+                parent_markers = marker_files_in(parent_path)
+                parent_kind = MARKER_FILES[parent_markers[0].name] if len(parent_markers) == 1 else "unknown"
+                if parent_kind != "assumption":
+                    issues.append(ValidationIssue(path, "experiments can only live under an assumption"))
+
+    for path in sorted([root, *[p for p in root.rglob("*") if p.is_dir()]]):
+        markers = marker_files_in(path)
+        current_kind = "root"
+        if len(markers) == 1:
+            current_kind = MARKER_FILES[markers[0].name]
+
+        for rel_dir in relationship_dirs(path):
+            if rel_dir.name not in ALLOWED_CHILD_RELATIONSHIPS[current_kind]:
+                issues.append(ValidationIssue(rel_dir, f"{rel_dir.name}/ is not allowed under {current_kind}"))
+            for child_dir in sorted(child for child in rel_dir.iterdir() if child.is_dir()):
+                child_markers = marker_files_in(child_dir)
+                if len(child_markers) == 0:
+                    issues.append(ValidationIssue(child_dir, f"missing marker file for child under {rel_dir.name}/"))
+
+    return issues
+
+
+def parent_node_and_relationship(root: Path, path: Path) -> tuple[Path, str] | None:
+    parent = path.parent
+    if parent == root:
+        return None
+    relationship = parent.name
+    if relationship not in RELATIONSHIP_TO_CHILD_KIND:
+        return None
+    node_parent = parent.parent
+    if node_parent == root:
+        return node_parent, relationship
+    if len(marker_files_in(node_parent)) != 1:
+        return None
+    return node_parent, relationship

outcome_engineering/model.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+MARKER_FILES = {
+    "VISION.md": "vision",
+    "STRATEGY.md": "strategy",
+    "OUTCOME.md": "outcome",
+    "OPPORTUNITY.md": "opportunity",
+    "SOLUTION.md": "solution",
+    "ASSUMPTION.md": "assumption",
+    "EXPERIMENT.md": "experiment",
+    "PRD.md": "prd",
+}
+
+RELATIONSHIP_TO_CHILD_KIND = {
+    "outcomes": {"outcome"},
+    "opportunities": {"opportunity"},
+    "solutions": {"solution"},
+    "assumptions": {"assumption"},
+    "experiments": {"experiment"},
+    "prds": {"prd"},
+}
+
+KIND_TO_MARKER_FILE = {kind: marker for marker, kind in MARKER_FILES.items()}
+
+KIND_TO_RELATIONSHIP = {
+    "outcome": "outcomes",
+    "opportunity": "opportunities",
+    "solution": "solutions",
+    "assumption": "assumptions",
+    "experiment": "experiments",
+    "prd": "prds",
+}
+
+PARENT_KIND_TO_CHILD_KIND = {
+    "root": {"outcome"},
+    "outcome": {"opportunity"},
+    "opportunity": {"opportunity", "solution"},
+    "solution": {"assumption", "prd"},
+    "assumption": {"experiment"},
+}
+
+ALLOWED_CHILD_RELATIONSHIPS = {
+    "root": {"outcomes"},
+    "vision": set(),
+    "strategy": set(),
+    "outcome": {"opportunities"},
+    "opportunity": {"opportunities", "solutions"},
+    "solution": {"assumptions", "prds"},
+    "assumption": {"experiments"},
+    "experiment": set(),
+    "prd": set(),
+}
+
+
+@dataclass(frozen=True)
+class ProductNode:
+    path: Path
+    kind: str
+    marker_file: Path
+    slug: str
+    parent: "ProductNode | None" = None
+    relationship: str | None = None
+    children: list["ProductNode"] = field(default_factory=list)
+
+    @property
+    def id(self) -> str:
+        return f"{self.kind}.{self.slug}"
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    path: Path
+    message: str

outcome_engineering/skill_installer.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import os
+import shutil
+from importlib import resources
+from pathlib import Path
+
+
+SKILL_NAME = "oe-cli"
+
+
+def skill_target(agent: str) -> Path:
+    normalized = agent.lower()
+    if normalized == "codex":
+        return codex_skill_target()
+    if normalized == "claude":
+        return claude_skill_target()
+    raise ValueError(f"unsupported agent {agent!r}; expected codex, claude, or all")
+
+
+def project_skill_target(kind: str, cwd: Path | None = None) -> Path:
+    root = (cwd or Path.cwd()).resolve()
+    normalized = kind.lower()
+    if normalized in {"", "claude"}:
+        return root / ".claude" / "skills" / SKILL_NAME
+    if normalized == "agents":
+        return root / ".agents" / "skills" / SKILL_NAME
+    raise ValueError("unsupported --skills value; use --skills, --skills=claude, or --skills=agents")
+
+
+def codex_skill_target() -> Path:
+    codex_home = os.environ.get("CODEX_HOME")
+    if codex_home:
+        return Path(codex_home) / "skills" / SKILL_NAME
+    return Path.home() / ".codex" / "skills" / SKILL_NAME
+
+
+def claude_skill_target() -> Path:
+    claude_home = os.environ.get("CLAUDE_HOME")
+    if claude_home:
+        return Path(claude_home) / "skills" / SKILL_NAME
+    return Path.home() / ".claude" / "skills" / SKILL_NAME
+
+
+def install_skill(target: Path | None = None, force: bool = False) -> Path:
+    destination = (target or codex_skill_target()).expanduser()
+    return copy_skill(destination, force=force)
+
+
+def install_skill_for_agent(agent: str, force: bool = False) -> list[Path]:
+    normalized = agent.lower()
+    if normalized == "all":
+        return [copy_skill(skill_target(name), force=force) for name in ("codex", "claude")]
+    return [copy_skill(skill_target(normalized), force=force)]
+
+
+def install_project_skill(kind: str = "claude", cwd: Path | None = None, force: bool = False) -> Path:
+    return copy_skill(project_skill_target(kind, cwd=cwd), force=force)
+
+
+def copy_skill(destination: Path, force: bool = False) -> Path:
+    destination = destination.expanduser()
+    source = resources.files("outcome_engineering") / "skills" / SKILL_NAME
+
+    if destination.exists():
+        if not force:
+            raise FileExistsError(f"{destination} already exists. Re-run with --force to replace it.")
+        if destination.is_dir():
+            shutil.rmtree(destination)
+        else:
+            destination.unlink()
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(source, destination)
+    return destination

outcome_engineering/skills/oe-cli/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: oe-cli
+description: Use this skill whenever a repository has an Outcome Engineering product graph, the `oe` CLI, the `outcome-engineering` Python package, or the user asks about product vision, outcomes, opportunities, solutions, assumptions, experiments, PRDs, product discovery, or implementing work that should trace to product intent. This skill tells agents how to use `oe` to inspect, create, validate, and contextualize product graph structure before doing product or delivery work.
+---
+
+# Outcome Engineering
+
+Use the `oe` CLI to work with repo-native product graphs.
+
+The Python package is `outcome-engineering`. The command is `oe`.
+
+Install the skill for agent tools:
+
+```sh
+uvx outcome-engineering install --skills
+uvx outcome-engineering install --skills=agents
+```
+
+Outcome Engineering stores product intent as a filesystem graph rooted at:
+
+```text
+product/
+```
+
+The graph convention is:
+
+```text
+product/
+  VISION.md
+  STRATEGY.md
+  outcomes/
+    <outcome>/
+      OUTCOME.md
+      opportunities/
+        <opportunity>/
+          OPPORTUNITY.md
+          opportunities/
+            <sub-opportunity>/
+          solutions/
+            <solution>/
+              SOLUTION.md
+              assumptions/
+                <assumption>/
+                  ASSUMPTION.md
+                  experiments/
+                    <experiment>/
+                      EXPERIMENT.md
+              prds/
+                <prd>/
+                  PRD.md
+```
+
+Experiments belong under assumptions. Do not create experiments directly under solutions.
+
+## When To Use
+
+Use this skill when the user asks to:
+
+- create or refine product vision, strategy, outcomes, opportunities, solutions, assumptions, experiments, or PRDs
+- decide what to build next
+- turn product thinking into a PRD or delivery work
+- implement a feature that should trace back to product intent
+- validate or inspect an existing product graph
+- add discovery evidence, assumptions, or experiments
+
+Skip it for isolated implementation chores that do not affect product behavior, such as small refactors, formatting, dependency bumps, or mechanical bug fixes with no product artifact.
+
+## Default Workflow
+
+Start by checking whether the repo has a product graph:
+
+```sh
+test -d product && uv run oe validate product
+```
+
+If the graph exists, inspect it before making product or delivery changes:
+
+```sh
+uv run oe tree product
+uv run oe list outcomes --root product
+```
+
+Before working on a specific product artifact, trace it:
+
+```sh
+uv run oe trace <node-id-or-slug> --root product
+uv run oe context <node-id-or-slug> --root product
+```
+
+Use `oe context` before writing a PRD, editing a solution, or implementing code from a PRD. It gives deterministic context; it does not replace reading the linked files.
+
+After changing graph structure, validate:
+
+```sh
+uv run oe validate product
+```
+
+## Creating Nodes
+
+Create graph nodes through `oe new` instead of hand-rolling directories.
+
+```sh
+uv run oe new outcome <slug> --root product
+uv run oe new opportunity <slug> --root product --under outcome.<slug>
+uv run oe new solution <slug> --root product --under opportunity.<slug>
+uv run oe new assumption <slug> --root product --under solution.<slug>
+uv run oe new experiment <slug> --root product --under assumption.<slug>
+uv run oe new prd <slug> --root product --under solution.<slug>
+```
+
+If a slug is ambiguous, use the full node id or marker file path.
+
+## Important Boundary
+
+`oe` currently manages deterministic structure. It does not make product judgment.
+
+Do not pretend that `oe validate` means the product thinking is good. It only means the graph structure is valid. Human judgment and user discovery remain required.

outcome_engineering-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+outcome_engineering/__init__.py,sha256=EegsRgUFfo3HhgqBaD44uYXUxrm2MfPqXUxcAu0ggEo,63
+outcome_engineering/cli.py,sha256=xQ-Z_7LuCUpU93cwFdR9qAzZ4PARt12_IAfkCNMMYJM,10624
+outcome_engineering/example.py,sha256=7GdFrnjsEgnpyvHxW2_75XbzZK-CH9kKCDyjAVtn5lo,11098
+outcome_engineering/graph.py,sha256=i4NhTDnUbAR_r51HaJQzI9qg2rcPp7sj7G_Oc4XuobI,10466
+outcome_engineering/model.py,sha256=A3f9X_-UnFfgoWa_0Zv54fzh5ePEH8G6PEq2f1QJOfY,1809
+outcome_engineering/skill_installer.py,sha256=sUK5C-ns2uARNWuF6dBaR5vF7cOo0iMzDZMMaJyRKTA,2534
+outcome_engineering/skills/oe-cli/SKILL.md,sha256=kXlKtePOrGMI4nFjjumWWS9OWj0cCLFhKtjcM4f5IVM,3696
+outcome_engineering-0.1.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+outcome_engineering-0.1.0.dist-info/entry_points.txt,sha256=IIdrnuxEgUt0GSH5aSiH8N85JJHBUEjNIl7XL4nyd-A,52
+outcome_engineering-0.1.0.dist-info/METADATA,sha256=O5p80I2-PlO-9H2WOblgGprz3ha3BzlGZ-sqY0GZuUw,6014
+outcome_engineering-0.1.0.dist-info/RECORD,,

outcome_engineering-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

outcome_engineering-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+oe = outcome_engineering.cli:app
+