Skip to content

tutorial.md

Latest commit

 

History

History
259 lines (167 loc) · 9.2 KB

tutorial.md

File metadata and controls

259 lines (167 loc) · 9.2 KB
Raw

Tutorial: Outcome Engineering with the Spec Tree Methodology

This tutorial walks through the full workflow — from bootstrapping a spec tree in a new or existing product to authoring specs, implementing code, and committing changes.

Prerequisites

# Install the spx CLI
npm install -g @outcomeeng/spx

# Add the marketplace and install plugins
claude plugin marketplace add outcomeeng/plugins
claude plugin install spec-tree@outcomeeng

# Install a language plugin for your product
claude plugin install python@outcomeeng      # or typescript@outcomeeng

1. Bootstrap a spec tree

The /bootstrap command works for both existing projects (where code already exists) and blank projects (starting from scratch). It reads your product's CLAUDE.md and codebase to understand what the product does, then interviews you to fill in the gaps.

Existing product

If you have a product with code but no spec tree, /bootstrap detects the product from your existing files:

> /bootstrap

It reads CLAUDE.md, package.json, README, or whatever describes your product, then asks targeted questions about what's missing.

Bootstrap detects the product from CLAUDE.md

What it asks

The interview gathers three things:

Outcome hypothesis — What change in user behavior do you expect?

Outcome hypothesis question with structured options

Scope — What are the major things this product does? Each becomes a top-level node.

Scope question with progressive options

Shared infrastructure — Do any concerns share dependencies that should be extracted as enablers?

Shared infrastructure question

Confirm the scaffold

Before creating any files, the skill presents the full plan and lets you refine it:

Confirm scaffold with options to refine

Result

The scaffold creates the product spec, a product guide, and top-level node stubs with the correct directory structure and sparse integer ordering:

Scaffold result showing created files

Your spx/ directory now has a product spec, CLAUDE.md guide, and enabler/outcome nodes ready to fill in.

2. Author specs and decisions

Use /author to create any spec-tree artifact. It detects what you want from the argument:

> /author outcome for search          # create an outcome node
> /author PDR for auth policy          # create a product decision
> /author ADR for caching strategy     # create an architecture decision
> /author enabler for test harness     # create a shared enabler

The skill:

  1. Loads the foundation methodology (/understand)
  2. Loads context for the placement location (/contextualize)
  3. Reads the appropriate template
  4. Asks clarifying questions about genuine gaps
  5. Drafts the artifact in atemporal voice
  6. Validates and creates the files

Outcome nodes

Every outcome has a three-part hypothesis:

  • Output — what the software does (tested by assertions)
  • Outcome — measurable change in user behavior
  • Impact — business value

The skill guides you through writing each part and suggests typed assertions (Scenario, Property, Mapping, Conformance, Compliance).

Decision records

ADRs (architecture decisions) and PDRs (product decisions) govern what the product does. They use MUST/NEVER compliance rules verified by audit.

> /author ADR for database choice

The skill asks about the decision, alternatives considered, trade-offs accepted, and compliance rules.

3. Decompose nodes

When a node accumulates too many assertions (>7) or contains independent concerns, break it down:

> /decompose

The skill:

  1. Reads the target node's assertions
  2. Groups them by independent concern
  3. Presents the proposed split for your review
  4. Assigns enabler/outcome types and sparse integer indices
  5. Creates child directories with spec stubs
  6. Redistributes assertions from parent to children

4. Check consistency

Use /align to review specs for contradictions, gaps, or quality issues:

> /align

It checks:

  • Atemporal voice (no temporal language like "currently" or "we need to")
  • Cross-node consistency (no conflicting assertions)
  • Content placement (architecture in ADRs, not in specs)
  • Assertion completeness (every outcome has typed assertions with test links)

5. Write tests

Use /test to write tests driven by spec assertions:

> /test

The skill extracts typed assertions from the spec, determines what test evidence is needed, and generates test scaffolds. It delegates methodology decisions to the 5-stage testing router (what level, what doubles) and language patterns to /test-python or /test-typescript.

6. Implement with TDD

The /apply command starts the full TDD flow — architecture, tests, then code — with review gates at each step:

> /apply spx/21-auth.outcome

This invokes the /apply skill, which orchestrates 8 steps:

  1. Load methodology (/understand)
  2. Load work item context (/contextualize)
  3. Architect — produce ADR via /architect-python or /architect-typescript
  4. Review architecture — loop until APPROVED
  5. Write tests — via /test-python or /test-typescript
  6. Review tests — loop until APPROVED
  7. Implement — via /code-python or /code-typescript
  8. Review code — loop until APPROVED

Without arguments, /apply determines work from conversation context or falls back to spx/EXCLUDE.

7. Commit changes

Use /commit-changes for Conventional Commits with selective staging:

> /commit-changes

The skill:

  1. Runs product validation (just check, pnpm run check, etc.)
  2. Classifies changes by concern (type + scope)
  3. Stages specific files for one concern at a time
  4. Writes a commit message in imperative mood
  5. Repeats for remaining concerns

Multiple concerns = multiple commits. The skill never uses git add ..

8. Hand off and pick up

When you need to continue work in a fresh session:

> /handoff                             # create a timestamped handoff

This saves the current context — what you were working on, what's done, what's next — to .spx/sessions/.

To resume in a new session:

> /pickup                              # list and claim a previous handoff

9. Refactor the tree

When the structure needs to change — moving nodes, re-scoping assertions, extracting shared enablers:

> /refactor

Four operations:

  • Move — relocate a node under a different parent
  • Re-scope — shift assertions between existing siblings
  • Extract enabler — factor shared infrastructure from 2+ siblings into a lower-index enabler
  • Consolidate — merge two nodes that are really the same concern

The skill analyzes impact (broken links, ADR/PDR scope changes), applies changes, and validates consistency afterward.

10. Stop ad hoc work

If you catch yourself writing code without specs, debugging without tests, or skipping the methodology:

> /refocus

This stops the current ad hoc work and restarts the proper TDD flow from Step 1. It's a corrective command — use it when you realize you're off track.

Workflow summary

Step What you do Command/Skill
Setup Install spx CLI, add marketplace, install plugins npm install -g @outcomeeng/spx
Bootstrap Create spec tree for your product /bootstrap
Author Create specs, decisions, nodes /author
Decompose Break down large nodes /decompose
Align Check consistency and quality /align
Test Write tests from spec assertions /test
Implement TDD flow: architect → test → code /apply
Commit Selective staging, Conventional Commits /commit-changes
Hand off Save context for next session /handoff → /pickup
Refactor Restructure the tree /refactor
Correct Stop ad hoc work, restart methodology /refocus