@diottodev/runic 1.0.0 → 1.1.0

package/engineering/skills/chaos-engineering/references/experiment_design.md

@@ -0,0 +1,158 @@
+# Experiment design
+
+A well-designed chaos experiment has 7 sections. Skip any of them and the experiment becomes either useless (no learning) or dangerous (no bounds).
+
+## The 7 sections
+
+```
+1. Hypothesis
+2. Steady-state metric
+3. Attack
+4. Blast radius
+5. Abort criteria
+6. Rollback procedure
+7. Learning question
+```
+
+## 1. Hypothesis
+
+**Format:** *When [fault], [steady-state metric] stays [tolerance].*
+
+Examples:
+- *"When the primary Postgres replica fails, checkout p99 latency stays below 500ms."*
+- *"When 50% of payment-service requests are throttled to 1 RPS, conversion rate drops by less than 5% within 60 seconds of return-to-normal."*
+- *"When us-east-1 is partitioned from us-west-2, Search continues to return results from us-west-2 within 200ms p99."*
+
+A good hypothesis:
+- Names a specific fault (not "things break")
+- Names a specific metric (not "everything")
+- States a specific tolerance (not "good enough")
+- Is measurable and falsifiable
+
+## 2. Steady-state metric
+
+The metric you'll measure before, during, and after the experiment.
+
+Required properties:
+- **Quantitative** — a number, not a feeling
+- **Customer-relevant** — something users feel (latency, error rate, conversion)
+- **Measurable in <60s** — slow metrics give you no time to abort
+- **Stable in normal operation** — you need a baseline
+
+| Good | Bad |
+|---|---|
+| p99 checkout latency | "the system is healthy" |
+| 4xx + 5xx rate | "errors are low" |
+| Successful login rate | CPU usage |
+| Items added to cart per minute | replica count |
+
+## 3. Attack
+
+The fault you're injecting. Must specify:
+
+- **Type** — latency, error, resource, partition, dependency, time, infrastructure
+- **Magnitude** — *how* much (e.g., "+200ms", "10% errors", "100% timeout to peer X")
+- **Duration** — how long the attack runs (typically 5-30 minutes)
+- **Target** — which subset of the system gets the attack
+
+See `attack_taxonomy.md` for the 7 attack types.
+
+## 4. Blast radius
+
+The maximum scope of customer impact. Use `blast_radius_calculator.py` to compute:
+
+- **Affected users** — `traffic_share × user_population`
+- **Error budget consumed** — `duration × traffic_share × availability_delta`
+- **Risk score** — GREEN (<1% budget) / YELLOW (1-10%) / RED (>10%)
+
+Rule of thumb:
+- Start at 1% traffic share
+- Grow only after 3 successful experiments at the previous level
+- Never exceed 10% of monthly error budget in a single experiment
+
+## 5. Abort criteria
+
+The signals that auto-trigger experiment termination. Each must be:
+
+- **Concrete** — specific metric and threshold ("p99 > 1000ms" not "performance degrades")
+- **Detectable in <60s** — latency, error rate, throughput
+- **Wired to action** — manual abort link in the dashboard, automatic via alert webhook
+
+Standard abort criteria:
+
+| Signal | Threshold | Action |
+|---|---|---|
+| p99 latency | > 2× baseline | abort |
+| 5xx rate | > baseline + 1pp | abort |
+| 4xx rate (excl. 401/404) | > baseline + 5pp | abort |
+| Conversion rate | < baseline × 0.95 | abort |
+| Customer ticket spike | > 3× baseline | escalate |
+| On-call paged | any SEV1/SEV2 | abort |
+
+## 6. Rollback procedure
+
+How you'll revert the fault. Required because:
+- Sometimes the chaos tool itself fails to revert
+- Sometimes the fault has lingering effects (caches, connections)
+
+Standard rollback:
+1. Disable fault injection in tool
+2. Verify steady-state recovers within 2 minutes
+3. If not recovering, escalate as incident; restore from backup if needed
+
+## 7. Learning question
+
+What do you expect NOT to learn? Force yourself to predict the outcome.
+
+Examples:
+- *"We expect the cache to absorb the latency. We'll learn whether the timeout configuration on the upstream is correct."*
+- *"We expect failover to take 30s. We'll learn whether retry backoff is configured."*
+
+If you predicted the outcome correctly: confidence increased.
+If you didn't: there's an unknown — file a follow-up.
+
+## Pre-flight checklist
+
+Before running the experiment, verify:
+
+- [ ] Hypothesis written
+- [ ] Steady-state metric measured for ≥5 minutes
+- [ ] Blast radius calculated (GREEN or YELLOW)
+- [ ] Abort criteria documented with thresholds
+- [ ] Rollback procedure tested in staging
+- [ ] On-call team notified in the team channel
+- [ ] Monitoring dashboards open
+- [ ] Owner identified and reachable
+- [ ] Time-box agreed (max experiment duration)
+- [ ] Communication plan if abort triggers
+
+## Time-boxing
+
+| Experiment type | Typical duration | Max recommended |
+|---|---|---|
+| First-time chaos | 5 minutes | 10 minutes |
+| Familiar attack, new target | 15 minutes | 30 minutes |
+| Continuous (automated) | per scheduler | 10 min per attack |
+| Game Day (human-led) | 1-2 hours | 4 hours |
+
+## Escalation
+
+If abort criteria are hit:
+
+1. **Stop the experiment immediately** (the obvious step many teams forget to script)
+2. Verify steady-state recovery
+3. If recovery doesn't happen in 5 min → declare an incident
+4. Open a postmortem doc using `experiment_postmortem.py`
+5. Notify stakeholders (whoever was promised "this won't impact anything")
+6. Capture timeline while memory is fresh
+
+## Anti-patterns
+
+- **Hypothesis written after running** — that's a postmortem, not chaos engineering
+- **Steady-state metric chosen during experiment** — pick before
+- **Magnitude "small"** — quantify; "small" varies by reader
+- **No abort criteria** — never run without them
+- **Single owner of all chaos** — culture problem; spread the practice
+- **Chaos that always succeeds** — increase magnitude; you're not learning if everything passes
+- **Chaos that always fails** — reduce magnitude; you can't learn if everything breaks
+- **Chaos with no follow-up actions** — what was the point?

package/engineering/skills/chaos-engineering/references/tooling_landscape.md

@@ -0,0 +1,197 @@
+# Tooling landscape
+
+Six options. Pick by stack, license preference, and required attack types.
+
+## At-a-glance
+
+| Tool | License | Stack | Attack coverage | Best for |
+|---|---|---|---|---|
+| **Chaos Toolkit** | OSS (Apache 2) | Any (Python) | Broad via plugins | Lightweight, multi-cloud, JSON experiments |
+| **Chaos Mesh** | OSS (Apache 2) | Kubernetes | Very broad (network, pod, IO, time, stress) | k8s-native, rich CRDs |
+| **Litmus** | OSS (Apache 2) | Kubernetes | Very broad (300+ experiments) | k8s, Argo-integrated |
+| **Gremlin** | Commercial | Any (agents) | Broad, polished | Enterprise, audit, multi-cloud |
+| **AWS FIS** | Paid (AWS) | AWS | AWS services + EC2/ECS/EKS | AWS-heavy, IAM-integrated |
+| **Custom** | Your code | Any | What you build | Niche, single-cloud, low budget |
+
+## Decision tree
+
+```
+Stack constraint?
+├── Kubernetes-only ──┬── OSS preferred → Chaos Mesh OR Litmus
+│                     │       (Litmus has the bigger experiment library;
+│                     │        Chaos Mesh has cleaner CRD model)
+│                     └── Enterprise budget → Gremlin
+│
+├── AWS-heavy ────────┬── Simple needs → AWS FIS
+│                     ├── Multi-cloud + AWS → Chaos Toolkit + AWS plugin
+│                     └── Enterprise → Gremlin
+│
+├── Multi-cloud ──────┬── OSS → Chaos Toolkit
+│                     └── Enterprise → Gremlin
+│
+└── No infra constraint
+    └── Just need fault injection → Toxiproxy (a single-purpose tool, not full chaos framework)
+```
+
+## Chaos Toolkit
+
+**What it is:** Python-based framework. You write experiments as JSON or YAML files; the CLI runs them.
+
+**Strengths:**
+- Lightweight; runs anywhere Python runs
+- Plugin ecosystem for AWS, Azure, GCP, Kubernetes, etc.
+- JSON experiments are version-controllable
+- Apache 2 license
+
+**Weaknesses:**
+- No built-in scheduling (you bring cron / CI)
+- Smaller experiment library than Litmus
+- Plugin quality varies
+
+**Example experiment (JSON):**
+```json
+{
+  "title": "Latency on payment-svc",
+  "description": "p99 latency stays <500ms when payment is +200ms slow",
+  "steady-state-hypothesis": {
+    "title": "p99 < 500ms",
+    "probes": [{ "type": "probe", "tolerance": [0, 500],
+                 "provider": { "type": "http", "url": "https://my.dashboards/p99" } }]
+  },
+  "method": [{ "type": "action", "name": "add-latency",
+               "provider": { "type": "process", "path": "tc", "arguments": [...] } }]
+}
+```
+
+## Chaos Mesh
+
+**What it is:** Kubernetes operator + CRDs for chaos. Install in-cluster; `kubectl apply` an experiment.
+
+**Strengths:**
+- True k8s-native (no external orchestrator)
+- Comprehensive coverage: network, pod, IO, stress, time, DNS, HTTP, kernel
+- UI dashboard for running experiments
+- CNCF Incubating project
+
+**Weaknesses:**
+- k8s-only
+- CRD layout is opinionated; some types feel similar but aren't
+- Setup requires cluster admin
+
+**Example experiment (CRD):**
+```yaml
+apiVersion: chaos-mesh.org/v1alpha1
+kind: NetworkChaos
+metadata:
+  name: payment-latency
+spec:
+  action: delay
+  mode: one
+  selector:
+    namespaces: [default]
+    labelSelectors:
+      app: payment-svc
+  delay:
+    latency: 200ms
+  duration: 5m
+```
+
+## Litmus
+
+**What it is:** Kubernetes chaos framework with a large experiment library. Argo-CD integration.
+
+**Strengths:**
+- 300+ pre-built experiments
+- Strong Argo / GitOps integration
+- ChaosHub community library
+- Workflow capability for multi-step experiments
+
+**Weaknesses:**
+- More moving parts than Chaos Mesh
+- Some pre-built experiments are thin wrappers; quality varies
+- k8s-only
+
+## Gremlin
+
+**What it is:** Commercial SaaS. Agents on hosts; central control plane.
+
+**Strengths:**
+- Polished UX
+- Comprehensive attack library
+- Audit logs (compliance)
+- Multi-cloud, multi-OS
+- Customer support
+
+**Weaknesses:**
+- Paid (per-host or per-MAU)
+- Vendor lock-in
+- Less control than OSS
+
+**When to choose:** large enterprise, compliance/audit requirements, dedicated chaos team, budget exists.
+
+## AWS FIS (Fault Injection Simulator)
+
+**What it is:** AWS-managed chaos service. Templates of "actions" (stop instance, throttle API) chained into experiments.
+
+**Strengths:**
+- IAM-integrated (proper auth/audit)
+- Native to AWS services (RDS failover, ECS/EKS, Network Manager)
+- Pay-per-experiment (no agents to maintain)
+
+**Weaknesses:**
+- AWS-only
+- Smaller attack library than Chaos Mesh / Gremlin
+- Multi-account is awkward
+
+**When to choose:** AWS-heavy team that wants chaos without managing the chaos infra.
+
+## Custom (DIY)
+
+**When to choose:**
+- Single-cloud, single-stack, low complexity
+- Budget = $0
+- Have engineering capacity to maintain the tool
+- Need a niche attack type that no tool covers
+
+**Implementation patterns:**
+- Bash scripts that wrap `tc` / iptables / kill / stress-ng
+- Application-level chaos via feature flags + middleware
+- Service mesh fault injection (Istio / Linkerd) — covers many cases without a chaos framework
+
+**Trade-offs:**
+- You build all the safety rails (abort, timeout, blast-radius)
+- You build the scheduler
+- You debug your own bugs
+
+For most teams, this is a starter path; once chaos becomes regular, switch to a real tool.
+
+## Pricing rule of thumb
+
+| Tool | Typical cost (annual) |
+|---|---|
+| Chaos Toolkit | $0 |
+| Chaos Mesh | $0 |
+| Litmus OSS | $0 |
+| Litmus Enterprise | $5-30k |
+| Gremlin | $20-100k+ |
+| AWS FIS | pay-per-action, ~$100-2000/mo for active use |
+| Custom | engineering time only |
+
+## Migration paths
+
+| From | To | Effort |
+|---|---|---|
+| Custom scripts | Chaos Toolkit | Low (wrap scripts as actions) |
+| Chaos Toolkit | Chaos Mesh | Medium (k8s-only; rewrite for CRDs) |
+| Chaos Mesh | Litmus | Medium (similar shape, different CRDs) |
+| Anything | Gremlin | Easy (Gremlin imports many formats) |
+
+## Selection checklist
+
+Before committing:
+- [ ] Stack matches (k8s vs multi-cloud vs AWS-only)
+- [ ] Required attack types covered (cross-reference `attack_taxonomy.md`)
+- [ ] Audit logging requirement met (Gremlin / AWS FIS only have full audit)
+- [ ] Self-hosting requirement met (OSS only)
+- [ ] Budget approved
+- [ ] Run a 30-day proof-of-concept; verify abort path works

package/engineering/skills/chaos-engineering/scripts/blast_radius_calculator.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Compute blast radius and risk score for a chaos experiment.
+
+Inputs: traffic share affected, user population, duration, baseline availability,
+expected impacted availability. Outputs expected affected users, error budget
+consumed, and a GREEN / YELLOW / RED risk score with PROCEED / REDUCE / ABORT
+recommendation.
+"""
+import argparse
+import json
+import sys
+
+
+def calculate(traffic_share, user_pop, duration_min, baseline_avail, impacted_avail, monthly_budget_min):
+    if not 0 <= traffic_share <= 1:
+        raise ValueError("traffic-share must be between 0 and 1")
+    if not 0 < impacted_avail <= 1:
+        raise ValueError("impacted-availability must be between 0 (exclusive) and 1")
+    if not 0 < baseline_avail <= 1:
+        raise ValueError("baseline-availability must be between 0 (exclusive) and 1")
+    affected_users = int(user_pop * traffic_share)
+    delta_avail = max(baseline_avail - impacted_avail, 0.0)
+    error_budget_consumed_min = round(duration_min * traffic_share * delta_avail, 4)
+    pct_of_monthly_budget = round(100 * error_budget_consumed_min / monthly_budget_min, 2) if monthly_budget_min > 0 else 0
+    if pct_of_monthly_budget < 1:
+        risk = "GREEN"
+        recommendation = "PROCEED"
+    elif pct_of_monthly_budget < 10:
+        risk = "YELLOW"
+        recommendation = "PROCEED with explicit owner sign-off; consider reducing traffic share"
+    else:
+        risk = "RED"
+        recommendation = "ABORT or REDUCE — blast radius exceeds 10% of monthly error budget"
+    return {
+        "inputs": {
+            "traffic_share": traffic_share,
+            "user_pop": user_pop,
+            "duration_min": duration_min,
+            "baseline_availability": baseline_avail,
+            "impacted_availability": impacted_avail,
+            "monthly_budget_min": monthly_budget_min,
+        },
+        "expected_affected_users": affected_users,
+        "expected_availability_delta": round(delta_avail, 4),
+        "error_budget_consumed_min": error_budget_consumed_min,
+        "pct_of_monthly_budget": pct_of_monthly_budget,
+        "risk": risk,
+        "recommendation": recommendation,
+    }
+
+
+def render_text(result):
+    print("Blast Radius Calculator")
+    print("=" * 40)
+    i = result["inputs"]
+    print(f"Traffic share affected:   {i['traffic_share'] * 100:.2f}%")
+    print(f"User population:          {i['user_pop']:,}")
+    print(f"Duration:                 {i['duration_min']} min")
+    print(f"Baseline availability:    {i['baseline_availability']}")
+    print(f"Impacted availability:    {i['impacted_availability']}")
+    print(f"Monthly error budget:     {i['monthly_budget_min']} min")
+    print("")
+    print(f"Expected affected users:  {result['expected_affected_users']:,}")
+    print(f"Availability delta:       {result['expected_availability_delta']}")
+    print(f"Error budget consumed:    {result['error_budget_consumed_min']} min ({result['pct_of_monthly_budget']}% of monthly)")
+    print("")
+    print(f"Risk:           {result['risk']}")
+    print(f"Recommendation: {result['recommendation']}")
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--traffic-share", type=float, required=True, help="Fraction (0-1) of traffic affected")
+    ap.add_argument("--user-pop", type=int, required=True, help="Total user population")
+    ap.add_argument("--duration-min", type=int, required=True, help="Experiment duration in minutes")
+    ap.add_argument("--baseline-availability", type=float, default=0.999, help="Baseline availability (default: 0.999)")
+    ap.add_argument("--expected-impact-availability", type=float, default=0.95, dest="impact_avail",
+                    help="Availability under fault (default: 0.95)")
+    ap.add_argument("--monthly-budget-min", type=float, default=43.2,
+                    help="Monthly error budget in minutes (default: 43.2 for 99.9%% on 30 days)")
+    ap.add_argument("--format", choices=["text", "json"], default="text")
+    args = ap.parse_args()
+
+    try:
+        result = calculate(
+            args.traffic_share, args.user_pop, args.duration_min,
+            args.baseline_availability, args.impact_avail, args.monthly_budget_min,
+        )
+    except ValueError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 2
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        render_text(result)
+    return 0 if result["risk"] != "RED" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engineering/skills/chaos-engineering/scripts/experiment_designer.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Generate a structured chaos engineering experiment plan.
+
+Enforces the required sections (hypothesis, steady-state metric, blast radius,
+abort criteria, rollback). Output is markdown by default; JSON available for
+piping into experiment_postmortem.py.
+"""
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+
+ATTACK_DEFAULTS = {
+    "latency": {"magnitude_hint": "+200ms", "tooling_hint": "tc / Chaos Mesh NetworkChaos"},
+    "error": {"magnitude_hint": "10% of requests return 5xx", "tooling_hint": "Toxiproxy / Chaos Mesh HTTPChaos"},
+    "cpu": {"magnitude_hint": "80% sustained", "tooling_hint": "stress-ng / Chaos Mesh StressChaos"},
+    "memory": {"magnitude_hint": "+1GiB pressure", "tooling_hint": "stress-ng / Chaos Mesh StressChaos"},
+    "disk": {"magnitude_hint": "fill /var to 95%", "tooling_hint": "stress-ng / Chaos Mesh IOChaos"},
+    "network-partition": {"magnitude_hint": "drop 100% to peer X", "tooling_hint": "Chaos Mesh NetworkChaos partition"},
+    "dependency-failure": {"magnitude_hint": "100% timeout to dependency", "tooling_hint": "service mesh fault injection"},
+    "time-skew": {"magnitude_hint": "+5 minutes", "tooling_hint": "libfaketime / Chaos Mesh TimeChaos"},
+    "kill-instance": {"magnitude_hint": "1 of N instances", "tooling_hint": "AWS FIS / Chaos Monkey"},
+}
+
+
+def build_plan(args):
+    attack_meta = ATTACK_DEFAULTS.get(args.attack, {})
+    magnitude = args.magnitude or attack_meta.get("magnitude_hint", "<set magnitude>")
+    tooling = args.tooling or attack_meta.get("tooling_hint", "<set tooling>")
+    plan = {
+        "experiment_id": f"chaos-{args.target}-{args.attack}-{int(datetime.now(timezone.utc).timestamp())}",
+        "created": datetime.now(timezone.utc).isoformat(),
+        "target": args.target,
+        "hypothesis": args.hypothesis,
+        "steady_state": {
+            "metric": args.steady_metric or "<must define before experiment>",
+            "baseline_window": "5 minutes pre-experiment",
+            "tolerance": args.tolerance or "within ±5% of baseline",
+        },
+        "attack": {
+            "type": args.attack,
+            "magnitude": magnitude,
+            "duration_min": args.duration_min,
+            "tooling": tooling,
+        },
+        "blast_radius": {
+            "scope": args.blast_radius or "<must define before experiment>",
+            "rollback_immediately_if": args.abort_if or "<must define abort criteria>",
+        },
+        "abort_criteria": _parse_abort_criteria(args.abort_if),
+        "rollback_procedure": args.rollback or "Disable fault injection; verify steady state recovers within 2 minutes.",
+        "monitoring_dashboard": args.dashboard or "<paste dashboard URL>",
+        "owner": args.owner or "<assign owner>",
+        "on_call_acknowledged": False,
+        "learning_question": args.learning or "What did we learn that we did not know before?",
+    }
+    return plan
+
+
+def _parse_abort_criteria(raw):
+    if not raw:
+        return []
+    parts = [p.strip() for p in raw.split(" OR ")]
+    return [{"signal": p, "action": "abort"} for p in parts if p]
+
+
+def render_markdown(plan):
+    lines = []
+    lines.append(f"# Chaos Experiment: {plan['experiment_id']}")
+    lines.append("")
+    lines.append(f"- **Target:** `{plan['target']}`")
+    lines.append(f"- **Created:** {plan['created']}")
+    lines.append(f"- **Owner:** {plan['owner']}")
+    lines.append("")
+    lines.append("## Hypothesis")
+    lines.append(f"> {plan['hypothesis']}")
+    lines.append("")
+    lines.append("## Steady-state metric")
+    lines.append(f"- **Metric:** {plan['steady_state']['metric']}")
+    lines.append(f"- **Baseline window:** {plan['steady_state']['baseline_window']}")
+    lines.append(f"- **Tolerance:** {plan['steady_state']['tolerance']}")
+    lines.append("")
+    lines.append("## Attack")
+    a = plan["attack"]
+    lines.append(f"- **Type:** {a['type']}")
+    lines.append(f"- **Magnitude:** {a['magnitude']}")
+    lines.append(f"- **Duration:** {a['duration_min']} minutes")
+    lines.append(f"- **Tooling:** {a['tooling']}")
+    lines.append("")
+    lines.append("## Blast radius")
+    lines.append(f"- **Scope:** {plan['blast_radius']['scope']}")
+    lines.append("")
+    lines.append("## Abort criteria")
+    if plan["abort_criteria"]:
+        for c in plan["abort_criteria"]:
+            lines.append(f"- {c['signal']}")
+    else:
+        lines.append("- **WARNING: no abort criteria defined — DO NOT RUN**")
+    lines.append("")
+    lines.append("## Rollback procedure")
+    lines.append(plan["rollback_procedure"])
+    lines.append("")
+    lines.append("## Monitoring")
+    lines.append(f"- Dashboard: {plan['monitoring_dashboard']}")
+    lines.append("")
+    lines.append("## Learning question")
+    lines.append(f"> {plan['learning_question']}")
+    return "\n".join(lines)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--target", required=True, help="Target system or service")
+    ap.add_argument("--hypothesis", required=True, help='Hypothesis: "When X, metric Y stays Z"')
+    ap.add_argument("--attack", required=True, choices=list(ATTACK_DEFAULTS.keys()))
+    ap.add_argument("--magnitude", help="Attack magnitude (default: per-attack hint)")
+    ap.add_argument("--duration-min", type=int, default=15)
+    ap.add_argument("--steady-metric", help="Steady-state metric name (e.g., 'p99 latency')")
+    ap.add_argument("--tolerance", help="Tolerance vs baseline (e.g., 'within ±5%%')")
+    ap.add_argument("--blast-radius", help="Blast radius (e.g., '5%% of US traffic')")
+    ap.add_argument("--abort-if", dest="abort_if", help='Abort criteria, OR-separated (e.g., "p99 > 1000ms OR error_rate > +1pp")')
+    ap.add_argument("--rollback", help="Rollback procedure")
+    ap.add_argument("--tooling", help="Chaos tool to use (default: per-attack hint)")
+    ap.add_argument("--dashboard", help="Monitoring dashboard URL")
+    ap.add_argument("--owner", help="Experiment owner")
+    ap.add_argument("--learning", help="Learning question")
+    ap.add_argument("--format", choices=["markdown", "json"], default="markdown")
+    args = ap.parse_args()
+
+    plan = build_plan(args)
+    if args.format == "json":
+        print(json.dumps(plan, indent=2))
+    else:
+        print(render_markdown(plan))
+    return 0 if plan["abort_criteria"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())